home *** CD-ROM | disk | FTP | other *** search
/ ftp.rarlab.com / 2014.05.ftp.rarlab.com.tar / ftp.rarlab.com / rar / unrar343.zip / UNRARDLL.TXT < prev    next >
Text File  |  2003-06-12  |  18KB  |  581 lines
  1.  
  2.     unRAR.dll Manual
  3.     ~~~~~~~~~~~~~~~~
  4.  
  5.     UNRAR.DLL is a 32-bit Windows dynamic-link library which provides
  6.  file extraction from RAR archives.
  7.  
  8.  
  9.     Exported functions
  10.  
  11. ====================================================================
  12. HANDLE PASCAL RAROpenArchive(struct RAROpenArchiveData *ArchiveData)
  13. ====================================================================
  14.  
  15. Description
  16. ~~~~~~~~~~~
  17.   Open RAR archive and allocate memory structures
  18.  
  19. Parameters
  20. ~~~~~~~~~~
  21. ArchiveData       Points to RAROpenArchiveData structure
  22.  
  23. struct RAROpenArchiveData
  24. {
  25.   char *ArcName;
  26.   UINT OpenMode;
  27.   UINT OpenResult;
  28.   char *CmtBuf;
  29.   UINT CmtBufSize;
  30.   UINT CmtSize;
  31.   UINT CmtState;
  32. };
  33.  
  34. Structure fields:
  35.  
  36. ArcName
  37.   Input parameter which should point to zero terminated string 
  38.   containing the archive name. 
  39.  
  40. OpenMode
  41.   Input parameter.
  42.  
  43.   Possible values
  44.  
  45.   RAR_OM_LIST           Open archive for reading file headers only
  46.   RAR_OM_EXTRACT        Open archive for testing and extracting files
  47.  
  48. OpenResult
  49.   Output parameter.
  50.  
  51.   Possible values
  52.  
  53.   0                     Success
  54.   ERAR_NO_MEMORY        Not enough memory to initialize data structures
  55.   ERAR_BAD_DATA         Archive header broken
  56.   ERAR_BAD_ARCHIVE      File is not valid RAR archive
  57.   ERAR_EOPEN            File open error
  58.  
  59. CmtBuf
  60.   Input parameter which should point to the buffer for archive 
  61.   comments. Maximum comment size is limited to 64Kb. Comment text is 
  62.   zero terminated. If the comment text is larger than the buffer 
  63.   size, the comment text will be truncated. If CmtBuf is set to 
  64.   NULL, comments will not be read. 
  65.  
  66. CmtBufSize
  67.   Input parameter which should contain size of buffer for archive
  68.   comments.
  69.  
  70. CmtSize
  71.   Output parameter containing size of comments actually read into the
  72.   buffer, cannot exceed CmtBufSize.
  73.  
  74. CmtState
  75.   Output parameter.
  76.  
  77.   Possible values
  78.  
  79.   0                     comments not present
  80.   1                     Comments read completely
  81.   ERAR_NO_MEMORY        Not enough memory to extract comments
  82.   ERAR_BAD_DATA         Broken comment
  83.   ERAR_UNKNOWN_FORMAT   Unknown comment format
  84.   ERAR_SMALL_BUF        Buffer too small, comments not completely read
  85.  
  86. Return values
  87. ~~~~~~~~~~~~~
  88.   Archive handle or NULL in case of error
  89.  
  90.  
  91. ========================================================================
  92. HANDLE PASCAL RAROpenArchiveEx(struct RAROpenArchiveDataEx *ArchiveData)
  93. ========================================================================
  94.  
  95. Description
  96. ~~~~~~~~~~~
  97.   Similar to RAROpenArchive, but uses RAROpenArchiveDataEx structure
  98.   allowing to specify Unicode archive name and returning information
  99.   about archive flags.
  100.  
  101. Parameters
  102. ~~~~~~~~~~
  103. ArchiveData       Points to RAROpenArchiveDataEx structure
  104.  
  105. struct RAROpenArchiveDataEx
  106. {
  107.   char         *ArcName;
  108.   wchar_t      *ArcNameW;
  109.   unsigned int OpenMode;
  110.   unsigned int OpenResult;
  111.   char         *CmtBuf;
  112.   unsigned int CmtBufSize;
  113.   unsigned int CmtSize;
  114.   unsigned int CmtState;
  115.   unsigned int Flags;
  116.   unsigned int Reserved[32];
  117. };
  118.  
  119. Structure fields:
  120.  
  121. ArcNameW
  122.   Input parameter which should point to zero terminated Unicode string
  123.   containing the archive name or NULL if Unicode name is not specified.
  124.  
  125. Flags
  126.   Output parameter. Combination of bit flags.
  127.  
  128.   Possible values
  129.  
  130.     0x0001  - Volume attribute (archive volume)
  131.     0x0002  - Archive comment present
  132.     0x0004  - Archive lock attribute
  133.     0x0008  - Solid attribute (solid archive)
  134.     0x0010  - New volume naming scheme ('volname.partN.rar')
  135.     0x0020  - Authenticity information present
  136.     0x0040  - Recovery record present
  137.     0x0080  - Block headers are encrypted
  138.     0x0100  - First volume (set only by RAR 3.0 and later)
  139.  
  140. Reserved[32]
  141.   Reserved for future use. Must be zero.
  142.  
  143. Information on other structure fields and function return values
  144. is available above, in RAROpenArchive function description.
  145.  
  146.  
  147. ====================================================================
  148. int PASCAL RARCloseArchive(HANDLE hArcData)
  149. ====================================================================
  150.  
  151. Description
  152. ~~~~~~~~~~~
  153.   Close RAR archive and release allocated memory. It must be called when
  154.   archive processing is finished, even if the archive processing was stopped
  155.   due to an error.
  156.  
  157. Parameters
  158. ~~~~~~~~~~
  159. hArcData
  160.   This parameter should contain the archive handle obtained from the
  161.   RAROpenArchive function call.
  162.  
  163. Return values
  164. ~~~~~~~~~~~~~
  165.   0                     Success
  166.   ERAR_ECLOSE           Archive close error
  167.  
  168.  
  169. ====================================================================
  170. int PASCAL RARReadHeader(HANDLE hArcData,
  171.                          struct RARHeaderData *HeaderData)
  172. ====================================================================
  173.  
  174. Description
  175. ~~~~~~~~~~~
  176.   Read header of file in archive.
  177.  
  178. Parameters
  179. ~~~~~~~~~~
  180. hArcData
  181.   This parameter should contain the archive handle obtained from the
  182.   RAROpenArchive function call.
  183.  
  184. HeaderData
  185.   It should point to RARHeaderData structure:
  186.  
  187. struct RARHeaderData
  188. {
  189.   char ArcName[260];
  190.   char FileName[260];
  191.   UINT Flags;
  192.   UINT PackSize;
  193.   UINT UnpSize;
  194.   UINT HostOS;
  195.   UINT FileCRC;
  196.   UINT FileTime;
  197.   UINT UnpVer;
  198.   UINT Method;
  199.   UINT FileAttr;
  200.   char *CmtBuf;
  201.   UINT CmtBufSize;
  202.   UINT CmtSize;
  203.   UINT CmtState;
  204. };
  205.  
  206. Structure fields:
  207.  
  208. ArcName
  209.   Output parameter which contains a zero terminated string of the
  210.   current archive name.  May be used to determine the current volume 
  211.   name. 
  212.  
  213. FileName
  214.   Output parameter which contains a zero terminated string of the 
  215.   file name in OEM (DOS) encoding.
  216.  
  217. Flags
  218.   Output parameter which contains file flags:
  219.  
  220.   0x01 - file continued from previous volume
  221.   0x02 - file continued on next volume
  222.   0x04 - file encrypted with password
  223.   0x08 - file comment present
  224.   0x10 - compression of previous files is used (solid flag)
  225.  
  226.   bits 7 6 5
  227.  
  228.        0 0 0    - dictionary size   64 Kb
  229.        0 0 1    - dictionary size  128 Kb
  230.        0 1 0    - dictionary size  256 Kb
  231.        0 1 1    - dictionary size  512 Kb
  232.        1 0 0    - dictionary size 1024 Kb
  233.        1 0 1    - reserved
  234.        1 1 0    - reserved
  235.        1 1 1    - file is directory
  236.  
  237.   Other bits are reserved.
  238.  
  239. PackSize
  240.   Output parameter means packed file size or size of the
  241.   file part if file was split between volumes.
  242.  
  243. UnpSize
  244.   Output parameter - unpacked file size.
  245.  
  246. HostOS
  247.   Output parameter - operating system used for archiving:
  248.  
  249.   0 - MS DOS;
  250.   1 - OS/2.
  251.   2 - Win32
  252.   3 - Unix
  253.  
  254. FileCRC
  255.   Output parameter which contains unpacked file CRC. It should not be
  256.   used for file parts which were split between volumes.
  257.  
  258. FileTime
  259.   Output parameter - contains date and time in standard MS DOS format.
  260.  
  261. UnpVer
  262.   Output parameter - RAR version needed to extract file.
  263.   It is encoded as 10 * Major version + minor version.
  264.  
  265. Method
  266.   Output parameter - packing method.
  267.  
  268. FileAttr
  269.   Output parameter - file attributes.
  270.  
  271. CmtBuf
  272.   File comments support is not implemented in the new DLL version yet.
  273.   Now CmtState is always 0.
  274.  
  275. /*
  276.  * Input parameter which should point to the buffer for file
  277.  * comments. Maximum comment size is limited to 64Kb. Comment text is 
  278.  * a zero terminated string in OEM encoding. If the comment text is
  279.  * larger than the buffer size, the comment text will be truncated.
  280.  * If CmtBuf is set to NULL, comments will not be read. 
  281.  */
  282.  
  283. CmtBufSize
  284.   Input parameter which should contain size of buffer for archive
  285.   comments.
  286.  
  287. CmtSize
  288.   Output parameter containing size of comments actually read into the
  289.   buffer, should not exceed CmtBufSize.
  290.  
  291. CmtState
  292.   Output parameter.
  293.  
  294.   Possible values
  295.  
  296.   0                     Absent comments
  297.   1                     Comments read completely
  298.   ERAR_NO_MEMORY        Not enough memory to extract comments
  299.   ERAR_BAD_DATA         Broken comment
  300.   ERAR_UNKNOWN_FORMAT   Unknown comment format
  301.   ERAR_SMALL_BUF        Buffer too small, comments not completely read
  302.  
  303. Return values
  304. ~~~~~~~~~~~~~
  305.  
  306.   0                     Success
  307.   ERAR_END_ARCHIVE      End of archive
  308.   ERAR_BAD_DATA         File header broken
  309.  
  310.  
  311. ====================================================================
  312. int PASCAL RARReadHeaderEx(HANDLE hArcData,
  313.                            struct RARHeaderDataEx *HeaderData)
  314. ====================================================================
  315.  
  316. Description
  317. ~~~~~~~~~~~
  318.   Similar to RARReadHeader, but uses RARHeaderDataEx structure,
  319. containing information about Unicode file names and 64 bit file sizes.
  320.  
  321. struct RARHeaderDataEx
  322. {
  323.   char         ArcName[1024];
  324.   wchar_t      ArcNameW[1024];
  325.   char         FileName[1024];
  326.   wchar_t      FileNameW[1024];
  327.   unsigned int Flags;
  328.   unsigned int PackSize;
  329.   unsigned int PackSizeHigh;
  330.   unsigned int UnpSize;
  331.   unsigned int UnpSizeHigh;
  332.   unsigned int HostOS;
  333.   unsigned int FileCRC;
  334.   unsigned int FileTime;
  335.   unsigned int UnpVer;
  336.   unsigned int Method;
  337.   unsigned int FileAttr;
  338.   char         *CmtBuf;
  339.   unsigned int CmtBufSize;
  340.   unsigned int CmtSize;
  341.   unsigned int CmtState;
  342.   unsigned int Reserved[1024];
  343. };
  344.  
  345.  
  346. ====================================================================
  347. int PASCAL RARProcessFile(HANDLE hArcData,
  348.                           int Operation,
  349.                           char *DestPath,
  350.                           char *DestName)
  351. ====================================================================
  352.  
  353. Description
  354. ~~~~~~~~~~~
  355.   Performs action and moves the current position in the archive to 
  356.   the next file. Extract or test the current file from the archive 
  357.   opened in RAR_OM_EXTRACT mode. If the mode RAR_OM_LIST is set, 
  358.   then a call to this function will simply skip the archive position 
  359.   to the next file. 
  360.  
  361. Parameters
  362. ~~~~~~~~~~
  363. hArcData
  364.   This parameter should contain the archive handle obtained from the
  365.   RAROpenArchive function call.
  366.  
  367. Operation
  368.   File operation.
  369.  
  370.   Possible values
  371.  
  372.   RAR_SKIP              Move to the next file in the archive. If the 
  373.                         archive is solid and RAR_OM_EXTRACT mode was set 
  374.                         when the archive was opened, the current file will 
  375.                         be processed - the operation will be performed 
  376.                         slower than a simple seek. 
  377.  
  378.   RAR_TEST              Test the current file and move to the next file in 
  379.                         the archive. If the archive was opened with 
  380.                         RAR_OM_LIST mode, the operation is equal to 
  381.                         RAR_SKIP. 
  382.  
  383.   RAR_EXTRACT           Extract the current file and move to the next file.
  384.                         If the archive was opened with RAR_OM_LIST mode,
  385.                         the operation is equal to RAR_SKIP.
  386.  
  387.  
  388. DestPath
  389.   This parameter should point to a zero terminated string containing the 
  390.   destination directory to which to extract files to. If DestPath is equal 
  391.   to NULL it means extract to the current directory. This parameter has 
  392.   meaning only if DestName is NULL. 
  393.  
  394. DestName
  395.   This parameter should point to a string containing the full path and name
  396.   of the file to be extracted or NULL as default. If DestName is defined
  397.   (not NULL) it overrides the original file name saved in the archive and 
  398.   DestPath setting. 
  399.  
  400.   Both DestPath and DestName must be in OEM encoding. If necessary,
  401.   use CharToOem to convert text to OEM before passing to this function.
  402.  
  403. Return values
  404. ~~~~~~~~~~~~~
  405.   0                     Success
  406.   ERAR_BAD_DATA         File CRC error
  407.   ERAR_BAD_ARCHIVE      Volume is not valid RAR archive
  408.   ERAR_UNKNOWN_FORMAT   Unknown archive format
  409.   ERAR_EOPEN            Volume open error
  410.   ERAR_ECREATE          File create error
  411.   ERAR_ECLOSE           File close error
  412.   ERAR_EREAD            Read error
  413.   ERAR_EWRITE           Write error
  414.  
  415.  
  416. ====================================================================
  417. int PASCAL RARProcessFileW(HANDLE hArcData,
  418.                            int Operation,
  419.                            wchar_t *DestPath,
  420.                            wchar_t *DestName)
  421. ====================================================================
  422.  
  423. Description
  424. ~~~~~~~~~~~
  425.   Unicode version of RARProcessFile. It uses Unicode DestPath
  426.   and DestName parameters, other parameters and return values
  427.   are the same as in RARProcessFile.
  428.  
  429.  
  430. ====================================================================
  431. void PASCAL RARSetCallback(HANDLE hArcData,
  432.             int PASCAL (*CallbackProc)(UINT msg,LONG UserData,LONG P1,LONG P2),
  433.             LONG UserData);
  434. ====================================================================
  435.  
  436. Description
  437. ~~~~~~~~~~~
  438.   Set a user-defined callback function to process Unrar events.
  439.  
  440. Parameters
  441. ~~~~~~~~~~
  442. hArcData
  443.   This parameter should contain the archive handle obtained from the
  444.   RAROpenArchive function call.
  445.  
  446. CallbackProc
  447.   It should point to a user-defined callback function.
  448.  
  449.   The function will be passed four parameters:
  450.  
  451.  
  452.   msg                    Type of event. Described below.
  453.  
  454.   UserData               User defined value passed to RARSetCallback.
  455.  
  456.   P1 and P2              Event dependent parameters. Described below.
  457.  
  458.  
  459.   Possible events
  460.  
  461.     UCM_CHANGEVOLUME     Process volume change.
  462.  
  463.       P1                   Points to the zero terminated name
  464.                            of the next volume.
  465.  
  466.       P2                   The function call mode:
  467.  
  468.         RAR_VOL_ASK          Required volume is absent. The function should
  469.                              prompt user and return a positive value
  470.                              to retry or return -1 value to terminate 
  471.                              operation. The function may also specify a new 
  472.                              volume name, placing it to the address specified
  473.                              by P1 parameter. 
  474.  
  475.         RAR_VOL_NOTIFY       Required volume is successfully opened.
  476.                              This is a notification call and volume name
  477.                              modification is not allowed. The function should 
  478.                              return a positive value to continue or -1
  479.                              to terminate operation. 
  480.  
  481.     UCM_PROCESSDATA          Process unpacked data. It may be used to read
  482.                              a file while it is being extracted or tested
  483.                              without actual extracting file to disk.
  484.                              Return a positive value to continue process
  485.                              or -1 to cancel the archive operation
  486.  
  487.       P1                   Address pointing to the unpacked data.
  488.                            Function may refer to the data but must not
  489.                            change it.
  490.  
  491.       P2                   Size of the unpacked data. It is guaranteed
  492.                            only that the size will not exceed the maximum
  493.                            dictionary size (4 Mb in RAR 3.0).
  494.  
  495.     UCM_NEEDPASSWORD         DLL needs a password to process archive.
  496.                              This message must be processed if you wish
  497.                              to be able to handle archives with encrypted
  498.                              file names. It can be also used as replacement
  499.                              of RARSetPassword function even for usual
  500.                              encrypted files with non-encrypted names.
  501.  
  502.       P1                   Address pointing to the buffer for a password.
  503.                            You need to copy a password here.
  504.  
  505.       P2                   Size of the password buffer.
  506.  
  507.  
  508. UserData
  509.   User data passed to callback function.
  510.  
  511.   Other functions of UNRAR.DLL should not be called from the callback
  512.   function.
  513.  
  514. Return values
  515. ~~~~~~~~~~~~~
  516.   None
  517.  
  518.  
  519.  
  520. ====================================================================
  521. void PASCAL RARSetChangeVolProc(HANDLE hArcData,
  522.             int PASCAL (*ChangeVolProc)(char *ArcName,int Mode));
  523. ====================================================================
  524.  
  525. Obsoleted, use RARSetCallback instead.
  526.  
  527.  
  528.  
  529. ====================================================================
  530. void PASCAL RARSetProcessDataProc(HANDLE hArcData,
  531.             int PASCAL (*ProcessDataProc)(unsigned char *Addr,int Size))
  532. ====================================================================
  533.  
  534. Obsoleted, use RARSetCallback instead.
  535.  
  536.  
  537. ====================================================================
  538. void PASCAL RARSetPassword(HANDLE hArcData,
  539.                            char *Password);
  540. ====================================================================
  541.  
  542. Description
  543. ~~~~~~~~~~~
  544.   Set a password to decrypt files.
  545.  
  546. Parameters
  547. ~~~~~~~~~~
  548. hArcData
  549.   This parameter should contain the archive handle obtained from the
  550.   RAROpenArchive function call.
  551.  
  552. Password
  553.   It should point to a string containing a zero terminated password.
  554.  
  555. Return values
  556. ~~~~~~~~~~~~~
  557.   None
  558.  
  559.  
  560. ====================================================================
  561. void PASCAL RARGetDllVersion();
  562. ====================================================================
  563.  
  564. Description
  565. ~~~~~~~~~~~
  566.   Returns unrar.dll version.
  567.  
  568. Parameters
  569. ~~~~~~~~~~
  570.   None.
  571.  
  572. Return values
  573. ~~~~~~~~~~~~~
  574.   Returns an integer value denoting DLL version. It is increased in case
  575. of changes in DLL API. The current version value is defined in unrar.h
  576. as RAR_DLL_VERSION
  577.  
  578.   This function is absent in old versions of unrar.dll, so it may be wise
  579. to use LoadLibrary and GetProcAddress to access this function.
  580.  
  581.