home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 9 Archive / 09-Archive.zip / unzip532.zip / windll / windll.doc < prev    next >
Text File  |  1997-10-31  |  10KB  |  238 lines
  1. There are now several entry points to the dll.
  2.  
  3. There is a single "unzipping" entry point of:
  4.  
  5. windll_unzip(int ifnc, char **ifnv, int xfnc, char **xfnv,
  6.      DCL far*lpDCL, USERFUNCTIONS far *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. The DCL structure is shown below:
  28.  
  29. typedef struct {
  30. int ExtractOnlyNewer;   = true if you are to extract only newer
  31. int SpaceToUnderscore;  = true if convert space to underscore
  32. int PromptToOverwrite;  = true if prompt to overwrite is wanted
  33. int fQuiet;             = quiet flag. 1 = few messages, 2 = no messages, 0 = all messages
  34. int ncflag              = write to stdout if true
  35. int ntflag              = test zip file
  36. int nvflag              = verbose listing
  37. int nUflag              = "update" (extract only newer/new files)
  38. int nzflag              = display zip file comment
  39. int ndflag              = all args are files/dir to be extracted
  40. int noflag              = true if you are to always over-write files, false if not
  41. int naflag              = do end-of-line translation
  42. int nZIflag;            = get zip info if true
  43. int C_flag;             = be case insensitive if TRUE
  44. int fPrivilege          = 1 => restore Acl's, 2 => Use privileges
  45. LPSTR lpszZipFN         = zip file name
  46. LPSTR lpszExtractDir    = Directory to extract to. This should be NULL if you
  47.                           are extracting to the current directory.
  48. } DCL, _far *LPDCL;
  49.  
  50. The typedef's for the function pointers in the structure USERFUNCTIONS
  51. are shown immediately below.
  52.  
  53. typedef unsigned short ush;
  54. typedef int (WINAPI DLLPRNT) (LPSTR, unsigned long);
  55. typedef int (WINAPI DLLPASSWORD) (LPSTR, int, const LPSTR, const LPSTR);
  56. typedef void (WINAPI DLLSND) (void);
  57. typedef int (WINAPI DLLREPLACE)(LPSTR);
  58. typedef void (WINAPI DLLMESSAGE)(unsigned long, unsigned long,
  59.    ush, ush, ush, ush, ush, ush, char, LPSTR, LPSTR, unsigned long, char);
  60.  
  61. Structure USERFUNCTIONS
  62.  
  63. typedef struct {
  64. DLLPRNT *print;         = a pointer to the application's print routine.
  65. DLLSND *sound;          = a pointer to the application's sound routine. This
  66.                           can be NULL if your application doesn't use
  67.                           sound.
  68. DLLREPLACE *replace     = a pointer to the application's replace routine.
  69. DLLPASSWORD *password   = a pointer to the application's password routine.
  70. DLLMESSAGE *SendApplicationMessage = a pointer to the application's routine
  71.                           for displaying information about specific files
  72.                           in the archive. Used for listing the contents of
  73.                           an archive.
  74. NOTE: The values below are filled in only when listing the contents of an
  75.       archive.
  76.  
  77. WORD cchComment;        = flag to be set if archive has a comment
  78. unsigned long TotalSizeComp = value to be filled in by the dll for the
  79.                           compressed total size of the archive. Note this
  80.                           value does not include the size of the archive
  81.                           header and central directory list.
  82. unsigned long TotalSize = value to be filled in by the dll for the total
  83.                           size of all files in the archive.
  84. int CompFactor          = value to be filled in by the dll for the overall
  85.                           compression factor. This could actually be computed
  86.                           from the other values, but it is available.
  87. unsigned int NumMembers = total number of files in the archive.
  88. } USERFUNCTIONS, far * LPUSERFUNCTIONS;
  89.  
  90. For examples of how the actual calls to the dll are set up in WiZ, look in
  91. the files action.c and wizmain.c in the WiZ source directory. For a trival
  92. example of how to load and call the dll, look in example.c and example.h.
  93.  
  94. For examples of how the actual loading and unloading of the dll's themselves
  95. was done, look in wizmain.c in the WiZ source directory. Note that WiZ looks
  96. specifically for a particular version number of the dll, and also expects to
  97. find the company name to be Info-ZIP. This is to protect from getting
  98. different versions of the dll loaded, with resulting unknown behavior.
  99.  
  100. Additional entry points:
  101.  
  102.     WINAPI UzpVersion2(UzpVer far *);
  103.  
  104. where UzpVer is defined as:
  105.  
  106. typedef struct _UzpVer {
  107.     ulg structlen;          /* length of the struct being passed */
  108.     ulg flag;               /* bit 0: is_beta   bit 1: uses_zlib */
  109.     LPSTR betalevel;        /* e.g., "g BETA" or "" */
  110.     LPSTR date;             /* e.g., "4 Sep 95" (beta) or "4 September 1995" */
  111.     LPSTR zlib_version;     /* e.g., "1.0.5" or NULL */
  112.     _version_type unzip;
  113.     _version_type zipinfo;
  114.     _version_type os2dll;
  115.     _version_type windll;
  116. } UzpVer;
  117.  
  118. and _version_type is defined as:
  119.  
  120. typedef struct _ver {
  121.     uch major;              /* e.g., integer 5 */
  122.     uch minor;              /* e.g., 2 */
  123.     uch patchlevel;         /* e.g., 0 */
  124.     uch not_used;
  125. } _version_type;
  126.  
  127.    See api.c for exactly what UzpVersion2 does, but the short version of
  128.    what it does is fill in the version information in the UzpVer structure.
  129.  
  130. void WINAPI Unz_NoPrinting(int flag)
  131.  
  132.    This entry point simply turns off all messages to the calling application if
  133.    flag is true, and turns them on if flag is false.
  134.  
  135. int WINAPI Unz_Validate(LPSTR archive, int AllCodes)
  136.  
  137.    If AllCodes is FALSE, then Unz_Validate returns TRUE if archive points to a
  138.    valid archive, and FALSE otherwise. If AllCodes is TRUE, then Unz_Validate
  139.    returns whatever error code process_zipfiles returns, without evaluating it.
  140.  
  141. int UZ_EXP UzpUnzipToMemory(char *zip, char *file, UzpBuffer *retstr)
  142.  
  143.    Where UzpBuffer is defined as:
  144.  
  145.    typedef struct _UzpBuffer {
  146.    ulg strlength; /* length of string */
  147.    char * strptr; /* pointer to string */
  148.    } UzpBuffer
  149.  
  150.    Pass the name of the zip file in zip and the name of the file you wish to
  151.    extract in file. UzpUnzipToMemory will create a buffer and return it in
  152.    *retstr. 0 on return indicates failure.
  153.  
  154. int UZ_EXP Unz_Grep(char *zip, char *file, char * pattern, int code)
  155.  
  156.    Pass the name of the zip file in "zip", the name of the file you wish to
  157.    perform the "grep" on in "file", and the string you wish to look for in
  158.    "pattern". There are four possible options for code:
  159.  
  160.    0 => case insensitive search
  161.    1 => case sensitive search
  162.    2 => case insensitive search, whole words only
  163.    3 => case sensitive search, whole words only
  164.  
  165.    Unz_Grep returns:
  166.  
  167.    -1 => error such as unable to allocate memory, unable to find file, etc.
  168.     0 => match not found, based on the search criteria
  169.     1 => match found, based on the search criteria
  170.  
  171. There is an additional function call that does not specifically deal with
  172. "unzipping", but is a quite useful function that is currently used in Wiz
  173. itself in several places. This call is currently only available in the
  174. static library, not in the DLL.
  175.  
  176. Match the pattern (wildcard) against the string (fixed):
  177.  
  178.   match(string, pattern, ignore_case);
  179.  
  180.   returns TRUE if string matches pattern, FALSE otherwise.  In the pattern:
  181.  
  182.      `*' matches any sequence of characters (zero or more)
  183.      `?' matches any single character
  184.      [SET] matches any character in the specified set,
  185.      [!SET] or [^SET] matches any character not in the specified set.
  186.  
  187.   A set is composed of characters or ranges; a range looks like ``character
  188.   hyphen character'' (as in 0-9 or A-Z).  [0-9a-zA-Z_] is the minimal set of
  189.   characters allowed in the [..] pattern construct.  Other characters are
  190.   allowed (i.e., 8-bit characters) if your system will support them.
  191.  
  192.   To suppress the special syntactic significance of any of ``[]*?!^-\'', in-
  193.   side or outside a [..] construct, and match the character exactly, precede
  194.   it with a ``\'' (backslash).
  195.  
  196. The remaining functions are linked together. Their use would be as
  197. follows (explanations for each function are shown further below):
  198.  
  199.     #include "windll.h"
  200.     #include "structs.h"
  201.     MyApiCallingRoutine()
  202.     {
  203.         CREATEGLOBALS();
  204.         .
  205.         .
  206.         .
  207.         Unz_Init(UzpGlobals, lpUserFunctions); /* Set up user functions */
  208.         .
  209.         .
  210.         .
  211.         Unz_SetOpts(UzpGlobals, lpDCL); /* Set up unzipping options */
  212.         .
  213.         .
  214.         .
  215.         Unz_Unzip(UzpGlobals, ifnc, ifnv, xfnc, xfnv); /* Unzip files */
  216.         .
  217.         .
  218.         .
  219.         DESTROYGLOBALS();
  220.     }
  221.  
  222. Each entry point is as defined below:
  223.  
  224.     BOOL WINAPI Unz_Init(zvoid *, USERFUNCTIONS far *);
  225.  
  226.     BOOL WINAPI Unz_SetOpts(zvoid *, LPDCL);
  227.  
  228.     int WINAPI Unz_Unzip(zvoid *, int, char **, int, char **);
  229.  
  230. Note that you should use either windll_unzip OR the series of calls
  231. described above. Using both, depending on how you do it, could cause
  232. problems.
  233.  
  234. Last revised October 22, 1997.
  235.  
  236. Mike White
  237.  
  238.