src/lzma/7zC.txt
author Ryan C. Gordon <icculus@icculus.org>
Fri, 27 Mar 2009 15:10:42 -0400
changeset 972 254427fc42ab
parent 917 lzma/7zC.txt@d299a58a274f
permissions -rw-r--r--
Moved directory structure around.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
917
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
     1
7z ANSI-C Decoder 4.48
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
     2
----------------------
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
     3
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
     4
7z ANSI-C Decoder 4.48 Copyright (C) 1999-2006 Igor Pavlov
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
     5
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
     6
7z ANSI-C provides 7z/LZMA decoding.
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
     7
7z ANSI-C version is simplified version ported from C++ code.
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
     8
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
     9
LZMA is default and general compression method of 7z format
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    10
in 7-Zip compression program (www.7-zip.org). LZMA provides high 
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    11
compression ratio and very fast decompression.
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    12
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    13
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    14
LICENSE
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    15
-------
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    16
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    17
Read lzma.txt for information about license.
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    18
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    19
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    20
Files
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    21
---------------------
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    22
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    23
7zAlloc.*    - Allocate and Free
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    24
7zBuffer.*   - Buffer structure
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    25
7zCrc.*      - CRC32 code
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    26
7zDecode.*   - Low level memory->memory decoding
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    27
7zExtract.*  - High level stream->memory decoding
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    28
7zHeader.*   - .7z format constants
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    29
7zIn.*       - .7z archive opening
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    30
7zItem.*     - .7z structures
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    31
7zMain.c     - Test application
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    32
7zMethodID.* - MethodID structure
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    33
7zTypes.h    - Base types and constants
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    34
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    35
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    36
How To Use
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    37
----------
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    38
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    39
You must download 7-Zip program from www.7-zip.org.
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    40
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    41
You can create .7z archive with 7z.exe or 7za.exe:
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    42
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    43
  7za.exe a archive.7z *.htm -r -mx -m0fb=255
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    44
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    45
If you have big number of files in archive, and you need fast extracting, 
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    46
you can use partly-solid archives:
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    47
  
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    48
  7za.exe a archive.7z *.htm -ms=512K -r -mx -m0fb=255 -m0d=512K
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    49
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    50
In that example 7-Zip will use 512KB solid blocks. So it needs to decompress only 
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    51
512KB for extracting one file from such archive.
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    52
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    53
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    54
Limitations of current version of 7z ANSI-C Decoder
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    55
---------------------------------------------------
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    56
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    57
 - It reads only "FileName", "Size", "LastWriteTime" and "CRC" information for each file in archive.
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    58
 - It supports only LZMA and Copy (no compression) methods with BCJ or BCJ2 filters.
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    59
 - It converts original UTF-16 Unicode file names to UTF-8 Unicode file names.
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    60
 
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    61
These limitations will be fixed in future versions.
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    62
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    63
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    64
Using 7z ANSI-C Decoder Test application:
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    65
-----------------------------------------
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    66
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    67
Usage: 7zDec <command> <archive_name>
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    68
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    69
<Command>:
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    70
  e: Extract files from archive
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    71
  l: List contents of archive
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    72
  t: Test integrity of archive
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    73
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    74
Example: 
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    75
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    76
  7zDec l archive.7z
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    77
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    78
lists contents of archive.7z
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    79
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    80
  7zDec e archive.7z
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    81
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    82
extracts files from archive.7z to current folder.
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    83
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    84
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    85
How to use .7z Decoder
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    86
----------------------
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    87
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    88
.7z Decoder can be compiled in one of two modes:
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    89
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    90
1) Default mode. In that mode 7z Decoder will read full compressed 
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    91
   block to RAM before decompressing.
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    92
  
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    93
2) Mode with defined _LZMA_IN_CB. In that mode 7z Decoder can read
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    94
   compressed block by parts. And you can specify desired buffer size. 
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    95
   So memory requirements can be reduced. But decompressing speed will 
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    96
   be 5-10% lower and code size is slightly larger.
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    97
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    98
   
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
    99
Memory allocation
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   100
~~~~~~~~~~~~~~~~~
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   101
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   102
7z Decoder uses two memory pools:
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   103
1) Temporary pool
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   104
2) Main pool
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   105
Such scheme can allow you to avoid fragmentation of allocated blocks.
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   106
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   107
Steps for using 7z decoder
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   108
--------------------------
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   109
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   110
Use code at 7zMain.c as example.
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   111
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   112
1) Declare variables:
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   113
  inStream                     /* implements ISzInStream interface */
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   114
  CArchiveDatabaseEx db;       /* 7z archive database structure */
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   115
  ISzAlloc allocImp;           /* memory functions for main pool */
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   116
  ISzAlloc allocTempImp;       /* memory functions for temporary pool */
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   117
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   118
2) call InitCrcTable(); function to initialize CRC structures.
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   119
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   120
3) call SzArDbExInit(&db); function to initialize db structures.
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   121
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   122
4) call SzArchiveOpen(inStream, &db, &allocMain, &allocTemp) to open archive
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   123
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   124
This function opens archive "inStream" and reads headers to "db".
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   125
All items in "db" will be allocated with "allocMain" functions.
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   126
SzArchiveOpen function allocates and frees temporary structures by "allocTemp" functions.
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   127
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   128
5) List items or Extract items
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   129
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   130
  Listing code:
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   131
  ~~~~~~~~~~~~~
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   132
    {
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   133
      UInt32 i;
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   134
      for (i = 0; i < db.Database.NumFiles; i++)
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   135
      {
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   136
        CFileItem *f = db.Database.Files + i;
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   137
        printf("%10d  %s\n", (int)f->Size, f->Name);
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   138
      }
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   139
    }
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   140
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   141
  Extracting code:
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   142
  ~~~~~~~~~~~~~~~~
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   143
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   144
  SZ_RESULT SzExtract(
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   145
    ISzInStream *inStream, 
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   146
    CArchiveDatabaseEx *db,
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   147
    UInt32 fileIndex,         /* index of file */
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   148
    UInt32 *blockIndex,       /* index of solid block */
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   149
    Byte **outBuffer,         /* pointer to pointer to output buffer (allocated with allocMain) */
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   150
    size_t *outBufferSize,    /* buffer size for output buffer */
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   151
    size_t *offset,           /* offset of stream for required file in *outBuffer */
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   152
    size_t *outSizeProcessed, /* size of file in *outBuffer */
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   153
    ISzAlloc *allocMain,
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   154
    ISzAlloc *allocTemp);
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   155
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   156
  If you need to decompress more than one file, you can send these values from previous call:
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   157
    blockIndex, 
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   158
    outBuffer, 
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   159
    outBufferSize,
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   160
  You can consider "outBuffer" as cache of solid block. If your archive is solid, 
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   161
  it will increase decompression speed.
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   162
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   163
  After decompressing you must free "outBuffer":
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   164
  allocImp.Free(outBuffer);
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   165
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   166
6) call SzArDbExFree(&db, allocImp.Free) to free allocated items in "db".
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   167
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   168
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   169
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   170
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   171
Memory requirements for .7z decoding 
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   172
------------------------------------
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   173
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   174
Memory usage for Archive opening:
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   175
  - Temporary pool:
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   176
     - Memory for compressed .7z headers (if _LZMA_IN_CB is not defined)
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   177
     - Memory for uncompressed .7z headers
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   178
     - some other temporary blocks
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   179
  - Main pool:
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   180
     - Memory for database: 
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   181
       Estimated size of one file structures in solid archive:
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   182
         - Size (4 or 8 Bytes)
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   183
         - CRC32 (4 bytes)
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   184
         - LastWriteTime (8 bytes)
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   185
         - Some file information (4 bytes)
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   186
         - File Name (variable length) + pointer + allocation structures
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   187
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   188
Memory usage for archive Decompressing:
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   189
  - Temporary pool:
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   190
     - Memory for compressed solid block (if _LZMA_IN_CB is not defined)
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   191
     - Memory for LZMA decompressing structures
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   192
  - Main pool:
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   193
     - Memory for decompressed solid block
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   194
     - Memory for temprorary buffers, if BCJ2 fileter is used. Usually these 
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   195
       temprorary buffers can be about 15% of solid block size. 
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   196
  
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   197
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   198
If _LZMA_IN_CB is defined, 7z Decoder will not allocate memory for 
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   199
compressed blocks. Instead of this, you must allocate buffer with desired 
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   200
size before calling 7z Decoder. Use 7zMain.c as example.
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   201
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   202
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   203
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   204
EXIT codes
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   205
-----------
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   206
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   207
7z Decoder functions can return one of the following codes:
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   208
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   209
#define SZ_OK (0)
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   210
#define SZE_DATA_ERROR (1)
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   211
#define SZE_OUTOFMEMORY (2)
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   212
#define SZE_CRC_ERROR (3)
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   213
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   214
#define SZE_NOTIMPL (4)
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   215
#define SZE_FAIL (5)
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   216
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   217
#define SZE_ARCHIVE_ERROR (6)
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   218
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   219
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   220
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   221
LZMA Defines
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   222
------------
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   223
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   224
_LZMA_IN_CB       - Use special callback mode for input stream to reduce memory requirements
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   225
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   226
_SZ_FILE_SIZE_32  - define it if you need only support for files smaller than 4 GB
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   227
_SZ_NO_INT_64     - define it if your compiler doesn't support long long int or __int64.
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   228
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   229
_LZMA_PROB32      - it can increase LZMA decompressing speed on some 32-bit CPUs.
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   230
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   231
_SZ_ALLOC_DEBUG   - define it if you want to debug alloc/free operations to stderr.
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   232
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   233
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   234
---
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   235
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   236
http://www.7-zip.org
d299a58a274f Upgraded lzma sdk to 4.57.
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
   237
http://www.7-zip.org/support.html