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}
 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     void OnEntryUpdated(wxZipEntry& entry);
 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}
 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
 172     /**
 173         Copy constructor.
 174     */
 175     wxZipEntry(const wxZipEntry& entry);
 176
 177     /**
 178         Make a copy of this entry.
 179     */
 180     wxZipEntry* Clone() const;
 181
 182     //@{
 183     /**
 184         Gets and sets the short comment for this entry.
 185     */
 186     wxString GetComment() const;
 187     void SetComment(const wxString& comment);
 188     //@}
 189
 190     //@{
 191     /**
 192         The low 8 bits are always the DOS/Windows file attributes for this entry.
 193         The values of these attributes are given in the enumeration ::wxZipAttributes.
 194
 195         The remaining bits can store platform specific permission bits or
 196         attributes, and their meaning depends on the value of SetSystemMadeBy().
 197         If IsMadeByUnix() is @true then the high 16 bits are unix mode bits.
 198
 199         The following other accessors access these bits:
 200         - IsReadOnly() / SetIsReadOnly()
 201         - IsDir() / SetIsDir()
 202         - GetMode() / SetMode()
 203     */
 204     wxUint32 GetExternalAttributes() const;
 205     void SetExternalAttributes(wxUint32 attr);
 206     //@}
 207
 208     //@{
 209     /**
 210         The extra field from the entry's central directory record.
 211
 212         The extra field is used to store platform or application specific
 213         data. See Pkware's document 'appnote.txt' for information on its format.
 214     */
 215     char* GetExtra() const;
 216     size_t GetExtraLen() const;
 217     void SetExtra(const char* extra, size_t len);
 218     //@}
 219
 220     //@{
 221     /**
 222         The extra field from the entry's local record.
 223
 224         The extra field is used to store platform or application specific
 225         data. See Pkware's document 'appnote.txt' for information on its format.
 226     */
 227     char* GetLocalExtra() const;
 228     size_t GetLocalExtraLen() const;
 229     void SetLocalExtra(const char* extra, size_t len);
 230     //@}
 231
 232     //@{
 233     /**
 234         The compression method.
 235         The enumeration ::wxZipMethod lists the possible values.
 236
 237         The default constructor sets this to @c wxZIP_METHOD_DEFAULT,
 238         which allows wxZipOutputStream to choose the method when writing the entry.
 239     */
 240     int GetMethod() const;
 241     void SetMethod(int method);
 242     //@}
 243
 244     //@{
 245     /**
 246         If IsMadeByUnix() is true then returns the unix permission bits stored
 247         in GetExternalAttributes(). Otherwise synthesises them from the DOS attributes.
 248     */
 249     int GetMode() const;
 250
 251     /**
 252         Sets the DOS attributes in GetExternalAttributes() to be consistent with
 253         the @a mode given.
 254
 255         If IsMadeByUnix() is @true then also stores @a mode in GetExternalAttributes().
 256         Note that the default constructor sets GetSystemMadeBy() to
 257         @c wxZIP_SYSTEM_MSDOS by default. So to be able to store unix
 258         permissions when creating zips, call SetSystemMadeBy(wxZIP_SYSTEM_UNIX).
 259     */
 260     void SetMode(int mode);
 261     //@}
 262
 263     //@{
 264     /**
 265         The originating file-system.
 266
 267         The default constructor sets this to @c wxZIP_SYSTEM_MSDOS.
 268         Set it to @c wxZIP_SYSTEM_UNIX in order to be able to store unix
 269         permissions using SetMode().
 270     */
 271     int GetSystemMadeBy() const;
 272     void SetSystemMadeBy(int system);
 273     //@}
 274
 275     /**
 276         The compressed size of this entry in bytes.
 277     */
 278     off_t GetCompressedSize() const;
 279
 280     /**
 281         CRC32 for this entry's data.
 282     */
 283     wxUint32 GetCrc() const;
 284
 285     /**
 286         Returns a combination of the bits flags in the enumeration @c wxZipFlags.
 287     */
 288     int GetFlags() const;
 289
 290     //@{
 291     /**
 292         A static member that translates a filename into the internal format used
 293         within the archive. If the third parameter is provided, the bool pointed
 294         to is set to indicate whether the name looks like a directory name
 295         (i.e. has a trailing path separator).
 296
 297         @see @ref overview_archive_byname
 298     */
 299     wxString GetInternalName(const wxString& name,
 300                             wxPathFormat format = wxPATH_NATIVE,
 301                             bool* pIsDir = NULL);
 302     /**
 303         Returns the entry's filename in the internal format used within the archive.
 304         The name can include directory components, i.e. it can be a full path.
 305
 306         The names of directory entries are returned without any trailing path separator.
 307         This gives a canonical name that can be used in comparisons.
 308     */
 309     wxString GetInternalName() const;
 310     //@}
 311
 312     /**
 313         Returns @true if GetSystemMadeBy() is a flavour of unix.
 314     */
 315     bool IsMadeByUnix() const;
 316
 317     //@{
 318     /**
 319         Indicates that this entry's data is text in an 8-bit encoding.
 320     */
 321     bool IsText() const;
 322     void SetIsText(bool isText = true);
 323     //@}
 324
 325     //@{
 326     /**
 327         Sets the notifier (see wxZipNotifier) for this entry.
 328         Whenever the wxZipInputStream updates this entry, it will then invoke
 329         the associated notifier's wxZipNotifier::OnEntryUpdated() method.
 330
 331         Setting a notifier is not usually necessary. It is used to handle
 332         certain cases when modifying an zip in a pipeline (i.e. between
 333         non-seekable streams).
 334
 335         @see @ref overview_archive_noseek, wxZipNotifier
 336     */
 337     void SetNotifier(wxZipNotifier& notifier);
 338     void UnsetNotifier();
 339     //@}
 340
 341     /**
 342         Assignment operator.
 343     */
 344     wxZipEntry& operator=(const wxZipEntry& entry);
 345 };
 346
 347
 348 /**
 349     @class wxZipInputStream
 350
 351     Input stream for reading zip files.
 352
 353     wxZipInputStream::GetNextEntry() returns a wxZipEntry object containing the
 354     meta-data for the next entry in the zip (and gives away ownership).
 355     Reading from the wxZipInputStream then returns the entry's data.
 356     Eof() becomes @true after an attempt has been made to read past the end of
 357     the entry's data.
 358     When there are no more entries, GetNextEntry() returns @NULL and sets Eof().
 359
 360     Note that in general zip entries are not seekable, and
 361     wxZipInputStream::SeekI() always returns ::wxInvalidOffset.
 362
 363     @library{wxbase}
 364     @category{streams}
 365
 366     @see @ref overview_archive, wxZipEntry, wxZipOutputStream
 367 */
 368 class wxZipInputStream : public wxArchiveInputStream
 369 {
 370 public:
 371
 372     //@{
 373     /**
 374         Constructor. In a Unicode build the second parameter @a conv is used to
 375         translate the filename and comment fields into Unicode.
 376         It has no effect on the stream's data.
 377         If the parent stream is passed as a pointer then the new filter stream
 378         takes ownership of it. If it is passed by reference then it does not.
 379     */
 380     wxZipInputStream(wxInputStream& stream,
 381                      wxMBConv& conv = wxConvLocal);
 382     wxZipInputStream(wxInputStream* stream,
 383                      wxMBConv& conv = wxConvLocal);
 384     //@}
 385
 386     /**
 387         @deprecated
 388         Compatibility constructor (requires WXWIN_COMPATIBILITY_2_6).
 389         When this constructor is used, an emulation of seeking is
 390         switched on for compatibility with previous versions. Note however,
 391         that it is deprecated.
 392     */
 393     wxZipInputStream(const wxString& archive,
 394                      const wxString& file);
 395
 396     /**
 397         Closes the current entry.
 398         On a non-seekable stream reads to the end of the current entry first.
 399     */
 400     bool CloseEntry();
 401
 402     /**
 403         Returns the zip comment.
 404
 405         This is stored at the end of the zip, therefore when reading a zip
 406         from a non-seekable stream, it returns the empty string until the end
 407         of the zip has been reached, i.e. when GetNextEntry() returns @NULL.
 408     */
 409     wxString GetComment();
 410
 411     /**
 412         Closes the current entry if one is open, then reads the meta-data for
 413         the next entry and returns it in a wxZipEntry object, giving away ownership.
 414         The stream is then open and can be read.
 415     */
 416     wxZipEntry* GetNextEntry();
 417
 418     /**
 419         For a zip on a seekable stream returns the total number of entries in
 420         the zip. For zips on non-seekable streams returns the number of entries
 421         returned so far by GetNextEntry().
 422     */
 423     int GetTotalEntries();
 424
 425     /**
 426         Closes the current entry if one is open, then opens the entry specified
 427         by the @a entry object.
 428
 429         @a entry should be from the same zip file, and the zip should
 430         be on a seekable stream.
 431
 432         @see overview_archive_byname
 433     */
 434     bool OpenEntry(wxZipEntry& entry);
 435 };
 436
 437
 438
 439 /**
 440     @class wxZipClassFactory
 441
 442     Class factory for the zip archive format.
 443     See the base class for details.
 444
 445     @library{wxbase}
 446     @category{archive}
 447
 448     @see @ref overview_archive,
 449          @ref overview_archive_generic,
 450          wxZipEntry, wxZipInputStream, wxZipOutputStream
 451 */
 452 class wxZipClassFactory : public wxArchiveClassFactory
 453 {
 454 public:
 455
 456 };
 457
 458
 459
 460 /**
 461     @class wxZipOutputStream
 462
 463     Output stream for writing zip files.
 464
 465     wxZipOutputStream::PutNextEntry() is used to create a new entry in the
 466     output zip, then the entry's data is written to the wxZipOutputStream.
 467     Another call to wxZipOutputStream::PutNextEntry() closes the current
 468     entry and begins the next.
 469
 470     @library{wxbase}
 471     @category{streams}
 472
 473     @see @ref overview_archive, wxZipEntry, wxZipInputStream
 474 */
 475 class wxZipOutputStream : public wxArchiveOutputStream
 476 {
 477 public:
 478     //@{
 479     /**
 480         Constructor.
 481
 482         @a level is the compression level to use.
 483         It can be a value between 0 and 9 or -1 to use the default value
 484         which currently is equivalent to 6.
 485
 486         If the parent stream is passed as a pointer then the new filter stream
 487         takes ownership of it. If it is passed by reference then it does not.
 488         In a Unicode build the third parameter @a conv is used to translate
 489         the filename and comment fields to an 8-bit encoding.
 490         It has no effect on the stream's data.
 491     */
 492     wxZipOutputStream(wxOutputStream& stream, int level = -1,
 493                       wxMBConv& conv = wxConvLocal);
 494     wxZipOutputStream(wxOutputStream* stream, int level = -1,
 495                       wxMBConv& conv = wxConvLocal);
 496     //@}
 497
 498     /**
 499         The destructor calls Close() to finish writing the zip if it has
 500         not been called already.
 501     */
 502     ~wxZipOutputStream();
 503
 504     /**
 505         Finishes writing the zip, returning @true if successful.
 506         Called by the destructor if not called explicitly.
 507     */
 508     bool Close();
 509
 510     /**
 511         Close the current entry.
 512         It is called implicitly whenever another new entry is created with CopyEntry()
 513         or PutNextEntry(), or when the zip is closed.
 514     */
 515     bool CloseEntry();
 516
 517     /**
 518         Transfers the zip comment from the wxZipInputStream
 519         to this output stream.
 520     */
 521     bool CopyArchiveMetaData(wxZipInputStream& inputStream);
 522
 523     /**
 524         Takes ownership of @a entry and uses it to create a new entry
 525         in the zip. @a entry is then opened in @a inputStream and its contents
 526         copied to this stream.
 527
 528         CopyEntry() is much more efficient than transferring the data using
 529         Read() and Write() since it will copy them without decompressing and
 530         recompressing them.
 531
 532         For zips on seekable streams, @a entry must be from the same zip file
 533         as @a inputStream. For non-seekable streams, @a entry must also be the
 534         last thing read from @a inputStream.
 535     */
 536     bool CopyEntry(wxZipEntry* entry, wxZipInputStream& inputStream);
 537
 538     //@{
 539     /**
 540         Set the compression level that will be used the next time an entry is
 541         created.
 542
 543         It can be a value between 0 and 9 or -1 to use the default value
 544         which currently is equivalent to 6.
 545     */
 546     int GetLevel() const;
 547     void SetLevel(int level);
 548     //@}
 549
 550     /**
 551         Create a new directory entry (see wxArchiveEntry::IsDir) with the given
 552         name and timestamp.
 553
 554         PutNextEntry() can also be used to create directory entries, by supplying
 555         a name with a trailing path separator.
 556     */
 557     bool PutNextDirEntry(const wxString& name,
 558                          const wxDateTime& dt = wxDateTime::Now());
 559
 560     //@{
 561     /**
 562         Takes ownership of @a entry and uses it to create a new entry in the zip.
 563     */
 564     bool PutNextEntry(wxZipEntry* entry);
 565
 566     /**
 567         Create a new entry with the given name, timestamp and size.
 568     */
 569     bool PutNextEntry(const wxString& name,
 570                       const wxDateTime& dt = wxDateTime::Now(),
 571                       off_t size = wxInvalidOffset);
 572     //@}
 573
 574     /**
 575         Sets a comment for the zip as a whole.
 576         It is written at the end of the zip.
 577     */
 578     void SetComment(const wxString& comment);
 579 };
 580