Portable UnRAR version


   1. General

   This package includes freeware Unrar C++ source and a few makefiles
   (makefile.bcc, makefile.msc+msc.dep, makefile.unix). Unrar source
   is subset of RAR and generated from RAR source automatically,
   by a small program removing blocks like '#ifndef UNRAR ... #endif'.
   Such method is not perfect and you may find some RAR related
   stuff unnecessary in Unrar, especially in header files.

   If you wish to port Unrar to a new platform, you may need to edit
   '#define LITTLE_ENDIAN' in os.hpp and data type definitions
   in rartypes.hpp.

   if computer architecture does not allow not aligned data access,
   you need to undefine ALLOW_NOT_ALIGNED_INT and define
   STRICT_ALIGNMENT_REQUIRED in os.h. Note that it will increase memory
   requirements.

   If you use Borland C++ makefile (makefile.bcc), you need to define
   BASEPATHCC environment (or makefile) variable containing
   the path to Borland C++ installation.

   Makefile.unix contains numerous compiler option sets.
   GCC Linux is selected by default. If you need to compile Unrar
   for other platforms, uncomment corresponding lines.

   UnRAR.vcproj and UnRARDll.vcproj are projects for Microsoft Visual C++.
   UnRARDll.vcproj lets to build unrar.dll library.


   2. Unrar binaries

   If you compiled Unrar for OS, which is not present in "Downloads"
   and "RAR extras" on www.rarlab.com, we will appreciate if you send
   us the compiled executable to place it to our site.


   3. Acknowledgements

   This source includes parts of code written by the following authors:

   Dmitry Shkarin     PPMII v.H text compression
   Dmitry Subbotin    Carryless rangecoder
   Szymon Stefanek    AES encryption
   Brian Gladman      AES encryption
   Steve Reid         SHA-1 hash function
   Marcus Herbert     makefile.unix file
   Tomasz Klim        fixes for libunrar.so
   Robert Riebisch    makefile.dj and patches for DJGPP


   4. Legal stuff

   Unrar source may be used in any software to handle RAR archives
   without limitations free of charge, but cannot be used to re-create
   the RAR compression algorithm, which is proprietary. Distribution
   of modified Unrar source in separate form or as a part of other
   software is permitted, provided that it is clearly stated in
   the documentation and source comments that the code may not be used
   to develop a RAR (WinRAR) compatible archiver.

   More detailed license text is available in license.txt.


	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

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_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    - reserved
       1 1 0    - reserved
       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. It should not be
  used for file parts which were split between volumes.

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
  of the file to be extracted or NULL as default. If DestName is defined
  (not NULL) it overrides the original file name saved in the archive and 
  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


====================================================================
void PASCAL RARSetCallback(HANDLE hArcData,
            int PASCAL (*CallbackProc)(UINT msg,LONG UserData,LONG P1,LONG P2),
            LONG 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 non-zero 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 non-zero 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 non-zero 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 unrar.dll version.

Parameters
~~~~~~~~~~
  None.

Return values
~~~~~~~~~~~~~
  Returns an integer value denoting DLL version. It is increased in case
of changes in DLL API. The current version value is defined in unrar.h
as RAR_DLL_VERSION

  This function is absent in old versions of unrar.dll, so it may be wise
to use LoadLibrary and GetProcAddress to access this function.