interface/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     @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     @see @ref overview_wxarcnoseek "Archives on non-seekable streams", wxZipEntry,
  29     wxZipInputStream, wxZipOutputStream
  30 */
  31 class wxZipNotifier
  32 {
  33 public:
  34     /**
  35         Override this to receive notifications when
  36         an wxZipEntry object changes.
  37     */
  38     void OnEntryUpdated(wxZipEntry& entry);
  39 };
  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     @see @ref overview_wxarc "Archive formats such as zip", wxZipInputStream,
  53     wxZipOutputStream, wxZipNotifier
  54 */
  55 class wxZipEntry : public wxArchiveEntry
  56 {
  57 public:
  58     //@{
  59     /**
  60         Copy constructor.
  61     */
  62     wxZipEntry(const wxString& name = wxEmptyString);
  63     wxZipEntry(const wxZipEntry& entry);
  64     //@}
  65
  66     /**
  67         Make a copy of this entry.
  68     */
  69     wxZipEntry* Clone() const;
  70
  71     //@{
  72     /**
  73         A short comment for this entry.
  74     */
  75     wxString GetComment();
  76     const void SetComment(const wxString& comment);
  77     //@}
  78
  79     //@{
  80     /**
  81         The low 8 bits are always the DOS/Windows file attributes for this entry.
  82         The values of these attributes are given in the
  83         enumeration @c wxZipAttributes.
  84         The remaining bits can store platform specific permission bits or
  85         attributes, and their meaning depends on the value
  86         of @ref systemmadeby() SetSystemMadeBy.
  87         If IsMadeByUnix() is @true then the
  88         high 16 bits are unix mode bits.
  89         The following other accessors access these bits:
  90         @ref wxArchiveEntry::isreadonly IsReadOnly/SetIsReadOnly
  91
  92         @ref wxArchiveEntry::isdir IsDir/SetIsDir
  93
  94         @ref mode() Get/SetMode
  95     */
  96     wxUint32 GetExternalAttributes();
  97     const void SetExternalAttributes(wxUint32 attr);
  98     //@}
  99
 100     //@{
 101     /**
 102         The extra field from the entry's central directory record.
 103         The extra field is used to store platform or application specific
 104         data. See Pkware's document 'appnote.txt' for information on its format.
 105     */
 106     const char* GetExtra();
 107     const size_t GetExtraLen();
 108     const void SetExtra(const char* extra, size_t len);
 109     //@}
 110
 111     //@{
 112     /**
 113         The extra field from the entry's local record.
 114         The extra field is used to store platform or application specific
 115         data. See Pkware's document 'appnote.txt' for information on its format.
 116     */
 117     const char* GetLocalExtra();
 118     const size_t GetLocalExtraLen();
 119     const void SetLocalExtra(const char* extra, size_t len);
 120     //@}
 121
 122     //@{
 123     /**
 124         The compression method. The enumeration @c wxZipMethod lists the
 125         possible values.
 126         The default constructor sets this to wxZIP_METHOD_DEFAULT,
 127         which allows wxZipOutputStream to
 128         choose the method when writing the entry.
 129     */
 130     int GetMethod();
 131     const void SetMethod(int method);
 132     //@}
 133
 134     //@{
 135     /**
 136         Sets the DOS attributes
 137         in @ref externalattributes() GetExternalAttributes
 138         to be consistent with the @c mode given.
 139         If IsMadeByUnix() is @true then also
 140         stores @c mode in GetExternalAttributes().
 141         Note that the default constructor
 142         sets @ref systemmadeby() GetSystemMadeBy to
 143         wxZIP_SYSTEM_MSDOS by default. So to be able to store unix
 144         permissions when creating zips, call SetSystemMadeBy(wxZIP_SYSTEM_UNIX).
 145     */
 146     int GetMode();
 147     const void SetMode(int mode);
 148     //@}
 149
 150     //@{
 151     /**
 152         The originating file-system. The default constructor sets this to
 153         wxZIP_SYSTEM_MSDOS. Set it to wxZIP_SYSTEM_UNIX in order to be
 154         able to store unix permissions using @ref mode() SetMode.
 155     */
 156     int GetSystemMadeBy();
 157     const void SetSystemMadeBy(int system);
 158     //@}
 159
 160     /**
 161         The compressed size of this entry in bytes.
 162     */
 163     off_t GetCompressedSize() const;
 164
 165     /**
 166         CRC32 for this entry's data.
 167     */
 168     wxUint32 GetCrc() const;
 169
 170     /**
 171         Returns a combination of the bits flags in the enumeration @c wxZipFlags.
 172     */
 173     int GetFlags() const;
 174
 175     //@{
 176     /**
 177         A static member that translates a filename into the internal format used
 178         within the archive. If the third parameter is provided, the bool pointed
 179         to is set to indicate whether the name looks like a directory name
 180         (i.e. has a trailing path separator).
 181
 182         @see @ref overview_wxarcbyname "Looking up an archive entry by name"
 183     */
 184     wxString GetInternalName();
 185     const wxString  GetInternalName(const wxString& name,
 186                                     wxPathFormat format = wxPATH_NATIVE,
 187                                     bool* pIsDir = NULL);
 188     //@}
 189
 190     /**
 191         Returns @true if @ref systemmadeby() GetSystemMadeBy
 192         is a flavour of unix.
 193     */
 194     bool IsMadeByUnix() const;
 195
 196     //@{
 197     /**
 198         Indicates that this entry's data is text in an 8-bit encoding.
 199     */
 200     bool IsText();
 201     const void SetIsText(bool isText = true);
 202     //@}
 203
 204     //@{
 205     /**
 206         Sets the notifier() for this entry.
 207         Whenever the wxZipInputStream updates
 208         this entry, it will then invoke the associated
 209         notifier's wxZipNotifier::OnEntryUpdated
 210         method.
 211         Setting a notifier is not usually necessary. It is used to handle
 212         certain cases when modifying an zip in a pipeline (i.e. between
 213         non-seekable streams).
 214
 215         @see @ref overview_wxarcnoseek "Archives on non-seekable streams", wxZipNotifier
 216     */
 217     void SetNotifier(wxZipNotifier& notifier);
 218     void UnsetNotifier();
 219     //@}
 220
 221     /**
 222         Assignment operator.
 223     */
 224     wxZipEntry& operator operator=(const wxZipEntry& entry);
 225 };
 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     @see @ref overview_wxarc "Archive formats such as zip", wxZipEntry,
 249     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 /**
 310     @class wxZipClassFactory
 311     @wxheader{zipstrm.h}
 312
 313     Class factory for the zip archive format. See the base class
 314     for details.
 315
 316     @library{wxbase}
 317     @category{FIXME}
 318
 319     @see @ref overview_wxarc "Archive formats such as zip", @ref
 320     overview_wxarcgeneric "Generic archive programming", wxZipEntry, wxZipInputStream, wxZipOutputStream
 321 */
 322 class wxZipClassFactory : public wxArchiveClassFactory
 323 {
 324 public:
 325
 326 };
 327
 328
 329
 330 /**
 331     @class wxZipOutputStream
 332     @wxheader{zipstrm.h}
 333
 334     Output stream for writing zip files.
 335
 336     wxZipOutputStream::PutNextEntry is used to create
 337     a new entry in the output zip, then the entry's data is written to the
 338     wxZipOutputStream.  Another call to PutNextEntry() closes the current
 339     entry and begins the next.
 340
 341     @library{wxbase}
 342     @category{streams}
 343
 344     @see @ref overview_wxarc "Archive formats such as zip", wxZipEntry,
 345     wxZipInputStream
 346 */
 347 class wxZipOutputStream : public wxArchiveOutputStream
 348 {
 349 public:
 350     //@{
 351     /**
 352         Constructor. @c level is the compression level to use.
 353         It can be a value between 0 and 9 or -1 to use the default value
 354         which currently is equivalent to 6.
 355         If the parent stream is passed as a pointer then the new filter stream
 356         takes ownership of it. If it is passed by reference then it does not.
 357         In a Unicode build the third parameter @c conv is used to translate
 358         the filename and comment fields to an 8-bit encoding. It has no effect on the
 359         stream's data.
 360     */
 361     wxZipOutputStream(wxOutputStream& stream, int level = -1,
 362                       wxMBConv& conv = wxConvLocal);
 363     wxZipOutputStream(wxOutputStream* stream, int level = -1,
 364                       wxMBConv& conv = wxConvLocal);
 365     //@}
 366
 367     /**
 368         The destructor calls Close() to finish
 369         writing the zip if it has not been called already.
 370     */
 371     ~wxZipOutputStream();
 372
 373     /**
 374         Finishes writing the zip, returning @true if successful.
 375         Called by the destructor if not called explicitly.
 376     */
 377     bool Close();
 378
 379     /**
 380         Close the current entry. It is called implicitly whenever another new
 381         entry is created with CopyEntry()
 382         or PutNextEntry(), or
 383         when the zip is closed.
 384     */
 385     bool CloseEntry();
 386
 387     /**
 388         Transfers the zip comment from the wxZipInputStream
 389         to this output stream.
 390     */
 391     bool CopyArchiveMetaData(wxZipInputStream& inputStream);
 392
 393     /**
 394         Takes ownership of @c entry and uses it to create a new entry
 395         in the zip. @c entry is then opened in @c inputStream and its contents
 396         copied to this stream.
 397         CopyEntry() is much more efficient than transferring the data using
 398         Read() and Write() since it will copy them without decompressing and
 399         recompressing them.
 400         For zips on seekable streams, @c entry must be from the same zip file
 401         as @c stream. For non-seekable streams, @c entry must also be the
 402         last thing read from @c inputStream.
 403     */
 404     bool CopyEntry(wxZipEntry* entry, wxZipInputStream& inputStream);
 405
 406     //@{
 407     /**
 408         Set the compression level that will be used the next time an entry is
 409         created. It can be a value between 0 and 9 or -1 to use the default value
 410         which currently is equivalent to 6.
 411     */
 412     int GetLevel();
 413     const void SetLevel(int level);
 414     //@}
 415
 416     /**
 417         )
 418         Create a new directory entry
 419         (see wxArchiveEntry::IsDir)
 420         with the given name and timestamp.
 421         PutNextEntry() can
 422         also be used to create directory entries, by supplying a name with
 423         a trailing path separator.
 424     */
 425     bool PutNextDirEntry(const wxString& name);
 426
 427     //@{
 428     /**
 429         , @b off_t@e size = wxInvalidOffset)
 430         Create a new entry with the given name, timestamp and size.
 431     */
 432     bool PutNextEntry(wxZipEntry* entry);
 433     bool PutNextEntry(const wxString& name);
 434     //@}
 435
 436     /**
 437         Sets a comment for the zip as a whole. It is written at the end of the
 438         zip.
 439     */
 440     void SetComment(const wxString& comment);
 441 };
 442