]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/zipstrm.h
typo fix
[wxWidgets.git] / interface / wx / zipstrm.h
index 5e6561f2e53c019cf429b62d60f1d05e32ce1b89..f7cdd400a015763e788e62f4ba041b515d0b2536 100644 (file)
@@ -98,7 +98,7 @@ enum wxZipFlags
     See @ref overview_archive_noseek.
 
     @library{wxbase}
-    @category{archive}
+    @category{archive,streams}
 
     @see @ref overview_archive_noseek, wxZipEntry, wxZipInputStream, wxZipOutputStream
 */
@@ -108,7 +108,7 @@ public:
     /**
         Override this to receive notifications when an wxZipEntry object changes.
     */
-    void OnEntryUpdated(wxZipEntry& entry);
+    virtual void OnEntryUpdated(wxZipEntry& entry) = 0;
 };
 
 
@@ -160,14 +160,16 @@ public:
     - wxZipEntry::IsText
 
     @library{wxbase}
-    @category{archive}
+    @category{archive,streams}
 
     @see @ref overview_archive, wxZipInputStream, wxZipOutputStream, wxZipNotifier
 */
 class wxZipEntry : public wxArchiveEntry
 {
 public:
-    wxZipEntry(const wxString& name = wxEmptyString);
+    wxZipEntry(const wxString& name = wxEmptyString,
+               const wxDateTime& dt = Now(),
+               wxFileOffset size = wxInvalidOffset);
 
     /**
         Copy constructor.
@@ -275,7 +277,7 @@ public:
     /**
         The compressed size of this entry in bytes.
     */
-    off_t GetCompressedSize() const;
+    wxFileOffset GetCompressedSize() const;
 
     /**
         CRC32 for this entry's data.
@@ -345,69 +347,73 @@ public:
 };
 
 
-
----
-
-
-
 /**
     @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
-    wxZipInputStream::SeekI() always returns wxInvalidOffset.
+    wxZipInputStream::SeekI() always returns ::wxInvalidOffset.
 
     @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:
+
     //@{
     /**
-        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);
+    //@}
+
+    /**
+        @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);
-    //@}
 
     /**
-        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.
+
         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
-        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();
 
@@ -421,8 +427,11 @@ public:
     /**
         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.
+
+        @see overview_archive_byname
     */
     bool OpenEntry(wxZipEntry& entry);
 };
@@ -432,14 +441,15 @@ public:
 /**
     @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}
-    @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
 {
@@ -454,30 +464,32 @@ public:
 
     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}
-    @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:
     //@{
     /**
-        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.
+
         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);
@@ -486,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.
@@ -498,10 +510,9 @@ public:
     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();
 
@@ -512,51 +523,59 @@ public:
     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.
+
         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
-        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.
     */
-    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(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);
 };