docs/latex/wx/archive.tex

   1 %
   2 % automatically generated by HelpGen $Revision$ from
   3 % wx/archive.h at 16/Sep/04 12:19:29
   4 %
   5
   6 \section{\class{wxArchiveClassFactory}}\label{wxarchiveclassfactory}
   7
   8 Allows the creation of streams to handle archive formats such
   9 as zip and tar.
  10
  11 For example, given a filename you can search for a factory that will
  12 handle it and create a stream to read it:
  13
  14 \begin{verbatim}
  15     factory = wxArchiveClassFactory::Find(filename, wxSTREAM_FILEEXT);
  16     if (factory)
  17         stream = factory->NewStream(new wxFFileInputStream(filename));
  18
  19 \end{verbatim}
  20
  21 \helpref{Find()}{wxarchiveclassfactoryfind} can also search
  22 for a factory by MIME type or wxFileSystem protocol.
  23 The available factories can be enumerated
  24 using \helpref{GetFirst() and GetNext()}{wxarchiveclassfactorygetfirst}.
  25
  26 \wxheading{Derived from}
  27
  28 \helpref{wxObject}{wxobject}
  29
  30 \wxheading{Include files}
  31
  32 <wx/archive.h>
  33
  34 \wxheading{Library}
  35
  36 \helpref{wxBase}{librarieslist}
  37
  38 \wxheading{Data structures}
  39
  40 \begin{verbatim}
  41 enum wxStreamProtocolType
  42 {
  43     wxSTREAM_PROTOCOL,  // wxFileSystem protocol (should be only one)
  44     wxSTREAM_MIMETYPE,  // MIME types the stream handles
  45     wxSTREAM_ENCODING,  // Not used for archives
  46     wxSTREAM_FILEEXT    // File extensions the stream handles
  47 };
  48
  49 \end{verbatim}
  50
  51 \wxheading{See also}
  52
  53 \helpref{Archive formats such as zip}{wxarc}\\
  54 \helpref{Generic archive programming}{wxarcgeneric}\\
  55 \helpref{wxArchiveEntry}{wxarchiveentry}\\
  56 \helpref{wxArchiveInputStream}{wxarchiveinputstream}\\
  57 \helpref{wxArchiveOutputStream}{wxarchiveoutputstream}\\
  58 \helpref{wxFilterClassFactory}{wxfilterclassfactory}
  59
  60 \latexignore{\rtfignore{\wxheading{Members}}}
  61
  62
  63 \membersection{wxArchiveClassFactory::Get/SetConv}\label{wxarchiveclassfactoryconv}
  64
  65 \constfunc{wxMBConv\&}{GetConv}{\void}
  66
  67 \func{void}{SetConv}{\param{wxMBConv\& }{conv}}
  68
  69 The \helpref{wxMBConv}{wxmbconv} object that the created streams
  70 will use when translating meta-data. The initial default, set by the
  71 constructor, is wxConvLocal.
  72
  73
  74 \membersection{wxArchiveClassFactory::CanHandle}\label{wxarchiveclassfactorycanhandle}
  75
  76 \constfunc{bool}{CanHandle}{\param{const wxChar* }{protocol}, \param{wxStreamProtocolType }{type = wxSTREAM\_PROTOCOL}}
  77
  78 Returns true if this factory can handle the given protocol, MIME type
  79 or file extension.
  80
  81 When using wxSTREAM\_FILEEXT for the second parameter, the first parameter
  82 can be a complete filename rather than just an extension.
  83
  84
  85 \membersection{wxArchiveClassFactory::Find}\label{wxarchiveclassfactoryfind}
  86
  87 \func{static const wxArchiveClassFactory*}{Find}{\param{const wxChar* }{protocol}, \param{wxStreamProtocolType }{type = wxSTREAM\_PROTOCOL}}
  88
  89 A static member that finds a factory that can handle a given protocol, MIME
  90 type or file extension.  Returns a pointer to the class factory if found, or
  91 NULL otherwise. It does not give away ownership of the factory.
  92
  93 When using wxSTREAM\_FILEEXT for the second parameter, the first parameter
  94 can be a complete filename rather than just an extension.
  95
  96
  97 \membersection{wxArchiveClassFactory::GetFirst/GetNext}\label{wxarchiveclassfactorygetfirst}
  98
  99 \func{static const wxArchiveClassFactory*}{GetFirst}{\void}
 100
 101 \constfunc{const wxArchiveClassFactory*}{GetNext}{\void}
 102
 103 GetFirst and GetNext can be used to enumerate the available factories.
 104
 105 For example, to list them:
 106
 107 \begin{verbatim}
 108     wxString list;
 109     const wxArchiveClassFactory *factory = wxArchiveClassFactory::GetFirst();
 110
 111     while (factory) {
 112         list << factory->GetProtocol() << _T("\n");
 113         factory = factory->GetNext();
 114     }
 115
 116 \end{verbatim}
 117
 118 GetFirst()/GetNext() return a pointer to a factory or NULL if no more
 119 are available. They do not give away ownership of the factory.
 120
 121
 122 \membersection{wxArchiveClassFactory::GetInternalName}\label{wxarchiveclassfactorygetinternalname}
 123
 124 \constfunc{wxString}{GetInternalName}{\param{const wxString\& }{name}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 125
 126 Calls the static GetInternalName() function for the archive entry type,
 127 for example
 128  \helpref{wxZipEntry::GetInternalName()}{wxzipentrygetinternalname}.
 129
 130
 131 \membersection{wxArchiveClassFactory::GetProtocol}\label{wxarchiveclassfactorygetprotocol}
 132
 133 \constfunc{wxString}{GetProtocol}{\void}
 134
 135 Returns the wxFileSystem protocol supported by this factory. Equivalent
 136 to wxString(*GetProtcols()).
 137
 138
 139 \membersection{wxArchiveClassFactory::GetProtocols}\label{wxarchiveclassfactorygetprotocols}
 140
 141 \constfunc{const wxChar * const*}{GetProtocols}{\param{wxStreamProtocolType }{type = wxSTREAM\_PROTOCOL}}
 142
 143 Returns the protocols, MIME types or file extensions supported by this
 144 factory, as an array of null terminated strings. It does not give away
 145 ownership of the array or strings.
 146
 147 For example, to list the file extensions a factory supports:
 148
 149 \begin{verbatim}
 150     wxString list;
 151     const wxChar *const *p;
 152
 153     for (p = factory->GetProtocols(wxSTREAM_FILEEXT); *p; p++)
 154         list << *p << _T("\n");
 155
 156 \end{verbatim}
 157
 158
 159 \membersection{wxArchiveClassFactory::NewEntry}\label{wxarchiveclassfactorynewentry}
 160
 161 \constfunc{wxArchiveEntry*}{NewEntry}{\void}
 162
 163 Create a new \helpref{wxArchiveEntry}{wxarchiveentry} object of the
 164 appropriate type.
 165
 166
 167 \membersection{wxArchiveClassFactory::NewStream}\label{wxarchiveclassfactorynewstream}
 168
 169 \constfunc{wxArchiveInputStream*}{NewStream}{\param{wxInputStream\& }{stream}}
 170
 171 \constfunc{wxArchiveOutputStream*}{NewStream}{\param{wxOutputStream\& }{stream}}
 172
 173 \constfunc{wxArchiveInputStream*}{NewStream}{\param{wxInputStream* }{stream}}
 174
 175 \constfunc{wxArchiveOutputStream*}{NewStream}{\param{wxOutputStream* }{stream}}
 176
 177 Create a new input or output stream to read or write an archive.
 178
 179 If the parent stream is passed as a pointer then the new archive stream
 180 takes ownership of it. If it is passed by reference then it does not.
 181
 182
 183 \membersection{wxArchiveClassFactory::PushFront}\label{wxarchiveclassfactorypushfront}
 184
 185 \func{void}{PushFront}{\void}
 186
 187 Adds this class factory to the list returned
 188 by \helpref{GetFirst()/GetNext()}{wxarchiveclassfactorygetfirst}.
 189
 190 It is not necessary to do this to use the archive streams. It is usually
 191 used when implementing streams, typically the implementation will
 192 add a static instance of its factory class.
 193
 194 It can also be used to change the order of a factory already in the list,
 195 bringing it to the front. This isn't a thread safe operation
 196 so can't be done when other threads are running that will be using the list.
 197
 198 The list does not take ownership of the factory.
 199
 200
 201 \membersection{wxArchiveClassFactory::Remove}\label{wxarchiveclassfactoryremove}
 202
 203 \func{void}{Remove}{\void}
 204
 205 Removes this class factory from the list returned
 206 by \helpref{GetFirst()/GetNext()}{wxarchiveclassfactorygetfirst}.
 207
 208 Removing from the list isn't a thread safe operation
 209 so can't be done when other threads are running that will be using the list.
 210
 211 The list does not own the factories, so removing a factory does not delete it.
 212
 213
 214 %
 215 % automatically generated by HelpGen $Revision$ from
 216 % wx/archive.h at 16/Sep/04 12:19:29
 217 %
 218
 219 \section{\class{wxArchiveEntry}}\label{wxarchiveentry}
 220
 221 An abstract base class which serves as a common interface to
 222 archive entry classes such as \helpref{wxZipEntry}{wxzipentry}.
 223 These hold the meta-data (filename, timestamp, etc.), for entries
 224 in archive files such as zips and tars.
 225
 226 \wxheading{Derived from}
 227
 228 \helpref{wxObject}{wxobject}
 229
 230 \wxheading{Include files}
 231
 232 <wx/archive.h>
 233
 234 \wxheading{Library}
 235
 236 \helpref{wxBase}{librarieslist}
 237
 238 \wxheading{See also}
 239
 240 \helpref{Archive formats such as zip}{wxarc}\\
 241 \helpref{Generic archive programming}{wxarcgeneric}\\
 242 \helpref{wxArchiveInputStream}{wxarchiveinputstream}\\
 243 \helpref{wxArchiveOutputStream}{wxarchiveoutputstream}\\
 244 \helpref{wxArchiveNotifier}{wxarchivenotifier}
 245
 246 \wxheading{Non-seekable streams}
 247
 248 This information applies only when reading archives from non-seekable
 249 streams. When the stream is
 250 seekable \helpref{GetNextEntry()}{wxarchiveinputstreamgetnextentry}
 251 returns a fully populated \helpref{wxArchiveEntry}{wxarchiveentry}.
 252 See '\helpref{Archives on non-seekable streams}{wxarcnoseek}' for
 253 more information.
 254
 255 For generic programming, when the worst case must be assumed, you can
 256 rely on all the fields of wxArchiveEntry being fully populated when
 257 GetNextEntry() returns, with the the following exceptions:
 258
 259 \begin{twocollist}\twocolwidtha{3cm}
 260 \twocolitem{\helpref{GetSize()}{wxarchiveentrysize}}{Guaranteed to be
 261 available after the entry has been read to \helpref{Eof()}{wxinputstreameof},
 262 or \helpref{CloseEntry()}{wxarchiveinputstreamcloseentry} has been called}
 263 \twocolitem{\helpref{IsReadOnly()}{wxarchiveentryisreadonly}}{Guaranteed to
 264 be available after the end of the archive has been reached, i.e. after
 265 GetNextEntry() returns NULL and Eof() is true}
 266 \end{twocollist}
 267
 268
 269 \latexignore{\rtfignore{\wxheading{Members}}}
 270
 271
 272 \membersection{wxArchiveEntry::Clone}\label{wxarchiveentryclone}
 273
 274 \constfunc{wxArchiveEntry*}{Clone}{\void}
 275
 276 Returns a copy of this entry object.
 277
 278
 279 \membersection{wxArchiveEntry::Get/SetDateTime}\label{wxarchiveentrydatetime}
 280
 281 \constfunc{wxDateTime}{GetDateTime}{\void}
 282
 283 \func{void}{SetDateTime}{\param{const wxDateTime\& }{dt}}
 284
 285 The entry's timestamp.
 286
 287
 288 \membersection{wxArchiveEntry::GetInternalFormat}\label{wxarchiveentrygetinternalformat}
 289
 290 \constfunc{wxPathFormat}{GetInternalFormat}{\void}
 291
 292 Returns the path format used internally within the archive to store
 293 filenames.
 294
 295
 296 \membersection{wxArchiveEntry::GetInternalName}\label{wxarchiveentrygetinternalname}
 297
 298 \constfunc{wxString}{GetInternalName}{\void}
 299
 300 Returns the entry's filename in the internal format used within the
 301 archive. The name can include directory components, i.e. it can be a
 302 full path.
 303
 304 The names of directory entries are returned without any trailing path
 305 separator. This gives a canonical name that can be used in comparisons.
 306
 307 \wxheading{See also}
 308
 309 \helpref{Looking up an archive entry by name}{wxarcbyname}
 310
 311
 312 \membersection{wxArchiveEntry::Get/SetName}\label{wxarchiveentryname}
 313
 314 \constfunc{wxString}{GetName}{\param{wxPathFormat }{format = wxPATH\_NATIVE}}
 315
 316 \func{void}{SetName}{\param{const wxString\& }{name}, \param{wxPathFormat }{format = wxPATH\_NATIVE}}
 317
 318 The entry's name, by default in the native format. The name can include
 319 directory components, i.e. it can be a full path.
 320
 321 If this is a directory entry, (i.e. if \helpref{IsDir()}{wxarchiveentryisdir}
 322 is true) then GetName() returns the name with a trailing path separator.
 323
 324 Similarly, setting a name with a trailing path separator sets IsDir().
 325
 326
 327 \membersection{wxArchiveEntry::GetOffset}\label{wxarchiveentrygetoffset}
 328
 329 \constfunc{off\_t}{GetOffset}{\void}
 330
 331 Returns a numeric value unique to the entry within the archive.
 332
 333
 334 \membersection{wxArchiveEntry::Get/SetSize}\label{wxarchiveentrysize}
 335
 336 \constfunc{off\_t}{GetSize}{\void}
 337
 338 \func{void}{SetSize}{\param{off\_t }{size}}
 339
 340 The size of the entry's data in bytes.
 341
 342
 343 \membersection{wxArchiveEntry::IsDir/SetIsDir}\label{wxarchiveentryisdir}
 344
 345 \constfunc{bool}{IsDir}{\void}
 346
 347 \func{void}{SetIsDir}{\param{bool }{isDir = true}}
 348
 349 True if this is a directory entry.
 350
 351 Directory entries are entries with no data, which are used to store
 352 the meta-data of directories. They also make it possible for completely
 353 empty directories to be stored.
 354
 355 The names of entries within an archive can be complete paths, and
 356 unarchivers typically create whatever directories are necessary as they
 357 restore files, even if the archive contains no explicit directory entries.
 358
 359
 360 \membersection{wxArchiveEntry::IsReadOnly/SetIsReadOnly}\label{wxarchiveentryisreadonly}
 361
 362 \constfunc{bool}{IsReadOnly}{\void}
 363
 364 \func{void}{SetIsReadOnly}{\param{bool }{isReadOnly = true}}
 365
 366 True if the entry is a read-only file.
 367
 368
 369 \membersection{wxArchiveEntry::Set/UnsetNotifier}\label{wxarchiveentrynotifier}
 370
 371 \func{void}{SetNotifier}{\param{wxArchiveNotifier\& }{notifier}}
 372
 373 \func{void}{UnsetNotifier}{\void}
 374
 375 Sets the \helpref{notifier}{wxarchivenotifier} for this entry.
 376 Whenever the \helpref{wxArchiveInputStream}{wxarchiveinputstream} updates
 377 this entry, it will then invoke the associated
 378 notifier's \helpref{OnEntryUpdated}{wxarchivenotifieronentryupdated}
 379 method.
 380
 381 Setting a notifier is not usually necessary. It is used to handle
 382 certain cases when modifying an archive in a pipeline (i.e. between
 383 non-seekable streams).
 384
 385 \wxheading{See also}
 386
 387 \helpref{Archives on non-seekable streams}{wxarcnoseek}\\
 388 \helpref{wxArchiveNotifier}{wxarchivenotifier}
 389
 390
 391 %
 392 % automatically generated by HelpGen $Revision$ from
 393 % wx/archive.h at 16/Sep/04 12:19:29
 394 %
 395
 396 \section{\class{wxArchiveInputStream}}\label{wxarchiveinputstream}
 397
 398 An abstract base class which serves as a common interface to
 399 archive input streams such as \helpref{wxZipInputStream}{wxzipinputstream}.
 400
 401 \helpref{GetNextEntry()}{wxarchiveinputstreamgetnextentry} returns an
 402  \helpref{wxArchiveEntry}{wxarchiveentry} object containing the meta-data
 403 for the next entry in the archive (and gives away ownership). Reading from
 404 the wxArchiveInputStream then returns the entry's data. Eof() becomes true
 405 after an attempt has been made to read past the end of the entry's data.
 406 When there are no more entries, GetNextEntry() returns NULL and sets Eof().
 407
 408 \wxheading{Derived from}
 409
 410 \helpref{wxFilterInputStream}{wxfilterinputstream}
 411
 412 \wxheading{Include files}
 413
 414 <wx/archive.h>
 415
 416 \wxheading{Library}
 417
 418 \helpref{wxBase}{librarieslist}
 419
 420 \wxheading{Data structures}
 421 \begin{verbatim}
 422 typedef wxArchiveEntry entry_type
 423 \end{verbatim}
 424
 425 \wxheading{See also}
 426
 427 \helpref{Archive formats such as zip}{wxarc}\\
 428 \helpref{wxArchiveEntry}{wxarchiveentry}\\
 429 \helpref{wxArchiveOutputStream}{wxarchiveoutputstream}
 430
 431 \latexignore{\rtfignore{\wxheading{Members}}}
 432
 433
 434 \membersection{wxArchiveInputStream::CloseEntry}\label{wxarchiveinputstreamcloseentry}
 435
 436 \func{bool}{CloseEntry}{\void}
 437
 438 Closes the current entry. On a non-seekable stream reads to the end of
 439 the current entry first.
 440
 441
 442 \membersection{wxArchiveInputStream::GetNextEntry}\label{wxarchiveinputstreamgetnextentry}
 443
 444 \func{wxArchiveEntry*}{GetNextEntry}{\void}
 445
 446 Closes the current entry if one is open, then reads the meta-data for
 447 the next entry and returns it in a \helpref{wxArchiveEntry}{wxarchiveentry}
 448 object, giving away ownership. Reading this wxArchiveInputStream then
 449 returns the entry's data.
 450
 451
 452 \membersection{wxArchiveInputStream::OpenEntry}\label{wxarchiveinputstreamopenentry}
 453
 454 \func{bool}{OpenEntry}{\param{wxArchiveEntry\& }{entry}}
 455
 456 Closes the current entry if one is open, then opens the entry specified
 457 by the \helpref{wxArchiveEntry}{wxarchiveentry} object.
 458
 459 {\it entry} must be from the same archive file that this
 460 wxArchiveInputStream is reading, and it must be reading it from a
 461 seekable stream.
 462
 463 \wxheading{See also}
 464
 465 \helpref{Looking up an archive entry by name}{wxarcbyname}
 466
 467
 468 %
 469 % automatically generated by HelpGen $Revision$ from
 470 % wx/archive.h at 16/Sep/04 12:19:29
 471 %
 472
 473 \section{\class{wxArchiveIterator}}\label{wxarchiveiterator}
 474
 475 An input iterator template class that can be used to transfer an archive's
 476 catalogue to a container. It is only available if wxUSE\_STL is set to 1
 477 in setup.h, and the uses for it outlined below require a compiler which
 478 supports member templates.
 479
 480 \begin{verbatim}
 481 template <class Arc, class T = typename Arc::entry_type*>
 482 class wxArchiveIterator
 483 {
 484     // this constructor creates an 'end of sequence' object
 485     wxArchiveIterator();
 486
 487     // template parameter 'Arc' should be the type of an archive input stream
 488     wxArchiveIterator(Arc& arc) {
 489
 490     /* ... */
 491 };
 492
 493 \end{verbatim}
 494
 495 The first template parameter should be the type of archive input stream
 496 (e.g. \helpref{wxArchiveInputStream}{wxarchiveinputstream}) and the
 497 second can either be a pointer to an entry
 498 (e.g. \helpref{wxArchiveEntry}{wxarchiveentry}*), or a string/pointer pair
 499 (e.g. std::pair<wxString, wxArchiveEntry*>).
 500
 501 The {\tt <wx/archive.h>} header defines the following typedefs:
 502
 503 \begin{verbatim}
 504     typedef wxArchiveIterator<wxArchiveInputStream> wxArchiveIter;
 505
 506     typedef wxArchiveIterator<wxArchiveInputStream,
 507              std::pair<wxString, wxArchiveEntry*> > wxArchivePairIter;
 508
 509 \end{verbatim}
 510
 511 The header for any implementation of this interface should define similar
 512 typedefs for its types, for example in {\tt <wx/zipstrm.h>} there is:
 513
 514 \begin{verbatim}
 515     typedef wxArchiveIterator<wxZipInputStream> wxZipIter;
 516
 517     typedef wxArchiveIterator<wxZipInputStream,
 518              std::pair<wxString, wxZipEntry*> > wxZipPairIter;
 519
 520 \end{verbatim}
 521
 522 Transferring the catalogue of an archive {\it arc} to a vector {\it cat},
 523 can then be done something like this:
 524
 525 \begin{verbatim}
 526     std::vector<wxArchiveEntry*> cat((wxArchiveIter)arc, wxArchiveIter());
 527
 528 \end{verbatim}
 529
 530 When the iterator is dereferenced, it gives away ownership of an entry
 531 object. So in the above example, when you have finished with {\it cat}
 532 you must delete the pointers it contains.
 533
 534 If you have smart pointers with normal copy semantics (i.e. not auto\_ptr
 535 or \helpref{wxScopedPtr}{wxscopedptr}), then you can create an iterator
 536 which uses them instead.  For example, with a smart pointer class for
 537 zip entries {\it ZipEntryPtr}:
 538
 539 \begin{verbatim}
 540     typedef std::vector<ZipEntryPtr> ZipCatalog;
 541     typedef wxArchiveIterator<wxZipInputStream, ZipEntryPtr> ZipIter;
 542     ZipCatalog cat((ZipIter)zip, ZipIter());
 543
 544 \end{verbatim}
 545
 546 Iterators that return std::pair objects can be used to
 547 populate a std::multimap, to allow entries to be looked
 548 up by name. The string is initialised using the wxArchiveEntry object's
 549  \helpref{GetInternalName()}{wxarchiveentrygetinternalname} function.
 550
 551 \begin{verbatim}
 552     typedef std::multimap<wxString, wxZipEntry*> ZipCatalog;
 553     ZipCatalog cat((wxZipPairIter)zip, wxZipPairIter());
 554
 555 \end{verbatim}
 556
 557 Note that this iterator also gives away ownership of an entry
 558 object each time it is dereferenced. So in the above example, when
 559 you have finished with {\it cat} you must delete the pointers it contains.
 560
 561 Or if you have them, a pair containing a smart pointer can be used
 562 (again {\it ZipEntryPtr}), no worries about ownership:
 563
 564 \begin{verbatim}
 565     typedef std::multimap<wxString, ZipEntryPtr> ZipCatalog;
 566     typedef wxArchiveIterator<wxZipInputStream,
 567                 std::pair<wxString, ZipEntryPtr> > ZipPairIter;
 568     ZipCatalog cat((ZipPairIter)zip, ZipPairIter());
 569
 570 \end{verbatim}
 571
 572 \wxheading{Derived from}
 573
 574 No base class
 575
 576 \wxheading{Include files}
 577
 578 <wx/archive.h>
 579
 580 \wxheading{See also}
 581
 582 \helpref{wxArchiveEntry}{wxarchiveentry}\\
 583 \helpref{wxArchiveInputStream}{wxarchiveinputstream}\\
 584 \helpref{wxArchiveOutputStream}{wxarchiveoutputstream}
 585
 586 \wxheading{Data structures}
 587 \begin{verbatim}
 588 typedef std::input_iterator_tag iterator_category
 589 typedef T value_type
 590 typedef ptrdiff_t difference_type
 591 typedef T* pointer
 592 typedef T& reference
 593 \end{verbatim}
 594
 595 \latexignore{\rtfignore{\wxheading{Members}}}
 596
 597
 598 \membersection{wxArchiveIterator::wxArchiveIterator}\label{wxarchiveiteratorwxarchiveiterator}
 599
 600 \func{}{wxArchiveIterator}{\void}
 601
 602 Construct an 'end of sequence' instance.
 603
 604 \func{}{wxArchiveIterator}{\param{Arc\& }{arc}}
 605
 606 Construct iterator that returns all the entries in the archive input
 607 stream {\it arc}.
 608
 609
 610 \membersection{wxArchiveIterator::operator*}\label{wxarchiveiteratoroperatorstar}
 611
 612 \constfunc{const T\&}{operator*}{\void}
 613
 614 Returns an entry object from the archive input stream, giving away
 615 ownership.
 616
 617
 618 \membersection{wxArchiveIterator::operator++}\label{wxarchiveiteratoroperatorincrement}
 619
 620 \func{wxArchiveIterator\&}{operator++}{\void}
 621
 622 \func{wxArchiveIterator\&}{operator++}{\param{int}{}}
 623
 624 Position the input iterator at the next entry in the archive input stream.
 625
 626
 627 %
 628 % automatically generated by HelpGen $Revision$ from
 629 % wx/archive.h at 16/Sep/04 12:19:29
 630 %
 631
 632 \section{\class{wxArchiveNotifier}}\label{wxarchivenotifier}
 633
 634 If you need to know when a
 635  \helpref{wxArchiveInputStream}{wxarchiveinputstream} updates a
 636  \helpref{wxArchiveEntry}{wxarchiveentry} object, you can create
 637 a notifier by deriving from this abstract base class, overriding
 638  \helpref{OnEntryUpdated()}{wxarchivenotifieronentryupdated}.  An instance
 639 of your notifier class can then be assigned to the wxArchiveEntry object
 640 using \helpref{wxArchiveEntry::SetNotifier()}{wxarchiveentrynotifier}.
 641 Your OnEntryUpdated() method will then be invoked whenever the input
 642 stream updates the entry.
 643
 644 Setting a notifier is not usually necessary. It is used to handle
 645 certain cases when modifying an archive in a pipeline (i.e. between
 646 non-seekable streams).
 647 See \helpref{Archives on non-seekable streams}{wxarcnoseek}.
 648
 649 \wxheading{Derived from}
 650
 651 No base class
 652
 653 \wxheading{Include files}
 654
 655 <wx/archive.h>
 656
 657 \wxheading{Library}
 658
 659 \helpref{wxBase}{librarieslist}
 660
 661 \wxheading{See also}
 662
 663 \helpref{Archives on non-seekable streams}{wxarcnoseek}\\
 664 \helpref{wxArchiveEntry}{wxarchiveentry}\\
 665 \helpref{wxArchiveInputStream}{wxarchiveinputstream}\\
 666 \helpref{wxArchiveOutputStream}{wxarchiveoutputstream}
 667
 668 \latexignore{\rtfignore{\wxheading{Members}}}
 669
 670
 671 \membersection{wxArchiveNotifier::OnEntryUpdated}\label{wxarchivenotifieronentryupdated}
 672
 673 \func{void}{OnEntryUpdated}{\param{class wxArchiveEntry\& }{entry}}
 674
 675 This method must be overridden in your derived class.
 676
 677
 678 %
 679 % automatically generated by HelpGen $Revision$ from
 680 % wx/archive.h at 16/Sep/04 12:19:29
 681 %
 682
 683 \section{\class{wxArchiveOutputStream}}\label{wxarchiveoutputstream}
 684
 685 An abstract base class which serves as a common interface to
 686 archive output streams such as \helpref{wxZipOutputStream}{wxzipoutputstream}.
 687
 688 \helpref{PutNextEntry()}{wxarchiveoutputstreamputnextentry} is used
 689 to create a new entry in the output archive, then the entry's data is
 690 written to the wxArchiveOutputStream.  Another call to PutNextEntry()
 691 closes the current entry and begins the next.
 692
 693 \wxheading{Derived from}
 694
 695 \helpref{wxFilterOutputStream}{wxfilteroutputstream}
 696
 697 \wxheading{Include files}
 698
 699 <wx/archive.h>
 700
 701 \wxheading{Library}
 702
 703 \helpref{wxBase}{librarieslist}
 704
 705 \wxheading{See also}
 706
 707 \helpref{Archive formats such as zip}{wxarc}\\
 708 \helpref{wxArchiveEntry}{wxarchiveentry}\\
 709 \helpref{wxArchiveInputStream}{wxarchiveinputstream}
 710
 711 \latexignore{\rtfignore{\wxheading{Members}}}
 712
 713
 714 \membersection{wxArchiveOutputStream::\destruct{wxArchiveOutputStream}}\label{wxarchiveoutputstreamdtor}
 715
 716 \func{}{\destruct{wxArchiveOutputStream}}{\void}
 717
 718 Calls \helpref{Close()}{wxarchiveoutputstreamclose} if it has not already
 719 been called.
 720
 721
 722 \membersection{wxArchiveOutputStream::Close}\label{wxarchiveoutputstreamclose}
 723
 724 \func{bool}{Close}{\void}
 725
 726 Closes the archive, returning true if it was successfully written.
 727 Called by the destructor if not called explicitly.
 728
 729
 730 \membersection{wxArchiveOutputStream::CloseEntry}\label{wxarchiveoutputstreamcloseentry}
 731
 732 \func{bool}{CloseEntry}{\void}
 733
 734 Close the current entry. It is called implicitly whenever another new
 735 entry is created with \helpref{CopyEntry()}{wxarchiveoutputstreamcopyentry}
 736 or \helpref{PutNextEntry()}{wxarchiveoutputstreamputnextentry}, or
 737 when the archive is closed.
 738
 739
 740 \membersection{wxArchiveOutputStream::CopyArchiveMetaData}\label{wxarchiveoutputstreamcopyarchivemetadata}
 741
 742 \func{bool}{CopyArchiveMetaData}{\param{wxArchiveInputStream\& }{stream}}
 743
 744 Some archive formats have additional meta-data that applies to the archive
 745 as a whole.  For example in the case of zip there is a comment, which
 746 is stored at the end of the zip file.  CopyArchiveMetaData() can be used
 747 to transfer such information when writing a modified copy of an archive.
 748
 749 Since the position of the meta-data can vary between the various archive
 750 formats, it is best to call CopyArchiveMetaData() before transferring
 751 the entries.  The \helpref{wxArchiveOutputStream}{wxarchiveoutputstream}
 752 will then hold on to the meta-data and write it at the correct point in
 753 the output file.
 754
 755 When the input archive is being read from a non-seekable stream, the
 756 meta-data may not be available when CopyArchiveMetaData() is called,
 757 in which case the two streams set up a link and transfer the data
 758 when it becomes available.
 759
 760
 761 \membersection{wxArchiveOutputStream::CopyEntry}\label{wxarchiveoutputstreamcopyentry}
 762
 763 \func{bool}{CopyEntry}{\param{wxArchiveEntry* }{entry}, \param{wxArchiveInputStream\& }{stream}}
 764
 765 Takes ownership of {\it entry} and uses it to create a new entry in the
 766 archive. {\it entry} is then opened in the input stream {\it stream}
 767 and its contents copied to this stream.
 768
 769 For archive types which compress entry data, CopyEntry() is likely to be
 770 much more efficient than transferring the data using Read() and Write()
 771 since it will copy them without decompressing and recompressing them.
 772
 773 {\it entry} must be from the same archive file that {\it stream} is
 774 accessing. For non-seekable streams, {\it entry} must also be the last
 775 thing read from {\it stream}.
 776
 777
 778 \membersection{wxArchiveOutputStream::PutNextDirEntry}\label{wxarchiveoutputstreamputnextdirentry}
 779
 780 \func{bool}{PutNextDirEntry}{\param{const wxString\& }{name}, \param{const wxDateTime\& }{dt = wxDateTime::Now()}}
 781
 782 Create a new directory entry
 783 (see \helpref{wxArchiveEntry::IsDir()}{wxarchiveentryisdir})
 784 with the given name and timestamp.
 785
 786 \helpref{PutNextEntry()}{wxarchiveoutputstreamputnextentry} can
 787 also be used to create directory entries, by supplying a name with
 788 a trailing path separator.
 789
 790
 791 \membersection{wxArchiveOutputStream::PutNextEntry}\label{wxarchiveoutputstreamputnextentry}
 792
 793 \func{bool}{PutNextEntry}{\param{wxArchiveEntry* }{entry}}
 794
 795 Takes ownership of {\it entry} and uses it to create a new entry in
 796 the archive. The entry's data can then be written by writing to this
 797 wxArchiveOutputStream.
 798
 799 \func{bool}{PutNextEntry}{\param{const wxString\& }{name}, \param{const wxDateTime\& }{dt = wxDateTime::Now()}, \param{off\_t }{size = wxInvalidOffset}}
 800
 801 Create a new entry with the given name, timestamp and size. The entry's
 802 data can then be written by writing to this wxArchiveOutputStream.
 803
 804