home *** CD-ROM | disk | FTP | other *** search
/ PC Online 1997 May / PCO_5_97.ISO / FilesBBS / WIN95 / WINRAR.ARJ / UnRARDLL.Txt < prev   
Encoding:
Text File  |  1996-06-26  |  13.0 KB  |  434 lines
  1.  
  2.  ██████╗   █████╗  ██████╗      unRAR.dll Manual
  3.  ██╔══██╗ ██╔══██╗ ██╔══██╗     ~~~~~~~~~~~~~~~~
  4.  ██████╔╝ ███████║ ██████╔╝     RAR 2.00 for Windows
  5.  ██╔══██╗ ██╔══██║ ██╔══██╗     ~~~~~~~~~~~~~~~~~~~~
  6.  ██║  ██║ ██║  ██║ ██║  ██║     Multifunctional Integrated Archive Manager
  7.  ╚═╝  ╚═╝ ╚═╝  ╚═╝ ╚═╝  ╚═╝     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  8.  
  9.     UNRAR.DLL is a 32-bit Windows dynamic-link library which provides file
  10.  extraction from RAR archives. It handles archives created with RAR 2.0
  11.  only and cannot extract files from archives of previous versions of RAR.
  12.  
  13.  
  14.     Exported functions
  15.  
  16. ====================================================================
  17. HANDLE PASCAL RAROpenArchive(struct RAROpenArchiveData *ArchiveData)
  18. ====================================================================
  19.  
  20. Description
  21. ~~~~~~~~~~~
  22.   Open RAR archive and allocate memory structures (about 1 Mb)
  23.  
  24. Parameters
  25. ~~~~~~~~~~
  26. ArchiveData       Points to RAROpenArchiveData structure
  27.  
  28. struct RAROpenArchiveData
  29. {
  30.   char *ArcName;
  31.   UINT OpenMode;
  32.   UINT OpenResult;
  33.   char *CmtBuf;
  34.   UINT CmtBufSize;
  35.   UINT CmtSize;
  36.   UINT CmtState;
  37. };
  38.  
  39. Structure fields:
  40.  
  41. ArcName
  42.   Input parameter which should point to a, zero terminated string 
  43.   containing the archive name. 
  44.  
  45. OpenMode
  46.   Input parameter.
  47.  
  48.   Possible values
  49.  
  50.   RAR_OM_LIST           Open archive for reading file headers only
  51.   RAR_OM_EXTRACT        Open archive for testing and extracting files
  52.  
  53. OpenResult
  54.   Output parameter.
  55.  
  56.   Possible values
  57.  
  58.   0                     Success
  59.   ERAR_NO_MEMORY        Not enough memory to initialize data structures
  60.   ERAR_BAD_DATA         Archive header broken
  61.   ERAR_BAD_ARCHIVE      File is not valid RAR archive
  62.   ERAR_EOPEN            File open error
  63.  
  64. CmtBuf
  65.   Input parameter which should point to the buffer for archive 
  66.   comments. Maximum comment size is limited to 64Kb. Comment text is 
  67.   zero terminated. If the comment text is larger than the buffer 
  68.   size, the comment text will be truncated. If CmtBuf is set to 
  69.   NULL, comments will not be read. 
  70.  
  71. CmtBufSize
  72.   Input parameter which should contain size of buffer for archive
  73.   comments.
  74.  
  75. CmtSize
  76.   Output parameter containing size of comments actually read into the
  77.   buffer, cannot exceed CmtBufSize.
  78.  
  79. CmtState
  80.   Output parameter.
  81.  
  82.   Possible values
  83.  
  84.   0                     comments not present
  85.   1                     Comments read completely
  86.   ERAR_NO_MEMORY        Not enough memory to extract comments
  87.   ERAR_BAD_DATA         Broken comment
  88.   ERAR_UNKNOWN_FORMAT   Unknown comment format
  89.   ERAR_SMALL_BUF        Buffer too small, comments not completely read
  90.  
  91. Return values
  92. ~~~~~~~~~~~~~
  93.   Archive handle or NULL in case of error
  94.  
  95.  
  96. ====================================================================
  97. int PASCAL RARCloseArchive(HANDLE hArcData)
  98. ====================================================================
  99.  
  100. Description
  101. ~~~~~~~~~~~
  102.   Close RAR archive and release allocated memory. It must be called when
  103.   archive processing is finished, even if the archive processing was stopped
  104.   due to an error.
  105.  
  106. Parameters
  107. ~~~~~~~~~~
  108. hArcData
  109.   This parameter should contain the archive handle obtained from the
  110.   RAROpenArchive function call.
  111.  
  112. Return values
  113. ~~~~~~~~~~~~~
  114.   0                     Success
  115.   ERAR_ECLOSE           Archive close error
  116.  
  117.  
  118. ====================================================================
  119. int PASCAL RARReadHeader(HANDLE hArcData,
  120.                          struct RARHeaderData *HeaderData)
  121. ====================================================================
  122.  
  123. Description
  124. ~~~~~~~~~~~
  125.   Read header of file in archive.
  126.  
  127. Parameters
  128. ~~~~~~~~~~
  129. hArcData
  130.   This parameter should contain the archive handle obtained from the
  131.   RAROpenArchive function call.
  132.  
  133. HeaderData
  134.   It should point to RARHeaderData structure:
  135.  
  136. struct RARHeaderData
  137. {
  138.   char ArcName[260];
  139.   char FileName[260];
  140.   UINT Flags;
  141.   UINT PackSize;
  142.   UINT UnpSize;
  143.   UINT HostOS;
  144.   UINT FileCRC;
  145.   UINT FileTime;
  146.   UINT UnpVer;
  147.   UINT Method;
  148.   UINT FileAttr;
  149.   char *CmtBuf;
  150.   UINT CmtBufSize;
  151.   UINT CmtSize;
  152.   UINT CmtState;
  153. };
  154.  
  155. Structure fields:
  156.  
  157. ArcName
  158.   Output parameter which contains a zero terminated string of the
  159.   current archive name.  May be used to determine the current volume 
  160.   name. 
  161.  
  162. FileName
  163.   Output parameter which contains a zero terminated string of the 
  164.   file name. 
  165.  
  166. Flags
  167.   Output parameter which contains file flags:
  168.  
  169.   0x01 - file continued from previous volume
  170.   0x02 - file continued on next volume
  171.   0x04 - file encrypted with password
  172.   0x08 - file comment present
  173.   0x10 - compression of previous files is used (solid flag)
  174.  
  175.   bits 7 6 5
  176.  
  177.        0 0 0    - dictionary size   64 Kb
  178.        0 0 1    - dictionary size  128 Kb
  179.        0 1 0    - dictionary size  256 Kb
  180.        0 1 1    - dictionary size  512 Kb
  181.        1 0 0    - dictionary size 1024 Kb
  182.        1 0 1    - reserved
  183.        1 1 0    - reserved
  184.        1 1 1    - file is directory
  185.  
  186.   Other bits are reserved.
  187.  
  188. PackSize
  189.   Output parameter means packed file size or size of the
  190.   file part if file was split between volumes.
  191.  
  192. UnpSize
  193.   Output parameter - unpacked file size.
  194.  
  195. HostOS
  196.   Output parameter - operating system used for archiving:
  197.  
  198.   0 - MS DOS;
  199.   1 - OS/2.
  200.   2 - Win32
  201.   3 - Unix
  202.  
  203. FileCRC
  204.   Output parameter which contains unpacked file CRC. It should not be
  205.   used for file parts which were split between volumes.
  206.  
  207. FileTime
  208.   Output parameter - contains date and time in standard MS DOS format.
  209.  
  210. UnpVer
  211.   Output parameter - RAR version needed to extract file.
  212.   It is encoded as 10 * Major version + minor version.
  213.  
  214. Method
  215.   Output parameter - packing method.
  216.  
  217. FileAttr
  218.   Output parameter - file attributes.
  219.  
  220. CmtBuf
  221.   Input parameter which should point to the buffer for archive 
  222.   comments. Maximum comment size is limited to 64Kb. Comment text is 
  223.   a zero terminated string.  If the comment text is larger than the 
  224.   buffer size, the comment text will be truncated. If CmtBuf is set 
  225.   to NULL, comments will not be read. 
  226.  
  227. CmtBufSize
  228.   Input parameter which should contain size of buffer for archive
  229.   comments.
  230.  
  231. CmtSize
  232.   Output parameter containing size of comments actually read into the
  233.   buffer, should not exceed CmtBufSize.
  234.  
  235. CmtState
  236.   Output parameter.
  237.  
  238.   Possible values
  239.  
  240.   0                     Absent comments
  241.   1                     Comments read completely
  242.   ERAR_NO_MEMORY        Not enough memory to extract comments
  243.   ERAR_BAD_DATA         Broken comment
  244.   ERAR_UNKNOWN_FORMAT   Unknown comment format
  245.   ERAR_SMALL_BUF        Buffer too small, comments not completely read
  246.  
  247. Return values
  248. ~~~~~~~~~~~~~
  249.  
  250.   0                     Success
  251.   ERAR_END_ARCHIVE      End of archive
  252.   ERAR_BAD_DATA         File header broken
  253.  
  254.  
  255. ====================================================================
  256. int PASCAL RARProcessFile(HANDLE hArcData,
  257.                           int Operation,
  258.                           char *DestPath,
  259.                           char *DestName)
  260. ====================================================================
  261.  
  262. Description
  263. ~~~~~~~~~~~
  264.   Performs action and moves the current position in the archive to 
  265.   the next file. Extract or test the current file from the archive 
  266.   opened in RAR_OM_EXTRACT mode. If the mode RAR_OM_LIST is set, 
  267.   then a call to this function will simply skip the archive position 
  268.   to the next file. 
  269.  
  270. Parameters
  271. ~~~~~~~~~~
  272. hArcData
  273.   This parameter should contain the archive handle obtained from the
  274.   RAROpenArchive function call.
  275.  
  276. Operation
  277.   File operation.
  278.  
  279.   Possible values
  280.  
  281.   RAR_SKIP              Move to the next file in the archive. If the 
  282.                         archive is solid and RAR_OM_EXTRACT mode was set 
  283.                         when the archive was opened, the current file will 
  284.                         be processed - the operation will be performed 
  285.                         slower than a simple seek. 
  286.  
  287.   RAR_TEST              Test the current file and move to the next file in 
  288.                         the archive. If the archive was opened with 
  289.                         RAR_OM_LIST mode, the operation is equal to 
  290.                         RAR_SKIP. 
  291.  
  292.   RAR_EXTRACT           Extract the current file and move to the next file.
  293.                         If the archive was opened with RAR_OM_LIST mode,
  294.                         the operation is equal to RAR_SKIP.
  295.  
  296.  
  297. DestPath
  298.   This parameter should point to a zero terminated string containing the 
  299.   destination directory to which to extract files to. If DestPath is equal 
  300.   to NULL it means extract to the current directory. This parameter has 
  301.   meaning only if DestName is NULL. 
  302.  
  303. DestName
  304.   This parameter should point to a string containing the full path and name
  305.   of the file to be extracted or NULL as default. If DestName is defined
  306.   (not NULL) it overrides the original file name saved in the archive and 
  307.   DestPath setting. 
  308.  
  309. Return values
  310. ~~~~~~~~~~~~~
  311.   0                     Success
  312.   ERAR_BAD_DATA         File CRC error
  313.   ERAR_BAD_ARCHIVE      Volume is not valid RAR archive
  314.   ERAR_UNKNOWN_FORMAT   Unknown archive format
  315.   ERAR_EOPEN            Volume open error
  316.   ERAR_ECREATE          File create error
  317.   ERAR_ECLOSE           File close error
  318.   ERAR_EREAD            Read error
  319.   ERAR_EWRITE           Write error
  320.  
  321.  
  322. ====================================================================
  323. void PASCAL RARSetChangeVolProc(HANDLE hArcData,
  324.             int (*ChangeVolProc)(char *ArcName,int Mode));
  325. ====================================================================
  326.  
  327. Description
  328. ~~~~~~~~~~~
  329.   Set a user-defined function to process volume changing.
  330.  
  331. Parameters
  332. ~~~~~~~~~~
  333. hArcData
  334.   This parameter should contain the archive handle obtained from the
  335.   RAROpenArchive function call.
  336.  
  337. ChangeVolProc
  338.   It should point to a user-defined "volume change processing" function.
  339.  
  340.   The function will be passed two parameters:
  341.  
  342.   ArcName                Points to the zero terminated name
  343.                          of the next volume.
  344.  
  345.   Mode                   The function call mode.
  346.  
  347.     Possible values
  348.  
  349.     RAR_VOL_ASK          Required volume is absent. The function should
  350.                          prompt user and return a non-zero value
  351.                          to retry or return a zero value to terminate 
  352.                          operation. The function may also specify a new 
  353.                          volume name, placing it to the ArcName parameter. 
  354.  
  355.     RAR_VOL_NOTIFY       Required volume is successfully opened.
  356.                          This is a notification call and ArcName 
  357.                          modification is not allowed. The function should 
  358.                          return a non-zero value to continue or a zero 
  359.                          value to terminate operation. 
  360.  
  361.   Other functions of UNRAR.DLL should not be called from the
  362.   ChangeVolProc function.
  363.  
  364. Return values
  365. ~~~~~~~~~~~~~
  366.   None
  367.  
  368.  
  369. ====================================================================
  370. void PASCAL RARSetProcessDataProc(HANDLE hArcData,
  371.             int (*ProcessDataProc)(unsigned char *Addr,int Size))
  372. ====================================================================
  373.  
  374. Description
  375. ~~~~~~~~~~~
  376.   Set a user-defined function to process unpacked data. It may be used
  377.   to read a file while it is being extracted or tested without actual 
  378.   extracting file to disk.
  379.  
  380. Parameters
  381. ~~~~~~~~~~
  382. hArcData
  383.   This parameter should contain the archive handle obtained from the
  384.   RAROpenArchive function call.
  385.  
  386. ProcessDataProc
  387.   It should point to user-defined "data processing" function.
  388.  
  389.   The function is called each time when the next data portion is unpacked.
  390.   It will be passed two parameters.
  391.  
  392.   Addr                  The address pointing to the unpacked data. The 
  393.                         function may refer to the data but must not change 
  394.                         it.
  395.  
  396.   Size                  The size of the unpacked data. It is guaranteed only
  397.                         that the size will not exceed 1 Mb (1048576 bytes).
  398.                         Any other presumptions may not be correct for
  399.                         future implementations of UNRAR.DLL.
  400.  
  401.   The ProcessDataProc function should return a non-zero value to continue
  402.   process or a zero value to cancel the archive operation.
  403.  
  404.   Other functions of UNRAR.DLL should not be called from the
  405.   ProcessDataProc function.
  406.  
  407. Return values
  408. ~~~~~~~~~~~~~
  409.   None
  410.  
  411.  
  412. ====================================================================
  413. void PASCAL RARSetPassword(HANDLE hArcData,
  414.                            char *Password);
  415. ====================================================================
  416.  
  417. Description
  418. ~~~~~~~~~~~
  419.   Set a password to decrypt files.
  420.  
  421. Parameters
  422. ~~~~~~~~~~
  423. hArcData
  424.   This parameter should contain the archive handle obtained from the
  425.   RAROpenArchive function call.
  426.  
  427. Password
  428.   It should point to a string containing a zero terminated password.
  429.  
  430. Return values
  431. ~~~~~~~~~~~~~
  432.   None
  433.  
  434.