/// <summary>
/// Reads a zip file archive from the given stream using the
/// specified options.
/// </summary>
///
/// <remarks>
///
/// <para>
/// When reading from a file, it's probably easier to just use
/// <see cref="ZipFile.Read(String,
/// ReadOptions)">ZipFile.Read(String, ReadOptions)</see>. This
/// overload is useful when when the zip archive content is
/// available from an already-open stream. The stream must be
/// open and readable and seekable when calling this method. The
/// stream is left open when the reading is completed.
/// </para>
///
/// <para>
/// Reading of zip content begins at the current position in the
/// stream. This means if you have a stream that concatenates
/// regular data and zip data, if you position the open, readable
/// stream at the start of the zip data, you will be able to read
/// the zip archive using this constructor, or any of the ZipFile
/// constructors that accept a <see cref="System.IO.Stream" /> as
/// input. Some examples of where this might be useful: the zip
/// content is concatenated at the end of a regular EXE file, as
/// some self-extracting archives do. (Note: SFX files produced
/// by DotNetZip do not work this way; they can be read as normal
/// ZIP files). Another example might be a stream being read from
/// a database, where the zip content is embedded within an
/// aggregate stream of data.
/// </para>
/// </remarks>
///
/// <param name="zipStream">the stream containing the zip data.</param>
///
/// <param name="options">
/// The set of options to use when reading the zip file.
/// </param>
///
/// <exception cref="System.Exception">
/// Thrown if the zip archive cannot be read.
/// </exception>
///
/// <returns>The ZipFile instance read from the stream.</returns>
///
/// <seealso cref="ZipFile.Read(String, ReadOptions)"/>
///
public static ZipFile Read(Stream zipStream, ReadOptions options)
{
if (options == null)
throw new ArgumentNullException("options");
return Read(zipStream,
options.StatusMessageWriter,
options.Encoding,
options.ReadProgress);
}
/// <summary>
/// Reads a zip file archive from the named filesystem file using the
/// specified options.
/// </summary>
///
/// <remarks>
/// <para>
/// This version of the <c>Read()</c> method allows the caller to pass
/// in a <c>TextWriter</c> an <c>Encoding</c>, via an instance of the
/// <c>ReadOptions</c> class. The <c>ZipFile</c> is read in using the
/// specified encoding for entries where UTF-8 encoding is not
/// explicitly specified.
/// </para>
/// </remarks>
///
/// <example>
///
/// <para>
/// This example shows how to read a zip file using the Big-5 Chinese
/// code page (950), and extract each entry in the zip file, while
/// sending status messages out to the Console.
/// </para>
///
/// <para>
/// For this code to work as intended, the zipfile must have been
/// created using the big5 code page (CP950). This is typical, for
/// example, when using WinRar on a machine with CP950 set as the
/// default code page. In that case, the names of entries within the
/// Zip archive will be stored in that code page, and reading the zip
/// archive must be done using that code page. If the application did
/// not use the correct code page in ZipFile.Read(), then names of
/// entries within the zip archive would not be correctly retrieved.
/// </para>
///
/// <code lang="C#">
/// string zipToExtract = "MyArchive.zip";
/// string extractDirectory = "extract";
/// var options = new ReadOptions
/// {
/// StatusMessageWriter = System.Console.Out,
/// Encoding = System.Text.Encoding.GetEncoding(950)
/// };
/// using (ZipFile zip = ZipFile.Read(zipToExtract, options))
/// {
/// foreach (ZipEntry e in zip)
/// {
/// e.Extract(extractDirectory);
/// }
/// }
/// </code>
///
///
/// <code lang="VB">
/// Dim zipToExtract as String = "MyArchive.zip"
/// Dim extractDirectory as String = "extract"
/// Dim options as New ReadOptions
/// options.Encoding = System.Text.Encoding.GetEncoding(950)
/// options.StatusMessageWriter = System.Console.Out
/// Using zip As ZipFile = ZipFile.Read(zipToExtract, options)
/// Dim e As ZipEntry
/// For Each e In zip
/// e.Extract(extractDirectory)
/// Next
/// End Using
/// </code>
/// </example>
///
///
/// <example>
///
/// <para>
/// This example shows how to read a zip file using the default
/// code page, to remove entries that have a modified date before a given threshold,
/// sending status messages out to a <c>StringWriter</c>.
/// </para>
///
/// <code lang="C#">
/// var options = new ReadOptions
/// {
/// StatusMessageWriter = new System.IO.StringWriter()
/// };
/// using (ZipFile zip = ZipFile.Read("PackedDocuments.zip", options))
/// {
/// var Threshold = new DateTime(2007,7,4);
/// // We cannot remove the entry from the list, within the context of
/// // an enumeration of said list.
/// // So we add the doomed entry to a list to be removed later.
/// // pass 1: mark the entries for removal
/// var MarkedEntries = new System.Collections.Generic.List<ZipEntry>();
/// foreach (ZipEntry e in zip)
/// {
/// if (e.LastModified < Threshold)
/// MarkedEntries.Add(e);
/// }
/// // pass 2: actually remove the entry.
/// foreach (ZipEntry zombie in MarkedEntries)
/// zip.RemoveEntry(zombie);
/// zip.Comment = "This archive has been updated.";
/// zip.Save();
/// }
/// // can now use contents of sw, eg store in an audit log
/// </code>
///
/// <code lang="VB">
/// Dim options as New ReadOptions
/// options.StatusMessageWriter = New System.IO.StringWriter
/// Using zip As ZipFile = ZipFile.Read("PackedDocuments.zip", options)
/// Dim Threshold As New DateTime(2007, 7, 4)
/// ' We cannot remove the entry from the list, within the context of
/// ' an enumeration of said list.
/// ' So we add the doomed entry to a list to be removed later.
/// ' pass 1: mark the entries for removal
/// Dim MarkedEntries As New System.Collections.Generic.List(Of ZipEntry)
/// Dim e As ZipEntry
/// For Each e In zip
/// If (e.LastModified < Threshold) Then
/// MarkedEntries.Add(e)
/// End If
/// Next
/// ' pass 2: actually remove the entry.
/// Dim zombie As ZipEntry
/// For Each zombie In MarkedEntries
/// zip.RemoveEntry(zombie)
/// Next
/// zip.Comment = "This archive has been updated."
/// zip.Save
/// End Using
/// ' can now use contents of sw, eg store in an audit log
/// </code>
/// </example>
///
/// <exception cref="System.Exception">
/// Thrown if the zipfile cannot be read. The implementation of
/// this method relies on <c>System.IO.File.OpenRead</c>, which
/// can throw a variety of exceptions, including specific
/// exceptions if a file is not found, an unauthorized access
/// exception, exceptions for poorly formatted filenames, and so
/// on.
/// </exception>
///
/// <param name="fileName">
/// The name of the zip archive to open.
/// This can be a fully-qualified or relative pathname.
/// </param>
///
/// <param name="options">
/// The set of options to use when reading the zip file.
/// </param>
///
/// <returns>The ZipFile instance read from the zip archive.</returns>
///
/// <seealso cref="ZipFile.Read(Stream, ReadOptions)"/>
///
public static ZipFile Read(string fileName,
ReadOptions options)
{
if (options == null)
throw new ArgumentNullException("options");
return Read(fileName,
options.StatusMessageWriter,
options.Encoding,
options.ReadProgress);
}