From b34c7f3ca9c9ae87313fcb7e9563bc0267756a94 Mon Sep 17 00:00:00 2001 From: Michael Wetherell 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} + + + +\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} + + + +\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 . + +\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} + + + +\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} + + + +\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.47.2