info_zip windll.txt 的翻译
自己用的，有人用的着也是好事一件：
- 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.
- //正被解压的文件名个数，如果需解压所有文件，可设这个参数为0。
- ifnv = file names to be unarchived. Wildcard patterns are recognized
- and expanded. If all files are to be extracted, then this can
- be NULL.
- //解压的文件名，可使用通配符。如果需解压所有文件，可设这个参数为NULL。
- xfnc = number of "file names to be excluded from processing" being
- passed. If all files are to be extracted, set this to zero.
- //“没有被处理的文件名”个数。如果需解压所有文件，可设这个参数为0。
- 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.
- //不被解压处理的文件名，可使用通配符。如果需解压所有文件，可设这个参数为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
- // 安静模式：0 = 所有信息, 1 = 很少信息, 2 = 没有信息
- int ncflag = write to stdout if true //写入标准控制台
- int ntflag = test zip file //测试zip文件
- int nvflag = verbose listing //冗长的监听
- int nfflag = "freshen" (replace existing files by newer versions)
- //“更新的”（用新的代替旧的文件）
- int nzflag = display zip file comment显示zip文件注释
- 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)
- //控制解压过程中（子）路径的重新创建
- //0 = 从文件名中忽略路径
- //1 = 文件名中的有效路径 (跳过 "../")
- //2 = 允许非安全路径 (目录遍历)
- int noflag = true if you are to always overwrite existing files
- //总是覆盖已存在文件
- int naflag = do end-of-line translation //进行行尾标识符转换
- int nZIflag = get ZipInfo if TRUE //获取ZipInfo
- int C_flag = be case insensitive if TRUE //区分大小写
- int fPrivilege = 1 => restore ACLs in user mode, //在用户模式下恢复ACLs
- 2 => try to use privileges for restoring ACLs
- //尝试使用的特权，恢复ACL
- LPSTR lpszZipFN = zip file name //zip文件名
- LPSTR lpszExtractDir = directory to extract to. This should be NULL if you
- are extracting to the current directory.
- //解压路径，如果您是提取到当前目录，就设为NUll。
- } 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:
- //ExtractOnlyNewer, nfflag, PromptToOverwrite, noflag 四个标志控制文档的实际处理
- //过程，和UnZip命令行的对应关系见下面的决策矩阵：
- _____________________________________________________________________
- | 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:
- //queryfunc()是由unzip dll的调用者提供的回调函数，它可能返回下面的值：
- 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.
- //在USERFUNCTIONS中的函数指针的宏定义如下：
- 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.
- //指向声音的应用程序的例行函数。如果应用程序不使用声音，
- //可以设为NULL。
- 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.
- //这个回调函数设计的目的是为了处理或者撤消处理给
- //定标识的Windows消息，如果这个函数返回的是个非0值，
- //那么它会终止它所做的事情，它提供程序已经处理的文档名称
- //以及它的原始大小。
- 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.
- //dll将填充这个值，这个值代表压缩后的文档总大小。注意，
- //这个值不包括文档头和里面目录的大小。
- unsigned long TotalSize = value to be filled in by the dll for the total
- size of all files in the archive.
- //dll将填充这个值，这个值代表整个文档的大小。
- 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.
- //dll将填充这个值，这个值代表压缩比。实际上它可以从其它
- //值计算出来，但这个是可信的。
- 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).
- //Wiz_SingleEntryUnzip() 返回一个与PKWARE兼容的错误代码（如果没有错误或警告它将是0）
- 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.
- //关于怎样调用和设置WIZ的实际过程，请参考WiZ源目录下的 action.c 和 wizmain.c ，
- //一个简单的例子关于怎样加载和调用这个DLL，请参见uzexampl.c 和 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.
- //传入压缩文件名和你希望解压的文件。Wiz_UnzipToMemory将创建一个缓存并通过*retstr返回。
- //如果失败将返回0。
- void WINAPI UzpFreeMemBuffer(UzpBuffer *retstr)
- Use this routine to release the return data space allocated by the function
- Wiz_UnzipToMemory().
- //释放 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:
- //传入zip文件中的文档名，待搜索的zip名，查找的字符串和下面的四个选项：
- 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.
- //这里有一个额外的函数，它不用于处理“解压”工作。但是却相当的有用，它在Wiz中的
- //许多地方被用到。它只能在静态库中有用。
- 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.
- //注意，你应该使用Wiz_SingleEntryUnzip或上面描述的一系列函数。同时使用
- //（看你怎么用），可能会引发问题。较低级别的函数给你更大的自由，你可以添加额外的
- //函数。与此相比single-entry api更加容易使用。当你使用上面的一系列函数时，注意要
- //让Wiz_SetOpts 和 Wiz_Unzip一起使用！当调用成功，Wiz_Unzip将释放Wiz_SetOpts已经
- //分配的内部结构。
- Last revised February 27, 2005.
- Mike White, Christian Spieler