home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 9 Archive / 09-Archive.zip / unzip531.zip / windll / windll.doc < prev    next >
Text File  |  1997-05-30  |  9KB  |  209 lines
  1. The code set out below is not intended to be compiled, but is only intended
  2. as a very simplistic pointer to how to load and call the dll. You will have
  3. to look in the files referenced below for actual, working code.
  4.  
  5. There are now five entry points to the dll.
  6.  
  7. There is a single "unzipping" entry point of:
  8.  
  9. windll_unzip(int argc, char **argv, DCL far*lpDCL,
  10.      USERFUNCTIONS far *lpUserFunc)
  11.  
  12. where the arguments are:
  13.  
  14. argc       = number of file names being passed. If all files are to be
  15.              extracted, then this can be zero.
  16. argv       = file names to be unarchived. If all files are to be extracted,
  17.              then this can be null.
  18. lpDCL      = pointer to a structure with the flags for setting the
  19.              various options, as well as the zip file name.
  20. lpUserFunc = pointer to a structure that contains pointers to functions
  21.              in the calling application, as well as sizes passed back to
  22.              the calling application etc. See below for a detailed description
  23.              of all the parameters
  24.  
  25. The DCL structure is shown below:
  26.  
  27. typedef struct {
  28. int ExtractOnlyNewer;   = true if you are to extract only newer
  29. int Overwrite;          = true if always overwrite files
  30. int SpaceToUnderscore;  = true if convert space to underscore
  31. int PromptToOverwrite;  = true if prompt to overwrite is wanted
  32. int ncflag              = write to stdout if true
  33. int ntflag              = test zip file
  34. int nvflag              = verbose listing
  35. int nUflag              = "update" (extract only newer/new files
  36. int nzflag              = display zip file comment
  37. int ndflag              = all args are files/dir to be extracted
  38. int noflag              = true if you are to over-write files, false if not
  39. int naflag              = do ASCII-EBCDIC and/or end of line translation
  40. int fPrivilege          = 1 => restore Acl's, 2 => Use privileges
  41. LPSTR lpszZipFN         = zip file name
  42. } DCL, _far *LPDCL;
  43.  
  44. The typedef's for the function pointers in the structure USERFUNCTIONS
  45. are shown immediately below.
  46.  
  47. typedef unsigned short ush;
  48. typedef int (WINAPI DLLPRNT) (char * far, unsigned long);
  49. typedef int (WINAPI DLLPASSWORD) (char *, int, const char *, const char *);
  50. typedef void (WINAPI DLLSND) (void);
  51. typedef int (WINAPI DLLREPLACE)(char *);
  52. typedef void (WINAPI DLLMESSAGE)(unsigned long, unsigned long,
  53.    ush, ush, ush, ush, ush, ush, char, char *, char *, unsigned long, char);
  54.  
  55. Structure USERFUNCTIONS
  56.  
  57. typedef struct {
  58. DLLPRNT *print;         = a pointer to the application's print routine.
  59. DLLSND *sound;          = a pointer to the application's sound routine. This
  60.                           can be NULL if your application doesn't use
  61.                           sound.
  62. DLLREPLACE *replace     = a pointer to the application's replace routine.
  63. DLLPASSWORD *password   = a pointer to the application's password routine.
  64. DLLMESSAGE *SendApplicationMessage = a pointer to the application's routine
  65.                           for displaying information about specific files
  66.                           in the archive. Used for listing the contents of
  67.                           an archive.
  68. WORD cchComment;        = flag to be set if archive has a comment
  69. unsigned long TotalSizeComp = value to be filled in by the dll for the
  70.                           compressed total size of the archive. Note this
  71.                           value does not include the size of the archive
  72.                           header and central directory list.
  73. unsigned long TotalSize = value to be filled in by the dll for the total
  74.                           size of all files in the archive.
  75. int CompFactor          = value to be filled in by the dll for the overall
  76.                           compression factor. This could actually be computed
  77.                           from the other values, but it is available.
  78. unsigned int NumMembers = total number of files in the archive.
  79. } USERFUNCTIONS, far * LPUSERFUNCTIONS;
  80.  
  81. For examples of how the actual calls to the dll are set up in WiZ, look in
  82. the files action.c and wizmain.c in the WiZ source directory. For a trival
  83. example of how to load and call the dll, look in example.c and example.h.
  84.  
  85. For examples of how the actual loading and unloading of the dll's themselves
  86. was done, look in wizmain.c in the WiZ source directory. Note that WiZ looks
  87. specifically for a particular version number of the dll, and also expects to
  88. find the company name to be Info-ZIP. This is to protect from getting
  89. different versions of the dll loaded, with resulting unknown behavior.
  90.  
  91. There is also a second "single" entry point that was designed for use with
  92. Visual Basic (and can possibly be used with Delphi also.) NOTE THAT THIS
  93. ENTRY POINT HAS NOT BEEN ACTUALLY TESTED WITH VISUAL BASIC. It has been
  94. tested with 'C', and works, but I do not have access to Visual Basic, and
  95. am not a Visual Basic programmer. If you are trying to use this entry point
  96. with Visual Basic, you are on your own. I have no idea how to call this
  97. from Visual Basic.
  98.  
  99. int WINAPI unzipVB(int argc, char **argv, DCL far *lpDCL,
  100.    VBUSERFUNCTIONS far *lpUF)
  101.  
  102. where the arguments are:
  103.  
  104. argc       = number of file names being passed
  105. argv       = file names to be unarchived
  106. lpDCL      = pointer to a structure with the flags for setting the
  107.              various options, as well as the zip file name.
  108. lpUF       = pointer to a structure that contains pointers to functions
  109.              in the calling application.
  110.  
  111. The DCL structure is shown above.
  112.  
  113. The VBUSERFUNCTION structure is as shown below:
  114.  
  115. typedef struct {
  116. HINSTANCE hInstance;    = The instance of the calling application.
  117. char print[80];         = A string containing the name of the calling
  118.                           application's print routine.
  119. char sound[80];         = A string containing the name of the calling
  120.                           application's sound routine.
  121. char replace[80];       = A string containing the name of the calling
  122.                           application's rename/replace routine.
  123. char password[80];      = A string containing the name of the calling
  124.                           application's password routine.
  125. char SendApplicationMessage[80]; = A string containing the name of the calling
  126.                           application's routine for displaying information
  127.                           about specific files in the archive. Used for
  128.                           listing the contents of an archive.
  129. WORD cchComment;        = flag to be set if archive has a comment
  130. unsigned long TotalSizeComp = value to be filled in by the dll for the
  131.                           compressed total size of the archive. Note this
  132.                           value does not include the size of the archive
  133.                           header and central directory list.
  134. unsigned long TotalSize = value to be filled in by the dll for the total
  135.                           size of all files in the archive.
  136. int CompFactor          = value to be filled in by the dll for the overall
  137.                           compression factor. This could actually be computed
  138.                           from the other values, but it is available.
  139. unsigned int NumMembers = total number of files in the archive.
  140. } VBUSERFUNCTIONS, far * LPVBUSERFUNCTIONS;
  141.  
  142. NOTE: The calling application must export (make available to the dll) the
  143.       routines for print, sound, replace and SendApplicationMessage.
  144.  
  145. There are four additional entry points:
  146.  
  147.     UzpVersion:
  148.  
  149.     UzpVer * UzpVersion(void);
  150.  
  151. where UzpVer is defined as:
  152.  
  153. typedef struct _UzpVer {
  154.     ulg structlen;          /* length of the struct being passed */
  155.     ulg flag;               /* bit 0: is_beta   bit 1: uses_zlib */
  156.     char *betalevel;        /* e.g., "g BETA" or "" */
  157.     char *date;             /* e.g., "4 Sep 95" (beta) or "4 September 1995" */
  158.     char *zlib_version;     /* e.g., "1.0.5" or NULL */
  159.     _version_type unzip;
  160.     _version_type zipinfo;
  161.     _version_type os2dll;
  162.     _version_type windll;
  163. } UzpVer;
  164.  
  165. See api.c for exactly what UzpVersion does, but the short version of
  166. what it does is return the unzip and dll versions in the UzpVer structure.
  167.  
  168. The remaining five functions are linked together. Their use would be as
  169. follows (explanations of each function is shown further below):
  170.  
  171.     #include "windll.h"
  172.     MyApiCallingRoutine()
  173.     {
  174.         CREATEGLOBALS();
  175.         .
  176.         .
  177.         .
  178.         Unz_Init(UzpGlobals, lpUserFunctions); /* Set up user functions */
  179.         .
  180.         .
  181.         .
  182.         Unz_SetOpts(UzpGlobals, lpDCL); /* Set up unzipping options */
  183.         .
  184.         .
  185.         .
  186.         Unz_Unzip(UzpGlobals, argc, argv); /* Unzip files */
  187.         .
  188.         .
  189.         .
  190.         DESTROYGLOBALS();
  191.     }
  192.  
  193. Each entry point is as defined below:
  194.  
  195.     BOOL WINAPI Unz_Init(zvoid *, USERFUNCTIONS far *);
  196.  
  197.     BOOL WINAPI Unz_SetOpts(zvoid *, LPDCL);
  198.  
  199.     int WINAPI Unz_Unzip(zvoid *, int, char **);
  200.  
  201. Note that you should use either windll_unzip OR the series of calls
  202. described above. Using both, depending on how you do it, could cause
  203. problems.
  204.  
  205. Last revised May 30, 1997.
  206.  
  207. Mike White
  208.  
  209.