.TH "KArchive" kde3 "11 Jun 2005" "Version Version 3.4.1" "kio Library" \" -*- nroff -*-
.ad l
.nh
.SH NAME
KArchive \- KArchive is a base class for reading and writing archives. generic class for reading/writing archives.  

.PP
.SH SYNOPSIS
.br
.PP
\fC#include <karchive.h>\fP
.PP
Inherited by \fBKAr\fP, \fBKTar\fP, and \fBKZip\fP.
.PP
.SS "Public Member Functions"

.in +1c
.ti -1c
.RI "virtual bool \fBopen\fP (int mode)"
.br
.ti -1c
.RI "virtual void \fBclose\fP ()"
.br
.ti -1c
.RI "bool \fBisOpened\fP () const "
.br
.ti -1c
.RI "int \fBmode\fP () const "
.br
.ti -1c
.RI "\fBQIODevice\fP * \fBdevice\fP () const "
.br
.ti -1c
.RI "const \fBKArchiveDirectory\fP * \fBdirectory\fP () const "
.br
.ti -1c
.RI "bool \fBaddLocalFile\fP (const \fBQString\fP &fileName, const \fBQString\fP &destName)"
.br
.ti -1c
.RI "bool \fBaddLocalDirectory\fP (const \fBQString\fP &path, const \fBQString\fP &destName)"
.br
.ti -1c
.RI "virtual bool \fBwriteDir\fP (const \fBQString\fP &name, const \fBQString\fP &user, const \fBQString\fP &group)=0"
.br
.ti -1c
.RI "bool \fBwriteDir\fP (const \fBQString\fP &name, const \fBQString\fP &user, const \fBQString\fP &group, mode_t perm, time_t atime, time_t mtime, time_t ctime)"
.br
.ti -1c
.RI "bool \fBwriteSymLink\fP (const \fBQString\fP &name, const \fBQString\fP &target, const \fBQString\fP &user, const \fBQString\fP &group, mode_t perm, time_t atime, time_t mtime, time_t ctime)"
.br
.ti -1c
.RI "virtual bool \fBwriteFile\fP (const \fBQString\fP &name, const \fBQString\fP &user, const \fBQString\fP &group, uint size, const char *data)"
.br
.ti -1c
.RI "bool \fBwriteFile\fP (const \fBQString\fP &name, const \fBQString\fP &user, const \fBQString\fP &group, uint size, mode_t perm, time_t atime, time_t mtime, time_t ctime, const char *data)"
.br
.ti -1c
.RI "virtual bool \fBprepareWriting\fP (const \fBQString\fP &name, const \fBQString\fP &user, const \fBQString\fP &group, uint size)=0"
.br
.ti -1c
.RI "bool \fBprepareWriting\fP (const \fBQString\fP &name, const \fBQString\fP &user, const \fBQString\fP &group, uint size, mode_t perm, time_t atime, time_t mtime, time_t ctime)"
.br
.ti -1c
.RI "bool \fBwriteData\fP (const char *data, uint size)"
.br
.ti -1c
.RI "virtual bool \fBdoneWriting\fP (uint size)=0"
.br
.in -1c
.SS "Protected Types"

.in +1c
.ti -1c
.RI "enum { \fBVIRTUAL_WRITE_DATA\fP =  1, \fBVIRTUAL_WRITE_SYMLINK\fP, \fBVIRTUAL_WRITE_DIR\fP, \fBVIRTUAL_WRITE_FILE\fP, \fBVIRTUAL_PREPARE_WRITING\fP }"
.br
.in -1c
.SS "Protected Member Functions"

.in +1c
.ti -1c
.RI "\fBKArchive\fP (\fBQIODevice\fP *dev)"
.br
.ti -1c
.RI "virtual bool \fBopenArchive\fP (int mode)=0"
.br
.ti -1c
.RI "virtual bool \fBcloseArchive\fP ()=0"
.br
.ti -1c
.RI "virtual \fBKArchiveDirectory\fP * \fBrootDir\fP ()"
.br
.ti -1c
.RI "\fBKArchiveDirectory\fP * \fBfindOrCreate\fP (const \fBQString\fP &path)"
.br
.ti -1c
.RI "void \fBsetDevice\fP (\fBQIODevice\fP *dev)"
.br
.ti -1c
.RI "void \fBsetRootDir\fP (\fBKArchiveDirectory\fP *rootDir)"
.br
.ti -1c
.RI "virtual void \fBvirtual_hook\fP (int id, void *data)"
.br
.ti -1c
.RI "bool \fBprepareWriting_impl\fP (const \fBQString\fP &name, const \fBQString\fP &user, const \fBQString\fP &group, uint size, mode_t perm, time_t atime, time_t mtime, time_t ctime)"
.br
.ti -1c
.RI "bool \fBwriteFile_impl\fP (const \fBQString\fP &name, const \fBQString\fP &user, const \fBQString\fP &group, uint size, mode_t perm, time_t atime, time_t mtime, time_t ctime, const char *data)"
.br
.ti -1c
.RI "bool \fBwriteDir_impl\fP (const \fBQString\fP &name, const \fBQString\fP &user, const \fBQString\fP &group, mode_t perm, time_t atime, time_t mtime, time_t ctime)"
.br
.ti -1c
.RI "bool \fBwriteSymLink_impl\fP (const \fBQString\fP &name, const \fBQString\fP &target, const \fBQString\fP &user, const \fBQString\fP &group, mode_t perm, time_t atime, time_t mtime, time_t ctime)"
.br
.ti -1c
.RI "bool \fBwriteData_impl\fP (const char *data, uint size)"
.br
.in -1c
.SH "Detailed Description"
.PP 
KArchive is a base class for reading and writing archives. generic class for reading/writing archives. 

\fBAuthor:\fP
.RS 4
David Faure <faure@kde.org> 
.RE
.PP

.PP
Definition at line 42 of file karchive.h.
.SH "Constructor & Destructor Documentation"
.PP 
.SS "KArchive::KArchive (\fBQIODevice\fP * dev)\fC [protected]\fP"
.PP
Base constructor (protected since this is a pure virtual class). 
.PP
\fBParameters:\fP
.RS 4
\fIdev\fP the I/O device where the archive reads its data Note that this can be a file, but also a data buffer, a compression filter, etc. 
.RE
.PP

.PP
Definition at line 74 of file karchive.cpp.
.SH "Member Function Documentation"
.PP 
.SS "bool KArchive::open (int mode)\fC [virtual]\fP"
.PP
Opens the archive for reading or writing. 
.PP
Inherited classes might want to reimplement openArchive instead. 
.PP
\fBParameters:\fP
.RS 4
\fImode\fP may be IO_ReadOnly or IO_WriteOnly 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBclose\fP 
.RE
.PP

.PP
Definition at line 90 of file karchive.cpp.
.PP
References close(), QIODevice::open(), and openArchive().
.PP
Referenced by KZip::openArchive().
.SS "void KArchive::close ()\fC [virtual]\fP"
.PP
Closes the archive. 
.PP
Inherited classes might want to reimplement closeArchive instead.
.PP
\fBSee also:\fP
.RS 4
\fBopen\fP 
.RE
.PP

.PP
Definition at line 107 of file karchive.cpp.
.PP
References QIODevice::close(), and closeArchive().
.PP
Referenced by open(), KAr::~KAr(), KTar::~KTar(), and KZip::~KZip().
.SS "bool KArchive::isOpened () const\fC [inline]\fP"
.PP
Checks whether the archive is open. 
.PP
\fBReturns:\fP
.RS 4
true if the archive is opened 
.RE
.PP

.PP
Definition at line 75 of file karchive.h.
.PP
Referenced by KTar::setOrigFileName(), KTar::writeDir(), KAr::~KAr(), KTar::~KTar(), and KZip::~KZip().
.SS "int KArchive::mode () const\fC [inline]\fP"
.PP
Returns the mode in which the archive was opened. 
.PP
\fBReturns:\fP
.RS 4
the mode in which the archive was opened (IO_ReadOnly or IO_WriteOnly) 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBopen()\fP 
.RE
.PP

.PP
Definition at line 82 of file karchive.h.
.PP
Referenced by KZip::closeArchive(), KTar::closeArchive(), KTar::doneWriting(), KTar::setOrigFileName(), and KTar::writeDir().
.SS "\fBQIODevice\fP* KArchive::device () const\fC [inline]\fP"
.PP
The underlying device. 
.PP
\fBReturns:\fP
.RS 4
the underlying device. 
.RE
.PP

.PP
Definition at line 88 of file karchive.h.
.PP
Referenced by KZip::closeArchive(), KArchiveFile::data(), KZip::doneWriting(), KTar::doneWriting(), KZip::openArchive(), KTar::openArchive(), KAr::openArchive(), KTar::writeDir(), KAr::~KAr(), KTar::~KTar(), and KZip::~KZip().
.SS "const \fBKArchiveDirectory\fP * KArchive::directory () const"
.PP
If an archive is opened for reading, then the contents of the archive can be accessed via this function. 
.PP
\fBReturns:\fP
.RS 4
the directory of the archive 
.RE
.PP

.PP
Definition at line 123 of file karchive.cpp.
.SS "bool KArchive::addLocalFile (const \fBQString\fP & fileName, const \fBQString\fP & destName)"
.PP
Writes a local file into the archive. 
.PP
The main difference with writeFile, is that this method minimizes memory usage, by not loading the whole file into memory in one go.
.PP
If \fCfileName\fP is a symbolic link, it will be written as is, i. e. it will not be resolved before. 
.PP
\fBParameters:\fP
.RS 4
\fIfileName\fP full path to an existing local file, to be added to the archive. 
.br
\fIdestName\fP the resulting name (or relative path) of the file in the archive. 
.RE
.PP

.PP
Definition at line 130 of file karchive.cpp.
.PP
References doneWriting(), endl(), QFileInfo::group(), QFileInfo::isFile(), QFileInfo::isSymLink(), kdWarning(), QFile::open(), QFileInfo::owner(), prepareWriting(), QFileInfo::readLink(), QFileInfo::size(), writeData(), and writeSymLink().
.PP
Referenced by addLocalDirectory().
.SS "bool KArchive::addLocalDirectory (const \fBQString\fP & path, const \fBQString\fP & destName)"
.PP
Writes a local directory into the archive, including all its contents, recursively. 
.PP
Calls addLocalFile for each file to be added.
.PP
Since \fBKDE\fP 3.2 it will also add a \fCpath\fP that is a symbolic link to a directory. The symbolic link will be dereferenced and the content of the directory it is pointing to added recursively. However, symbolic links *under* \fCpath\fP will be stored as is. 
.PP
\fBParameters:\fP
.RS 4
\fIpath\fP full path to an existing local directory, to be added to the archive. 
.br
\fIdestName\fP the resulting name (or relative path) of the file in the archive. 
.RE
.PP

.PP
Definition at line 194 of file karchive.cpp.
.PP
References addLocalFile(), QDir::entryList(), QDir::exists(), QFileInfo::isDir(), QFileInfo::isFile(), and QFileInfo::isSymLink().
.SS "virtual bool KArchive::writeDir (const \fBQString\fP & name, const \fBQString\fP & user, const \fBQString\fP & group)\fC [pure virtual]\fP"
.PP
If an archive is opened for writing then you can add new directories using this function. 
.PP
KArchive won't write one directory twice.
.PP
\fBParameters:\fP
.RS 4
\fIname\fP the name of the directory 
.br
\fIuser\fP the user that owns the directory 
.br
\fIgroup\fP the group that owns the directory // TODO(BIC): make this a thin wrapper around // writeDir(name,user,group,perm,atime,mtime,ctime) // or elimitate it 
.RE
.PP

.PP
Implemented in \fBKAr\fP, \fBKTar\fP, and \fBKZip\fP.
.PP
Referenced by KTar::writeDir().
.SS "bool KArchive::writeDir (const \fBQString\fP & name, const \fBQString\fP & user, const \fBQString\fP & group, mode_t perm, time_t atime, time_t mtime, time_t ctime)"
.PP
If an archive is opened for writing then you can add new directories using this function. 
.PP
KArchive won't write one directory twice.
.PP
This method also allows some file metadata to be set. However, depending on the archive type not all metadata might be regarded. 
.PP
\fBParameters:\fP
.RS 4
\fIname\fP the name of the directory 
.br
\fIuser\fP the user that owns the directory 
.br
\fIgroup\fP the group that owns the directory 
.br
\fIperm\fP permissions of the directory 
.br
\fIatime\fP time the file was last accessed 
.br
\fImtime\fP modification time of the file 
.br
\fIctime\fP creation time of the file 
.RE
.PP
\fBSince:\fP
.RS 4
3.2 // TODO(BIC): make this virtual. For now use virtual hook 
.RE
.PP

.PP
Reimplemented in \fBKTar\fP.
.PP
Definition at line 297 of file karchive.cpp.
.SS "bool KArchive::writeSymLink (const \fBQString\fP & name, const \fBQString\fP & target, const \fBQString\fP & user, const \fBQString\fP & group, mode_t perm, time_t atime, time_t mtime, time_t ctime)"
.PP
Writes a symbolic link to the archive if the archive must be opened for writing. 
.PP
\fBParameters:\fP
.RS 4
\fIname\fP name of symbolic link 
.br
\fItarget\fP target of symbolic link 
.br
\fIuser\fP the user that owns the directory 
.br
\fIgroup\fP the group that owns the directory 
.br
\fIperm\fP permissions of the directory 
.br
\fIatime\fP time the file was last accessed 
.br
\fImtime\fP modification time of the file 
.br
\fIctime\fP creation time of the file 
.RE
.PP
\fBSince:\fP
.RS 4
3.2 // TODO(BIC) make virtual. For now it must be implemented by virtual_hook. 
.RE
.PP

.PP
Reimplemented in \fBKTar\fP, and \fBKZip\fP.
.PP
Definition at line 320 of file karchive.cpp.
.PP
Referenced by addLocalFile(), KZip::writeSymLink(), and KTar::writeSymLink().
.SS "bool KArchive::writeFile (const \fBQString\fP & name, const \fBQString\fP & user, const \fBQString\fP & group, uint size, const char * data)\fC [virtual]\fP"
.PP
If an archive is opened for writing then you can add a new file using this function. 
.PP
If the file name is for example 'mydir/test1' then the directory 'mydir' is automatically appended first if that did not happen yet. 
.PP
\fBParameters:\fP
.RS 4
\fIname\fP the name of the file 
.br
\fIuser\fP the user that owns the file 
.br
\fIgroup\fP the group that owns the file 
.br
\fIsize\fP the size of the file 
.br
\fIdata\fP the data to write (\fCsize\fP bytes) // TODO(BIC): make this a thin non-virtual wrapper around // writeFile(name,user,group,size,perm,atime,mtime,ctime,data) 
.RE
.PP

.PP
Reimplemented in \fBKZip\fP.
.PP
Definition at line 221 of file karchive.cpp.
.PP
Referenced by KZip::writeFile().
.SS "bool KArchive::writeFile (const \fBQString\fP & name, const \fBQString\fP & user, const \fBQString\fP & group, uint size, mode_t perm, time_t atime, time_t mtime, time_t ctime, const char * data)"
.PP
If an archive is opened for writing then you can add a new file using this function. 
.PP
If the file name is for example 'mydir/test1' then the directory 'mydir' is automatically appended first if that did not happen yet.
.PP
This method also allows some file metadata to be set. However, depending on the archive type not all metadata might be regarded. 
.PP
\fBParameters:\fP
.RS 4
\fIname\fP the name of the file 
.br
\fIuser\fP the user that owns the file 
.br
\fIgroup\fP the group that owns the file 
.br
\fIsize\fP the size of the file 
.br
\fIperm\fP permissions of the file 
.br
\fIatime\fP time the file was last accessed 
.br
\fImtime\fP modification time of the file 
.br
\fIctime\fP creation time of the file 
.br
\fIdata\fP the data to write (\fCsize\fP bytes) 
.RE
.PP
\fBSince:\fP
.RS 4
3.2 // TODO(BIC): make virtual. For now use virtual hook 
.RE
.PP

.PP
Reimplemented in \fBKZip\fP.
.PP
Definition at line 252 of file karchive.cpp.
.SS "virtual bool KArchive::prepareWriting (const \fBQString\fP & name, const \fBQString\fP & user, const \fBQString\fP & group, uint size)\fC [pure virtual]\fP"
.PP
Here's another way of writing a file into an archive: Call prepareWriting, then call \fBwriteData()\fP as many times as wanted then call doneWriting( totalSize ). 
.PP
For tar.gz files, you need to know the size before hand, since it is needed in the header. For zip files, size isn't used.
.PP
\fBParameters:\fP
.RS 4
\fIname\fP the name of the file 
.br
\fIuser\fP the user that owns the file 
.br
\fIgroup\fP the group that owns the file 
.br
\fIsize\fP the size of the file // TODO(BIC): make this a thin non-virtual wrapper around // prepareWriting(name,user,group,size,perm,atime,mtime,ctime) or eliminate it. 
.RE
.PP

.PP
Implemented in \fBKAr\fP, \fBKTar\fP, and \fBKZip\fP.
.PP
Referenced by addLocalFile(), KZip::prepareWriting(), and KTar::prepareWriting().
.SS "bool KArchive::prepareWriting (const \fBQString\fP & name, const \fBQString\fP & user, const \fBQString\fP & group, uint size, mode_t perm, time_t atime, time_t mtime, time_t ctime)"
.PP
Here's another way of writing a file into an archive: Call prepareWriting, then call \fBwriteData()\fP as many times as wanted then call doneWriting( totalSize ). 
.PP
For tar.gz files, you need to know the size before hand, it is needed in the header! For zip files, size isn't used.
.PP
This method also allows some file metadata to be set. However, depending on the archive type not all metadata might be regarded. 
.PP
\fBParameters:\fP
.RS 4
\fIname\fP the name of the file 
.br
\fIuser\fP the user that owns the file 
.br
\fIgroup\fP the group that owns the file 
.br
\fIsize\fP the size of the file 
.br
\fIperm\fP permissions of the file 
.br
\fIatime\fP time the file was last accessed 
.br
\fImtime\fP modification time of the file 
.br
\fIctime\fP creation time of the file 
.RE
.PP
\fBSince:\fP
.RS 4
3.2 // TODO(BIC): make this virtual. For now use virtual hook. 
.RE
.PP

.PP
Reimplemented in \fBKTar\fP, and \fBKZip\fP.
.PP
Definition at line 228 of file karchive.cpp.
.SS "bool KArchive::writeData (const char * data, uint size)"
.PP
Write data into the current file - to be called after calling prepareWriting // TODO(BIC) make virtual. 
.PP
For now virtual_hook allows reimplementing it. 
.PP
Reimplemented in \fBKZip\fP.
.PP
Definition at line 346 of file karchive.cpp.
.PP
Referenced by addLocalFile(), and KZip::writeData().
.SS "virtual bool KArchive::doneWriting (uint size)\fC [pure virtual]\fP"
.PP
Call doneWriting after writing the data. 
.PP
\fBParameters:\fP
.RS 4
\fIsize\fP the size of the file 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBprepareWriting()\fP 
.RE
.PP

.PP
Implemented in \fBKAr\fP, \fBKTar\fP, and \fBKZip\fP.
.PP
Referenced by addLocalFile().
.SS "virtual bool KArchive::openArchive (int mode)\fC [protected, pure virtual]\fP"
.PP
Opens an archive for reading or writing. 
.PP
Called by open. 
.PP
\fBParameters:\fP
.RS 4
\fImode\fP may be IO_ReadOnly or IO_WriteOnly 
.RE
.PP

.PP
Implemented in \fBKAr\fP, \fBKTar\fP, and \fBKZip\fP.
.PP
Referenced by open().
.SS "virtual bool KArchive::closeArchive ()\fC [protected, pure virtual]\fP"
.PP
Closes the archive. 
.PP
Called by close. 
.PP
Implemented in \fBKAr\fP, \fBKTar\fP, and \fBKZip\fP.
.PP
Referenced by close().
.SS "\fBKArchiveDirectory\fP * KArchive::rootDir ()\fC [protected, virtual]\fP"
.PP
Retrieves or create the root directory. 
.PP
The default implementation assumes that \fBopenArchive()\fP did the parsing, so it creates a dummy rootdir if none was set (write mode, or no '/' in the archive). Reimplement this to provide parsing/listing on demand. 
.PP
\fBReturns:\fP
.RS 4
the root directory 
.RE
.PP

.PP
Definition at line 361 of file karchive.cpp.
.PP
References QFile::decodeName(), and QString::number().
.PP
Referenced by findOrCreate(), KZip::openArchive(), KTar::openArchive(), and KAr::openArchive().
.SS "\fBKArchiveDirectory\fP * KArchive::findOrCreate (const \fBQString\fP & path)\fC [protected]\fP"
.PP
Ensures that \fCpath\fP exists, create otherwise. 
.PP
This handles e.g. tar files missing directory entries, like mico-2.3.0.tar.gz :) 
.PP
\fBParameters:\fP
.RS 4
\fIpath\fP the path of the directory 
.RE
.PP
\fBReturns:\fP
.RS 4
the directory with the given \fCpath\fP 
.RE
.PP

.PP
Definition at line 376 of file karchive.cpp.
.PP
References KArchiveDirectory::addEntry(), KArchiveDirectory::entry(), KArchiveEntry::isDirectory(), QString::left(), QString::mid(), and rootDir().
.PP
Referenced by KZip::openArchive(), and KTar::openArchive().

.SH "Author"
.PP 
Generated automatically by Doxygen for kio Library from the source code.
