There are now several entry points to the dll.

There is a single "unzipping" entry point of:

int WINAPI Wiz_SingleEntryUnzip(int ifnc, char **ifnv, int xfnc, char **xfnv,
                                LPDCL lpDCL, LPUSERFUNCTIONS lpUserFunc)

where the arguments are:

ifnc       = number of file names being passed. If all files are to be
             extracted, then this can be zero.
ifnv       = file names to be unarchived. Wildcard patterns are recognized
             and expanded. If all files are to be extracted, then this can
             be NULL.
xfnc       = number of "file names to be excluded from processing" being
             passed. If all files are to be extracted, set this to zero.
xfnv       = file names to be excluded from the unarchiving process. Wildcard
             characters are allowed and expanded. If all files are to be
             extracted, set this argument to NULL.
lpDCL      = pointer to a structure with the flags for setting the
             various options, as well as the zip file name.
lpUserFunc = pointer to a structure that contains pointers to functions
             in the calling application, as well as sizes passed back to
             the calling application etc. See below for a detailed description
             of all the parameters.

The DCL structure is shown below:

typedef struct {
int ExtractOnlyNewer    = true for "update" without interaction
                          (extract only newer/new files, without queries)
int SpaceToUnderscore   = true if convert space to underscore
int PromptToOverwrite   = true if prompt to overwrite is wanted
int fQuiet              = quiet flag:
                           0 = all messages, 1 = few messages, 2 = no messages
int ncflag              = write to stdout if true
int ntflag              = test zip file
int nvflag              = verbose listing
int nfflag              = "freshen" (replace existing files by newer versions)
int nzflag              = display zip file comment
int ndflag              = controls (sub)directory recreation during extraction
                          0 = junk paths from filenames
                          1 = "safe" usage of paths in filenames (skip "../")
                          2 = allow also unsafe path components (dir traversal)
int noflag              = true if you are to always overwrite existing files
int naflag              = do end-of-line translation
int nZIflag             = get ZipInfo if TRUE
int C_flag              = be case insensitive if TRUE
int fPrivilege          = 1 => restore ACLs in user mode,
                          2 => try to use privileges for restoring ACLs
LPSTR lpszZipFN         = zip file name
LPSTR lpszExtractDir    = directory to extract to. This should be NULL if you
                          are extracting to the current directory.
} DCL, far * LPDCL;

REMARKS:
The four extract-mode flags ExtractOnlyNewer, nfflag, PromptToOverwrite, and
noflag control which of the selected archive entries are actually processed.
They are mapped to UnZip's command line qualifiers "-u", "-f", "-o", "-n"
according to the following decision matrix:
 _____________________________________________________________________
 | UnZip 1)|| Extract-  | nfflag | noflag | PrompTo-  | lpUserFunc   |
 | options || OnlyNewer |        |        | Overwrite | ->replape()  |
 =====================================================================
 | none 2) ||   false   |  false |  false |   true    |queryfunc() 5)|
 | -o      ||   false   |  false |  true  |   false   |     N/A      |
 | -n      ||   false   |  false |  false |   false   |     N/A      |
 |---------||-----------|--------|--------|-----------|--------------|
 | -u      ||   true    |  false |  false |   true    |queryfunc() 5)|
 | -uo     ||   true    |  false |  true  |   false   |     N/A      |
 | -un  3) ||   true    |  false |  false |   false   |     N/A      |
 |---------||-----------|--------|--------|-----------|--------------|
 | -f      ||    N/A    |  true  |  false |   true    |queryfunc() 5)|
 | -fo     ||    N/A    |  true  |  true  |   false   |     N/A      |
 | -fn  4) ||    N/A    |  true  |  false |   false   |     N/A      |
 ---------------------------------------------------------------------
 Legend: true:  integer number <> 0
         false: integer number 0
	 N/A:   not applicable, could be set to any value
 NOTES:
 1) The UnZip options are explained in the generic UnZip manual, see
    "unzip.txt" or "man/unzip.1".
 2) no options from the set "ufno" are specified.
 3) -un is functionally equivalent to -n
 4) -fn is functionally equivalent to "do nothing", so this combination
    does not make sense.
 5) queryfunc() is a callback function provided by the caller of the
    unzip dll that may return one of the following result keys:
     IDM_REPLACE_NO, IDM_REPLACE_YES,
     IDM_REPLACE_ALL, IDM_REPLACE_NONE,
     IDM_REPLACE_RENAME
     (IDM_REPLACE_TEXT, IDM_REPLACE_HELP are defined but not used)
    UnZip's internal code treats a "NULL" lpUserFunc->replace() function
    pointer as "{return IDM_REPLACE_NONE}". However, currently, the windll
    interface checks for this function pointer to be not NULL and signals
    a fatal error if this condition is not fulfilled.


The typedef's for the function pointers in the structure USERFUNCTIONS
are shown immediately below.

typedef unsigned short ush;
typedef int (WINAPI DLLPRNT) (LPSTR, unsigned long);
typedef int (WINAPI DLLPASSWORD) (LPSTR, int, LPCSTR, LPCSTR);
typedef int (WINAPI DLLSERVICE) (LPSTR, unsigned long);
typedef void (WINAPI DLLSND) (void);
typedef int (WINAPI DLLREPLACE)(LPSTR);
typedef void (WINAPI DLLMESSAGE)(unsigned long, unsigned long, unsigned,
   unsigned, unsigned, unsigned, unsigned, unsigned,
   char, LPSTR, LPSTR, unsigned long, char);

Structure USERFUNCTIONS

typedef struct {
DLLPRNT *print;         = a pointer to the application's print routine.
DLLSND *sound;          = a pointer to the application's sound routine. This
                          can be NULL if your application doesn't use
                          sound.
DLLREPLACE *replace     = a pointer to the application's replace routine.
DLLPASSWORD *password   = a pointer to the application's password routine.
DLLMESSAGE *SendApplicationMessage = a pointer to the application's routine
                          for displaying information about specific files
                          in the archive. Used for listing the contents of
                          an archive.
DLLSERVICE *ServCallBk  = Callback function designed to be used for
                          allowing the application to process Windows messages,
                          or canceling the operation, as well as giving the
                          option of a progress indicator. If this function
                          returns a non-zero value, then it will terminate
                          what it is doing. It provides the application with
                          the name of the name of the archive member it has
                          just processed, as well as it's original size.
NOTE: The values below are filled in only when listing the contents of an
      archive.

unsigned long TotalSizeComp = value to be filled in by the dll for the
                          compressed total size of the archive. Note this
                          value does not include the size of the archive
                          header and central directory list.
unsigned long TotalSize = value to be filled in by the dll for the total
                          size of all files in the archive.
unsigned long CompFactor = value to be filled in by the dll for the overall
                          compression factor. This could actually be computed
                          from the other values, but it is available.
unsigned long NumMembers = total number of files in the archive.
WORD cchComment;        = flag to be set if archive has a comment
} USERFUNCTIONS, far * LPUSERFUNCTIONS;

Wiz_SingleEntryUnzip() returns a PKWARE compatible error code (0 if no
error or warning). For an explanation of the supported error codes see
the UnZip user documentation (the UnZip man page).

For examples of how the actual calls to the dll are set up in WiZ, look in
the files action.c and wizmain.c in the WiZ source directory. For a trival
example of how to load and call the dll, look in uzexampl.c and uzexampl.h.

For examples of how the actual loading and unloading of the dll's themselves
was done, look in wizmain.c in the WiZ source directory. Note that WiZ looks
specifically for a particular version number of the dll, and also expects to
find the company name to be Info-ZIP. This is to protect from getting
different versions of the dll loaded, with resulting unknown behavior.

Additional entry points:

    void WINAPI UzpVersion2(UzpVer far *);

where UzpVer is defined as:

typedef struct _UzpVer {
    ulg structlen;          /* length of the struct being passed */
    ulg flag;               /* bit 0: is_beta   bit 1: uses_zlib */
    LPSTR betalevel;        /* e.g., "g BETA" or "" */
    LPSTR date;             /* e.g., "4 Sep 95" (beta) or "4 September 1995" */
    LPSTR zlib_version;     /* e.g., "1.0.5" or NULL */
    _version_type unzip;
    _version_type zipinfo;
    _version_type os2dll;
    _version_type windll;
} UzpVer;

and _version_type is defined as:

typedef struct _ver {
    uch major;              /* e.g., integer 5 */
    uch minor;              /* e.g., 2 */
    uch patchlevel;         /* e.g., 0 */
    uch not_used;
} _version_type;

   See api.c for exactly what UzpVersion2 does, but the short version of
   what it does is fill in the version information in the UzpVer structure.

void WINAPI Wiz_NoPrinting(int flag)

   This entry point simply turns off all messages to the calling application if
   flag is true, and turns them on if flag is false.

int WINAPI Wiz_Validate(LPSTR archive, int AllCodes)

   If AllCodes is FALSE, then Unz_Validate returns TRUE if archive points to a
   valid archive, and FALSE otherwise. If AllCodes is TRUE, then Unz_Validate
   returns whatever error code process_zipfiles returns, without evaluating it.

int WINAPI Wiz_UnzipToMemory(LPSTR zip, LPSTR file, LPUSERFUNCTIONS lpUserFunc,
                             UzpBuffer *retstr)

   Where UzpBuffer is defined as:

   typedef struct _UzpBuffer {
      ulg strlength; /* length of string */
      char * strptr; /* pointer to string */
   } UzpBuffer

   Pass the name of the zip file in zip and the name of the file you wish to
   extract in file. UzpUnzipToMemory will create a buffer and return it in
   *retstr. 0 on return indicates failure.

void WINAPI UzpFreeMemBuffer(UzpBuffer *retstr)
   Use this routine to release the return data space allocated by the function
   Wiz_UnzipToMemory().

int WINAPI Wiz_Grep(LPSTR archive, LPSTR file, LPSTR pattern, int cmd,
                    int SkipBin, LPUSERFUNCTIONS lpUserFunc)

   Pass the name of the zip file in "zip", the name of the zip entry you wish
   to perform the "grep" on in "file", and the string you wish to look for in
   "pattern". There are four possible options for code:

   0 => case insensitive search
   1 => case sensitive search
   2 => case insensitive search, whole words only
   3 => case sensitive search, whole words only

   If SkipBin is TRUE, then any binary (loosely interpreted) files will be
   ignored.

   lpUserFunc is a pointer to a USERFUNCTION structure as shown above.

   UzpGrep returns:

   -1 => error such as unable to allocate memory, unable to find file, etc.
    0 => match not found, based on the search criteria
    1 => match found, based on the search criteria

There is an additional function call that does not specifically deal with
"unzipping", but is a quite useful function that is currently used in Wiz
itself in several places. This call is currently only available in the
static library, not in the DLL.

Match the pattern (wildcard) against the string (fixed):

  match(string, pattern, ignore_case);

  returns TRUE if string matches pattern, FALSE otherwise.  In the pattern:

     `*' matches any sequence of characters (zero or more)
     `?' matches any single character
     [SET] matches any character in the specified set,
     [!SET] or [^SET] matches any character not in the specified set.

  A set is composed of characters or ranges; a range looks like ``character
  hyphen character'' (as in 0-9 or A-Z).  [0-9a-zA-Z_] is the minimal set of
  characters allowed in the [..] pattern construct.  Other characters are
  allowed (i.e., 8-bit characters) if your system will support them.

  To suppress the special syntactic significance of any of ``[]*?!^-\'', in-
  side or outside a [..] construct, and match the character exactly, precede
  it with a ``\'' (backslash).

The remaining functions are linked together. Their use would be as
follows (explanations for each function are shown further below):

    #include "windll.h"
    #include "structs.h"
    MyApiCallingRoutine()
    {
        CREATEGLOBALS();
        .
        .
        .
        Wiz_Init(pG, lpUserFunctions); /* Set up user functions */
        /* zvoid *pG, LPUSERFUNCTIONS lpUserFunctions */
        .
        .
        do {
          .
          .
          Wiz_SetOpts(pG, lpDCL); /* Set up unzipping options */
          /* zvoid *pG, LPDCL lpDCL */
          .
          .
          Wiz_Unzip(pG, ifnc, ifnv, xfnc, xfnv); /* Unzip files */
          .
          .
        } while (!finished_condition)
        .
        .
        DESTROYGLOBALS();
    }

Each entry point is as defined below:

    BOOL WINAPI Wiz_Init(zvoid *, LPUSERFUNCTIONS);

    BOOL WINAPI Wiz_SetOpts(zvoid *, LPDCL);

    int WINAPI Wiz_Unzip(zvoid *, int, char **, int, char **);

Note that you should use either Wiz_SingleEntryUnzip OR the series of calls
described above. Using both, depending on how you do it, could cause
problems. The series of "lower level" gives you more freedom to add additional
functionalities, whereas the single-entry api is easier to use. When using
the "series" of calls, make sure that Wiz_SetOpts and Wiz_Unzip are always
used together! When successfully called, Wiz_SetOpts has allocated some
internal structures which are in turn free'd by Wiz_Unzip.

Last revised February 27, 2005.

Mike White, Christian Spieler
