interface/archive.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        archive.h
   3 // Purpose:     documentation for wxArchiveInputStream class
   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     @seealso
  27     @ref overview_wxarc "Archive formats such as zip", wxArchiveEntry,
  28     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
  42         object, giving away ownership. Reading this wxArchiveInputStream then
  43         returns the entry's data.
  44     */
  45     wxArchiveEntry* GetNextEntry();
  46
  47     /**
  48         Closes the current entry if one is open, then opens the entry specified
  49         by the wxArchiveEntry object.
  50         @a entry must be from the same archive file that this
  51         wxArchiveInputStream is reading, and it must be reading it from a
  52         seekable stream.
  53     */
  54     bool OpenEntry(wxArchiveEntry& entry);
  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     @seealso
  74     @ref overview_wxarc "Archive formats such as zip", wxArchiveEntry,
  75     wxArchiveInputStream
  76 */
  77 class wxArchiveOutputStream : public wxFilterOutputStream
  78 {
  79 public:
  80     /**
  81         Calls Close() if it has not already
  82         been called.
  83     */
  84     ~wxArchiveOutputStream();
  85
  86     /**
  87         Closes the archive, returning @true if it was successfully written.
  88         Called by the destructor if not called explicitly.
  89     */
  90     bool Close();
  91
  92     /**
  93         Close the current entry. It is called implicitly whenever another new
  94         entry is created with CopyEntry()
  95         or PutNextEntry(), or
  96         when the archive is closed.
  97     */
  98     bool CloseEntry();
  99
 100     /**
 101         Some archive formats have additional meta-data that applies to the archive
 102         as a whole.  For example in the case of zip there is a comment, which
 103         is stored at the end of the zip file.  CopyArchiveMetaData() can be used
 104         to transfer such information when writing a modified copy of an archive.
 105         Since the position of the meta-data can vary between the various archive
 106         formats, it is best to call CopyArchiveMetaData() before transferring
 107         the entries.  The wxArchiveOutputStream
 108         will then hold on to the meta-data and write it at the correct point in
 109         the output file.
 110         When the input archive is being read from a non-seekable stream, the
 111         meta-data may not be available when CopyArchiveMetaData() is called,
 112         in which case the two streams set up a link and transfer the data
 113         when it becomes available.
 114     */
 115     bool CopyArchiveMetaData(wxArchiveInputStream& stream);
 116
 117     /**
 118         Takes ownership of @a entry and uses it to create a new entry in the
 119         archive. @a entry is then opened in the input stream @e stream
 120         and its contents copied to this stream.
 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         @a entry must be from the same archive file that @a stream is
 125         accessing. For non-seekable streams, @a entry must also be the last
 126         thing read from @e stream.
 127     */
 128     bool CopyEntry(wxArchiveEntry* entry,
 129                    wxArchiveInputStream& stream);
 130
 131     /**
 132         )
 133         Create a new directory entry
 134         (see wxArchiveEntry::IsDir)
 135         with the given name and timestamp.
 136         PutNextEntry() can
 137         also be used to create directory entries, by supplying a name with
 138         a trailing path separator.
 139     */
 140     bool PutNextDirEntry(const wxString& name);
 141
 142     //@{
 143     /**
 144         , @b off_t@e size = wxInvalidOffset)
 145         Create a new entry with the given name, timestamp and size. The entry's
 146         data can then be written by writing to this wxArchiveOutputStream.
 147     */
 148     bool PutNextEntry(wxArchiveEntry* entry);
 149     bool PutNextEntry(const wxString& name);
 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     @seealso
 167     @ref overview_wxarc "Archive formats such as zip", @ref overview_wxarcgeneric
 168     "Generic archive programming", wxArchiveInputStream, wxArchiveOutputStream, wxArchiveNotifier
 169 */
 170 class wxArchiveEntry : public wxObject
 171 {
 172 public:
 173     /**
 174         Returns a copy of this entry object.
 175     */
 176     wxArchiveEntry* Clone() const;
 177
 178     //@{
 179     /**
 180         The entry's timestamp.
 181     */
 182     wxDateTime GetDateTime();
 183     const void SetDateTime(const wxDateTime& dt);
 184     //@}
 185
 186     //@{
 187     /**
 188         The entry's name, by default in the native format. The name can include
 189         directory components, i.e. it can be a full path.
 190         If this is a directory entry, (i.e. if IsDir()
 191         is @true) then GetName() returns the name with a trailing path separator.
 192         Similarly, setting a name with a trailing path separator sets IsDir().
 193     */
 194     wxString GetName(wxPathFormat format = wxPATH_NATIVE);
 195     const void SetName(const wxString& name,
 196                        wxPathFormat format = wxPATH_NATIVE);
 197     //@}
 198
 199     //@{
 200     /**
 201         The size of the entry's data in bytes.
 202     */
 203     off_t GetSize();
 204     const void SetSize(off_t size);
 205     //@}
 206
 207     /**
 208         Returns the path format used internally within the archive to store
 209         filenames.
 210     */
 211     wxPathFormat GetInternalFormat() const;
 212
 213     /**
 214         Returns the entry's filename in the internal format used within the
 215         archive. The name can include directory components, i.e. it can be a
 216         full path.
 217         The names of directory entries are returned without any trailing path
 218         separator. This gives a canonical name that can be used in comparisons.
 219
 220         @see @ref overview_wxarcbyname "Looking up an archive entry by name"
 221     */
 222     wxString GetInternalName() const;
 223
 224     /**
 225         Returns a numeric value unique to the entry within the archive.
 226     */
 227     off_t GetOffset() const;
 228
 229     //@{
 230     /**
 231         True if this is a directory entry.
 232         Directory entries are entries with no data, which are used to store
 233         the meta-data of directories. They also make it possible for completely
 234         empty directories to be stored.
 235         The names of entries within an archive can be complete paths, and
 236         unarchivers typically create whatever directories are necessary as they
 237         restore files, even if the archive contains no explicit directory entries.
 238     */
 239     bool IsDir();
 240     const void SetIsDir(bool isDir = true);
 241     //@}
 242
 243     //@{
 244     /**
 245         True if the entry is a read-only file.
 246     */
 247     bool IsReadOnly();
 248     const void SetIsReadOnly(bool isReadOnly = true);
 249     //@}
 250
 251     //@{
 252     /**
 253         Sets the notifier for this entry.
 254         Whenever the wxArchiveInputStream updates
 255         this entry, it will then invoke the associated
 256         notifier's wxArchiveNotifier::OnEntryUpdated
 257         method.
 258         Setting a notifier is not usually necessary. It is used to handle
 259         certain cases when modifying an archive in a pipeline (i.e. between
 260         non-seekable streams).
 261     */
 262     void SetNotifier(wxArchiveNotifier& notifier);
 263     void UnsetNotifier();
 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     @seealso
 293     @ref overview_wxarc "Archive formats such as zip", @ref overview_wxarcgeneric
 294     "Generic archive programming", wxArchiveEntry, wxArchiveInputStream, wxArchiveOutputStream, wxFilterClassFactory
 295 */
 296 class wxArchiveClassFactory : public wxObject
 297 {
 298 public:
 299     /**
 300         Returns @true if this factory can handle the given protocol, MIME type
 301         or file extension.
 302         When using wxSTREAM_FILEEXT for the second parameter, the first parameter
 303         can be a complete filename rather than just an extension.
 304     */
 305     bool CanHandle(const wxChar* protocol,
 306                    wxStreamProtocolType type = wxSTREAM_PROTOCOL) const;
 307
 308     /**
 309         A static member that finds a factory that can handle a given protocol, MIME
 310         type or file extension.  Returns a pointer to the class factory if found, or
 311         @NULL otherwise. It does not give away ownership of the factory.
 312         When using wxSTREAM_FILEEXT for the second parameter, the first parameter
 313         can be a complete filename rather than just an extension.
 314     */
 315     static const wxArchiveClassFactory* Find(const wxChar* protocol,
 316             wxStreamProtocolType type = wxSTREAM_PROTOCOL);
 317
 318     //@{
 319     /**
 320         The wxMBConv object that the created streams
 321         will use when translating meta-data. The initial default, set by the
 322         constructor, is wxConvLocal.
 323     */
 324     wxMBConv GetConv();
 325     const void SetConv(wxMBConv& conv);
 326     //@}
 327
 328     //@{
 329     /**
 330         GetFirst and GetNext can be used to enumerate the available factories.
 331         For example, to list them:
 332
 333         GetFirst()/GetNext() return a pointer to a factory or @NULL if no more
 334         are available. They do not give away ownership of the factory.
 335     */
 336     static const wxArchiveClassFactory* GetFirst() const;
 337     const wxArchiveClassFactory* GetNext() const;
 338     //@}
 339
 340     /**
 341         Calls the static GetInternalName() function for the archive entry type,
 342         for example
 343          wxZipEntry::GetInternalName.
 344     */
 345     wxString GetInternalName(const wxString& name,
 346                              wxPathFormat format = wxPATH_NATIVE) const;
 347
 348     /**
 349         Returns the wxFileSystem protocol supported by this factory. Equivalent
 350         to wxString(*GetProtcols()).
 351     */
 352     wxString GetProtocol() const;
 353
 354     /**
 355         Returns the protocols, MIME types or file extensions supported by this
 356         factory, as an array of null terminated strings. It does not give away
 357         ownership of the array or strings.
 358         For example, to list the file extensions a factory supports:
 359     */
 360     const wxChar* const* GetProtocols(wxStreamProtocolType type = wxSTREAM_PROTOCOL) const;
 361
 362     /**
 363         Create a new wxArchiveEntry object of the
 364         appropriate type.
 365     */
 366     wxArchiveEntry* NewEntry() const;
 367
 368     //@{
 369     /**
 370         Create a new input or output stream to read or write an archive.
 371         If the parent stream is passed as a pointer then the new archive stream
 372         takes ownership of it. If it is passed by reference then it does not.
 373     */
 374     wxArchiveInputStream* NewStream(wxInputStream& stream) const;
 375     const wxArchiveOutputStream*  NewStream(wxOutputStream& stream) const;
 376     const wxArchiveInputStream*  NewStream(wxInputStream* stream) const;
 377     const wxArchiveOutputStream*  NewStream(wxOutputStream* stream) const;
 378     //@}
 379
 380     /**
 381         Adds this class factory to the list returned
 382         by @ref getfirst() GetFirst()/GetNext.
 383         It is not necessary to do this to use the archive streams. It is usually
 384         used when implementing streams, typically the implementation will
 385         add a static instance of its factory class.
 386         It can also be used to change the order of a factory already in the list,
 387         bringing it to the front. This isn't a thread safe operation
 388         so can't be done when other threads are running that will be using the list.
 389         The list does not take ownership of the factory.
 390     */
 391     void PushFront();
 392
 393     /**
 394         Removes this class factory from the list returned
 395         by @ref getfirst() GetFirst()/GetNext.
 396         Removing from the list isn't a thread safe operation
 397         so can't be done when other threads are running that will be using the list.
 398         The list does not own the factories, so removing a factory does not delete it.
 399     */
 400     void Remove();
 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     @seealso
 427     @ref overview_wxarcnoseek "Archives on non-seekable streams", wxArchiveEntry,
 428     wxArchiveInputStream, wxArchiveOutputStream
 429 */
 430 class wxArchiveNotifier
 431 {
 432 public:
 433     /**
 434         This method must be overridden in your derived class.
 435     */
 436     void OnEntryUpdated(class wxArchiveEntry& entry);
 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     @seealso
 539     wxArchiveEntry, wxArchiveInputStream, wxArchiveOutputStream
 540 */
 541 class wxArchiveIterator
 542 {
 543 public:
 544     //@{
 545     /**
 546         Construct iterator that returns all the entries in the archive input
 547         stream @e arc.
 548     */
 549     wxArchiveIterator();
 550     wxArchiveIterator(Arc& arc);
 551     //@}
 552
 553     /**
 554         Returns an entry object from the archive input stream, giving away
 555         ownership.
 556     */
 557     const T operator*() const;
 558
 559     //@{
 560     /**
 561         Position the input iterator at the next entry in the archive input stream.
 562     */
 563     wxArchiveIterator operator++();
 564     wxArchiveIterator operator++(int );
 565     //@}
 566 };