litezip.htm

是一个C语言的压缩和解压缩的DLL源程序.

<P>To take some existing files on disk, and create a zip archive on disk, do the following:

<OL>
<P><LI>Call ZipCreateFile. You pass a handle to where you wish ZipCreateFile to supply an HZIP to you. You do not need to know the particulars of this handle. You'll simply pass it to other functions in LiteZip.dll just like you may pass a CreateFile() handle to ReadFile(). You also pass the filename for the zip archive you would like to create on disk. The name can include the full path such as "C:\My Directory\MyArchive.zip". If you wish to use encryption, you also pass the password string. If not using encryption, pass a 0 instead.

<P>If successful, ZipCreateFile will create an (empty) zip archive on disk, and fill in your HZIP handle.

<P><LI>Call ZipAddFile for each file you wish to add to the zip archive. You'll pass the HZIP handle supplied to you by ZipCreateFile, the filename of the file to be added to the archive, and the name you wish it to have inside of the zip archive. (You may wish to trim off some of the directories on the latter name if you want a relative directory hierarchy in the zip. Or you may wish to prepend directory names to create some directory hierarchy within the zip archive).

<P><LI>After you're done adding items to the zip archive, call ZipClose to finish up. You'll pass the HZIP handle supplied to you by ZipCreateFile.
</OL>

<P>Here's an example of the above. Assume that we have two files on disk, named "simple.bmp" and "simple.txt". We wish to zip them up into a zip archive named "simple1.zip".

<PRE>
  <span class='cpp-preprocessor'>#include</span> &lt;Windows.h&gt;
  <span class='cpp-preprocessor'>#include</span> <span class='cpp-string'>"LiteZip.h"</span>

  HZIP hz;

  ZipCreateFile(&hz, <span class='cpp-string'>"simple1.zip"</span>, <span class='cpp-literal'>0</span>);
  ZipAddFile(hz, <span class='cpp-string'>"simple.bmp"</span>);
  ZipAddFile(hz, <span class='cpp-string'>"simple.txt"</span>);
  ZipClose(hz);
</PRE>

The downloaded example ZipFile contains a similiar example, with error-checking, and also dynamic linking to LiteZip.dll. (With dynamic linking, you don't add LiteZip.lib to your project. And LiteZip.dll is not loaded when your app first starts. It is loaded only when you call LoadLibrary).

<H3>Example 2 - unzip a zipfile (on disk) to files on disk</H3>

<P>To take a zip archive on disk, and unzip its contents to disk, do the following:

<OL>
<P><LI>Call UnzipOpenFile. You pass a handle to where you wish UnzipOpenFile to supply an HUNZIP to you. You do not need to know the particulars of this handle. You'll simply pass it to other functions in LiteUnzip.dll. You also pass the filename for the zip archive you would like to unzip. The name can include the full path. If the zip is encrypted. you also pass the needed password string. If not using encryption, pass a 0 instead.

<P>If successful, UnzipOpenFile will open the zip archive on disk, and fill in your HUNZIP handle.

<P><LI>Call UnzipGetItem to determine how many items (files) are in the zip archive. You supply a ZIPENTRY struct to UnzipGetItem. (This is defined in LiteUnzip.h). You can allocate this struct using a memory function such as malloc, or declare it on the stack, or declare it as a global variable, etc. (If you allocate it, you're responsible for freeing it). Set the ZIPENTRY's Index field to -1 before you pass it to UnzipGetItem. You'll also pass the HUNZIP handle supplied to you by UnzipOpenFile.

<P>UnzipGetItem will set the ZIPENTRY's Index field to how many items are inside the zip archive.

<P><LI>Loop around calls to UnzipGetItem and UnzipItemToFile to extract each item from the archive, and save it on disk.

<P>To extract an item, you first set the ZIPENTRY's Index field to which item you wish to extract (where 0 is the first item, 1 is the second item, 2 is the third item, etc).

<P>Pass your ZIPENTRY, and the HUNZIP handle supplied by UnzipOpenFile, to UnzipGetItem. UnzipGetItem will fill in the ZIPENTRY with information about that item. This includes its name, its uncompressed size, its modification date, etc. If you want to extract only a particular item, rather than calling UnzipGetItem, you can fill in your ZIPENTRY's Name field with the desired item's name, and pass your ZIPENTRY to UnzipFindItem to fill in your ZIPENTRY with other information about that item.

<P>Finally, call UnzipItemToFile to extract that item to a disk file. Pass your ZIPENTRY, the HUNZIP handle supplied by UnzipOpenFile, and the filename you wish the item to be saved to. (You can use the ZIPENTRY's Name field if you want to use the same name it had within the archive). UnzipItemToFile will extract the item and save it to disk, creating any needed directories.

<P><LI>After you're done extracting items from the zip archive, call UnzipClose to finish up. You'll pass the HUNZIP handle supplied to you by ZipOpenFile.
</OL>

<P>Here's an example of the above. Assume that we have a zip archive on disk named "simple1.zip". We'll extract all its items, using the same filenames as within the archive. No encryption is used.

<PRE>
  <span class='cpp-preprocessor'>#include</span> &lt;Windows.h&gt;
  <span class='cpp-preprocessor'>#include</span> <span class='cpp-string'>"LiteUnzip.h"</span>

  HUNZIP   huz;
  ZIPENTRY ze;
  DWORD    numitems;

  ZipOpenFile(&huz, <span class='cpp-string'>"simple1.zip"</span>, <span class='cpp-literal'>0</span>);

  ze.Index = (DWORD)<span class='cpp-literal'>-1</span>;
  UnzipGetItem(huz, &ze);
  numitems = ze.Index;

  <span class='cpp-keyword'>for</span> (ze.Index = <span class='cpp-literal'>0</span>; ze.Index < numitems; ze.Index++)
  {
     UnzipGetItem(huz, &ze);
     UnzipItemToFile(huz, ze.Name, &ze);
  }

  UnzipClose(huz);
</PRE>

The downloaded example UnzipFile contains a similiar example, with error-checking, and also dynamic linking to LiteUnzip.dll. (With dynamic linking, you don't add LiteUnzip.lib to your project. And LiteUnzip.dll is not loaded when your app first starts. It is loaded only when you call LoadLibrary).

<P>Here's an example of extracting only the item named "readme.txt" from the same zip archive:

<PRE>
  HUNZIP   huz;
  ZIPENTRY ze;

  ZipOpenFile(&huz, <span class='cpp-string'>"simple1.zip"</span>, <span class='cpp-literal'>0</span>);
  lstrcpy(ze.name, <span class='cpp-string'>"readme.txt"</span>);
  UnzipFindItem(huz, &ze, <span class='cpp-literal'>0</span>); <span class='cpp-comment'>// Pass a 1 for case-insensitive find</span>
  UnzipItemToFile(huz, ze.Name, &ze);
  UnzipClose(huz);
</PRE>

<H3>Example 3- unzip from resource directly into memory</H3>

<P>This technique is useful for small games, where you want to keep all data files bundled up inside the executable, but reduce their size by zipping them first. It may also be useful for an installer, where the files to be installed are zipped into an archive that is embedded in the installer exe's resource.

<P>Assume our project has a .RC file with the line<BR>
<CODE><span class='cpp-literal'>1</span> RCDATA <span class='cpp-string'>"file.zip"</span></CODE><BR>
to embed the zipfile as a resource. Let's also assume that this zip archive contains an item named "sample.jpg", and we wish to unzip that one item into a memory buffer.

<P>The technique is very similiar to the above unzip example, except:

<OL>
<P><LI>We call UnzipOpenBuffer instead of UnzipOpenFile. After all, the zip archive is not a separate zip file on disk. Rather, it is part of our EXE's resources. The third arg is the resource id number. We used the number 1 in our RCDATA statement above.</LI>

<P><LI>We call UnzipItemToBuffer instead of UnzipItemToFile. After all, we want to unzip the item to a memory buffer we create, rather than a file on disk. Note that UnzipFindItem fills in the ZIPENTRY's UncompressedSize field with the size of the buffer we'll need. So we allocate that with GlobalAlloc (or in C++ you can use new).</LI>
</OL>

<PRE>
  HUNZIP   huz;
  ZIPENTRY ze;
  <span class='cpp-keyword'>char</span>    *buffer;

  UnzipOpenBuffer(&huz, <span class='cpp-literal'>0</span>, <span class='cpp-literal'>1</span>, <span class='cpp-literal'>0</span>)

  lstrcpy(ze.name, <span class='cpp-string'>"sample.jpg"</span>);
  UnzipFindItem(huz, &ze, <span class='cpp-literal'>0</span>);

  buffer = (<span class='cpp-keyword'>char</span> *)GlobalAlloc(GMEM_FIXED, ze.UncompressedSize);

  UnzipItemToBuffer(huz, buffer, ze.UncompressedSize, &ze)

  UnzipClose(huz);
  
  <span class='cpp-comment'>// Here you would do something with the contents of buffer.</span>

  GlobalFree(buffer);
</PRE>

The downloaded example UnzipResource shows how an installer EXE may unzip the entire contents of an archive embedded in its resources.

<H3>Other examples</H3>

<P>You can also zip up some existing file into an archive that is created in a memory buffer. You can either supply your own memory buffer (and make sure its big enough to accomodate the resulting archive), or you can simply let LiteZip.dll allocate the buffer from system paged memory. In the latter case, the DLL can automatically grow the buffer on-the-fly as needed.

<P>Furthermore, you can add the contents of some memory buffer

<P>The downloaded example ZipMemory shows the zipping the contents of a memory buffers into an archive created in memory. The example lets the DLL allocate system paged memory for the resulting archive. It's similiar to the zip example above except:

<OL>
<P><LI>We call zipCreateBuffer instead of ZipCreateFile. After all, the zip archive is not going to be created on disk. Rather, it is going to be created in memory. The third arg is the maximum limit to the growable size. You can make this a very large number because memory will be only reserved, but not actually committed, until needed.</LI>

<P><LI>We call ZipAddBuffer instead of ZipAddFile. After all, we want to zip up a memory buffer's contents rather than some existing file on disk.</LI>

<P><LI>Because we let the DLL allocate growable memory, rather than supplying our own buffer, we have to call ZipGetMemory to retrieve the buffer that the DLL creates the zip archive in. We don't need to call ZipClose because ZipGetMemory does that for us. We're also responsible for freeing that memory.</LI>
</OL>
</body></html>