DOC/7zC.txt

   1 7z ANSI-C Decoder 4.62\r
   2 ----------------------\r
   3 \r
   4 7z ANSI-C provides 7z/LZMA decoding.\r
   5 7z ANSI-C version is simplified version ported from C++ code.\r
   6 \r
   7 LZMA is default and general compression method of 7z format\r
   8 in 7-Zip compression program (www.7-zip.org). LZMA provides high \r
   9 compression ratio and very fast decompression.\r
  10 \r
  11 \r
  12 LICENSE\r
  13 -------\r
  14 \r
  15 7z ANSI-C Decoder is part of the LZMA SDK.\r
  16 LZMA SDK is written and placed in the public domain by Igor Pavlov.\r
  17 \r
  18 Files\r
  19 ---------------------\r
  20 \r
  21 7zDecode.*   - Low level 7z decoding\r
  22 7zExtract.*  - High level 7z decoding\r
  23 7zHeader.*   - .7z format constants\r
  24 7zIn.*       - .7z archive opening\r
  25 7zItem.*     - .7z structures\r
  26 7zMain.c     - Test application\r
  27 \r
  28 \r
  29 How To Use\r
  30 ----------\r
  31 \r
  32 You must download 7-Zip program from www.7-zip.org.\r
  33 \r
  34 You can create .7z archive with 7z.exe or 7za.exe:\r
  35 \r
  36   7za.exe a archive.7z *.htm -r -mx -m0fb=255\r
  37 \r
  38 If you have big number of files in archive, and you need fast extracting, \r
  39 you can use partly-solid archives:\r
  40   \r
  41   7za.exe a archive.7z *.htm -ms=512K -r -mx -m0fb=255 -m0d=512K\r
  42 \r
  43 In that example 7-Zip will use 512KB solid blocks. So it needs to decompress only \r
  44 512KB for extracting one file from such archive.\r
  45 \r
  46 \r
  47 Limitations of current version of 7z ANSI-C Decoder\r
  48 ---------------------------------------------------\r
  49 \r
  50  - It reads only "FileName", "Size", "LastWriteTime" and "CRC" information for each file in archive.\r
  51  - It supports only LZMA and Copy (no compression) methods with BCJ or BCJ2 filters.\r
  52  - It converts original UTF-16 Unicode file names to UTF-8 Unicode file names.\r
  53  \r
  54 These limitations will be fixed in future versions.\r
  55 \r
  56 \r
  57 Using 7z ANSI-C Decoder Test application:\r
  58 -----------------------------------------\r
  59 \r
  60 Usage: 7zDec <command> <archive_name>\r
  61 \r
  62 <Command>:\r
  63   e: Extract files from archive\r
  64   l: List contents of archive\r
  65   t: Test integrity of archive\r
  66 \r
  67 Example: \r
  68 \r
  69   7zDec l archive.7z\r
  70 \r
  71 lists contents of archive.7z\r
  72 \r
  73   7zDec e archive.7z\r
  74 \r
  75 extracts files from archive.7z to current folder.\r
  76 \r
  77 \r
  78 How to use .7z Decoder\r
  79 ----------------------\r
  80 \r
  81 Memory allocation\r
  82 ~~~~~~~~~~~~~~~~~\r
  83 \r
  84 7z Decoder uses two memory pools:\r
  85 1) Temporary pool\r
  86 2) Main pool\r
  87 Such scheme can allow you to avoid fragmentation of allocated blocks.\r
  88 \r
  89 \r
  90 Steps for using 7z decoder\r
  91 --------------------------\r
  92 \r
  93 Use code at 7zMain.c as example.\r
  94 \r
  95 1) Declare variables:\r
  96   inStream                 /* implements ILookInStream interface */\r
  97   CSzArEx db;              /* 7z archive database structure */\r
  98   ISzAlloc allocImp;       /* memory functions for main pool */\r
  99   ISzAlloc allocTempImp;   /* memory functions for temporary pool */\r
 100 \r
 101 2) call CrcGenerateTable(); function to initialize CRC structures.\r
 102 \r
 103 3) call SzArEx_Init(&db); function to initialize db structures.\r
 104 \r
 105 4) call SzArEx_Open(&db, inStream, &allocMain, &allocTemp) to open archive\r
 106 \r
 107 This function opens archive "inStream" and reads headers to "db".\r
 108 All items in "db" will be allocated with "allocMain" functions.\r
 109 SzArEx_Open function allocates and frees temporary structures by "allocTemp" functions.\r
 110 \r
 111 5) List items or Extract items\r
 112 \r
 113   Listing code:\r
 114   ~~~~~~~~~~~~~\r
 115     {\r
 116       UInt32 i;\r
 117       for (i = 0; i < db.db.NumFiles; i++)\r
 118       {\r
 119         CFileItem *f = db.db.Files + i;\r
 120         printf("%10d  %s\n", (int)f->Size, f->Name);\r
 121       }\r
 122     }\r
 123 \r
 124   Extracting code:\r
 125   ~~~~~~~~~~~~~~~~\r
 126 \r
 127   SZ_RESULT SzAr_Extract(\r
 128     CArchiveDatabaseEx *db,\r
 129     ILookInStream *inStream, \r
 130     UInt32 fileIndex,         /* index of file */\r
 131     UInt32 *blockIndex,       /* index of solid block */\r
 132     Byte **outBuffer,         /* pointer to pointer to output buffer (allocated with allocMain) */\r
 133     size_t *outBufferSize,    /* buffer size for output buffer */\r
 134     size_t *offset,           /* offset of stream for required file in *outBuffer */\r
 135     size_t *outSizeProcessed, /* size of file in *outBuffer */\r
 136     ISzAlloc *allocMain,\r
 137     ISzAlloc *allocTemp);\r
 138 \r
 139   If you need to decompress more than one file, you can send these values from previous call:\r
 140     blockIndex, \r
 141     outBuffer, \r
 142     outBufferSize,\r
 143   You can consider "outBuffer" as cache of solid block. If your archive is solid, \r
 144   it will increase decompression speed.\r
 145 \r
 146   After decompressing you must free "outBuffer":\r
 147   allocImp.Free(outBuffer);\r
 148 \r
 149 6) call SzArEx_Free(&db, allocImp.Free) to free allocated items in "db".\r
 150 \r
 151 \r
 152 \r
 153 \r
 154 Memory requirements for .7z decoding \r
 155 ------------------------------------\r
 156 \r
 157 Memory usage for Archive opening:\r
 158   - Temporary pool:\r
 159      - Memory for uncompressed .7z headers\r
 160      - some other temporary blocks\r
 161   - Main pool:\r
 162      - Memory for database: \r
 163        Estimated size of one file structures in solid archive:\r
 164          - Size (4 or 8 Bytes)\r
 165          - CRC32 (4 bytes)\r
 166          - LastWriteTime (8 bytes)\r
 167          - Some file information (4 bytes)\r
 168          - File Name (variable length) + pointer + allocation structures\r
 169 \r
 170 Memory usage for archive Decompressing:\r
 171   - Temporary pool:\r
 172      - Memory for LZMA decompressing structures\r
 173   - Main pool:\r
 174      - Memory for decompressed solid block\r
 175      - Memory for temprorary buffers, if BCJ2 fileter is used. Usually these \r
 176        temprorary buffers can be about 15% of solid block size. \r
 177   \r
 178 \r
 179 7z Decoder doesn't allocate memory for compressed blocks. \r
 180 Instead of this, you must allocate buffer with desired \r
 181 size before calling 7z Decoder. Use 7zMain.c as example.\r
 182 \r
 183 \r
 184 Defines\r
 185 -------\r
 186 \r
 187 _SZ_ALLOC_DEBUG   - define it if you want to debug alloc/free operations to stderr.\r
 188 \r
 189 \r
 190 ---\r
 191 \r
 192 http://www.7-zip.org\r
 193 http://www.7-zip.org/sdk.html\r
 194 http://www.7-zip.org/support.html\r