KArchive Class

Member Function Documentation

[explicit protected] KArchive::KArchive(QIODevice *dev)

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

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

[explicit protected] KArchive::KArchive(const QString &fileName)

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

fileName is 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().

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.

path full path to an existing local directory, to be added to the archive.

destName the resulting name (or relative path) of the file in the archive.

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.

fileName full path to an existing local file, to be added to the archive.

destName the resulting name (or relative path) of the file in the archive.

[virtual] bool KArchive::close()

Closes the archive.

Inherited classes might want to reimplement closeArchive instead.

Returns true if close succeeded without problems

See also open.

[pure virtual protected] bool KArchive::closeArchive()

Closes the archive.

Called by close.

[virtual protected] bool KArchive::createDevice(QIODeviceBase::OpenMode mode)

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().

QIODevice *KArchive::device() const

Returns the underlying device.

See also setDevice().

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

[pure virtual protected] bool KArchive::doFinishWriting(qint64 size)

Called after writing the data.

This virtual method must be implemented by subclasses.

size the size of the file

See also finishWriting().

[pure virtual protected] 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)

This virtual method must be implemented by subclasses.

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

name the name of the file

user the user that owns the file

group the group that owns the file

size the size of the file

perm permissions of the file. Use 0100644 if you don't have any more specific permissions to set.

atime time the file was last accessed

mtime modification time of the file

ctime time of last status change

See also prepareWriting.

[virtual protected, since 6.0] bool KArchive::doWriteData(const char *data, qint64 size)

Write data into the current file. Called by writeData.

data a pointer to the data

size the size of the chunk

Returns true if successful, false otherwise

This function was introduced in 6.0.

See also writeData.

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

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.

name the name of the directory

user the user that owns the directory

group the group that owns the directory

perm permissions of the directory. Use 040755 if you don't have any other information.

atime time the file was last accessed

mtime modification time of the file

ctime time of last status change

See also writeDir.

[pure virtual protected] 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)

Writes a symbolic link to the archive. This virtual method must be implemented by subclasses.

name name of symbolic link

target target of symbolic link

user the user that owns the directory

group the group that owns the directory

perm permissions of the directory

atime time the file was last accessed

mtime modification time of the file

ctime time of last status change

See also writeSymLink.

[since 5.29] QString KArchive::errorString() const

Returns a description of the last error

This function was introduced in 5.29.

See also setErrorString().

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

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

Ensures that path exists, create otherwise.

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

path the path of the directory

Returns the directory with the given path

bool KArchive::finishWriting(qint64 size)

Call finishWriting after writing the data.

size the size of the file

See also prepareWriting().

bool KArchive::isOpen() const

Checks whether the archive is open.

Returns true if the archive is opened

QIODeviceBase::OpenMode KArchive::mode() const

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

See also open().

[virtual] bool KArchive::open(QIODeviceBase::OpenMode mode)

Opens the archive for reading or writing.

Inherited classes might want to reimplement openArchive instead.

mode may be QIODevice::ReadOnly or QIODevice::WriteOnly

See also close.

[pure virtual protected] bool KArchive::openArchive(QIODeviceBase::OpenMode mode)

Opens an archive for reading or writing.

Called by open.

mode may be QIODevice::ReadOnly or QIODevice::WriteOnly

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.

name the name of the file

user the user that owns the file

group the group that owns the file

size the size of the file

perm permissions of the file

atime time the file was last accessed

mtime modification time of the file

ctime time of last status change

[virtual protected] KArchiveDirectory *KArchive::rootDir()

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

See also setRootDir().

[protected] void KArchive::setDevice(QIODevice *dev)

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.

See also device().

[protected, since 5.29] void KArchive::setErrorString(const QString &errorStr)

Sets error description

errorStr error description

This function was introduced in 5.29.

See also errorString().

[protected] void KArchive::setRootDir(KArchiveDirectory *rootDir)

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

See also rootDir().

[since 6.0] bool KArchive::writeData(QByteArrayView data)

Overload for writeData(const char *, qint64);

This function was introduced in 6.0.

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

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

data a pointer to the data

size the size of the chunk

Returns true if successful, false otherwise

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.

name the name of the directory

user the user that owns the directory

group the group that owns the directory

perm permissions of the directory

atime time the file was last accessed

mtime modification time of the file

ctime time of last status change

[since 6.0] bool KArchive::writeFile(const QString &name, QByteArrayView 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.

name the name of the file

data the data to write

perm permissions of the file

user the user that owns the file

group the group that owns the file

atime time the file was last accessed

mtime modification time of the file

ctime time of last status change

This function was introduced in 6.0.

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.

name name of symbolic link

target target of symbolic link

user the user that owns the directory

group the group that owns the directory

perm permissions of the directory

atime time the file was last accessed

mtime modification time of the file

ctime time of last status change