0,0 → 1,434 |
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: |
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 = 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 |
0 = restore all timestamps (default) |
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 |
0 = automatic UTF-8 translation enabled (default) |
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: |
|
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(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 |