Package: Cabinet File Library and Utilities
Version: 0.10
Last modification date: 10/6/1998
Version: 0.20
Last modification date: 1/5/1999
Changes: Moved code to read and extract files from cabinet files to cfreader.cpp
         and cfreader.h.  Added classes in cfcreate.cpp/cfcreate.cpp to be used 
	    to create new cabinet files using either MSZIP or no compression.  Test 
	    sample program now creates a new cabinet file if no arguments, to view 
	    and/or extract cabinet files list the cabinet file as an argument.
Version: 0.29 (0.30 prerelease 1)
Last modification date: 10/17/1999
Changes: Complete rewrite of cabinet extraction code, part of goal towards  
         moving to a unified class base for both creating cabinet files and 
         extracting files from them.  Serious compatability bug fixed in which 
	    cabinet files past a certain certain size were not compatable with 
	    Microsoft's various cabinet utilities.  Cabinet files created with 
	    this library however remained able to be extracted by this library.  
	    This library is now fully compatable with Microsoft's cabinet 
	    utilities.  Note to all current users, you must upgrade to this 
	    version as the previous versions are now to be considered broken.  A 
	    Special note to all current users is that they must also pay attention 
	    to the changes in the codebase.  While the old cabinet extraction code 
	    is still available under the previous class name, do not use it, it is 
	    broken and will be removed by the next version.  Use cabinet_reader 
	    to read cabinet information and extract file from it.  Each 
	    cabinet_creator object creates its own tempory file to hold 
	    intermediate data now, so multiple cabinet files may be created at 
	    one time.
Version: 0.30
Last modification date: 10/24/1999
Changes: Added a build script to build library versions of the cabinet library. 
         Please use ./buildlib to build the library version.  Use ./testlib to 
	    test the library.  And use ./installlib to install the library.  An 
	    uninstall script is provided with ./uninstalllib.  The old build 
	    script has been kept around for those playing with the cabinet 
	    library.  Normal users should not use it anymore.  By default 
	    everything is installed under /usr/local.  The listcab utility is also 
	    install and can be used to build cabinets and extract files from them. 
	    All of the old cabinet creating classes have now been removed in favor 
	    of the new ones.  As part of the new library creating and installation 
	    routines, this package now requires the GNU libtool package.  libtool 
	    is not required for those playing with the library with the old build 
	    script.  Removed left over debugging tracers from code that will be 
	    going into the library.  Adjusted the folder class to return an error 
	    status as it was needed for the compression initializer.

All files in this package falls under the copywrite below:

Copyright (c) 1998 Anthony Barbachan.  All rights reserved.
This software is available for non-commercial purposes with the sole 
requirement that credit for my contribution, in this code, towards any software 
project be aknowledged.  Those looking to use this code in commercial purposes 
must contact me to work something resonable out.

Author and maintainer: Anthony Barbachan <cabinet@Trill.cis.fordham.edu>
Submit patches and reports to: cabinet@Trill.cis.fordham.edu

Introduction:

Contains cabinet file library and utilies under development.

	Currently most files are basically done, work is continuing within the 
listcab.cpp file to finish the cabinet reading/extracting class.  Some functions 
remain with the sole purpose of testing the cabinet file class.  The classes 
that create new cabinet files are mostly complete as well, only support for 
adding reserved areas remains to be added.

Building:

	Run the included buildlib script to build the listcab program.  The clean 
script will do the same as a "make clean".  A Makefile still has to be created 
for this project.  I do not know how to write makefiles so I would appreciate 
any makefile submissions.  After building you may run testlib to test the 
library.  To install the library run installlib.  To uninstall the library run 
uninstalllib.

Installation steps:

1. ./buildlib
2. ./testlib
3. ./installlib

	Everything will be installed under /usr/local.  Before upgrade to the next 
version I strongly suggest you uninstall this version first, unless you need to 
keep the shared library around for compiled programs.

Coder building instructions:

1. ./build

	This will build a binary ./listcab that includes the cabinet library as 
part of itself.  This can be used by coders to easily work with and modify the 
library internals.

DOS/Windows Users' Instructions

	If you happen to have the various used GNU utilities running on your 
system then you may be able to build using the above steps.  However most will 
have to include all the included C and CPP files into a project in Borland C++ 
in order to compile the library.  I have included my BC5 IDE project file which 
may be usable on your system.  For building a library used all included C and 
CPP files except LISTCAB.CPP.  LISTCAB.CPP can be used for building the 
LISTCAB.EXE utility.

Important Information:

	This package is intended to eventually be a portable cabinet file decoder 
and encoder, library and utility program.  Currently this is a project under 
development.  The current status of the development has most of the low-level 
cabinet related files complete, while work remains in implementing compression 
types other than MSZIP and adding cabinet file creation capabilities.  This code 
can, for now, read a cabinet file, retreive all of it's information, and extract 
one file per function call on MSZIP compressed folders.  I expect to eventually 
release the completed product under the GPL, however I want to closely read that 
document first.  For now, I am basically giving others permission to use and 
modify my code for non-commercial purposes with the only requirements being that 
you give credit to me for my pieces of code, let me know what you are using it 
in, and provide me similar access to whatever program/library/patch you decide 
to use my code in.  If you wish to use my code for commercial purposes, contact 
me and we will work something out.  Note: the permissions I have provided above 
only applies to code that I have written myself, other code retain whatever 
access rights their owners provided with them.

The code base consists of three sources:

All of the C files originate from the zlib 1.0.4 library package and retain 
whatever copywrites originated with them.  Note: that these files have been 
modified to correctly compile in a C++ enviroment and to correctly compress and 
decompress MSZIP compressed data as MSZIP slightly differs from the original 
library's compression specifications.  I suspect that these files may be removed 
in the future in favor of some combination of a C++ wrapper and the original 
zlib library.

The cabinet file data block checksum functions originated from the cabinet file 
specifiction document, necesary modifications were made to make it work within 
the class library.  The original author of this function was Microsoft, however 
it was distributed freely along with the detailed specifications for cabinet 
files.

The C++ files, except for the Microsoft checksum function, entirely consists of 
my code and is copywriten to me.  My changes to the other code bases are also 
copywriten to me.  For now, this section of the code base is being released 
under the permissions that I have granted above.  Eventually I expect to release 
this code under the GPL, but I want to read and fully understand that license 
agreement first.  Note that while the names of my member variables may be 
similar to that of other cabinet classes or structures this is probably due to 
my naming the various pieces of information the same as they were named in the 
cabinet file specifications.  Non of this code had any origins from other pieces 
of code.

Perferred coding style for patch submissions:

	Please use the following coding style to maintain readability and 
compatability:

	1 - use tabs characters not spaces.  If you must use spaces use 5 per tab.
	    When alligning things using tabs I strongly suggest you configure your 
	    editor to use 5 spaces per tab to maintain the style.
	2 - use the follow brace style for braced blocks for for,if,while,etc...

			if(...)			while(...)		for(...)
			{				{				{
				...				...				...
			}				}				}

	3 - use indents!!!
	4 - Comments are mine, yours, and every other programmer's best freind.
	5 - use pre-new standard C++, I want the resulting code to still be 
	    compilable on my Turbo C++ 3.0 IDE, the best programming IDE ever 
	    created.  So no incompatable templates, namespaces, new-style casts, 
	    new-style header names, exceptions, etc.  This is also my small revolt 
	    against the generally appauling and non-backwardly compatable changes 
	    the C++ standards committee has decided to implement in the new C++ 
	    standard.
	6 - Provide extensive error checking where needed, although I have probably 
	    done that what was most needed as most errors would occure during file 
	    reads or writes.  Remember that this will eventually be a library, so 
	    result codes should be more detailed than pass or fail.  Avoid bools as 
	    they do not provide much differentiation.  Use the error codes defined 
	    in cftypes.h, add if necesary.
	7 - The returning pointer for a new memory allocation call does not need to 
	    be checked for failures, I plan on adding a new handler or requiring 
	    the eventual user to provide one to handle memory allocation failures.

References:

	Cabinet file specifications: virtually all the specifications were obtained 
from the freely available Cabinet SDK from Microsoft.  The remaining 
specifications were obtained through trial and error except for the attribute 
settings for directories and volume names, those were obtained from Dr. Dobbs' 
code that showed how to program for cabinet files.

zlib specifications: were obtained from the same place I obtained the actual 
library.

deflate specifications: obtained from the deflate related rfc documents.

MSZIP specifications: obtained from the MSZIP specifications that were 
distributed with the Cabinet SDK.  Some details were gotten from trial and error 
along with inspired guesses as the MSZIP document lacked some important details.

- A. Barbachan (10/24/1999)
