Subversion Repositories Kolibri OS

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.

This calling wrapper for Wiz_SingleEntryUnzip() provides a method to pass

file lists as plain strings instead of the usual string arrays.

For VB Users only...:

int WINAPI Wiz_SingleEntryUnzpList(unsigned int ifnc, LPCSTR ExtList,

                                   unsigned int xfnc, LPCSTR ExcList,

                                   LPDCL lpDCL, LPUSERFUNCTIONS lpUserFunc)

ifnc       = number of file names being passed. If all files are to be

             extracted, then this can be zero.

ExtList    = Pointer to a list of file names to be extracted, separated by

             white space. If all files are to be extracted, then this should

             be NULL. Parameter ifnc should have an accurate count of the

             number of filenames being passed in.

xfnc       = number of "file names to be excluded from processing" being

             passed. If all files are to be extracted, set this to zero.

ExcList    = Pointer to a list of file names to be excluded from processing.

             Parameter xfnc should have an accurate count of the number of

             the number of filenames being passed in.

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.

The DCL structure collects the set of option flags supported by the WinDLL

interface to control the operation of the main function calls.

The first member of this structure is now a version identifier that should

be used to check structural compatibility of a passed option struct with

the expected structure layout. The C header file containing the reference

definition of the DCL structure also provides a symbol denoting the currently

valid StructVersID:

#define UZ_DCL_STRUCTVER        0x600

The layout of the DCL structure is shown below:

typedef struct {

 unsigned StructVersID  = struct version id (= UZ_DCL_STRUCTVER)

 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:

 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

                          1 = "safe" usage of paths in filenames (skip "../")

                          2 = allow also unsafe path components (dir traversal)

 int noflag             = always overwriting existing files if TRUE

 int naflag             = do end-of-line translation

 int nZIflag            = get ZipInfo if TRUE

 int B_flag             = backup existing files if TRUE

 int C_flag             = be case insensitive if TRUE

 int D_flag             = controls restoration of timestamps

                          1 = skip restoration of timestamps for folders

                              created on behalf of directory entries in the

                              Zip archive

                          2 = do not restore any timestamps; extracted files

                              and directories get stamped with the current time

 int U_flag             = controls UTF-8 filename coding support

                          1 = recognize UTF-8 coded names, but all non-ASCII

                              characters are "escaped" into "#Uxxxx"

                          2 = UTF-8 support is disabled, filename handling

                              works exactly as in previous UnZip versions

 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 pwbuf, int bufsiz,

    LPCSTR promptmsg, LPCSTR entryname);

typedef int (WINAPI DLLSERVICE) (LPCSTR entryname, z_uint8 uncomprsiz);

typedef int (WINAPI DLLSERVICE_I32) (LPCSTR entryname,

    unsigned long ucsz_lo, unsigned long ucsz_hi);

typedef void (WINAPI DLLSND) (void);

typedef int (WINAPI DLLREPLACE) (LPSTR efnam, unsigned efbufsiz);

typedef void (WINAPI DLLMESSAGE) (z_uint8 ucsize, z_uint8 csize,

    unsigned cfactor,

    unsigned mo, unsigned dy, unsigned yr, unsigned hh, unsigned mm,

    char c, LPCSTR filename, LPCSTR methbuf, unsigned long crc, char fCrypt);

typedef void (WINAPI DLLMESSAGE_I32) (unsigned long ucsiz_l,

    unsigned long ucsiz_h, unsigned long csiz_l, unsigned long csiz_h,

    unsigned cfactor,

    unsigned mo, unsigned dy, unsigned yr, unsigned hh, unsigned mm,

    char c, LPCSTR filename, LPCSTR methbuf, unsigned long crc, char fCrypt);

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. The

                          replace routine may modify the content of the efnam

                          string buffer, but must not write beyond its fixed

                          size of efbufsiz bytes! (This is a potential security

                          leak of the windll interface.) When modifying the

                          efnam buffer, the replace routine should return

                          the status IDM_REPLACE_RENAME.

 DLLPASSWORD *password  = a pointer to the application's password routine.

                          This function should return one of the status values

                          IZ_PW_ENTERED (0), IZ_PW_CANCEL (-1),

                          IZ_PW_CANCEL_ALL (-2), IZ_PW_ERROR (5).

 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 archive member it has just processed,

                          as well as it's original size.

 DLLMESSAGE_I32 *SendApplicationMessage_i32 = variant of SendApplicationMessage

                          callback, for environments that do not support the

                          64-bit integer types required to transfer "large"

                          ZIP64-compatible sizes.

 DLLSERVICE_I32 *ServCallBk_i32  = variant of the ServCallBk callback function,

                          for environments that do not support 64-bit integers.

 [NOTE: The _i32 variants of the SendApplicationMessage and ServCallBk callback

        functions are only called when the corresponding "regular" callback

        function pointers are set to NULL.  For the i386 architecture, the

        "..._i32" calling interfaces are binary identical with the

        corresponding regular __int64-aware interfaces.]

 [NOTE: The values below are filled in only when listing the contents of an

        archive.]

 z_uint8 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.

 z_uint8 TotalSize      = value to be filled in by the dll for the total

                          size of all files in the archive.

 z_uint8 NumMembers     = total number of files in the archive.

 unsigned 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.

 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:

    const UzpVer * WINAPI UzpVersion(void);

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 */

    LPCSTR betalevel;         /* e.g. "g BETA" or "" */

    LPCSTR date;              /* e.g. "9 Oct 08" (beta) or "9 October 2008" */

    LPCSTR zlib_version;      /* e.g. "1.2.3" or NULL */

    _version_type unzip;      /* current UnZip version */

    _version_type zipinfo;    /* current ZipInfo version */

    _version_type os2dll;     /* OS2DLL version (retained for compatibility) */

    _version_type windll;     /* WinDLL version (retained for compatibility) */

    _version_type dllapimin;  /* last incompatible change of library API */

} 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 UzpVersion does, but the short description is

    "UzpVersion() returns a pointer to a dll-internal static structure

    containing the unzip32.dll version information".

For usage with languages that do not support function which return pointers

to structures, the variant UzpVersion2() allows to retrieve the version info

into a memory area supplied by the caller:

    unsigned WINAPI UzpVersion2(UzpVer2 far *);

where UzpVer2 is defined as:

typedef struct _UzpVer2 {

    ulg structlen;            /* length of the struct being passed */

    ulg flag;                 /* bit 0: is_beta   bit 1: uses_zlib */

    char betalevel[10];       /* e.g. "g BETA" or "" */

    char date[20];            /* e.g. "9 Oct 08" (beta) or "9 October 2008" */

    char zlib_version[10];    /* e.g. "1.2.3" or NULL */

    _version_type unzip;      /* current UnZip version */

    _version_type zipinfo;    /* current ZipInfo version */

    _version_type os2dll;     /* OS2DLL version (retained for compatibility) */

    _version_type windll;     /* WinDLL version (retained for compatibility) */

    _version_type dllapimin;  /* last incompatible change of library API */

} UzpVer2;

   See api.c for the exact function of UzpVersion2, but the short description

   is "fill in the version information in the UzpVer2 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 cmd:

   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.

    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(const char *string, const char *pattern, int ignore_case);

or, when UnZips WILD_SEP_AT_DIR compile-time option was set:

  match(const char *string, const char *pattern, int ignore_case, int sepc);

  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.

  In case the code was compiled with WILD_STOP_AT_DIR enabled, the pattern

  wildcard functionality is modified as follows:

     `*' matches any sequence of characters (zero or more) until the first

         occurence of the separating character denoted by `sepc'

     `**' matches any sequence of characters (zero or more)

  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 January 18, 2009.

Mike White, Christian Spieler