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