interface/wx/archive.h

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