Table of Contents

Introduction
Type Declarations
The TUnRar Component
The EUnRarError Class
Downloading TUnRar
Sample Program
License Terms
History

Introduction

TUnRar is a simple wrapper around Eugene Roshal's unRAR.DLL.

Since RAR is one of the most compact archive formats, it was a good idea to write an archive lister and unpacker component for Builder. Unfortunately, I couldn't write a complete RAR archiver, but I could make a simple wrapper around the popular unRAR.DLL. Feel free to use the component in your own applications.

It might be strange at first that the component doesn't have any events. That's because I couldn't figure out how to write event handlers for unRAR.DLL. It uses callback functions as events, and it seems simple callback functions don't fit in the delegation model of the VCL. On the other hand, I don't think that this component really needs events.

Type Declarations

enum TResult

TResult defines result constants for the TUnRar component.

Description

TResult defines the following constants:

   code                      description
   ____________________________________________________________________
   resNone                   There is no result
   resOk                     Operation successful
   resNoMemory               Not enough memory
   resBadData                Bad data
   resBadArchive             Bad archive
   resOpenError              Open error
   resEndOfFile              End of archive
   resCloseError             Close error
   resCreateError            File create error
   resReadError              Read error
   resWriteError             Write error
   resUnknownFormat          Unknown archive format
   resDllError               Couldn't open UNRAR.DLL

enum TCommentState

TCommentState defines constants for the comment states.

Description

TCommentState defines the following constants:

   code                      description
   ____________________________________________________________________
   csNone                    Comment is absent
   csOk                      Comment read completely
   csNoMemory                Not enough memory to extract comments
   csBadData                 Broken comment
   csUnknownFormat           Unknown comment format

enum TFileFlag

TFileFlag defines constants for RAR archive flags.

Description

TFileFlag defines the following constants:

   code                      description
   ____________________________________________________________________
   ffPrevVolume              File continued from previous volume
   ffNextVolume              File continued on next volume
   ffPassword                File encrypted with password
   ffComment                 File comment present
   ffSolid                   Compression of previous files is used (solid archive)
   ffDirectory               File is a directory

typedef Set TFileFlags;

TFileFlags defines a set of TFileFlag constants.

enum THostOS { hosMsDos, hosOS2, hosWin32, hosUnix };

THostOS defines constants for the host operating system.

Description

THostOS defines the following constants:

   code                      description
   ____________________________________________________________________
   hosMsDos                  MS DOS
   hosOS2                    OS/2
   hosWin32                  Win32 (Win95/NT or Win98)
   hosUnix                   Unix

enum TRarOperation { opSkip, opTest, opExtract };

TRarOperation defines constants for a RAR operation.

Description

TRarOperation defines the following constants:

   code                      description
   ____________________________________________________________________
   opSkip                    Skip the current file
   opTest                    Test the current file
   opExtract                 Extract the current file

See also

Process

The TUnRar Component

published properties

__property AnsiString ArchiveName

ArchiveName contains the name of the RAR file to read.

Description

You must set the ArchiveName property before opening an archive. This is the only parameter that you must absolutely specify when using TUnRar.

See also

Open

__property bool Extract

Extract determines whether extraction is allowed from the archive.

Description

The default value for Extract is false, which means you can't extract files from the archive. When Extract is set false, you can only list an archive, but the operation is quite fast. If Extract is set to true, you can list, test, or extract a file in the archive, but even if you're just listing the archive, the operation is a bit slow compared to the Extract=false mode.

You must set Extract before opening an archive. Changing its value has no effect if an archive is open.

See also

Open, Process

__property AnsiString Password

Password contains the password.

Description

If no password is required, just set it to an empty string. Password can be set before or after opening an archive.

See also

Open

__property AnsiString DestPath

DestPath contains the destination path.

Description

Before extracting a file, you can set the DestPath property to the destination path. It can be an empty string, which means the destination path is the current directory.

See also

Process

__property bool ExceptionOnError

ExceptionOnError determines whether an exception is thrown if an error occurs.

Description

The default value for ExceptionOnError is true, which means an exception is thrown on error. If ExceptionOnError is false, no exception is thrown. Exception is never thrown if you're trying to process another file and there are no more files in the archive. In this case, only the Eof is set to true, and the Result is set to resEndOfFile.

See also

Eof, Result, Process

public properties

__property bool Active

Active determines whether an archive is open or not.

Description

The default value for Active is false. You can open an archive by setting Active to true, or by calling the Open method. You can close an archive by setting Active to false or by calling the Close method. An open archive must be closed before opening another one.

Note

When you open an archive, TUnRar automatically reads some information about the first file in the archive, including its name, size, date, and much more. To move on to the next file in the archive, just call the Process method.

See also

Open, Close, Process

__property TResult Result /* read-only */

Result contains the result of the last operation.

Description

If ExceptionOnError is set to false, check Result to see if an error occurred. Result contain resOk if there was no error, otherwise it contains the error code.

See also

TResult

__property bool Eof /* read-only */

Eof determines whether the end of file is reached.

Description

Eof is true if there are no more files to process in the archive. Otherwise it is false.

See also

Process

__property AnsiString ArchiveComment /* read-only */

ArchiveComment contains the comment for the archive.

Description

ArchiveComment is a part of the archive's header data. You can read it after opening an archive.

See also

ArchiveCommentState

__property TCommentState ArchiveCommentState /* read-only */

ArchiveCommentState contains the state of the archive's comment.

Description

ArchiveCommentState is a part of the archive's header data. You can read it after opening an archive.

See also

TCommentState, ArchiveComment

__property AnsiString FileName /* read-only */

FileName contains the name of the current file.

Description

FileName is a part of the current file's header data. You can read it after opening an archive.

__property AnsiString Comment /* read-only */

Comment contains the comment for the current file.

Description

Comment is a part of the current file's header data. You can read it after opening an archive.

See also

CommentState

__property TCommentState CommentState /* read-only */

CommentState contains the state of the file's comment.

Description

CommentState is a part of the current file's header data. You can read it after opening an archive.

See also

TCommentState, Comment

__property TFileFlags FileFlags /* read-only */

FileFlags contains the RAR flags for the current file.

Description

FileFlags is a part of the current file's header data. You can read it after opening an archive.

Note

FileFlags are not the DOS attributes for the file. They're in the Attr property.

See also

TFileFlags, Attr

__property int DictionarySize /* read-only */

DictionarySize contains the dictionary size.

Description

DictionarySize is a part of the current file's header data. You can read it after opening an archive.

DictionarySize can be 64 kB, 128 kB, 256 kB, 512 kB, or 1024 kB.

__property unsigned PackedSize /* read-only */

PackedSize contains the size of the packed file.

Description

PackedSize is a part of the current file's header data. You can read it after opening an archive.

See also

UnpackedSize

__property unsigned UnpackedSize /* read-only */

UnpackedSize contains the size of the unpacked file.

Description

UnpackedSize is a part of the current file's header data. You can read it after opening an archive.

See also

PackedSize

__property THostOS HostOS /* read-only */

HostOS contains information about the operating system on which the archive is created.

Description

HostOS is a part of the current file's header data. You can read it after opening an archive.

See also

THostOS

__property unsigned CRC /* read-only */

CRC contains the CRC for the current file.

Description

CRC is a part of the current file's header data. You can read it after opening an archive.

__property unsigned FileTime /* read-only */

FileTime contains the time of the current file.

Description

FileTime is a part of the current file's header data. You can read it after opening an archive.

FileTime can be converted into TDateTime by the FileDateToDateTime function. See the online help for more information.

__property int RarVersion /* read-only */

RarVersion contains the version number of the RAR archiver on which the archive is created.

Description

RarVersion is a part of the current file's header data. You can read it after opening an archive.

RarVersion is in the following format: 10 * major_version + minor_version

__property unsigned Attr /* read-only */

Attr contains the DOS attributes for the current file.

Description

Attr is a part of the current file's header data. You can read it after opening an archive.

static member variables

static AnsiString ChangeDiskTitle

ChangeDiskTitle contains the title of the ChangeDisk dialog box.

Description

If an archive consists of multiple volumes, there is always a chance that the next volume is not in the current path. In this case, TUnRar automatically pops up the standard Open dialog box. That's what I call the ChangeDisk dialog box. The user can change the disk or can specify a new folder for the next volume. The title of this dialog box can be set by assigning a new string to the ChangeDiskTitle member variable. The default value is Insert new disk.

ChangeDiskTitle is a static member variable, which means all TUnRar components share the same instance of variable.

See also

ChangeDiskModalResult

static TModalResult ChangeDiskModalResult

ChangeDiskModalResult contains the latest modal result of the ChangeDisk dialog box.

Description

ChangeDiskModalResult can be mrNone, mrOk, or mrCancel. It's mrNone if the dialog box was not yet poped up. ChangeDiskModalResult is mrOk if the user clicked the Open button. It's mrCancel if the user close the dialog box by clicking the Close button.

ChangeDiskModalResult is a static member variable, which means all TUnRar components share the same instance of variable.

If you just want to check if the user changed the disk and everything went Ok, you don't need to read the ChangeDiskModalResult variable. TUnRar automatically handles all kinds of errors, so if the user closes the ChangeDisk dialog box by clicking the Close button and the exceptions are turned on, an exception will occur. If the exceptions are turned off, you can check the return value of the Process method.

See also

ChangeDiskTitle, Process, ExceptionOnError

public methods

__fastcall TUnRar(Classes::TComponent* AOwner);

The constructor for the TUnRar component.

Note

The constructor doesn't open an archive.

__fastcall ~TUnRar();

The destructor for the TUnRar component.

Description

If there is an open archive, the destructor automatically closes it.

bool __fastcall Open();

Open opens an archive. The ArchiveName property must be set before you open an archive.

Description

Open opens an archive. It first reads the ArchiveName and the Extract properties, and then opens the archive. You cannot change the ArchiveName or the Extract properties after opening an archive, unless you close it first. Open reads the archive's header information, and the header information for the first file of the archive. You can move on to the next file by calling the Process method.

If everything is Ok, Open sets the Active property to true. Open returns false if an error occurred, otherwise it returns true. The Result property contains the result of the operation.

See also

Active, Close, Process

bool __fastcall Close();

Close closes an open archive.

Description

Close closes an archive and sets the Active property to false.

Close returns false if an error occurred, otherwise it returns true. The Result property contains the result of the operation.

See also

Active, Open

bool __fastcall Process(TRarOperation op=opSkip, AnsiString DestName="");

Process processes the current file and moves on to the next one.

Description

If the Extact property was set to true before opening the archive, Process can skip, test, or extract the current file. The operation depends on the op parameter. If it's opSkip, Process just skips the current file. If the op is opTest, Process tests the current file if it's not corrupted. Finally, if op is opExtract, Process extracts the current file. The DestPath property contains the output path or an empty string for the current path. If the DestName parameter contains an empty string, the destination file is going to have the same name as the current file name in the archive. Otherwise, DestName overrides the original file name saved in the archive and the DestPath setting. The default value for DestName is an empty string.

If the Extract property was set to false before opening the archive, no matter what you set in the op parameter, Process skips the current file.

Process returns false if an error occurred, otherwise it returns true. The Result property contains the result of the operation.

The EUnRarError Class

public properties

__property TResult Result; /* read-only */

This read-only property contains the result of the operation that has thrown the exception.

See also

TResult

public methods

__fastcall EUnRarError(TResult res)

This is the constructor for the EUnRarError class.

Downloading TUnRar

Download TUnRar for Borland C++Builder (file size: 42,013)

Sample Program

Here is a very easy sample program that lists an archive. Drop down a TListBox and a TUnRar component on your main form and add the following event handler to your program:

void __fastcall TForm1::FormCreate(TObject *Sender)
{
   UnRar1->ArchiveName = "temp.rar";
   UnRar1->Open();
   // while not end of archive
   while(UnRar1->Result==resOk)
   {
      // add the name and the size of the current file to the list box
      ListBox1->Items->Add(UnRar1->FileName + ", " + IntToStr(UnRar1->UnpackedSize));
      // move on to the next file
      UnRar1->Process();
   }
   // You can free some memory by closing an unused archive
   UnRar1->Close();
}

License Terms

1. The TUnRar component may be freely distributed and used in your own programs.
2. No person or company may charge fee for this component.
3. TUnRar IS DISTRIBUTED "AS IS". NO WARRANTY OF ANY KIND IS EXPRESSED OR IMPLIED. YOU USE AT YOUR OWN RISK. THE AUTHOR WILL NOT BE LIABLE FOR DATA LOSS, DAMAGES, LOSS OF PROFITS OR ANY OTHER KIND OF LOSS WHILE USING OR MISUSING THIS COMPONENT.
4. The protected and private members are undocumented, and they're subject to change.
5. You must agree with all terms of the original license of unRAR written by Eugene Roshal, which is included in the unrar.zip file.
6. If you don't agree with terms of the license you must remove TUnRar from your storage devices.

History

Version 1.2 (Jun 9, 1998)

A bug is fixed. In 1.1. an exception occurred on extraction.

Version 1.1 (Jun 7, 1998)

Now it works on both BCB 3.0 and BCB 1.0. A bug is fixed (the ExceptionOnError property was stuck at true).

Version 1.0 (Apr 26, 1998)

The first release of the component for C++Builder 1.0.