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