"Fossies" - the Fresh Open Source Software Archive

Member "xorriso-1.5.4/libjte/libjte.h" (30 Jan 2021, 23734 Bytes) of package /linux/misc/xorriso-1.5.4.pl02.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "libjte.h" see the Fossies "Dox" file reference documentation and the last Fossies "Diffs" side-by-side code changes report: 1.5.2_vs_1.5.4.

    1 /*
    2  * libjte.h
    3  *
    4  * Copyright (c) 2010 Thomas Schmitt <scdbackup@gmx.net>
    5  *
    6  * API definition of libjte, to be included as <libjte/libjte.h>
    7  *
    8  * GNU LGPL v2.1 (including option for GPL v2 or later)
    9  *
   10  */
   11 
   12 #ifndef LIBJTE_H_INCLUDED 
   13 #define LIBJTE_H_INCLUDED 1
   14 
   15 #include <sys/types.h>
   16 
   17 /* The common environment handle */
   18 
   19 struct libjte_env;
   20 
   21 
   22 /* --------------------------- Version Inquiry --------------------------- */
   23 
   24 /** These three release version numbers tell the revision of this header file
   25     and of the API which it describes. They shall be memorized by applications
   26     at build time.
   27     @since 0.1.0
   28 */
   29 #define LIBJTE_VERSION_MAJOR   2
   30 #define LIBJTE_VERSION_MINOR   0
   31 #define LIBJTE_VERSION_MICRO   0
   32 
   33 /** Obtain the three release version numbers of the library. These are the
   34     numbers encountered by the application when linking with libjte
   35     i.e. possibly not before run time.
   36     Better do not base the fundamental compatibility decision of an application
   37     on these numbers. For a reliable check use libjte__is_compatible().
   38     @since 0.1.0
   39     @param major The maturity version (0 for now, as we are still learning)
   40     @param minor The development goal version.
   41     @param micro The development step version.
   42 */
   43 void libjte__version(int *major, int *minor, int *micro);
   44 
   45 /** Check whether all features of header file libjte.h from the given
   46     major.minor.micro revision triple can be delivered by the library version
   47     which is performing this call.
   48         if (! libjte__is_compatible(LIBJTE_VERSION_MAJOR, LIBJTE_VERSION_MINOR,
   49                                     LIBJTE_VERSION_MICRO, 0))
   50            ...refuse to start the program with this dynamic library version...
   51     @since 0.1.0
   52     @param major obtained at build time
   53     @param minor obtained at build time
   54     @param micro obtained at build time
   55     @param flag Bitfield for control purposes. Unused yet. Submit 0.
   56     @return 1= library can work for caller
   57             0= library is not usable in some aspects. Caller must restrict
   58                itself to an earlier API version or must not use this library
   59                at all.
   60 */
   61 int libjte__is_compatible(int major, int minor, int micro, int flag);
   62 
   63 
   64 /* ------------------------------- Life Cycle ----------------------------- */
   65 
   66 /** Create a libjte environment object. It is to be used with most of the
   67     calls of this API for storing parameters and for memorizing the state
   68     of its libjte operations.
   69     @since 0.1.0
   70     @param jte_handle  Returns an opaque handle to the allocated environment
   71     @param flag        Bitfield for control purposes. Unused yet. Submit 0.
   72     @return  >0 means success, <=0 indicates failure 
   73 */
   74 int libjte_new(struct libjte_env **jte_handle, int flag);
   75 
   76 
   77 /** Dispose a libjte environment and free the system facilities which it uses.
   78     @since 0.1.0
   79     @param jte_handle  The environment to be disposed.
   80                        *jte_handle will be set to NULL
   81     @return  >0 means success, <=0 indicates failure
   82 */
   83 int libjte_destroy(struct libjte_env **jte_handle);
   84 
   85 
   86 /* ----------------------------- Parameter Setup ------------------------- */
   87 
   88 /** Tell libjte the name that will become value of "Filename=" in the "[Image]"
   89     section of the jigdo file.
   90     @since 0.1.0
   91     @param jte_handle  The environment to be manipulated.
   92     @param outfile     The value
   93     @return  >0 means success, <=0 indicates failure
   94 */
   95 int libjte_set_outfile(struct libjte_env *jte_handle, char *outfile);
   96 
   97 /** Enable or disable debugging verbosity.
   98     @since 0.1.0
   99     @param jte_handle  The environment to be manipulated.
  100     @param verbose     If not 0 : cause verbosity
  101     @return  >0 means success, <=0 indicates failure
  102 */
  103 int libjte_set_verbose(struct libjte_env *jte_handle, int verbose);
  104 
  105 /** Choose the checksum algorithm that libjte will use in its checksum
  106     calculations and expectations. Supported algorithms are "md5" and
  107     "sha256". If this function is *not* called explicitly, libjte will
  108     default to "md5" for backwards compatibility with older versions
  109     of the library that only supported md5.
  110     Choice of the checksum algorithm here is important elsewhere in
  111     terms of sizes of buffers, formats of input, etc.:
  112     - libjte_set_md5_path()
  113     - libjte_set_checksum_path()
  114     - libjte_decide_file_jigdo{,2}()
  115     - libjte_write_match_record{,2}()
  116     It also affects the compatibility of the jigdo and template files
  117     created. Choosing "md5" will modify the format of the template
  118     file, and declare the "Version" in the [Jigdo] field to be
  119     1.2. Choosing "sha256" will declare the "Version" in the [Jigdo]
  120     field to be 2.0 and the output will *NOT* work with older jigdo
  121     client tools.
  122     @since 2.0.0
  123     @param jte_handle  The environment to be manipulated.
  124     @param algorithm   If not 0 : cause verbosity
  125     @param size        Pointer to storage; if no errors, will be filled
  126                        with the size in bytes of the checksum output for
  127                future function calls to use
  128     @return  >0 means success, <=0 indicates failure
  129 */
  130 int libjte_set_checksum_algorithm(struct libjte_env *jte_handle,
  131                   char *algorithm, int *size);
  132 
  133 /** Define the file address on hard disk for the template file.
  134     @since 0.1.0
  135     @param jte_handle  The environment to be manipulated.
  136     @param path        Will be used with fopen(path, "w")
  137     @return  >0 means success, <=0 indicates failure
  138 */
  139 int libjte_set_template_path(struct libjte_env *jte_handle, char *path);
  140 
  141 /** Define the file address on hard disk for the jigdo file.
  142     @since 0.1.0
  143     @param jte_handle  The environment to be manipulated.
  144     @param path        Will be used with fopen(path, "w")
  145     @return  >0 means success, <=0 indicates failure
  146 */
  147 int libjte_set_jigdo_path(struct libjte_env *jte_handle, char *path);
  148 
  149 /** Tell libjte the hard disk address of the .md5 file, which lists the
  150     data files which might get extracted and referred in the jigdo file.
  151     Still supported in 2.0.0, but is now just an alias for
  152     libjte_set_checksums_path(handle, path) below
  153     \deprecated since 2.0.0
  154     @since 0.1.0
  155     @param jte_handle  The environment to be manipulated.
  156     @param path        Will be used with fopen(path, "r")
  157     @return  >0 means success, <=0 indicates failure
  158 */
  159 int libjte_set_md5_path(struct libjte_env *jte_handle, char *path);
  160 
  161 /** Tell libjte the hard disk address of the .checksum file, which
  162     lists the data files which might get extracted and referred in the
  163     jigdo file.
  164     @since 2.0.0
  165     @param jte_handle  The environment to be manipulated.
  166     @param path        Will be used with fopen(path, "r")
  167     @return  >0 means success, <=0 indicates failure
  168 */
  169 int libjte_set_checksum_path(struct libjte_env *jte_handle, char *path);
  170 
  171 /** Define a minimum size for data files to get extracted and referred in
  172     the jigdo file.
  173     @since 0.1.0
  174     @param jte_handle  The environment to be manipulated.
  175     @param min_size    Lower size limit in bytes
  176     @return  >0 means success, <=0 indicates failure
  177 */
  178 int libjte_set_min_size(struct libjte_env *jte_handle, int min_size);
  179 
  180 /** Choose one or more checksum algorithms to be applied to the emerging
  181     payload image. The resulting sums will be written into the jigdo file
  182     as lines "# Image Hex ...".
  183     Supported algorithms are "md5", "sha1", "sha256", "sha512" which may be
  184     combined in a comma separated list like "md5,sha1,sha512".
  185     Checksum_code "all" chooses all available algorithms.
  186     @since 0.1.0
  187     @param jte_handle     The environment to be manipulated.
  188     @param  checksum_code Comma separated list string or "all".
  189     @return  >0 means success, <=0 indicates failure
  190 */
  191 int libjte_set_checksum_iso(struct libjte_env *jte_handle,
  192                             char *checksum_code);
  193 
  194 /** Choose one or more checksum algorithms to be applied to the emerging
  195     template file. The resulting sums will be written into the jigdo file
  196     as lines "# Template Hex ...".
  197     Supported algorithms are "md5", "sha1", "sha256", "sha512" which may be
  198     combined in a comma separated list like "md5,sha1,sha512".
  199     Checksum_code "all" chooses all available algorithms.
  200     @since 0.1.0
  201     @param jte_handle     The environment to be manipulated.
  202     @param  checksum_code Comma separated list string or "all".
  203     @return  >0 means success, <=0 indicates failure
  204 */
  205 int libjte_set_checksum_template(struct libjte_env *jte_handle,
  206                                  char *checksum_code);
  207 
  208 /** Choose a compression algorithm for the template file.
  209     @since 0.1.0
  210     @param jte_handle        The environment to be manipulated.
  211     @param compression_code  Either "gzip" or "bzip2".
  212     @return  >0 means success, <=0 indicates failure
  213 */
  214 int libjte_set_compression(struct libjte_env *jte_handle,
  215                            char *compression_code);
  216 
  217 /** Add a regular expression pattern to the list of excluded filenames.
  218     The pattern will be tested against the filenames that are handed to
  219     libjte_decide_file_jigdo() or libjte_begin_data_file().
  220     @since 0.1.0
  221     @param jte_handle  The environment to be manipulated.
  222     @param             String for regcomp(3)
  223     @return  >0 means success, <=0 indicates failure
  224 */
  225 int libjte_add_exclude(struct libjte_env *jte_handle, char *pattern);
  226 
  227 /** Add a regular expression pattern to the list of files which must be
  228     found matching in the .md5 file.
  229     The pattern will be tested against the filenames that are handed to
  230     libjte_decide_file_jigdo() or libjte_begin_data_file() and do not find
  231     a matching entry in the .md5 file. If it matches, then said two functions
  232     will return error resp. perform exit() if this is enabled by 
  233     libjte_set_error_behavior().
  234     Still supported in 2.0.0, but is now just an alias for
  235     libjte_add_checksum_demand(handle, path) below
  236     \deprecated since 2.0.0
  237     @since 0.1.0
  238     @param jte_handle  The environment to be manipulated.
  239     @param             String for regcomp(3)
  240     @return  >0 means success, <=0 indicates failure
  241 */
  242 int libjte_add_md5_demand(struct libjte_env *jte_handle, char *pattern);
  243 
  244 /** Add a regular expression pattern to the list of files which must be
  245     found matching in the .checksum file.
  246     The pattern will be tested against the filenames that are handed
  247     to libjte_decide_file_jigdo() or libjte_begin_data_file() and do
  248     not find a matching entry in the .checksum file. If it matches,
  249     then said two functions will return error resp. perform exit() if
  250     this is enabled by libjte_set_error_behavior().
  251     @since 2.0.0
  252     @param jte_handle  The environment to be manipulated.
  253     @param             String for regcomp(3)
  254     @return  >0 means success, <=0 indicates failure
  255 */
  256 int libjte_add_checksum_demand(struct libjte_env *jte_handle, char *pattern);
  257 
  258 /** Add a To=From pair to the list of mirror name mapping.
  259     The pair will be split at the '=' character. The mirror_name submitted to
  260     libjte_write_match_record() will be tested whether it begins by the From
  261     string. If so, then this string will be replaced by the To string and           a ':' character.
  262     The resulting string will be used as data file name in the jigdo file.
  263 
  264     libjte_decide_file_jigdo() gets the mirror_name from the matching line
  265     in the .checksum file and hands it to the application.
  266     libjte_begin_data_file() obtains the mirror name and processes it without
  267     bothering the application.
  268 
  269     @since 0.1.0
  270     @param jte_handle  The environment to be manipulated.
  271     @param arg         String of the form To=From
  272     @return  >0 means success, <=0 indicates failure
  273 */
  274 int libjte_add_mapping(struct libjte_env *jte_handle, char *arg);
  275 
  276 
  277 /* ----------------------------- Operation --------------------------------- */
  278 
  279 /** Start the production of jigdo and template file.
  280     This is to be done after all parameters are set and before any payload
  281     data are produced by the application.
  282     @since 0.1.0
  283     @param jte_handle  The environment to be started.
  284     @return >0 = ok
  285              0 = error
  286             -1 = would have called exit(1) if enabled
  287 */
  288 int libjte_write_header(struct libjte_env *jte_handle);
  289 
  290 
  291 /** Finish the production of jigdo and template file.
  292     This is to be done after all payload has been produced by the application
  293     and processed by libjte, and before the libjte environment gets disposed.
  294     @since 0.1.0
  295     @param jte_handle  The environment to be finished.
  296     @return >0 = ok
  297              0 = error
  298             -1 = would have called exit(1) if enabled
  299 */
  300 int libjte_write_footer(struct libjte_env *jte_handle);
  301 
  302 
  303 /* ---------------------------  Data File APIs ---------------------------- */
  304 
  305 /* There are two alternative ways how to process a single data file and its
  306    content: Traditional and Simplified.
  307    Choose either one.
  308 
  309    CAUTION: Do not mix them !
  310 
  311 */
  312 
  313 /* ---------------------- Traditional Data File API ----------------------- */
  314 
  315 /* This implements the way how genisoimage deals with single data files when
  316    showing them to its built-in JTE.
  317 
  318    When processing of a data file begins :
  319 
  320      if (libjte_decide_file_jigdo(..., &mirror_name, md5) == 1) {
  321          libjte_write_match_record(..., mirror_name, ..., md5);
  322          write_unmatched_data = 0;
  323      } else
  324          write_unmatched_data = 1;
  325 
  326    When a chunk of data content is written to the payload image :
  327 
  328      if (write_unmatched_data)
  329         libjte_write_unmatched(...);
  330 
  331    Before calling libjte_write_footer() :
  332 
  333      libjte_set_image_size(...);
  334 
  335 */
  336 
  337 /** Decide whether a data file shall be extracted, i.e. referred in the
  338     template file and listed in the jigdo file, or whether its content
  339     shall be written compressed into the template file.
  340     \deprecated since 2.0.0, use libjte_decide_file_jigdo2() in preference.
  341     @since 0.1.0
  342     @param jte_handle  The environment to be used.
  343     @param filename    The address to be used with fopen(filename, "r")
  344     @param size        Number of bytes in the data file
  345     @param mirror_name Returns the name which shall be listed in the jigdo
  346                        file. This is NULL or allocated memory that has to
  347                        be disposed by free(3).
  348     @param md5         May get filled by MD5 for libjte_write_match_record().
  349     @return  0= use libjte_write_unmatched(),
  350              1= use libjte_write_match_record()
  351             -1= would have called exit(1) if enabled, e.g. if called
  352                 after saying "sha256" in
  353                 libjte_set_checksum_algorithm().
  354 */
  355 int libjte_decide_file_jigdo(struct libjte_env *jte_handle,
  356                              char *filename, off_t size, char **mirror_name,
  357                              unsigned char md5[16]);
  358 
  359 /** Decide whether a data file shall be extracted, i.e. referred in the
  360     template file and listed in the jigdo file, or whether its content
  361     shall be written compressed into the template file.
  362     @since 2.0.0
  363     @param jte_handle  The environment to be used.
  364     @param filename    The address to be used with fopen(filename, "r")
  365     @param size        Number of bytes in the data file
  366     @param mirror_name Returns the name which shall be listed in the jigdo
  367                        file. This is NULL or allocated memory that has to
  368                        be disposed by free(3).
  369     @param checksum    May get filled by a checksum for libjte_write_match_record2().
  370                        The size of the needed buffer here varies
  371                        depending on the checksum chosen in
  372                        libjte_set_checksum_algorithm() and is passed
  373                        back by that function.
  374     @return  0= use libjte_write_unmatched(),
  375              1= use libjte_write_match_record()
  376             -1= would have called exit(1) if enabled
  377 */
  378 int libjte_decide_file_jigdo2(struct libjte_env *jte_handle,
  379                   char *filename, off_t size, char **mirror_name,
  380                   unsigned char *checksum);
  381 
  382 /** Register a list entry in the jigdo file and write a reference tag into
  383     the template file. This is to be called if libjte_decide_file_jigdo()
  384     returned 1.
  385     \deprecated since 2.0.0, use libjte_write_match_record2() in preference.
  386     @since 0.1.0
  387     @param jte_handle  The environment to be used.
  388     @param filename    The address to be used with fopen(filename, "r").
  389     @param mirror_name The mirror_name returned by libjte_decide_file_jigdo().
  390     @param sector_size An eventual byte address alignment which is achieved
  391                        in the payload image by padding file ends with zeros.
  392                        Submit 1 if no alignment is done. For ISO images: 2048.
  393     @param size        The number of bytes in the data file.
  394     @param md5         The md5 buffer submitted to libjte_decide_file_jigdo().
  395     @return >0 = ok
  396              0 = error
  397             -1 = would have called exit(1) if enabled, e.g. if called
  398                  after saying "sha256" in
  399                  libjte_set_checksum_algorithm().
  400 */
  401 int libjte_write_match_record(struct libjte_env *jte_handle,
  402                   char *filename, char *mirror_name, int sector_size,
  403                   off_t size, unsigned char md5[16]);
  404 
  405 /** Register a list entry in the jigdo file and write a reference tag into
  406     the template file. This is to be called if libjte_decide_file_jigdo()
  407     returned 1.
  408     @since 2.0.0
  409     @param jte_handle  The environment to be used.
  410     @param filename    The address to be used with fopen(filename, "r").
  411     @param mirror_name The mirror_name returned by libjte_decide_file_jigdo().
  412     @param sector_size An eventual byte address alignment which is achieved
  413                        in the payload image by padding file ends with zeros.
  414                        Submit 1 if no alignment is done. For ISO images: 2048.
  415     @param size        The number of bytes in the data file.
  416     @param checksum    The checksum buffer submitted to libjte_decide_file_jigdo2().
  417     @return >0 = ok
  418              0 = error
  419             -1 = would have called exit(1) if enabled
  420 */
  421 int libjte_write_match_record2(struct libjte_env *jte_handle,
  422                    char *filename, char *mirror_name, int sector_size,
  423                    off_t size, unsigned char *checksum);
  424 
  425 /** Write a payload data chunk into the template file. This is to be called
  426     with any data file bytes if libjte_decide_file_jigdo{,2}() returned 0.
  427     It is also to be called with any payload image bytes which are not content
  428     of a data file.
  429     @since 0.1.0
  430     @param jte_handle  The environment to be used.
  431     @param buffer      The memory buffer containing the payload bytes
  432     @param size        The block size within buffer. (1 is well ok.)
  433     @param count       The number of blocks of the given size within buffer.
  434     @return  >0 means success, <=0 indicates failure
  435 */
  436 /* @return >0 = ok
  437             0 = error
  438            -1 = would have called exit(1) if enabled
  439 */
  440 int libjte_write_unmatched(struct libjte_env *jte_handle, void *buffer,
  441                int size, int count);
  442 
  443 /** Before calling libjte_footer() submit the number of written payload bytes.
  444     The Traditional Data File API does not keep track of this count. 
  445     @since 0.1.0
  446     @param jte_handle  The environment to be used.
  447     @param image_size  Number of bytes in the image.
  448     @return  >0 means success, <=0 indicates failure
  449 */
  450 int libjte_set_image_size(struct libjte_env *o, off_t image_size);
  451             
  452 
  453 /* ------------------------- Simplified Data File API ---------------------- */
  454 
  455 /* This implements the way how libisofs deals with single data files when
  456    showing them to libjte. It does not demand from the application to memorize
  457    the state of libjte decisions and parameters.
  458    It rather shows any payload data to libjte and only marks the begin and
  459    end of data file content.
  460 
  461    When a chunk of bytes is written to the payload image :
  462 
  463      libjte_show_data_chunk();
  464 
  465    When processing of a data file begins :
  466 
  467      libjte_begin_data_file();
  468 
  469    When the content of a data file has been shown completely :
  470 
  471      libjte_end_data_file();
  472 */
  473 
  474 /** Show a chunk of payload data to libjte which will decide whether to write
  475     it into the template file or whether to ignore it, because it belongs to
  476     a Jigdo extracted file.
  477     @since 0.1.0
  478     @param jte_handle  The environment to be used.
  479     @param buffer      The memory buffer containing the payload bytes
  480     @param size        The block size within buffer. (1 is well ok.)
  481     @param count       The number of blocks of the given size within buffer.
  482     @return  >0 means success, <=0 indicates failure
  483 */
  484 int libjte_show_data_chunk(struct libjte_env *jte_handle,
  485                            void *buffer, int size, int count);
  486 
  487 /** Tell libjte that the content of a data file is to be processed next.
  488     libjte will decide whether to extract the file and list it in the jigdo
  489     file, or whether to direct subsequent calls of libjte_show_data_chunk()
  490     into the template file.
  491     @param jte_handle  The environment to be used.
  492     @param filename    The address to be used with fopen(filename, "r").
  493     @param sector_size An eventual byte address alignment which is achieved
  494                        in the payload image by padding file ends with zeros.
  495                        Submit 1 if no alignment is done. For ISO images: 2048.
  496     @param size        The number of bytes in the data file.
  497     @return >0 = ok
  498              0 = error
  499             -1 = would have called exit(1) if enabled
  500                  E.g. because a libjte_add_md5_demand() pattern matched
  501                  a file that shall not get extracted.
  502 */
  503 int libjte_begin_data_file(struct libjte_env *jte_handle, char *filename,
  504                            int sector_size, off_t size);
  505 
  506 /** Tell libjte that all content of the previously announced data file has
  507     been submitted to libjte_show_data_chunk().
  508     libjte will direct the following calls of libjte_show_data_chunk() into
  509     the template file.
  510     @since 0.1.0
  511     @param jte_handle  The environment to be used.
  512     @return  >0 means success, <=0 indicates failure
  513 */
  514 int libjte_end_data_file(struct libjte_env *jte_handle);
  515 
  516 
  517 /* ----------------- Message Reporting and Error Behavior ----------------- */
  518 
  519 /** Define how libjte shall deliver its messages and whether it is allowed
  520     to call exit() in hopeless situations. 
  521     @since 0.1.0
  522     @param jte_handle  The environment to be manipulated.
  523     @param to_stderr   If 0, append messages to the message list of the libjte
  524                        environment.
  525                        If 1 print messages directly to stderr. This is the
  526                        default.
  527     @param with_exit   If 1 perform exit(1); when encountering severe errors.
  528                        If 0 return -1 in such situations. This is the default.
  529     @return  >0 means success, <=0 indicates failure
  530 */
  531 int libjte_set_error_behavior(struct libjte_env *o, 
  532                               int to_stderr, int with_exit);
  533 
  534 /** Get the oldest pending message from the message list. 
  535     @since 0.1.0
  536     @param jte_handle  The environment to be manipulated.
  537     @return Pointer to alloceted memory. Apply free() when no longer needed.
  538             NULL means that no more message is available 
  539 */
  540 char *libjte_get_next_message(struct libjte_env *o);
  541 
  542 /** Dispose all pending messages after eventually printing them to stderr.
  543     @since 0.1.0
  544     @param jte_handle  The environment to be manipulated.
  545     @param flag bit0= print pending messages to stderr
  546                 bit1= eventually complain before printing messages
  547     @return  >0 means success, <=0 indicates failure
  548 */
  549 int libjte_clear_msg_list(struct libjte_env *o, int flag);
  550 
  551 #endif /* LIBJTE_H_INCLUDED */
  552