libmspack, alpha release

The purpose of libmspack is to provide compressors and decompressors,
archivers and dearchivers for Microsoft compression formats: CAB, CHM,
HLP, KWAJ, LIT 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
http://www.kyz.uklinux.net/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 CVS, 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 CVS:

- 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.

In addition to the provisions of the LGPL, you are permitted to use the
library directly as part of your build process provided you meet all of
the following conditions:

1. Any modifications to the existing libmspack source code are ALL
   published and distributed under the LGPL license.
2. You MUST NOT use function calls, structures or definitions unless they are
   defined in the public library interface, "mspack.h".


EXAMPLE CODE

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

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.
cabextract_md5 - cabextract 0.6 (pre-libmspack) with output like cabd_md5
chmd_md5       - Prints the MD5 checksums of all files within a CHM file.
chminfo        - Prints verbose information about CHM file structures.
chmx           - Extracts all files in a CHM file to disk.
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;
}
