another patch bring the docs more up to date (patch 1717776)

[wxWidgets.git] / docs / latex / wx / tarstrm.tex

%
% automatically generated by HelpGen $Revision$ from
% wx/tarstrm.h at 28/Oct/06 18:27:02
%

\section{\class{wxTarClassFactory}}\label{wxtarclassfactory}

Class factory for the tar archive format. See the base class
for details.

\wxheading{Derived from}

\helpref{wxArchiveClassFactory}{wxarchiveclassfactory}

\wxheading{Include files}

<wx/tarstrm.h>

\wxheading{See also}

\helpref{Archive formats such as zip}{wxarc}\\
\helpref{Generic archive programming}{wxarcgeneric}\\
\helpref{wxTarEntry}{wxtarentry}\\
\helpref{wxTarInputStream}{wxtarinputstream}\\
\helpref{wxTarOutputStream}{wxtaroutputstream}


%
% automatically generated by HelpGen $Revision$ from
% wx/tarstrm.h at 28/Oct/06 18:27:02
%

\section{\class{wxTarEntry}}\label{wxtarentry}

Holds the meta-data for an entry in a tar.

\wxheading{Derived from}

\helpref{wxArchiveEntry}{wxarchiveentry}

\wxheading{Include files}

<wx/tarstrm.h>

\wxheading{Data structures}

Constants for \helpref{Get/SetTypeFlag}{wxtarentrytypeflag}:

\begin{verbatim}
// TypeFlag values
enum {
    wxTAR_REGTYPE   = '0',      // regular file
    wxTAR_LNKTYPE   = '1',      // hard link
    wxTAR_SYMTYPE   = '2',      // symbolic link
    wxTAR_CHRTYPE   = '3',      // character special
    wxTAR_BLKTYPE   = '4',      // block special
    wxTAR_DIRTYPE   = '5',      // directory
    wxTAR_FIFOTYPE  = '6',      // named pipe
    wxTAR_CONTTYPE  = '7'       // contiguous file
};

\end{verbatim}

\wxheading{See also}

\helpref{Archive formats such as zip}{wxarc}\\
\helpref{wxTarInputStream}{wxtarinputstream}\\
\helpref{wxTarOutputStream}{wxtaroutputstream}

\wxheading{Field availability}

The tar format stores all the meta-data for an entry ahead of its data,
therefore \helpref{GetNextEntry()}{wxtarinputstreamgetnextentry} always returns
a fully populated wxTarEntry object, both when reading from seekable and
non-seekable streams.


\latexignore{\rtfignore{\wxheading{Members}}}


\membersection{wxTarEntry::wxTarEntry}\label{wxtarentrywxtarentry}

\func{}{wxTarEntry}{\param{const wxString\& }{name = wxEmptyString}, \param{const wxDateTime\& }{dt = wxDateTime::Now()}, \param{wxFileOffset }{size = wxInvalidOffset}}

Constructor. The tar archive format stores the entry's size ahead of the
entry's data. Therefore when creating an archive on a non-seekable stream it
is necessary to supply the correct size when each entry is created.

\func{}{wxTarEntry}{\param{const wxTarEntry\& }{entry}}

Copy constructor.


\membersection{wxTarEntry::Get/SetAccessTime}\label{wxtarentryaccesstime}

\constfunc{wxDateTime}{GetAccessTime}{\void}

\func{void}{SetAccessTime}{\param{const wxDateTime\& }{dt}}

The entry's access time stamp. See also
 \helpref{wxArchiveEntry::Get/SetDateTime}{wxarchiveentrydatetime}.


\membersection{wxTarEntry::Get/SetCreateTime}\label{wxtarentrycreatetime}

\constfunc{wxDateTime}{GetCreateTime}{\void}

\func{void}{SetCreateTime}{\param{const wxDateTime\& }{dt}}

The entry's creation time stamp. See also
 \helpref{wxArchiveEntry::Get/SetDateTime}{wxarchiveentrydatetime}.


\membersection{wxTarEntry::Get/SetDevMajor and Get/SetDevMinor}\label{wxtarentrydev}

\constfunc{int}{GetDevMajor}{\void}

\constfunc{int}{GetDevMinor}{\void}

\func{void}{SetDevMajor}{\param{int }{dev}}

\func{void}{SetDevMinor}{\param{int }{dev}}

OS specific IDs defining a device, these are only meaningful when
 \helpref{TypeFlag}{wxtarentrytypeflag} is set to {\it wxTAR\_CHRTYPE}
 or {\it wxTAR\_BLKTYPE}.


\membersection{wxTarEntry::Get/SetGroupId and Get/SetUserId}\label{wxtarentryuidgid}

\constfunc{int}{GetGroupId}{\void}

\constfunc{int}{GetUserId}{\void}

\func{void}{SetGroupId}{\param{int }{id}}

\func{void}{SetUserId}{\param{int }{id}}

The user ID and group ID that has \helpref{permissions}{wxtarentrymode} over
this entry. These values aren't usually useful unless the file will only be
restored to the same system it originated from. \helpref{Get/SetGroupName and
Get/SetUserName}{wxtarentryunamegname} can be used instead.


\membersection{wxTarEntry::Get/SetGroupName and Get/SetUserName}\label{wxtarentryunamegname}

\constfunc{wxString}{GetGroupName}{\void}

\constfunc{wxString}{GetUserName}{\void}

\func{void}{SetGroupName}{\param{const wxString\& }{group}}

\func{void}{SetUserName}{\param{const wxString\& }{user}}

The names of the user and group that has \helpref{permissions}{wxtarentrymode}
over this entry. These are not present in very old tars.


\membersection{wxTarEntry::GetInternalName}\label{wxtarentrygetinternalname}

\constfunc{wxString}{GetInternalName}{\void}

Returns the entry's filename in the internal format used within the
archive. The name can include directory components, i.e. it can be a
full path.

The names of directory entries are returned without any trailing path
separator. This gives a canonical name that can be used in comparisons.

\func{wxString}{GetInternalName}{\param{const wxString\& }{name}, \param{wxPathFormat }{format = wxPATH\_NATIVE}, \param{bool* }{pIsDir = NULL}}

A static member that translates a filename into the internal format used
within the archive. If the third parameter is provided, the bool pointed
to is set to indicate whether the name looks like a directory name
(i.e. has a trailing path separator).


\membersection{wxTarEntry::Get/SetLinkName}\label{wxtarentrylinkname}

\constfunc{wxString}{GetLinkName}{\void}

\func{void}{SetLinkName}{\param{const wxString\& }{link}}

The filename of a previous entry in the tar that this entry is a link to.
Only meaningful when \helpref{TypeFlag}{wxtarentrytypeflag} is set
to {\it wxTAR\_LNKTYPE} or {\it wxTAR\_SYMTYPE}.


\membersection{wxTarEntry::Get/SetMode}\label{wxtarentrymode}

\constfunc{int}{GetMode}{\void}

\func{void}{SetMode}{\param{int }{mode}}

UNIX permission bits for this entry. Giving read, write and execute permissions
to the file's \helpref{User and Group}{wxtarentryunamegname} and to others.
Symbols are defined for them in <wx/file.h>.

\begin{verbatim}
#define wxS_IRUSR 00400
#define wxS_IWUSR 00200
#define wxS_IXUSR 00100

#define wxS_IRGRP 00040
#define wxS_IWGRP 00020
#define wxS_IXGRP 00010

#define wxS_IROTH 00004
#define wxS_IWOTH 00002
#define wxS_IXOTH 00001

\end{verbatim}


\membersection{wxTarEntry::Get/SetSize}\label{wxtarentrysize}

\func{void}{SetSize}{\param{wxFileOffset }{size}}

\constfunc{wxFileOffset}{GetSize}{\void}

The size of the entry's data in bytes.

The tar archive format stores the entry's size ahead of the entry's data.
Therefore when creating an archive on a non-seekable stream it is necessary to
supply the correct size when each entry is created. For seekable streams this
is not necessary as \helpref{wxTarOutputStream}{wxtaroutputstream} will attempt
to seek back and fix the entry's header when the entry is closed, though it is
still more efficient if the size is given beforehand.


\membersection{wxTarEntry::Get/SetTypeFlag}\label{wxtarentrytypeflag}

\constfunc{int}{GetTypeFlag}{\void}

\func{void}{SetTypeFlag}{\param{int }{type}}

Returns the type of the entry. It should be one of the following:

\begin{verbatim}
// TypeFlag values
enum {
    wxTAR_REGTYPE   = '0',      // regular file
    wxTAR_LNKTYPE   = '1',      // hard link
    wxTAR_SYMTYPE   = '2',      // symbolic link
    wxTAR_CHRTYPE   = '3',      // character special
    wxTAR_BLKTYPE   = '4',      // block special
    wxTAR_DIRTYPE   = '5',      // directory
    wxTAR_FIFOTYPE  = '6',      // named pipe
    wxTAR_CONTTYPE  = '7'       // contiguous file
};

\end{verbatim}

When creating archives use just these values. When reading archives
any other values should be treated as {\it wxTAR\_REGTYPE}.


\membersection{wxTarEntry::operator=}\label{wxtarentryoperatorassign}

\func{wxTarEntry\& operator}{operator=}{\param{const wxTarEntry\& }{entry}}

Assignment operator.


%
% automatically generated by HelpGen $Revision$ from
% wx/tarstrm.h at 28/Oct/06 18:27:02
%

\section{\class{wxTarInputStream}}\label{wxtarinputstream}

Input stream for reading tar files.

\helpref{GetNextEntry()}{wxtarinputstreamgetnextentry} returns an
 \helpref{wxTarEntry}{wxtarentry} object containing the meta-data
for the next entry in the tar (and gives away ownership). Reading from
the wxTarInputStream then returns the entry's data. Eof() becomes true
after an attempt has been made to read past the end of the entry's data.
When there are no more entries, GetNextEntry() returns NULL and sets Eof().

Tar entries are seekable if the parent stream is seekable. In practice this
usually means they are only seekable if the tar is stored as a local file and
is not compressed.

\wxheading{Derived from}

\helpref{wxArchiveInputStream}{wxarchiveinputstream}

\wxheading{Include files}

<wx/tarstrm.h>

\wxheading{Data structures}
\begin{verbatim}
typedef wxTarEntry entry_type
\end{verbatim}

\helpref{Archive formats such as zip}{wxarc}\\
\helpref{wxTarEntry}{wxtarentry}\\
\helpref{wxTarOutputStream}{wxtaroutputstream}

\latexignore{\rtfignore{\wxheading{Members}}}


\membersection{wxTarInputStream::wxTarInputStream}\label{wxtarinputstreamwxtarinputstream}

\func{}{wxTarInputStream}{\param{wxInputStream\& }{stream}, \param{wxMBConv\& }{conv = wxConvLocal}}

\func{}{wxTarInputStream}{\param{wxInputStream* }{stream}, \param{wxMBConv\& }{conv = wxConvLocal}}

Constructor. In a Unicode build the second parameter {\it conv} is
used to translate fields from the standard tar header into Unicode. It has
no effect on the stream's data. {\it conv} is only used for the standard
tar headers, any pax extended headers are always UTF-8 encoded.

If the parent stream is passed as a pointer then the new filter stream
takes ownership of it. If it is passed by reference then it does not.


\membersection{wxTarInputStream::CloseEntry}\label{wxtarinputstreamcloseentry}

\func{bool}{CloseEntry}{\void}

Closes the current entry. On a non-seekable stream reads to the end of
the current entry first.


\membersection{wxTarInputStream::GetNextEntry}\label{wxtarinputstreamgetnextentry}

\func{wxTarEntry*}{GetNextEntry}{\void}

Closes the current entry if one is open, then reads the meta-data for
the next entry and returns it in a \helpref{wxTarEntry}{wxtarentry}
object, giving away ownership. The stream is then open and can be read.


\membersection{wxTarInputStream::OpenEntry}\label{wxtarinputstreamopenentry}

\func{bool}{OpenEntry}{\param{wxTarEntry\& }{entry}}

Closes the current entry if one is open, then opens the entry specified
by the {\it entry} object.

{\it entry} should be from the same tar file, and the tar should
be on a seekable stream.

\wxheading{See also}

\helpref{Looking up an archive entry by name}{wxarcbyname}


%
% automatically generated by HelpGen $Revision$ from
% wx/tarstrm.h at 28/Oct/06 18:27:02
%

\section{\class{wxTarOutputStream}}\label{wxtaroutputstream}

Output stream for writing tar files.

\helpref{PutNextEntry()}{wxtaroutputstreamputnextentry} is used to create
a new entry in the output tar, then the entry's data is written to the
wxTarOutputStream. Another call to PutNextEntry() closes the current
entry and begins the next.

\wxheading{Derived from}

\helpref{wxArchiveOutputStream}{wxarchiveoutputstream}

\wxheading{Include files}

<wx/tarstrm.h>

\wxheading{Data structures}

Constants for the {\it format} parameter of the
 \helpref{constructor}{wxtaroutputstreamwxtaroutputstream}.

\begin{verbatim}
// Archive Formats (use wxTAR_PAX, it's backward compatible)
enum wxTarFormat
{
    wxTAR_USTAR,                // POSIX.1-1990 tar format
    wxTAR_PAX                   // POSIX.1-2001 tar format
};

\end{verbatim}

\wxheading{See also}

\helpref{Archive formats such as zip}{wxarc}\\
\helpref{wxTarEntry}{wxtarentry}\\
\helpref{wxTarInputStream}{wxtarinputstream}


\latexignore{\rtfignore{\wxheading{Members}}}


\membersection{wxTarOutputStream::wxTarOutputStream}\label{wxtaroutputstreamwxtaroutputstream}

\func{}{wxTarOutputStream}{\param{wxOutputStream\& }{stream}, \param{wxTarFormat }{format = wxTAR\_PAX}, \param{wxMBConv\& }{conv = wxConvLocal}}

\func{}{wxTarOutputStream}{\param{wxOutputStream* }{stream}, \param{wxTarFormat }{format = wxTAR\_PAX}, \param{wxMBConv\& }{conv = wxConvLocal}}

If the parent stream is passed as a pointer then the new filter stream
takes ownership of it. If it is passed by reference then it does not.

In a Unicode build the third parameter {\it conv} is used to translate the
headers fields into an 8-bit encoding. It has no effect on the stream's data.

When the {\it format} is {\it wxTAR\_PAX}, pax extended headers are generated
when any header field will not fit the standard tar header block or if it
uses any non-ascii characters.

Extended headers are stored as extra 'files' within the tar, and will be
extracted as such by any other tar program that does not understand them.
The {\it conv} parameter only affect the standard tar headers, the extended
headers are always UTF-8 encoded.

When the {\it format} is {\it wxTAR\_USTAR}, no extended headers are
generated, and instead a warning message is logged if any header field
overflows.


\membersection{wxTarOutputStream::\destruct{wxTarOutputStream}}\label{wxtaroutputstreamdtor}

\func{}{\destruct{wxTarOutputStream}}{\void}

The destructor calls \helpref{Close()}{wxtaroutputstreamclose} to finish
writing the tar if it has not been called already.


\membersection{wxTarOutputStream::Close}\label{wxtaroutputstreamclose}

\func{bool}{Close}{\void}

Finishes writing the tar, returning true if successful.
Called by the destructor if not called explicitly.


\membersection{wxTarOutputStream::CloseEntry}\label{wxtaroutputstreamcloseentry}

\func{bool}{CloseEntry}{\void}

Close the current entry. It is called implicitly whenever another new
entry is created with \helpref{CopyEntry()}{wxtaroutputstreamcopyentry}
or \helpref{PutNextEntry()}{wxtaroutputstreamputnextentry}, or
when the tar is closed.


\membersection{wxTarOutputStream::CopyArchiveMetaData}\label{wxtaroutputstreamcopyarchivemetadata}

\func{bool}{CopyArchiveMetaData}{\param{wxTarInputStream\& }{s}}

See \helpref{wxArchiveOutputStream::CopyArchiveMetaData}{wxarchiveoutputstreamcopyarchivemetadata}.
For the tar format this function does nothing.


\membersection{wxTarOutputStream::CopyEntry}\label{wxtaroutputstreamcopyentry}

\func{bool}{CopyEntry}{\param{wxTarEntry* }{entry}, \param{wxTarInputStream\& }{inputStream}}

Takes ownership of {\it entry} and uses it to create a new entry
in the tar. {\it entry} is then opened in {\it inputStream} and its contents
copied to this stream.

For some other archive formats CopyEntry() is much more efficient than
transferring the data using Read() and Write() since it will copy them
without decompressing and recompressing them. For tar however it makes
no difference.

For tars on seekable streams, {\it entry} must be from the same tar file
as {\it stream}. For non-seekable streams, {\it entry} must also be the
last thing read from {\it inputStream}.


\membersection{wxTarOutputStream::Get/SetBlockingFactor}\label{wxtaroutputstreamblockingfactor}

\constfunc{int}{GetBlockingFactor}{\void}

\func{void}{SetBlockingFactor}{\param{int }{factor}}

The tar is zero padded to round its size up to {\it BlockingFactor * 512} bytes.

Defaults to 10 for {\it wxTAR\_PAX} and 20 for {\it wxTAR\_USTAR}
(see the \helpref{constructor}{wxtaroutputstreamwxtaroutputstream}), as
specified in the POSIX standards.


\membersection{wxTarOutputStream::PutNextDirEntry}\label{wxtaroutputstreamputnextdirentry}

\func{bool}{PutNextDirEntry}{\param{const wxString\& }{name}, \param{const wxDateTime\& }{dt = wxDateTime::Now()}}

Create a new directory entry
(see \helpref{wxArchiveEntry::IsDir()}{wxarchiveentryisdir})
with the given name and timestamp.

\helpref{PutNextEntry()}{wxtaroutputstreamputnextentry} can
also be used to create directory entries, by supplying a name with
a trailing path separator.


\membersection{wxTarOutputStream::PutNextEntry}\label{wxtaroutputstreamputnextentry}

\func{bool}{PutNextEntry}{\param{wxTarEntry* }{entry}}

Takes ownership of {\it entry} and uses it to create a new entry
in the tar. 

\func{bool}{PutNextEntry}{\param{const wxString\& }{name}, \param{const wxDateTime\& }{dt = wxDateTime::Now()}, \param{wxFileOffset }{size = wxInvalidOffset}}

Create a new entry with the given name, timestamp and size.