\section{KTar Class Reference}
\label{classKTar}\index{KTar@{KTar}}
A class for reading / writing (optionally compressed) tar archives.  


{\tt \#include $<$ktar.h$>$}

Inheritance diagram for KTar:\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=46pt]{classKTar__inherit__graph}
\end{center}
\end{figure}
Collaboration diagram for KTar:\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=95pt]{classKTar__coll__graph}
\end{center}
\end{figure}
\subsection*{Public Member Functions}
\begin{CompactItemize}
\item 
{\bf KTar} (const {\bf QString} \&filename, const {\bf QString} \&mimetype=QString::null)
\item 
{\bf KTar} ({\bf QIODevice} $\ast$dev)
\item 
virtual {\bf $\sim$KTar} ()
\item 
{\bf QString} {\bf file\-Name} ()
\item 
void {\bf set\-Orig\-File\-Name} (const {\bf QCString} \&file\-Name)
\item 
bool {\bf write\-Sym\-Link} (const {\bf QString} \&name, const {\bf QString} \&target, const {\bf QString} \&user, const {\bf QString} \&group, mode\_\-t perm, time\_\-t atime, time\_\-t mtime, time\_\-t ctime)
\item 
virtual bool {\bf write\-Dir} (const {\bf QString} \&name, const {\bf QString} \&user, const {\bf QString} \&group)
\item 
bool {\bf write\-Dir} (const {\bf QString} \&name, const {\bf QString} \&user, const {\bf QString} \&group, mode\_\-t perm, time\_\-t atime, time\_\-t mtime, time\_\-t ctime)
\item 
virtual bool {\bf prepare\-Writing} (const {\bf QString} \&name, const {\bf QString} \&user, const {\bf QString} \&group, uint size)
\item 
bool {\bf prepare\-Writing} (const {\bf QString} \&name, const {\bf QString} \&user, const {\bf QString} \&group, uint size, mode\_\-t perm, time\_\-t atime, time\_\-t mtime, time\_\-t ctime)
\item 
virtual bool {\bf done\-Writing} (uint size)
\end{CompactItemize}
\subsection*{Protected Member Functions}
\begin{CompactItemize}
\item 
virtual bool {\bf open\-Archive} (int mode)
\item 
virtual bool {\bf close\-Archive} ()
\item 
virtual void {\bf virtual\_\-hook} (int id, void $\ast$data)\label{classKTar_b2}

\item 
bool {\bf prepare\-Writing\_\-impl} (const {\bf QString} \&name, const {\bf QString} \&user, const {\bf QString} \&group, uint size, mode\_\-t perm, time\_\-t atime, time\_\-t mtime, time\_\-t ctime)\label{classKTar_b3}

\item 
bool {\bf write\-Dir\_\-impl} (const {\bf QString} \&name, const {\bf QString} \&user, const {\bf QString} \&group, mode\_\-t perm, time\_\-t atime, time\_\-t mtime, time\_\-t ctime)\label{classKTar_b4}

\item 
bool {\bf write\-Sym\-Link\_\-impl} (const {\bf QString} \&name, const {\bf QString} \&target, const {\bf QString} \&user, const {\bf QString} \&group, mode\_\-t perm, time\_\-t atime, time\_\-t mtime, time\_\-t ctime)\label{classKTar_b5}

\end{CompactItemize}


\subsection{Detailed Description}
A class for reading / writing (optionally compressed) tar archives. 

KTar allows you to read and write tar archives, including those that are compressed using gzip or bzip2.

\begin{Desc}
\item[Author:]Torben Weis $<${\tt weis@kde.org}$>$, David Faure $<${\tt faure@kde.org}$>$ \end{Desc}




Definition at line 40 of file ktar.h.

\subsection{Constructor \& Destructor Documentation}
\index{KTar@{KTar}!KTar@{KTar}}
\index{KTar@{KTar}!KTar@{KTar}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}KTar::KTar (const {\bf QString} \& {\em filename}, const {\bf QString} \& {\em mimetype} = {\tt QString::null})}\label{classKTar_a0}


Creates an instance that operates on the given filename using the compression filter associated to given mimetype. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em filename}]is a local path (e.g. \char`\"{}/home/weis/myfile.tgz\char`\"{}) \item[{\em mimetype}]\char`\"{}application/x-gzip\char`\"{} or \char`\"{}application/x-bzip2\char`\"{} Do not use application/x-tgz or similar - you only need to specify the compression layer ! If the mimetype is omitted, it will be determined from the filename. \end{description}
\end{Desc}


Definition at line 59 of file ktar.cpp.

References QFile::close(), endl(), KMime\-Type::find\-By\-File\-Content(), KMime\-Type::find\-By\-Path(), QFile::getch(), QString::is\-Empty(), kd\-Debug(), and QFile::open().\index{KTar@{KTar}!KTar@{KTar}}
\index{KTar@{KTar}!KTar@{KTar}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}KTar::KTar ({\bf QIODevice} $\ast$ {\em dev})}\label{classKTar_a1}


Creates an instance that operates on the given device. 

The device can be compressed ({\bf KFilter\-Dev}{\rm (p.\,\pageref{classKFilterDev})}) or not ({\bf QFile}, etc.). WARNING: don't assume that giving a {\bf QFile} here will decompress the file, in case it's compressed! \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em dev}]the device to read from. If the source is compressed, the {\bf QIODevice} must take care of decompression \end{description}
\end{Desc}


Definition at line 144 of file ktar.cpp.\index{KTar@{KTar}!~KTar@{$\sim$KTar}}
\index{~KTar@{$\sim$KTar}!KTar@{KTar}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}KTar::$\sim${\bf KTar} ()\hspace{0.3cm}{\tt  [virtual]}}\label{classKTar_a2}


If the tar ball is still opened, then it will be closed automatically by the destructor. 



Definition at line 150 of file ktar.cpp.

References KArchive::close(), KArchive::device(), QString::is\-Empty(), and KArchive::is\-Opened().

\subsection{Member Function Documentation}
\index{KTar@{KTar}!fileName@{fileName}}
\index{fileName@{fileName}!KTar@{KTar}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}{\bf QString} KTar::file\-Name ()\hspace{0.3cm}{\tt  [inline]}}\label{classKTar_a3}


The name of the tar file, as passed to the constructor Null if you used the {\bf QIODevice} constructor. 

\begin{Desc}
\item[Returns:]the name of the file, or QString::null if unknown \end{Desc}


Definition at line 76 of file ktar.h.

Referenced by set\-Orig\-File\-Name().\index{KTar@{KTar}!setOrigFileName@{setOrigFileName}}
\index{setOrigFileName@{setOrigFileName}!KTar@{KTar}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void KTar::set\-Orig\-File\-Name (const {\bf QCString} \& {\em file\-Name})}\label{classKTar_a4}


Special function for setting the \char`\"{}original file name\char`\"{} in the gzip header, when writing a tar.gz file. 

It appears when using in the \char`\"{}file\char`\"{} command, for instance. Should only be called if the underlying device is a KFilter\-Dev! \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em file\-Name}]the original file name \end{description}
\end{Desc}


Definition at line 165 of file ktar.cpp.

References file\-Name(), KArchive::is\-Opened(), kd\-Warning(), and KArchive::mode().\index{KTar@{KTar}!writeSymLink@{writeSymLink}}
\index{writeSymLink@{writeSymLink}!KTar@{KTar}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}bool KTar::write\-Sym\-Link (const {\bf QString} \& {\em name}, const {\bf QString} \& {\em target}, const {\bf QString} \& {\em user}, const {\bf QString} \& {\em group}, mode\_\-t {\em perm}, time\_\-t {\em atime}, time\_\-t {\em mtime}, time\_\-t {\em ctime})}\label{classKTar_a5}


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

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em name}]name of symbolic link \item[{\em target}]target of symbolic link \item[{\em user}]the user that owns the directory \item[{\em group}]the group that owns the directory \item[{\em perm}]permissions of the directory \item[{\em atime}]time the file was last accessed \item[{\em mtime}]modification time of the file \item[{\em ctime}]creation time of the file \end{description}
\end{Desc}
\begin{Desc}
\item[Since:]3.2 // TODO(BIC) make virtual. For now it must be implemented by virtual\_\-hook. \end{Desc}


Reimplemented from {\bf KArchive} {\rm (p.\,\pageref{classKArchive_a11})}.

Definition at line 869 of file ktar.cpp.

References KArchive::write\-Sym\-Link().\index{KTar@{KTar}!writeDir@{writeDir}}
\index{writeDir@{writeDir}!KTar@{KTar}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}bool KTar::write\-Dir (const {\bf QString} \& {\em name}, const {\bf QString} \& {\em user}, const {\bf QString} \& {\em group})\hspace{0.3cm}{\tt  [virtual]}}\label{classKTar_a6}


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

{\bf KArchive}{\rm (p.\,\pageref{classKArchive})} won't write one directory twice.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em name}]the name of the directory \item[{\em user}]the user that owns the directory \item[{\em group}]the group that owns the directory // TODO(BIC): make this a thin wrapper around // write\-Dir(name,user,group,perm,atime,mtime,ctime) // or elimitate it \end{description}
\end{Desc}


Implements {\bf KArchive} {\rm (p.\,\pageref{classKArchive_a9})}.

Definition at line 542 of file ktar.cpp.

References QIODevice::at(), KArchive::device(), KArchive::is\-Opened(), kd\-Warning(), QString::length(), QString::local8Bit(), KArchive::mode(), QString::right(), and QIODevice::write\-Block().\index{KTar@{KTar}!writeDir@{writeDir}}
\index{writeDir@{writeDir}!KTar@{KTar}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}bool KTar::write\-Dir (const {\bf QString} \& {\em name}, const {\bf QString} \& {\em user}, const {\bf QString} \& {\em group}, mode\_\-t {\em perm}, time\_\-t {\em atime}, time\_\-t {\em mtime}, time\_\-t {\em ctime})}\label{classKTar_a7}


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

{\bf KArchive}{\rm (p.\,\pageref{classKArchive})} 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. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em name}]the name of the directory \item[{\em user}]the user that owns the directory \item[{\em group}]the group that owns the directory \item[{\em perm}]permissions of the directory \item[{\em atime}]time the file was last accessed \item[{\em mtime}]modification time of the file \item[{\em ctime}]creation time of the file \end{description}
\end{Desc}
\begin{Desc}
\item[Since:]3.2 // TODO(BIC): make this virtual. For now use virtual hook \end{Desc}


Reimplemented from {\bf KArchive} {\rm (p.\,\pageref{classKArchive_a10})}.

Definition at line 806 of file ktar.cpp.

References KArchive::write\-Dir().\index{KTar@{KTar}!prepareWriting@{prepareWriting}}
\index{prepareWriting@{prepareWriting}!KTar@{KTar}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}bool KTar::prepare\-Writing (const {\bf QString} \& {\em name}, const {\bf QString} \& {\em user}, const {\bf QString} \& {\em group}, uint {\em size})\hspace{0.3cm}{\tt  [virtual]}}\label{classKTar_a8}


Here's another way of writing a file into an archive: Call prepare\-Writing, then call {\bf write\-Data()}{\rm (p.\,\pageref{classKArchive_a16})} as many times as wanted then call done\-Writing( total\-Size ). 

For tar.gz files, you need to know the size before hand, since it is needed in the header. For zip files, size isn't used.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em name}]the name of the file \item[{\em user}]the user that owns the file \item[{\em group}]the group that owns the file \item[{\em size}]the size of the file // TODO(BIC): make this a thin non-virtual wrapper around // prepare\-Writing(name,user,group,size,perm,atime,mtime,ctime) or eliminate it. \end{description}
\end{Desc}


Implements {\bf KArchive} {\rm (p.\,\pageref{classKArchive_a14})}.

Definition at line 604 of file ktar.cpp.\index{KTar@{KTar}!prepareWriting@{prepareWriting}}
\index{prepareWriting@{prepareWriting}!KTar@{KTar}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}bool KTar::prepare\-Writing (const {\bf QString} \& {\em name}, const {\bf QString} \& {\em user}, const {\bf QString} \& {\em group}, uint {\em size}, mode\_\-t {\em perm}, time\_\-t {\em atime}, time\_\-t {\em mtime}, time\_\-t {\em ctime})}\label{classKTar_a9}


Here's another way of writing a file into an archive: Call prepare\-Writing, then call {\bf write\-Data()}{\rm (p.\,\pageref{classKArchive_a16})} as many times as wanted then call done\-Writing( total\-Size ). 

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. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em name}]the name of the file \item[{\em user}]the user that owns the file \item[{\em group}]the group that owns the file \item[{\em size}]the size of the file \item[{\em perm}]permissions of the file \item[{\em atime}]time the file was last accessed \item[{\em mtime}]modification time of the file \item[{\em ctime}]creation time of the file \end{description}
\end{Desc}
\begin{Desc}
\item[Since:]3.2 // TODO(BIC): make this virtual. For now use virtual hook. \end{Desc}


Reimplemented from {\bf KArchive} {\rm (p.\,\pageref{classKArchive_a15})}.

Definition at line 735 of file ktar.cpp.

References KArchive::prepare\-Writing().\index{KTar@{KTar}!doneWriting@{doneWriting}}
\index{doneWriting@{doneWriting}!KTar@{KTar}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}bool KTar::done\-Writing (uint {\em size})\hspace{0.3cm}{\tt  [virtual]}}\label{classKTar_a10}


Call done\-Writing after writing the data. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em size}]the size of the file \end{description}
\end{Desc}
\begin{Desc}
\item[See also:]{\bf prepare\-Writing()}{\rm (p.\,\pageref{classKTar_a8})} \end{Desc}


Implements {\bf KArchive} {\rm (p.\,\pageref{classKArchive_a17})}.

Definition at line 612 of file ktar.cpp.

References QIODevice::at(), KArchive::device(), KArchive::mode(), and QIODevice::write\-Block().\index{KTar@{KTar}!openArchive@{openArchive}}
\index{openArchive@{openArchive}!KTar@{KTar}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}bool KTar::open\-Archive (int {\em mode})\hspace{0.3cm}{\tt  [protected, virtual]}}\label{classKTar_b0}


Opens the archive for reading. 

Parses the directory listing of the archive and creates the KArchive\-Directory/KArchive\-File entries. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em mode}]the mode of the file \end{description}
\end{Desc}


Implements {\bf KArchive} {\rm (p.\,\pageref{classKArchive_b1})}.

Definition at line 326 of file ktar.cpp.

References KArchive\-Directory::add\-Entry(), QIODevice::at(), QDir::clean\-Dir\-Path(), KArchive::device(), endl(), KArchive::find\-Or\-Create(), QString::find\-Rev(), kd\-Debug(), kd\-Warning(), QString::left(), QString::length(), QString::mid(), QString::right(), and KArchive::root\-Dir().\index{KTar@{KTar}!closeArchive@{closeArchive}}
\index{closeArchive@{closeArchive}!KTar@{KTar}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}bool KTar::close\-Archive ()\hspace{0.3cm}{\tt  [protected, virtual]}}\label{classKTar_b1}


Closes the archive. 

Called by close. 

Implements {\bf KArchive} {\rm (p.\,\pageref{classKArchive_b2})}.

Definition at line 529 of file ktar.cpp.

References KArchive::mode().

The documentation for this class was generated from the following files:\begin{CompactItemize}
\item 
ktar.h\item 
ktar.cpp\end{CompactItemize}
