KArchive Class Reference

from PyKDE4.kio import *

Detailed Description

KArchive is a base class for reading and writing archives. generic class for reading/writing archives

Author:: David Faure <faure@kde.org>

Enumerations
<anonymous>	{ UnknownTime }
Methods
	__init__ (self, QString fileName)
	__init__ (self, QIODevice dev)
	__init__ (self, KArchive other)
bool	addLocalDirectory (self, QString path, QString destName)
bool	addLocalFile (self, QString fileName, QString destName)
bool	close (self)
bool	closeArchive (self)
bool	createDevice (self, QIODevice.OpenMode mode)
QIODevice	device (self)
KArchiveDirectory	directory (self)
bool	doFinishWriting (self, long size)
bool	doPrepareWriting (self, QString name, QString user, QString group, long size, long perm, long atime, long mtime, long ctime)
bool	doWriteDir (self, QString name, QString user, QString group, long perm, long atime, long mtime, long ctime)
bool	doWriteSymLink (self, QString name, QString target, QString user, QString group, long perm, long atime, long mtime, long ctime)
QString	fileName (self)
KArchiveDirectory	findOrCreate (self, QString path)
bool	finishWriting (self, long size)
bool	isOpen (self)
QIODevice.OpenMode	mode (self)
bool	open (self, QIODevice.OpenMode mode)
bool	openArchive (self, QIODevice.OpenMode mode)
bool	prepareWriting (self, QString name, QString user, QString group, long size, long perm=0100644, long atime=UnknownTime, long mtime=UnknownTime, long ctime=UnknownTime)
KArchiveDirectory	rootDir (self)
	setDevice (self, QIODevice dev)
	setRootDir (self, KArchiveDirectory rootDir)
bool	writeData (self, QString data, long size)
bool	writeDir (self, QString name, QString user, QString group, long perm=040755, long atime=UnknownTime, long mtime=UnknownTime, long ctime=UnknownTime)
bool	writeFile (self, QString name, QString user, QString group, QString data, long size, long perm=0100644, long atime=UnknownTime, long mtime=UnknownTime, long ctime=UnknownTime)
bool	writeSymLink (self, QString name, QString target, QString user, QString group, long perm=0120755, long atime=UnknownTime, long mtime=UnknownTime, long ctime=UnknownTime)

Method Documentation

__init__	(	self,
		QString	fileName
	)

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

Parameters:

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

__init__	(	self,
		QIODevice	dev
	)

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

Parameters:

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 KSaveFile when saving.

__init__	(	self,
		KArchive	other
	)

bool addLocalDirectory	(	self,
		QString	path,
		QString	destName
	)

Writes a local directory into the archive, including all its contents, recursively. Calls addLocalFile for each file to be added.

Since KDE 3.2 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:

	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 addLocalFile	(	self,
		QString	fileName,
		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:

	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.

bool close ( self )

Closes the archive. Inherited classes might want to reimplement closeArchive instead.

Returns:: true if close succeeded without problems

See also:: open

bool closeArchive ( self )

Abstract method:: This method is abstract and can be overridden but not called directly.

Closes the archive. Called by close.

bool createDevice	(	self,
		QIODevice.OpenMode	mode
	)

Can be reimplemented in order to change the creation of the device (when using the fileName constructor). By default this method uses KSaveFile when saving, and a simple QFile on reading. This method is called by open().

QIODevice device ( self )

The underlying device.

Returns:: the underlying device.

KArchiveDirectory directory ( self )

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

bool doFinishWriting	(	self,
		long	size
	)

Abstract method:: This method is abstract and can be overridden but not called directly.

Called after writing the data. This virtual method must be implemented by subclasses.

Parameters:

size

the size of the file

See also:: finishWriting()

bool doPrepareWriting	(	self,
		QString	name,
		QString	user,
		QString	group,
		long	size,
		long	perm,
		long	atime,
		long	mtime,
		long	ctime
	)

Abstract method:: This method is abstract and can be overridden but not called directly.

This virtual method must be implemented by subclasses.

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

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

bool doWriteDir	(	self,
		QString	name,
		QString	user,
		QString	group,
		long	perm,
		long	atime,
		long	mtime,
		long	ctime
	)

Abstract method:: This method is abstract and can be overridden but not called directly.

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:

	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

bool doWriteSymLink	(	self,
		QString	name,
		QString	target,
		QString	user,
		QString	group,
		long	perm,
		long	atime,
		long	mtime,
		long	ctime
	)

Abstract method:: This method is abstract and can be overridden but not called directly.

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

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	time of last status change

See also:: writeSymLink

QString fileName ( self )

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

KArchiveDirectory findOrCreate	(	self,
		QString	path
	)

Ensures that path exists, create otherwise. This handles e.g. tar files missing directory entries, like mico-2.3.0.tar.gz :)

Parameters:

path

the path of the directory

Returns:: the directory with the given path

bool finishWriting	(	self,
		long	size
	)

Call finishWriting after writing the data.

Parameters:

size

the size of the file

See also:: prepareWriting()

bool isOpen ( self )

Checks whether the archive is open.

Returns:: true if the archive is opened

QIODevice.OpenMode mode ( self )

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

bool open	(	self,
		QIODevice.OpenMode	mode
	)

Opens the archive for reading or writing. Inherited classes might want to reimplement openArchive instead.

Parameters:

mode

may be QIODevice.ReadOnly or QIODevice.WriteOnly

See also:: close

bool openArchive	(	self,
		QIODevice.OpenMode	mode
	)

Abstract method:: This method is abstract and can be overridden but not called directly.

Opens an archive for reading or writing. Called by open.

Parameters:

mode

may be QIODevice.ReadOnly or QIODevice.WriteOnly

bool prepareWriting	(	self,
		QString	name,
		QString	user,
		QString	group,
		long	size,
		long	perm=0100644,
		long	atime=UnknownTime,
		long	mtime=UnknownTime,
		long	ctime=UnknownTime
	)

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:

	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

KArchiveDirectory rootDir ( self )

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	(	self,
		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.

setRootDir	(	self,
		KArchiveDirectory	rootDir
	)

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

bool writeData	(	self,
		QString	data,
		long	size
	)

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

bool writeDir	(	self,
		QString	name,
		QString	user,
		QString	group,
		long	perm=040755,
		long	atime=UnknownTime,
		long	mtime=UnknownTime,
		long	ctime=UnknownTime
	)

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:

	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

bool writeFile	(	self,
		QString	name,
		QString	user,
		QString	group,
		QString	data,
		long	size,
		long	perm=0100644,
		long	atime=UnknownTime,
		long	mtime=UnknownTime,
		long	ctime=UnknownTime
	)

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
	data	the data to write (@p size bytes)
	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

bool writeSymLink	(	self,
		QString	name,
		QString	target,
		QString	user,
		QString	group,
		long	perm=0120755,
		long	atime=UnknownTime,
		long	mtime=UnknownTime,
		long	ctime=UnknownTime
	)

Writes a symbolic link to the archive if supported. 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	time of last status change

Enumeration Documentation

anonymous

Enumerator:

UnknownTime

KArchive Class Reference

Detailed Description

Enumerations

Methods

Method Documentation

Enumeration Documentation

Modules