add the missing < > symbols

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

diff --git a/docs/doxygen/overviews/arc.h b/docs/doxygen/overviews/arc.h
index 02be708864ae0b56013c8f50c14d4402f10fc8d2..7e0bc839ac551570910fbf8b2f8c91d3f6aa6a2f 100644 (file)
--- a/docs/doxygen/overviews/arc.h
+++ b/docs/doxygen/overviews/arc.h
@@ -1,5 +1,5 @@
 /////////////////////////////////////////////////////////////////////////////
 /////////////////////////////////////////////////////////////////////////////

-// Name:        arc
+// Name:        arc.h

 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$


@@ -7,114 +7,81 @@
 /////////////////////////////////////////////////////////////////////////////
 
 /*!
 /////////////////////////////////////////////////////////////////////////////
 
 /*!

- 
- @page arc_overview Archive formats such as zip
- 
+
+ @page overview_arc Archive formats such as zip
+

  The archive classes handle archive formats such as zip, tar, rar and cab.
  The archive classes handle archive formats such as zip, tar, rar and cab.

- Currently #wxZip
- and #wxTar classes are included.
+ Currently #wxZip and #wxTar classes are included.
+

  For each archive type, there are the following classes (using zip here
  as an example):
  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.)
- 
- 
- 
- 
- 
+
+ @li wxZipInputStream: input stream
+ @li wxZipOutputStream: output stream
+ @li 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
  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'.
+ that can handle any of the archive types, see @ref overview_arc_generic.
+

  Also see #wxFileSystem for a higher level interface that
  can handle archive files in a generic way.
  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
  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.
+ (see @ref overview_arc_noseek).
+
+ See also #wxFileSystem.
+
+ @li @ref overview_arc_create
+ @li @ref overview_arc_extract
+ @li @ref overview_arc_modify
+ @li @ref overview_arc_byname
+ @li @ref overview_arc_generic
+ @li @ref overview_arc_noseek
+
+
+ <hr>
+
+
+ @section overview_arc_create Creating an archive
+
+ 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:
  Another call to PutNextEntry() closes the current entry and begins the next.
  For example:

- 
+

  @code
  @code

- wxFFileOutputStream out(_T("test.zip"));
+     wxFFileOutputStream out(_T("test.zip"));

      wxZipOutputStream zip(out);
      wxTextOutputStream txt(zip);
      wxString sep(wxFileName::GetPathSeparator());
      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("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
      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.
  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.
+
+
+ @section overview_arc_extract Extracting an archive
+
+ #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().
  When there are no more entries, GetNextEntry() returns @NULL and sets Eof().

- 
+

  @code
  @code

- auto_ptrwxZipEntry entry;
- 
+     auto_ptr<wxZipEntry> entry;
+

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

- 
+

      while (entry.reset(zip.GetNextEntry()), entry.get() != @NULL)
      {
          // access meta-data
      while (entry.reset(zip.GetNextEntry()), entry.get() != @NULL)
      {
          // access meta-data


@@ -122,113 +89,112 @@
          // read 'zip' to access the entry's data
      }
  @endcode
          // read 'zip' to access the entry's data
      }
  @endcode

- 
- 
- 
- @section wxarcmodify Modifying an archive
- 
- @ref arc_overview
+
+
+
+ @section overview_arc_modify Modifying an archive
+

  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().
  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.
  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
  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.
+ losing the whole archive. #wxTempFileOutputStream can be helpful to do this.
+

  For example to delete all entries matching the pattern "*.txt":
  For example to delete all entries matching the pattern "*.txt":

- 
+

  @code
  @code

- auto_ptrwxFFileInputStream in(new wxFFileInputStream(_T("test.zip")));
+     auto_ptr<wxFFileInputStream> in(new wxFFileInputStream(_T("test.zip")));

      wxTempFileOutputStream out(_T("test.zip"));
      wxTempFileOutputStream out(_T("test.zip"));

- 
+

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

- 
-     auto_ptrwxZipEntry entry;
- 
+
+     auto_ptr<wxZipEntry> entry;
+

      // transfer any meta-data for the archive as a whole (the zip comment
      // in the case of zip)
      outzip.CopyArchiveMetaData(inzip);
      // 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;
      // 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();
      // 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
      // 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
+
+
+
+ @section overview_arc_byname Looking up an archive entry by name
+

  Also see #wxFileSystem for a higher level interface that is
  more convenient for accessing archive entries by name.
  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 open just one entry in an archive, the most efficient way is

- to simply search for it linearly by calling
-  #GetNextEntry() until the
+ 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.
  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
  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
+ "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.
  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:
  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
  @code

- auto_ptrwxZipEntry entry;
- 
+     auto_ptr<wxZipEntry> entry;
+

      // convert the local name we are looking for into the internal format
      wxString name = wxZipEntry::GetInternalName(localname);
      // 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);
      // 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);
      // 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
      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
  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.
- 
+ #wxHashMap then entries looked up by name can be opened using the #OpenEntry() method.
+

  @code
  @code

- WX_DECLARE_STRING_HASH_MAP(wxZipEntry*, ZipCatalog);
+     WX_DECLARE_STRING_HASH_MAP(wxZipEntry*, ZipCatalog);

      ZipCatalog::iterator it;
      wxZipEntry *entry;
      ZipCatalog cat;
      ZipCatalog::iterator it;
      wxZipEntry *entry;
      ZipCatalog cat;

- 
+

      // open the zip
      wxFFileInputStream in(_T("test.zip"));
      wxZipInputStream zip(in);
      // 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()];
      // load the zip catalog
      while ((entry = zip.GetNextEntry()) != @NULL) {
          wxZipEntry*& current = cat[entry-GetInternalName()];


@@ -237,117 +203,83 @@
          delete current;
          current = entry;
      }
          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
      // 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:
  To open more than one entry simultaneously you need more than one
  underlying stream on the same archive:

- 
+

  @code
  @code

- // opening another entry without closing the first requires another
+     // 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
      // 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
+
+
+
+ @section overview_arc_generic Generic archive programming
+

  Also see #wxFileSystem for a higher level interface that
  can handle archive files in a generic way.
  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:
  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)
- 
- 
- 
- 
- 
+
+ @li wxArchiveInputStream: input stream
+ @li wxArchiveOutputStream: output stream
+ @li 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.
  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
  To allow this there is a class factory for each archive type, derived from

-  #wxArchiveClassFactory, that can create
- the other classes.
+ #wxArchiveClassFactory, that can create the other classes.
+

  For example, given @e wxArchiveClassFactory* factory, streams and
  entries can be created like this:
  For example, given @e wxArchiveClassFactory* factory, streams and
  entries can be created like this:

- 
+

  @code
  @code

- // create streams without knowing their type
-     auto_ptrwxArchiveInputStream inarc(factory-NewStream(in));
-     auto_ptrwxArchiveOutputStream outarc(factory-NewStream(out));
- 
+     // 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
      // create an empty entry object

-     auto_ptrwxArchiveEntry entry(factory-NewEntry());
+     auto_ptr<wxArchiveEntry> entry(factory-NewEntry());

  @endcode
  @endcode

- 
- For the factory itself, the static member
-  wxArchiveClassFactory::Find().
+
+ 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:
  can be used to find a class factory that can handle a given file
  extension or mime type. For example, given @e filename:

- 
+

  @code
  @code

- const wxArchiveClassFactory *factory;
+     const wxArchiveClassFactory *factory;

      factory = wxArchiveClassFactory::Find(filename, wxSTREAM_FILEEXT);
      factory = wxArchiveClassFactory::Find(filename, wxSTREAM_FILEEXT);

- 
+

      if (factory)
          stream = factory-NewStream(new wxFFileInputStream(filename));
  @endcode
      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.
  @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.
  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().
+ These can be found using wxFilterClassFactory::Find().
+

  For example, to list the contents of archive @e filename:
  For example, to list the contents of archive @e filename:

- 
+

  @code
  @code

- auto_ptrwxInputStream in(new wxFFileInputStream(filename));
- 
+     auto_ptr<wxInputStream> in(new wxFFileInputStream(filename));
+

      if (in-IsOk())
      {
          // look for a filter handler, e.g. for '.gz'
      if (in-IsOk())
      {
          // look for a filter handler, e.g. for '.gz'


@@ -358,14 +290,14 @@
              // pop the extension, so if it was '.tar.gz' it is now just '.tar'
              filename = fcf-PopExtension(filename);
          }
              // 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) {
          // 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;
- 
+             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";
              // list the contents of the archive
              while ((entry.reset(arc-GetNextEntry())), entry.get() != @NULL)
                  std::wcout  entry-GetName().c_str()  "\n";


@@ -375,116 +307,92 @@
          }
      }
  @endcode
          }
      }
  @endcode

- 
- 
- 
- @section wxarcnoseek Archives on non-seekable streams
- 
- @ref arc_overview
+
+
+
+ @section overview_arc_noseek Archives on non-seekable streams
+

  In general, handling archives on non-seekable streams is done in the same
  way as for seekable streams, with a few caveats.
  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 
+
+ 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.
  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.
  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
  @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.
+ 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.
  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.
  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
  @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.
+ 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 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:
  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.
+
+ @li GetSize(): Guaranteed to be available after the entry has been read to #Eof(),
+                or #CloseEntry() has been called
+
+ @li 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.
  @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
  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():
- 
+ required field before writing it with #CopyEntry():
+

  @code
  @code

- auto_ptrwxArchiveInputStream arc(factory-NewStream(in));
-     auto_ptrwxArchiveOutputStream outarc(factory-NewStream(out));
-     auto_ptrwxArchiveEntry entry;
- 
+     auto_ptr<wxArchiveInputStream> arc(factory-NewStream(in));
+     auto_ptr<wxArchiveOutputStream> outarc(factory-NewStream(out));
+     auto_ptr<wxArchiveEntry> entry;
+

      outarc-CopyArchiveMetaData(*arc);
      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;
      }
      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
      bool success = arc-Eof() && outarc-Close();
  @endcode

- 
+

  However, for non-seekable streams, this technique cannot be used for
  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:
- 
+ 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
  {
  @code
  class MyNotifier : public wxArchiveNotifier
  {


@@ -492,36 +400,33 @@
      void OnEntryUpdated(wxArchiveEntry& entry) { entry.SetIsReadOnly(@false); }
  };
  @endcode
      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():
- 
+
+ The meta-data changes are done in your notifier's #OnEntryUpdated() method,
+ then #SetNotifier() is called before CopyEntry():
+

  @code
  @code

- auto_ptrwxArchiveInputStream arc(factory-NewStream(in));
-     auto_ptrwxArchiveOutputStream outarc(factory-NewStream(out));
-     auto_ptrwxArchiveEntry entry;
+     auto_ptr<wxArchiveInputStream> arc(factory-NewStream(in));
+     auto_ptr<wxArchiveOutputStream> outarc(factory-NewStream(out));
+     auto_ptr<wxArchiveEntry> entry;

      MyNotifier notifier;
      MyNotifier notifier;

- 
+

      outarc-CopyArchiveMetaData(*arc);
      outarc-CopyArchiveMetaData(*arc);

- 
+

      while (entry.reset(arc-GetNextEntry()), entry.get() != @NULL) {
          entry-SetNotifier(notifier);
          if (!outarc-CopyEntry(entry.release(), *arc))
              break;
      }
      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
      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.
  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.

- 
- */
- 
- 
+
+*/
+