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     @section wxarchiveentry_nonseekable About non-seekable streams
 169
 170     This information applies only when reading archives from non-seekable streams.
 171     When the stream is seekable GetNextEntry() returns a fully populated wxArchiveEntry.
 172     See @ref overview_archive_noseek for more information.
 173
 174     For generic programming, when the worst case must be assumed, you can rely on
 175     all the fields of wxArchiveEntry being fully populated when
 176     wxArchiveInputStream::GetNextEntry() returns, with the the following exceptions:
 177
 178     @li GetSize(): guaranteed to be available after the entry has been read to Eof(),
 179         or CloseEntry() has been called;
 180     @li IsReadOnly(): guaranteed to be available after the end of the archive has
 181         been reached, i.e. after GetNextEntry() returns NULL and Eof() is true.
 182
 183     @library{wxbase}
 184     @category{archive}
 185
 186     @see @ref overview_archive, @ref overview_archive_generic,
 187          wxArchiveInputStream, wxArchiveOutputStream, wxArchiveNotifier
 188 */
 189 class wxArchiveEntry : public wxObject
 190 {
 191 public:
 192     /**
 193         Returns a copy of this entry object.
 194     */
 195     wxArchiveEntry* Clone() const;
 196
 197     /**
 198         Gets the entry's timestamp.
 199     */
 200     virtual wxDateTime GetDateTime() const = 0;
 201
 202     /**
 203         Sets the entry's timestamp.
 204     */
 205     virtual void SetDateTime(const wxDateTime& dt) = 0;
 206
 207     /**
 208         Returns the entry's name, by default in the native format.
 209         The name can include directory components, i.e. it can be a full path.
 210
 211         If this is a directory entry, (i.e. if IsDir() is @true) then the
 212         returned string is the name with a trailing path separator.
 213     */
 214     virtual wxString GetName(wxPathFormat format = wxPATH_NATIVE) const = 0;
 215
 216     /**
 217         Sets the entry's name.
 218         Setting a name with a trailing path separator sets IsDir().
 219
 220         @see GetName()
 221     */
 222     virtual void SetName(const wxString& name,
 223                          wxPathFormat format = wxPATH_NATIVE) = 0;
 224
 225     /**
 226         Returns the size of the entry's data in bytes.
 227     */
 228     virtual wxFileOffset GetSize() const = 0;
 229
 230     /**
 231         Sets the size of the entry's data in bytes.
 232     */
 233     virtual void SetSize(wxFileOffset size) = 0;
 234
 235     /**
 236         Returns the path format used internally within the archive to store
 237         filenames.
 238     */
 239     virtual wxPathFormat GetInternalFormat() const = 0;
 240
 241     /**
 242         Returns the entry's filename in the internal format used within the
 243         archive. The name can include directory components, i.e. it can be a
 244         full path.
 245
 246         The names of directory entries are returned without any trailing path
 247         separator. This gives a canonical name that can be used in comparisons.
 248
 249         @see @ref overview_archive_byname
 250     */
 251     virtual wxString GetInternalName() const = 0;
 252
 253     /**
 254         Returns a numeric value unique to the entry within the archive.
 255     */
 256     virtual wxFileOffset GetOffset() const = 0;
 257
 258     /**
 259         Returns @true if this is a directory entry.
 260
 261         Directory entries are entries with no data, which are used to store
 262         the meta-data of directories. They also make it possible for completely
 263         empty directories to be stored.
 264
 265         @note
 266         The names of entries within an archive can be complete paths, and
 267         unarchivers typically create whatever directories are necessary as they
 268         restore files, even if the archive contains no explicit directory entries.
 269     */
 270     virtual bool IsDir() const = 0;
 271
 272     /**
 273         Marks this entry as a directory if @a isDir is @true. See IsDir() for more info.
 274     */
 275     virtual void SetIsDir(bool isDir = true) = 0;
 276
 277     /**
 278         Returns @true if the entry is a read-only file.
 279     */
 280     virtual bool IsReadOnly() const = 0;
 281
 282     /**
 283         Sets this entry as a read-only file.
 284     */
 285     virtual void SetIsReadOnly(bool isReadOnly = true) = 0;
 286
 287     /**
 288         Sets the notifier (see wxArchiveNotifier) for this entry.
 289
 290         Whenever the wxArchiveInputStream updates this entry, it will then invoke
 291         the associated notifier's wxArchiveNotifier::OnEntryUpdated method.
 292
 293         Setting a notifier is not usually necessary. It is used to handle
 294         certain cases when modifying an archive in a pipeline (i.e. between
 295         non-seekable streams).
 296     */
 297     void SetNotifier(wxArchiveNotifier& notifier);
 298
 299     /**
 300         Unsets the notifier eventually attached to this entry.
 301     */
 302     virtual void UnsetNotifier();
 303 };
 304
 305
 306 /**
 307     Type of stream enumeration; used by wxArchiveClassFactory methods.
 308 */
 309 enum wxStreamProtocolType
 310 {
 311     wxSTREAM_PROTOCOL,  //!< wxFileSystem protocol (should be only one)
 312     wxSTREAM_MIMETYPE,  //!< MIME types the stream handles
 313     wxSTREAM_ENCODING,  //!< Not used for archives
 314     wxSTREAM_FILEEXT    //!< File extensions the stream handles
 315 };
 316
 317 /**
 318     @class wxArchiveClassFactory
 319     @wxheader{archive.h}
 320
 321     Allows the creation of streams to handle archive formats such as zip and tar.
 322
 323     For example, given a filename you can search for a factory that will
 324     handle it and create a stream to read it:
 325
 326     @code
 327         factory = wxArchiveClassFactory::Find(filename, wxSTREAM_FILEEXT);
 328         if (factory)
 329             stream = factory->NewStream(new wxFFileInputStream(filename));
 330     @endcode
 331
 332     wxArchiveClassFactory::Find can also search for a factory by MIME type
 333     or wxFileSystem protocol.
 334
 335     The available factories can be enumerated using
 336     wxArchiveClassFactory::GetFirst() and wxArchiveClassFactory::GetNext().
 337
 338     @library{wxbase}
 339     @category{archive}
 340
 341     @see @ref overview_archive, @ref overview_archive_generic, wxArchiveEntry,
 342          wxArchiveInputStream, wxArchiveOutputStream, wxFilterClassFactory
 343 */
 344 class wxArchiveClassFactory : public wxObject
 345 {
 346 public:
 347     /**
 348         Returns @true if this factory can handle the given protocol, MIME type
 349         or file extension.
 350
 351         When using wxSTREAM_FILEEXT for the second parameter, the first parameter
 352         can be a complete filename rather than just an extension.
 353     */
 354     bool CanHandle(const wxChar* protocol,
 355                    wxStreamProtocolType type = wxSTREAM_PROTOCOL) const;
 356
 357     /**
 358         A static member that finds a factory that can handle a given protocol, MIME
 359         type or file extension.  Returns a pointer to the class factory if found, or
 360         @NULL otherwise. It does not give away ownership of the factory.
 361
 362         When using wxSTREAM_FILEEXT for the second parameter, the first parameter
 363         can be a complete filename rather than just an extension.
 364     */
 365     static const wxArchiveClassFactory* Find(const wxChar* protocol,
 366             wxStreamProtocolType type = wxSTREAM_PROTOCOL);
 367
 368     /**
 369         Returns the wxMBConv object that the created streams will use when
 370         translating meta-data. The initial default, set by the constructor,
 371         is wxConvLocal.
 372     */
 373     wxMBConv GetConv() const;
 374
 375     /**
 376         Sets the wxMBConv object that the created streams will use when
 377         translating meta-data.
 378     */
 379     void SetConv(wxMBConv& conv);
 380
 381     //@{
 382     /**
 383         GetFirst and GetNext can be used to enumerate the available factories.
 384         For example, to list them:
 385
 386         @code
 387         wxString list;
 388         const wxArchiveClassFactory *factory = wxArchiveClassFactory::GetFirst();
 389
 390         while (factory) {
 391             list << factory->GetProtocol() << _T("\n");
 392             factory = factory->GetNext();
 393         }
 394         @endcode
 395
 396         GetFirst() and GetNext() return a pointer to a factory or @NULL if no more
 397         are available. They do not give away ownership of the factory.
 398     */
 399     static const wxArchiveClassFactory* GetFirst() const;
 400     const wxArchiveClassFactory* GetNext() const;
 401     //@}
 402
 403     /**
 404         Calls the static GetInternalName() function for the archive entry type,
 405         for example wxZipEntry::GetInternalName.
 406     */
 407     wxString GetInternalName(const wxString& name,
 408                              wxPathFormat format = wxPATH_NATIVE) const;
 409
 410     /**
 411         Returns the wxFileSystem protocol supported by this factory.
 412         Equivalent to @code wxString(*GetProtocols()) @endcode.
 413     */
 414     wxString GetProtocol() const;
 415
 416     /**
 417         Returns the protocols, MIME types or file extensions supported by this
 418         factory, as an array of null terminated strings.
 419
 420         It does not give away ownership of the array or strings.
 421         For example, to list the file extensions a factory supports:
 422
 423         @code
 424         wxString list;
 425         const wxChar *const *p;
 426
 427         for (p = factory->GetProtocols(wxSTREAM_FILEEXT); *p; p++)
 428             list << *p << _T("\n");
 429         @encode
 430     */
 431     const wxChar* const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL) const;
 432
 433     /**
 434         Create a new wxArchiveEntry object of the appropriate type.
 435     */
 436     wxArchiveEntry* NewEntry() const;
 437
 438     //@{
 439     /**
 440         Create a new input or output stream to read or write an archive.
 441
 442         If the parent stream is passed as a pointer then the new archive stream
 443         takes ownership of it. If it is passed by reference then it does not.
 444     */
 445     wxArchiveInputStream* NewStream(wxInputStream& stream) const;
 446     wxArchiveOutputStream* NewStream(wxOutputStream& stream) const;
 447     wxArchiveInputStream* NewStream(wxInputStream* stream) const;
 448     wxArchiveOutputStream* NewStream(wxOutputStream* stream) const;
 449     //@}
 450
 451     /**
 452         Adds this class factory to the list returned by GetFirst() or GetNext().
 453
 454         It is not necessary to do this to use the archive streams. It is usually
 455         used when implementing streams, typically the implementation will
 456         add a static instance of its factory class.
 457
 458         It can also be used to change the order of a factory already in the list,
 459         bringing it to the front. This isn't a thread safe operation
 460         so can't be done when other threads are running that will be using the list.
 461         The list does not take ownership of the factory.
 462     */
 463     void PushFront();
 464
 465     /**
 466         Removes this class factory from the list returned by GetFirst() and GetNext().
 467
 468         Removing from the list isn't a thread safe operation so can't be done when
 469         other threads are running that will be using the list.
 470         The list does not own the factories, so removing a factory does not delete it.
 471     */
 472     void Remove();
 473 };
 474
 475
 476
 477 /**
 478     @class wxArchiveNotifier
 479     @wxheader{archive.h}
 480
 481     If you need to know when a wxArchiveInputStream updates a wxArchiveEntry
 482     object, you can create a notifier by deriving from this abstract base class,
 483     overriding wxArchiveNotifier::OnEntryUpdated.
 484
 485     An instance of your notifier class can then be assigned to the wxArchiveEntry
 486     object using wxArchiveEntry::SetNotifier.
 487     Your OnEntryUpdated() method will then be invoked whenever the input
 488     stream updates the entry.
 489
 490     Setting a notifier is not usually necessary. It is used to handle
 491     certain cases when modifying an archive in a pipeline (i.e. between
 492     non-seekable streams).
 493     See @ref overview_archive_noseek.
 494
 495     @library{wxbase}
 496     @category{archive}
 497
 498     @see @ref overview_archive_noseek, wxArchiveEntry, wxArchiveInputStream,
 499          wxArchiveOutputStream
 500 */
 501 class wxArchiveNotifier
 502 {
 503 public:
 504     /**
 505         This method must be overridden in your derived class.
 506     */
 507     void OnEntryUpdated(class wxArchiveEntry& entry);
 508 };
 509
 510
 511
 512 /**
 513     @class wxArchiveIterator
 514     @wxheader{archive.h}
 515
 516     An input iterator template class that can be used to transfer an archive's
 517     catalogue to a container. It is only available if wxUSE_STL is set to 1
 518     in setup.h, and the uses for it outlined below require a compiler which
 519     supports member templates.
 520
 521     @code
 522     template class Arc, class T = typename Arc::entry_type*
 523     class wxArchiveIterator
 524     {
 525         // this constructor creates an 'end of sequence' object
 526         wxArchiveIterator();
 527
 528         // template parameter 'Arc' should be the type of an archive input stream
 529         wxArchiveIterator(Arc& arc) {
 530             // ...
 531         }
 532     };
 533     @endcode
 534
 535     The first template parameter should be the type of archive input stream
 536     (e.g. wxArchiveInputStream) and the second can either be a pointer to an entry
 537     (e.g. wxArchiveEntry*), or a string/pointer pair (e.g. std::pairwxString,
 538     wxArchiveEntry*).
 539
 540     The @c wx/archive.h header defines the following typedefs:
 541
 542     @code
 543     typedef wxArchiveIterator<wxArchiveInputStream> wxArchiveIter;
 544
 545     typedef wxArchiveIterator<wxArchiveInputStream,
 546             std::pair<wxString, wxArchiveEntry*> > wxArchivePairIter;
 547     @endcode
 548
 549     The header for any implementation of this interface should define similar
 550     typedefs for its types, for example in @c wx/zipstrm.h there is:
 551
 552     @code
 553     typedef wxArchiveIterator<wxZipInputStream> wxZipIter;
 554
 555     typedef wxArchiveIterator<wxZipInputStream,
 556              std::pair<wxString, wxZipEntry*> > wxZipPairIter;
 557     @endcode
 558
 559     Transferring the catalogue of an archive @e arc to a vector @e cat,
 560     can then be done something like this:
 561
 562     @code
 563         std::vector<wxArchiveEntry*> cat((wxArchiveIter)arc, wxArchiveIter());
 564     @endcode
 565
 566     When the iterator is dereferenced, it gives away ownership of an entry
 567     object. So in the above example, when you have finished with @e cat
 568     you must delete the pointers it contains.
 569
 570     If you have smart pointers with normal copy semantics (i.e. not auto_ptr
 571     or wxScopedPtr), then you can create an iterator  which uses them instead.
 572
 573     For example, with a smart pointer class for zip entries @e ZipEntryPtr:
 574
 575     @code
 576     typedef std::vector<ZipEntryPtr> ZipCatalog;
 577     typedef wxArchiveIterator<wxZipInputStream, ZipEntryPtr> ZipIter;
 578     ZipCatalog cat((ZipIter)zip, ZipIter());
 579     @endcode
 580
 581     Iterators that return std::pair objects can be used to populate a std::multimap,
 582     to allow entries to be looked up by name.
 583     The string is initialised using the wxArchiveEntry object's
 584     wxArchiveEntry::GetInternalName function.
 585
 586     @code
 587     typedef std::multimap<wxString, wxZipEntry*> ZipCatalog;
 588     ZipCatalog cat((wxZipPairIter)zip, wxZipPairIter());
 589     @endcode
 590
 591     Note that this iterator also gives away ownership of an entry
 592     object each time it is dereferenced. So in the above example, when
 593     you have finished with @e cat you must delete the pointers it contains.
 594
 595     Or if you have them, a pair containing a smart pointer can be used
 596     (again @e ZipEntryPtr), no worries about ownership:
 597
 598     @code
 599     typedef std::multimap<wxString, ZipEntryPtr> ZipCatalog;
 600     typedef wxArchiveIterator<wxZipInputStream,
 601                 std::pair<wxString, ZipEntryPtr> > ZipPairIter;
 602     ZipCatalog cat((ZipPairIter)zip, ZipPairIter());
 603     @endcode
 604
 605     @library{wxbase}
 606     @category{archive}
 607
 608     @see wxArchiveEntry, wxArchiveInputStream, wxArchiveOutputStream
 609 */
 610 class wxArchiveIterator
 611 {
 612 public:
 613     /**
 614         Default constructor.
 615     */
 616     wxArchiveIterator();
 617
 618     /**
 619         Construct the iterator that returns all the entries in the archive input
 620         stream @a arc.
 621     */
 622     wxArchiveIterator(Arc& arc);
 623
 624     /**
 625         Returns an entry object from the archive input stream, giving away
 626         ownership.
 627     */
 628     const T operator*() const;
 629
 630     //@{
 631     /**
 632         Position the input iterator at the next entry in the archive input stream.
 633     */
 634     wxArchiveIterator operator++();
 635     wxArchiveIterator operator++(int);
 636     //@}
 637 };
 638