From b34c7f3ca9c9ae87313fcb7e9563bc0267756a94 Mon Sep 17 00:00:00 2001
From: Michael Wetherell <mike.wetherell@ntlworld.com>
Date: Sun, 12 Nov 2006 21:49:16 +0000
Subject: [PATCH] Add wxTar docs.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@43375 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
---
 docs/latex/wx/category.tex |   6 +-
 docs/latex/wx/classes.tex  |   1 +
 docs/latex/wx/tarstrm.tex  | 513 +++++++++++++++++++++++++++++++++++++
 3 files changed, 518 insertions(+), 2 deletions(-)
 create mode 100644 docs/latex/wx/tarstrm.tex

diff --git a/docs/latex/wx/category.tex b/docs/latex/wx/category.tex
index 7571c54826..f102836d58 100644
--- a/docs/latex/wx/category.tex
+++ b/docs/latex/wx/category.tex
@@ -555,10 +555,12 @@ libraries, and to provide enhanced functionality.
 \twocolitem{\helpref{wxTempFileOutputStream}{wxtempfileoutputstream}}{Stream to safely replace an existing file}
 \twocolitem{\helpref{wxStringInputStream}{wxstringinputstream}}{String input stream class}
 \twocolitem{\helpref{wxStringOutputStream}{wxstringoutputstream}}{String output stream class}
-\twocolitem{\helpref{wxZlibInputStream}{wxzlibinputstream}}{Zlib (compression) input stream class}
-\twocolitem{\helpref{wxZlibOutputStream}{wxzliboutputstream}}{Zlib (compression) output stream class}
+\twocolitem{\helpref{wxZlibInputStream}{wxzlibinputstream}}{Zlib and gzip (compression) input stream class}
+\twocolitem{\helpref{wxZlibOutputStream}{wxzliboutputstream}}{Zlib and gzip (compression) output stream class}
 \twocolitem{\helpref{wxZipInputStream}{wxzipinputstream}}{Input stream for reading from ZIP archives}
 \twocolitem{\helpref{wxZipOutputStream}{wxzipoutputstream}}{Output stream for writing from ZIP archives}
+\twocolitem{\helpref{wxTarInputStream}{wxtarinputstream}}{Input stream for reading from tar archives}
+\twocolitem{\helpref{wxTarOutputStream}{wxtaroutputstream}}{Output stream for writing from tar archives}
 \twocolitem{\helpref{wxSocketInputStream}{wxsocketinputstream}}{Socket input stream class}
 \twocolitem{\helpref{wxSocketOutputStream}{wxsocketoutputstream}}{Socket output stream class}
 \end{twocollist}
diff --git a/docs/latex/wx/classes.tex b/docs/latex/wx/classes.tex
index e7030d05bf..0b4a51fa58 100644
--- a/docs/latex/wx/classes.tex
+++ b/docs/latex/wx/classes.tex
@@ -389,6 +389,7 @@
 \input sysclevt.tex
 \input sysopt.tex
 \input settings.tex
+\input tarstrm.tex
 \input taskbar.tex
 \input tcpclint.tex
 \input tcpconn.tex
diff --git a/docs/latex/wx/tarstrm.tex b/docs/latex/wx/tarstrm.tex
new file mode 100644
index 0000000000..c5351aba53
--- /dev/null
+++ b/docs/latex/wx/tarstrm.tex
@@ -0,0 +1,513 @@
+%
+% 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::SetGroupName}\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.
+
-- 
2.50.0

