libmspack 0.3alpha

The purpose of libmspack is to provide compressors and decompressors,
archivers and dearchivers for Microsoft compression formats: CAB, CHM, WIM,
LIT, HLP, KWAJ and SZDD. It is also designed to be easily embeddable,
stable, robust and resource-efficient.

The library is not intended as a generalised "any archiver" interface.
Users of the library must explicitly choose the format they intend to work
with.

All special features of the above formats will be covered as fully as
possible -- for example, CAB's multi-part cabinet sets, or CHM's fast
lookup indices. All compression methods used by the formats will be
implemented as completely as possible.

However, other than what is required for access to these formats and their
features, no other functionality is intended. There is no file metadata
translation functionality. All file I/O is abstracted, although a default
implementation using the standard C library is provided.


DOCUMENTATION

The API documentation is stored in the doc/ directory. It is generated
automatically from mspack.h with doxygen. It is also available online at
https://www.cabextract.org.uk/libmspack/doc/


BUILDING / INSTALLING

./configure
make
make install

This will install the main libmspack library and mspack.h header file.
Some other libraries and executables are built, but not installed.

If building from the Subversion repository, running rebuild.sh will create
all the automatically generated files like the configure script, and will
then ./configure, make and make distcheck. Running cleanup.sh will perform
a thorough clean, deleting all automatically generated files.

In addition to gcc, you also need the following for building from Subversion:

- at least autoconf 2.57
- at least automake 1.7
- libtool

This is an alpha release. Unless you are in a position to package the
libmspack library for the environment you intend to run your application,
it is recommended that you do not rely on users of your software having
the binary library installed and instead you should include the libmspack
source files directly in your application's build environment.


LEGAL ISSUES

The the best of my knowledge, libmspack does not infringe on any
compression or decompression patents. However, this is not legal
advice, and it is recommended that you perform your own patent search.

libmspack is licensed under the LGPL - see COPYING.LIB in this directory.

The LGPL requires you to build libmspack as a stand alone library then link
your code to it using a linker. I personally grant you some extra rights:
you can incorporate libmspack's source code wholly or partially in your own
code, without having to build and link libmspack as an independent library,
provided you meet ALL of the following conditions:

1. ANY modifications to the existing libmspack source code are published and
   distributed under the LGPL license.
2. You MUST NOT use libmspack function calls, structures or definitions unless
   they are defined in the public library interface "mspack.h".
3. When distributing your code, you MUST make clear your code uses libmspack,
   and either include the full libmspack distribution with your code, or
   provide access to it as per clause 4 of the LGPL.

EXAMPLE CODE

There are a number of useful programs in the test/ directory which
exercise and demonstrate libmspack's features.

cabd_c10       - Tests the CAB decompressor on the C10 collection.
cabd_compare   - Compares the CAB decompressor with Microsoft's EXTRACT.EXE
cabd_md5       - Prints the MD5 checksums of all files within a CAB file/set.
cabd_memory    - An mspack_system implementation that reads/writes to memory.
cabd_test      - Regression tests for libmspack's CAB decompression.
cabrip         - Extracts any CAB files embedded in another file.
chmd_compare   - Compares the CHM decompressor to Microsoft's HH.EXE
chmd_find      - Fast-finds a file within a CHM file.
chmd_md5       - Prints the MD5 checksums of all files within a CHM file.
chmd_order     - Tests extracting files in a CHM file in four different ways.
chminfo        - Prints verbose information about CHM file structures.
chmx           - Extracts all files in a CHM file to disk.
expand         - Extracts an SZDD or KWAJ file.
msdecompile_md5- Runs Microsoft's HH.EXE -DECOMPILE via WINE.
msexpand_md5   - Runs Microsoft's EXTRACT.EXE via WINE.
multifh        - An mspack_system implementation that can simultaneously work
                 on in-memory images, raw file descriptors, open file handles
                 and regular disk files.

Here is a simple example of usage, which will create a CAB decompressor,
then use that to open an existing Microsoft CAB file called "example.cab",
and list the names of all the files contained in that cab.

#include <stdio.h>
#include <unistd.h>
#include <mspack.h>

int main() {
  struct mscab_decompressor *cabd;
  struct mscabd_cabinet *cab;
  struct mscabd_file *file;
  int test;

  MSPACK_SYS_SELFTEST(test);
  if (test != MSPACK_ERR_OK) exit(0);

  if ((cabd = mspack_create_cab_decompressor(NULL))) {
    if ((cab = cabd->open(cabd, "example.cab"))) {
      for (file = cab->files; file; file = file->next) {
        printf("%s\n", file->filename);
      }
      cabd->close(cabd, cab);
    }
    mspack_destroy_cab_decompressor(cabd);
  }
  return 0;
}