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 /**
 305     @class wxArchiveClassFactory
 306
 307     Allows the creation of streams to handle archive formats such as zip and tar.
 308
 309     For example, given a filename you can search for a factory that will
 310     handle it and create a stream to read it:
 311
 312     @code
 313         factory = wxArchiveClassFactory::Find(filename, wxSTREAM_FILEEXT);
 314         if (factory)
 315             stream = factory->NewStream(new wxFFileInputStream(filename));
 316     @endcode
 317
 318     wxArchiveClassFactory::Find can also search for a factory by MIME type
 319     or wxFileSystem protocol.
 320
 321     The available factories can be enumerated using
 322     wxArchiveClassFactory::GetFirst() and wxArchiveClassFactory::GetNext().
 323
 324     @library{wxbase}
 325     @category{archive,streams}
 326
 327     @see @ref overview_archive, @ref overview_archive_generic, wxArchiveEntry,
 328          wxArchiveInputStream, wxArchiveOutputStream, wxFilterClassFactory
 329 */
 330 class wxArchiveClassFactory : public wxObject
 331 {
 332 public:
 333     /**
 334         Returns @true if this factory can handle the given protocol, MIME type
 335         or file extension.
 336
 337         When using wxSTREAM_FILEEXT for the second parameter, the first parameter
 338         can be a complete filename rather than just an extension.
 339     */
 340     bool CanHandle(const wxString& protocol,
 341                    wxStreamProtocolType type = wxSTREAM_PROTOCOL) const;
 342
 343     /**
 344         A static member that finds a factory that can handle a given protocol, MIME
 345         type or file extension.  Returns a pointer to the class factory if found, or
 346         @NULL otherwise. It does not give away ownership of the factory.
 347
 348         When using wxSTREAM_FILEEXT for the second parameter, the first parameter
 349         can be a complete filename rather than just an extension.
 350     */
 351     static const wxArchiveClassFactory* Find(const wxString& protocol,
 352             wxStreamProtocolType type = wxSTREAM_PROTOCOL);
 353
 354     /**
 355         Returns the wxMBConv object that the created streams will use when
 356         translating meta-data. The initial default, set by the constructor,
 357         is wxConvLocal.
 358     */
 359     wxMBConv& GetConv() const;
 360
 361     /**
 362         Sets the wxMBConv object that the created streams will use when
 363         translating meta-data.
 364     */
 365     void SetConv(wxMBConv& conv);
 366
 367     //@{
 368     /**
 369         GetFirst and GetNext can be used to enumerate the available factories.
 370         For example, to list them:
 371
 372         @code
 373         wxString list;
 374         const wxArchiveClassFactory *factory = wxArchiveClassFactory::GetFirst();
 375
 376         while (factory) {
 377             list << factory->GetProtocol() << wxT("\n");
 378             factory = factory->GetNext();
 379         }
 380         @endcode
 381
 382         GetFirst() and GetNext() return a pointer to a factory or @NULL if no more
 383         are available. They do not give away ownership of the factory.
 384     */
 385     static const wxArchiveClassFactory* GetFirst();
 386     const wxArchiveClassFactory* GetNext() const;
 387     //@}
 388
 389     /**
 390         Calls the static GetInternalName() function for the archive entry type,
 391         for example wxZipEntry::GetInternalName.
 392     */
 393     virtual wxString GetInternalName(const wxString& name,
 394                                      wxPathFormat format = wxPATH_NATIVE) const = 0;
 395
 396     /**
 397         Returns the wxFileSystem protocol supported by this factory.
 398         Equivalent to @code wxString(*GetProtocols()) @endcode.
 399     */
 400     wxString GetProtocol() const;
 401
 402     /**
 403         Returns the protocols, MIME types or file extensions supported by this
 404         factory, as an array of null terminated strings.
 405
 406         It does not give away ownership of the array or strings.
 407         For example, to list the file extensions a factory supports:
 408
 409         @code
 410         wxString list;
 411         const wxChar *const *p;
 412
 413         for (p = factory->GetProtocols(wxSTREAM_FILEEXT); *p; p++)
 414             list << *p << wxT("\n");
 415         @endcode
 416     */
 417     virtual const wxChar** GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL) const = 0;
 418
 419     /**
 420         Create a new wxArchiveEntry object of the appropriate type.
 421     */
 422     wxArchiveEntry* NewEntry() const;
 423
 424     //@{
 425     /**
 426         Create a new input or output stream to read or write an archive.
 427
 428         If the parent stream is passed as a pointer then the new archive stream
 429         takes ownership of it. If it is passed by reference then it does not.
 430     */
 431     wxArchiveInputStream* NewStream(wxInputStream& stream) const;
 432     wxArchiveOutputStream* NewStream(wxOutputStream& stream) const;
 433     wxArchiveInputStream* NewStream(wxInputStream* stream) const;
 434     wxArchiveOutputStream* NewStream(wxOutputStream* stream) const;
 435     //@}
 436
 437     /**
 438         Adds this class factory to the list returned by GetFirst() or GetNext().
 439
 440         It is not necessary to do this to use the archive streams. It is usually
 441         used when implementing streams, typically the implementation will
 442         add a static instance of its factory class.
 443
 444         It can also be used to change the order of a factory already in the list,
 445         bringing it to the front. This isn't a thread safe operation
 446         so can't be done when other threads are running that will be using the list.
 447         The list does not take ownership of the factory.
 448     */
 449     void PushFront();
 450
 451     /**
 452         Removes this class factory from the list returned by GetFirst() and GetNext().
 453
 454         Removing from the list isn't a thread safe operation so can't be done when
 455         other threads are running that will be using the list.
 456         The list does not own the factories, so removing a factory does not delete it.
 457     */
 458     void Remove();
 459 };
 460
 461
 462
 463 /**
 464     @class wxArchiveNotifier
 465
 466     If you need to know when a wxArchiveInputStream updates a wxArchiveEntry
 467     object, you can create a notifier by deriving from this abstract base class,
 468     overriding wxArchiveNotifier::OnEntryUpdated.
 469
 470     An instance of your notifier class can then be assigned to the wxArchiveEntry
 471     object using wxArchiveEntry::SetNotifier.
 472     Your OnEntryUpdated() method will then be invoked whenever the input
 473     stream updates the entry.
 474
 475     Setting a notifier is not usually necessary. It is used to handle
 476     certain cases when modifying an archive in a pipeline (i.e. between
 477     non-seekable streams).
 478     See @ref overview_archive_noseek.
 479
 480     @library{wxbase}
 481     @category{archive,streams}
 482
 483     @see @ref overview_archive_noseek, wxArchiveEntry, wxArchiveInputStream,
 484          wxArchiveOutputStream
 485 */
 486 class wxArchiveNotifier
 487 {
 488 public:
 489     /**
 490         This method must be overridden in your derived class.
 491     */
 492     virtual void OnEntryUpdated(wxArchiveEntry& entry) = 0;
 493 };
 494
 495
 496
 497 /**
 498     @class wxArchiveIterator
 499
 500     An input iterator template class that can be used to transfer an archive's
 501     catalogue to a container. It is only available if wxUSE_STL is set to 1
 502     in setup.h, and the uses for it outlined below require a compiler which
 503     supports member templates.
 504
 505     @code
 506     template<class Arc, class T = typename Arc::entry_type*>
 507     class wxArchiveIterator
 508     {
 509         // this constructor creates an 'end of sequence' object
 510         wxArchiveIterator();
 511
 512         // template parameter 'Arc' should be the type of an archive input stream
 513         wxArchiveIterator(Arc& arc) {
 514             // ...
 515         }
 516     };
 517     @endcode
 518
 519     The first template parameter should be the type of archive input stream
 520     (e.g. wxArchiveInputStream) and the second can either be a pointer to an entry
 521     (e.g. wxArchiveEntry*), or a string/pointer pair
 522     (e.g. std::pair<wxString,wxArchiveEntry*>).
 523
 524     The @c wx/archive.h header defines the following typedefs:
 525
 526     @code
 527     typedef wxArchiveIterator<wxArchiveInputStream> wxArchiveIter;
 528
 529     typedef wxArchiveIterator<wxArchiveInputStream,
 530             std::pair<wxString, wxArchiveEntry*> > wxArchivePairIter;
 531     @endcode
 532
 533     The header for any implementation of this interface should define similar
 534     typedefs for its types, for example in @c wx/zipstrm.h there is:
 535
 536     @code
 537     typedef wxArchiveIterator<wxZipInputStream> wxZipIter;
 538
 539     typedef wxArchiveIterator<wxZipInputStream,
 540              std::pair<wxString, wxZipEntry*> > wxZipPairIter;
 541     @endcode
 542
 543     Transferring the catalogue of an archive @e arc to a vector @e cat,
 544     can then be done something like this:
 545
 546     @code
 547         std::vector<wxArchiveEntry*> cat((wxArchiveIter)arc, wxArchiveIter());
 548     @endcode
 549
 550     When the iterator is dereferenced, it gives away ownership of an entry
 551     object. So in the above example, when you have finished with @e cat
 552     you must delete the pointers it contains.
 553
 554     If you have smart pointers with normal copy semantics (i.e. not auto_ptr
 555     or wxScopedPtr), then you can create an iterator  which uses them instead.
 556
 557     For example, with a smart pointer class for zip entries @e ZipEntryPtr:
 558
 559     @code
 560     typedef std::vector<ZipEntryPtr> ZipCatalog;
 561     typedef wxArchiveIterator<wxZipInputStream, ZipEntryPtr> ZipIter;
 562     ZipCatalog cat((ZipIter)zip, ZipIter());
 563     @endcode
 564
 565     Iterators that return std::pair objects can be used to populate a std::multimap,
 566     to allow entries to be looked up by name.
 567     The string is initialised using the wxArchiveEntry object's
 568     wxArchiveEntry::GetInternalName function.
 569
 570     @code
 571     typedef std::multimap<wxString, wxZipEntry*> ZipCatalog;
 572     ZipCatalog cat((wxZipPairIter)zip, wxZipPairIter());
 573     @endcode
 574
 575     Note that this iterator also gives away ownership of an entry
 576     object each time it is dereferenced. So in the above example, when
 577     you have finished with @e cat you must delete the pointers it contains.
 578
 579     Or if you have them, a pair containing a smart pointer can be used
 580     (again @e ZipEntryPtr), no worries about ownership:
 581
 582     @code
 583     typedef std::multimap<wxString, ZipEntryPtr> ZipCatalog;
 584     typedef wxArchiveIterator<wxZipInputStream,
 585                 std::pair<wxString, ZipEntryPtr> > ZipPairIter;
 586     ZipCatalog cat((ZipPairIter)zip, ZipPairIter());
 587     @endcode
 588
 589     @library{wxbase}
 590     @category{archive,streams}
 591
 592     @see wxArchiveEntry, wxArchiveInputStream, wxArchiveOutputStream
 593 */
 594 class wxArchiveIterator
 595 {
 596 public:
 597     /**
 598         Default constructor.
 599     */
 600     wxArchiveIterator();
 601
 602     /**
 603         Construct the iterator that returns all the entries in the archive input
 604         stream @a arc.
 605     */
 606     wxArchiveIterator(Arc& arc);
 607
 608     /**
 609         Returns an entry object from the archive input stream, giving away
 610         ownership.
 611     */
 612     const T operator*() const;
 613
 614     //@{
 615     /**
 616         Position the input iterator at the next entry in the archive input stream.
 617     */
 618     wxArchiveIterator operator++();
 619     wxArchiveIterator operator++(int);
 620     //@}
 621 };
 622