"Fossies" - the Fresh Open Source Software Archive 
Member "windll.txt" (18 Jan 2009, 21320 Bytes) of package /windows/misc/unz600dn.zip:
As a special service "Fossies" has tried to format the requested text file into HTML format (style:
standard) with prefixed line numbers.
Alternatively you can here
view or
download the uninterpreted source code file.
1 There are now several entry points to the dll.
2
3 There is a single "unzipping" entry point of:
4
5 int WINAPI Wiz_SingleEntryUnzip(int ifnc, char **ifnv, int xfnc, char **xfnv,
6 LPDCL lpDCL, LPUSERFUNCTIONS lpUserFunc)
7
8 where the arguments are:
9
10 ifnc = number of file names being passed. If all files are to be
11 extracted, then this can be zero.
12 ifnv = 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.
15 xfnc = number of "file names to be excluded from processing" being
16 passed. If all files are to be extracted, set this to zero.
17 xfnv = 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.
20 lpDCL = pointer to a structure with the flags for setting the
21 various options, as well as the zip file name.
22 lpUserFunc = 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
27 This calling wrapper for Wiz_SingleEntryUnzip() provides a method to pass
28 file lists as plain strings instead of the usual string arrays.
29 For VB Users only...:
30
31 int WINAPI Wiz_SingleEntryUnzpList(unsigned int ifnc, LPCSTR ExtList,
32 unsigned int xfnc, LPCSTR ExcList,
33 LPDCL lpDCL, LPUSERFUNCTIONS lpUserFunc)
34
35 ifnc = number of file names being passed. If all files are to be
36 extracted, then this can be zero.
37 ExtList = 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.
41 xfnc = number of "file names to be excluded from processing" being
42 passed. If all files are to be extracted, set this to zero.
43 ExcList = 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.
46 lpDCL = pointer to a structure with the flags for setting the
47 various options, as well as the zip file name.
48 lpUserFunc = 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
53 The DCL structure collects the set of option flags supported by the WinDLL
54 interface to control the operation of the main function calls.
55 The first member of this structure is now a version identifier that should
56 be used to check structural compatibility of a passed option struct with
57 the expected structure layout. The C header file containing the reference
58 definition of the DCL structure also provides a symbol denoting the currently
59 valid StructVersID:
60
61 #define UZ_DCL_STRUCTVER 0x600
62
63 The layout of the DCL structure is shown below:
64
65 typedef 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
107 REMARKS:
108 The four extract-mode flags ExtractOnlyNewer, nfflag, PromptToOverwrite, and
109 noflag control which of the selected archive entries are actually processed.
110 They are mapped to UnZip's command line qualifiers "-u", "-f", "-o", "-n"
111 according 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
150 The typedef's for the function pointers in the structure USERFUNCTIONS
151 are shown immediately below.
152
153 typedef unsigned short ush;
154 typedef int (WINAPI DLLPRNT) (LPSTR, unsigned long);
155 typedef int (WINAPI DLLPASSWORD) (LPSTR pwbuf, int bufsiz,
156 LPCSTR promptmsg, LPCSTR entryname);
157 typedef int (WINAPI DLLSERVICE) (LPCSTR entryname, z_uint8 uncomprsiz);
158 typedef int (WINAPI DLLSERVICE_I32) (LPCSTR entryname,
159 unsigned long ucsz_lo, unsigned long ucsz_hi);
160 typedef void (WINAPI DLLSND) (void);
161 typedef int (WINAPI DLLREPLACE) (LPSTR efnam, unsigned efbufsiz);
162 typedef 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);
166 typedef 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
172 Structure USERFUNCTIONS
173
174 typedef 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
228 Wiz_SingleEntryUnzip() returns a PKWARE compatible error code (0 if no
229 error or warning). For an explanation of the supported error codes see
230 the UnZip user documentation (the UnZip man page).
231
232 For examples of how the actual calls to the dll are set up in WiZ, look in
233 the files action.c and wizmain.c in the WiZ source directory. For a trival
234 example of how to load and call the dll, look in uzexampl.c and uzexampl.h.
235
236 For examples of how the actual loading and unloading of the dll's themselves
237 was done, look in wizmain.c in the WiZ source directory. Note that WiZ looks
238 specifically for a particular version number of the dll, and also expects to
239 find the company name to be Info-ZIP. This is to protect from getting
240 different versions of the dll loaded, with resulting unknown behavior.
241
242 Additional entry points:
243
244 const UzpVer * WINAPI UzpVersion(void);
245
246 where UzpVer is defined as:
247
248 typedef 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
261 and _version_type is defined as:
262
263 typedef 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
274 For usage with languages that do not support function which return pointers
275 to structures, the variant UzpVersion2() allows to retrieve the version info
276 into a memory area supplied by the caller:
277
278 unsigned WINAPI UzpVersion2(UzpVer2 far *);
279
280 where UzpVer2 is defined as:
281
282 typedef 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
298 void 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
303 int 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
309 int 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
323 void WINAPI UzpFreeMemBuffer(UzpBuffer *retstr)
324 Use this routine to release the return data space allocated by the function
325 Wiz_UnzipToMemory().
326
327 int 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
350 There 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
352 itself in several places. This call is currently only available in the
353 static library, not in the DLL.
354
355 Match the pattern (wildcard) against the string (fixed):
356
357 match(const char *string, const char *pattern, int ignore_case);
358
359 or, 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
385 The remaining functions are linked together. Their use would be as
386 follows (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
416 Each 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
424 Note that you should use either Wiz_SingleEntryUnzip OR the series of calls
425 described above. Using both, depending on how you do it, could cause
426 problems. The series of "lower level" gives you more freedom to add additional
427 functionalities, whereas the single-entry api is easier to use. When using
428 the "series" of calls, make sure that Wiz_SetOpts and Wiz_Unzip are always
429 used together! When successfully called, Wiz_SetOpts has allocated some
430 internal structures which are in turn free'd by Wiz_Unzip.
431
432 Last revised January 18, 2009.
433
434 Mike White, Christian Spieler