use @subpage where possible instead of @ref

[wxWidgets.git] / docs / doxygen / overviews / arc.h

/////////////////////////////////////////////////////////////////////////////
// Name:        arc
// Purpose:     topic overview
// Author:      wxWidgets team
// RCS-ID:      $Id$
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////

/*!

 @page arc_overview Archive formats such as zip

 The archive classes handle archive formats such as zip, tar, rar and cab.
 Currently #wxZip
 and #wxTar classes are included.
 For each archive type, there are the following classes (using zip here
 as an example):






 #wxZipInputStream




 Input stream





 #wxZipOutputStream




 Output stream





 #wxZipEntry




 Holds the meta-data for an
 entry (e.g. filename, timestamp, etc.)





 There are also abstract wxArchive classes that can be used to write code
 that can handle any of the archive types,
 see '@ref arcgeneric_overview'.
 Also see #wxFileSystem for a higher level interface that
 can handle archive files in a generic way.
 The classes are designed to handle archives on both seekable streams such
 as disk files, or non-seekable streams such as pipes and sockets
 (see '@ref arcnoseek_overview').
 @b See also
 #wxFileSystem

 @ref arccreate_overview
 @ref arcextract_overview
 @ref arcmodify_overview
 @ref arcbyname_overview
 @ref arcgeneric_overview
 @ref arcnoseek_overview


 @section wxarccreate Creating an archive

 @ref arc_overview
 Call #PutNextEntry() to
 create each new entry in the archive, then write the entry's data.
 Another call to PutNextEntry() closes the current entry and begins the next.
 For example:

 @code
 wxFFileOutputStream out(_T("test.zip"));
     wxZipOutputStream zip(out);
     wxTextOutputStream txt(zip);
     wxString sep(wxFileName::GetPathSeparator());

     zip.PutNextEntry(_T("entry1.txt"));
     txt  _T("Some text for entry1.txt\n");

     zip.PutNextEntry(_T("subdir") + sep + _T("entry2.txt"));
     txt  _T("Some text for subdir/entry2.txt\n");
 @endcode

 The name of each entry can be a full path, which makes it possible to
 store entries in subdirectories.


 @section wxarcextract Extracting an archive

 @ref arc_overview
 #GetNextEntry() returns a pointer
 to entry object containing the meta-data for the next entry in the archive
 (and gives away ownership). Reading from the input stream 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().

 @code
 auto_ptrwxZipEntry entry;

     wxFFileInputStream in(_T("test.zip"));
     wxZipInputStream zip(in);

     while (entry.reset(zip.GetNextEntry()), entry.get() != @NULL)
     {
         // access meta-data
         wxString name = entry-GetName();
         // read 'zip' to access the entry's data
     }
 @endcode



 @section wxarcmodify Modifying an archive

 @ref arc_overview
 To modify an existing archive, write a new copy of the archive to a new file,
 making any necessary changes along the way and transferring any unchanged
 entries using #CopyEntry().
 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.
 In general modifications are not possible without rewriting the archive,
 though it may be possible in some limited cases. Even then, rewriting the
 archive is usually a better choice since a failure can be handled without
 losing the whole
 archive. #wxTempFileOutputStream can
 be helpful to do this.
 For example to delete all entries matching the pattern "*.txt":

 @code
 auto_ptrwxFFileInputStream in(new wxFFileInputStream(_T("test.zip")));
     wxTempFileOutputStream out(_T("test.zip"));

     wxZipInputStream inzip(*in);
     wxZipOutputStream outzip(out);

     auto_ptrwxZipEntry entry;

     // transfer any meta-data for the archive as a whole (the zip comment
     // in the case of zip)
     outzip.CopyArchiveMetaData(inzip);

     // call CopyEntry for each entry except those matching the pattern
     while (entry.reset(inzip.GetNextEntry()), entry.get() != @NULL)
         if (!entry-GetName().Matches(_T("*.txt")))
             if (!outzip.CopyEntry(entry.release(), inzip))
                 break;

     // close the input stream by releasing the pointer to it, do this
     // before closing the output stream so that the file can be replaced
     in.reset();

     // you can check for success as follows
     bool success = inzip.Eof() && outzip.Close() && out.Commit();
 @endcode



 @section wxarcbyname Looking up an archive entry by name

 @ref arc_overview
 Also see #wxFileSystem for a higher level interface that is
 more convenient for accessing archive entries by name.
 To open just one entry in an archive, the most efficient way is
 to simply search for it linearly by calling
  #GetNextEntry() until the
 required entry is found. This works both for archives on seekable and
 non-seekable streams.
 The format of filenames in the archive is likely to be different
 from the local filename format. For example zips and tars use
 unix style names, with forward slashes as the path separator,
 and absolute paths are not allowed. So if on Windows the file
 "C:\MYDIR\MYFILE.TXT" is stored, then when reading
 the entry back #GetName() will return
 "MYDIR\MYFILE.TXT". The conversion into the internal format
 and back has lost some information.
 So to avoid ambiguity when searching for an entry matching a local name,
 it is better to convert the local name to the archive's internal format
 and search for that:

 @code
 auto_ptrwxZipEntry entry;

     // convert the local name we are looking for into the internal format
     wxString name = wxZipEntry::GetInternalName(localname);

     // open the zip
     wxFFileInputStream in(_T("test.zip"));
     wxZipInputStream zip(in);

     // call GetNextEntry() until the required internal name is found
     do {
         entry.reset(zip.GetNextEntry());
     }
     while (entry.get() != @NULL && entry-GetInternalName() != name);

     if (entry.get() != @NULL) {
         // read the entry's data...
     }
 @endcode

 To access several entries randomly, it is most efficient to transfer the
 entire catalogue of entries to a container such as a std::map or a
  #wxHashMap then entries looked up by name can be
 opened using the #OpenEntry() method.

 @code
 WX_DECLARE_STRING_HASH_MAP(wxZipEntry*, ZipCatalog);
     ZipCatalog::iterator it;
     wxZipEntry *entry;
     ZipCatalog cat;

     // open the zip
     wxFFileInputStream in(_T("test.zip"));
     wxZipInputStream zip(in);

     // load the zip catalog
     while ((entry = zip.GetNextEntry()) != @NULL) {
         wxZipEntry*& current = cat[entry-GetInternalName()];
         // some archive formats can have multiple entries with the same name
         // (e.g. tar) though it is an error in the case of zip
         delete current;
         current = entry;
     }

     // open an entry by name
     if ((it = cat.find(wxZipEntry::GetInternalName(localname))) != cat.end()) {
         zip.OpenEntry(*it-second);
         // ... now read entry's data
     }
 @endcode

 To open more than one entry simultaneously you need more than one
 underlying stream on the same archive:

 @code
 // opening another entry without closing the first requires another
     // input stream for the same file
     wxFFileInputStream in2(_T("test.zip"));
     wxZipInputStream zip2(in2);
     if ((it = cat.find(wxZipEntry::GetInternalName(local2))) != cat.end())
         zip2.OpenEntry(*it-second);
 @endcode



 @section wxarcgeneric Generic archive programming

 @ref arc_overview
 Also see #wxFileSystem 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:






 #wxArchiveInputStream




 Input stream





 #wxArchiveOutputStream




 Output stream





 #wxArchiveEntry




 Holds the meta-data for an
 entry (e.g. filename)





 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
  #wxArchiveClassFactory, that can create
 the other classes.
 For example, given @e wxArchiveClassFactory* factory, streams and
 entries can be created like this:

 @code
 // create streams without knowing their type
     auto_ptrwxArchiveInputStream inarc(factory-NewStream(in));
     auto_ptrwxArchiveOutputStream outarc(factory-NewStream(out));

     // create an empty entry object
     auto_ptrwxArchiveEntry entry(factory-NewEntry());
 @endcode

 For the factory itself, the static member
  wxArchiveClassFactory::Find().
 can be used to find a class factory that can handle a given file
 extension or mime type. For example, given @e filename:

 @code
 const wxArchiveClassFactory *factory;
     factory = wxArchiveClassFactory::Find(filename, wxSTREAM_FILEEXT);

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

 @e 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
  wxFilterClassFactory::Find().
 For example, to list the contents of archive @e filename:

 @code
 auto_ptrwxInputStream 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_ptrwxArchiveInputStream arc(acf-NewStream(in.release()));
             auto_ptrwxArchiveEntry 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());
         }
     }
 @endcode



 @section wxarcnoseek Archives on non-seekable streams

 @ref arc_overview
 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
  #OpenEntry()
 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.
 @b 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
  #PutNextEntry() 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.
 @b 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, #GetNextEntry()
 can only return a partially populated #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:






 #GetSize()




 Guaranteed to be
 available after the entry has been read to #Eof(),
 or #CloseEntry() has been called





 #IsReadOnly()




 Guaranteed to
 be available after the end of the archive has been reached, i.e. after
 GetNextEntry() returns @NULL and Eof() is @true





 This mechanism allows #CopyEntry()
 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.
 @b wxArchiveNotifier
 Notifier objects can be used to get a notification whenever an input
 stream updates a #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
  #CopyEntry():

 @code
 auto_ptrwxArchiveInputStream arc(factory-NewStream(in));
     auto_ptrwxArchiveOutputStream outarc(factory-NewStream(out));
     auto_ptrwxArchiveEntry 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();
 @endcode

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

 @code
 class MyNotifier : public wxArchiveNotifier
 {
 public:
     void OnEntryUpdated(wxArchiveEntry& entry) { entry.SetIsReadOnly(@false); }
 };
 @endcode

 The meta-data changes are done in your notifier's
  #OnEntryUpdated() method,
 then #SetNotifier() is called before
 CopyEntry():

 @code
 auto_ptrwxArchiveInputStream arc(factory-NewStream(in));
     auto_ptrwxArchiveOutputStream outarc(factory-NewStream(out));
     auto_ptrwxArchiveEntry 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();
 @endcode

 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.

 */