% % automatically generated by HelpGen $Revision$ from % wx/archive.h at 16/Sep/04 12:19:29 % \section{\class{wxArchiveClassFactory}}\label{wxarchiveclassfactory} An abstract base class which serves as a common interface to archive class factories such as \helpref{wxZipClassFactory}{wxzipclassfactory}. For each supported archive type (such as zip) there is a class factory derived from wxArchiveClassFactory, which allows archive objects to be created in a generic way, without knowing the particular type of archive being used. \wxheading{Derived from} \helpref{wxObject}{wxobject} \wxheading{Include files} \wxheading{See also} \helpref{Archive formats such as zip}{wxarc}\\ \helpref{Generic archive programming}{wxarcgeneric}\\ \helpref{wxArchiveEntry}{wxarchiveentry}\\ \helpref{wxArchiveInputStream}{wxarchiveinputstream}\\ \helpref{wxArchiveOutputStream}{wxarchiveoutputstream} \latexignore{\rtfignore{\wxheading{Members}}} \membersection{wxArchiveClassFactory::Get/SetConv}\label{wxarchiveclassfactoryconv} \constfunc{wxMBConv\&}{GetConv}{\void} \func{void}{SetConv}{\param{wxMBConv\& }{conv}} The \helpref{wxMBConv}{wxmbconv} object that the created streams will use when translating meta-data. The initial default, set by the constructor, is wxConvLocal. \membersection{wxArchiveClassFactory::GetInternalName}\label{wxarchiveclassfactorygetinternalname} \constfunc{wxString}{GetInternalName}{\param{const wxString\& }{name}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} Calls the static GetInternalName() function for the archive entry type, for example \helpref{wxZipEntry::GetInternalName()}{wxzipentrygetinternalname}. \membersection{wxArchiveClassFactory::NewEntry}\label{wxarchiveclassfactorynewentry} \constfunc{wxArchiveEntry*}{NewEntry}{\void} Create a new \helpref{wxArchiveEntry}{wxarchiveentry} object of the appropriate type. \membersection{wxArchiveClassFactory::NewStream}\label{wxarchiveclassfactorynewstream} \constfunc{wxArchiveInputStream*}{NewStream}{\param{wxInputStream\& }{stream}} \constfunc{wxArchiveOutputStream*}{NewStream}{\param{wxOutputStream\& }{stream}} Create a new \helpref{wxArchiveInputStream}{wxarchiveinputstream} or \helpref{wxArchiveOutputStream}{wxarchiveoutputstream} of the appropriate type. % % automatically generated by HelpGen $Revision$ from % wx/archive.h at 16/Sep/04 12:19:29 % \section{\class{wxArchiveEntry}}\label{wxarchiveentry} An abstract base class which serves as a common interface to archive entry classes such as \helpref{wxZipEntry}{wxzipentry}. These hold the meta-data (filename, timestamp, etc.), for entries in archive files such as zips and tars. \wxheading{Derived from} \helpref{wxObject}{wxobject} \wxheading{Include files} \wxheading{See also} \helpref{Archive formats such as zip}{wxarc}\\ \helpref{Generic archive programming}{wxarcgeneric}\\ \helpref{wxArchiveInputStream}{wxarchiveinputstream}\\ \helpref{wxArchiveOutputStream}{wxarchiveoutputstream}\\ \helpref{wxArchiveNotifier}{wxarchivenotifier} \wxheading{Non-seekable streams} This information applies only when reading archives from non-seekable streams. When the stream is seekable \helpref{GetNextEntry()}{wxarchiveinputstreamgetnextentry} returns a fully populated \helpref{wxArchiveEntry}{wxarchiveentry}. See '\helpref{Archives on non-seekable streams}{wxarcnoseek}' for more information. For generic programming, when the worst case must be assumed, you can rely on all the fields of wxArchiveEntry being fully populated when GetNextEntry() returns, with the the following exceptions: \begin{twocollist}\twocolwidtha{3cm} \twocolitem{\helpref{GetSize()}{wxarchiveentrysize}}{Guaranteed to be available after the entry has been read to \helpref{Eof()}{wxinputstreameof}, or \helpref{CloseEntry()}{wxarchiveinputstreamcloseentry} has been called} \twocolitem{\helpref{IsReadOnly()}{wxarchiveentryisreadonly}}{Guaranteed to be available after the end of the archive has been reached, i.e. after GetNextEntry() returns NULL and Eof() is true} \end{twocollist} \latexignore{\rtfignore{\wxheading{Members}}} \membersection{wxArchiveEntry::Clone}\label{wxarchiveentryclone} \constfunc{wxArchiveEntry*}{Clone}{\void} Returns a copy of this entry object. \membersection{wxArchiveEntry::Get/SetDateTime}\label{wxarchiveentrydatetime} \constfunc{wxDateTime}{GetDateTime}{\void} \func{void}{SetDateTime}{\param{const wxDateTime\& }{dt}} The entry's timestamp. \membersection{wxArchiveEntry::GetInternalFormat}\label{wxarchiveentrygetinternalformat} \constfunc{wxPathFormat}{GetInternalFormat}{\void} Returns the path format used internally within the archive to store filenames. \membersection{wxArchiveEntry::GetInternalName}\label{wxarchiveentrygetinternalname} \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. \wxheading{See also} \helpref{Looking up an archive entry by name}{wxarcbyname} \membersection{wxArchiveEntry::Get/SetName}\label{wxarchiveentryname} \constfunc{wxString}{GetName}{\param{wxPathFormat }{format = wxPATH\_NATIVE}} \func{void}{SetName}{\param{const wxString\& }{name}, \param{wxPathFormat }{format = wxPATH\_NATIVE}} The entry's name, by default in the native format. The name can include directory components, i.e. it can be a full path. If this is a directory entry, (i.e. if \helpref{IsDir()}{wxarchiveentryisdir} is true) then GetName() returns the name with a trailing path separator. Similarly, setting a name with a trailing path separator sets IsDir(). \membersection{wxArchiveEntry::GetOffset}\label{wxarchiveentrygetoffset} \constfunc{off\_t}{GetOffset}{\void} Returns a numeric value unique to the entry within the archive. \membersection{wxArchiveEntry::Get/SetSize}\label{wxarchiveentrysize} \constfunc{off\_t}{GetSize}{\void} \func{void}{SetSize}{\param{off\_t }{size}} The size of the entry's data in bytes. \membersection{wxArchiveEntry::IsDir/SetIsDir}\label{wxarchiveentryisdir} \constfunc{bool}{IsDir}{\void} \func{void}{SetIsDir}{\param{bool }{isDir = true}} True if this is a directory entry. Directory entries are entries with no data, which are used to store the meta-data of directories. They also make it possible for completely empty directories to be stored. The names of entries within an archive can be complete paths, and unarchivers typically create whatever directories are necessary as they restore files, even if the archive contains no explicit directory entries. \membersection{wxArchiveEntry::IsReadOnly/SetIsReadOnly}\label{wxarchiveentryisreadonly} \constfunc{bool}{IsReadOnly}{\void} \func{void}{SetIsReadOnly}{\param{bool }{isReadOnly = true}} True if the entry is a read-only file. \membersection{wxArchiveEntry::Set/UnsetNotifier}\label{wxarchiveentrynotifier} \func{void}{SetNotifier}{\param{wxArchiveNotifier\& }{notifier}} \func{void}{UnsetNotifier}{\void} Sets the \helpref{notifier}{wxarchivenotifier} for this entry. Whenever the \helpref{wxArchiveInputStream}{wxarchiveinputstream} updates this entry, it will then invoke the associated notifier's \helpref{OnEntryUpdated}{wxarchivenotifieronentryupdated} method. Setting a notifier is not usually necessary. It is used to handle certain cases when modifying an archive in a pipeline (i.e. between non-seekable streams). \wxheading{See also} \helpref{Archives on non-seekable streams}{wxarcnoseek}\\ \helpref{wxArchiveNotifier}{wxarchivenotifier} % % automatically generated by HelpGen $Revision$ from % wx/archive.h at 16/Sep/04 12:19:29 % \section{\class{wxArchiveInputStream}}\label{wxarchiveinputstream} An abstract base class which serves as a common interface to archive input streams such as \helpref{wxZipInputStream}{wxzipinputstream}. \helpref{GetNextEntry()}{wxarchiveinputstreamgetnextentry} returns an \helpref{wxArchiveEntry}{wxarchiveentry} object containing the meta-data for the next entry in the archive (and gives away ownership). Reading from the wxArchiveInputStream 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(). \wxheading{Derived from} \helpref{wxFilterInputStream}{wxfilterinputstream} \wxheading{Include files} \wxheading{Data structures} {\small \begin{verbatim} typedef wxArchiveEntry entry\_type \end{verbatim}} \wxheading{See also} \helpref{Archive formats such as zip}{wxarc}\\ \helpref{wxArchiveEntry}{wxarchiveentry}\\ \helpref{wxArchiveOutputStream}{wxarchiveoutputstream} \latexignore{\rtfignore{\wxheading{Members}}} \membersection{wxArchiveInputStream::CloseEntry}\label{wxarchiveinputstreamcloseentry} \func{bool}{CloseEntry}{\void} Closes the current entry. On a non-seekable stream reads to the end of the current entry first. \membersection{wxArchiveInputStream::GetNextEntry}\label{wxarchiveinputstreamgetnextentry} \func{wxArchiveEntry*}{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{wxArchiveEntry}{wxarchiveentry} object, giving away ownership. Reading this wxArchiveInputStream then returns the entry's data. \membersection{wxArchiveInputStream::OpenEntry}\label{wxarchiveinputstreamopenentry} \func{bool}{OpenEntry}{\param{wxArchiveEntry\& }{entry}} Closes the current entry if one is open, then opens the entry specified by the \helpref{wxArchiveEntry}{wxarchiveentry} object. {\it entry} must be from the same archive file that this wxArchiveInputStream is reading, and it must be reading it from a seekable stream. \wxheading{See also} \helpref{Looking up an archive entry by name}{wxarcbyname} % % automatically generated by HelpGen $Revision$ from % wx/archive.h at 16/Sep/04 12:19:29 % \section{\class{wxArchiveIterator}}\label{wxarchiveiterator} An input iterator template class that can be used to transfer an archive's catalogue to a container. It is only available if wxUSE\_STL is set to 1 in setup.h, and the uses for it outlined below require a compiler which supports member templates. \begin{verbatim} template class wxArchiveIterator { // this constructor creates an 'end of sequence' object wxArchiveIterator(); // template parameter 'Arc' should be the type of an archive input stream wxArchiveIterator(Arc& arc) { /* ... */ }; \end{verbatim} The first template parameter should be the type of archive input stream (e.g. \helpref{wxArchiveInputStream}{wxarchiveinputstream}) and the second can either be a pointer to an entry (e.g. \helpref{wxArchiveEntry}{wxarchiveentry}*), or a string/pointer pair (e.g. std::pair). The {\tt } header defines the following typedefs: \begin{verbatim} typedef wxArchiveIterator wxArchiveIter; typedef wxArchiveIterator > wxArchivePairIter; \end{verbatim} The header for any implementation of this interface should define similar typedefs for its types, for example in {\tt } there is: \begin{verbatim} typedef wxArchiveIterator wxZipIter; typedef wxArchiveIterator > wxZipPairIter; \end{verbatim} Transferring the catalogue of an archive {\it arc} to a vector {\it cat}, can then be done something like this: \begin{verbatim} std::vector cat((wxArchiveIter)arc, wxArchiveIter()); \end{verbatim} When the iterator is dereferenced, it gives away ownership of an entry object. So in the above example, when you have finished with {\it cat} you must delete the pointers it contains. If you have smart pointers with normal copy semantics (i.e. not auto\_ptr or \helpref{wxScopedPtr}{wxscopedptr}), then you can create an iterator which uses them instead. For example, with a smart pointer class for zip entries {\it ZipEntryPtr}: \begin{verbatim} typedef std::vector ZipCatalog; typedef wxArchiveIterator ZipIter; ZipCatalog cat((ZipIter)zip, ZipIter()); \end{verbatim} Iterators that return std::pair objects can be used to populate a std::multimap, to allow entries to be looked up by name. The string is initialised using the wxArchiveEntry object's \helpref{GetInternalName()}{wxarchiveentrygetinternalname} function. \begin{verbatim} typedef std::multimap ZipCatalog; ZipCatalog cat((wxZipPairIter)zip, wxZipPairIter()); \end{verbatim} Note that this iterator also gives away ownership of an entry object each time it is dereferenced. So in the above example, when you have finished with {\it cat} you must delete the pointers it contains. Or if you have them, a pair containing a smart pointer can be used (again {\it ZipEntryPtr}), no worries about ownership: \begin{verbatim} typedef std::multimap ZipCatalog; typedef wxArchiveIterator > ZipPairIter; ZipCatalog cat((ZipPairIter)zip, ZipPairIter()); \end{verbatim} \wxheading{Derived from} No base class \wxheading{Include files} \wxheading{See also} \helpref{wxArchiveEntry}{wxarchiveentry}\\ \helpref{wxArchiveInputStream}{wxarchiveinputstream}\\ \helpref{wxArchiveOutputStream}{wxarchiveoutputstream} \wxheading{Data structures} {\small \begin{verbatim} typedef std::input\_iterator\_tag iterator\_category typedef T value\_type typedef ptrdiff\_t difference\_type typedef T* pointer typedef T\& reference \end{verbatim}} \latexignore{\rtfignore{\wxheading{Members}}} \membersection{wxArchiveIterator::wxArchiveIterator}\label{wxarchiveiteratorwxarchiveiterator} \func{}{wxArchiveIterator}{\void} Construct an 'end of sequence' instance. \func{}{wxArchiveIterator}{\param{Arc\& }{arc}} Construct iterator that returns all the entries in the archive input stream {\it arc}. \membersection{wxArchiveIterator::operator*}\label{wxarchiveiteratoroperatorunknown} \constfunc{const T\&}{operator*}{\void} Returns an entry object from the archive input stream, giving away ownership. \membersection{wxArchiveIterator::operator++}\label{wxarchiveiteratoroperatorunknown} \func{wxArchiveIterator\&}{operator++}{\void} \func{wxArchiveIterator\&}{operator++}{\param{int}{}} Position the input iterator at the next entry in the archive input stream. % % automatically generated by HelpGen $Revision$ from % wx/archive.h at 16/Sep/04 12:19:29 % \section{\class{wxArchiveNotifier}}\label{wxarchivenotifier} If you need to know when a \helpref{wxArchiveInputStream}{wxarchiveinputstream} updates a \helpref{wxArchiveEntry}{wxarchiveentry} object, you can create a notifier by deriving from this abstract base class, overriding \helpref{OnEntryUpdated()}{wxarchivenotifieronentryupdated}. An instance of your notifier class can then be assigned to the wxArchiveEntry object using \helpref{wxArchiveEntry::SetNotifier()}{wxarchiveentrynotifier}. Your OnEntryUpdated() method will then be invoked whenever the input stream updates the entry. Setting a notifier is not usually necessary. It is used to handle certain cases when modifying an archive in a pipeline (i.e. between non-seekable streams). See \helpref{Archives on non-seekable streams}{wxarcnoseek}. \wxheading{Derived from} No base class \wxheading{Include files} \wxheading{See also} \helpref{Archives on non-seekable streams}{wxarcnoseek}\\ \helpref{wxArchiveEntry}{wxarchiveentry}\\ \helpref{wxArchiveInputStream}{wxarchiveinputstream}\\ \helpref{wxArchiveOutputStream}{wxarchiveoutputstream} \latexignore{\rtfignore{\wxheading{Members}}} \membersection{wxArchiveNotifier::OnEntryUpdated}\label{wxarchivenotifieronentryupdated} \func{void}{OnEntryUpdated}{\param{class wxArchiveEntry\& }{entry}} This method must be overridden in your derived class. % % automatically generated by HelpGen $Revision$ from % wx/archive.h at 16/Sep/04 12:19:29 % \section{\class{wxArchiveOutputStream}}\label{wxarchiveoutputstream} An abstract base class which serves as a common interface to archive output streams such as \helpref{wxZipOutputStream}{wxzipoutputstream}. \helpref{PutNextEntry()}{wxarchiveoutputstreamputnextentry} is used to create a new entry in the output archive, then the entry's data is written to the wxArchiveOutputStream. Another call to PutNextEntry() closes the current entry and begins the next. \wxheading{Derived from} \helpref{wxFilterOutputStream}{wxfilteroutputstream} \wxheading{Include files} \wxheading{See also} \helpref{Archive formats such as zip}{wxarc}\\ \helpref{wxArchiveEntry}{wxarchiveentry}\\ \helpref{wxArchiveInputStream}{wxarchiveinputstream} \latexignore{\rtfignore{\wxheading{Members}}} \membersection{wxArchiveOutputStream::\destruct{wxArchiveOutputStream}}\label{wxarchiveoutputstreamdtor} \func{}{\destruct{wxArchiveOutputStream}}{\void} Calls \helpref{Close()}{wxarchiveoutputstreamclose} if it has not already been called. \membersection{wxArchiveOutputStream::Close}\label{wxarchiveoutputstreamclose} \func{bool}{Close}{\void} Closes the archive, returning true if it was successfully written. Called by the destructor if not called explicitly. \membersection{wxArchiveOutputStream::CloseEntry}\label{wxarchiveoutputstreamcloseentry} \func{bool}{CloseEntry}{\void} Close the current entry. It is called implicitly whenever another new entry is created with \helpref{CopyEntry()}{wxarchiveoutputstreamcopyentry} or \helpref{PutNextEntry()}{wxarchiveoutputstreamputnextentry}, or when the archive is closed. \membersection{wxArchiveOutputStream::CopyArchiveMetaData}\label{wxarchiveoutputstreamcopyarchivemetadata} \func{bool}{CopyArchiveMetaData}{\param{wxArchiveInputStream\& }{stream}} Some archive formats have additional meta-data that applies to the archive as a whole. For example in the case of zip there is a comment, which is stored at the end of the zip file. CopyArchiveMetaData() can be used to transfer such information when writing a modified copy of an archive. Since the position of the meta-data can vary between the various archive formats, it is best to call CopyArchiveMetaData() before transferring the entries. The \helpref{wxArchiveOutputStream}{wxarchiveoutputstream} will then hold on to the meta-data and write it at the correct point in the output file. When the input archive is being read from a non-seekable stream, the meta-data may not be available when CopyArchiveMetaData() is called, in which case the two streams set up a link and transfer the data when it becomes available. \membersection{wxArchiveOutputStream::CopyEntry}\label{wxarchiveoutputstreamcopyentry} \func{bool}{CopyEntry}{\param{wxArchiveEntry* }{entry}, \param{wxArchiveInputStream\& }{stream}} Takes ownership of {\it entry} and uses it to create a new entry in the archive. {\it entry} is then opened in the input stream {\it stream} and its contents copied to this stream. For archive types which compress entry data, CopyEntry() is likely to be much more efficient than transferring the data using Read() and Write() since it will copy them without decompressing and recompressing them. {\it entry} must be from the same archive file that {\it stream} is accessing. For non-seekable streams, {\it entry} must also be the last thing read from {\it stream}. \membersection{wxArchiveOutputStream::PutNextDirEntry}\label{wxarchiveoutputstreamputnextdirentry} \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()}{wxarchiveoutputstreamputnextentry} can also be used to create directory entries, by supplying a name with a trailing path separator. \membersection{wxArchiveOutputStream::PutNextEntry}\label{wxarchiveoutputstreamputnextentry} \func{bool}{PutNextEntry}{\param{wxArchiveEntry* }{entry}} Takes ownership of {\it entry} and uses it to create a new entry in the archive. The entry's data can then be written by writing to this wxArchiveOutputStream. \func{bool}{PutNextEntry}{\param{const wxString\& }{name}, \param{const wxDateTime\& }{dt = wxDateTime::Now()}, \param{off\_t }{size = wxInvalidOffset}} Create a new entry with the given name, timestamp and size. The entry's data can then be written by writing to this wxArchiveOutputStream.