interface/archive.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        archive.h
   3 // Purpose:     interface of wxArchive* classes
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxArchiveInputStream
  11     @wxheader{archive.h}
  12
  13     This is an abstract base class which serves as a common interface to
  14     archive input streams such as wxZipInputStream.
  15
  16     wxArchiveInputStream::GetNextEntry returns an wxArchiveEntry object containing
  17     the meta-data for the next entry in the archive (and gives away ownership).
  18
  19     Reading from the wxArchiveInputStream then returns the entry's data. Eof()
  20     becomes @true after an attempt has been made to read past the end of the
  21     entry's data.
  22
  23     When there are no more entries, GetNextEntry() returns @NULL and sets Eof().
  24
  25     @library{wxbase}
  26     @category{archive}
  27
  28     @see @ref overview_archive, wxArchiveEntry, wxArchiveOutputStream
  29 */
  30 class wxArchiveInputStream : public wxFilterInputStream
  31 {
  32 public:
  33     /**
  34         Closes the current entry. On a non-seekable stream reads to the end of
  35         the current entry first.
  36     */
  37     virtual bool CloseEntry() = 0;
  38
  39     /**
  40         Closes the current entry if one is open, then reads the meta-data for
  41         the next entry and returns it in a wxArchiveEntry object, giving away
  42         ownership. Reading this wxArchiveInputStream then returns the entry's data.
  43     */
  44     wxArchiveEntry* GetNextEntry();
  45
  46     /**
  47         Closes the current entry if one is open, then opens the entry specified
  48         by the wxArchiveEntry object.
  49
  50         @a entry must be from the same archive file that this wxArchiveInputStream
  51         is reading, and it must be reading it from a seekable stream.
  52     */
  53     virtual bool OpenEntry(wxArchiveEntry& entry) = 0;
  54 };
  55
  56
  57
  58 /**
  59     @class wxArchiveOutputStream
  60     @wxheader{archive.h}
  61
  62     This is an abstract base class which serves as a common interface to
  63     archive output streams such as wxZipOutputStream.
  64
  65     wxArchiveOutputStream::PutNextEntry is used to create a new entry in the
  66     output archive, then the entry's data is written to the wxArchiveOutputStream.
  67     Another call to PutNextEntry() closes the current entry and begins the next.
  68
  69     @library{wxbase}
  70     @category{archive}
  71
  72     @see @ref overview_archive, wxArchiveEntry, wxArchiveInputStream
  73 */
  74 class wxArchiveOutputStream : public wxFilterOutputStream
  75 {
  76 public:
  77     /**
  78         Calls Close() if it has not already been called.
  79     */
  80     virtual ~wxArchiveOutputStream();
  81
  82     /**
  83         Closes the archive, returning @true if it was successfully written.
  84         Called by the destructor if not called explicitly.
  85
  86         @see wxOutputStream::Close()
  87     */
  88     virtual bool Close();
  89
  90     /**
  91         Close the current entry.
  92         It is called implicitly whenever another new entry is created with CopyEntry()
  93         or PutNextEntry(), or when the archive is closed.
  94     */
  95     virtual bool CloseEntry() = 0;
  96
  97     /**
  98         Some archive formats have additional meta-data that applies to the archive
  99         as a whole.
 100         For example in the case of zip there is a comment, which is stored at the end
 101         of the zip file.  CopyArchiveMetaData() can be used to transfer such information
 102         when writing a modified copy of an archive.
 103
 104         Since the position of the meta-data can vary between the various archive
 105         formats, it is best to call CopyArchiveMetaData() before transferring
 106         the entries.  The wxArchiveOutputStream will then hold on to the meta-data
 107         and write it at the correct point in the output file.
 108
 109         When the input archive is being read from a non-seekable stream, the
 110         meta-data may not be available when CopyArchiveMetaData() is called,
 111         in which case the two streams set up a link and transfer the data
 112         when it becomes available.
 113     */
 114     virtual bool CopyArchiveMetaData(wxArchiveInputStream& stream) = 0;
 115
 116     /**
 117         Takes ownership of @a entry and uses it to create a new entry in the
 118         archive. @a entry is then opened in the input stream @a stream
 119         and its contents copied to this stream.
 120
 121         For archive types which compress entry data, CopyEntry() is likely to be
 122         much more efficient than transferring the data using Read() and Write()
 123         since it will copy them without decompressing and recompressing them.
 124
 125         @a entry must be from the same archive file that @a stream is
 126         accessing. For non-seekable streams, @a entry must also be the last
 127         thing read from @a stream.
 128     */
 129     virtual bool CopyEntry(wxArchiveEntry* entry,
 130                            wxArchiveInputStream& stream) = 0;
 131
 132     /**
 133         Create a new directory entry (see wxArchiveEntry::IsDir) with the given
 134         name and timestamp.
 135
 136         PutNextEntry() can also be used to create directory entries, by supplying
 137         a name with a trailing path separator.
 138     */
 139     virtual bool PutNextDirEntry(const wxString& name,
 140                                  const wxDateTime& dt = wxDateTime::Now()) = 0;
 141
 142     /**
 143         Takes ownership of entry and uses it to create a new entry in the archive.
 144         The entry's data can then be written by writing to this wxArchiveOutputStream.
 145     */
 146     virtual bool PutNextEntry(wxArchiveEntry* entry) = 0;
 147
 148     /**
 149         Create a new entry with the given name, timestamp and size. The entry's
 150         data can then be written by writing to this wxArchiveOutputStream.
 151     */
 152     virtual bool PutNextEntry(const wxString& name,
 153                               const wxDateTime& dt = wxDateTime::Now(),
 154                               wxFileOffset size = wxInvalidOffset) = 0;
 155 };
 156
 157
 158
 159 /**
 160     @class wxArchiveEntry
 161     @wxheader{archive.h}
 162
 163     This is an abstract base class which serves as a common interface to
 164     archive entry classes such as wxZipEntry.
 165     These hold the meta-data (filename, timestamp, etc.), for entries
 166     in archive files such as zips and tars.
 167
 168     <b>About non-seekable streams</b>: this information applies only when reading
 169     archives from non-seekable streams. When the stream is seekable GetNextEntry()
 170     returns a fully populated wxArchiveEntry.
 171     See @ref overview_archive_noseek for more information.
 172
 173     For generic programming, when the worst case must be assumed, you can rely on
 174     all the fields of wxArchiveEntry being fully populated when
 175     wxArchiveInputStream::GetNextEntry() returns, with the the following exceptions:
 176
 177     @li GetSize(): guaranteed to be available after the entry has been read to Eof(),
 178         or CloseEntry() has been called;
 179     @li IsReadOnly(): guaranteed to be available after the end of the archive has
 180         been reached, i.e. after GetNextEntry() returns NULL and Eof() is true.
 181
 182     @library{wxbase}
 183     @category{archive}
 184
 185     @see @ref overview_archive, @ref overview_archive_generic,
 186          wxArchiveInputStream, wxArchiveOutputStream, wxArchiveNotifier
 187 */
 188 class wxArchiveEntry : public wxObject
 189 {
 190 public:
 191     /**
 192         Returns a copy of this entry object.
 193     */
 194     wxArchiveEntry* Clone() const;
 195
 196     /**
 197         Gets the entry's timestamp.
 198     */
 199     virtual wxDateTime GetDateTime() const = 0;
 200
 201     /**
 202         Sets the entry's timestamp.
 203     */
 204     virtual void SetDateTime(const wxDateTime& dt) = 0;
 205
 206     /**
 207         Returns the entry's name, by default in the native format.
 208         The name can include directory components, i.e. it can be a full path.
 209
 210         If this is a directory entry, (i.e. if IsDir() is @true) then the
 211         returned string is the name with a trailing path separator.
 212     */
 213     virtual wxString GetName(wxPathFormat format = wxPATH_NATIVE) const = 0;
 214
 215     /**
 216         Sets the entry's name.
 217         Setting a name with a trailing path separator sets IsDir().
 218
 219         @see GetName()
 220     */
 221     virtual void SetName(const wxString& name,
 222                          wxPathFormat format = wxPATH_NATIVE) = 0;
 223
 224     /**
 225         Returns the size of the entry's data in bytes.
 226     */
 227     virtual wxFileOffset GetSize() const = 0;
 228
 229     /**
 230         Sets the size of the entry's data in bytes.
 231     */
 232     virtual void SetSize(wxFileOffset size) = 0;
 233
 234     /**
 235         Returns the path format used internally within the archive to store
 236         filenames.
 237     */
 238     virtual wxPathFormat GetInternalFormat() const = 0;
 239
 240     /**
 241         Returns the entry's filename in the internal format used within the
 242         archive. The name can include directory components, i.e. it can be a
 243         full path.
 244
 245         The names of directory entries are returned without any trailing path
 246         separator. This gives a canonical name that can be used in comparisons.
 247
 248         @see @ref overview_archive_byname
 249     */
 250     virtual wxString GetInternalName() const = 0;
 251
 252     /**
 253         Returns a numeric value unique to the entry within the archive.
 254     */
 255     virtual wxFileOffset GetOffset() const = 0;
 256
 257     /**
 258         Returns @true if this is a directory entry.
 259
 260         Directory entries are entries with no data, which are used to store
 261         the meta-data of directories. They also make it possible for completely
 262         empty directories to be stored.
 263
 264         @note
 265         The names of entries within an archive can be complete paths, and
 266         unarchivers typically create whatever directories are necessary as they
 267         restore files, even if the archive contains no explicit directory entries.
 268     */
 269     virtual bool IsDir() const = 0;
 270
 271     /**
 272         Marks this entry as a directory if @a isDir is @true. See IsDir() for more info.
 273     */
 274     virtual void SetIsDir(bool isDir = true) = 0;
 275
 276     /**
 277         Returns @true if the entry is a read-only file.
 278     */
 279     virtual bool IsReadOnly() const = 0;
 280
 281     /**
 282         Sets this entry as a read-only file.
 283     */
 284     virtual void SetIsReadOnly(bool isReadOnly = true) = 0;
 285
 286     /**
 287         Sets the notifier (see wxArchiveNotifier) for this entry.
 288
 289         Whenever the wxArchiveInputStream updates this entry, it will then invoke
 290         the associated notifier's wxArchiveNotifier::OnEntryUpdated method.
 291
 292         Setting a notifier is not usually necessary. It is used to handle
 293         certain cases when modifying an archive in a pipeline (i.e. between
 294         non-seekable streams).
 295     */
 296     void SetNotifier(wxArchiveNotifier& notifier);
 297
 298     /**
 299         Unsets the notifier eventually attached to this entry.
 300     */
 301     virtual void UnsetNotifier();
 302 };
 303
 304
 305 /**
 306     Type of stream enumeration; used by wxArchiveClassFactory methods.
 307 */
 308 enum wxStreamProtocolType
 309 {
 310     wxSTREAM_PROTOCOL,  //!< wxFileSystem protocol (should be only one)
 311     wxSTREAM_MIMETYPE,  //!< MIME types the stream handles
 312     wxSTREAM_ENCODING,  //!< Not used for archives
 313     wxSTREAM_FILEEXT    //!< File extensions the stream handles
 314 };
 315
 316 /**
 317     @class wxArchiveClassFactory
 318     @wxheader{archive.h}
 319
 320     Allows the creation of streams to handle archive formats such as zip and tar.
 321
 322     For example, given a filename you can search for a factory that will
 323     handle it and create a stream to read it:
 324
 325     @code
 326         factory = wxArchiveClassFactory::Find(filename, wxSTREAM_FILEEXT);
 327         if (factory)
 328             stream = factory->NewStream(new wxFFileInputStream(filename));
 329     @endcode
 330
 331     wxArchiveClassFactory::Find can also search for a factory by MIME type
 332     or wxFileSystem protocol.
 333
 334     The available factories can be enumerated using
 335     wxArchiveClassFactory::GetFirst() and wxArchiveClassFactory::GetNext().
 336
 337     @library{wxbase}
 338     @category{archive}
 339
 340     @see @ref overview_archive, @ref overview_archive_generic, wxArchiveEntry,
 341          wxArchiveInputStream, wxArchiveOutputStream, wxFilterClassFactory
 342 */
 343 class wxArchiveClassFactory : public wxObject
 344 {
 345 public:
 346     /**
 347         Returns @true if this factory can handle the given protocol, MIME type
 348         or file extension.
 349
 350         When using wxSTREAM_FILEEXT for the second parameter, the first parameter
 351         can be a complete filename rather than just an extension.
 352     */
 353     bool CanHandle(const wxChar* protocol,
 354                    wxStreamProtocolType type = wxSTREAM_PROTOCOL) const;
 355
 356     /**
 357         A static member that finds a factory that can handle a given protocol, MIME
 358         type or file extension.  Returns a pointer to the class factory if found, or
 359         @NULL otherwise. It does not give away ownership of the factory.
 360
 361         When using wxSTREAM_FILEEXT for the second parameter, the first parameter
 362         can be a complete filename rather than just an extension.
 363     */
 364     static const wxArchiveClassFactory* Find(const wxChar* protocol,
 365             wxStreamProtocolType type = wxSTREAM_PROTOCOL);
 366
 367     /**
 368         Returns the wxMBConv object that the created streams will use when
 369         translating meta-data. The initial default, set by the constructor,
 370         is wxConvLocal.
 371     */
 372     wxMBConv GetConv() const;
 373
 374     /**
 375         Sets the wxMBConv object that the created streams will use when
 376         translating meta-data.
 377     */
 378     void SetConv(wxMBConv& conv);
 379
 380     //@{
 381     /**
 382         GetFirst and GetNext can be used to enumerate the available factories.
 383         For example, to list them:
 384
 385         @code
 386         wxString list;
 387         const wxArchiveClassFactory *factory = wxArchiveClassFactory::GetFirst();
 388
 389         while (factory) {
 390             list << factory->GetProtocol() << _T("\n");
 391             factory = factory->GetNext();
 392         }
 393         @endcode
 394
 395         GetFirst() and GetNext() return a pointer to a factory or @NULL if no more
 396         are available. They do not give away ownership of the factory.
 397     */
 398     static const wxArchiveClassFactory* GetFirst() const;
 399     const wxArchiveClassFactory* GetNext() const;
 400     //@}
 401
 402     /**
 403         Calls the static GetInternalName() function for the archive entry type,
 404         for example wxZipEntry::GetInternalName.
 405     */
 406     wxString GetInternalName(const wxString& name,
 407                              wxPathFormat format = wxPATH_NATIVE) const;
 408
 409     /**
 410         Returns the wxFileSystem protocol supported by this factory.
 411         Equivalent to @code wxString(*GetProtocols()) @endcode.
 412     */
 413     wxString GetProtocol() const;
 414
 415     /**
 416         Returns the protocols, MIME types or file extensions supported by this
 417         factory, as an array of null terminated strings.
 418
 419         It does not give away ownership of the array or strings.
 420         For example, to list the file extensions a factory supports:
 421
 422         @code
 423         wxString list;
 424         const wxChar *const *p;
 425
 426         for (p = factory->GetProtocols(wxSTREAM_FILEEXT); *p; p++)
 427             list << *p << _T("\n");
 428         @encode
 429     */
 430     const wxChar* const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL) const;
 431
 432     /**
 433         Create a new wxArchiveEntry object of the appropriate type.
 434     */
 435     wxArchiveEntry* NewEntry() const;
 436
 437     //@{
 438     /**
 439         Create a new input or output stream to read or write an archive.
 440
 441         If the parent stream is passed as a pointer then the new archive stream
 442         takes ownership of it. If it is passed by reference then it does not.
 443     */
 444     wxArchiveInputStream* NewStream(wxInputStream& stream) const;
 445     wxArchiveOutputStream* NewStream(wxOutputStream& stream) const;
 446     wxArchiveInputStream* NewStream(wxInputStream* stream) const;
 447     wxArchiveOutputStream* NewStream(wxOutputStream* stream) const;
 448     //@}
 449
 450     /**
 451         Adds this class factory to the list returned by GetFirst() or GetNext().
 452
 453         It is not necessary to do this to use the archive streams. It is usually
 454         used when implementing streams, typically the implementation will
 455         add a static instance of its factory class.
 456
 457         It can also be used to change the order of a factory already in the list,
 458         bringing it to the front. This isn't a thread safe operation
 459         so can't be done when other threads are running that will be using the list.
 460         The list does not take ownership of the factory.
 461     */
 462     void PushFront();
 463
 464     /**
 465         Removes this class factory from the list returned by GetFirst() and GetNext().
 466
 467         Removing from the list isn't a thread safe operation so can't be done when
 468         other threads are running that will be using the list.
 469         The list does not own the factories, so removing a factory does not delete it.
 470     */
 471     void Remove();
 472 };
 473
 474
 475
 476 /**
 477     @class wxArchiveNotifier
 478     @wxheader{archive.h}
 479
 480     If you need to know when a wxArchiveInputStream updates a wxArchiveEntry
 481     object, you can create a notifier by deriving from this abstract base class,
 482     overriding wxArchiveNotifier::OnEntryUpdated.
 483
 484     An instance of your notifier class can then be assigned to the wxArchiveEntry
 485     object using wxArchiveEntry::SetNotifier.
 486     Your OnEntryUpdated() method will then be invoked whenever the input
 487     stream updates the entry.
 488
 489     Setting a notifier is not usually necessary. It is used to handle
 490     certain cases when modifying an archive in a pipeline (i.e. between
 491     non-seekable streams).
 492     See @ref overview_archive_noseek.
 493
 494     @library{wxbase}
 495     @category{archive}
 496
 497     @see @ref overview_archive_noseek, wxArchiveEntry, wxArchiveInputStream,
 498          wxArchiveOutputStream
 499 */
 500 class wxArchiveNotifier
 501 {
 502 public:
 503     /**
 504         This method must be overridden in your derived class.
 505     */
 506     void OnEntryUpdated(class wxArchiveEntry& entry);
 507 };
 508
 509
 510
 511 /**
 512     @class wxArchiveIterator
 513     @wxheader{archive.h}
 514
 515     An input iterator template class that can be used to transfer an archive's
 516     catalogue to a container. It is only available if wxUSE_STL is set to 1
 517     in setup.h, and the uses for it outlined below require a compiler which
 518     supports member templates.
 519
 520     @code
 521     template class Arc, class T = typename Arc::entry_type*
 522     class wxArchiveIterator
 523     {
 524         // this constructor creates an 'end of sequence' object
 525         wxArchiveIterator();
 526
 527         // template parameter 'Arc' should be the type of an archive input stream
 528         wxArchiveIterator(Arc& arc) {
 529             // ...
 530         }
 531     };
 532     @endcode
 533
 534     The first template parameter should be the type of archive input stream
 535     (e.g. wxArchiveInputStream) and the second can either be a pointer to an entry
 536     (e.g. wxArchiveEntry*), or a string/pointer pair (e.g. std::pairwxString,
 537     wxArchiveEntry*).
 538
 539     The @c wx/archive.h header defines the following typedefs:
 540
 541     @code
 542     typedef wxArchiveIterator<wxArchiveInputStream> wxArchiveIter;
 543
 544     typedef wxArchiveIterator<wxArchiveInputStream,
 545             std::pair<wxString, wxArchiveEntry*> > wxArchivePairIter;
 546     @endcode
 547
 548     The header for any implementation of this interface should define similar
 549     typedefs for its types, for example in @c wx/zipstrm.h there is:
 550
 551     @code
 552     typedef wxArchiveIterator<wxZipInputStream> wxZipIter;
 553
 554     typedef wxArchiveIterator<wxZipInputStream,
 555              std::pair<wxString, wxZipEntry*> > wxZipPairIter;
 556     @endcode
 557
 558     Transferring the catalogue of an archive @e arc to a vector @e cat,
 559     can then be done something like this:
 560
 561     @code
 562         std::vector<wxArchiveEntry*> cat((wxArchiveIter)arc, wxArchiveIter());
 563     @endcode
 564
 565     When the iterator is dereferenced, it gives away ownership of an entry
 566     object. So in the above example, when you have finished with @e cat
 567     you must delete the pointers it contains.
 568
 569     If you have smart pointers with normal copy semantics (i.e. not auto_ptr
 570     or wxScopedPtr), then you can create an iterator  which uses them instead.
 571
 572     For example, with a smart pointer class for zip entries @e ZipEntryPtr:
 573
 574     @code
 575     typedef std::vector<ZipEntryPtr> ZipCatalog;
 576     typedef wxArchiveIterator<wxZipInputStream, ZipEntryPtr> ZipIter;
 577     ZipCatalog cat((ZipIter)zip, ZipIter());
 578     @endcode
 579
 580     Iterators that return std::pair objects can be used to populate a std::multimap,
 581     to allow entries to be looked up by name.
 582     The string is initialised using the wxArchiveEntry object's
 583     wxArchiveEntry::GetInternalName function.
 584
 585     @code
 586     typedef std::multimap<wxString, wxZipEntry*> ZipCatalog;
 587     ZipCatalog cat((wxZipPairIter)zip, wxZipPairIter());
 588     @endcode
 589
 590     Note that this iterator also gives away ownership of an entry
 591     object each time it is dereferenced. So in the above example, when
 592     you have finished with @e cat you must delete the pointers it contains.
 593
 594     Or if you have them, a pair containing a smart pointer can be used
 595     (again @e ZipEntryPtr), no worries about ownership:
 596
 597     @code
 598     typedef std::multimap<wxString, ZipEntryPtr> ZipCatalog;
 599     typedef wxArchiveIterator<wxZipInputStream,
 600                 std::pair<wxString, ZipEntryPtr> > ZipPairIter;
 601     ZipCatalog cat((ZipPairIter)zip, ZipPairIter());
 602     @endcode
 603
 604     @library{wxbase}
 605     @category{archive}
 606
 607     @see wxArchiveEntry, wxArchiveInputStream, wxArchiveOutputStream
 608 */
 609 class wxArchiveIterator
 610 {
 611 public:
 612     /**
 613         Default constructor.
 614     */
 615     wxArchiveIterator();
 616
 617     /**
 618         Construct the iterator that returns all the entries in the archive input
 619         stream @a arc.
 620     */
 621     wxArchiveIterator(Arc& arc);
 622
 623     /**
 624         Returns an entry object from the archive input stream, giving away
 625         ownership.
 626     */
 627     const T operator*() const;
 628
 629     //@{
 630     /**
 631         Position the input iterator at the next entry in the archive input stream.
 632     */
 633     wxArchiveIterator operator++();
 634     wxArchiveIterator operator++(int);
 635     //@}
 636 };
 637