interface/archive.h

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