Ref counting overview.

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

%
% 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}

<wx/archive.h>

\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}

<wx/archive.h>

\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}

<wx/archive.h>

\wxheading{Data structures}
\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 Arc, class T = typename Arc::entry_type*>
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<wxString, wxArchiveEntry*>).

The {\tt <wx/archive.h>} header defines the following typedefs:

\begin{verbatim}
    typedef wxArchiveIterator<wxArchiveInputStream> wxArchiveIter;

    typedef wxArchiveIterator<wxArchiveInputStream,
             std::pair<wxString, wxArchiveEntry*> > wxArchivePairIter;

\end{verbatim}

The header for any implementation of this interface should define similar
typedefs for its types, for example in {\tt <wx/zipstrm.h>} there is:

\begin{verbatim}
    typedef wxArchiveIterator<wxZipInputStream> wxZipIter;

    typedef wxArchiveIterator<wxZipInputStream,
             std::pair<wxString, wxZipEntry*> > 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<wxArchiveEntry*> 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<ZipEntryPtr> ZipCatalog;
    typedef wxArchiveIterator<wxZipInputStream, ZipEntryPtr> 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<wxString, wxZipEntry*> 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<wxString, ZipEntryPtr> ZipCatalog;
    typedef wxArchiveIterator<wxZipInputStream,
                std::pair<wxString, ZipEntryPtr> > ZipPairIter;
    ZipCatalog cat((ZipPairIter)zip, ZipPairIter());

\end{verbatim}

\wxheading{Derived from}

No base class

\wxheading{Include files}

<wx/archive.h>

\wxheading{See also}

\helpref{wxArchiveEntry}{wxarchiveentry}\\
\helpref{wxArchiveInputStream}{wxarchiveinputstream}\\
\helpref{wxArchiveOutputStream}{wxarchiveoutputstream}

\wxheading{Data structures}
\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{wxarchiveiteratoroperatorstar}

\constfunc{const T\&}{operator*}{\void}

Returns an entry object from the archive input stream, giving away
ownership.


\membersection{wxArchiveIterator::operator++}\label{wxarchiveiteratoroperatorincrement}

\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}

<wx/archive.h>

\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}

<wx/archive.h>

\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.