diff options
Diffstat (limited to 'rbutil/rbutilqt/mspack/mspack.h')
| -rw-r--r-- | rbutil/rbutilqt/mspack/mspack.h | 316 |
1 files changed, 249 insertions, 67 deletions
diff --git a/rbutil/rbutilqt/mspack/mspack.h b/rbutil/rbutilqt/mspack/mspack.h index 7f6bdf1465..3e99624463 100644 --- a/rbutil/rbutilqt/mspack/mspack.h +++ b/rbutil/rbutilqt/mspack/mspack.h @@ -1,5 +1,5 @@ /* libmspack -- a library for working with Microsoft compression formats. - * (C) 2003-2011 Stuart Caie <kyzer@4u.net> + * (C) 2003-2019 Stuart Caie <kyzer@cabextract.org.uk> * * libmspack is free software; you can redistribute it and/or modify it under * the terms of the GNU Lesser General Public License (LGPL) version 2.1 @@ -30,6 +30,7 @@ * - .CAB (MS Cabinet) files, which use deflate, LZX or Quantum compression * - .CHM (HTML Help) files, which use LZX compression * - .LIT (MS EBook) files, which use LZX compression and DES encryption + * - .LZX (Exchange Offline Addressbook) files, which use LZX compression * * To determine the capabilities of the library, and the binary * compatibility version of any particular compressor or decompressor, use @@ -60,6 +61,7 @@ * - mspack_create_hlp_compressor() creates a mshlp_compressor * - mspack_create_szdd_compressor() creates a msszdd_compressor * - mspack_create_kwaj_compressor() creates a mskwaj_compressor + * - mspack_create_oab_compressor() creates a msoab_compressor * * For decompression: * - mspack_create_cab_decompressor() creates a mscab_decompressor @@ -68,6 +70,7 @@ * - mspack_create_hlp_decompressor() creates a mshlp_decompressor * - mspack_create_szdd_decompressor() creates a msszdd_decompressor * - mspack_create_kwaj_decompressor() creates a mskwaj_decompressor + * - mspack_create_oab_decompressor() creates a msoab_decompressor * * Once finished working with a format, each kind of * compressor/decompressor has its own specific destructor: @@ -83,6 +86,8 @@ * - mspack_destroy_szdd_decompressor() * - mspack_destroy_kwaj_compressor() * - mspack_destroy_kwaj_decompressor() + * - mspack_destroy_oab_compressor() + * - mspack_destroy_oab_decompressor() * * Destroying a compressor or decompressor does not destroy any objects, * structures or handles that have been created using that compressor or @@ -208,6 +213,8 @@ extern int mspack_sys_selftest_internal(int); * - #MSPACK_VER_MSSZDDC: the msszdd_compressor interface * - #MSPACK_VER_MSKWAJD: the mskwaj_decompressor interface * - #MSPACK_VER_MSKWAJC: the mskwaj_compressor interface + * - #MSPACK_VER_MSOABD: the msoab_decompressor interface + * - #MSPACK_VER_MSOABC: the msoab_compressor interface * * The result of the function should be interpreted as follows: * - -1: this interface is completely unknown to the library @@ -249,6 +256,10 @@ extern int mspack_version(int entity); #define MSPACK_VER_MSKWAJD (12) /** Pass to mspack_version() to get the mskwaj_compressor version */ #define MSPACK_VER_MSKWAJC (13) +/** Pass to mspack_version() to get the msoab_decompressor version */ +#define MSPACK_VER_MSOABD (14) +/** Pass to mspack_version() to get the msoab_compressor version */ +#define MSPACK_VER_MSOABC (15) /* --- file I/O abstraction ------------------------------------------------ */ @@ -297,8 +308,8 @@ struct mspack_system { * @see close(), read(), write(), seek(), tell(), message() */ struct mspack_file * (*open)(struct mspack_system *self, - const char *filename, - int mode); + const char *filename, + int mode); /** * Closes a previously opened file. If any memory was allocated for this @@ -317,12 +328,14 @@ struct mspack_system { * @param bytes the number of bytes to read from the file. * @return the number of bytes successfully read (this can be less than * the number requested), zero to mark the end of file, or less - * than zero to indicate an error. + * than zero to indicate an error. The library does not "retry" + * reads and assumes short reads are due to EOF, so you should + * avoid returning short reads because of transient errors. * @see open(), write() */ int (*read)(struct mspack_file *file, - void *buffer, - int bytes); + void *buffer, + int bytes); /** * Writes a given number of bytes to an open file. @@ -338,8 +351,8 @@ struct mspack_system { * @see open(), read() */ int (*write)(struct mspack_file *file, - void *buffer, - int bytes); + void *buffer, + int bytes); /** * Seeks to a specific file offset within an open file. @@ -365,8 +378,8 @@ struct mspack_system { * @see open(), tell() */ int (*seek)(struct mspack_file *file, - off_t offset, - int mode); + off_t offset, + int mode); /** * Returns the current file position (in bytes) of the given file. @@ -392,8 +405,8 @@ struct mspack_system { * @see open() */ void (*message)(struct mspack_file *file, - const char *format, - ...); + const char *format, + ...); /** * Allocates memory. @@ -406,12 +419,12 @@ struct mspack_system { * @see free() */ void * (*alloc)(struct mspack_system *self, - size_t bytes); + size_t bytes); /** * Frees memory. * - * @param ptr the memory to be freed. + * @param ptr the memory to be freed. NULL is accepted and ignored. * @see alloc() */ void (*free)(void *ptr); @@ -429,8 +442,8 @@ struct mspack_system { * @param bytes the size of the memory region, in bytes */ void (*copy)(void *src, - void *dest, - size_t bytes); + void *dest, + size_t bytes); /** * A null pointer to mark the end of mspack_system. It must equal NULL. @@ -645,6 +658,31 @@ extern void mspack_destroy_kwaj_compressor(struct mskwaj_compressor *self); extern void mspack_destroy_kwaj_decompressor(struct mskwaj_decompressor *self); +/** Creates a new OAB compressor. + * @param sys a custom mspack_system structure, or NULL to use the default + * @return a #msoab_compressor or NULL + */ +extern struct msoab_compressor * + mspack_create_oab_compressor(struct mspack_system *sys); + +/** Creates a new OAB decompressor. + * @param sys a custom mspack_system structure, or NULL to use the default + * @return a #msoab_decompressor or NULL + */ +extern struct msoab_decompressor * + mspack_create_oab_decompressor(struct mspack_system *sys); + +/** Destroys an existing OAB compressor. + * @param self the #msoab_compressor to destroy + */ +extern void mspack_destroy_oab_compressor(struct msoab_compressor *self); + +/** Destroys an existing OAB decompressor. + * @param self the #msoab_decompressor to destroy + */ +extern void mspack_destroy_oab_decompressor(struct msoab_decompressor *self); + + /* --- support for .CAB (MS Cabinet) file format --------------------------- */ /** @@ -896,6 +934,13 @@ struct mscabd_file { #define MSCABD_PARAM_FIXMSZIP (1) /** mscab_decompressor::set_param() parameter: size of decompression buffer */ #define MSCABD_PARAM_DECOMPBUF (2) +/** mscab_decompressor::set_param() parameter: salvage data from bad cabinets? + * If enabled, open() will skip file with bad folder indices or filenames + * rather than reject the whole cabinet, and extract() will limit rather than + * reject files with invalid offsets and lengths, and bad data block checksums + * will be ignored. Available only in CAB decoder version 2 and above. + */ +#define MSCABD_PARAM_SALVAGE (3) /** TODO */ struct mscab_compressor { @@ -931,7 +976,7 @@ struct mscab_decompressor { * @see close(), search(), last_error() */ struct mscabd_cabinet * (*open) (struct mscab_decompressor *self, - const char *filename); + const char *filename); /** * Closes a previously opened cabinet or cabinet set. @@ -963,7 +1008,7 @@ struct mscab_decompressor { * @see open(), search(), append(), prepend() */ void (*close)(struct mscab_decompressor *self, - struct mscabd_cabinet *cab); + struct mscabd_cabinet *cab); /** * Searches a regular file for embedded cabinets. @@ -1000,7 +1045,7 @@ struct mscab_decompressor { * @see close(), open(), last_error() */ struct mscabd_cabinet * (*search) (struct mscab_decompressor *self, - const char *filename); + const char *filename); /** * Appends one mscabd_cabinet to another, forming or extending a cabinet @@ -1043,8 +1088,8 @@ struct mscab_decompressor { * @see prepend(), open(), close() */ int (*append) (struct mscab_decompressor *self, - struct mscabd_cabinet *cab, - struct mscabd_cabinet *nextcab); + struct mscabd_cabinet *cab, + struct mscabd_cabinet *nextcab); /** * Prepends one mscabd_cabinet to another, forming or extending a @@ -1065,8 +1110,8 @@ struct mscab_decompressor { * @see append(), open(), close() */ int (*prepend) (struct mscab_decompressor *self, - struct mscabd_cabinet *cab, - struct mscabd_cabinet *prevcab); + struct mscabd_cabinet *cab, + struct mscabd_cabinet *prevcab); /** * Extracts a file from a cabinet or cabinet set. @@ -1091,8 +1136,8 @@ struct mscab_decompressor { * @return an error code, or MSPACK_ERR_OK if successful */ int (*extract)(struct mscab_decompressor *self, - struct mscabd_file *file, - const char *filename); + struct mscabd_file *file, + const char *filename); /** * Sets a CAB decompression engine parameter. @@ -1117,8 +1162,8 @@ struct mscab_decompressor { * @see search(), extract() */ int (*set_param)(struct mscab_decompressor *self, - int param, - int value); + int param, + int value); /** * Returns the error code set by the most recently called method. @@ -1403,8 +1448,8 @@ struct mschm_compressor { * @see use_temporary_file() set_param() */ int (*generate)(struct mschm_compressor *self, - struct mschmc_file file_list[], - const char *output_file); + struct mschmc_file file_list[], + const char *output_file); /** * Specifies whether a temporary file is used during CHM generation. @@ -1460,8 +1505,8 @@ struct mschm_compressor { * @see generate() */ int (*use_temporary_file)(struct mschm_compressor *self, - int use_temp_file, - const char *temp_file); + int use_temp_file, + const char *temp_file); /** * Sets a CHM compression engine parameter. * @@ -1508,8 +1553,8 @@ struct mschm_compressor { * @see generate() */ int (*set_param)(struct mschm_compressor *self, - int param, - unsigned int value); + int param, + int value); /** * Returns the error code set by the most recently called method. @@ -1551,7 +1596,7 @@ struct mschm_decompressor { * @see close() */ struct mschmd_header *(*open)(struct mschm_decompressor *self, - const char *filename); + const char *filename); /** * Closes a previously opened CHM helpfile. @@ -1571,7 +1616,7 @@ struct mschm_decompressor { * @see open(), fast_open() */ void (*close)(struct mschm_decompressor *self, - struct mschmd_header *chm); + struct mschmd_header *chm); /** * Extracts a file from a CHM helpfile. @@ -1592,8 +1637,8 @@ struct mschm_decompressor { * @return an error code, or MSPACK_ERR_OK if successful */ int (*extract)(struct mschm_decompressor *self, - struct mschmd_file *file, - const char *filename); + struct mschmd_file *file, + const char *filename); /** * Returns the error code set by the most recently called method. @@ -1631,7 +1676,7 @@ struct mschm_decompressor { * @see open(), close(), fast_find(), extract() */ struct mschmd_header *(*fast_open)(struct mschm_decompressor *self, - const char *filename); + const char *filename); /** * Finds file details quickly. @@ -1672,10 +1717,10 @@ struct mschm_decompressor { * @see open(), close(), fast_find(), extract() */ int (*fast_find)(struct mschm_decompressor *self, - struct mschmd_header *chm, - const char *filename, - struct mschmd_file *f_ptr, - int f_size); + struct mschmd_header *chm, + const char *filename, + struct mschmd_file *f_ptr, + int f_size); }; /* --- support for .LIT (EBook) file format -------------------------------- */ @@ -1781,9 +1826,9 @@ struct msszdd_compressor { * @see set_param() */ int (*compress)(struct msszdd_compressor *self, - const char *input, - const char *output, - off_t length); + const char *input, + const char *output, + off_t length); /** * Sets an SZDD compression engine parameter. @@ -1807,8 +1852,8 @@ struct msszdd_compressor { * @see compress() */ int (*set_param)(struct msszdd_compressor *self, - int param, - unsigned int value); + int param, + int value); /** * Returns the error code set by the most recently called method. @@ -1849,7 +1894,7 @@ struct msszdd_decompressor { * @see close() */ struct msszddd_header *(*open)(struct msszdd_decompressor *self, - const char *filename); + const char *filename); /** * Closes a previously opened SZDD file. @@ -1865,7 +1910,7 @@ struct msszdd_decompressor { * @see open() */ void (*close)(struct msszdd_decompressor *self, - struct msszddd_header *szdd); + struct msszddd_header *szdd); /** * Extracts the compressed data from a SZDD file. @@ -1881,8 +1926,8 @@ struct msszdd_decompressor { * @return an error code, or MSPACK_ERR_OK if successful */ int (*extract)(struct msszdd_decompressor *self, - struct msszddd_header *szdd, - const char *filename); + struct msszddd_header *szdd, + const char *filename); /** * Decompresses an SZDD file to an output file in one step. @@ -1902,8 +1947,8 @@ struct msszdd_decompressor { * @return an error code, or MSPACK_ERR_OK if successful */ int (*decompress)(struct msszdd_decompressor *self, - const char *input, - const char *output); + const char *input, + const char *output); /** * Returns the error code set by the most recently called method. @@ -1937,6 +1982,8 @@ struct msszdd_decompressor { #define MSKWAJ_COMP_SZDD (2) /** KWAJ compression type: LZ+Huffman compression */ #define MSKWAJ_COMP_LZH (3) +/** KWAJ compression type: MSZIP */ +#define MSKWAJ_COMP_MSZIP (4) /** KWAJ optional header flag: decompressed file length is included */ #define MSKWAJ_HDR_HASLENGTH (0x01) @@ -2015,9 +2062,9 @@ struct mskwaj_compressor { * @see set_param() */ int (*compress)(struct mskwaj_compressor *self, - const char *input, - const char *output, - off_t length); + const char *input, + const char *output, + off_t length); /** * Sets an KWAJ compression engine parameter. @@ -2043,8 +2090,8 @@ struct mskwaj_compressor { * @see generate() */ int (*set_param)(struct mskwaj_compressor *self, - int param, - unsigned int value); + int param, + int value); /** @@ -2065,7 +2112,7 @@ struct mskwaj_compressor { * filename is too long */ int (*set_filename)(struct mskwaj_compressor *self, - const char *filename); + const char *filename); /** * Sets arbitrary data that will be stored in the header of the @@ -2085,8 +2132,8 @@ struct mskwaj_compressor { * is too long */ int (*set_extra_data)(struct mskwaj_compressor *self, - void *data, - size_t bytes); + void *data, + size_t bytes); /** * Returns the error code set by the most recently called method. @@ -2127,7 +2174,7 @@ struct mskwaj_decompressor { * @see close() */ struct mskwajd_header *(*open)(struct mskwaj_decompressor *self, - const char *filename); + const char *filename); /** * Closes a previously opened KWAJ file. @@ -2142,7 +2189,7 @@ struct mskwaj_decompressor { * @see open() */ void (*close)(struct mskwaj_decompressor *self, - struct mskwajd_header *kwaj); + struct mskwajd_header *kwaj); /** * Extracts the compressed data from a KWAJ file. @@ -2158,8 +2205,8 @@ struct mskwaj_decompressor { * @return an error code, or MSPACK_ERR_OK if successful */ int (*extract)(struct mskwaj_decompressor *self, - struct mskwajd_header *kwaj, - const char *filename); + struct mskwajd_header *kwaj, + const char *filename); /** * Decompresses an KWAJ file to an output file in one step. @@ -2179,8 +2226,8 @@ struct mskwaj_decompressor { * @return an error code, or MSPACK_ERR_OK if successful */ int (*decompress)(struct mskwaj_decompressor *self, - const char *input, - const char *output); + const char *input, + const char *output); /** * Returns the error code set by the most recently called method. @@ -2196,6 +2243,141 @@ struct mskwaj_decompressor { int (*last_error)(struct mskwaj_decompressor *self); }; +/* --- support for .LZX (Offline Address Book) file format ----------------- */ + +/** + * A compressor for the Offline Address Book (OAB) format. + * + * All fields are READ ONLY. + * + * @see mspack_create_oab_compressor(), mspack_destroy_oab_compressor() + */ +struct msoab_compressor { + /** + * Compress a full OAB file. + * + * The input file will be read and the compressed contents written to the + * output file. + * + * @param self a self-referential pointer to the msoab_decompressor + * instance being called + * @param input the filename of the input file. This is passed + * directly to mspack_system::open(). + * @param output the filename of the output file. This is passed + * directly to mspack_system::open(). + * @return an error code, or MSPACK_ERR_OK if successful + */ + int (*compress) (struct msoab_compressor *self, + const char *input, + const char *output); + + /** + * Generate a compressed incremental OAB patch file. + * + * The two uncompressed files "input" and "base" will be read, and an + * incremental patch to generate "input" from "base" will be written to + * the output file. + * + * @param self a self-referential pointer to the msoab_compressor + * instance being called + * @param input the filename of the input file containing the new + * version of its contents. This is passed directly + * to mspack_system::open(). + * @param base the filename of the original base file containing + * the old version of its contents, against which the + * incremental patch shall generated. This is passed + * directly to mspack_system::open(). + * @param output the filename of the output file. This is passed + * directly to mspack_system::open(). + * @return an error code, or MSPACK_ERR_OK if successful + */ + int (*compress_incremental) (struct msoab_compressor *self, + const char *input, + const char *base, + const char *output); +}; + +/** + * A decompressor for .LZX (Offline Address Book) files + * + * All fields are READ ONLY. + * + * @see mspack_create_oab_decompressor(), mspack_destroy_oab_decompressor() + */ +struct msoab_decompressor { + /** + * Decompresses a full Offline Address Book file. + * + * If the input file is a valid compressed Offline Address Book file, + * it will be read and the decompressed contents will be written to + * the output file. + * + * @param self a self-referential pointer to the msoab_decompressor + * instance being called + * @param input the filename of the input file. This is passed + * directly to mspack_system::open(). + * @param output the filename of the output file. This is passed + * directly to mspack_system::open(). + * @return an error code, or MSPACK_ERR_OK if successful + */ + int (*decompress) (struct msoab_decompressor *self, + const char *input, + const char *output); + + /** + * Decompresses an Offline Address Book with an incremental patch file. + * + * This requires both a full UNCOMPRESSED Offline Address Book file to + * act as the "base", and a compressed incremental patch file as input. + * If the input file is valid, it will be decompressed with reference to + * the base file, and the decompressed contents will be written to the + * output file. + * + * There is no way to tell what the right base file is for the given + * incremental patch, but if you get it wrong, this will usually result + * in incorrect data being decompressed, which will then fail a checksum + * test. + * + * @param self a self-referential pointer to the msoab_decompressor + * instance being called + * @param input the filename of the input file. This is passed + * directly to mspack_system::open(). + * @param base the filename of the base file to which the + * incremental patch shall be applied. This is passed + * directly to mspack_system::open(). + * @param output the filename of the output file. This is passed + * directly to mspack_system::open(). + * @return an error code, or MSPACK_ERR_OK if successful + */ + int (*decompress_incremental) (struct msoab_decompressor *self, + const char *input, + const char *base, + const char *output); + + /** + * Sets an OAB decompression engine parameter. Available only in OAB + * decompressor version 2 and above. + * + * - #MSOABD_PARAM_DECOMPBUF: How many bytes should be used as an input + * buffer by decompressors? The minimum value is 16. The default value + * is 4096. + * + * @param self a self-referential pointer to the msoab_decompressor + * instance being called + * @param param the parameter to set + * @param value the value to set the parameter to + * @return MSPACK_ERR_OK if all is OK, or MSPACK_ERR_ARGS if there + * is a problem with either parameter or value. + */ + int (*set_param)(struct msoab_decompressor *self, + int param, + int value); + +}; + +/** msoab_decompressor::set_param() parameter: size of decompression buffer */ +#define MSOABD_PARAM_DECOMPBUF (0) + #ifdef __cplusplus } #endif |