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 ---
 350
 351
 352
 353 /**
 354     @class wxZipInputStream
 355
 356     Input stream for reading zip files.
 357
 358     wxZipInputStream::GetNextEntry returns an
 359      wxZipEntry object containing the meta-data
 360     for the next entry in the zip (and gives away ownership). Reading from
 361     the wxZipInputStream then returns the entry's data. Eof() becomes @true
 362     after an attempt has been made to read past the end of the entry's data.
 363     When there are no more entries, GetNextEntry() returns @NULL and sets Eof().
 364
 365     Note that in general zip entries are not seekable, and
 366     wxZipInputStream::SeekI() always returns wxInvalidOffset.
 367
 368     @library{wxbase}
 369     @category{streams}
 370
 371     @see @ref overview_wxarc "Archive formats such as zip", wxZipEntry,
 372     wxZipOutputStream
 373 */
 374 class wxZipInputStream : public wxArchiveInputStream
 375 {
 376 public:
 377     //@{
 378     /**
 379         Compatibility constructor (requires WXWIN_COMPATIBILITY_2_6).
 380         When this constructor is used, an emulation of seeking is
 381         switched on for compatibility with previous versions. Note however,
 382         that it is deprecated.
 383     */
 384     wxZipInputStream(wxInputStream& stream,
 385                      wxMBConv& conv = wxConvLocal);
 386     wxZipInputStream(wxInputStream* stream,
 387                      wxMBConv& conv = wxConvLocal);
 388     wxZipInputStream(const wxString& archive,
 389                      const wxString& file);
 390     //@}
 391
 392     /**
 393         Closes the current entry. On a non-seekable stream reads to the end of
 394         the current entry first.
 395     */
 396     bool CloseEntry();
 397
 398     /**
 399         Returns the zip comment.
 400         This is stored at the end of the zip, therefore when reading a zip
 401         from a non-seekable stream, it returns the empty string until the
 402         end of the zip has been reached, i.e. when GetNextEntry() returns
 403         @NULL.
 404     */
 405     wxString GetComment();
 406
 407     /**
 408         Closes the current entry if one is open, then reads the meta-data for
 409         the next entry and returns it in a wxZipEntry
 410         object, giving away ownership. The stream is then open and can be read.
 411     */
 412     wxZipEntry* GetNextEntry();
 413
 414     /**
 415         For a zip on a seekable stream returns the total number of entries in
 416         the zip. For zips on non-seekable streams returns the number of entries
 417         returned so far by GetNextEntry().
 418     */
 419     int GetTotalEntries();
 420
 421     /**
 422         Closes the current entry if one is open, then opens the entry specified
 423         by the @a entry object.
 424         @a entry should be from the same zip file, and the zip should
 425         be on a seekable stream.
 426     */
 427     bool OpenEntry(wxZipEntry& entry);
 428 };
 429
 430
 431
 432 /**
 433     @class wxZipClassFactory
 434
 435     Class factory for the zip archive format. See the base class
 436     for details.
 437
 438     @library{wxbase}
 439     @category{FIXME}
 440
 441     @see @ref overview_wxarc "Archive formats such as zip", @ref
 442     overview_wxarcgeneric "Generic archive programming", wxZipEntry, wxZipInputStream, wxZipOutputStream
 443 */
 444 class wxZipClassFactory : public wxArchiveClassFactory
 445 {
 446 public:
 447
 448 };
 449
 450
 451
 452 /**
 453     @class wxZipOutputStream
 454
 455     Output stream for writing zip files.
 456
 457     wxZipOutputStream::PutNextEntry is used to create
 458     a new entry in the output zip, then the entry's data is written to the
 459     wxZipOutputStream.  Another call to PutNextEntry() closes the current
 460     entry and begins the next.
 461
 462     @library{wxbase}
 463     @category{streams}
 464
 465     @see @ref overview_wxarc "Archive formats such as zip", wxZipEntry,
 466     wxZipInputStream
 467 */
 468 class wxZipOutputStream : public wxArchiveOutputStream
 469 {
 470 public:
 471     //@{
 472     /**
 473         Constructor. @c level is the compression level to use.
 474         It can be a value between 0 and 9 or -1 to use the default value
 475         which currently is equivalent to 6.
 476         If the parent stream is passed as a pointer then the new filter stream
 477         takes ownership of it. If it is passed by reference then it does not.
 478         In a Unicode build the third parameter @c conv is used to translate
 479         the filename and comment fields to an 8-bit encoding. It has no effect on the
 480         stream's data.
 481     */
 482     wxZipOutputStream(wxOutputStream& stream, int level = -1,
 483                       wxMBConv& conv = wxConvLocal);
 484     wxZipOutputStream(wxOutputStream* stream, int level = -1,
 485                       wxMBConv& conv = wxConvLocal);
 486     //@}
 487
 488     /**
 489         The destructor calls Close() to finish
 490         writing the zip if it has not been called already.
 491     */
 492     ~wxZipOutputStream();
 493
 494     /**
 495         Finishes writing the zip, returning @true if successful.
 496         Called by the destructor if not called explicitly.
 497     */
 498     bool Close();
 499
 500     /**
 501         Close the current entry. It is called implicitly whenever another new
 502         entry is created with CopyEntry()
 503         or PutNextEntry(), or
 504         when the zip is closed.
 505     */
 506     bool CloseEntry();
 507
 508     /**
 509         Transfers the zip comment from the wxZipInputStream
 510         to this output stream.
 511     */
 512     bool CopyArchiveMetaData(wxZipInputStream& inputStream);
 513
 514     /**
 515         Takes ownership of @c entry and uses it to create a new entry
 516         in the zip. @c entry is then opened in @c inputStream and its contents
 517         copied to this stream.
 518         CopyEntry() is much more efficient than transferring the data using
 519         Read() and Write() since it will copy them without decompressing and
 520         recompressing them.
 521         For zips on seekable streams, @c entry must be from the same zip file
 522         as @c stream. For non-seekable streams, @c entry must also be the
 523         last thing read from @c inputStream.
 524     */
 525     bool CopyEntry(wxZipEntry* entry, wxZipInputStream& inputStream);
 526
 527     //@{
 528     /**
 529         Set the compression level that will be used the next time an entry is
 530         created. It can be a value between 0 and 9 or -1 to use the default value
 531         which currently is equivalent to 6.
 532     */
 533     int GetLevel();
 534     const void SetLevel(int level);
 535     //@}
 536
 537     /**
 538         )
 539         Create a new directory entry
 540         (see wxArchiveEntry::IsDir)
 541         with the given name and timestamp.
 542         PutNextEntry() can
 543         also be used to create directory entries, by supplying a name with
 544         a trailing path separator.
 545     */
 546     bool PutNextDirEntry(const wxString& name);
 547
 548     //@{
 549     /**
 550         , @b off_t@e size = wxInvalidOffset)
 551         Create a new entry with the given name, timestamp and size.
 552     */
 553     bool PutNextEntry(wxZipEntry* entry);
 554     bool PutNextEntry(const wxString& name);
 555     //@}
 556
 557     /**
 558         Sets a comment for the zip as a whole. It is written at the end of the
 559         zip.
 560     */
 561     void SetComment(const wxString& comment);
 562 };
 563