kio Library API Documentation

KZip Class Reference

This class implements a kioslave to access zip files from KDE. A class for reading/writing zip archives. More...

#include <kzip.h>

Inheritance diagram for KZip:

KArchive List of all members.

Public Types

enum  ExtraField { , ModificationTime = 1, DefaultExtraField = 1 }
enum  Compression { NoCompression = 0, DeflateCompression = 1 }

Public Methods

 KZip (const QString &filename)
 KZip (QIODevice *dev)
virtual ~KZip ()
QString fileName ()
void setExtraField (ExtraField ef)
ExtraField extraField () const
void setCompression (Compression c)
Compression compression () const
virtual bool writeFile (const QString &name, const QString &user, const QString &group, uint size, const char *data)
virtual bool prepareWriting (const QString &name, const QString &user, const QString &group, uint size)
bool writeSymLink (const QString &name, const QString &target, const QString &user, const QString &group, mode_t perm, time_t atime, time_t mtime, time_t ctime)
bool prepareWriting (const QString &name, const QString &user, const QString &group, uint size, mode_t perm, time_t atime, time_t mtime, time_t ctime)
bool writeFile (const QString &name, const QString &user, const QString &group, uint size, mode_t perm, time_t atime, time_t mtime, time_t ctime, const char *data)
bool writeData (const char *data, uint size)
virtual bool doneWriting (uint size)

Protected Methods

virtual bool openArchive (int mode)
virtual bool closeArchive ()
virtual bool writeDir (const QString &, const QString &, const QString &)
virtual void virtual_hook (int id, void *data)
bool writeData_impl (const char *data, uint size)
bool prepareWriting_impl (const QString &name, const QString &user, const QString &group, uint size, mode_t perm, time_t atime, time_t mtime, time_t ctime)
bool writeSymLink_impl (const QString &name, const QString &target, const QString &user, const QString &group, mode_t perm, time_t atime, time_t mtime, time_t ctime)

Detailed Description

This class implements a kioslave to access zip files from KDE. A class for reading/writing zip archives.

You can use it in IO_ReadOnly or in IO_WriteOnly mode, and it behaves just as expected. It can also be used in IO_ReadWrite mode, in this case one can append files to an existing zip archive. When you append new files, which are not yet in the zip, it works as expected, i.e. the files are appended at the end. When you append a file, which is already in the file, the reference to the old file is dropped and the new one is added to the zip - but the old data from the file itself is not deleted, it is still in the zipfile. so when you want to have a small and garbage-free zipfile, just read the contents of the appended zip file and write it to a new one in IO_WriteOnly mode. This is especially important when you don't want to leak information of how intermediate versions of files in the zip were looking. For more information on the zip fileformat go to http://www.pkware.com/products/enterprise/white_papers/appnote.html

Author:
Holger Schroeder <holger-kde@holgis.net>
Since:
3.1

Definition at line 53 of file kzip.h.


Member Enumeration Documentation

enum KZip::ExtraField
 

Describes the contents of the "extra field" for a given file in the Zip archive.

Enumeration values:
ModificationTime  No extra field.
DefaultExtraField  Modification time ("extended timestamp" header).

Definition at line 89 of file kzip.h.

Referenced by extraField().

enum KZip::Compression
 

Describes the compression type for a given file in the Zip archive.

Enumeration values:
NoCompression  Uncompressed.
DeflateCompression  Deflate compression method.

Definition at line 112 of file kzip.h.

Referenced by compression().


Constructor & Destructor Documentation

KZip::KZip const QString   filename
 

Creates an instance that operates on the given filename.

using the compression filter associated to given mimetype.

Parameters:
filename  is a local path (e.g. "/home/holger/myfile.zip")

Definition at line 310 of file kzip.cpp.

KZip::KZip QIODevice   dev
 

Creates an instance that operates on the given device.

The device can be compressed (KFilterDev) or not (QFile, etc.). WARNING: don't assume that giving a QFile here will decompress the file, in case it's compressed!

Parameters:
dev  the device to access

Definition at line 319 of file kzip.cpp.

KZip::~KZip   [virtual]
 

If the zip file is still opened, then it will be closed automatically by the destructor.

Definition at line 326 of file kzip.cpp.

References KArchive::close(), KArchive::device(), QString::isEmpty(), and KArchive::isOpened().


Member Function Documentation

QString KZip::fileName   [inline]
 

The name of the zip file, as passed to the constructor.

Null if you used the QIODevice constructor.

Returns:
the zip's file name, or null if a QIODevice is used

Definition at line 84 of file kzip.h.

void KZip::setExtraField ExtraField    ef
 

Call this before writeFile or prepareWriting, to define what the next file to be written should have in its extra field.

Parameters:
ef  the type of "extra field"
See also:
extraField()

Definition at line 1152 of file kzip.cpp.

KZip::ExtraField KZip::extraField  
 

The current type of "extra field" that will be used for new files.

Returns:
the current type of "extra field"
See also:
setExtraField()

Definition at line 1157 of file kzip.cpp.

References ExtraField.

void KZip::setCompression Compression    c
 

Call this before writeFile or prepareWriting, to define whether the next files to be written should be compressed or not.

Parameters:
c  the new compression mode
See also:
compression()

Definition at line 1142 of file kzip.cpp.

References NoCompression.

KZip::Compression KZip::compression  
 

The current compression mode that will be used for new files.

Returns:
the current compression mode
See also:
setCompression()

Definition at line 1147 of file kzip.cpp.

References Compression, DeflateCompression, and NoCompression.

bool KZip::writeFile const QString   name,
const QString   user,
const QString   group,
uint    size,
const char *    data
[virtual]
 

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

This method takes the whole data at once.

Parameters:
name  can include subdirs e.g. path/to/the/file
user  the user owning the file
group  the group owning the file
size  the size of the file
data  a pointer to the data
Returns:
true if successful, false otherwise

Reimplemented from KArchive.

Definition at line 818 of file kzip.cpp.

References KArchive::mode(), and KArchive::writeFile().

bool KZip::prepareWriting const QString   name,
const QString   user,
const QString   group,
uint    size
[virtual]
 

Alternative method for writing: call prepareWriting(), then feed the data in small chunks using writeData(), and call doneWriting() when done.

Parameters:
name  can include subdirs e.g. path/to/the/file
user  the user owning the file
group  the group owning the file
size  unused argument
Returns:
true if successful, false otherwise

Implements KArchive.

Definition at line 836 of file kzip.cpp.

bool KZip::writeSymLink const QString   name,
const QString   target,
const QString   user,
const QString   group,
mode_t    perm,
time_t    atime,
time_t    mtime,
time_t    ctime
 

Writes a symbolic link to the archive if the archive must be opened for writing.

Parameters:
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  creation time of the file
Since:
3.2 // TODO(BIC) make virtual. For now it must be implemented by virtual_hook.

Reimplemented from KArchive.

Definition at line 1054 of file kzip.cpp.

References KArchive::writeSymLink().

bool KZip::prepareWriting const QString   name,
const QString   user,
const QString   group,
uint    size,
mode_t    perm,
time_t    atime,
time_t    mtime,
time_t    ctime
 

Here's another way of writing a file into an archive: Call prepareWriting, then call writeData() as many times as wanted then call doneWriting( 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:
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  creation time of the file
Since:
3.2 // TODO(BIC): make this virtual. For now use virtual hook.

Reimplemented from KArchive.

Definition at line 845 of file kzip.cpp.

References KArchive::prepareWriting().

bool KZip::writeFile const QString   name,
const QString   user,
const QString   group,
uint    size,
mode_t    perm,
time_t    atime,
time_t    mtime,
time_t    ctime,
const char *    data
 

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

If the file name is for example "mydir/test1" then the directory "mydir" is automatically appended first if that did not happen yet.

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

Parameters:
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  creation time of the file
data  the data to write (size bytes)
Since:
3.2 // TODO(BIC): make virtual. For now use virtual hook

Reimplemented from KArchive.

Definition at line 827 of file kzip.cpp.

References KArchive::writeFile().

bool KZip::writeData const char *    data,
uint    size
 

Write data to a file that has been created using prepareWriting().

Parameters:
data  a pointer to the data
size  the size of the chunk
Returns:
true if successful, false otherwise

Reimplemented from KArchive.

Definition at line 1121 of file kzip.cpp.

References KArchive::writeData().

bool KZip::doneWriting uint    size [virtual]
 

Write data to a file that has been created using prepareWriting().

Parameters:
size  the size of the file
Returns:
true if successful, false otherwise

Implements KArchive.

Definition at line 1017 of file kzip.cpp.

References QIODevice::at(), KArchive::device(), and ModificationTime.

bool KZip::openArchive int    mode [protected, virtual]
 

Opens the archive for reading.

Parses the directory listing of the archive and creates the KArchiveDirectory/KArchiveFile entries.

Parameters:
mode  the mode of the file

Implements KArchive.

Definition at line 337 of file kzip.cpp.

References KArchiveDirectory::addEntry(), QIODevice::at(), QDir::cleanDirPath(), QFile::decodeName(), KArchive::device(), QString::endsWith(), KArchiveDirectory::entry(), KArchive::findOrCreate(), QString::findRev(), QAsciiDict::insert(), KArchiveEntry::isDirectory(), QString::isEmpty(), QString::left(), QString::length(), QString::mid(), KArchive::mode(), NoCompression, QIODevice::readBlock(), KArchive::rootDir(), QAsciiDict::setAutoDelete(), and KIO::symlink().

bool KZip::closeArchive   [protected, virtual]
 

Closes the archive.

Implements KArchive.

Definition at line 630 of file kzip.cpp.

References QIODevice::at(), QPtrListIterator::current(), KArchive::device(), QFile::encodeName(), QCString::length(), KArchive::mode(), QPtrListIterator::toFirst(), and QIODevice::writeBlock().

virtual bool KZip::writeDir const QString  ,
const QString  ,
const QString  
[inline, protected, virtual]
 

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

KArchive won't write one directory twice.

Parameters:
name  the name of the directory
user  the user that owns the directory
group  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

Implements KArchive.

Definition at line 197 of file kzip.h.


The documentation for this class was generated from the following files:
KDE Logo
This file is part of the documentation for kio Library Version 3.2.2.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Thu Apr 22 14:24:20 2004 by doxygen 1.2.18 written by Dimitri van Heesch, © 1997-2003