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