unrarlib
— ctypes wrapper for UnRAR library¶
The RAR file format is a common archive and compression standard. This module provides a ctypes wrapper for UnRAR library (provided by RARLAB).
Most of this information is extracted from RAR library documentation.
The module defines the following items:
-
exception
unrarlib.
UnrarException
¶ The error raised for possible library errors.
-
class
unrarlib.
RAROpenArchiveDataEx
¶ Class mapping the library RAROpenArchiveDataEx C struct:
struct RAROpenArchiveData{ 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]; };
Using the name fields described above you can access the respective values through an instance as they were instance attributes.
See section RAROpenArchiveDataEx for details.
-
class
unrarlib.
RARHeaderDataEx
¶ Class mapping the library RARHeaderDataEx C struct:
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]; };
See section RARHeaderDataEx for details.
-
unrarlib.
dostime_to_timetuple
(dostime)¶ Convert an MS-DOS format date time to a Python time tuple.
-
unrarlib.
RAROpenArchiveEx
(archive_data)¶ Open RAR archive and allocate memory structures. archive_data should be a pointer to an initialized
RAROpenArchiveDataEx
. When it succeeds, it loads the archive information into archive_data and returns a handle identifying the open archive, to be used as argument to the other functions in the module. In case of error, it raises an UnrarException (you can confirm which the error was by checkingRAROpenArchiveDataEx.OpenResult
).
-
unrarlib.
RARCloseArchive
(handle)¶ 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.
-
unrarlib.
RARReadHeaderEx
(handle, header_data)¶ Read header of file in archive. header_data should be a pointer to an initialized
RARHeaderDataEx
, that would get filled with the member details.
-
unrarlib.
RARProcessFile
(handle, operation, dest_path, dest_name)¶ 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
constants
.RAR_OM_EXTRACT mode. If the modeconstants
.RAR_OM_LIST is set, then a call to this function will simply skip the archive position to the next file.Possible operations are:
constants
.RAR_SKIP- Move to the next file in the archive. If the
archive is solid and
constants
.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. constants
.RAR_TEST- Test the current file and move to the next file in
the archive. If the archive was opened with
constants
.RAR_OM_LIST mode, the operation is equal toconstants
.RAR_SKIP. constants
.RAR_EXTRACT- Extract the current file and move to the next file.
If the archive was opened with
constants
.RAR_OM_LIST mode, the operation is equal toconstants
.RAR_SKIP.
-
unrarlib.
RARSetPassword
(handle, pwd)¶ Set a password to decrypt files when processing.
-
unrarlib.
RARSetCallback
(handle, callback, user_data)¶ Set a user-defined callback function to process unrar events.
callback is a user-defined function, taking four parameters:
- msg
- Type of event.
- user_data
- User data passed to callback function.
- P1, P2
- Event dependent parameters.
You need to wrap your callback function to use the right calling convention; for that you can use
unrarlib
.UNRARCALLBACK function, that will set the correct argument types and return value for your OS.Possible events:
constants
.UCM_CHANGEVOLUME- Process volume change.
- P1
- Points to the zero terminated name of the next volume.
- P2
- The function call mode:
constants
.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.
constants
.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.
constants
.UCM_PROCESSDATAProcess 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).
constants
.UCM_NEEDPASSWORDDLL 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.
Other functions of unrarlib should not be called from the callback function. There is no return value. For an example of using callbacks, you can check
rarfile.RarFile.open()
implementation.
-
unrarlib.
RARGetDllVersion
()¶ Return library API version.
RAROpenArchiveDataEx¶
-
class
unrarlib.
RAROpenArchiveDataEx
(filename[, mode=constants.RAR_OM_LIST]) Initialize a RAROpenArchiveDataEx instance to open filename using the indicated mode. mode should be one of the possible open modes defined in
constants
.
-
RAROpenArchiveDataEx.
ArcName
¶ Input parameter, a string containing the archive name.
-
RAROpenArchiveDataEx.
ArcNameW
¶ Input parameter, a Unicode string containing the archive name or None if Unicode name is not specified.
-
RAROpenArchiveDataEx.
OpenMode
¶ Input parameter.
Possible values:
constants
.RAR_OM_LIST- Open archive for reading file headers only.
constants
.RAR_OM_EXTRACT- Open archive for testing and extracting files.
constants
.RAR_OM_LIST_INCSPLIT- Open archive for reading file headers only. If you open an archive
in such mode, RARReadHeaderEx will return all file headers,
including those with “file continued from previous volume” flag.
In case of
constants
.RAR_OM_LIST such headers are automatically skipped. So if you process RAR volumes inconstants
.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.
-
RAROpenArchiveDataEx.
OpenResult
¶ Output parameter.
Possible values:
constants
.SUCCESS- Success
constants
.ERAR_NO_MEMORY- Not enough memory to initialize data structures
constants
.ERAR_BAD_DATA- Archive header broken
constants
.ERAR_BAD_ARCHIVE- File is not valid RAR archive
constants
.ERAR_UNKNOWN_FORMAT- Unknown encryption used for archive headers
constants
.ERAR_EOPEN- File open error
-
RAROpenArchiveDataEx.
CmtBuf
¶ Buffer for archive comments. Maximum comment size is limited to 64Kb. If the comment text is larger than the buffer size, the comment text will be truncated.
-
RAROpenArchiveDataEx.
CmtBufSize
¶ Input parameter which should contain size of buffer for archive comments.
-
RAROpenArchiveDataEx.
CmtSize
¶ Output parameter containing size of comments actually read into the buffer, cannot exceed
CmtBufSize
.
-
RAROpenArchiveDataEx.
CmtState
¶ Output parameter.
Possible values:
constants
.RAR_NO_COMMENTS- Comments not present
constants
.RAR_COMMENTS_SUCCESS- Comments read completely
constants
.ERAR_NO_MEMORY- Not enough memory to extract comments
constants
.ERAR_BAD_DATA- Broken comment
constants
.ERAR_UNKNOWN_FORMAT- Unknown comment format
constants
.ERAR_SMALL_BUF- Buffer too small, comments not completely read
-
RAROpenArchiveDataEx.
Flags
¶ Output parameter. Combination of bit flags.
Possible values:
0x0001 - Volume attribute (archive volume)0x0002 - Archive comment present0x0004 - Archive lock attribute0x0008 - Solid attribute (solid archive)0x0010 - New volume naming scheme (‘volname.partN.rar’)0x0020 - Authenticity information present0x0040 - Recovery record present0x0080 - Block headers are encrypted0x0100 - First volume (set only by RAR 3.0 and later)
-
RAROpenArchiveDataEx.
Reserved
¶ Reserved for future use. Must be zero.
RARHeaderDataEx¶
-
class
unrarlib.
RARHeaderDataEx
() Initialize an empty RARHeaderDataEx instance, to be populated with the details returned by
RARReadHeaderEx()
.
-
RARHeaderDataEx.
ArcName
¶ Output parameter which contains a zero terminated string of the current archive name. May be used to determine the current volume name.
-
RARHeaderDataEx.
FileName
¶ Output parameter which contains a zero terminated string of the file name in OEM (DOS) encoding.
-
RARHeaderDataEx.
Flags
¶ Output parameter which contains file flags:
0x01 - file continued from previous volume0x02 - file continued on next volume0x04 - file encrypted with password0x08 - file comment present0x10 - compression of previous files is used (solid flag)[bits 7 6 5]0 0 0 - dictionary size 64 Kb0 0 1 - dictionary size 128 Kb0 1 0 - dictionary size 256 Kb0 1 1 - dictionary size 512 Kb1 0 0 - dictionary size 1024 Kb1 0 1 - dictionary size 2048 KB1 1 0 - dictionary size 4096 KB1 1 1 - file is directoryOther bits are reserved.
-
RARHeaderDataEx.
PackSize
¶ Output parameter means packed file size or size of the file part if file was split between volumes.
-
RARHeaderDataEx.
UnpSize
¶ Output parameter - unpacked file size.
-
RARHeaderDataEx.
HostOS
¶ Output parameter - operating system used for archiving:
-
RARHeaderDataEx.
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
constants
.RAR_OM_LIST_INCSPLIT listing mode.
-
RARHeaderDataEx.
FileTime
¶ Output parameter - contains date and time in standard MS DOS format.
-
RARHeaderDataEx.
UnpVer
¶ Output parameter - RAR version needed to extract file. It is encoded as 10 * Major version + minor version.
-
RARHeaderDataEx.
Method
¶ Output parameter - packing method.
-
RARHeaderDataEx.
FileAttr
¶ Output parameter - file attributes.
-
RARHeaderDataEx.
CmtBuf
¶ File comments support is not implemented in the new DLL version yet. Now
CmtState
is alwaysconstants
.RAR_NO_COMMENTS.
-
RARHeaderDataEx.
CmtBufSize
¶ Input parameter which should contain size of buffer for archive comments.
-
RARHeaderDataEx.
CmtSize
¶ Output parameter containing size of comments actually read into the buffer, should not exceed
CmtBufSize
.
-
RARHeaderDataEx.
CmtState
¶ Output parameter.
Possible values:
constants
.RAR_NO_COMMENTS- Absent comments
constants
.RAR_COMMENTS_SUCCESS- Comments read completely
constants
.ERAR_NO_MEMORY- Not enough memory to extract comments
constants
.ERAR_BAD_DATA- Broken comment
constants
.ERAR_UNKNOWN_FORMAT- Unknown comment format
constants
.ERAR_SMALL_BUF- Buffer too small, comments not completely read
See also
- UnRAR Manual
UnRAR library manual
- RARLAB
- Official RAR site.
- RAR addons
- RAR addons where you can download UnRAR library sources. Check source files to get more detailed information.