interface/wx/zipstrm.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        zipstrm.h
   3 // Purpose:     interface of wxZipNotifier
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10
  11 /// Compression Method, only 0 (store) and 8 (deflate) are supported here
  12 enum wxZipMethod
  13 {
  14     wxZIP_METHOD_STORE,
  15     wxZIP_METHOD_SHRINK,
  16     wxZIP_METHOD_REDUCE1,
  17     wxZIP_METHOD_REDUCE2,
  18     wxZIP_METHOD_REDUCE3,
  19     wxZIP_METHOD_REDUCE4,
  20     wxZIP_METHOD_IMPLODE,
  21     wxZIP_METHOD_TOKENIZE,
  22     wxZIP_METHOD_DEFLATE,
  23     wxZIP_METHOD_DEFLATE64,
  24     wxZIP_METHOD_BZIP2 = 12,
  25     wxZIP_METHOD_DEFAULT = 0xffff
  26 };
  27
  28 /// Originating File-System.
  29 ///
  30 /// These are Pkware's values. Note that Info-zip disagree on some of them,
  31 /// most notably NTFS.
  32 enum wxZipSystem
  33 {
  34     wxZIP_SYSTEM_MSDOS,
  35     wxZIP_SYSTEM_AMIGA,
  36     wxZIP_SYSTEM_OPENVMS,
  37     wxZIP_SYSTEM_UNIX,
  38     wxZIP_SYSTEM_VM_CMS,
  39     wxZIP_SYSTEM_ATARI_ST,
  40     wxZIP_SYSTEM_OS2_HPFS,
  41     wxZIP_SYSTEM_MACINTOSH,
  42     wxZIP_SYSTEM_Z_SYSTEM,
  43     wxZIP_SYSTEM_CPM,
  44     wxZIP_SYSTEM_WINDOWS_NTFS,
  45     wxZIP_SYSTEM_MVS,
  46     wxZIP_SYSTEM_VSE,
  47     wxZIP_SYSTEM_ACORN_RISC,
  48     wxZIP_SYSTEM_VFAT,
  49     wxZIP_SYSTEM_ALTERNATE_MVS,
  50     wxZIP_SYSTEM_BEOS,
  51     wxZIP_SYSTEM_TANDEM,
  52     wxZIP_SYSTEM_OS_400
  53 };
  54
  55 /// Dos/Win file attributes
  56 enum wxZipAttributes
  57 {
  58     wxZIP_A_RDONLY = 0x01,
  59     wxZIP_A_HIDDEN = 0x02,
  60     wxZIP_A_SYSTEM = 0x04,
  61     wxZIP_A_SUBDIR = 0x10,
  62     wxZIP_A_ARCH   = 0x20,
  63
  64     wxZIP_A_MASK   = 0x37
  65 };
  66
  67 /// Values for the flags field in the zip headers
  68 enum wxZipFlags
  69 {
  70     wxZIP_ENCRYPTED         = 0x0001,
  71     wxZIP_DEFLATE_NORMAL    = 0x0000,   // normal compression
  72     wxZIP_DEFLATE_EXTRA     = 0x0002,   // extra compression
  73     wxZIP_DEFLATE_FAST      = 0x0004,   // fast compression
  74     wxZIP_DEFLATE_SUPERFAST = 0x0006,   // superfast compression
  75     wxZIP_DEFLATE_MASK      = 0x0006,
  76     wxZIP_SUMS_FOLLOW       = 0x0008,   // crc and sizes come after the data
  77     wxZIP_ENHANCED          = 0x0010,
  78     wxZIP_PATCH             = 0x0020,
  79     wxZIP_STRONG_ENC        = 0x0040,
  80     wxZIP_UNUSED            = 0x0F80,
  81     wxZIP_RESERVED          = 0xF000
  82 };
  83
  84
  85 /**
  86     @class wxZipNotifier
  87
  88     If you need to know when a wxZipInputStream updates a wxZipEntry,
  89     you can create a notifier by deriving from this abstract base class,
  90     overriding wxZipNotifier::OnEntryUpdated().
  91
  92     An instance of your notifier class can then be assigned to wxZipEntry
  93     objects, using wxZipEntry::SetNotifier().
  94
  95     Setting a notifier is not usually necessary. It is used to handle
  96     certain cases when modifying an zip in a pipeline (i.e. between
  97     non-seekable streams).
  98     See @ref overview_archive_noseek.
  99
 100     @library{wxbase}
 101     @category{archive,streams}
 102
 103     @see @ref overview_archive_noseek, wxZipEntry, wxZipInputStream, wxZipOutputStream
 104 */
 105 class wxZipNotifier
 106 {
 107 public:
 108     /**
 109         Override this to receive notifications when an wxZipEntry object changes.
 110     */
 111     virtual void OnEntryUpdated(wxZipEntry& entry) = 0;
 112 };
 113
 114
 115
 116 /**
 117     @class wxZipEntry
 118
 119     Holds the meta-data for an entry in a zip.
 120
 121     @section zipentry_avail Field availability
 122
 123     When reading a zip from a stream that is seekable, wxZipEntry::GetNextEntry()
 124     returns a fully populated wxZipEntry object except for wxZipEntry::GetLocalExtra().
 125     wxZipEntry::GetLocalExtra() becomes available when the entry is opened, either by
 126     calling wxZipInputStream::OpenEntry() or by making an attempt to read the entry's data.
 127
 128     For zips on non-seekable streams, the following fields are always available
 129     when wxZipEntry::GetNextEntry() returns:
 130     - wxZipEntry::GetDateTime
 131     - wxZipEntry::GetInternalFormat
 132     - wxZipEntry::GetInternalName
 133     - wxZipEntry::GetFlags
 134     - wxZipEntry::GetLocalExtra
 135     - wxZipEntry::GetMethod
 136     - wxZipEntry::GetName
 137     - wxZipEntry::GetOffset
 138     - wxZipEntry::IsDir
 139
 140     The following fields are also usually available when GetNextEntry() returns,
 141     however, if the zip was also written to a non-seekable stream the zipper is
 142     permitted to store them after the entry's data. In that case they become
 143     available when the entry's data has been read to Eof(), or CloseEntry()
 144     has been called. (GetFlags() & wxZIP_SUMS_FOLLOW) != 0 indicates that
 145     one or more of these come after the data:
 146     - wxZipEntry::GetCompressedSize
 147     - wxZipEntry::GetCrc
 148     - wxZipEntry::GetSize
 149
 150     The following are stored at the end of the zip, and become available when the
 151     end of the zip has been reached, i.e. after GetNextEntry() returns @NULL
 152     and Eof() is true:
 153     - wxZipEntry::GetComment
 154     - wxZipEntry::GetExternalAttributes
 155     - wxZipEntry::GetExtra
 156     - wxZipEntry::GetMode
 157     - wxZipEntry::GetSystemMadeBy
 158     - wxZipEntry::IsReadOnly
 159     - wxZipEntry::IsMadeByUnix
 160     - wxZipEntry::IsText
 161
 162     @library{wxbase}
 163     @category{archive,streams}
 164
 165     @see @ref overview_archive, wxZipInputStream, wxZipOutputStream, wxZipNotifier
 166 */
 167 class wxZipEntry : public wxArchiveEntry
 168 {
 169 public:
 170     wxZipEntry(const wxString& name = wxEmptyString,
 171                const wxDateTime& dt = Now(),
 172                wxFileOffset size = wxInvalidOffset);
 173
 174     /**
 175         Copy constructor.
 176     */
 177     wxZipEntry(const wxZipEntry& entry);
 178
 179     /**
 180         Make a copy of this entry.
 181     */
 182     wxZipEntry* Clone() const;
 183
 184     //@{
 185     /**
 186         Gets and sets the short comment for this entry.
 187     */
 188     wxString GetComment() const;
 189     void SetComment(const wxString& comment);
 190     //@}
 191
 192     //@{
 193     /**
 194         The low 8 bits are always the DOS/Windows file attributes for this entry.
 195         The values of these attributes are given in the enumeration ::wxZipAttributes.
 196
 197         The remaining bits can store platform specific permission bits or
 198         attributes, and their meaning depends on the value of SetSystemMadeBy().
 199         If IsMadeByUnix() is @true then the high 16 bits are unix mode bits.
 200
 201         The following other accessors access these bits:
 202         - IsReadOnly() / SetIsReadOnly()
 203         - IsDir() / SetIsDir()
 204         - GetMode() / SetMode()
 205     */
 206     wxUint32 GetExternalAttributes() const;
 207     void SetExternalAttributes(wxUint32 attr);
 208     //@}
 209
 210     //@{
 211     /**
 212         The extra field from the entry's central directory record.
 213
 214         The extra field is used to store platform or application specific
 215         data. See Pkware's document 'appnote.txt' for information on its format.
 216     */
 217     const char* GetExtra() const;
 218     size_t GetExtraLen() const;
 219     void SetExtra(const char* extra, size_t len);
 220     //@}
 221
 222     //@{
 223     /**
 224         The extra field from the entry's local record.
 225
 226         The extra field is used to store platform or application specific
 227         data. See Pkware's document 'appnote.txt' for information on its format.
 228     */
 229     const char* GetLocalExtra() const;
 230     size_t GetLocalExtraLen() const;
 231     void SetLocalExtra(const char* extra, size_t len);
 232     //@}
 233
 234     //@{
 235     /**
 236         The compression method.
 237         The enumeration ::wxZipMethod lists the possible values.
 238
 239         The default constructor sets this to @c wxZIP_METHOD_DEFAULT,
 240         which allows wxZipOutputStream to choose the method when writing the entry.
 241     */
 242     int GetMethod() const;
 243     void SetMethod(int method);
 244     //@}
 245
 246     //@{
 247     /**
 248         If IsMadeByUnix() is true then returns the unix permission bits stored
 249         in GetExternalAttributes(). Otherwise synthesises them from the DOS attributes.
 250     */
 251     int GetMode() const;
 252
 253     /**
 254         Sets the DOS attributes in GetExternalAttributes() to be consistent with
 255         the @a mode given.
 256
 257         If IsMadeByUnix() is @true then also stores @a mode in GetExternalAttributes().
 258         Note that the default constructor sets GetSystemMadeBy() to
 259         @c wxZIP_SYSTEM_MSDOS by default. So to be able to store unix
 260         permissions when creating zips, call SetSystemMadeBy(wxZIP_SYSTEM_UNIX).
 261     */
 262     void SetMode(int mode);
 263     //@}
 264
 265     //@{
 266     /**
 267         The originating file-system.
 268
 269         The default constructor sets this to @c wxZIP_SYSTEM_MSDOS.
 270         Set it to @c wxZIP_SYSTEM_UNIX in order to be able to store unix
 271         permissions using SetMode().
 272     */
 273     int GetSystemMadeBy() const;
 274     void SetSystemMadeBy(int system);
 275     //@}
 276
 277     /**
 278         The compressed size of this entry in bytes.
 279     */
 280     wxFileOffset GetCompressedSize() const;
 281
 282     /**
 283         CRC32 for this entry's data.
 284     */
 285     wxUint32 GetCrc() const;
 286
 287     /**
 288         Returns a combination of the bits flags in the enumeration @c wxZipFlags.
 289     */
 290     int GetFlags() const;
 291
 292     //@{
 293     /**
 294         A static member that translates a filename into the internal format used
 295         within the archive. If the third parameter is provided, the bool pointed
 296         to is set to indicate whether the name looks like a directory name
 297         (i.e. has a trailing path separator).
 298
 299         @see @ref overview_archive_byname
 300     */
 301     wxString GetInternalName(const wxString& name,
 302                             wxPathFormat format = wxPATH_NATIVE,
 303                             bool* pIsDir = NULL);
 304     /**
 305         Returns the entry's filename in the internal format used within the archive.
 306         The name can include directory components, i.e. it can be a full path.
 307
 308         The names of directory entries are returned without any trailing path separator.
 309         This gives a canonical name that can be used in comparisons.
 310     */
 311     wxString GetInternalName() const;
 312     //@}
 313
 314     /**
 315         Returns @true if GetSystemMadeBy() is a flavour of unix.
 316     */
 317     bool IsMadeByUnix() const;
 318
 319     //@{
 320     /**
 321         Indicates that this entry's data is text in an 8-bit encoding.
 322     */
 323     bool IsText() const;
 324     void SetIsText(bool isText = true);
 325     //@}
 326
 327     //@{
 328     /**
 329         Sets the notifier (see wxZipNotifier) for this entry.
 330         Whenever the wxZipInputStream updates this entry, it will then invoke
 331         the associated notifier's wxZipNotifier::OnEntryUpdated() method.
 332
 333         Setting a notifier is not usually necessary. It is used to handle
 334         certain cases when modifying an zip in a pipeline (i.e. between
 335         non-seekable streams).
 336
 337         @see @ref overview_archive_noseek, wxZipNotifier
 338     */
 339     void SetNotifier(wxZipNotifier& notifier);
 340     void UnsetNotifier();
 341     //@}
 342
 343     /**
 344         Assignment operator.
 345     */
 346     wxZipEntry& operator=(const wxZipEntry& entry);
 347 };
 348
 349
 350 /**
 351     @class wxZipInputStream
 352
 353     Input stream for reading zip files.
 354
 355     wxZipInputStream::GetNextEntry() returns a wxZipEntry object containing the
 356     meta-data for the next entry in the zip (and gives away ownership).
 357     Reading from the wxZipInputStream then returns the entry's data.
 358     Eof() becomes @true after an attempt has been made to read past the end of
 359     the entry's data.
 360     When there are no more entries, GetNextEntry() returns @NULL and sets Eof().
 361
 362     Note that in general zip entries are not seekable, and
 363     wxZipInputStream::SeekI() always returns ::wxInvalidOffset.
 364
 365     @library{wxbase}
 366     @category{archive,streams}
 367
 368     @see @ref overview_archive, wxZipEntry, wxZipOutputStream
 369 */
 370 class wxZipInputStream : public wxArchiveInputStream
 371 {
 372 public:
 373
 374     //@{
 375     /**
 376         Constructor. In a Unicode build the second parameter @a conv is used to
 377         translate the filename and comment fields into Unicode.
 378         It has no effect on the stream's data.
 379         If the parent stream is passed as a pointer then the new filter stream
 380         takes ownership of it. If it is passed by reference then it does not.
 381     */
 382     wxZipInputStream(wxInputStream& stream,
 383                      wxMBConv& conv = wxConvLocal);
 384     wxZipInputStream(wxInputStream* stream,
 385                      wxMBConv& conv = wxConvLocal);
 386     //@}
 387
 388     /**
 389         @deprecated
 390         Compatibility constructor (requires WXWIN_COMPATIBILITY_2_6).
 391         When this constructor is used, an emulation of seeking is
 392         switched on for compatibility with previous versions. Note however,
 393         that it is deprecated.
 394     */
 395     wxZipInputStream(const wxString& archive,
 396                      const wxString& file);
 397
 398     /**
 399         Closes the current entry.
 400         On a non-seekable stream reads to the end of the current entry first.
 401     */
 402     bool CloseEntry();
 403
 404     /**
 405         Returns the zip comment.
 406
 407         This is stored at the end of the zip, therefore when reading a zip
 408         from a non-seekable stream, it returns the empty string until the end
 409         of the zip has been reached, i.e. when GetNextEntry() returns @NULL.
 410     */
 411     wxString GetComment();
 412
 413     /**
 414         Closes the current entry if one is open, then reads the meta-data for
 415         the next entry and returns it in a wxZipEntry object, giving away ownership.
 416         The stream is then open and can be read.
 417     */
 418     wxZipEntry* GetNextEntry();
 419
 420     /**
 421         For a zip on a seekable stream returns the total number of entries in
 422         the zip. For zips on non-seekable streams returns the number of entries
 423         returned so far by GetNextEntry().
 424     */
 425     int GetTotalEntries();
 426
 427     /**
 428         Closes the current entry if one is open, then opens the entry specified
 429         by the @a entry object.
 430
 431         @a entry should be from the same zip file, and the zip should
 432         be on a seekable stream.
 433
 434         @see overview_archive_byname
 435     */
 436     bool OpenEntry(wxZipEntry& entry);
 437 };
 438
 439
 440
 441 /**
 442     @class wxZipClassFactory
 443
 444     Class factory for the zip archive format.
 445     See the base class for details.
 446
 447     @library{wxbase}
 448     @category{archive,streams}
 449
 450     @see @ref overview_archive,
 451          @ref overview_archive_generic,
 452          wxZipEntry, wxZipInputStream, wxZipOutputStream
 453 */
 454 class wxZipClassFactory : public wxArchiveClassFactory
 455 {
 456 public:
 457
 458 };
 459
 460
 461
 462 /**
 463     @class wxZipOutputStream
 464
 465     Output stream for writing zip files.
 466
 467     wxZipOutputStream::PutNextEntry() is used to create a new entry in the
 468     output zip, then the entry's data is written to the wxZipOutputStream.
 469     Another call to wxZipOutputStream::PutNextEntry() closes the current
 470     entry and begins the next.
 471
 472     @library{wxbase}
 473     @category{archive,streams}
 474
 475     @see @ref overview_archive, wxZipEntry, wxZipInputStream
 476 */
 477 class wxZipOutputStream : public wxArchiveOutputStream
 478 {
 479 public:
 480     //@{
 481     /**
 482         Constructor.
 483
 484         @a level is the compression level to use.
 485         It can be a value between 0 and 9 or -1 to use the default value
 486         which currently is equivalent to 6.
 487
 488         If the parent stream is passed as a pointer then the new filter stream
 489         takes ownership of it. If it is passed by reference then it does not.
 490         In a Unicode build the third parameter @a conv is used to translate
 491         the filename and comment fields to an 8-bit encoding.
 492         It has no effect on the stream's data.
 493     */
 494     wxZipOutputStream(wxOutputStream& stream, int level = -1,
 495                       wxMBConv& conv = wxConvLocal);
 496     wxZipOutputStream(wxOutputStream* stream, int level = -1,
 497                       wxMBConv& conv = wxConvLocal);
 498     //@}
 499
 500     /**
 501         The destructor calls Close() to finish writing the zip if it has
 502         not been called already.
 503     */
 504     virtual ~wxZipOutputStream();
 505
 506     /**
 507         Finishes writing the zip, returning @true if successful.
 508         Called by the destructor if not called explicitly.
 509     */
 510     bool Close();
 511
 512     /**
 513         Close the current entry.
 514         It is called implicitly whenever another new entry is created with CopyEntry()
 515         or PutNextEntry(), or when the zip is closed.
 516     */
 517     bool CloseEntry();
 518
 519     /**
 520         Transfers the zip comment from the wxZipInputStream
 521         to this output stream.
 522     */
 523     bool CopyArchiveMetaData(wxZipInputStream& inputStream);
 524
 525     /**
 526         Takes ownership of @a entry and uses it to create a new entry
 527         in the zip. @a entry is then opened in @a inputStream and its contents
 528         copied to this stream.
 529
 530         CopyEntry() is much more efficient than transferring the data using
 531         Read() and Write() since it will copy them without decompressing and
 532         recompressing them.
 533
 534         For zips on seekable streams, @a entry must be from the same zip file
 535         as @a inputStream. For non-seekable streams, @a entry must also be the
 536         last thing read from @a inputStream.
 537     */
 538     bool CopyEntry(wxZipEntry* entry, wxZipInputStream& inputStream);
 539
 540     //@{
 541     /**
 542         Set the compression level that will be used the next time an entry is
 543         created.
 544
 545         It can be a value between 0 and 9 or -1 to use the default value
 546         which currently is equivalent to 6.
 547     */
 548     int GetLevel() const;
 549     void SetLevel(int level);
 550     //@}
 551
 552     /**
 553         Create a new directory entry (see wxArchiveEntry::IsDir) with the given
 554         name and timestamp.
 555
 556         PutNextEntry() can also be used to create directory entries, by supplying
 557         a name with a trailing path separator.
 558     */
 559     bool PutNextDirEntry(const wxString& name,
 560                          const wxDateTime& dt = wxDateTime::Now());
 561
 562     //@{
 563     /**
 564         Takes ownership of @a entry and uses it to create a new entry in the zip.
 565     */
 566     bool PutNextEntry(wxZipEntry* entry);
 567
 568     /**
 569         Create a new entry with the given name, timestamp and size.
 570     */
 571     bool PutNextEntry(const wxString& name,
 572                       const wxDateTime& dt = wxDateTime::Now(),
 573                       wxFileOffset size = wxInvalidOffset);
 574     //@}
 575
 576     /**
 577         Sets a comment for the zip as a whole.
 578         It is written at the end of the zip.
 579     */
 580     void SetComment(const wxString& comment);
 581 };
 582