Clarify that wxFileSystem::OpenFile() takes URL, not filename.

[wxWidgets.git] / interface / wx / zipstrm.h

diff --git a/interface/wx/zipstrm.h b/interface/wx/zipstrm.h
index 13415333c109da4abedaebb76484afe69801f61d..0122fff594f8d5f85217ec2c01a774f7ac7d46a9 100644 (file)
--- a/interface/wx/zipstrm.h
+++ b/interface/wx/zipstrm.h
@@ -6,35 +6,109 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 

+
+
+/// Compression Method, only 0 (store) and 8 (deflate) are supported here
+enum wxZipMethod
+{
+    wxZIP_METHOD_STORE,
+    wxZIP_METHOD_SHRINK,
+    wxZIP_METHOD_REDUCE1,
+    wxZIP_METHOD_REDUCE2,
+    wxZIP_METHOD_REDUCE3,
+    wxZIP_METHOD_REDUCE4,
+    wxZIP_METHOD_IMPLODE,
+    wxZIP_METHOD_TOKENIZE,
+    wxZIP_METHOD_DEFLATE,
+    wxZIP_METHOD_DEFLATE64,
+    wxZIP_METHOD_BZIP2 = 12,
+    wxZIP_METHOD_DEFAULT = 0xffff
+};
+
+/// Originating File-System.
+///
+/// These are Pkware's values. Note that Info-zip disagree on some of them,
+/// most notably NTFS.
+enum wxZipSystem
+{
+    wxZIP_SYSTEM_MSDOS,
+    wxZIP_SYSTEM_AMIGA,
+    wxZIP_SYSTEM_OPENVMS,
+    wxZIP_SYSTEM_UNIX,
+    wxZIP_SYSTEM_VM_CMS,
+    wxZIP_SYSTEM_ATARI_ST,
+    wxZIP_SYSTEM_OS2_HPFS,
+    wxZIP_SYSTEM_MACINTOSH,
+    wxZIP_SYSTEM_Z_SYSTEM,
+    wxZIP_SYSTEM_CPM,
+    wxZIP_SYSTEM_WINDOWS_NTFS,
+    wxZIP_SYSTEM_MVS,
+    wxZIP_SYSTEM_VSE,
+    wxZIP_SYSTEM_ACORN_RISC,
+    wxZIP_SYSTEM_VFAT,
+    wxZIP_SYSTEM_ALTERNATE_MVS,
+    wxZIP_SYSTEM_BEOS,
+    wxZIP_SYSTEM_TANDEM,
+    wxZIP_SYSTEM_OS_400
+};
+
+/// Dos/Win file attributes
+enum wxZipAttributes
+{
+    wxZIP_A_RDONLY = 0x01,
+    wxZIP_A_HIDDEN = 0x02,
+    wxZIP_A_SYSTEM = 0x04,
+    wxZIP_A_SUBDIR = 0x10,
+    wxZIP_A_ARCH   = 0x20,
+
+    wxZIP_A_MASK   = 0x37
+};
+
+/// Values for the flags field in the zip headers
+enum wxZipFlags
+{
+    wxZIP_ENCRYPTED         = 0x0001,
+    wxZIP_DEFLATE_NORMAL    = 0x0000,   // normal compression
+    wxZIP_DEFLATE_EXTRA     = 0x0002,   // extra compression
+    wxZIP_DEFLATE_FAST      = 0x0004,   // fast compression
+    wxZIP_DEFLATE_SUPERFAST = 0x0006,   // superfast compression
+    wxZIP_DEFLATE_MASK      = 0x0006,
+    wxZIP_SUMS_FOLLOW       = 0x0008,   // crc and sizes come after the data
+    wxZIP_ENHANCED          = 0x0010,
+    wxZIP_PATCH             = 0x0020,
+    wxZIP_STRONG_ENC        = 0x0040,
+    wxZIP_UNUSED            = 0x0F80,
+    wxZIP_RESERVED          = 0xF000
+};
+
+

 /**
     @class wxZipNotifier
 
 /**
     @class wxZipNotifier
 

-    If you need to know when a wxZipInputStream
-    updates a wxZipEntry,
+    If you need to know when a wxZipInputStream updates a wxZipEntry,

     you can create a notifier by deriving from this abstract base class,
     you can create a notifier by deriving from this abstract base class,

-    overriding wxZipNotifier::OnEntryUpdated.
+    overriding wxZipNotifier::OnEntryUpdated().
+

     An instance of your notifier class can then be assigned to wxZipEntry
     An instance of your notifier class can then be assigned to wxZipEntry

-    objects, using wxZipEntry::SetNotifier.
+    objects, using wxZipEntry::SetNotifier().

 
     Setting a notifier is not usually necessary. It is used to handle
     certain cases when modifying an zip in a pipeline (i.e. between
     non-seekable streams).
 
     Setting a notifier is not usually necessary. It is used to handle
     certain cases when modifying an zip in a pipeline (i.e. between
     non-seekable streams).

-    See '@ref overview_wxarcnoseek "Archives on non-seekable streams"'.
+    See @ref overview_archive_noseek.

 
     @library{wxbase}
 
     @library{wxbase}

-    @category{FIXME}
+    @category{archive,streams}

 
 

-    @see @ref overview_wxarcnoseek "Archives on non-seekable streams", wxZipEntry,
-    wxZipInputStream, wxZipOutputStream
+    @see @ref overview_archive_noseek, wxZipEntry, wxZipInputStream, wxZipOutputStream

 */
 class wxZipNotifier
 {
 public:
     /**
 */
 class wxZipNotifier
 {
 public:
     /**

-        Override this to receive notifications when
-        an wxZipEntry object changes.
+        Override this to receive notifications when an wxZipEntry object changes.

     */
     */

-    void OnEntryUpdated(wxZipEntry& entry);
+    virtual void OnEntryUpdated(wxZipEntry& entry) = 0;

 };
 
 
 };
 
 


@@ -44,22 +118,63 @@ public:
 
     Holds the meta-data for an entry in a zip.
 
 
     Holds the meta-data for an entry in a zip.
 

+    @section zipentry_avail Field availability
+
+    When reading a zip from a stream that is seekable, wxZipEntry::GetNextEntry()
+    returns a fully populated wxZipEntry object except for wxZipEntry::GetLocalExtra().
+    wxZipEntry::GetLocalExtra() becomes available when the entry is opened, either by
+    calling wxZipInputStream::OpenEntry() or by making an attempt to read the entry's data.
+
+    For zips on non-seekable streams, the following fields are always available
+    when wxZipEntry::GetNextEntry() returns:
+    - wxZipEntry::GetDateTime
+    - wxZipEntry::GetInternalFormat
+    - wxZipEntry::GetInternalName
+    - wxZipEntry::GetFlags
+    - wxZipEntry::GetLocalExtra
+    - wxZipEntry::GetMethod
+    - wxZipEntry::GetName
+    - wxZipEntry::GetOffset
+    - wxZipEntry::IsDir
+
+    The following fields are also usually available when GetNextEntry() returns,
+    however, if the zip was also written to a non-seekable stream the zipper is
+    permitted to store them after the entry's data. In that case they become
+    available when the entry's data has been read to Eof(), or CloseEntry()
+    has been called. (GetFlags() & wxZIP_SUMS_FOLLOW) != 0 indicates that
+    one or more of these come after the data:
+    - wxZipEntry::GetCompressedSize
+    - wxZipEntry::GetCrc
+    - wxZipEntry::GetSize
+
+    The following are stored at the end of the zip, and become available when the
+    end of the zip has been reached, i.e. after GetNextEntry() returns @NULL
+    and Eof() is true:
+    - wxZipEntry::GetComment
+    - wxZipEntry::GetExternalAttributes
+    - wxZipEntry::GetExtra
+    - wxZipEntry::GetMode
+    - wxZipEntry::GetSystemMadeBy
+    - wxZipEntry::IsReadOnly
+    - wxZipEntry::IsMadeByUnix
+    - wxZipEntry::IsText
+

     @library{wxbase}
     @library{wxbase}

-    @category{FIXME}
+    @category{archive,streams}

 
 

-    @see @ref overview_wxarc "Archive formats such as zip", wxZipInputStream,
-    wxZipOutputStream, wxZipNotifier
+    @see @ref overview_archive, wxZipInputStream, wxZipOutputStream, wxZipNotifier

 */
 class wxZipEntry : public wxArchiveEntry
 {
 public:
 */
 class wxZipEntry : public wxArchiveEntry
 {
 public:

-    //@{
+    wxZipEntry(const wxString& name = wxEmptyString,
+               const wxDateTime& dt = Now(),
+               wxFileOffset size = wxInvalidOffset);
+

     /**
         Copy constructor.
     */
     /**
         Copy constructor.
     */

-    wxZipEntry(const wxString& name = wxEmptyString);

     wxZipEntry(const wxZipEntry& entry);
     wxZipEntry(const wxZipEntry& entry);

-    //@}

 
     /**
         Make a copy of this entry.
 
     /**
         Make a copy of this entry.


@@ -68,97 +183,101 @@ public:
 
     //@{
     /**
 
     //@{
     /**

-        A short comment for this entry.
+        Gets and sets the short comment for this entry.

     */
     */

-    wxString GetComment();
-    const void SetComment(const wxString& comment);
+    wxString GetComment() const;
+    void SetComment(const wxString& comment);

     //@}
 
     //@{
     /**
         The low 8 bits are always the DOS/Windows file attributes for this entry.
     //@}
 
     //@{
     /**
         The low 8 bits are always the DOS/Windows file attributes for this entry.

-        The values of these attributes are given in the
-        enumeration @c wxZipAttributes.
-        The remaining bits can store platform specific permission bits or
-        attributes, and their meaning depends on the value
-        of @ref systemmadeby() SetSystemMadeBy.
-        If IsMadeByUnix() is @true then the
-        high 16 bits are unix mode bits.
-        The following other accessors access these bits:
-        @ref wxArchiveEntry::isreadonly IsReadOnly/SetIsReadOnly
+        The values of these attributes are given in the enumeration ::wxZipAttributes.

 
 

-        @ref wxArchiveEntry::isdir IsDir/SetIsDir
+        The remaining bits can store platform specific permission bits or
+        attributes, and their meaning depends on the value of SetSystemMadeBy().
+        If IsMadeByUnix() is @true then the high 16 bits are unix mode bits.

 
 

-        @ref mode() Get/SetMode
+        The following other accessors access these bits:
+        - IsReadOnly() / SetIsReadOnly()
+        - IsDir() / SetIsDir()
+        - GetMode() / SetMode()

     */
     */

-    wxUint32 GetExternalAttributes();
-    const void SetExternalAttributes(wxUint32 attr);
+    wxUint32 GetExternalAttributes() const;
+    void SetExternalAttributes(wxUint32 attr);

     //@}
 
     //@{
     /**
         The extra field from the entry's central directory record.
     //@}
 
     //@{
     /**
         The extra field from the entry's central directory record.

+

         The extra field is used to store platform or application specific
         data. See Pkware's document 'appnote.txt' for information on its format.
     */
         The extra field is used to store platform or application specific
         data. See Pkware's document 'appnote.txt' for information on its format.
     */

-    const char* GetExtra();
-    const size_t GetExtraLen();
-    const void SetExtra(const char* extra, size_t len);
+    const char* GetExtra() const;
+    size_t GetExtraLen() const;
+    void SetExtra(const char* extra, size_t len);

     //@}
 
     //@{
     /**
         The extra field from the entry's local record.
     //@}
 
     //@{
     /**
         The extra field from the entry's local record.

+

         The extra field is used to store platform or application specific
         data. See Pkware's document 'appnote.txt' for information on its format.
     */
         The extra field is used to store platform or application specific
         data. See Pkware's document 'appnote.txt' for information on its format.
     */

-    const char* GetLocalExtra();
-    const size_t GetLocalExtraLen();
-    const void SetLocalExtra(const char* extra, size_t len);
+    const char* GetLocalExtra() const;
+    size_t GetLocalExtraLen() const;
+    void SetLocalExtra(const char* extra, size_t len);

     //@}
 
     //@{
     /**
     //@}
 
     //@{
     /**

-        The compression method. The enumeration @c wxZipMethod lists the
-        possible values.
-        The default constructor sets this to wxZIP_METHOD_DEFAULT,
-        which allows wxZipOutputStream to
-        choose the method when writing the entry.
+        The compression method.
+        The enumeration ::wxZipMethod lists the possible values.
+
+        The default constructor sets this to @c wxZIP_METHOD_DEFAULT,
+        which allows wxZipOutputStream to choose the method when writing the entry.

     */
     */

-    int GetMethod();
-    const void SetMethod(int method);
+    int GetMethod() const;
+    void SetMethod(int method);

     //@}
 
     //@{
     /**
     //@}
 
     //@{
     /**

-        Sets the DOS attributes
-        in @ref externalattributes() GetExternalAttributes
-        to be consistent with the @c mode given.
-        If IsMadeByUnix() is @true then also
-        stores @c mode in GetExternalAttributes().
-        Note that the default constructor
-        sets @ref systemmadeby() GetSystemMadeBy to
-        wxZIP_SYSTEM_MSDOS by default. So to be able to store unix
+        If IsMadeByUnix() is true then returns the unix permission bits stored
+        in GetExternalAttributes(). Otherwise synthesises them from the DOS attributes.
+    */
+    int GetMode() const;
+
+    /**
+        Sets the DOS attributes in GetExternalAttributes() to be consistent with
+        the @a mode given.
+
+        If IsMadeByUnix() is @true then also stores @a mode in GetExternalAttributes().
+        Note that the default constructor sets GetSystemMadeBy() to
+        @c wxZIP_SYSTEM_MSDOS by default. So to be able to store unix

         permissions when creating zips, call SetSystemMadeBy(wxZIP_SYSTEM_UNIX).
     */
         permissions when creating zips, call SetSystemMadeBy(wxZIP_SYSTEM_UNIX).
     */

-    int GetMode();
-    const void SetMode(int mode);
+    void SetMode(int mode);

     //@}
 
     //@{
     /**
     //@}
 
     //@{
     /**

-        The originating file-system. The default constructor sets this to
-        wxZIP_SYSTEM_MSDOS. Set it to wxZIP_SYSTEM_UNIX in order to be
-        able to store unix permissions using @ref mode() SetMode.
+        The originating file-system.
+
+        The default constructor sets this to @c wxZIP_SYSTEM_MSDOS.
+        Set it to @c wxZIP_SYSTEM_UNIX in order to be able to store unix
+        permissions using SetMode().

     */
     */

-    int GetSystemMadeBy();
-    const void SetSystemMadeBy(int system);
+    int GetSystemMadeBy() const;
+    void SetSystemMadeBy(int system);

     //@}
 
     /**
         The compressed size of this entry in bytes.
     */
     //@}
 
     /**
         The compressed size of this entry in bytes.
     */

-    off_t GetCompressedSize() const;
+    wxFileOffset GetCompressedSize() const;

 
     /**
         CRC32 for this entry's data.
 
     /**
         CRC32 for this entry's data.


@@ -177,17 +296,23 @@ public:
         to is set to indicate whether the name looks like a directory name
         (i.e. has a trailing path separator).
 
         to is set to indicate whether the name looks like a directory name
         (i.e. has a trailing path separator).
 

-        @see @ref overview_wxarcbyname "Looking up an archive entry by name"
+        @see @ref overview_archive_byname

     */
     */

-    wxString GetInternalName();
-    const wxString  GetInternalName(const wxString& name,
-                                    wxPathFormat format = wxPATH_NATIVE,
-                                    bool* pIsDir = NULL);
+    wxString GetInternalName(const wxString& name,
+                            wxPathFormat format = wxPATH_NATIVE,
+                            bool* pIsDir = NULL);
+    /**
+        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.
+    */
+    wxString GetInternalName() const;

     //@}
 
     /**
     //@}
 
     /**

-        Returns @true if @ref systemmadeby() GetSystemMadeBy
-        is a flavour of unix.
+        Returns @true if GetSystemMadeBy() is a flavour of unix.

     */
     bool IsMadeByUnix() const;
 
     */
     bool IsMadeByUnix() const;
 


@@ -195,22 +320,21 @@ public:
     /**
         Indicates that this entry's data is text in an 8-bit encoding.
     */
     /**
         Indicates that this entry's data is text in an 8-bit encoding.
     */

-    bool IsText();
-    const void SetIsText(bool isText = true);
+    bool IsText() const;
+    void SetIsText(bool isText = true);

     //@}
 
     //@{
     /**
     //@}
 
     //@{
     /**

-        Sets the notifier() for this entry.
-        Whenever the wxZipInputStream updates
-        this entry, it will then invoke the associated
-        notifier's wxZipNotifier::OnEntryUpdated
-        method.
+        Sets the notifier (see wxZipNotifier) for this entry.
+        Whenever the wxZipInputStream updates this entry, it will then invoke
+        the associated notifier's wxZipNotifier::OnEntryUpdated() method.
+

         Setting a notifier is not usually necessary. It is used to handle
         certain cases when modifying an zip in a pipeline (i.e. between
         non-seekable streams).
 
         Setting a notifier is not usually necessary. It is used to handle
         certain cases when modifying an zip in a pipeline (i.e. between
         non-seekable streams).
 

-        @see @ref overview_wxarcnoseek "Archives on non-seekable streams", wxZipNotifier
+        @see @ref overview_archive_noseek, wxZipNotifier

     */
     void SetNotifier(wxZipNotifier& notifier);
     void UnsetNotifier();
     */
     void SetNotifier(wxZipNotifier& notifier);
     void UnsetNotifier();


@@ -219,69 +343,77 @@ public:
     /**
         Assignment operator.
     */
     /**
         Assignment operator.
     */

-    wxZipEntry& operator operator=(const wxZipEntry& entry);
+    wxZipEntry& operator=(const wxZipEntry& entry);

 };
 
 
 };
 
 

-

 /**
     @class wxZipInputStream
 
     Input stream for reading zip files.
 
 /**
     @class wxZipInputStream
 
     Input stream for reading zip files.
 

-    wxZipInputStream::GetNextEntry returns an
-     wxZipEntry object containing the meta-data
-    for the next entry in the zip (and gives away ownership). Reading from
-    the wxZipInputStream 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.
+    wxZipInputStream::GetNextEntry() returns a wxZipEntry object containing the
+    meta-data for the next entry in the zip (and gives away ownership).
+    Reading from the wxZipInputStream 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().
 
     Note that in general zip entries are not seekable, and
     When there are no more entries, GetNextEntry() returns @NULL and sets Eof().
 
     Note that in general zip entries are not seekable, and

-    wxZipInputStream::SeekI() always returns wxInvalidOffset.
+    wxZipInputStream::SeekI() always returns ::wxInvalidOffset.

 
     @library{wxbase}
 
     @library{wxbase}

-    @category{streams}
+    @category{archive,streams}

 
 

-    @see @ref overview_wxarc "Archive formats such as zip", wxZipEntry,
-    wxZipOutputStream
+    @see @ref overview_archive, wxZipEntry, wxZipOutputStream

 */
 class wxZipInputStream : public wxArchiveInputStream
 {
 public:
 */
 class wxZipInputStream : public wxArchiveInputStream
 {
 public:

+

     //@{
     /**
     //@{
     /**

-        Compatibility constructor (requires WXWIN_COMPATIBILITY_2_6).
-        When this constructor is used, an emulation of seeking is
-        switched on for compatibility with previous versions. Note however,
-        that it is deprecated.
+        Constructor. In a Unicode build the second parameter @a conv is used to
+        translate the filename and comment fields into Unicode.
+        It has no effect on the stream's data.
+        If the parent stream is passed as a pointer then the new filter stream
+        takes ownership of it. If it is passed by reference then it does not.

     */
     wxZipInputStream(wxInputStream& stream,
                      wxMBConv& conv = wxConvLocal);
     wxZipInputStream(wxInputStream* stream,
                      wxMBConv& conv = wxConvLocal);
     */
     wxZipInputStream(wxInputStream& stream,
                      wxMBConv& conv = wxConvLocal);
     wxZipInputStream(wxInputStream* stream,
                      wxMBConv& conv = wxConvLocal);

+    //@}
+
+    /**
+        @deprecated
+        Compatibility constructor (requires WXWIN_COMPATIBILITY_2_6).
+        When this constructor is used, an emulation of seeking is
+        switched on for compatibility with previous versions. Note however,
+        that it is deprecated.
+    */

     wxZipInputStream(const wxString& archive,
                      const wxString& file);
     wxZipInputStream(const wxString& archive,
                      const wxString& file);

-    //@}

 
     /**
 
     /**

-        Closes the current entry. On a non-seekable stream reads to the end of
-        the current entry first.
+        Closes the current entry.
+        On a non-seekable stream reads to the end of the current entry first.

     */
     bool CloseEntry();
 
     /**
         Returns the zip comment.
     */
     bool CloseEntry();
 
     /**
         Returns the zip comment.

+

         This is stored at the end of the zip, therefore when reading a zip
         This is stored at the end of the zip, therefore when reading a zip

-        from a non-seekable stream, it returns the empty string until the
-        end of the zip has been reached, i.e. when GetNextEntry() returns
-        @NULL.
+        from a non-seekable stream, it returns the empty string until the end
+        of the zip has been reached, i.e. when GetNextEntry() returns @NULL.

     */
     wxString GetComment();
 
     /**
         Closes the current entry if one is open, then reads the meta-data for
     */
     wxString GetComment();
 
     /**
         Closes the current entry if one is open, then reads the meta-data for

-        the next entry and returns it in a wxZipEntry
-        object, giving away ownership. The stream is then open and can be read.
+        the next entry and returns it in a wxZipEntry object, giving away ownership.
+        The stream is then open and can be read.

     */
     wxZipEntry* GetNextEntry();
 
     */
     wxZipEntry* GetNextEntry();
 


@@ -295,8 +427,11 @@ public:
     /**
         Closes the current entry if one is open, then opens the entry specified
         by the @a entry object.
     /**
         Closes the current entry if one is open, then opens the entry specified
         by the @a entry object.

+

         @a entry should be from the same zip file, and the zip should
         be on a seekable stream.
         @a entry should be from the same zip file, and the zip should
         be on a seekable stream.

+
+        @see overview_archive_byname

     */
     bool OpenEntry(wxZipEntry& entry);
 };
     */
     bool OpenEntry(wxZipEntry& entry);
 };


@@ -306,14 +441,15 @@ public:
 /**
     @class wxZipClassFactory
 
 /**
     @class wxZipClassFactory
 

-    Class factory for the zip archive format. See the base class
-    for details.
+    Class factory for the zip archive format.
+    See the base class for details.

 
     @library{wxbase}
 
     @library{wxbase}

-    @category{FIXME}
+    @category{archive,streams}

 
 

-    @see @ref overview_wxarc "Archive formats such as zip", @ref
-    overview_wxarcgeneric "Generic archive programming", wxZipEntry, wxZipInputStream, wxZipOutputStream
+    @see @ref overview_archive,
+         @ref overview_archive_generic,
+         wxZipEntry, wxZipInputStream, wxZipOutputStream

 */
 class wxZipClassFactory : public wxArchiveClassFactory
 {
 */
 class wxZipClassFactory : public wxArchiveClassFactory
 {


@@ -328,30 +464,32 @@ public:
 
     Output stream for writing zip files.
 
 
     Output stream for writing zip files.
 

-    wxZipOutputStream::PutNextEntry is used to create
-    a new entry in the output zip, then the entry's data is written to the
-    wxZipOutputStream.  Another call to PutNextEntry() closes the current
+    wxZipOutputStream::PutNextEntry() is used to create a new entry in the
+    output zip, then the entry's data is written to the wxZipOutputStream.
+    Another call to wxZipOutputStream::PutNextEntry() closes the current

     entry and begins the next.
 
     @library{wxbase}
     entry and begins the next.
 
     @library{wxbase}

-    @category{streams}
+    @category{archive,streams}

 
 

-    @see @ref overview_wxarc "Archive formats such as zip", wxZipEntry,
-    wxZipInputStream
+    @see @ref overview_archive, wxZipEntry, wxZipInputStream

 */
 class wxZipOutputStream : public wxArchiveOutputStream
 {
 public:
     //@{
     /**
 */
 class wxZipOutputStream : public wxArchiveOutputStream
 {
 public:
     //@{
     /**

-        Constructor. @c level is the compression level to use.
+        Constructor.
+
+        @a level is the compression level to use.

         It can be a value between 0 and 9 or -1 to use the default value
         which currently is equivalent to 6.
         It can be a value between 0 and 9 or -1 to use the default value
         which currently is equivalent to 6.

+

         If the parent stream is passed as a pointer then the new filter stream
         takes ownership of it. If it is passed by reference then it does not.
         If the parent stream is passed as a pointer then the new filter stream
         takes ownership of it. If it is passed by reference then it does not.

-        In a Unicode build the third parameter @c conv is used to translate
-        the filename and comment fields to an 8-bit encoding. It has no effect on the
-        stream's data.
+        In a Unicode build the third parameter @a conv is used to translate
+        the filename and comment fields to an 8-bit encoding.
+        It has no effect on the stream's data.

     */
     wxZipOutputStream(wxOutputStream& stream, int level = -1,
                       wxMBConv& conv = wxConvLocal);
     */
     wxZipOutputStream(wxOutputStream& stream, int level = -1,
                       wxMBConv& conv = wxConvLocal);


@@ -360,10 +498,10 @@ public:
     //@}
 
     /**
     //@}
 
     /**

-        The destructor calls Close() to finish
-        writing the zip if it has not been called already.
+        The destructor calls Close() to finish writing the zip if it has
+        not been called already.

     */
     */

-    ~wxZipOutputStream();
+    virtual ~wxZipOutputStream();

 
     /**
         Finishes writing the zip, returning @true if successful.
 
     /**
         Finishes writing the zip, returning @true if successful.


@@ -372,10 +510,9 @@ public:
     bool Close();
 
     /**
     bool Close();
 
     /**

-        Close the current entry. It is called implicitly whenever another new
-        entry is created with CopyEntry()
-        or PutNextEntry(), or
-        when the zip is closed.
+        Close the current entry.
+        It is called implicitly whenever another new entry is created with CopyEntry()
+        or PutNextEntry(), or when the zip is closed.

     */
     bool CloseEntry();
 
     */
     bool CloseEntry();
 


@@ -386,51 +523,59 @@ public:
     bool CopyArchiveMetaData(wxZipInputStream& inputStream);
 
     /**
     bool CopyArchiveMetaData(wxZipInputStream& inputStream);
 
     /**

-        Takes ownership of @c entry and uses it to create a new entry
-        in the zip. @c entry is then opened in @c inputStream and its contents
+        Takes ownership of @a entry and uses it to create a new entry
+        in the zip. @a entry is then opened in @a inputStream and its contents

         copied to this stream.
         copied to this stream.

+

         CopyEntry() is much more efficient than transferring the data using
         Read() and Write() since it will copy them without decompressing and
         recompressing them.
         CopyEntry() is much more efficient than transferring the data using
         Read() and Write() since it will copy them without decompressing and
         recompressing them.

-        For zips on seekable streams, @c entry must be from the same zip file
-        as @c stream. For non-seekable streams, @c entry must also be the
-        last thing read from @c inputStream.
+
+        For zips on seekable streams, @a entry must be from the same zip file
+        as @a inputStream. For non-seekable streams, @a entry must also be the
+        last thing read from @a inputStream.

     */
     bool CopyEntry(wxZipEntry* entry, wxZipInputStream& inputStream);
 
     //@{
     /**
         Set the compression level that will be used the next time an entry is
     */
     bool CopyEntry(wxZipEntry* entry, wxZipInputStream& inputStream);
 
     //@{
     /**
         Set the compression level that will be used the next time an entry is

-        created. It can be a value between 0 and 9 or -1 to use the default value
+        created.
+
+        It can be a value between 0 and 9 or -1 to use the default value

         which currently is equivalent to 6.
     */
         which currently is equivalent to 6.
     */

-    int GetLevel();
-    const void SetLevel(int level);
+    int GetLevel() const;
+    void SetLevel(int level);

     //@}
 
     /**
     //@}
 
     /**

-        )
-        Create a new directory entry
-        (see wxArchiveEntry::IsDir)
-        with the given name and timestamp.
-        PutNextEntry() can
-        also be used to create directory entries, by supplying a name with
-        a trailing path separator.
+        Create a new directory entry (see wxArchiveEntry::IsDir) with the given
+        name and timestamp.
+
+        PutNextEntry() can also be used to create directory entries, by supplying
+        a name with a trailing path separator.

     */
     */

-    bool PutNextDirEntry(const wxString& name);
+    bool PutNextDirEntry(const wxString& name,
+                         const wxDateTime& dt = wxDateTime::Now());

 
     //@{
     /**
 
     //@{
     /**

-        , @b off_t@e size = wxInvalidOffset)
-        Create a new entry with the given name, timestamp and size.
+        Takes ownership of @a entry and uses it to create a new entry in the zip.

     */
     bool PutNextEntry(wxZipEntry* entry);
     */
     bool PutNextEntry(wxZipEntry* entry);

-    bool PutNextEntry(const wxString& name);
+
+    /**
+        Create a new entry with the given name, timestamp and size.
+    */
+    bool PutNextEntry(const wxString& name,
+                      const wxDateTime& dt = wxDateTime::Now(),
+                      wxFileOffset size = wxInvalidOffset);

     //@}
 
     /**
     //@}
 
     /**

-        Sets a comment for the zip as a whole. It is written at the end of the
-        zip.
+        Sets a comment for the zip as a whole.
+        It is written at the end of the zip.

     */
     void SetComment(const wxString& comment);
 };
     */
     void SetComment(const wxString& comment);
 };