# class KArchive

### abstract

Module | kio
Namespace |
Class | KArchive
Inherits |

KArchive is a base class for reading and writing archives. generic class for reading/writing archives Author David Faure <faure@kde.org>

### enums

- anonymous { UnknownTime }

enum details

### methods

- KArchive (fileName)

  returns ctor

  Argument | Type | Default
  --- | --- | ---
  fileName | QString |

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

- KArchive (dev)

  returns ctor

  Argument | Type | Default
  --- | --- | ---
  dev | QIODevice |

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

- addLocalDirectory (path, destName)

  returns bool

  Argument | Type | Default
  --- | --- | ---
  path | QString |
  destName | QString |

  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.

  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.

- addLocalFile (fileName, destName)

  returns bool

  Argument | Type | Default
  --- | --- | ---
  fileName | QString |
  destName | QString |

  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.

- close ( )

  returns bool

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

  Returns true if close succeeded without problems

  See also open

- closeArchive ( )

  returns bool
  pure virtual

  Closes the archive. Called by close.

- createDevice (mode)

  returns bool

  Argument | Type | Default
  --- | --- | ---
  mode | QIODevice.OpenMode |

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

- device ( )

  returns QIODevice

  The underlying device. Returns the underlying device.

- directory ( )

  returns KArchiveDirectory

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

  returns bool
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  size | qint64 |

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

  size - the size of the file

  See also finishWriting()

- doPrepareWriting (name, user, group, size, perm, atime, mtime, ctime)

  returns bool
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  name | QString |
  user | QString |
  group | QString |
  size | qint64 |
  perm | mode_t |
  atime | time_t |
  mtime | time_t |
  ctime | time_t |

  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

- doWriteDir (name, user, group, perm, atime, mtime, ctime)

  returns bool
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  name | QString |
  user | QString |
  group | QString |
  perm | mode_t |
  atime | time_t |
  mtime | time_t |
  ctime | time_t |

  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

- doWriteSymLink (name, target, user, group, perm, atime, mtime, ctime)

  returns bool
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  name | QString |
  target | QString |
  user | QString |
  group | QString |
  perm | mode_t |
  atime | time_t |
  mtime | time_t |
  ctime | time_t |

  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

- fileName ( )

  returns QString

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

  returns KArchiveDirectory

  Argument | Type | Default
  --- | --- | ---
  path | QString |

  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

- finishWriting (size)

  returns bool

  Argument | Type | Default
  --- | --- | ---
  size | qint64 |

  Call finishWriting after writing the data.

  size - the size of the file

  See also prepareWriting()

- isOpen ( )

  returns bool

  Checks whether the archive is open. Returns true if the archive is opened

- mode ( )

  returns QIODevice.OpenMode

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

  returns bool

  Argument | Type | Default
  --- | --- | ---
  mode | QIODevice.OpenMode |

  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

- openArchive (mode)

  returns bool
  pure virtual

  Argument | Type | Default
  --- | --- | ---
  mode | QIODevice.OpenMode |

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

  mode - may be QIODevice.ReadOnly or QIODevice.WriteOnly

- prepareWriting (name, user, group, size, perm, atime, mtime, ctime)

  returns bool

  Argument | Type | Default
  --- | --- | ---
  name | QString |
  user | QString |
  group | QString |
  size | qint64 |
  perm | mode_t | 0100644
  atime | time_t | UnknownTime
  mtime | time_t | UnknownTime
  ctime | time_t | 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.

  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

- rootDir ( )

  returns KArchiveDirectory

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

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  dev | QIODevice |

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

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  rootDir | KArchiveDirectory |

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

- virtual_hook (id, data)

  returns Nothing
  Not implemented

  Argument | Type | Default
  --- | --- | ---
  id | int |
  data | void |

- writeData (data, size)

  returns bool

  Argument | Type | Default
  --- | --- | ---
  data | char |
  size | qint64 |

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

- writeDir (name, user, group, perm, atime, mtime, ctime)

  returns bool

  Argument | Type | Default
  --- | --- | ---
  name | QString |
  user | QString |
  group | QString |
  perm | mode_t | 040755
  atime | time_t | UnknownTime
  mtime | time_t | UnknownTime
  ctime | time_t | 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.

  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

- writeFile (name, user, group, data, size, perm, atime, mtime, ctime)

  returns bool

  Argument | Type | Default
  --- | --- | ---
  name | QString |
  user | QString |
  group | QString |
  data | char |
  size | qint64 |
  perm | mode_t | 0100644
  atime | time_t | UnknownTime
  mtime | time_t | UnknownTime
  ctime | time_t | 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.

  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

- writeSymLink (name, target, user, group, perm, atime, mtime, ctime)

  returns bool

  Argument | Type | Default
  --- | --- | ---
  name | QString |
  target | QString |
  user | QString |
  group | QString |
  perm | mode_t | 0120755
  atime | time_t | UnknownTime
  mtime | time_t | UnknownTime
  ctime | time_t | UnknownTime

  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

### enums - detail

- anonymous { UnknownTime }

  | UnknownTime | - static_cast<time_t>(-1) | - |