1There are now several entry points to the dll. 2 3There is a single "unzipping" entry point of: 4 5int WINAPI Wiz_SingleEntryUnzip(int ifnc, char **ifnv, int xfnc, char **xfnv, 6 LPDCL lpDCL, LPUSERFUNCTIONS lpUserFunc) 7 8where the arguments are: 9 10ifnc = number of file names being passed. If all files are to be 11 extracted, then this can be zero. 12ifnv = file names to be unarchived. Wildcard patterns are recognized 13 and expanded. If all files are to be extracted, then this can 14 be NULL. 15xfnc = number of "file names to be excluded from processing" being 16 passed. If all files are to be extracted, set this to zero. 17xfnv = file names to be excluded from the unarchiving process. Wildcard 18 characters are allowed and expanded. If all files are to be 19 extracted, set this argument to NULL. 20lpDCL = pointer to a structure with the flags for setting the 21 various options, as well as the zip file name. 22lpUserFunc = pointer to a structure that contains pointers to functions 23 in the calling application, as well as sizes passed back to 24 the calling application etc. See below for a detailed description 25 of all the parameters. 26 27This calling wrapper for Wiz_SingleEntryUnzip() provides a method to pass 28file lists as plain strings instead of the usual string arrays. 29For VB Users only...: 30 31int WINAPI Wiz_SingleEntryUnzpList(unsigned int ifnc, LPCSTR ExtList, 32 unsigned int xfnc, LPCSTR ExcList, 33 LPDCL lpDCL, LPUSERFUNCTIONS lpUserFunc) 34 35ifnc = number of file names being passed. If all files are to be 36 extracted, then this can be zero. 37ExtList = Pointer to a list of file names to be extracted, separated by 38 white space. If all files are to be extracted, then this should 39 be NULL. Parameter ifnc should have an accurate count of the 40 number of filenames being passed in. 41xfnc = number of "file names to be excluded from processing" being 42 passed. If all files are to be extracted, set this to zero. 43ExcList = Pointer to a list of file names to be excluded from processing. 44 Parameter xfnc should have an accurate count of the number of 45 the number of filenames being passed in. 46lpDCL = pointer to a structure with the flags for setting the 47 various options, as well as the zip file name. 48lpUserFunc = pointer to a structure that contains pointers to functions 49 in the calling application, as well as sizes passed back to 50 the calling application etc. 51 52 53The DCL structure collects the set of option flags supported by the WinDLL 54interface to control the operation of the main function calls. 55The first member of this structure is now a version identifier that should 56be used to check structural compatibility of a passed option struct with 57the expected structure layout. The C header file containing the reference 58definition of the DCL structure also provides a symbol denoting the currently 59valid StructVersID: 60 61#define UZ_DCL_STRUCTVER 0x600 62 63The layout of the DCL structure is shown below: 64 65typedef struct { 66 unsigned StructVersID = struct version id (= UZ_DCL_STRUCTVER) 67 int ExtractOnlyNewer = TRUE for "update" without interaction 68 (extract only newer/new files, without queries) 69 int SpaceToUnderscore = TRUE if convert space to underscore 70 int PromptToOverwrite = TRUE if prompt to overwrite is wanted 71 int fQuiet = quiet flag: 72 0 = all messages, 1 = few messages, 2 = no messages 73 int ncflag = write to stdout if TRUE 74 int ntflag = test zip file 75 int nvflag = verbose listing 76 int nfflag = "freshen" (replace existing files by newer versions) 77 int nzflag = display zip file comment 78 int ndflag = controls (sub)directory recreation during extraction 79 0 = junk paths from filenames 80 1 = "safe" usage of paths in filenames (skip "../") 81 2 = allow also unsafe path components (dir traversal) 82 int noflag = always overwriting existing files if TRUE 83 int naflag = do end-of-line translation 84 int nZIflag = get ZipInfo if TRUE 85 int B_flag = backup existing files if TRUE 86 int C_flag = be case insensitive if TRUE 87 int D_flag = controls restoration of timestamps 88 0 = restore all timestamps (default) 89 1 = skip restoration of timestamps for folders 90 created on behalf of directory entries in the 91 Zip archive 92 2 = do not restore any timestamps; extracted files 93 and directories get stamped with the current time 94 int U_flag = controls UTF-8 filename coding support 95 0 = automatic UTF-8 translation enabled (default) 96 1 = recognize UTF-8 coded names, but all non-ASCII 97 characters are "escaped" into "#Uxxxx" 98 2 = UTF-8 support is disabled, filename handling 99 works exactly as in previous UnZip versions 100 int fPrivilege = 1 => restore ACLs in user mode, 101 2 => try to use privileges for restoring ACLs 102 LPSTR lpszZipFN = zip file name 103 LPSTR lpszExtractDir = directory to extract to. This should be NULL if you 104 are extracting to the current directory. 105} DCL, far * LPDCL; 106 107REMARKS: 108The four extract-mode flags ExtractOnlyNewer, nfflag, PromptToOverwrite, and 109noflag control which of the selected archive entries are actually processed. 110They are mapped to UnZip's command line qualifiers "-u", "-f", "-o", "-n" 111according to the following decision matrix: 112 _____________________________________________________________________ 113 | UnZip 1)|| Extract- | nfflag | noflag | PrompTo- | lpUserFunc | 114 | options || OnlyNewer | | | Overwrite | ->replape() | 115 ===================================================================== 116 | none 2) || false | false | false | true |queryfunc() 5)| 117 | -o || false | false | true | false | N/A | 118 | -n || false | false | false | false | N/A | 119 |---------||-----------|--------|--------|-----------|--------------| 120 | -u || true | false | false | true |queryfunc() 5)| 121 | -uo || true | false | true | false | N/A | 122 | -un 3) || true | false | false | false | N/A | 123 |---------||-----------|--------|--------|-----------|--------------| 124 | -f || N/A | true | false | true |queryfunc() 5)| 125 | -fo || N/A | true | true | false | N/A | 126 | -fn 4) || N/A | true | false | false | N/A | 127 --------------------------------------------------------------------- 128 Legend: true: integer number <> 0 129 false: integer number 0 130 N/A: not applicable, could be set to any value 131 NOTES: 132 1) The UnZip options are explained in the generic UnZip manual, see 133 "unzip.txt" or "man/unzip.1". 134 2) no options from the set "ufno" are specified. 135 3) -un is functionally equivalent to -n 136 4) -fn is functionally equivalent to "do nothing", so this combination 137 does not make sense. 138 5) queryfunc() is a callback function provided by the caller of the 139 unzip dll that may return one of the following result keys: 140 IDM_REPLACE_NO, IDM_REPLACE_YES, 141 IDM_REPLACE_ALL, IDM_REPLACE_NONE, 142 IDM_REPLACE_RENAME 143 (IDM_REPLACE_TEXT, IDM_REPLACE_HELP are defined but not used) 144 UnZip's internal code treats a "NULL" lpUserFunc->replace() function 145 pointer as "{return IDM_REPLACE_NONE}". However, currently, the windll 146 interface checks for this function pointer to be not NULL and signals 147 a fatal error if this condition is not fulfilled. 148 149 150The typedef's for the function pointers in the structure USERFUNCTIONS 151are shown immediately below. 152 153typedef unsigned short ush; 154typedef int (WINAPI DLLPRNT) (LPSTR, unsigned long); 155typedef int (WINAPI DLLPASSWORD) (LPSTR pwbuf, int bufsiz, 156 LPCSTR promptmsg, LPCSTR entryname); 157typedef int (WINAPI DLLSERVICE) (LPCSTR entryname, z_uint8 uncomprsiz); 158typedef int (WINAPI DLLSERVICE_I32) (LPCSTR entryname, 159 unsigned long ucsz_lo, unsigned long ucsz_hi); 160typedef void (WINAPI DLLSND) (void); 161typedef int (WINAPI DLLREPLACE) (LPSTR efnam, unsigned efbufsiz); 162typedef void (WINAPI DLLMESSAGE) (z_uint8 ucsize, z_uint8 csize, 163 unsigned cfactor, 164 unsigned mo, unsigned dy, unsigned yr, unsigned hh, unsigned mm, 165 char c, LPCSTR filename, LPCSTR methbuf, unsigned long crc, char fCrypt); 166typedef void (WINAPI DLLMESSAGE_I32) (unsigned long ucsiz_l, 167 unsigned long ucsiz_h, unsigned long csiz_l, unsigned long csiz_h, 168 unsigned cfactor, 169 unsigned mo, unsigned dy, unsigned yr, unsigned hh, unsigned mm, 170 char c, LPCSTR filename, LPCSTR methbuf, unsigned long crc, char fCrypt); 171 172Structure USERFUNCTIONS 173 174typedef struct { 175 DLLPRNT *print; = a pointer to the application's print routine. 176 DLLSND *sound; = a pointer to the application's sound routine. This 177 can be NULL if your application doesn't use 178 sound. 179 DLLREPLACE *replace = a pointer to the application's replace routine. The 180 replace routine may modify the content of the efnam 181 string buffer, but must not write beyond its fixed 182 size of efbufsiz bytes! (This is a potential security 183 leak of the windll interface.) When modifying the 184 efnam buffer, the replace routine should return 185 the status IDM_REPLACE_RENAME. 186 DLLPASSWORD *password = a pointer to the application's password routine. 187 This function should return one of the status values 188 IZ_PW_ENTERED (0), IZ_PW_CANCEL (-1), 189 IZ_PW_CANCEL_ALL (-2), IZ_PW_ERROR (5). 190 DLLMESSAGE *SendApplicationMessage = a pointer to the application's routine 191 for displaying information about specific files 192 in the archive. Used for listing the contents of 193 an archive. 194 DLLSERVICE *ServCallBk = Callback function designed to be used for 195 allowing the application to process Windows messages, 196 or canceling the operation, as well as giving the 197 option of a progress indicator. If this function 198 returns a non-zero value, then it will terminate 199 what it is doing. It provides the application with 200 the name of the archive member it has just processed, 201 as well as it's original size. 202 DLLMESSAGE_I32 *SendApplicationMessage_i32 = variant of SendApplicationMessage 203 callback, for environments that do not support the 204 64-bit integer types required to transfer "large" 205 ZIP64-compatible sizes. 206 DLLSERVICE_I32 *ServCallBk_i32 = variant of the ServCallBk callback function, 207 for environments that do not support 64-bit integers. 208 [NOTE: The _i32 variants of the SendApplicationMessage and ServCallBk callback 209 functions are only called when the corresponding "regular" callback 210 function pointers are set to NULL. For the i386 architecture, the 211 "..._i32" calling interfaces are binary identical with the 212 corresponding regular __int64-aware interfaces.] 213 [NOTE: The values below are filled in only when listing the contents of an 214 archive.] 215 z_uint8 TotalSizeComp = value to be filled in by the dll for the 216 compressed total size of the archive. Note this 217 value does not include the size of the archive 218 header and central directory list. 219 z_uint8 TotalSize = value to be filled in by the dll for the total 220 size of all files in the archive. 221 z_uint8 NumMembers = total number of files in the archive. 222 unsigned CompFactor = value to be filled in by the dll for the overall 223 compression factor. This could actually be computed 224 from the other values, but it is available. 225 WORD cchComment = flag to be set if archive has a comment 226} USERFUNCTIONS, far * LPUSERFUNCTIONS; 227 228Wiz_SingleEntryUnzip() returns a PKWARE compatible error code (0 if no 229error or warning). For an explanation of the supported error codes see 230the UnZip user documentation (the UnZip man page). 231 232For examples of how the actual calls to the dll are set up in WiZ, look in 233the files action.c and wizmain.c in the WiZ source directory. For a trival 234example of how to load and call the dll, look in uzexampl.c and uzexampl.h. 235 236For examples of how the actual loading and unloading of the dll's themselves 237was done, look in wizmain.c in the WiZ source directory. Note that WiZ looks 238specifically for a particular version number of the dll, and also expects to 239find the company name to be Info-ZIP. This is to protect from getting 240different versions of the dll loaded, with resulting unknown behavior. 241 242Additional entry points: 243 244 const UzpVer * WINAPI UzpVersion(void); 245 246where UzpVer is defined as: 247 248typedef struct _UzpVer { 249 ulg structlen; /* length of the struct being passed */ 250 ulg flag; /* bit 0: is_beta bit 1: uses_zlib */ 251 LPCSTR betalevel; /* e.g. "g BETA" or "" */ 252 LPCSTR date; /* e.g. "9 Oct 08" (beta) or "9 October 2008" */ 253 LPCSTR zlib_version; /* e.g. "1.2.3" or NULL */ 254 _version_type unzip; /* current UnZip version */ 255 _version_type zipinfo; /* current ZipInfo version */ 256 _version_type os2dll; /* OS2DLL version (retained for compatibility) */ 257 _version_type windll; /* WinDLL version (retained for compatibility) */ 258 _version_type dllapimin; /* last incompatible change of library API */ 259} UzpVer; 260 261and _version_type is defined as: 262 263typedef struct _ver { 264 uch major; /* e.g., integer 5 */ 265 uch minor; /* e.g., 2 */ 266 uch patchlevel; /* e.g., 0 */ 267 uch not_used; 268} _version_type; 269 270 See api.c for exactly what UzpVersion does, but the short description is 271 "UzpVersion() returns a pointer to a dll-internal static structure 272 containing the unzip32.dll version information". 273 274For usage with languages that do not support function which return pointers 275to structures, the variant UzpVersion2() allows to retrieve the version info 276into a memory area supplied by the caller: 277 278 unsigned WINAPI UzpVersion2(UzpVer2 far *); 279 280where UzpVer2 is defined as: 281 282typedef struct _UzpVer2 { 283 ulg structlen; /* length of the struct being passed */ 284 ulg flag; /* bit 0: is_beta bit 1: uses_zlib */ 285 char betalevel[10]; /* e.g. "g BETA" or "" */ 286 char date[20]; /* e.g. "9 Oct 08" (beta) or "9 October 2008" */ 287 char zlib_version[10]; /* e.g. "1.2.3" or NULL */ 288 _version_type unzip; /* current UnZip version */ 289 _version_type zipinfo; /* current ZipInfo version */ 290 _version_type os2dll; /* OS2DLL version (retained for compatibility) */ 291 _version_type windll; /* WinDLL version (retained for compatibility) */ 292 _version_type dllapimin; /* last incompatible change of library API */ 293} UzpVer2; 294 295 See api.c for the exact function of UzpVersion2, but the short description 296 is "fill in the version information in the UzpVer2 structure". 297 298void WINAPI Wiz_NoPrinting(int flag) 299 300 This entry point simply turns off all messages to the calling application if 301 flag is true, and turns them on if flag is false. 302 303int WINAPI Wiz_Validate(LPSTR archive, int AllCodes) 304 305 If AllCodes is FALSE, then Unz_Validate returns TRUE if archive points to a 306 valid archive, and FALSE otherwise. If AllCodes is TRUE, then Unz_Validate 307 returns whatever error code process_zipfiles returns, without evaluating it. 308 309int WINAPI Wiz_UnzipToMemory(LPSTR zip, LPSTR file, LPUSERFUNCTIONS lpUserFunc, 310 UzpBuffer *retstr) 311 312 Where UzpBuffer is defined as: 313 314 typedef struct _UzpBuffer { 315 ulg strlength; /* length of string */ 316 char * strptr; /* pointer to string */ 317 } UzpBuffer 318 319 Pass the name of the zip file in zip and the name of the file you wish to 320 extract in file. UzpUnzipToMemory will create a buffer and return it in 321 *retstr. 0 on return indicates failure. 322 323void WINAPI UzpFreeMemBuffer(UzpBuffer *retstr) 324 Use this routine to release the return data space allocated by the function 325 Wiz_UnzipToMemory(). 326 327int WINAPI Wiz_Grep(LPSTR archive, LPSTR file, LPSTR pattern, int cmd, 328 int SkipBin, LPUSERFUNCTIONS lpUserFunc) 329 330 Pass the name of the zip file in "zip", the name of the zip entry you wish 331 to perform the "grep" on in "file", and the string you wish to look for in 332 "pattern". There are four possible options for cmd: 333 334 0 => case insensitive search 335 1 => case sensitive search 336 2 => case insensitive search, whole words only 337 3 => case sensitive search, whole words only 338 339 If SkipBin is TRUE, then any binary (loosely interpreted) files will be 340 ignored. 341 342 lpUserFunc is a pointer to a USERFUNCTION structure as shown above. 343 344 UzpGrep returns: 345 346 -1 => error such as unable to allocate memory, unable to find file, etc. 347 0 => match not found, based on the search criteria 348 1 => match found, based on the search criteria 349 350There is an additional function call that does not specifically deal with 351"unzipping", but is a quite useful function that is currently used in Wiz 352itself in several places. This call is currently only available in the 353static library, not in the DLL. 354 355Match the pattern (wildcard) against the string (fixed): 356 357 match(const char *string, const char *pattern, int ignore_case); 358 359or, when UnZips WILD_SEP_AT_DIR compile-time option was set: 360 361 match(const char *string, const char *pattern, int ignore_case, int sepc); 362 363 returns TRUE if string matches pattern, FALSE otherwise. In the pattern: 364 365 `*' matches any sequence of characters (zero or more) 366 `?' matches any single character 367 [SET] matches any character in the specified set, 368 [!SET] or [^SET] matches any character not in the specified set. 369 370 In case the code was compiled with WILD_STOP_AT_DIR enabled, the pattern 371 wildcard functionality is modified as follows: 372 `*' matches any sequence of characters (zero or more) until the first 373 occurence of the separating character denoted by `sepc' 374 `**' matches any sequence of characters (zero or more) 375 376 A set is composed of characters or ranges; a range looks like ``character 377 hyphen character'' (as in 0-9 or A-Z). [0-9a-zA-Z_] is the minimal set of 378 characters allowed in the [..] pattern construct. Other characters are 379 allowed (i.e., 8-bit characters) if your system will support them. 380 381 To suppress the special syntactic significance of any of ``[]*?!^-\'', in- 382 side or outside a [..] construct, and match the character exactly, precede 383 it with a ``\'' (backslash). 384 385The remaining functions are linked together. Their use would be as 386follows (explanations for each function are shown further below): 387 388 #include "windll.h" 389 #include "structs.h" 390 MyApiCallingRoutine() 391 { 392 CREATEGLOBALS(); 393 . 394 . 395 . 396 Wiz_Init(pG, lpUserFunctions); /* Set up user functions */ 397 /* zvoid *pG, LPUSERFUNCTIONS lpUserFunctions */ 398 . 399 . 400 do { 401 . 402 . 403 Wiz_SetOpts(pG, lpDCL); /* Set up unzipping options */ 404 /* zvoid *pG, LPDCL lpDCL */ 405 . 406 . 407 Wiz_Unzip(pG, ifnc, ifnv, xfnc, xfnv); /* Unzip files */ 408 . 409 . 410 } while (!finished_condition) 411 . 412 . 413 DESTROYGLOBALS(); 414 } 415 416Each entry point is as defined below: 417 418 BOOL WINAPI Wiz_Init(zvoid *, LPUSERFUNCTIONS); 419 420 BOOL WINAPI Wiz_SetOpts(zvoid *, LPDCL); 421 422 int WINAPI Wiz_Unzip(zvoid *, int, char **, int, char **); 423 424Note that you should use either Wiz_SingleEntryUnzip OR the series of calls 425described above. Using both, depending on how you do it, could cause 426problems. The series of "lower level" gives you more freedom to add additional 427functionalities, whereas the single-entry api is easier to use. When using 428the "series" of calls, make sure that Wiz_SetOpts and Wiz_Unzip are always 429used together! When successfully called, Wiz_SetOpts has allocated some 430internal structures which are in turn free'd by Wiz_Unzip. 431 432Last revised January 18, 2009. 433 434Mike White, Christian Spieler 435