KArchive 5.109.0
Public Member Functions | Protected Member Functions | List of all members
KArchiveabstract

KArchive is a base class for reading and writing archives. More...

#include <KArchive>

Public Member Functions

bool addLocalDirectory (const QString &path, const QString &destName)
 Writes a local directory into the archive, including all its contents, recursively.
 
bool addLocalFile (const QString &fileName, const QString &destName)
 Writes a local file into the archive.
 
virtual bool close ()
 Closes the archive.
 
QIODevice * device () const
 The underlying device.
 
const KArchiveDirectorydirectory () const
 If an archive is opened for reading, then the contents of the archive can be accessed via this function.
 
QString errorString () const
 Returns a description of the last error.
 
QString fileName () const
 The name of the archive file, as passed to the constructor that takes a fileName, or an empty string if you used the QIODevice constructor.
 
bool finishWriting (qint64 size)
 Call finishWriting after writing the data.
 
bool isOpen () const
 Checks whether the archive is open.
 
QIODevice::OpenMode mode () const
 Returns the mode in which the archive was opened.
 
virtual bool open (QIODevice::OpenMode mode)
 Opens the archive for reading or writing.
 
bool prepareWriting (const QString &name, const QString &user, const QString &group, qint64 size, mode_t perm=0100644, const QDateTime &atime=QDateTime(), const QDateTime &mtime=QDateTime(), const QDateTime &ctime=QDateTime())
 Here's another way of writing a file into an archive: Call prepareWriting(), then call writeData() as many times as wanted then call finishWriting( totalSize ).
 
virtual bool writeData (const char *data, qint64 size)
 Write data into the current file - to be called after calling prepareWriting.
 
bool writeDir (const QString &name, const QString &user=QString(), const QString &group=QString(), mode_t perm=040755, const QDateTime &atime=QDateTime(), const QDateTime &mtime=QDateTime(), const QDateTime &ctime=QDateTime())
 If an archive is opened for writing then you can add new directories using this function.
 
bool writeFile (const QString &name, const QByteArray &data, mode_t perm=0100644, const QString &user=QString(), const QString &group=QString(), const QDateTime &atime=QDateTime(), const QDateTime &mtime=QDateTime(), const QDateTime &ctime=QDateTime())
 Writes a new file into the archive.
 
bool writeFile (const QString &name, const QString &user, const QString &group, const char *data, qint64 size, mode_t perm=0100644, const QDateTime &atime=QDateTime(), const QDateTime &mtime=QDateTime(), const QDateTime &ctime=QDateTime())
 
bool writeSymLink (const QString &name, const QString &target, const QString &user=QString(), const QString &group=QString(), mode_t perm=0120755, const QDateTime &atime=QDateTime(), const QDateTime &mtime=QDateTime(), const QDateTime &ctime=QDateTime())
 Writes a symbolic link to the archive if supported.
 

Protected Member Functions

 KArchive (const QString &fileName)
 Base constructor (protected since this is a pure virtual class).
 
 KArchive (QIODevice *dev)
 Base constructor (protected since this is a pure virtual class).
 
virtual bool closeArchive ()=0
 Closes the archive.
 
virtual bool createDevice (QIODevice::OpenMode mode)
 Can be reimplemented in order to change the creation of the device (when using the fileName constructor).
 
virtual bool doFinishWriting (qint64 size)=0
 Called after writing the data.
 
virtual bool doPrepareWriting (const QString &name, const QString &user, const QString &group, qint64 size, mode_t perm, const QDateTime &atime, const QDateTime &mtime, const QDateTime &ctime)=0
 This virtual method must be implemented by subclasses.
 
virtual bool doWriteDir (const QString &name, const QString &user, const QString &group, mode_t perm, const QDateTime &atime, const QDateTime &mtime, const QDateTime &ctime)=0
 Write a directory to the archive.
 
virtual bool doWriteSymLink (const QString &name, const QString &target, const QString &user, const QString &group, mode_t perm, const QDateTime &atime, const QDateTime &mtime, const QDateTime &ctime)=0
 Writes a symbolic link to the archive.
 
KArchiveDirectoryfindOrCreate (const QString &path)
 Ensures that path exists, create otherwise.
 
virtual bool openArchive (QIODevice::OpenMode mode)=0
 Opens an archive for reading or writing.
 
virtual KArchiveDirectoryrootDir ()
 Retrieves or create the root directory.
 
void setDevice (QIODevice *dev)
 Can be called by derived classes in order to set the underlying device.
 
void setErrorString (const QString &errorStr)
 Sets error description.
 
void setRootDir (KArchiveDirectory *rootDir)
 Derived classes call setRootDir from openArchive, to set the root directory after parsing an existing archive.
 
virtual void virtual_hook (int id, void *data)
 

Detailed Description

KArchive is a base class for reading and writing archives.

generic class for reading/writing archives

Author
David Faure faure.nosp@m.@kde.nosp@m..org

Constructor & Destructor Documentation

◆ KArchive() [1/2]

KArchive::KArchive ( const QString &  fileName)
protected

Base constructor (protected since this is a pure virtual class).

Parameters
fileNameis a local path (e.g. "/tmp/myfile.ext"), from which the archive will be read from, or into which the archive will be written, depending on the mode given to open().

◆ KArchive() [2/2]

KArchive::KArchive ( QIODevice *  dev)
protected

Base constructor (protected since this is a pure virtual class).

Parameters
devthe 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. For a file in writing mode it is better to use the other constructor though, to benefit from the use of QSaveFile when saving.

Member Function Documentation

◆ addLocalDirectory()

bool KArchive::addLocalDirectory ( const QString &  path,
const QString &  destName 
)

Writes a local directory into the archive, including all its contents, recursively.

Calls addLocalFile for each file to be added.

It will also add a path 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 path will be stored as is.

Parameters
pathfull path to an existing local directory, to be added to the archive.
destNamethe resulting name (or relative path) of the file in the archive.

◆ addLocalFile()

bool KArchive::addLocalFile ( const QString &  fileName,
const QString &  destName 
)

Writes a local file into the archive.

The main difference with writeFile, is that this method minimizes memory usage, by not loading the whole file into memory in one go.

If fileName is a symbolic link, it will be written as is, i. e. it will not be resolved before.

Parameters
fileNamefull path to an existing local file, to be added to the archive.
destNamethe resulting name (or relative path) of the file in the archive.

◆ close()

virtual bool KArchive::close ( )
virtual

Closes the archive.

Inherited classes might want to reimplement closeArchive instead.

Returns
true if close succeeded without problems
See also
open

◆ closeArchive()

virtual bool KArchive::closeArchive ( )
protectedpure virtual

Closes the archive.

Called by close.

Implemented in K7Zip, KAr, KRcc, KTar, and KZip.

◆ createDevice()

virtual bool KArchive::createDevice ( QIODevice::OpenMode  mode)
protectedvirtual

Can be reimplemented in order to change the creation of the device (when using the fileName constructor).

By default this method uses QSaveFile when saving, and a simple QFile on reading. This method is called by open().

Reimplemented in KTar.

◆ device()

QIODevice * KArchive::device ( ) const

The underlying device.

Returns
the underlying device.

◆ directory()

const KArchiveDirectory * KArchive::directory ( ) const

If an archive is opened for reading, then the contents of the archive can be accessed via this function.

Returns
the directory of the archive

◆ doFinishWriting()

virtual bool KArchive::doFinishWriting ( qint64  size)
protectedpure virtual

Called after writing the data.

This virtual method must be implemented by subclasses.

Parameters
sizethe size of the file
See also
finishWriting()

Implemented in K7Zip, KAr, KRcc, KTar, and KZip.

◆ doPrepareWriting()

virtual bool KArchive::doPrepareWriting ( const QString &  name,
const QString &  user,
const QString &  group,
qint64  size,
mode_t  perm,
const QDateTime &  atime,
const QDateTime &  mtime,
const QDateTime &  ctime 
)
protectedpure virtual

This virtual method must be implemented by subclasses.

Depending on the archive type not all metadata might be used.

Parameters
namethe name of the file
userthe user that owns the file
groupthe group that owns the file
sizethe size of the file
permpermissions of the file. Use 0100644 if you don't have any more specific permissions to set.
atimetime the file was last accessed
mtimemodification time of the file
ctimetime of last status change
See also
prepareWriting

Implemented in KZip, K7Zip, KAr, KRcc, and KTar.

◆ doWriteDir()

virtual bool KArchive::doWriteDir ( const QString &  name,
const QString &  user,
const QString &  group,
mode_t  perm,
const QDateTime &  atime,
const QDateTime &  mtime,
const QDateTime &  ctime 
)
protectedpure virtual

Write a directory to the archive.

This virtual method must be implemented by subclasses.

Depending on the archive type not all metadata might be used.

Parameters
namethe name of the directory
userthe user that owns the directory
groupthe group that owns the directory
permpermissions of the directory. Use 040755 if you don't have any other information.
atimetime the file was last accessed
mtimemodification time of the file
ctimetime of last status change
See also
writeDir

Implemented in K7Zip, KAr, KRcc, KTar, and KZip.

◆ doWriteSymLink()

virtual bool KArchive::doWriteSymLink ( const QString &  name,
const QString &  target,
const QString &  user,
const QString &  group,
mode_t  perm,
const QDateTime &  atime,
const QDateTime &  mtime,
const QDateTime &  ctime 
)
protectedpure virtual

Writes a symbolic link to the archive.

This virtual method must be implemented by subclasses.

Parameters
namename of symbolic link
targettarget of symbolic link
userthe user that owns the directory
groupthe group that owns the directory
permpermissions of the directory
atimetime the file was last accessed
mtimemodification time of the file
ctimetime of last status change
See also
writeSymLink

Implemented in K7Zip, KAr, KRcc, KTar, and KZip.

◆ errorString()

QString KArchive::errorString ( ) const

Returns a description of the last error.

Since
5.29

◆ fileName()

QString KArchive::fileName ( ) const

The name of the archive file, as passed to the constructor that takes a fileName, or an empty string if you used the QIODevice constructor.

Returns
the name of the file, or QString() if unknown

◆ findOrCreate()

KArchiveDirectory * KArchive::findOrCreate ( const QString &  path)
protected

Ensures that path exists, create otherwise.

This handles e.g. tar files missing directory entries, like mico-2.3.0.tar.gz :)

Parameters
paththe path of the directory
Returns
the directory with the given path

◆ finishWriting()

bool KArchive::finishWriting ( qint64  size)

Call finishWriting after writing the data.

Parameters
sizethe size of the file
See also
prepareWriting()

◆ isOpen()

bool KArchive::isOpen ( ) const

Checks whether the archive is open.

Returns
true if the archive is opened

◆ mode()

QIODevice::OpenMode KArchive::mode ( ) const

Returns the mode in which the archive was opened.

Returns
the mode in which the archive was opened (QIODevice::ReadOnly or QIODevice::WriteOnly)
See also
open()

◆ open()

virtual bool KArchive::open ( QIODevice::OpenMode  mode)
virtual

Opens the archive for reading or writing.

Inherited classes might want to reimplement openArchive instead.

Parameters
modemay be QIODevice::ReadOnly or QIODevice::WriteOnly
See also
close

◆ openArchive()

virtual bool KArchive::openArchive ( QIODevice::OpenMode  mode)
protectedpure virtual

Opens an archive for reading or writing.

Called by open.

Parameters
modemay be QIODevice::ReadOnly or QIODevice::WriteOnly

Implemented in K7Zip, KAr, KRcc, KTar, and KZip.

◆ prepareWriting()

bool KArchive::prepareWriting ( const QString &  name,
const QString &  user,
const QString &  group,
qint64  size,
mode_t  perm = 0100644,
const QDateTime &  atime = QDateTime(),
const QDateTime &  mtime = QDateTime(),
const QDateTime &  ctime = QDateTime() 
)

Here's another way of writing a file into an archive: Call prepareWriting(), then call writeData() as many times as wanted then call finishWriting( totalSize ).

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.

This method also allows some file metadata to be set. However, depending on the archive type not all metadata might be regarded.

Parameters
namethe name of the file
userthe user that owns the file
groupthe group that owns the file
sizethe size of the file
permpermissions of the file
atimetime the file was last accessed
mtimemodification time of the file
ctimetime of last status change

◆ rootDir()

virtual KArchiveDirectory * KArchive::rootDir ( )
protectedvirtual

Retrieves or create the root directory.

The default implementation assumes that openArchive() 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.

Returns
the root directory

◆ setDevice()

void KArchive::setDevice ( QIODevice *  dev)
protected

Can be called by derived classes in order to set the underlying device.

Note that KArchive will -not- own the device, it must be deleted by the derived class.

◆ setErrorString()

void KArchive::setErrorString ( const QString &  errorStr)
protected

Sets error description.

Parameters
errorStrerror description
Since
5.29

◆ setRootDir()

void KArchive::setRootDir ( KArchiveDirectory rootDir)
protected

Derived classes call setRootDir from openArchive, to set the root directory after parsing an existing archive.

◆ writeData()

virtual bool KArchive::writeData ( const char *  data,
qint64  size 
)
virtual

Write data into the current file - to be called after calling prepareWriting.

Reimplemented in K7Zip, and KZip.

◆ writeDir()

bool KArchive::writeDir ( const QString &  name,
const QString &  user = QString(),
const QString &  group = QString(),
mode_t  perm = 040755,
const QDateTime &  atime = QDateTime(),
const QDateTime &  mtime = QDateTime(),
const QDateTime &  ctime = QDateTime() 
)

If an archive is opened for writing then you can add new directories using this function.

KArchive won't write one directory twice.

This method also allows some file metadata to be set. However, depending on the archive type not all metadata might be regarded.

Parameters
namethe name of the directory
userthe user that owns the directory
groupthe group that owns the directory
permpermissions of the directory
atimetime the file was last accessed
mtimemodification time of the file
ctimetime of last status change

◆ writeFile() [1/2]

bool KArchive::writeFile ( const QString &  name,
const QByteArray &  data,
mode_t  perm = 0100644,
const QString &  user = QString(),
const QString &  group = QString(),
const QDateTime &  atime = QDateTime(),
const QDateTime &  mtime = QDateTime(),
const QDateTime &  ctime = QDateTime() 
)

Writes a new file into the archive.

The archive must be opened for writing first.

The necessary parent directories are created automatically if needed. For instance, writing "mydir/test1" does not require creating the directory "mydir" first.

This method also allows some file metadata to be set. However, depending on the archive type not all metadata might be written out.

Parameters
namethe name of the file
datathe data to write
permpermissions of the file
userthe user that owns the file
groupthe group that owns the file
atimetime the file was last accessed
mtimemodification time of the file
ctimetime of last status change

◆ writeFile() [2/2]

bool KArchive::writeFile ( const QString &  name,
const QString &  user,
const QString &  group,
const char *  data,
qint64  size,
mode_t  perm = 0100644,
const QDateTime &  atime = QDateTime(),
const QDateTime &  mtime = QDateTime(),
const QDateTime &  ctime = QDateTime() 
)
inline
Deprecated:
since 5.0, use writeFile(const QString&, const QByteArray&, mode_t, const QString&, const QString&, const QDateTime&, const QDateTime&, const QDateTime&)

◆ writeSymLink()

bool KArchive::writeSymLink ( const QString &  name,
const QString &  target,
const QString &  user = QString(),
const QString &  group = QString(),
mode_t  perm = 0120755,
const QDateTime &  atime = QDateTime(),
const QDateTime &  mtime = QDateTime(),
const QDateTime &  ctime = QDateTime() 
)

Writes a symbolic link to the archive if supported.

The archive must be opened for writing.

Parameters
namename of symbolic link
targettarget of symbolic link
userthe user that owns the directory
groupthe group that owns the directory
permpermissions of the directory
atimetime the file was last accessed
mtimemodification time of the file
ctimetime of last status change