michael@0: 7z ANSI-C Decoder 4.23
michael@0: ----------------------
michael@0: 
michael@0: 7z ANSI-C Decoder 4.23 Copyright (C) 1999-2005 Igor Pavlov
michael@0: 
michael@0: 7z ANSI-C provides 7z/LZMA decoding.
michael@0: 7z ANSI-C version is simplified version ported from C++ code.
michael@0: 
michael@0: LZMA is default and general compression method of 7z format
michael@0: in 7-Zip compression program (www.7-zip.org). LZMA provides high 
michael@0: compression ratio and very fast decompression.
michael@0: 
michael@0: 
michael@0: LICENSE
michael@0: -------
michael@0: 
michael@0: Read lzma.txt for information about license.
michael@0: 
michael@0: 
michael@0: Files
michael@0: ---------------------
michael@0: 
michael@0: 7zAlloc.*    - Allocate and Free
michael@0: 7zBuffer.*   - Buffer structure
michael@0: 7zCrc.*      - CRC32 code
michael@0: 7zDecode.*   - Low level memory->memory decoding
michael@0: 7zExtract.*  - High level stream->memory decoding
michael@0: 7zHeader.*   - .7z format constants
michael@0: 7zIn.*       - .7z archive opening
michael@0: 7zItem.*     - .7z structures
michael@0: 7zMain.c     - Test application
michael@0: 7zMethodID.* - MethodID structure
michael@0: 7zTypes.h    - Base types and constants
michael@0: 
michael@0: 
michael@0: How To Use
michael@0: ----------
michael@0: 
michael@0: You must download 7-Zip program from www.7-zip.org.
michael@0: 
michael@0: You can create .7z archive with 7z.exe or 7za.exe:
michael@0: 
michael@0:   7za.exe a archive.7z *.htm -r -mx -m0fb=255 -mf=off
michael@0: 
michael@0: If you have big number of files in archive, and you need fast extracting, 
michael@0: you can use partly-solid archives:
michael@0:   
michael@0:   7za.exe a archive.7z *.htm -ms=512K -r -mx -m0fb=255 -m0d=512K -mf=off
michael@0: 
michael@0: In that example 7-Zip will use 512KB solid blocks. So it needs to decompress only 
michael@0: 512KB for extracting one file from such archive.
michael@0: 
michael@0: 
michael@0: Limitations of current version of 7z ANSI-C Decoder
michael@0: ---------------------------------------------------
michael@0: 
michael@0:  - It reads only "FileName", "Size", and "CRC" information for each file in archive.
michael@0:  - It supports only LZMA and Copy (no compression) methods.
michael@0:  - It converts original UTF-16 Unicode file names to UTF-8 Unicode file names.
michael@0:  
michael@0: These limitations will be fixed in future versions.
michael@0: 
michael@0: 
michael@0: Using 7z ANSI-C Decoder Test application:
michael@0: -----------------------------------------
michael@0: 
michael@0: Usage: 7zDec <command> <archive_name>
michael@0: 
michael@0: <Command>:
michael@0:   e: Extract files from archive
michael@0:   l: List contents of archive
michael@0:   t: Test integrity of archive
michael@0: 
michael@0: Example: 
michael@0: 
michael@0:   7zDec l archive.7z
michael@0: 
michael@0: lists contents of archive.7z
michael@0: 
michael@0:   7zDec e archive.7z
michael@0: 
michael@0: extracts files from archive.7z to current folder.
michael@0: 
michael@0: 
michael@0: How to use .7z Decoder
michael@0: ----------------------
michael@0: 
michael@0: .7z Decoder can be compiled in one of two modes:
michael@0: 
michael@0: 1) Default mode. In that mode 7z Decoder will read full compressed 
michael@0:    block to RAM before decompressing.
michael@0:   
michael@0: 2) Mode with defined _LZMA_IN_CB. In that mode 7z Decoder can read
michael@0:    compressed block by parts. And you can specify desired buffer size. 
michael@0:    So memory requirements can be reduced. But decompressing speed will 
michael@0:    be 5-10% lower and code size is slightly larger.
michael@0: 
michael@0:    
michael@0: Memory allocation
michael@0: ~~~~~~~~~~~~~~~~~
michael@0: 
michael@0: 7z Decoder uses two memory pools:
michael@0: 1) Temporary pool
michael@0: 2) Main pool
michael@0: Such scheme can allow you to avoid fragmentation of allocated blocks.
michael@0: 
michael@0: Steps for using 7z decoder
michael@0: --------------------------
michael@0: 
michael@0: Use code at 7zMain.c as example.
michael@0: 
michael@0: 1) Declare variables:
michael@0:   inStream                     /* implements ISzInStream interface */
michael@0:   CArchiveDatabaseEx db;       /* 7z archive database structure */
michael@0:   ISzAlloc allocImp;           /* memory functions for main pool */
michael@0:   ISzAlloc allocTempImp;       /* memory functions for temporary pool */
michael@0: 
michael@0: 2) call InitCrcTable(); function to initialize CRC structures.
michael@0: 
michael@0: 3) call SzArDbExInit(&db); function to initialize db structures.
michael@0: 
michael@0: 4) call SzArchiveOpen(inStream, &db, &allocMain, &allocTemp) to open archive
michael@0: 
michael@0: This function opens archive "inStream" and reads headers to "db".
michael@0: All items in "db" will be allocated with "allocMain" functions.
michael@0: SzArchiveOpen function allocates and frees temporary structures by "allocTemp" functions.
michael@0: 
michael@0: 5) List items or Extract items
michael@0: 
michael@0:   Listing code:
michael@0:   ~~~~~~~~~~~~~
michael@0:     {
michael@0:       UInt32 i;
michael@0:       for (i = 0; i < db.Database.NumFiles; i++)
michael@0:       {
michael@0:         CFileItem *f = db.Database.Files + i;
michael@0:         printf("%10d  %s\n", (int)f->Size, f->Name);
michael@0:       }
michael@0:     }
michael@0: 
michael@0:   Extracting code:
michael@0:   ~~~~~~~~~~~~~~~~
michael@0: 
michael@0:   SZ_RESULT SzExtract(
michael@0:     ISzInStream *inStream, 
michael@0:     CArchiveDatabaseEx *db,
michael@0:     UInt32 fileIndex,         /* index of file */
michael@0:     UInt32 *blockIndex,       /* index of solid block */
michael@0:     Byte **outBuffer,         /* pointer to pointer to output buffer (allocated with allocMain) */
michael@0:     size_t *outBufferSize,    /* buffer size for output buffer */
michael@0:     size_t *offset,           /* offset of stream for required file in *outBuffer */
michael@0:     size_t *outSizeProcessed, /* size of file in *outBuffer */
michael@0:     ISzAlloc *allocMain,
michael@0:     ISzAlloc *allocTemp);
michael@0: 
michael@0:   If you need to decompress more than one file, you can send these values from previous call:
michael@0:     blockIndex, 
michael@0:     outBuffer, 
michael@0:     outBufferSize,
michael@0:   You can consider "outBuffer" as cache of solid block. If your archive is solid, 
michael@0:   it will increase decompression speed.
michael@0: 
michael@0:   After decompressing you must free "outBuffer":
michael@0:   allocImp.Free(outBuffer);
michael@0: 
michael@0: 6) call SzArDbExFree(&db, allocImp.Free) to free allocated items in "db".
michael@0: 
michael@0: 
michael@0: 
michael@0: 
michael@0: Memory requirements for .7z decoding 
michael@0: ------------------------------------
michael@0: 
michael@0: Memory usage for Archive opening:
michael@0:   - Temporary pool:
michael@0:      - Memory for compressed .7z headers (if _LZMA_IN_CB is not defined)
michael@0:      - Memory for uncompressed .7z headers
michael@0:      - some other temporary blocks
michael@0:   - Main pool:
michael@0:      - Memory for database: 
michael@0:        Estimated size of one file structures in solid archive:
michael@0:          - Size (4 or 8 Bytes)
michael@0:          - CRC32 (4 bytes)
michael@0:          - Some file information (4 bytes)
michael@0:          - File Name (variable length) + pointer + allocation structures
michael@0: 
michael@0: Memory usage for archive Decompressing:
michael@0:   - Temporary pool:
michael@0:      - Memory for compressed solid block (if _LZMA_IN_CB is not defined)
michael@0:      - Memory for LZMA decompressing structures
michael@0:   - Main pool:
michael@0:      - Memory for decompressed solid block
michael@0:   
michael@0: 
michael@0: If _LZMA_IN_CB is defined, 7z Decoder will not allocate memory for 
michael@0: compressed blocks. Instead of this, you must allocate buffer with desired 
michael@0: size before calling 7z Decoder. Use 7zMain.c as example.
michael@0: 
michael@0: 
michael@0: 
michael@0: EXIT codes
michael@0: -----------
michael@0: 
michael@0: 7z Decoder functions can return one of the following codes:
michael@0: 
michael@0: #define SZ_OK (0)
michael@0: #define SZE_DATA_ERROR (1)
michael@0: #define SZE_OUTOFMEMORY (2)
michael@0: #define SZE_CRC_ERROR (3)
michael@0: 
michael@0: #define SZE_NOTIMPL (4)
michael@0: #define SZE_FAIL (5)
michael@0: 
michael@0: #define SZE_ARCHIVE_ERROR (6)
michael@0: 
michael@0: 
michael@0: 
michael@0: LZMA Defines
michael@0: ------------
michael@0: 
michael@0: _LZMA_IN_CB       - Use special callback mode for input stream to reduce memory requirements
michael@0: 
michael@0: _SZ_FILE_SIZE_64  - define it if you need support for files larger than 4 GB
michael@0: _SZ_NO_INT_64     - define it if your compiler doesn't support long long int
michael@0: 
michael@0: _LZMA_PROB32      - it can increase LZMA decompressing speed on some 32-bit CPUs.
michael@0: 
michael@0: _SZ_ONE_DIRECTORY - define it if you want to locate all source files to one directory
michael@0: _SZ_ALLOC_DEBUG   - define it if you want to debug alloc/free operations to stderr.
michael@0: 
michael@0: 
michael@0: ---
michael@0: 
michael@0: http://www.7-zip.org
michael@0: http://www.7-zip.org/support.html