interface/zipstrm.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        zipstrm.h
   3 // Purpose:     documentation for wxZipNotifier class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxZipNotifier
  11     @wxheader{zipstrm.h}
  12
  13     If you need to know when a wxZipInputStream
  14     updates a wxZipEntry,
  15     you can create a notifier by deriving from this abstract base class,
  16     overriding wxZipNotifier::OnEntryUpdated.
  17     An instance of your notifier class can then be assigned to wxZipEntry
  18     objects, using wxZipEntry::SetNotifier.
  19
  20     Setting a notifier is not usually necessary. It is used to handle
  21     certain cases when modifying an zip in a pipeline (i.e. between
  22     non-seekable streams).
  23     See '@ref overview_wxarcnoseek "Archives on non-seekable streams"'.
  24
  25     @library{wxbase}
  26     @category{FIXME}
  27
  28     @seealso
  29     @ref overview_wxarcnoseek "Archives on non-seekable streams", wxZipEntry,
  30     wxZipInputStream, wxZipOutputStream
  31 */
  32 class wxZipNotifier
  33 {
  34 public:
  35     /**
  36         Override this to receive notifications when
  37         an wxZipEntry object changes.
  38     */
  39     void OnEntryUpdated(wxZipEntry& entry);
  40 };
  41
  42
  43 /**
  44     @class wxZipEntry
  45     @wxheader{zipstrm.h}
  46
  47     Holds the meta-data for an entry in a zip.
  48
  49     @library{wxbase}
  50     @category{FIXME}
  51
  52     @seealso
  53     @ref overview_wxarc "Archive formats such as zip", wxZipInputStream,
  54     wxZipOutputStream, wxZipNotifier
  55 */
  56 class wxZipEntry : public wxArchiveEntry
  57 {
  58 public:
  59     //@{
  60     /**
  61         Copy constructor.
  62     */
  63     wxZipEntry(const wxString& name = wxEmptyString);
  64     wxZipEntry(const wxZipEntry& entry);
  65     //@}
  66
  67     /**
  68         Make a copy of this entry.
  69     */
  70     wxZipEntry* Clone() const;
  71
  72     //@{
  73     /**
  74         A short comment for this entry.
  75     */
  76     wxString GetComment();
  77     const void SetComment(const wxString& comment);
  78     //@}
  79
  80     //@{
  81     /**
  82         The low 8 bits are always the DOS/Windows file attributes for this entry.
  83         The values of these attributes are given in the
  84         enumeration @c wxZipAttributes.
  85         The remaining bits can store platform specific permission bits or
  86         attributes, and their meaning depends on the value
  87         of @ref systemmadeby() SetSystemMadeBy.
  88         If IsMadeByUnix() is @true then the
  89         high 16 bits are unix mode bits.
  90         The following other accessors access these bits:
  91         @ref wxArchiveEntry::isreadonly IsReadOnly/SetIsReadOnly
  92
  93         @ref wxArchiveEntry::isdir IsDir/SetIsDir
  94
  95         @ref mode() Get/SetMode
  96     */
  97     wxUint32 GetExternalAttributes();
  98     const void SetExternalAttributes(wxUint32 attr);
  99     //@}
 100
 101     //@{
 102     /**
 103         The extra field from the entry's central directory record.
 104         The extra field is used to store platform or application specific
 105         data. See Pkware's document 'appnote.txt' for information on its format.
 106     */
 107     const char* GetExtra();
 108     const size_t GetExtraLen();
 109     const void SetExtra(const char* extra, size_t len);
 110     //@}
 111
 112     //@{
 113     /**
 114         The extra field from the entry's local record.
 115         The extra field is used to store platform or application specific
 116         data. See Pkware's document 'appnote.txt' for information on its format.
 117     */
 118     const char* GetLocalExtra();
 119     const size_t GetLocalExtraLen();
 120     const void SetLocalExtra(const char* extra, size_t len);
 121     //@}
 122
 123     //@{
 124     /**
 125         The compression method. The enumeration @c wxZipMethod lists the
 126         possible values.
 127         The default constructor sets this to wxZIP_METHOD_DEFAULT,
 128         which allows wxZipOutputStream to
 129         choose the method when writing the entry.
 130     */
 131     int GetMethod();
 132     const void SetMethod(int method);
 133     //@}
 134
 135     //@{
 136     /**
 137         Sets the DOS attributes
 138         in @ref externalattributes() GetExternalAttributes
 139         to be consistent with the @c mode given.
 140         If IsMadeByUnix() is @true then also
 141         stores @c mode in GetExternalAttributes().
 142         Note that the default constructor
 143         sets @ref systemmadeby() GetSystemMadeBy to
 144         wxZIP_SYSTEM_MSDOS by default. So to be able to store unix
 145         permissions when creating zips, call SetSystemMadeBy(wxZIP_SYSTEM_UNIX).
 146     */
 147     int GetMode();
 148     const void SetMode(int mode);
 149     //@}
 150
 151     //@{
 152     /**
 153         The originating file-system. The default constructor sets this to
 154         wxZIP_SYSTEM_MSDOS. Set it to wxZIP_SYSTEM_UNIX in order to be
 155         able to store unix permissions using @ref mode() SetMode.
 156     */
 157     int GetSystemMadeBy();
 158     const void SetSystemMadeBy(int system);
 159     //@}
 160
 161     /**
 162         The compressed size of this entry in bytes.
 163     */
 164     off_t GetCompressedSize() const;
 165
 166     /**
 167         CRC32 for this entry's data.
 168     */
 169     wxUint32 GetCrc() const;
 170
 171     /**
 172         Returns a combination of the bits flags in the enumeration @c wxZipFlags.
 173     */
 174     int GetFlags() const;
 175
 176     //@{
 177     /**
 178         A static member that translates a filename into the internal format used
 179         within the archive. If the third parameter is provided, the bool pointed
 180         to is set to indicate whether the name looks like a directory name
 181         (i.e. has a trailing path separator).
 182
 183         @see @ref overview_wxarcbyname "Looking up an archive entry by name"
 184     */
 185     wxString GetInternalName();
 186     const wxString  GetInternalName(const wxString& name,
 187                                     wxPathFormat format = wxPATH_NATIVE,
 188                                     bool* pIsDir = NULL);
 189     //@}
 190
 191     /**
 192         Returns @true if @ref systemmadeby() GetSystemMadeBy
 193         is a flavour of unix.
 194     */
 195     bool IsMadeByUnix() const;
 196
 197     //@{
 198     /**
 199         Indicates that this entry's data is text in an 8-bit encoding.
 200     */
 201     bool IsText();
 202     const void SetIsText(bool isText = true);
 203     //@}
 204
 205     //@{
 206     /**
 207         Sets the notifier for this entry.
 208         Whenever the wxZipInputStream updates
 209         this entry, it will then invoke the associated
 210         notifier's wxZipNotifier::OnEntryUpdated
 211         method.
 212         Setting a notifier is not usually necessary. It is used to handle
 213         certain cases when modifying an zip in a pipeline (i.e. between
 214         non-seekable streams).
 215
 216         @see @ref overview_wxarcnoseek "Archives on non-seekable streams", wxZipNotifier
 217     */
 218     void SetNotifier(wxZipNotifier& notifier);
 219     void UnsetNotifier();
 220     //@}
 221
 222     /**
 223         Assignment operator.
 224     */
 225     wxZipEntry& operator operator=(const wxZipEntry& entry);
 226 };
 227
 228
 229 /**
 230     @class wxZipInputStream
 231     @wxheader{zipstrm.h}
 232
 233     Input stream for reading zip files.
 234
 235     wxZipInputStream::GetNextEntry returns an
 236      wxZipEntry object containing the meta-data
 237     for the next entry in the zip (and gives away ownership). Reading from
 238     the wxZipInputStream then returns the entry's data. Eof() becomes @true
 239     after an attempt has been made to read past the end of the entry's data.
 240     When there are no more entries, GetNextEntry() returns @NULL and sets Eof().
 241
 242     Note that in general zip entries are not seekable, and
 243     wxZipInputStream::SeekI() always returns wxInvalidOffset.
 244
 245     @library{wxbase}
 246     @category{streams}
 247
 248     @seealso
 249     @ref overview_wxarc "Archive formats such as zip", wxZipEntry, wxZipOutputStream
 250 */
 251 class wxZipInputStream : public wxArchiveInputStream
 252 {
 253 public:
 254     //@{
 255     /**
 256         Compatibility constructor (requires WXWIN_COMPATIBILITY_2_6).
 257         When this constructor is used, an emulation of seeking is
 258         switched on for compatibility with previous versions. Note however,
 259         that it is deprecated.
 260     */
 261     wxZipInputStream(wxInputStream& stream,
 262                      wxMBConv& conv = wxConvLocal);
 263     wxZipInputStream(wxInputStream* stream,
 264                      wxMBConv& conv = wxConvLocal);
 265     wxZipInputStream(const wxString& archive,
 266                      const wxString& file);
 267     //@}
 268
 269     /**
 270         Closes the current entry. On a non-seekable stream reads to the end of
 271         the current entry first.
 272     */
 273     bool CloseEntry();
 274
 275     /**
 276         Returns the zip comment.
 277         This is stored at the end of the zip, therefore when reading a zip
 278         from a non-seekable stream, it returns the empty string until the
 279         end of the zip has been reached, i.e. when GetNextEntry() returns
 280         @NULL.
 281     */
 282     wxString GetComment();
 283
 284     /**
 285         Closes the current entry if one is open, then reads the meta-data for
 286         the next entry and returns it in a wxZipEntry
 287         object, giving away ownership. The stream is then open and can be read.
 288     */
 289     wxZipEntry* GetNextEntry();
 290
 291     /**
 292         For a zip on a seekable stream returns the total number of entries in
 293         the zip. For zips on non-seekable streams returns the number of entries
 294         returned so far by GetNextEntry().
 295     */
 296     int GetTotalEntries();
 297
 298     /**
 299         Closes the current entry if one is open, then opens the entry specified
 300         by the @a entry object.
 301         @a entry should be from the same zip file, and the zip should
 302         be on a seekable stream.
 303     */
 304     bool OpenEntry(wxZipEntry& entry);
 305 };
 306
 307
 308 /**
 309     @class wxZipClassFactory
 310     @wxheader{zipstrm.h}
 311
 312     Class factory for the zip archive format. See the base class
 313     for details.
 314
 315     @library{wxbase}
 316     @category{FIXME}
 317
 318     @seealso
 319     @ref overview_wxarc "Archive formats such as zip", @ref overview_wxarcgeneric
 320     "Generic archive programming", wxZipEntry, wxZipInputStream, wxZipOutputStream
 321 */
 322 class wxZipClassFactory : public wxArchiveClassFactory
 323 {
 324 public:
 325
 326 };
 327
 328
 329 /**
 330     @class wxZipOutputStream
 331     @wxheader{zipstrm.h}
 332
 333     Output stream for writing zip files.
 334
 335     wxZipOutputStream::PutNextEntry is used to create
 336     a new entry in the output zip, then the entry's data is written to the
 337     wxZipOutputStream.  Another call to PutNextEntry() closes the current
 338     entry and begins the next.
 339
 340     @library{wxbase}
 341     @category{streams}
 342
 343     @seealso
 344     @ref overview_wxarc "Archive formats such as zip", wxZipEntry, wxZipInputStream
 345 */
 346 class wxZipOutputStream : public wxArchiveOutputStream
 347 {
 348 public:
 349     //@{
 350     /**
 351         Constructor. @c level is the compression level to use.
 352         It can be a value between 0 and 9 or -1 to use the default value
 353         which currently is equivalent to 6.
 354         If the parent stream is passed as a pointer then the new filter stream
 355         takes ownership of it. If it is passed by reference then it does not.
 356         In a Unicode build the third parameter @c conv is used to translate
 357         the filename and comment fields to an 8-bit encoding. It has no effect on the
 358         stream's data.
 359     */
 360     wxZipOutputStream(wxOutputStream& stream, int level = -1,
 361                       wxMBConv& conv = wxConvLocal);
 362     wxZipOutputStream(wxOutputStream* stream, int level = -1,
 363                       wxMBConv& conv = wxConvLocal);
 364     //@}
 365
 366     /**
 367         The destructor calls Close() to finish
 368         writing the zip if it has not been called already.
 369     */
 370     ~wxZipOutputStream();
 371
 372     /**
 373         Finishes writing the zip, returning @true if successful.
 374         Called by the destructor if not called explicitly.
 375     */
 376     bool Close();
 377
 378     /**
 379         Close the current entry. It is called implicitly whenever another new
 380         entry is created with CopyEntry()
 381         or PutNextEntry(), or
 382         when the zip is closed.
 383     */
 384     bool CloseEntry();
 385
 386     /**
 387         Transfers the zip comment from the wxZipInputStream
 388         to this output stream.
 389     */
 390     bool CopyArchiveMetaData(wxZipInputStream& inputStream);
 391
 392     /**
 393         Takes ownership of @c entry and uses it to create a new entry
 394         in the zip. @c entry is then opened in @c inputStream and its contents
 395         copied to this stream.
 396         CopyEntry() is much more efficient than transferring the data using
 397         Read() and Write() since it will copy them without decompressing and
 398         recompressing them.
 399         For zips on seekable streams, @c entry must be from the same zip file
 400         as @c stream. For non-seekable streams, @c entry must also be the
 401         last thing read from @c inputStream.
 402     */
 403     bool CopyEntry(wxZipEntry* entry, wxZipInputStream& inputStream);
 404
 405     //@{
 406     /**
 407         Set the compression level that will be used the next time an entry is
 408         created. It can be a value between 0 and 9 or -1 to use the default value
 409         which currently is equivalent to 6.
 410     */
 411     int GetLevel();
 412     const void SetLevel(int level);
 413     //@}
 414
 415     /**
 416         )
 417         Create a new directory entry
 418         (see wxArchiveEntry::IsDir)
 419         with the given name and timestamp.
 420         PutNextEntry() can
 421         also be used to create directory entries, by supplying a name with
 422         a trailing path separator.
 423     */
 424     bool PutNextDirEntry(const wxString& name);
 425
 426     //@{
 427     /**
 428         , @b off_t@e size = wxInvalidOffset)
 429         Create a new entry with the given name, timestamp and size.
 430     */
 431     bool PutNextEntry(wxZipEntry* entry);
 432     bool PutNextEntry(const wxString& name);
 433     //@}
 434
 435     /**
 436         Sets a comment for the zip as a whole. It is written at the end of the
 437         zip.
 438     */
 439     void SetComment(const wxString& comment);
 440 };