arc.tex

很牛的GUI源码wxWidgets-2.8.0.zip 可在多种平台下运行.

\subsection{Generic archive programming}\label{wxarcgeneric}

\helpref{Archive formats such as zip}{wxarc}

Also see \helpref{wxFileSystem}{fs} for a higher level interface that
can handle archive files in a generic way.

The specific archive classes, such as the wxZip classes, inherit from
the following abstract classes which can be used to write code that can
handle any of the archive types:

\begin{twocollist}\twocolwidtha{5cm}
\twocolitem{\helpref{wxArchiveInputStream}{wxarchiveinputstream}}{Input stream}
\twocolitem{\helpref{wxArchiveOutputStream}{wxarchiveoutputstream}}{Output stream}
\twocolitem{\helpref{wxArchiveEntry}{wxarchiveentry}}{Holds the meta-data for an
entry (e.g. filename)}
\end{twocollist}

In order to able to write generic code it's necessary to be able to create
instances of the classes without knowing which archive type is being used.
To allow this there is a class factory for each archive type, derived from
 \helpref{wxArchiveClassFactory}{wxarchiveclassfactory}, that can create
the other classes.

For example, given {\it wxArchiveClassFactory* factory}, streams and
entries can be created like this:

\begin{verbatim}
    // create streams without knowing their type
    auto_ptr<wxArchiveInputStream> inarc(factory->NewStream(in));
    auto_ptr<wxArchiveOutputStream> outarc(factory->NewStream(out));

    // create an empty entry object
    auto_ptr<wxArchiveEntry> entry(factory->NewEntry());

\end{verbatim}

For the factory itself, the static member
 \helpref{wxArchiveClassFactory::Find()}{wxarchiveclassfactoryfind}.
can be used to find a class factory that can handle a given file
extension or mime type. For example, given {\it filename}:

\begin{verbatim}
    const wxArchiveClassFactory *factory;
    factory = wxArchiveClassFactory::Find(filename, wxSTREAM_FILEEXT);

    if (factory)
        stream = factory->NewStream(new wxFFileInputStream(filename));

\end{verbatim}

{\it Find} does not give away ownership of the returned pointer, so it
does not need to be deleted.

There are similar class factories for the filter streams that handle the
compression and decompression of a single stream, such as wxGzipInputStream.
These can be found using
 \helpref{wxFilterClassFactory::Find()}{wxfilterclassfactoryfind}.

For example, to list the contents of archive {\it filename}:

\begin{verbatim}
    auto_ptr<wxInputStream> in(new wxFFileInputStream(filename));

    if (in->IsOk())
    {
        // look for a filter handler, e.g. for '.gz'
        const wxFilterClassFactory *fcf;
        fcf = wxFilterClassFactory::Find(filename, wxSTREAM_FILEEXT);
        if (fcf) {
            in.reset(fcf->NewStream(in.release()));
            // pop the extension, so if it was '.tar.gz' it is now just '.tar'
            filename = fcf->PopExtension(filename);
        }

        // look for a archive handler, e.g. for '.zip' or '.tar'
        const wxArchiveClassFactory *acf;
        acf = wxArchiveClassFactory::Find(filename, wxSTREAM_FILEEXT);
        if (acf) {
            auto_ptr<wxArchiveInputStream> arc(acf->NewStream(in.release()));
            auto_ptr<wxArchiveEntry> entry;

            // list the contents of the archive
            while ((entry.reset(arc->GetNextEntry())), entry.get() != NULL)
                std::wcout << entry->GetName().c_str() << "\n";
        }
        else {
            wxLogError(_T("can't handle '%s'"), filename.c_str());
        }
    }

\end{verbatim}


\subsection{Archives on non-seekable streams}\label{wxarcnoseek}

\helpref{Archive formats such as zip}{wxarc}

In general, handling archives on non-seekable streams is done in the same
way as for seekable streams, with a few caveats.

The main limitation is that accessing entries randomly using
 \helpref{OpenEntry()}{wxarchiveinputstreamopenentry} 
is not possible, the entries can only be accessed sequentially in the order 
they are stored within the archive.

For each archive type, there will also be other limitations which will
depend on the order the entries' meta-data is stored within the archive.
These are not too difficult to deal with, and are outlined below.

\wxheading{PutNextEntry and the entry size}

When writing archives, some archive formats store the entry size before
the entry's data (tar has this limitation, zip doesn't). In this case
the entry's size must be passed to
 \helpref{PutNextEntry()}{wxarchiveoutputstreamputnextentry} or an error
occurs.

This is only an issue on non-seekable streams, since otherwise the archive
output stream can seek back and fix up the header once the size of the
entry is known.

For generic programming, one way to handle this is to supply the size
whenever it is known, and rely on the error message from the output
stream when the operation is not supported.

\wxheading{GetNextEntry and the weak reference mechanism}

Some archive formats do not store all an entry's meta-data before the
entry's data (zip is an example). In this case, when reading from a
non-seekable stream, \helpref{GetNextEntry()}{wxarchiveinputstreamgetnextentry} 
can only return a partially populated \helpref{wxArchiveEntry}{wxarchiveentry}
object - not all the fields are set.

The input stream then keeps a weak reference to the entry object and
updates it when more meta-data becomes available. A weak reference being
one that does not prevent you from deleting the wxArchiveEntry object - the
input stream only attempts to update it if it is still around.

The documentation for each archive entry type gives the details
of what meta-data becomes available and when. 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}

This mechanism allows \helpref{CopyEntry()}{wxarchiveoutputstreamcopyentry}
to always fully preserve entries' meta-data. No matter what order order
the meta-data occurs within the archive, the input stream will always
have read it before the output stream must write it.

\wxheading{wxArchiveNotifier}

Notifier objects can be used to get a notification whenever an input
stream updates a \helpref{wxArchiveEntry}{wxarchiveentry} object's data
via the weak reference mechanism.

Consider the following code which renames an entry in an archive.
This is the usual way to modify an entry's meta-data, simply set the
required field before writing it with
 \helpref{CopyEntry()}{wxarchiveoutputstreamcopyentry}:

\begin{verbatim}
    auto_ptr<wxArchiveInputStream> arc(factory->NewStream(in));
    auto_ptr<wxArchiveOutputStream> outarc(factory->NewStream(out));
    auto_ptr<wxArchiveEntry> entry;

    outarc->CopyArchiveMetaData(*arc);

    while (entry.reset(arc->GetNextEntry()), entry.get() != NULL) {
        if (entry->GetName() == from)
            entry->SetName(to);
        if (!outarc->CopyEntry(entry.release(), *arc))
            break;
    }

    bool success = arc->Eof() && outarc->Close();

\end{verbatim}

However, for non-seekable streams, this technique cannot be used for
fields such as \helpref{IsReadOnly()}{wxarchiveentryisreadonly},
which are not necessarily set when
 \helpref{GetNextEntry()}{wxarchiveinputstreamgetnextentry} returns. In
this case a \helpref{wxArchiveNotifier}{wxarchivenotifier} can be used:

\begin{verbatim}
class MyNotifier : public wxArchiveNotifier
{
public:
    void OnEntryUpdated(wxArchiveEntry& entry) { entry.SetIsReadOnly(false); }
};

\end{verbatim}

The meta-data changes are done in your notifier's
 \helpref{OnEntryUpdated()}{wxarchivenotifieronentryupdated} method,
then \helpref{SetNotifier()}{wxarchiveentrynotifier} is called before
CopyEntry():

\begin{verbatim}
    auto_ptr<wxArchiveInputStream> arc(factory->NewStream(in));
    auto_ptr<wxArchiveOutputStream> outarc(factory->NewStream(out));
    auto_ptr<wxArchiveEntry> entry;
    MyNotifier notifier;

    outarc->CopyArchiveMetaData(*arc);

    while (entry.reset(arc->GetNextEntry()), entry.get() != NULL) {
        entry->SetNotifier(notifier);
        if (!outarc->CopyEntry(entry.release(), *arc))
            break;
    }

    bool success = arc->Eof() && outarc->Close();

\end{verbatim}

SetNotifier() calls OnEntryUpdated() immediately, then the input
stream calls it again whenever it sets more fields in the entry. Since
OnEntryUpdated() will be called at least once, this technique always
works even when it is not strictly necessary to use it. For example,
changing the entry name can be done this way too and it works on seekable
streams as well as non-seekable.