2 % automatically generated by HelpGen $Revision$ from
3 % wx/archive.h at 16/Sep/04 12:19:29
6 \section{\class{wxArchiveClassFactory
}}\label{wxarchiveclassfactory
}
8 An abstract base class which serves as a common interface to
9 archive class factories such as
\helpref{wxZipClassFactory
}{wxzipclassfactory
}.
11 For each supported archive type (such as zip) there is a class factory
12 derived from wxArchiveClassFactory, which allows archive objects to be
13 created in a generic way, without knowing the particular type of archive
16 \wxheading{Derived from
}
18 \helpref{wxObject
}{wxobject
}
20 \wxheading{Include files
}
26 \helpref{Archive formats such as zip
}{wxarc
}\\
27 \helpref{Generic archive programming
}{wxarcgeneric
}\\
28 \helpref{wxArchiveEntry
}{wxarchiveentry
}\\
29 \helpref{wxArchiveInputStream
}{wxarchiveinputstream
}\\
30 \helpref{wxArchiveOutputStream
}{wxarchiveoutputstream
}
32 \latexignore{\rtfignore{\wxheading{Members
}}}
35 \membersection{wxArchiveClassFactory::Get/SetConv
}\label{wxarchiveclassfactoryconv
}
37 \constfunc{wxMBConv\&
}{GetConv
}{\void}
39 \func{void
}{SetConv
}{\param{wxMBConv\&
}{conv
}}
41 The
\helpref{wxMBConv
}{wxmbconv
} object that the created streams
42 will use when translating meta-data. The initial default, set by the
43 constructor, is wxConvLocal.
46 \membersection{wxArchiveClassFactory::GetInternalName
}\label{wxarchiveclassfactorygetinternalname
}
48 \constfunc{wxString
}{GetInternalName
}{\param{const wxString\&
}{name
},
\param{wxPathFormat
}{format = wxPATH
\_NATIVE}}
50 Calls the static GetInternalName() function for the archive entry type,
52 \helpref{wxZipEntry::GetInternalName()
}{wxzipentrygetinternalname
}.
55 \membersection{wxArchiveClassFactory::NewEntry
}\label{wxarchiveclassfactorynewentry
}
57 \constfunc{wxArchiveEntry*
}{NewEntry
}{\void}
59 Create a new
\helpref{wxArchiveEntry
}{wxarchiveentry
} object of the
63 \membersection{wxArchiveClassFactory::NewStream
}\label{wxarchiveclassfactorynewstream
}
65 \constfunc{wxArchiveInputStream*
}{NewStream
}{\param{wxInputStream\&
}{stream
}}
67 \constfunc{wxArchiveOutputStream*
}{NewStream
}{\param{wxOutputStream\&
}{stream
}}
69 Create a new
\helpref{wxArchiveInputStream
}{wxarchiveinputstream
}
70 or
\helpref{wxArchiveOutputStream
}{wxarchiveoutputstream
} of the
75 % automatically generated by HelpGen $Revision$ from
76 % wx/archive.h at 16/Sep/04 12:19:29
79 \section{\class{wxArchiveEntry
}}\label{wxarchiveentry
}
81 An abstract base class which serves as a common interface to
82 archive entry classes such as
\helpref{wxZipEntry
}{wxzipentry
}.
83 These hold the meta-data (filename, timestamp, etc.), for entries
84 in archive files such as zips and tars.
86 \wxheading{Derived from
}
88 \helpref{wxObject
}{wxobject
}
90 \wxheading{Include files
}
96 \helpref{Archive formats such as zip
}{wxarc
}\\
97 \helpref{Generic archive programming
}{wxarcgeneric
}\\
98 \helpref{wxArchiveInputStream
}{wxarchiveinputstream
}\\
99 \helpref{wxArchiveOutputStream
}{wxarchiveoutputstream
}\\
100 \helpref{wxArchiveNotifier
}{wxarchivenotifier
}
102 \wxheading{Non-seekable streams
}
104 This information applies only when reading archives from non-seekable
105 streams. When the stream is
106 seekable
\helpref{GetNextEntry()
}{wxarchiveinputstreamgetnextentry
}
107 returns a fully populated
\helpref{wxArchiveEntry
}{wxarchiveentry
}.
108 See '
\helpref{Archives on non-seekable streams
}{wxarcnoseek
}' for
111 For generic programming, when the worst case must be assumed, you can
112 rely on all the fields of wxArchiveEntry being fully populated when
113 GetNextEntry() returns, with the the following exceptions:
115 \begin{twocollist
}\twocolwidtha{3cm
}
116 \twocolitem{\helpref{GetSize()
}{wxarchiveentrysize
}}{Guaranteed to be
117 available after the entry has been read to
\helpref{Eof()
}{wxinputstreameof
},
118 or
\helpref{CloseEntry()
}{wxarchiveinputstreamcloseentry
} has been called
}
119 \twocolitem{\helpref{IsReadOnly()
}{wxarchiveentryisreadonly
}}{Guaranteed to
120 be available after the end of the archive has been reached, i.e. after
121 GetNextEntry() returns NULL and Eof() is true
}
125 \latexignore{\rtfignore{\wxheading{Members
}}}
128 \membersection{wxArchiveEntry::Clone
}\label{wxarchiveentryclone
}
130 \constfunc{wxArchiveEntry*
}{Clone
}{\void}
132 Returns a copy of this entry object.
135 \membersection{wxArchiveEntry::Get/SetDateTime
}\label{wxarchiveentrydatetime
}
137 \constfunc{wxDateTime
}{GetDateTime
}{\void}
139 \func{void
}{SetDateTime
}{\param{const wxDateTime\&
}{dt
}}
141 The entry's timestamp.
144 \membersection{wxArchiveEntry::GetInternalFormat
}\label{wxarchiveentrygetinternalformat
}
146 \constfunc{wxPathFormat
}{GetInternalFormat
}{\void}
148 Returns the path format used internally within the archive to store
152 \membersection{wxArchiveEntry::GetInternalName
}\label{wxarchiveentrygetinternalname
}
154 \constfunc{wxString
}{GetInternalName
}{\void}
156 Returns the entry's filename in the internal format used within the
157 archive. The name can include directory components, i.e. it can be a
160 The names of directory entries are returned without any trailing path
161 separator. This gives a canonical name that can be used in comparisons.
165 \helpref{Looking up an archive entry by name
}{wxarcbyname
}
168 \membersection{wxArchiveEntry::Get/SetName
}\label{wxarchiveentryname
}
170 \constfunc{wxString
}{GetName
}{\param{wxPathFormat
}{format = wxPATH
\_NATIVE}}
172 \func{void
}{SetName
}{\param{const wxString\&
}{name
},
\param{wxPathFormat
}{format = wxPATH
\_NATIVE}}
174 The entry's name, by default in the native format. The name can include
175 directory components, i.e. it can be a full path.
177 If this is a directory entry, (i.e. if
\helpref{IsDir()
}{wxarchiveentryisdir
}
178 is true) then GetName() returns the name with a trailing path separator.
180 Similarly, setting a name with a trailing path separator sets IsDir().
183 \membersection{wxArchiveEntry::GetOffset
}\label{wxarchiveentrygetoffset
}
185 \constfunc{off
\_t}{GetOffset
}{\void}
187 Returns a numeric value unique to the entry within the archive.
190 \membersection{wxArchiveEntry::Get/SetSize
}\label{wxarchiveentrysize
}
192 \constfunc{off
\_t}{GetSize
}{\void}
194 \func{void
}{SetSize
}{\param{off
\_t }{size
}}
196 The size of the entry's data in bytes.
199 \membersection{wxArchiveEntry::IsDir/SetIsDir
}\label{wxarchiveentryisdir
}
201 \constfunc{bool
}{IsDir
}{\void}
203 \func{void
}{SetIsDir
}{\param{bool
}{isDir = true
}}
205 True if this is a directory entry.
207 Directory entries are entries with no data, which are used to store
208 the meta-data of directories. They also make it possible for completely
209 empty directories to be stored.
211 The names of entries within an archive can be complete paths, and
212 unarchivers typically create whatever directories are necessary as they
213 restore files, even if the archive contains no explicit directory entries.
216 \membersection{wxArchiveEntry::IsReadOnly/SetIsReadOnly
}\label{wxarchiveentryisreadonly
}
218 \constfunc{bool
}{IsReadOnly
}{\void}
220 \func{void
}{SetIsReadOnly
}{\param{bool
}{isReadOnly = true
}}
222 True if the entry is a read-only file.
225 \membersection{wxArchiveEntry::Set/UnsetNotifier
}\label{wxarchiveentrynotifier
}
227 \func{void
}{SetNotifier
}{\param{wxArchiveNotifier\&
}{notifier
}}
229 \func{void
}{UnsetNotifier
}{\void}
231 Sets the
\helpref{notifier
}{wxarchivenotifier
} for this entry.
232 Whenever the
\helpref{wxArchiveInputStream
}{wxarchiveinputstream
} updates
233 this entry, it will then invoke the associated
234 notifier's
\helpref{OnEntryUpdated
}{wxarchivenotifieronentryupdated
}
237 Setting a notifier is not usually necessary. It is used to handle
238 certain cases when modifying an archive in a pipeline (i.e. between
239 non-seekable streams).
243 \helpref{Archives on non-seekable streams
}{wxarcnoseek
}\\
244 \helpref{wxArchiveNotifier
}{wxarchivenotifier
}
248 % automatically generated by HelpGen $Revision$ from
249 % wx/archive.h at 16/Sep/04 12:19:29
252 \section{\class{wxArchiveInputStream
}}\label{wxarchiveinputstream
}
254 An abstract base class which serves as a common interface to
255 archive input streams such as
\helpref{wxZipInputStream
}{wxzipinputstream
}.
257 \helpref{GetNextEntry()
}{wxarchiveinputstreamgetnextentry
} returns an
258 \helpref{wxArchiveEntry
}{wxarchiveentry
} object containing the meta-data
259 for the next entry in the archive (and gives away ownership). Reading from
260 the wxArchiveInputStream then returns the entry's data. Eof() becomes true
261 after an attempt has been made to read past the end of the entry's data.
262 When there are no more entries, GetNextEntry() returns NULL and sets Eof().
264 \wxheading{Derived from
}
266 \helpref{wxFilterInputStream
}{wxfilterinputstream
}
268 \wxheading{Include files
}
272 \wxheading{Data structures
}
273 {\small \begin{verbatim
}
274 typedef wxArchiveEntry entry
\_type
279 \helpref{Archive formats such as zip
}{wxarc
}\\
280 \helpref{wxArchiveEntry
}{wxarchiveentry
}\\
281 \helpref{wxArchiveOutputStream
}{wxarchiveoutputstream
}
283 \latexignore{\rtfignore{\wxheading{Members
}}}
286 \membersection{wxArchiveInputStream::CloseEntry
}\label{wxarchiveinputstreamcloseentry
}
288 \func{bool
}{CloseEntry
}{\void}
290 Closes the current entry. On a non-seekable stream reads to the end of
291 the current entry first.
294 \membersection{wxArchiveInputStream::GetNextEntry
}\label{wxarchiveinputstreamgetnextentry
}
296 \func{wxArchiveEntry*
}{GetNextEntry
}{\void}
298 Closes the current entry if one is open, then reads the meta-data for
299 the next entry and returns it in a
\helpref{wxArchiveEntry
}{wxarchiveentry
}
300 object, giving away ownership. Reading this wxArchiveInputStream then
301 returns the entry's data.
304 \membersection{wxArchiveInputStream::OpenEntry
}\label{wxarchiveinputstreamopenentry
}
306 \func{bool
}{OpenEntry
}{\param{wxArchiveEntry\&
}{entry
}}
308 Closes the current entry if one is open, then opens the entry specified
309 by the
\helpref{wxArchiveEntry
}{wxarchiveentry
} object.
311 {\it entry
} must be from the same archive file that this
312 wxArchiveInputStream is reading, and it must be reading it from a
317 \helpref{Looking up an archive entry by name
}{wxarcbyname
}
321 % automatically generated by HelpGen $Revision$ from
322 % wx/archive.h at 16/Sep/04 12:19:29
325 \section{\class{wxArchiveIterator
}}\label{wxarchiveiterator
}
327 An input iterator template class that can be used to transfer an archive's
328 catalogue to a container. It is only available if wxUSE
\_STL is set to
1
329 in setup.h, and the uses for it outlined below require a compiler which
330 supports member templates.
333 template <class Arc, class T = typename Arc::entry_type*>
334 class wxArchiveIterator
336 // this constructor creates an 'end of sequence' object
339 // template parameter 'Arc' should be the type of an archive input stream
340 wxArchiveIterator(Arc& arc)
{
347 The first template parameter should be the type of archive input stream
348 (e.g.
\helpref{wxArchiveInputStream
}{wxarchiveinputstream
}) and the
349 second can either be a pointer to an entry
350 (e.g.
\helpref{wxArchiveEntry
}{wxarchiveentry
}*), or a string/pointer pair
351 (e.g. std::pair<wxString, wxArchiveEntry*>).
353 The
{\tt <wx/archive.h>
} header defines the following typedefs:
356 typedef wxArchiveIterator<wxArchiveInputStream> wxArchiveIter;
358 typedef wxArchiveIterator<wxArchiveInputStream,
359 std::pair<wxString, wxArchiveEntry*> > wxArchivePairIter;
363 The header for any implementation of this interface should define similar
364 typedefs for its types, for example in
{\tt <wx/zipstrm.h>
} there is:
367 typedef wxArchiveIterator<wxZipInputStream> wxZipIter;
369 typedef wxArchiveIterator<wxZipInputStream,
370 std::pair<wxString, wxZipEntry*> > wxZipPairIter;
374 Transferring the catalogue of an archive
{\it arc
} to a vector
{\it cat
},
375 can then be done something like this:
378 std::vector<wxArchiveEntry*> cat((wxArchiveIter)arc, wxArchiveIter());
382 When the iterator is dereferenced, it gives away ownership of an entry
383 object. So in the above example, when you have finished with
{\it cat
}
384 you must delete the pointers it contains.
386 If you have smart pointers with normal copy semantics (i.e. not auto
\_ptr
387 or
\helpref{wxScopedPtr
}{wxscopedptr
}), then you can create an iterator
388 which uses them instead. For example, with a smart pointer class for
389 zip entries
{\it ZipEntryPtr
}:
392 typedef std::vector<ZipEntryPtr> ZipCatalog;
393 typedef wxArchiveIterator<wxZipInputStream, ZipEntryPtr> ZipIter;
394 ZipCatalog cat((ZipIter)zip, ZipIter());
398 Iterators that return std::pair objects can be used to
399 populate a std::multimap, to allow entries to be looked
400 up by name. The string is initialised using the wxArchiveEntry object's
401 \helpref{GetInternalName()
}{wxarchiveentrygetinternalname
} function.
404 typedef std::multimap<wxString, wxZipEntry*> ZipCatalog;
405 ZipCatalog cat((wxZipPairIter)zip, wxZipPairIter());
409 Note that this iterator also gives away ownership of an entry
410 object each time it is dereferenced. So in the above example, when
411 you have finished with
{\it cat
} you must delete the pointers it contains.
413 Or if you have them, a pair containing a smart pointer can be used
414 (again
{\it ZipEntryPtr
}), no worries about ownership:
417 typedef std::multimap<wxString, ZipEntryPtr> ZipCatalog;
418 typedef wxArchiveIterator<wxZipInputStream,
419 std::pair<wxString, ZipEntryPtr> > ZipPairIter;
420 ZipCatalog cat((ZipPairIter)zip, ZipPairIter());
424 \wxheading{Derived from
}
428 \wxheading{Include files
}
434 \helpref{wxArchiveEntry
}{wxarchiveentry
}\\
435 \helpref{wxArchiveInputStream
}{wxarchiveinputstream
}\\
436 \helpref{wxArchiveOutputStream
}{wxarchiveoutputstream
}
438 \wxheading{Data structures
}
439 {\small \begin{verbatim
}
440 typedef std::input
\_iterator\_tag iterator
\_category
441 typedef T value
\_type
442 typedef ptrdiff
\_t difference
\_type
444 typedef T\& reference
447 \latexignore{\rtfignore{\wxheading{Members
}}}
450 \membersection{wxArchiveIterator::wxArchiveIterator
}\label{wxarchiveiteratorwxarchiveiterator
}
452 \func{}{wxArchiveIterator
}{\void}
454 Construct an 'end of sequence' instance.
456 \func{}{wxArchiveIterator
}{\param{Arc\&
}{arc
}}
458 Construct iterator that returns all the entries in the archive input
462 \membersection{wxArchiveIterator::operator*
}\label{wxarchiveiteratoroperatorunknown
}
464 \constfunc{const T\&
}{operator*
}{\void}
466 Returns an entry object from the archive input stream, giving away
470 \membersection{wxArchiveIterator::operator++
}\label{wxarchiveiteratoroperatorunknown
}
472 \func{wxArchiveIterator\&
}{operator++
}{\void}
474 \func{wxArchiveIterator\&
}{operator++
}{\param{int
}{}}
476 Position the input iterator at the next entry in the archive input stream.
480 % automatically generated by HelpGen $Revision$ from
481 % wx/archive.h at 16/Sep/04 12:19:29
484 \section{\class{wxArchiveNotifier
}}\label{wxarchivenotifier
}
486 If you need to know when a
487 \helpref{wxArchiveInputStream
}{wxarchiveinputstream
} updates a
488 \helpref{wxArchiveEntry
}{wxarchiveentry
} object, you can create
489 a notifier by deriving from this abstract base class, overriding
490 \helpref{OnEntryUpdated()
}{wxarchivenotifieronentryupdated
}. An instance
491 of your notifier class can then be assigned to the wxArchiveEntry object
492 using
\helpref{wxArchiveEntry::SetNotifier()
}{wxarchiveentrynotifier
}.
493 Your OnEntryUpdated() method will then be invoked whenever the input
494 stream updates the entry.
496 Setting a notifier is not usually necessary. It is used to handle
497 certain cases when modifying an archive in a pipeline (i.e. between
498 non-seekable streams).
499 See
\helpref{Archives on non-seekable streams
}{wxarcnoseek
}.
501 \wxheading{Derived from
}
505 \wxheading{Include files
}
511 \helpref{Archives on non-seekable streams
}{wxarcnoseek
}\\
512 \helpref{wxArchiveEntry
}{wxarchiveentry
}\\
513 \helpref{wxArchiveInputStream
}{wxarchiveinputstream
}\\
514 \helpref{wxArchiveOutputStream
}{wxarchiveoutputstream
}
516 \latexignore{\rtfignore{\wxheading{Members
}}}
519 \membersection{wxArchiveNotifier::OnEntryUpdated
}\label{wxarchivenotifieronentryupdated
}
521 \func{void
}{OnEntryUpdated
}{\param{class wxArchiveEntry\&
}{entry
}}
523 This method must be overridden in your derived class.
527 % automatically generated by HelpGen $Revision$ from
528 % wx/archive.h at 16/Sep/04 12:19:29
531 \section{\class{wxArchiveOutputStream
}}\label{wxarchiveoutputstream
}
533 An abstract base class which serves as a common interface to
534 archive output streams such as
\helpref{wxZipOutputStream
}{wxzipoutputstream
}.
536 \helpref{PutNextEntry()
}{wxarchiveoutputstreamputnextentry
} is used
537 to create a new entry in the output archive, then the entry's data is
538 written to the wxArchiveOutputStream. Another call to PutNextEntry()
539 closes the current entry and begins the next.
541 \wxheading{Derived from
}
543 \helpref{wxFilterOutputStream
}{wxfilteroutputstream
}
545 \wxheading{Include files
}
551 \helpref{Archive formats such as zip
}{wxarc
}\\
552 \helpref{wxArchiveEntry
}{wxarchiveentry
}\\
553 \helpref{wxArchiveInputStream
}{wxarchiveinputstream
}
555 \latexignore{\rtfignore{\wxheading{Members
}}}
558 \membersection{wxArchiveOutputStream::
\destruct{wxArchiveOutputStream
}}\label{wxarchiveoutputstreamdtor
}
560 \func{}{\destruct{wxArchiveOutputStream
}}{\void}
562 Calls
\helpref{Close()
}{wxarchiveoutputstreamclose
} if it has not already
566 \membersection{wxArchiveOutputStream::Close
}\label{wxarchiveoutputstreamclose
}
568 \func{bool
}{Close
}{\void}
570 Closes the archive, returning true if it was successfully written.
571 Called by the destructor if not called explicitly.
574 \membersection{wxArchiveOutputStream::CloseEntry
}\label{wxarchiveoutputstreamcloseentry
}
576 \func{bool
}{CloseEntry
}{\void}
578 Close the current entry. It is called implicitly whenever another new
579 entry is created with
\helpref{CopyEntry()
}{wxarchiveoutputstreamcopyentry
}
580 or
\helpref{PutNextEntry()
}{wxarchiveoutputstreamputnextentry
}, or
581 when the archive is closed.
584 \membersection{wxArchiveOutputStream::CopyArchiveMetaData
}\label{wxarchiveoutputstreamcopyarchivemetadata
}
586 \func{bool
}{CopyArchiveMetaData
}{\param{wxArchiveInputStream\&
}{stream
}}
588 Some archive formats have additional meta-data that applies to the archive
589 as a whole. For example in the case of zip there is a comment, which
590 is stored at the end of the zip file. CopyArchiveMetaData() can be used
591 to transfer such information when writing a modified copy of an archive.
593 Since the position of the meta-data can vary between the various archive
594 formats, it is best to call CopyArchiveMetaData() before transferring
595 the entries. The
\helpref{wxArchiveOutputStream
}{wxarchiveoutputstream
}
596 will then hold on to the meta-data and write it at the correct point in
599 When the input archive is being read from a non-seekable stream, the
600 meta-data may not be available when CopyArchiveMetaData() is called,
601 in which case the two streams set up a link and transfer the data
602 when it becomes available.
605 \membersection{wxArchiveOutputStream::CopyEntry
}\label{wxarchiveoutputstreamcopyentry
}
607 \func{bool
}{CopyEntry
}{\param{wxArchiveEntry*
}{entry
},
\param{wxArchiveInputStream\&
}{stream
}}
609 Takes ownership of
{\it entry
} and uses it to create a new entry in the
610 archive.
{\it entry
} is then opened in the input stream
{\it stream
}
611 and its contents copied to this stream.
613 For archive types which compress entry data, CopyEntry() is likely to be
614 much more efficient than transferring the data using Read() and Write()
615 since it will copy them without decompressing and recompressing them.
617 {\it entry
} must be from the same archive file that
{\it stream
} is
618 accessing. For non-seekable streams,
{\it entry
} must also be the last
619 thing read from
{\it stream
}.
622 \membersection{wxArchiveOutputStream::PutNextDirEntry
}\label{wxarchiveoutputstreamputnextdirentry
}
624 \func{bool
}{PutNextDirEntry
}{\param{const wxString\&
}{name
},
\param{const wxDateTime\&
}{dt = wxDateTime::Now()
}}
626 Create a new directory entry
627 (see
\helpref{wxArchiveEntry::IsDir()
}{wxarchiveentryisdir
})
628 with the given name and timestamp.
630 \helpref{PutNextEntry()
}{wxarchiveoutputstreamputnextentry
} can
631 also be used to create directory entries, by supplying a name with
632 a trailing path separator.
635 \membersection{wxArchiveOutputStream::PutNextEntry
}\label{wxarchiveoutputstreamputnextentry
}
637 \func{bool
}{PutNextEntry
}{\param{wxArchiveEntry*
}{entry
}}
639 Takes ownership of
{\it entry
} and uses it to create a new entry in
640 the archive. The entry's data can then be written by writing to this
641 wxArchiveOutputStream.
643 \func{bool
}{PutNextEntry
}{\param{const wxString\&
}{name
},
\param{const wxDateTime\&
}{dt = wxDateTime::Now()
},
\param{off
\_t }{size = wxInvalidOffset
}}
645 Create a new entry with the given name, timestamp and size. The entry's
646 data can then be written by writing to this wxArchiveOutputStream.