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