607 lines
19 KiB
Plaintext
607 lines
19 KiB
Plaintext
|
|
UnRAR.dll Manual
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
UnRAR.dll is a 32-bit Windows dynamic-link library which provides
|
|
file extraction from RAR archives.
|
|
|
|
|
|
Exported functions
|
|
|
|
====================================================================
|
|
HANDLE PASCAL RAROpenArchive(struct RAROpenArchiveData *ArchiveData)
|
|
====================================================================
|
|
|
|
Description
|
|
~~~~~~~~~~~
|
|
Open RAR archive and allocate memory structures
|
|
|
|
Parameters
|
|
~~~~~~~~~~
|
|
ArchiveData Points to RAROpenArchiveData structure
|
|
|
|
struct RAROpenArchiveData
|
|
{
|
|
char *ArcName;
|
|
UINT OpenMode;
|
|
UINT OpenResult;
|
|
char *CmtBuf;
|
|
UINT CmtBufSize;
|
|
UINT CmtSize;
|
|
UINT CmtState;
|
|
};
|
|
|
|
Structure fields:
|
|
|
|
ArcName
|
|
Input parameter which should point to zero terminated string
|
|
containing the archive name.
|
|
|
|
OpenMode
|
|
Input parameter.
|
|
|
|
Possible values
|
|
|
|
RAR_OM_LIST
|
|
Open archive for reading file headers only.
|
|
|
|
RAR_OM_EXTRACT
|
|
Open archive for testing and extracting files.
|
|
|
|
RAR_OM_LIST_INCSPLIT
|
|
Open archive for reading file headers only. If you open an archive
|
|
in such mode, RARReadHeader[Ex] will return all file headers,
|
|
including those with "file continued from previous volume" flag.
|
|
In case of RAR_OM_LIST such headers are automatically skipped.
|
|
So if you process RAR volumes in RAR_OM_LIST_INCSPLIT mode, you will
|
|
get several file header records for same file if file is split between
|
|
volumes. For such files only the last file header record will contain
|
|
the correct file CRC and if you wish to get the correct packed size,
|
|
you need to sum up packed sizes of all parts.
|
|
|
|
OpenResult
|
|
Output parameter.
|
|
|
|
Possible values
|
|
|
|
0 Success
|
|
ERAR_NO_MEMORY Not enough memory to initialize data structures
|
|
ERAR_BAD_DATA Archive header broken
|
|
ERAR_BAD_ARCHIVE File is not valid RAR archive
|
|
ERAR_UNKNOWN_FORMAT Unknown encryption used for archive headers
|
|
ERAR_EOPEN File open error
|
|
|
|
CmtBuf
|
|
Input parameter which should point to the buffer for archive
|
|
comments. Maximum comment size is limited to 64Kb. Comment text is
|
|
zero terminated. If the comment text is larger than the buffer
|
|
size, the comment text will be truncated. If CmtBuf is set to
|
|
NULL, comments will not be read.
|
|
|
|
CmtBufSize
|
|
Input parameter which should contain size of buffer for archive
|
|
comments.
|
|
|
|
CmtSize
|
|
Output parameter containing size of comments actually read into the
|
|
buffer, cannot exceed CmtBufSize.
|
|
|
|
CmtState
|
|
Output parameter.
|
|
|
|
Possible values
|
|
|
|
0 comments not present
|
|
1 Comments read completely
|
|
ERAR_NO_MEMORY Not enough memory to extract comments
|
|
ERAR_BAD_DATA Broken comment
|
|
ERAR_UNKNOWN_FORMAT Unknown comment format
|
|
ERAR_SMALL_BUF Buffer too small, comments not completely read
|
|
|
|
Return values
|
|
~~~~~~~~~~~~~
|
|
Archive handle or NULL in case of error
|
|
|
|
|
|
========================================================================
|
|
HANDLE PASCAL RAROpenArchiveEx(struct RAROpenArchiveDataEx *ArchiveData)
|
|
========================================================================
|
|
|
|
Description
|
|
~~~~~~~~~~~
|
|
Similar to RAROpenArchive, but uses RAROpenArchiveDataEx structure
|
|
allowing to specify Unicode archive name and returning information
|
|
about archive flags.
|
|
|
|
Parameters
|
|
~~~~~~~~~~
|
|
ArchiveData Points to RAROpenArchiveDataEx structure
|
|
|
|
struct RAROpenArchiveDataEx
|
|
{
|
|
char *ArcName;
|
|
wchar_t *ArcNameW;
|
|
unsigned int OpenMode;
|
|
unsigned int OpenResult;
|
|
char *CmtBuf;
|
|
unsigned int CmtBufSize;
|
|
unsigned int CmtSize;
|
|
unsigned int CmtState;
|
|
unsigned int Flags;
|
|
unsigned int Reserved[32];
|
|
};
|
|
|
|
Structure fields:
|
|
|
|
ArcNameW
|
|
Input parameter which should point to zero terminated Unicode string
|
|
containing the archive name or NULL if Unicode name is not specified.
|
|
|
|
Flags
|
|
Output parameter. Combination of bit flags.
|
|
|
|
Possible values
|
|
|
|
0x0001 - Volume attribute (archive volume)
|
|
0x0002 - Archive comment present
|
|
0x0004 - Archive lock attribute
|
|
0x0008 - Solid attribute (solid archive)
|
|
0x0010 - New volume naming scheme ('volname.partN.rar')
|
|
0x0020 - Authenticity information present
|
|
0x0040 - Recovery record present
|
|
0x0080 - Block headers are encrypted
|
|
0x0100 - First volume (set only by RAR 3.0 and later)
|
|
|
|
Reserved[32]
|
|
Reserved for future use. Must be zero.
|
|
|
|
Information on other structure fields and function return values
|
|
is available above, in RAROpenArchive function description.
|
|
|
|
|
|
====================================================================
|
|
int PASCAL RARCloseArchive(HANDLE hArcData)
|
|
====================================================================
|
|
|
|
Description
|
|
~~~~~~~~~~~
|
|
Close RAR archive and release allocated memory. It must be called when
|
|
archive processing is finished, even if the archive processing was stopped
|
|
due to an error.
|
|
|
|
Parameters
|
|
~~~~~~~~~~
|
|
hArcData
|
|
This parameter should contain the archive handle obtained from the
|
|
RAROpenArchive function call.
|
|
|
|
Return values
|
|
~~~~~~~~~~~~~
|
|
0 Success
|
|
ERAR_ECLOSE Archive close error
|
|
|
|
|
|
====================================================================
|
|
int PASCAL RARReadHeader(HANDLE hArcData,
|
|
struct RARHeaderData *HeaderData)
|
|
====================================================================
|
|
|
|
Description
|
|
~~~~~~~~~~~
|
|
Read header of file in archive.
|
|
|
|
Parameters
|
|
~~~~~~~~~~
|
|
hArcData
|
|
This parameter should contain the archive handle obtained from the
|
|
RAROpenArchive function call.
|
|
|
|
HeaderData
|
|
It should point to RARHeaderData structure:
|
|
|
|
struct RARHeaderData
|
|
{
|
|
char ArcName[260];
|
|
char FileName[260];
|
|
UINT Flags;
|
|
UINT PackSize;
|
|
UINT UnpSize;
|
|
UINT HostOS;
|
|
UINT FileCRC;
|
|
UINT FileTime;
|
|
UINT UnpVer;
|
|
UINT Method;
|
|
UINT FileAttr;
|
|
char *CmtBuf;
|
|
UINT CmtBufSize;
|
|
UINT CmtSize;
|
|
UINT CmtState;
|
|
};
|
|
|
|
Structure fields:
|
|
|
|
ArcName
|
|
Output parameter which contains a zero terminated string of the
|
|
current archive name. May be used to determine the current volume
|
|
name.
|
|
|
|
FileName
|
|
Output parameter which contains a zero terminated string of the
|
|
file name in OEM (DOS) encoding.
|
|
|
|
Flags
|
|
Output parameter which contains file flags:
|
|
|
|
0x01 - file continued from previous volume
|
|
0x02 - file continued on next volume
|
|
0x04 - file encrypted with password
|
|
0x08 - file comment present
|
|
0x10 - compression of previous files is used (solid flag)
|
|
|
|
bits 7 6 5
|
|
|
|
0 0 0 - dictionary size 64 Kb
|
|
0 0 1 - dictionary size 128 Kb
|
|
0 1 0 - dictionary size 256 Kb
|
|
0 1 1 - dictionary size 512 Kb
|
|
1 0 0 - dictionary size 1024 Kb
|
|
1 0 1 - dictionary size 2048 KB
|
|
1 1 0 - dictionary size 4096 KB
|
|
1 1 1 - file is directory
|
|
|
|
Other bits are reserved.
|
|
|
|
PackSize
|
|
Output parameter means packed file size or size of the
|
|
file part if file was split between volumes.
|
|
|
|
UnpSize
|
|
Output parameter - unpacked file size.
|
|
|
|
HostOS
|
|
Output parameter - operating system used for archiving:
|
|
|
|
0 - MS DOS;
|
|
1 - OS/2.
|
|
2 - Win32
|
|
3 - Unix
|
|
|
|
FileCRC
|
|
Output parameter which contains unpacked file CRC. In case of file parts
|
|
split between volumes only the last part contains the correct CRC
|
|
and it is accessible only in RAR_OM_LIST_INCSPLIT listing mode.
|
|
|
|
FileTime
|
|
Output parameter - contains date and time in standard MS DOS format.
|
|
|
|
UnpVer
|
|
Output parameter - RAR version needed to extract file.
|
|
It is encoded as 10 * Major version + minor version.
|
|
|
|
Method
|
|
Output parameter - packing method.
|
|
|
|
FileAttr
|
|
Output parameter - file attributes.
|
|
|
|
CmtBuf
|
|
File comments support is not implemented in the new DLL version yet.
|
|
Now CmtState is always 0.
|
|
|
|
/*
|
|
* Input parameter which should point to the buffer for file
|
|
* comments. Maximum comment size is limited to 64Kb. Comment text is
|
|
* a zero terminated string in OEM encoding. If the comment text is
|
|
* larger than the buffer size, the comment text will be truncated.
|
|
* If CmtBuf is set to NULL, comments will not be read.
|
|
*/
|
|
|
|
CmtBufSize
|
|
Input parameter which should contain size of buffer for archive
|
|
comments.
|
|
|
|
CmtSize
|
|
Output parameter containing size of comments actually read into the
|
|
buffer, should not exceed CmtBufSize.
|
|
|
|
CmtState
|
|
Output parameter.
|
|
|
|
Possible values
|
|
|
|
0 Absent comments
|
|
1 Comments read completely
|
|
ERAR_NO_MEMORY Not enough memory to extract comments
|
|
ERAR_BAD_DATA Broken comment
|
|
ERAR_UNKNOWN_FORMAT Unknown comment format
|
|
ERAR_SMALL_BUF Buffer too small, comments not completely read
|
|
|
|
Return values
|
|
~~~~~~~~~~~~~
|
|
|
|
0 Success
|
|
ERAR_END_ARCHIVE End of archive
|
|
ERAR_BAD_DATA File header broken
|
|
|
|
|
|
====================================================================
|
|
int PASCAL RARReadHeaderEx(HANDLE hArcData,
|
|
struct RARHeaderDataEx *HeaderData)
|
|
====================================================================
|
|
|
|
Description
|
|
~~~~~~~~~~~
|
|
Similar to RARReadHeader, but uses RARHeaderDataEx structure,
|
|
containing information about Unicode file names and 64 bit file sizes.
|
|
|
|
struct RARHeaderDataEx
|
|
{
|
|
char ArcName[1024];
|
|
wchar_t ArcNameW[1024];
|
|
char FileName[1024];
|
|
wchar_t FileNameW[1024];
|
|
unsigned int Flags;
|
|
unsigned int PackSize;
|
|
unsigned int PackSizeHigh;
|
|
unsigned int UnpSize;
|
|
unsigned int UnpSizeHigh;
|
|
unsigned int HostOS;
|
|
unsigned int FileCRC;
|
|
unsigned int FileTime;
|
|
unsigned int UnpVer;
|
|
unsigned int Method;
|
|
unsigned int FileAttr;
|
|
char *CmtBuf;
|
|
unsigned int CmtBufSize;
|
|
unsigned int CmtSize;
|
|
unsigned int CmtState;
|
|
unsigned int Reserved[1024];
|
|
};
|
|
|
|
|
|
====================================================================
|
|
int PASCAL RARProcessFile(HANDLE hArcData,
|
|
int Operation,
|
|
char *DestPath,
|
|
char *DestName)
|
|
====================================================================
|
|
|
|
Description
|
|
~~~~~~~~~~~
|
|
Performs action and moves the current position in the archive to
|
|
the next file. Extract or test the current file from the archive
|
|
opened in RAR_OM_EXTRACT mode. If the mode RAR_OM_LIST is set,
|
|
then a call to this function will simply skip the archive position
|
|
to the next file.
|
|
|
|
Parameters
|
|
~~~~~~~~~~
|
|
hArcData
|
|
This parameter should contain the archive handle obtained from the
|
|
RAROpenArchive function call.
|
|
|
|
Operation
|
|
File operation.
|
|
|
|
Possible values
|
|
|
|
RAR_SKIP Move to the next file in the archive. If the
|
|
archive is solid and RAR_OM_EXTRACT mode was set
|
|
when the archive was opened, the current file will
|
|
be processed - the operation will be performed
|
|
slower than a simple seek.
|
|
|
|
RAR_TEST Test the current file and move to the next file in
|
|
the archive. If the archive was opened with
|
|
RAR_OM_LIST mode, the operation is equal to
|
|
RAR_SKIP.
|
|
|
|
RAR_EXTRACT Extract the current file and move to the next file.
|
|
If the archive was opened with RAR_OM_LIST mode,
|
|
the operation is equal to RAR_SKIP.
|
|
|
|
|
|
DestPath
|
|
This parameter should point to a zero terminated string containing the
|
|
destination directory to which to extract files to. If DestPath is equal
|
|
to NULL, it means extract to the current directory. This parameter has
|
|
meaning only if DestName is NULL.
|
|
|
|
DestName
|
|
This parameter should point to a string containing the full path and name
|
|
to assign to extracted file or it can be NULL to use the default name.
|
|
If DestName is defined (not NULL), it overrides both the original file
|
|
name saved in the archive and path specigied in DestPath setting.
|
|
|
|
Both DestPath and DestName must be in OEM encoding. If necessary,
|
|
use CharToOem to convert text to OEM before passing to this function.
|
|
|
|
Return values
|
|
~~~~~~~~~~~~~
|
|
0 Success
|
|
ERAR_BAD_DATA File CRC error
|
|
ERAR_BAD_ARCHIVE Volume is not valid RAR archive
|
|
ERAR_UNKNOWN_FORMAT Unknown archive format
|
|
ERAR_EOPEN Volume open error
|
|
ERAR_ECREATE File create error
|
|
ERAR_ECLOSE File close error
|
|
ERAR_EREAD Read error
|
|
ERAR_EWRITE Write error
|
|
|
|
|
|
Note: if you wish to cancel extraction, return -1 when processing
|
|
UCM_PROCESSDATA callback message.
|
|
|
|
|
|
====================================================================
|
|
int PASCAL RARProcessFileW(HANDLE hArcData,
|
|
int Operation,
|
|
wchar_t *DestPath,
|
|
wchar_t *DestName)
|
|
====================================================================
|
|
|
|
Description
|
|
~~~~~~~~~~~
|
|
Unicode version of RARProcessFile. It uses Unicode DestPath
|
|
and DestName parameters, other parameters and return values
|
|
are the same as in RARProcessFile.
|
|
|
|
|
|
====================================================================
|
|
void PASCAL RARSetCallback(HANDLE hArcData,
|
|
int PASCAL (*CallbackProc)(UINT msg,LPARAM UserData,LPARAM P1,LPARAM P2),
|
|
LPARAM UserData);
|
|
====================================================================
|
|
|
|
Description
|
|
~~~~~~~~~~~
|
|
Set a user-defined callback function to process Unrar events.
|
|
|
|
Parameters
|
|
~~~~~~~~~~
|
|
hArcData
|
|
This parameter should contain the archive handle obtained from the
|
|
RAROpenArchive function call.
|
|
|
|
CallbackProc
|
|
It should point to a user-defined callback function.
|
|
|
|
The function will be passed four parameters:
|
|
|
|
|
|
msg Type of event. Described below.
|
|
|
|
UserData User defined value passed to RARSetCallback.
|
|
|
|
P1 and P2 Event dependent parameters. Described below.
|
|
|
|
|
|
Possible events
|
|
|
|
UCM_CHANGEVOLUME Process volume change.
|
|
|
|
P1 Points to the zero terminated name
|
|
of the next volume.
|
|
|
|
P2 The function call mode:
|
|
|
|
RAR_VOL_ASK Required volume is absent. The function should
|
|
prompt user and return a positive value
|
|
to retry or return -1 value to terminate
|
|
operation. The function may also specify a new
|
|
volume name, placing it to the address specified
|
|
by P1 parameter.
|
|
|
|
RAR_VOL_NOTIFY Required volume is successfully opened.
|
|
This is a notification call and volume name
|
|
modification is not allowed. The function should
|
|
return a positive value to continue or -1
|
|
to terminate operation.
|
|
|
|
UCM_PROCESSDATA Process unpacked data. It may be used to read
|
|
a file while it is being extracted or tested
|
|
without actual extracting file to disk.
|
|
Return a positive value to continue process
|
|
or -1 to cancel the archive operation
|
|
|
|
P1 Address pointing to the unpacked data.
|
|
Function may refer to the data but must not
|
|
change it.
|
|
|
|
P2 Size of the unpacked data. It is guaranteed
|
|
only that the size will not exceed the maximum
|
|
dictionary size (4 Mb in RAR 3.0).
|
|
|
|
UCM_NEEDPASSWORD DLL needs a password to process archive.
|
|
This message must be processed if you wish
|
|
to be able to handle archives with encrypted
|
|
file names. It can be also used as replacement
|
|
of RARSetPassword function even for usual
|
|
encrypted files with non-encrypted names.
|
|
|
|
P1 Address pointing to the buffer for a password.
|
|
You need to copy a password here.
|
|
|
|
P2 Size of the password buffer.
|
|
|
|
|
|
UserData
|
|
User data passed to callback function.
|
|
|
|
Other functions of UnRAR.dll should not be called from the callback
|
|
function.
|
|
|
|
Return values
|
|
~~~~~~~~~~~~~
|
|
None
|
|
|
|
|
|
|
|
====================================================================
|
|
void PASCAL RARSetChangeVolProc(HANDLE hArcData,
|
|
int PASCAL (*ChangeVolProc)(char *ArcName,int Mode));
|
|
====================================================================
|
|
|
|
Obsoleted, use RARSetCallback instead.
|
|
|
|
|
|
|
|
====================================================================
|
|
void PASCAL RARSetProcessDataProc(HANDLE hArcData,
|
|
int PASCAL (*ProcessDataProc)(unsigned char *Addr,int Size))
|
|
====================================================================
|
|
|
|
Obsoleted, use RARSetCallback instead.
|
|
|
|
|
|
====================================================================
|
|
void PASCAL RARSetPassword(HANDLE hArcData,
|
|
char *Password);
|
|
====================================================================
|
|
|
|
Description
|
|
~~~~~~~~~~~
|
|
Set a password to decrypt files.
|
|
|
|
Parameters
|
|
~~~~~~~~~~
|
|
hArcData
|
|
This parameter should contain the archive handle obtained from the
|
|
RAROpenArchive function call.
|
|
|
|
Password
|
|
It should point to a string containing a zero terminated password.
|
|
|
|
Return values
|
|
~~~~~~~~~~~~~
|
|
None
|
|
|
|
|
|
====================================================================
|
|
void PASCAL RARGetDllVersion();
|
|
====================================================================
|
|
|
|
Description
|
|
~~~~~~~~~~~
|
|
Returns API version.
|
|
|
|
Parameters
|
|
~~~~~~~~~~
|
|
None.
|
|
|
|
Return values
|
|
~~~~~~~~~~~~~
|
|
Returns an integer value denoting UnRAR.dll API version, which is also
|
|
defined in unrar.h as RAR_DLL_VERSION. API version number is incremented
|
|
only in case of noticeable changes in UnRAR.dll API. Do not confuse it
|
|
with version of UnRAR.dll stored in DLL resources, which is incremented
|
|
with every DLL rebuild.
|
|
|
|
If RARGetDllVersion() returns a value lower than UnRAR.dll which your
|
|
application was designed for, it may indicate that DLL version is too old
|
|
and it will fail to provide all necessary functions to your application.
|
|
|
|
This function is absent in old versions of UnRAR.dll, so it is safer
|
|
to use LoadLibrary and GetProcAddress to access this function.
|
|
|