X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/880efa2a137ce3e3f39236d0dc85f5d2dacdda12..7447d53c35249d42128d6243c90998f03882859a:/docs/doxygen/overviews/archive.h?ds=sidebyside diff --git a/docs/doxygen/overviews/archive.h b/docs/doxygen/overviews/archive.h index 17874b6a78..6be6b783c3 100644 --- a/docs/doxygen/overviews/archive.h +++ b/docs/doxygen/overviews/archive.h @@ -3,15 +3,15 @@ // Purpose: topic overview // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** -@page overview_arc Archive Formats +@page overview_archive Archive Formats The archive classes handle archive formats such as zip, tar, rar and cab. -Currently wxZip and wxTar classes are included. +Currently wxZip, wxTar and wxZlib classes are included. For each archive type, there are the following classes (using zip here as an example): @@ -21,52 +21,52 @@ example): @li wxZipEntry: Holds meta-data for an entry (e.g. filename, timestamp, etc.) There are also abstract wxArchive classes that can be used to write code that -can handle any of the archive types, see @ref overview_arc_generic. +can handle any of the archive types, see @ref overview_archive_generic. Also see wxFileSystem for a higher level interface that can handle archive files in a generic way. The classes are designed to handle archives on both seekable streams such as disk files, or non-seekable streams such as pipes and sockets (see -@ref overview_arc_noseek). +@ref overview_archive_noseek). See also wxFileSystem. -@li @ref overview_arc_create -@li @ref overview_arc_extract -@li @ref overview_arc_modify -@li @ref overview_arc_byname -@li @ref overview_arc_generic -@li @ref overview_arc_noseek +@li @ref overview_archive_create +@li @ref overview_archive_extract +@li @ref overview_archive_modify +@li @ref overview_archive_byname +@li @ref overview_archive_generic +@li @ref overview_archive_noseek
-@section overview_arc_create Creating an Archive +@section overview_archive_create Creating an Archive Call wxArchiveOutputStream::PutNextEntry() to create each new entry in the archive, then write the entry's data. Another call to PutNextEntry() closes the current entry and begins the next. For example: @code -wxFFileOutputStream out(_T("test.zip")); +wxFFileOutputStream out(wxT("test.zip")); wxZipOutputStream zip(out); wxTextOutputStream txt(zip); wxString sep(wxFileName::GetPathSeparator()); -zip.PutNextEntry(_T("entry1.txt")); -txt << _T("Some text for entry1.txt\n"); +zip.PutNextEntry(wxT("entry1.txt")); +txt << wxT("Some text for entry1.txt\n"); -zip.PutNextEntry(_T("subdir") + sep + _T("entry2.txt")); -txt << _T("Some text for subdir/entry2.txt\n"); +zip.PutNextEntry(wxT("subdir") + sep + wxT("entry2.txt")); +txt << wxT("Some text for subdir/entry2.txt\n"); @endcode The name of each entry can be a full path, which makes it possible to store entries in subdirectories. -@section overview_arc_extract Extracting an Archive +@section overview_archive_extract Extracting an Archive wxArchiveInputStream::GetNextEntry() returns a pointer to entry object containing the meta-data for the next entry in the archive (and gives away @@ -80,7 +80,7 @@ When there are no more entries, GetNextEntry() returns @NULL and sets Eof(). @code auto_ptr entry; -wxFFileInputStream in(_T("test.zip")); +wxFFileInputStream in(wxT("test.zip")); wxZipInputStream zip(in); while (entry.reset(zip.GetNextEntry()), entry.get() != NULL) @@ -93,7 +93,7 @@ while (entry.reset(zip.GetNextEntry()), entry.get() != NULL) -@section overview_arc_modify Modifying an Archive +@section overview_archive_modify Modifying an Archive To modify an existing archive, write a new copy of the archive to a new file, making any necessary changes along the way and transferring any unchanged @@ -111,8 +111,8 @@ archive. wxTempFileOutputStream can be helpful to do this. For example to delete all entries matching the pattern "*.txt": @code -auto_ptr in(new wxFFileInputStream(_T("test.zip"))); -wxTempFileOutputStream out(_T("test.zip")); +auto_ptr in(new wxFFileInputStream(wxT("test.zip"))); +wxTempFileOutputStream out(wxT("test.zip")); wxZipInputStream inzip(*in); wxZipOutputStream outzip(out); @@ -125,7 +125,7 @@ outzip.CopyArchiveMetaData(inzip); // call CopyEntry for each entry except those matching the pattern while (entry.reset(inzip.GetNextEntry()), entry.get() != NULL) - if (!entry->GetName().Matches(_T("*.txt"))) + if (!entry->GetName().Matches(wxT("*.txt"))) if (!outzip.CopyEntry(entry.release(), inzip)) break; @@ -139,7 +139,7 @@ bool success = inzip.Eof() && outzip.Close() && out.Commit(); -@section overview_arc_byname Looking Up an Archive Entry by Name +@section overview_archive_byname Looking Up an Archive Entry by Name Also see wxFileSystem for a higher level interface that is more convenient for accessing archive entries by name. @@ -167,7 +167,7 @@ auto_ptr entry; wxString name = wxZipEntry::GetInternalName(localname); // open the zip -wxFFileInputStream in(_T("test.zip")); +wxFFileInputStream in(wxT("test.zip")); wxZipInputStream zip(in); // call GetNextEntry() until the required internal name is found @@ -195,7 +195,7 @@ wxZipEntry *entry; ZipCatalog cat; // open the zip -wxFFileInputStream in(_T("test.zip")); +wxFFileInputStream in(wxT("test.zip")); wxZipInputStream zip(in); // load the zip catalog @@ -222,7 +222,7 @@ stream on the same archive: @code // opening another entry without closing the first requires another // input stream for the same file -wxFFileInputStream in2(_T("test.zip")); +wxFFileInputStream in2(wxT("test.zip")); wxZipInputStream zip2(in2); if ((it = cat.find(wxZipEntry::GetInternalName(local2))) != cat.end()) zip2.OpenEntry(*it->second); @@ -230,7 +230,7 @@ if ((it = cat.find(wxZipEntry::GetInternalName(local2))) != cat.end()) -@section overview_arc_generic Generic Archive Programming +@section overview_archive_generic Generic Archive Programming Also see wxFileSystem for a higher level interface that can handle archive files in a generic way. @@ -311,14 +311,14 @@ if (in->IsOk()) } else { - wxLogError(_T("can't handle '%s'"), filename.c_str()); + wxLogError(wxT("can't handle '%s'"), filename.c_str()); } } @endcode -@section overview_arc_noseek Archives on Non-Seekable Streams +@section overview_archive_noseek Archives on Non-Seekable Streams In general, handling archives on non-seekable streams is done in the same way as for seekable streams, with a few caveats. @@ -331,7 +331,7 @@ For each archive type, there will also be other limitations which will depend on the order the entries' meta-data is stored within the archive. These are not too difficult to deal with, and are outlined below. -@subsection overview_arc_noseek_entrysize PutNextEntry and the Entry Size +@subsection overview_archive_noseek_entrysize PutNextEntry and the Entry Size When writing archives, some archive formats store the entry size before the entry's data (tar has this limitation, zip doesn't). In this case the entry's @@ -346,7 +346,7 @@ For generic programming, one way to handle this is to supply the size whenever it is known, and rely on the error message from the output stream when the operation is not supported. -@subsection overview_arc_noseek_weak GetNextEntry and the Weak Reference Mechanism +@subsection overview_archive_noseek_weak GetNextEntry and the Weak Reference Mechanism Some archive formats do not store all an entry's meta-data before the entry's data (zip is an example). In this case, when reading from a non-seekable @@ -361,7 +361,7 @@ attempts to update it if it is still around. The documentation for each archive entry type gives the details of what meta-data becomes available and when. For generic programming, when the worst case must be assumed, you can rely on all the fields of wxArchiveEntry being -fully populated when GetNextEntry() returns, with the the following exceptions: +fully populated when GetNextEntry() returns, with the following exceptions: @li wxArchiveEntry::GetSize(): Guaranteed to be available after the entry has been read to wxInputStream::Eof(), or wxArchiveInputStream::CloseEntry() @@ -375,7 +375,7 @@ preserve entries' meta-data. No matter what order order the meta-data occurs within the archive, the input stream will always have read it before the output stream must write it. -@subsection overview_arc_noseek_notifier wxArchiveNotifier +@subsection overview_archive_noseek_notifier wxArchiveNotifier Notifier objects can be used to get a notification whenever an input stream updates a wxArchiveEntry object's data via the weak reference mechanism.