1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxArchive* classes
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
10 @class wxArchiveInputStream
12 This is an abstract base class which serves as a common interface to
13 archive input streams such as wxZipInputStream.
15 wxArchiveInputStream::GetNextEntry returns an wxArchiveEntry object containing
16 the meta-data for the next entry in the archive (and gives away ownership).
18 Reading from the wxArchiveInputStream then returns the entry's data. Eof()
19 becomes @true after an attempt has been made to read past the end of the
22 When there are no more entries, GetNextEntry() returns @NULL and sets Eof().
25 @category{archive,streams}
27 @see @ref overview_archive, wxArchiveEntry, wxArchiveOutputStream
29 class wxArchiveInputStream
: public wxFilterInputStream
33 Closes the current entry. On a non-seekable stream reads to the end of
34 the current entry first.
36 virtual bool CloseEntry() = 0;
39 Closes the current entry if one is open, then reads the meta-data for
40 the next entry and returns it in a wxArchiveEntry object, giving away
41 ownership. Reading this wxArchiveInputStream then returns the entry's data.
43 wxArchiveEntry
* GetNextEntry();
46 Closes the current entry if one is open, then opens the entry specified
47 by the wxArchiveEntry object.
49 @a entry must be from the same archive file that this wxArchiveInputStream
50 is reading, and it must be reading it from a seekable stream.
52 virtual bool OpenEntry(wxArchiveEntry
& entry
) = 0;
58 @class wxArchiveOutputStream
60 This is an abstract base class which serves as a common interface to
61 archive output streams such as wxZipOutputStream.
63 wxArchiveOutputStream::PutNextEntry is used to create a new entry in the
64 output archive, then the entry's data is written to the wxArchiveOutputStream.
65 Another call to PutNextEntry() closes the current entry and begins the next.
68 @category{archive,streams}
70 @see @ref overview_archive, wxArchiveEntry, wxArchiveInputStream
72 class wxArchiveOutputStream
: public wxFilterOutputStream
76 Calls Close() if it has not already been called.
78 virtual ~wxArchiveOutputStream();
81 Closes the archive, returning @true if it was successfully written.
82 Called by the destructor if not called explicitly.
84 @see wxOutputStream::Close()
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.
93 virtual bool CloseEntry() = 0;
96 Some archive formats have additional meta-data that applies to the archive
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.
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.
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.
112 virtual bool CopyArchiveMetaData(wxArchiveInputStream
& stream
) = 0;
115 Takes ownership of @a entry and uses it to create a new entry in the
116 archive. @a entry is then opened in the input stream @a stream
117 and its contents copied to this stream.
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.
123 @a entry must be from the same archive file that @a stream is
124 accessing. For non-seekable streams, @a entry must also be the last
125 thing read from @a stream.
127 virtual bool CopyEntry(wxArchiveEntry
* entry
,
128 wxArchiveInputStream
& stream
) = 0;
131 Create a new directory entry (see wxArchiveEntry::IsDir) with the given
134 PutNextEntry() can also be used to create directory entries, by supplying
135 a name with a trailing path separator.
137 virtual bool PutNextDirEntry(const wxString
& name
,
138 const wxDateTime
& dt
= wxDateTime::Now()) = 0;
141 Takes ownership of entry and uses it to create a new entry in the archive.
142 The entry's data can then be written by writing to this wxArchiveOutputStream.
144 virtual bool PutNextEntry(wxArchiveEntry
* entry
) = 0;
147 Create a new entry with the given name, timestamp and size. The entry's
148 data can then be written by writing to this wxArchiveOutputStream.
150 virtual bool PutNextEntry(const wxString
& name
,
151 const wxDateTime
& dt
= wxDateTime::Now(),
152 wxFileOffset size
= wxInvalidOffset
) = 0;
158 @class wxArchiveEntry
160 This is an abstract base class which serves as a common interface to
161 archive entry classes such as wxZipEntry.
162 These hold the meta-data (filename, timestamp, etc.), for entries
163 in archive files such as zips and tars.
165 @section archiveentry_nonseekable About non-seekable streams
167 This information applies only when reading archives from non-seekable streams.
168 When the stream is seekable GetNextEntry() returns a fully populated wxArchiveEntry.
169 See @ref overview_archive_noseek for more information.
171 For generic programming, when the worst case must be assumed, you can rely on
172 all the fields of wxArchiveEntry being fully populated when
173 wxArchiveInputStream::GetNextEntry() returns, with the the following exceptions:
175 @li GetSize(): guaranteed to be available after the entry has been read to Eof(),
176 or CloseEntry() has been called;
177 @li IsReadOnly(): guaranteed to be available after the end of the archive has
178 been reached, i.e. after GetNextEntry() returns NULL and Eof() is true.
181 @category{archive,streams}
183 @see @ref overview_archive, @ref overview_archive_generic,
184 wxArchiveInputStream, wxArchiveOutputStream, wxArchiveNotifier
186 class wxArchiveEntry
: public wxObject
190 Returns a copy of this entry object.
192 wxArchiveEntry
* Clone() const;
195 Gets the entry's timestamp.
197 virtual wxDateTime
GetDateTime() const = 0;
200 Sets the entry's timestamp.
202 virtual void SetDateTime(const wxDateTime
& dt
) = 0;
205 Returns the entry's name, by default in the native format.
206 The name can include directory components, i.e. it can be a full path.
208 If this is a directory entry, (i.e. if IsDir() is @true) then the
209 returned string is the name with a trailing path separator.
211 virtual wxString
GetName(wxPathFormat format
= wxPATH_NATIVE
) const = 0;
214 Sets the entry's name.
215 Setting a name with a trailing path separator sets IsDir().
219 virtual void SetName(const wxString
& name
,
220 wxPathFormat format
= wxPATH_NATIVE
) = 0;
223 Returns the size of the entry's data in bytes.
225 virtual wxFileOffset
GetSize() const = 0;
228 Sets the size of the entry's data in bytes.
230 virtual void SetSize(wxFileOffset size
) = 0;
233 Returns the path format used internally within the archive to store
236 virtual wxPathFormat
GetInternalFormat() const = 0;
239 Returns the entry's filename in the internal format used within the
240 archive. The name can include directory components, i.e. it can be a
243 The names of directory entries are returned without any trailing path
244 separator. This gives a canonical name that can be used in comparisons.
246 @see @ref overview_archive_byname
248 virtual wxString
GetInternalName() const = 0;
251 Returns a numeric value unique to the entry within the archive.
253 virtual wxFileOffset
GetOffset() const = 0;
256 Returns @true if this is a directory entry.
258 Directory entries are entries with no data, which are used to store
259 the meta-data of directories. They also make it possible for completely
260 empty directories to be stored.
263 The names of entries within an archive can be complete paths, and
264 unarchivers typically create whatever directories are necessary as they
265 restore files, even if the archive contains no explicit directory entries.
267 virtual bool IsDir() const = 0;
270 Marks this entry as a directory if @a isDir is @true. See IsDir() for more info.
272 virtual void SetIsDir(bool isDir
= true) = 0;
275 Returns @true if the entry is a read-only file.
277 virtual bool IsReadOnly() const = 0;
280 Sets this entry as a read-only file.
282 virtual void SetIsReadOnly(bool isReadOnly
= true) = 0;
285 Sets the notifier (see wxArchiveNotifier) for this entry.
287 Whenever the wxArchiveInputStream updates this entry, it will then invoke
288 the associated notifier's wxArchiveNotifier::OnEntryUpdated method.
290 Setting a notifier is not usually necessary. It is used to handle
291 certain cases when modifying an archive in a pipeline (i.e. between
292 non-seekable streams).
294 void SetNotifier(wxArchiveNotifier
& notifier
);
297 Unsets the notifier eventually attached to this entry.
299 virtual void UnsetNotifier();
304 Type of stream enumeration; used by wxArchiveClassFactory methods.
306 enum wxStreamProtocolType
308 wxSTREAM_PROTOCOL
, //!< wxFileSystem protocol (should be only one)
309 wxSTREAM_MIMETYPE
, //!< MIME types the stream handles
310 wxSTREAM_ENCODING
, //!< Not used for archives
311 wxSTREAM_FILEEXT
//!< File extensions the stream handles
315 @class wxArchiveClassFactory
317 Allows the creation of streams to handle archive formats such as zip and tar.
319 For example, given a filename you can search for a factory that will
320 handle it and create a stream to read it:
323 factory = wxArchiveClassFactory::Find(filename, wxSTREAM_FILEEXT);
325 stream = factory->NewStream(new wxFFileInputStream(filename));
328 wxArchiveClassFactory::Find can also search for a factory by MIME type
329 or wxFileSystem protocol.
331 The available factories can be enumerated using
332 wxArchiveClassFactory::GetFirst() and wxArchiveClassFactory::GetNext().
335 @category{archive,streams}
337 @see @ref overview_archive, @ref overview_archive_generic, wxArchiveEntry,
338 wxArchiveInputStream, wxArchiveOutputStream, wxFilterClassFactory
340 class wxArchiveClassFactory
: public wxObject
344 Returns @true if this factory can handle the given protocol, MIME type
347 When using wxSTREAM_FILEEXT for the second parameter, the first parameter
348 can be a complete filename rather than just an extension.
350 bool CanHandle(const wxChar
* protocol
,
351 wxStreamProtocolType type
= wxSTREAM_PROTOCOL
) const;
354 A static member that finds a factory that can handle a given protocol, MIME
355 type or file extension. Returns a pointer to the class factory if found, or
356 @NULL otherwise. It does not give away ownership of the factory.
358 When using wxSTREAM_FILEEXT for the second parameter, the first parameter
359 can be a complete filename rather than just an extension.
361 static const wxArchiveClassFactory
* Find(const wxChar
* protocol
,
362 wxStreamProtocolType type
= wxSTREAM_PROTOCOL
);
365 Returns the wxMBConv object that the created streams will use when
366 translating meta-data. The initial default, set by the constructor,
369 wxMBConv
GetConv() const;
372 Sets the wxMBConv object that the created streams will use when
373 translating meta-data.
375 void SetConv(wxMBConv
& conv
);
379 GetFirst and GetNext can be used to enumerate the available factories.
380 For example, to list them:
384 const wxArchiveClassFactory *factory = wxArchiveClassFactory::GetFirst();
387 list << factory->GetProtocol() << _T("\n");
388 factory = factory->GetNext();
392 GetFirst() and GetNext() return a pointer to a factory or @NULL if no more
393 are available. They do not give away ownership of the factory.
395 static const wxArchiveClassFactory
* GetFirst() const;
396 const wxArchiveClassFactory
* GetNext() const;
400 Calls the static GetInternalName() function for the archive entry type,
401 for example wxZipEntry::GetInternalName.
403 wxString
GetInternalName(const wxString
& name
,
404 wxPathFormat format
= wxPATH_NATIVE
) const;
407 Returns the wxFileSystem protocol supported by this factory.
408 Equivalent to @code wxString(*GetProtocols()) @endcode.
410 wxString
GetProtocol() const;
413 Returns the protocols, MIME types or file extensions supported by this
414 factory, as an array of null terminated strings.
416 It does not give away ownership of the array or strings.
417 For example, to list the file extensions a factory supports:
421 const wxChar *const *p;
423 for (p = factory->GetProtocols(wxSTREAM_FILEEXT); *p; p++)
424 list << *p << _T("\n");
427 const wxChar
* const* GetProtocols(wxStreamProtocolType type
= wxSTREAM_PROTOCOL
) const;
430 Create a new wxArchiveEntry object of the appropriate type.
432 wxArchiveEntry
* NewEntry() const;
436 Create a new input or output stream to read or write an archive.
438 If the parent stream is passed as a pointer then the new archive stream
439 takes ownership of it. If it is passed by reference then it does not.
441 wxArchiveInputStream
* NewStream(wxInputStream
& stream
) const;
442 wxArchiveOutputStream
* NewStream(wxOutputStream
& stream
) const;
443 wxArchiveInputStream
* NewStream(wxInputStream
* stream
) const;
444 wxArchiveOutputStream
* NewStream(wxOutputStream
* stream
) const;
448 Adds this class factory to the list returned by GetFirst() or GetNext().
450 It is not necessary to do this to use the archive streams. It is usually
451 used when implementing streams, typically the implementation will
452 add a static instance of its factory class.
454 It can also be used to change the order of a factory already in the list,
455 bringing it to the front. This isn't a thread safe operation
456 so can't be done when other threads are running that will be using the list.
457 The list does not take ownership of the factory.
462 Removes this class factory from the list returned by GetFirst() and GetNext().
464 Removing from the list isn't a thread safe operation so can't be done when
465 other threads are running that will be using the list.
466 The list does not own the factories, so removing a factory does not delete it.
474 @class wxArchiveNotifier
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.
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.
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.
491 @category{archive,streams}
493 @see @ref overview_archive_noseek, wxArchiveEntry, wxArchiveInputStream,
494 wxArchiveOutputStream
496 class wxArchiveNotifier
500 This method must be overridden in your derived class.
502 void OnEntryUpdated(class wxArchiveEntry
& entry
);
508 @class wxArchiveIterator
510 An input iterator template class that can be used to transfer an archive's
511 catalogue to a container. It is only available if wxUSE_STL is set to 1
512 in setup.h, and the uses for it outlined below require a compiler which
513 supports member templates.
516 template class Arc, class T = typename Arc::entry_type*
517 class wxArchiveIterator
519 // this constructor creates an 'end of sequence' object
522 // template parameter 'Arc' should be the type of an archive input stream
523 wxArchiveIterator(Arc& arc) {
529 The first template parameter should be the type of archive input stream
530 (e.g. wxArchiveInputStream) and the second can either be a pointer to an entry
531 (e.g. wxArchiveEntry*), or a string/pointer pair (e.g. std::pairwxString,
534 The @c wx/archive.h header defines the following typedefs:
537 typedef wxArchiveIterator<wxArchiveInputStream> wxArchiveIter;
539 typedef wxArchiveIterator<wxArchiveInputStream,
540 std::pair<wxString, wxArchiveEntry*> > wxArchivePairIter;
543 The header for any implementation of this interface should define similar
544 typedefs for its types, for example in @c wx/zipstrm.h there is:
547 typedef wxArchiveIterator<wxZipInputStream> wxZipIter;
549 typedef wxArchiveIterator<wxZipInputStream,
550 std::pair<wxString, wxZipEntry*> > wxZipPairIter;
553 Transferring the catalogue of an archive @e arc to a vector @e cat,
554 can then be done something like this:
557 std::vector<wxArchiveEntry*> cat((wxArchiveIter)arc, wxArchiveIter());
560 When the iterator is dereferenced, it gives away ownership of an entry
561 object. So in the above example, when you have finished with @e cat
562 you must delete the pointers it contains.
564 If you have smart pointers with normal copy semantics (i.e. not auto_ptr
565 or wxScopedPtr), then you can create an iterator which uses them instead.
567 For example, with a smart pointer class for zip entries @e ZipEntryPtr:
570 typedef std::vector<ZipEntryPtr> ZipCatalog;
571 typedef wxArchiveIterator<wxZipInputStream, ZipEntryPtr> ZipIter;
572 ZipCatalog cat((ZipIter)zip, ZipIter());
575 Iterators that return std::pair objects can be used to populate a std::multimap,
576 to allow entries to be looked up by name.
577 The string is initialised using the wxArchiveEntry object's
578 wxArchiveEntry::GetInternalName function.
581 typedef std::multimap<wxString, wxZipEntry*> ZipCatalog;
582 ZipCatalog cat((wxZipPairIter)zip, wxZipPairIter());
585 Note that this iterator also gives away ownership of an entry
586 object each time it is dereferenced. So in the above example, when
587 you have finished with @e cat you must delete the pointers it contains.
589 Or if you have them, a pair containing a smart pointer can be used
590 (again @e ZipEntryPtr), no worries about ownership:
593 typedef std::multimap<wxString, ZipEntryPtr> ZipCatalog;
594 typedef wxArchiveIterator<wxZipInputStream,
595 std::pair<wxString, ZipEntryPtr> > ZipPairIter;
596 ZipCatalog cat((ZipPairIter)zip, ZipPairIter());
600 @category{archive,streams}
602 @see wxArchiveEntry, wxArchiveInputStream, wxArchiveOutputStream
604 class wxArchiveIterator
613 Construct the iterator that returns all the entries in the archive input
616 wxArchiveIterator(Arc
& arc
);
619 Returns an entry object from the archive input stream, giving away
622 const T
operator*() const;
626 Position the input iterator at the next entry in the archive input stream.
628 wxArchiveIterator
operator++();
629 wxArchiveIterator
operator++(int);