interface/zipstrm.h

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