CFileTar 1.0 - pack and unpack file archives

• Download source project - 3 Kb

Overview

CFileTar is a C++ class [written using plain C++ and a little Win API] that allows you to tar and untar files. People who are familiar with Unix will surely have used the tar archiving utility. This class attempts to provide a rather simple version for Win 32 programmers. Please note that this class does not produce unix-style tar files. It uses it's own custom format to tar and untar the files.

Features

• MFC not required
• Tar multiple files into a single archive
• UnTar files either singly, or as a whole from the archive
• Query a tar file for information
• Works with text and binary files

Usage

Tarring files

Tarring several files into a single tar archive can be easily achieved through the following steps.

CFileTar ft;
ft.SetHeaderDescription("This archive contains several pdf/doc files");

//Let's add some doc files
ft.SetFilePath("D:\\nish\\worddocs");
ft.AddFile("Proposal.doc","First project proposal");
ft.AddFile("ProjectPlan.doc","Project plan");
ft.AddFile("ProposalFinal.doc","Final proposal");

//Now some PDFs
ft.SetFilePath("D:\\nish\\pdffiles");
ft.AddFile("SRS.pdf","SRS doc template");
ft.AddFile("DDD.pdf","Detailed design doc template");

//Let's tar it now...
ft.CreateTar("ProjFiles.tar");

Querying tar files

Sometimes, you might want to retrieve information about a tar file. CFileTar provides a couple of static functions just for this purpose.

CFileTar::TarHeader t;
CFileTar::GetTarInfo("D:\\nish\\files.tar",&t);
cout << "Number of archived files : " << t.GetCount() << "\r\n";
cout << "Description of tar file : " << t.GetDescription() << "\r\n";

You can also retrieve information about individual files.

CFileTar::TarIndex ti;
for (int y=1;y<=t.GetCount();y++)
{
    CFileTar::GetFileInfo("D:\\nish\\files.tar",
        &ti,y);
    cout << "File Index : " << y << "\r\n";
    cout << "File Name : " << ti.FileName << "\r\n";
    cout << "File desc : " << ti.Description << "\r\n";
    cout << "Size : " << ti.Size << "\r\n";
}

Un-Tarring files

Un-Tarring individual files :-

CFileTar::UnTar("D:\\nish\\files.tar",3,
    "D:\\nish\\q1.xls");	

CFileTar::UnTar("D:\\nish\\files.tar",5,
    "D:\\nish\\sw34.doc");

Un-Tarring all files in a tar file :-

CFileTar::UnTar("D:\\nish\\files.tar",
    "D:\\nish\\temp");

Function Reference

CFileTar::CFileTar

CFileTar();

Remarks :- Creates a CFileTar object.

CFileTar::SetHeaderDescription

BOOL SetHeaderDescription(char *strdesc);

Return Value :- This will return true if the header was successfully set, else it will return false.

Parameters :-

strdesc - This is the header description string

Remarks :- Use this function to set the tar file's header description. This will prove useful when querying tar files.

CFileTar::GetHeaderDescription

const char* GetHeaderDescription();

Return Value :- This will return the tar file's header description

Remarks :- This function can be used to retrieve a const char* to the header description.

CFileTar::SetFilePath

void SetFilePath(char *path);

Parameters :-

path - This is the directory to search for the files being added to the tar archive.

Remarks :- Set the file path before adding files into the archive. You may change the file path any number of times, as you keep adding files from different folders.

CFileTar::AddFile

int AddFile(char *fname, char *desc);

Return Value :- Returns 0 if the file was successfully added to the list of files, else it returns 1.

Parameters :-

fname - The filename of the file to add, excluding the directory where it resides

desc - A description which is saved as meta-information on a per-file basis.

Remarks :- This function won't actually add the files to the tar. Instead it will add the filename with meta-info to a list of files to be tarred. The physical archiving process only takes place when the CreateTar function is called.

CFileTar::CreateTar

int CreateTar(char *TarFName, char* TarPath=NULL);

Return Value :- Returns 0 if the tar was successfully created, else returns 1

Parameters :-

TarFName - The filename of the tar file to create, excluding the directory path.

TarPath - The directory to create the tar file in. If not specified, then the last tar-files directory set using SetFilePath will be used as the default directory.

Remarks :- This is the function that actually creates the tar archive. If several huge files are being tarred, this function will obviously take quite a bit of time.

CFileTar::GetTarInfo

static int GetTarInfo(char *TarFile, TarHeader *pTarHeader);

Return Value :- Returns 0 if successful, else returns 1.

Parameters :-

TarFile - Fully qualified path and filename of the tar file.

pTarHeader - A pointer to a TarHeader object, that receives the information

Remarks :- Use this function to retrieve the Tar file header and the total number of files in the tar archive.

CFileTar::TarHeader::GetCount

int GetCount();

Return Value :- Returns the number of files in the tar archive.

Remarks :- Call this function on the TarHeader object that has been passed to a successful GetTarInfo function call.

CFileTar::TarHeader::GetDescription

const char* GetDescription();

Return Value :- Returns the tar header description.

Remarks :- Call this function on the TarHeader object that has been passed to a successful GetTarInfo function call.

CFileTar::GetFileInfo

static int GetFileInfo(char *TarFile, TarIndex *pTarIndex, int index);

Return Value :- Returns 0 if successful, else returns 1.

Parameters :-

TarFile - Fully qualified path and filename of the tar file.

pTarIndex - A pointer to a TarIndex object that will receive the information.

index - Index of file within the archive. The index is one-based.

Remarks :- The TarIndex object that we pass will contain the required information after a successful call to this function.

CFileTar::TarIndex

struct TarIndex
{
    long Start;
    long Size;
    char FileName[_MAX_FNAME];
    char Description[256];
}

Start - This is the start position of the file within the archive. The user need not bother with this field.

Size - This is the size of the file in bytes

FileName - This is the original filename

Description - This is the file description

CFileTar::UnTar

• static int UnTar(char *TarFile, char *dpath);
• static int UnTar(char *TarFile, int index, char *fpath);

Return Value :- Returns 0 if successful, else returns 1.

Parameters :-

TarFile - Fully qualified path and filename of the tar file.

dpath - The directory to extract all files in the archive to. The original filenames will be used for each file in the archive.

index - Index of the file within the archive. One-based index.

fpath - Fully qualified path and filename to be used for the file to be extracted.

Remarks :- The first override of this function will extract all files in the tar archive to the directory specified. The default filenames will be used for each extracted file. The second override is used to extract individual files. For this version, you'll need to specify a fully qualified filename with path for the extracted file.