x/gtav-src
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
gtav-src/tools_ng/bin/ReportGenerator/Ionic.Zip.Partial.xml
T
x a6770644bb init gta
2025-09-29 00:52:08 +02:00

13102 lines
654 KiB
XML
Executable File
Raw Permalink Blame History

<?xml version="1.0"?>
<doc>
<assembly>
<name>Ionic.Zip.Partial</name>
</assembly>
<members>
<member name="T:Ionic.Zip.ZipFile">
<summary>
The ZipFile type represents a zip archive file. This is the main type in the
DotNetZip class library. This class reads and writes zip files, as defined in
the format for zip described by PKWare. The compression for this
implementation is provided by a managed-code version of Zlib,
included with DotNetZip in the classes in the Ionic.Zlib namespace.
</summary>
</member>
<member name="M:Ionic.Zip.ZipFile.ContainsEntry(System.String)">
<summary>
Returns true if an entry by the given name exists in the ZipFile.
</summary>
</member>
<member name="F:Ionic.Zip.ZipFile.DefaultEncoding">
<summary>
The default text encoding used in zip archives. It is numeric 437, also
known as IBM437.
</summary>
<seealso cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/>
</member>
<member name="M:Ionic.Zip.ZipFile.ToString">
<summary>Provides a string representation of the instance.</summary>
<returns>a string representation of the instance.</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.#ctor(System.String)">
<summary>
Creates a new <c>ZipFile</c> instance, using the specified filename.
</summary>
<remarks>
<para>
Applications can use this constructor to create a new ZipFile for writing,
or to slurp in an existing zip archive for read and update purposes.
</para>
<para>
To create a new zip archive, an application can call this constructor,
passing the name of a file that does not exist. The name may be a fully
qualified path. Then the application can add directories or files to the
<c>ZipFile</c> via <c>AddDirectory()</c>, <c>AddFile()</c>, <c>AddItem()</c>
and then write the zip archive to the disk by calling <c>Save()</c>. The
zip file is not actually opened and written to the disk until the
application calls <c>ZipFile.Save()</c>. At that point the new zip file
with the given name is created.
</para>
<para>
If you won't know the name of the <c>Zipfile</c> until the time you call
<c>ZipFile.Save()</c>, or if you plan to save to a stream (which has no
name), then you should use the no-argument constructor.
</para>
<para>
The application can also call this constructor to read an existing zip
archive. passing the name of a valid zip file that does exist. But, it's
better form to use the static <see cref="M:Ionic.Zip.ZipFile.Read(System.String)"/> method,
passing the name of the zip file, because using <c>ZipFile.Read()</c> in
your code communicates very clearly what you are doing. In either case,
the file is then read into the <c>ZipFile</c> instance. The app can then
enumerate the entries or can modify the zip file, for example adding
entries, removing entries, changing comments, and so on.
</para>
<para>
One advantage to this parameterized constructor: it allows applications to
use the same code to add items to a zip archive, regardless of whether the
zip file exists.
</para>
<para>
Instances of the <c>ZipFile</c> class are not multi-thread safe. You may
not party on a single instance with multiple threads. You may have
multiple threads that each use a distinct <c>ZipFile</c> instance, or you
can synchronize multi-thread access to a single instance.
</para>
<para>
By the way, since DotNetZip is so easy to use, don't you think <see href="http://cheeso.members.winisp.net/DotNetZipDonate.aspx">you should
donate $5 or $10</see>?
</para>
</remarks>
<exception cref="T:Ionic.Zip.ZipException">
Thrown if name refers to an existing file that is not a valid zip file.
</exception>
<example>
This example shows how to create a zipfile, and add a few files into it.
<code>
String ZipFileToCreate = "archive1.zip";
String DirectoryToZip = "c:\\reports";
using (ZipFile zip = new ZipFile())
{
// Store all files found in the top level directory, into the zip archive.
String[] filenames = System.IO.Directory.GetFiles(DirectoryToZip);
zip.AddFiles(filenames, "files");
zip.Save(ZipFileToCreate);
}
</code>
<code lang="VB">
Dim ZipFileToCreate As String = "archive1.zip"
Dim DirectoryToZip As String = "c:\reports"
Using zip As ZipFile = New ZipFile()
Dim filenames As String() = System.IO.Directory.GetFiles(DirectoryToZip)
zip.AddFiles(filenames, "files")
zip.Save(ZipFileToCreate)
End Using
</code>
</example>
<param name="fileName">The filename to use for the new zip archive.</param>
</member>
<member name="M:Ionic.Zip.ZipFile.#ctor(System.String,System.Text.Encoding)">
<summary>
Creates a new <c>ZipFile</c> instance, using the specified name for the
filename, and the specified Encoding.
</summary>
<remarks>
<para>
See the documentation on the <see cref="M:Ionic.Zip.ZipFile.#ctor(System.String)">ZipFile
constructor that accepts a single string argument</see> for basic
information on all the <c>ZipFile</c> constructors.
</para>
<para>
The Encoding is used as the default alternate encoding for entries with
filenames or comments that cannot be encoded with the IBM437 code page.
This is equivalent to setting the <see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/> property on the <c>ZipFile</c>
instance after construction.
</para>
<para>
Instances of the <c>ZipFile</c> class are not multi-thread safe. You may
not party on a single instance with multiple threads. You may have
multiple threads that each use a distinct <c>ZipFile</c> instance, or you
can synchronize multi-thread access to a single instance.
</para>
</remarks>
<exception cref="T:Ionic.Zip.ZipException">
Thrown if name refers to an existing file that is not a valid zip file.
</exception>
<param name="fileName">The filename to use for the new zip archive.</param>
<param name="encoding">The Encoding is used as the default alternate
encoding for entries with filenames or comments that cannot be encoded
with the IBM437 code page. </param>
</member>
<member name="M:Ionic.Zip.ZipFile.#ctor">
<summary>
Create a zip file, without specifying a target filename or stream to save to.
</summary>
<remarks>
<para>
See the documentation on the <see cref="M:Ionic.Zip.ZipFile.#ctor(System.String)">ZipFile
constructor that accepts a single string argument</see> for basic
information on all the <c>ZipFile</c> constructors.
</para>
<para>
After instantiating with this constructor and adding entries to the
archive, the application should call <see cref="M:Ionic.Zip.ZipFile.Save(System.String)"/> or
<see cref="M:Ionic.Zip.ZipFile.Save(System.IO.Stream)"/> to save to a file or a
stream, respectively. The application can also set the <see cref="P:Ionic.Zip.ZipFile.Name"/>
property and then call the no-argument <see cref="M:Ionic.Zip.ZipFile.Save"/> method. (This
is the preferred approach for applications that use the library through
COM interop.) If you call the no-argument <see cref="M:Ionic.Zip.ZipFile.Save"/> method
without having set the <c>Name</c> of the <c>ZipFile</c>, either through
the parameterized constructor or through the explicit property , the
Save() will throw, because there is no place to save the file. </para>
<para>
Instances of the <c>ZipFile</c> class are not multi-thread safe. You may
have multiple threads that each use a distinct <c>ZipFile</c> instance, or
you can synchronize multi-thread access to a single instance. </para>
</remarks>
<example>
This example creates a Zip archive called Backup.zip, containing all the files
in the directory DirectoryToZip. Files within subdirectories are not zipped up.
<code>
using (ZipFile zip = new ZipFile())
{
// Store all files found in the top level directory, into the zip archive.
// note: this code does not recurse subdirectories!
String[] filenames = System.IO.Directory.GetFiles(DirectoryToZip);
zip.AddFiles(filenames, "files");
zip.Save("Backup.zip");
}
</code>
<code lang="VB">
Using zip As New ZipFile
' Store all files found in the top level directory, into the zip archive.
' note: this code does not recurse subdirectories!
Dim filenames As String() = System.IO.Directory.GetFiles(DirectoryToZip)
zip.AddFiles(filenames, "files")
zip.Save("Backup.zip")
End Using
</code>
</example>
</member>
<member name="M:Ionic.Zip.ZipFile.#ctor(System.Text.Encoding)">
<summary>
Create a zip file, specifying a text Encoding, but without specifying a
target filename or stream to save to.
</summary>
<remarks>
<para>
See the documentation on the <see cref="M:Ionic.Zip.ZipFile.#ctor(System.String)">ZipFile
constructor that accepts a single string argument</see> for basic
information on all the <c>ZipFile</c> constructors.
</para>
</remarks>
<param name="encoding">
The Encoding is used as the default alternate encoding for entries with
filenames or comments that cannot be encoded with the IBM437 code page.
</param>
</member>
<member name="M:Ionic.Zip.ZipFile.#ctor(System.String,System.IO.TextWriter)">
<summary>
Creates a new <c>ZipFile</c> instance, using the specified name for the
filename, and the specified status message writer.
</summary>
<remarks>
<para>
See the documentation on the <see cref="M:Ionic.Zip.ZipFile.#ctor(System.String)">ZipFile
constructor that accepts a single string argument</see> for basic
information on all the <c>ZipFile</c> constructors.
</para>
<para>
This version of the constructor allows the caller to pass in a TextWriter,
to which verbose messages will be written during extraction or creation of
the zip archive. A console application may wish to pass
System.Console.Out to get messages on the Console. A graphical or headless
application may wish to capture the messages in a different
<c>TextWriter</c>, for example, a <c>StringWriter</c>, and then display
the messages in a TextBox, or generate an audit log of ZipFile operations.
</para>
<para>
To encrypt the data for the files added to the <c>ZipFile</c> instance,
set the Password property after creating the <c>ZipFile</c> instance.
</para>
<para>
Instances of the <c>ZipFile</c> class are not multi-thread safe. You may
not party on a single instance with multiple threads. You may have
multiple threads that each use a distinct <c>ZipFile</c> instance, or you
can synchronize multi-thread access to a single instance.
</para>
</remarks>
<exception cref="T:Ionic.Zip.ZipException">
Thrown if name refers to an existing file that is not a valid zip file.
</exception>
<example>
<code>
using (ZipFile zip = new ZipFile("Backup.zip", Console.Out))
{
// Store all files found in the top level directory, into the zip archive.
// note: this code does not recurse subdirectories!
// Status messages will be written to Console.Out
String[] filenames = System.IO.Directory.GetFiles(DirectoryToZip);
zip.AddFiles(filenames);
zip.Save();
}
</code>
<code lang="VB">
Using zip As New ZipFile("Backup.zip", Console.Out)
' Store all files found in the top level directory, into the zip archive.
' note: this code does not recurse subdirectories!
' Status messages will be written to Console.Out
Dim filenames As String() = System.IO.Directory.GetFiles(DirectoryToZip)
zip.AddFiles(filenames)
zip.Save()
End Using
</code>
</example>
<param name="fileName">The filename to use for the new zip archive.</param>
<param name="statusMessageWriter">A TextWriter to use for writing
verbose status messages.</param>
</member>
<member name="M:Ionic.Zip.ZipFile.#ctor(System.String,System.IO.TextWriter,System.Text.Encoding)">
<summary>
Creates a new <c>ZipFile</c> instance, using the specified name for the
filename, the specified status message writer, and the specified Encoding.
</summary>
<remarks>
<para>
This constructor works like the <see cref="M:Ionic.Zip.ZipFile.#ctor(System.String)">ZipFile
constructor that accepts a single string argument.</see> See that
reference for detail on what this constructor does.
</para>
<para>
This version of the constructor allows the caller to pass in a
<c>TextWriter</c>, and an Encoding. The <c>TextWriter</c> will collect
verbose messages that are generated by the library during extraction or
creation of the zip archive. A console application may wish to pass
<c>System.Console.Out</c> to get messages on the Console. A graphical or
headless application may wish to capture the messages in a different
<c>TextWriter</c>, for example, a <c>StringWriter</c>, and then display
the messages in a <c>TextBox</c>, or generate an audit log of
<c>ZipFile</c> operations.
</para>
<para>
The <c>Encoding</c> is used as the default alternate encoding for entries
with filenames or comments that cannot be encoded with the IBM437 code
page. This is a equivalent to setting the <see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/> property on the <c>ZipFile</c>
instance after construction.
</para>
<para>
To encrypt the data for the files added to the <c>ZipFile</c> instance,
set the <c>Password</c> property after creating the <c>ZipFile</c>
instance.
</para>
<para>
Instances of the <c>ZipFile</c> class are not multi-thread safe. You may
not party on a single instance with multiple threads. You may have
multiple threads that each use a distinct <c>ZipFile</c> instance, or you
can synchronize multi-thread access to a single instance.
</para>
</remarks>
<exception cref="T:Ionic.Zip.ZipException">
Thrown if <c>fileName</c> refers to an existing file that is not a valid zip file.
</exception>
<param name="fileName">The filename to use for the new zip archive.</param>
<param name="statusMessageWriter">A TextWriter to use for writing verbose
status messages.</param>
<param name="encoding">
The Encoding is used as the default alternate encoding for entries with
filenames or comments that cannot be encoded with the IBM437 code page.
</param>
</member>
<member name="M:Ionic.Zip.ZipFile.Initialize(System.String)">
<summary>
Initialize a <c>ZipFile</c> instance by reading in a zip file.
</summary>
<remarks>
<para>
This method is primarily useful from COM Automation environments, when
reading or extracting zip files. In COM, it is not possible to invoke
parameterized constructors for a class. A COM Automation application can
update a zip file by using the <see cref="M:Ionic.Zip.ZipFile.#ctor">default (no argument)
constructor</see>, then calling <c>Initialize()</c> to read the contents
of an on-disk zip archive into the <c>ZipFile</c> instance.
</para>
<para>
.NET applications are encouraged to use the <c>ZipFile.Read()</c> methods
for better clarity.
</para>
</remarks>
<param name="fileName">the name of the existing zip file to read in.</param>
</member>
<member name="M:Ionic.Zip.ZipFile.RemoveEntry(Ionic.Zip.ZipEntry)">
<summary>
Removes the given <c>ZipEntry</c> from the zip archive.
</summary>
<remarks>
<para>
After calling <c>RemoveEntry</c>, the application must call <c>Save</c> to
make the changes permanent.
</para>
</remarks>
<exception cref="T:System.ArgumentException">
Thrown if the specified <c>ZipEntry</c> does not exist in the <c>ZipFile</c>.
</exception>
<example>
In this example, all entries in the zip archive dating from before
December 31st, 2007, are removed from the archive. This is actually much
easier if you use the RemoveSelectedEntries method. But I needed an
example for RemoveEntry, so here it is.
<code>
String ZipFileToRead = "ArchiveToModify.zip";
System.DateTime Threshold = new System.DateTime(2007,12,31);
using (ZipFile zip = ZipFile.Read(ZipFileToRead))
{
var EntriesToRemove = new System.Collections.Generic.List&lt;ZipEntry&gt;();
foreach (ZipEntry e in zip)
{
if (e.LastModified &lt; Threshold)
{
// 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.
EntriesToRemove.Add(e);
}
}
// actually remove the doomed entries.
foreach (ZipEntry zombie in EntriesToRemove)
zip.RemoveEntry(zombie);
zip.Comment= String.Format("This zip archive was updated at {0}.",
System.DateTime.Now.ToString("G"));
// save with a different name
zip.Save("Archive-Updated.zip");
}
</code>
<code lang="VB">
Dim ZipFileToRead As String = "ArchiveToModify.zip"
Dim Threshold As New DateTime(2007, 12, 31)
Using zip As ZipFile = ZipFile.Read(ZipFileToRead)
Dim EntriesToRemove As New System.Collections.Generic.List(Of ZipEntry)
Dim e As ZipEntry
For Each e In zip
If (e.LastModified &lt; Threshold) Then
' 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.
EntriesToRemove.Add(e)
End If
Next
' actually remove the doomed entries.
Dim zombie As ZipEntry
For Each zombie In EntriesToRemove
zip.RemoveEntry(zombie)
Next
zip.Comment = String.Format("This zip archive was updated at {0}.", DateTime.Now.ToString("G"))
'save as a different name
zip.Save("Archive-Updated.zip")
End Using
</code>
</example>
<param name="entry">
The <c>ZipEntry</c> to remove from the zip.
</param>
<seealso cref="M:Ionic.Zip.ZipFile.RemoveSelectedEntries(System.String)"/>
</member>
<member name="M:Ionic.Zip.ZipFile.RemoveEntry(System.String)">
<summary>
Removes the <c>ZipEntry</c> with the given filename from the zip archive.
</summary>
<remarks>
<para>
After calling <c>RemoveEntry</c>, the application must call <c>Save</c> to
make the changes permanent.
</para>
</remarks>
<exception cref="T:System.InvalidOperationException">
Thrown if the <c>ZipFile</c> is not updatable.
</exception>
<exception cref="T:System.ArgumentException">
Thrown if a <c>ZipEntry</c> with the specified filename does not exist in
the <c>ZipFile</c>.
</exception>
<example>
This example shows one way to remove an entry with a given filename from
an existing zip archive.
<code>
String zipFileToRead= "PackedDocuments.zip";
string candidate = "DatedMaterial.xps";
using (ZipFile zip = ZipFile.Read(zipFileToRead))
{
if (zip.EntryFilenames.Contains(candidate))
{
zip.RemoveEntry(candidate);
zip.Comment= String.Format("The file '{0}' has been removed from this archive.",
Candidate);
zip.Save();
}
}
</code>
<code lang="VB">
Dim zipFileToRead As String = "PackedDocuments.zip"
Dim candidate As String = "DatedMaterial.xps"
Using zip As ZipFile = ZipFile.Read(zipFileToRead)
If zip.EntryFilenames.Contains(candidate) Then
zip.RemoveEntry(candidate)
zip.Comment = String.Format("The file '{0}' has been removed from this archive.", Candidate)
zip.Save
End If
End Using
</code>
</example>
<param name="fileName">
The name of the file, including any directory path, to remove from the zip.
The filename match is not case-sensitive by default; you can use the
<c>CaseSensitiveRetrieval</c> property to change this behavior. The
pathname can use forward-slashes or backward slashes.
</param>
</member>
<member name="M:Ionic.Zip.ZipFile.Dispose">
<summary>
Closes the read and write streams associated
to the <c>ZipFile</c>, if necessary.
</summary>
<remarks>
The Dispose() method is generally employed implicitly, via a <c>using(..) {..}</c>
statement. (<c>Using...End Using</c> in VB) If you do not employ a using
statement, insure that your application calls Dispose() explicitly. For
example, in a Powershell application, or an application that uses the COM
interop interface, you must call Dispose() explicitly.
</remarks>
<example>
This example extracts an entry selected by name, from the Zip file to the
Console.
<code>
using (ZipFile zip = ZipFile.Read(zipfile))
{
foreach (ZipEntry e in zip)
{
if (WantThisEntry(e.FileName))
zip.Extract(e.FileName, Console.OpenStandardOutput());
}
} // Dispose() is called implicitly here.
</code>
<code lang="VB">
Using zip As ZipFile = ZipFile.Read(zipfile)
Dim e As ZipEntry
For Each e In zip
If WantThisEntry(e.FileName) Then
zip.Extract(e.FileName, Console.OpenStandardOutput())
End If
Next
End Using ' Dispose is implicity called here
</code>
</example>
</member>
<member name="M:Ionic.Zip.ZipFile.Dispose(System.Boolean)">
<summary>
Disposes any managed resources, if the flag is set, then marks the
instance disposed. This method is typically not called explicitly from
application code.
</summary>
<remarks>
Applications should call <see cref="M:Ionic.Zip.ZipFile.Dispose">the no-arg Dispose method</see>.
</remarks>
<param name="disposeManagedResources">
indicates whether the method should dispose streams or not.
</param>
</member>
<member name="F:Ionic.Zip.ZipFile.IoBufferSizeDefault">
<summary>
Default size of the buffer used for IO.
</summary>
</member>
<member name="M:Ionic.Zip.ZipFile.CheckZip(System.String)">
<summary>
Checks a zip file to see if its directory is consistent.
</summary>
<remarks>
<para>
In cases of data error, the directory within a zip file can get out
of synch with the entries in the zip file. This method checks the
given zip file and returns true if this has occurred.
</para>
<para> This method may take a long time to run for large zip files. </para>
<para>
This method is not supported in the Reduced or Compact Framework
versions of DotNetZip.
</para>
<para>
Developers using COM can use the <see cref="M:Ionic.Zip.ComHelper.CheckZip(System.String)">ComHelper.CheckZip(String)</see>
method.
</para>
</remarks>
<param name="zipFileName">The filename to of the zip file to check.</param>
<returns>true if the named zip file checks OK. Otherwise, false. </returns>
<seealso cref="M:Ionic.Zip.ZipFile.FixZipDirectory(System.String)"/>
<seealso cref="M:Ionic.Zip.ZipFile.CheckZip(System.String,System.Boolean,System.Collections.ObjectModel.ReadOnlyCollection{System.String}@)"/>
</member>
<member name="M:Ionic.Zip.ZipFile.CheckZip(System.String,System.Boolean,System.Collections.ObjectModel.ReadOnlyCollection{System.String}@)">
<summary>
Checks a zip file to see if its directory is consistent,
and optionally fixes the directory if necessary.
</summary>
<remarks>
<para>
In cases of data error, the directory within a zip file can get out of
synch with the entries in the zip file. This method checks the given
zip file, and returns true if this has occurred. It also optionally
fixes the zipfile, saving the fixed copy in <em>Name</em>_Fixed.zip.
</para>
<para>
This method may take a long time to run for large zip files. It
will take even longer if the file actually needs to be fixed, and if
<c>fixIfNecessary</c> is true.
</para>
<para>
This method is not supported in the Reduced or Compact
Framework versions of DotNetZip.
</para>
</remarks>
<param name="zipFileName">The filename to of the zip file to check.</param>
<param name="fixIfNecessary">If true, the method will fix the zip file if
necessary.</param>
<param name="messages">
a collection of messages generated while checking, indicating any problems that are found.
</param>
<returns>true if the named zip is OK; false if the file needs to be fixed.</returns>
<seealso cref="M:Ionic.Zip.ZipFile.CheckZip(System.String)"/>
<seealso cref="M:Ionic.Zip.ZipFile.FixZipDirectory(System.String)"/>
</member>
<member name="M:Ionic.Zip.ZipFile.FixZipDirectory(System.String)">
<summary>
Rewrite the directory within a zipfile.
</summary>
<remarks>
<para>
In cases of data error, the directory in a zip file can get out of
synch with the entries in the zip file. This method attempts to fix
the zip file if this has occurred.
</para>
<para> This can take a long time for large zip files. </para>
<para> This won't work if the zip file uses a non-standard
code page - neither IBM437 nor UTF-8. </para>
<para>
This method is not supported in the Reduced or Compact Framework
versions of DotNetZip.
</para>
<para>
Developers using COM can use the <see cref="M:Ionic.Zip.ComHelper.FixZipDirectory(System.String)">ComHelper.FixZipDirectory(String)</see>
method.
</para>
</remarks>
<param name="zipFileName">The filename to of the zip file to fix.</param>
<seealso cref="M:Ionic.Zip.ZipFile.CheckZip(System.String)"/>
<seealso cref="M:Ionic.Zip.ZipFile.CheckZip(System.String,System.Boolean,System.Collections.ObjectModel.ReadOnlyCollection{System.String}@)"/>
</member>
<member name="M:Ionic.Zip.ZipFile.GetEnumerator">
<summary>
Generic IEnumerator support, for use of a ZipFile in an enumeration.
</summary>
<remarks>
You probably do not want to call <c>GetEnumerator</c> explicitly. Instead
it is implicitly called when you use a <see langword="foreach"/> loop in C#, or a
<c>For Each</c> loop in VB.NET.
</remarks>
<example>
This example reads a zipfile of a given name, then enumerates the
entries in that zip file, and displays the information about each
entry on the Console.
<code>
using (ZipFile zip = ZipFile.Read(zipfile))
{
bool header = true;
foreach (ZipEntry e in zip)
{
if (header)
{
System.Console.WriteLine("Zipfile: {0}", zip.Name);
System.Console.WriteLine("Version Needed: 0x{0:X2}", e.VersionNeeded);
System.Console.WriteLine("BitField: 0x{0:X2}", e.BitField);
System.Console.WriteLine("Compression Method: 0x{0:X2}", e.CompressionMethod);
System.Console.WriteLine("\n{1,-22} {2,-6} {3,4} {4,-8} {0}",
"Filename", "Modified", "Size", "Ratio", "Packed");
System.Console.WriteLine(new System.String('-', 72));
header = false;
}
System.Console.WriteLine("{1,-22} {2,-6} {3,4:F0}% {4,-8} {0}",
e.FileName,
e.LastModified.ToString("yyyy-MM-dd HH:mm:ss"),
e.UncompressedSize,
e.CompressionRatio,
e.CompressedSize);
e.Extract();
}
}
</code>
<code lang="VB">
Dim ZipFileToExtract As String = "c:\foo.zip"
Using zip As ZipFile = ZipFile.Read(ZipFileToExtract)
Dim header As Boolean = True
Dim e As ZipEntry
For Each e In zip
If header Then
Console.WriteLine("Zipfile: {0}", zip.Name)
Console.WriteLine("Version Needed: 0x{0:X2}", e.VersionNeeded)
Console.WriteLine("BitField: 0x{0:X2}", e.BitField)
Console.WriteLine("Compression Method: 0x{0:X2}", e.CompressionMethod)
Console.WriteLine(ChrW(10) &amp; "{1,-22} {2,-6} {3,4} {4,-8} {0}", _
"Filename", "Modified", "Size", "Ratio", "Packed" )
Console.WriteLine(New String("-"c, 72))
header = False
End If
Console.WriteLine("{1,-22} {2,-6} {3,4:F0}% {4,-8} {0}", _
e.FileName, _
e.LastModified.ToString("yyyy-MM-dd HH:mm:ss"), _
e.UncompressedSize, _
e.CompressionRatio, _
e.CompressedSize )
e.Extract
Next
End Using
</code>
</example>
<returns>A generic enumerator suitable for use within a foreach loop.</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.GetNewEnum">
<summary>
An IEnumerator, for use of a ZipFile in a foreach construct.
</summary>
<remarks>
This method is included for COM support. An application generally does not call
this method directly. It is called implicitly by COM clients when enumerating
the entries in the ZipFile instance. In VBScript, this is done with a <c>For Each</c>
statement. In Javascript, this is done with <c>new Enumerator(zipfile)</c>.
</remarks>
<returns>
The IEnumerator over the entries in the ZipFile.
</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.SaveSelfExtractor(System.String,Ionic.Zip.SelfExtractorFlavor)">
<summary>
Saves the ZipFile instance to a self-extracting zip archive.
</summary>
<remarks>
<para>
The generated exe image will execute on any machine that has the .NET Framework 2.0
installed on it. The generated exe image is also a valid ZIP file, readable with DotNetZip
or another Zip library or tool such as WinZip.
</para>
<para>
There are two "flavors" of self-extracting archive. The <c>WinFormsApplication</c>
version will pop up a GUI and allow the user to select a target directory into which
to extract. There's also a checkbox allowing the user to specify to overwrite
existing files, and another checkbox to allow the user to request that Explorer be
opened to see the extracted files after extraction. The other flavor is
<c>ConsoleApplication</c>. A self-extractor generated with that flavor setting will
run from the command line. It accepts command-line options to set the overwrite
behavior, and to specify the target extraction directory.
</para>
<para>
There are a few temporary files created during the saving to a self-extracting zip.
These files are created in the directory pointed to by <see cref="P:Ionic.Zip.ZipFile.TempFileFolder"/>, which defaults to <see cref="M:System.IO.Path.GetTempPath"/>. These temporary files are removed upon
successful completion of this method.
</para>
<para>
When a user runs the WinForms SFX, the user's personal directory (<see cref="F:System.Environment.SpecialFolder.Personal"/>) will be used as the default extract
location. The user who runs the SFX will have the opportunity to change the extract
directory before extracting. When the user runs the Command-Line SFX, the user must
explicitly specify the directory to which to extract. The .NET Framework 2.0 is
required on the computer when the self-extracting archive is run.
</para>
<para>
NB: This method is not available in the version of DotNetZip
build for the .NET Compact Framework, nor in the "Reduced" DotNetZip library.
</para>
</remarks>
<example>
<code>
string DirectoryPath = "c:\\Documents\\Project7";
using (ZipFile zip = new ZipFile())
{
zip.AddDirectory(DirectoryPath, System.IO.Path.GetFileName(DirectoryPath));
zip.Comment = "This will be embedded into a self-extracting console-based exe";
zip.SaveSelfExtractor("archive.exe", SelfExtractorFlavor.ConsoleApplication);
}
</code>
<code lang="VB">
Dim DirectoryPath As String = "c:\Documents\Project7"
Using zip As New ZipFile()
zip.AddDirectory(DirectoryPath, System.IO.Path.GetFileName(DirectoryPath))
zip.Comment = "This will be embedded into a self-extracting console-based exe"
zip.SaveSelfExtractor("archive.exe", SelfExtractorFlavor.ConsoleApplication)
End Using
</code>
</example>
<param name="exeToGenerate">a pathname, possibly fully qualified, to be created. Typically it will end in an .exe extension.</param>
<param name="flavor">Indicates whether a Winforms or Console self-extractor is desired.</param>
</member>
<member name="M:Ionic.Zip.ZipFile.SaveSelfExtractor(System.String,Ionic.Zip.SelfExtractorSaveOptions)">
<summary>
Saves the ZipFile instance to a self-extracting zip archive, using the specified
save options.
</summary>
<remarks>
<para>
This method saves a self extracting archive, using the specified save
options. These options include the flavor of the SFX, the default extract
directory, the icon file, and so on. See the documentation
for <see cref="M:Ionic.Zip.ZipFile.SaveSelfExtractor(System.String,Ionic.Zip.SelfExtractorFlavor)"/> for more
details.
</para>
<para>
The user who runs the SFX will have the opportunity to change the extract
directory before extracting. If at the time of extraction, the specified
directory does not exist, the SFX will create the directory before
extracting the files.
</para>
</remarks>
<example>
This example saves a self-extracting archive that will use c:\ExtractHere
as the default extract location.
<code>
string DirectoryPath = "c:\\Documents\\Project7";
using (ZipFile zip = new ZipFile())
{
zip.AddDirectory(DirectoryPath, System.IO.Path.GetFileName(DirectoryPath));
zip.Comment = "This will be embedded into a self-extracting console-based exe";
SelfExtractorOptions options = new SelfExtractorOptions();
options.Flavor = SelfExtractorFlavor.ConsoleApplication;
options.DefaultExtractDirectory = "%USERPROFILE%\\ExtractHere";
options.PostExtractCommandLine = ExeToRunAfterExtract;
options.RemoveUnpackedFilesAfterExecute = true;
zip.SaveSelfExtractor("archive.exe", options);
}
</code>
<code lang="VB">
Dim DirectoryPath As String = "c:\Documents\Project7"
Using zip As New ZipFile()
zip.AddDirectory(DirectoryPath, System.IO.Path.GetFileName(DirectoryPath))
zip.Comment = "This will be embedded into a self-extracting console-based exe"
Dim options As New SelfExtractorOptions()
options.Flavor = SelfExtractorFlavor.ConsoleApplication
options.DefaultExtractDirectory = "%USERPROFILE%\\ExtractHere"
options.PostExtractCommandLine = ExeToRunAfterExtract
options.RemoveUnpackedFilesAfterExecute = True
zip.SaveSelfExtractor("archive.exe", options)
End Using
</code>
</example>
<param name="exeToGenerate">The name of the EXE to generate.</param>
<param name="options">provides the options for how to save the Self-extracting archive.</param>
</member>
<member name="M:Ionic.Zip.ZipFile.Save">
<summary>
Saves the Zip archive to a file, specified by the Name property of the <c>ZipFile</c>.
</summary>
<remarks>
<para>
The <c>ZipFile</c> instance is written to storage, typically a zip file in a
filesystem, only when the caller calls <c>Save</c>. The Save operation writes
the zip content to a temporary file, and then renames the temporary file
to the desired name. If necessary, this method will delete a pre-existing file
before the rename.
</para>
<para> The <see cref="P:Ionic.Zip.ZipFile.Name"/> property is specified either
explicitly, or implicitly using one of the parameterized ZipFile
constructors. For COM Automation clients, the <c>Name</c> property must be
set explicitly, because COM Automation clients cannot call parameterized
constructors. </para>
<para>
When using a filesystem file for the Zip output, it is possible to call
<c>Save</c> multiple times on the <c>ZipFile</c> instance. With each call the zip
content is re-written to the same output file.
</para>
<para>
Data for entries that have been added to the <c>ZipFile</c> instance is written
to the output when the <c>Save</c> method is called. This means that the input
streams for those entries must be available at the time the application calls
<c>Save</c>. If, for example, the application adds entries with <c>AddEntry</c>
using a dynamically-allocated <c>MemoryStream</c>, the memory stream must not
have been disposed before the call to <c>Save</c>. See the <see cref="P:Ionic.Zip.ZipEntry.InputStream"/> property for more discussion of the availability
requirements of the input stream for an entry, and an approach for providing
just-in-time stream lifecycle management.
</para>
</remarks>
<seealso cref="M:Ionic.Zip.ZipFile.AddEntry(System.String,System.IO.Stream)"/>
<exception cref="T:Ionic.Zip.BadStateException">
Thrown if you haven't specified a location or stream for saving the zip,
either in the constructor or by setting the Name property, or if you try to
save a regular zip archive to a filename with a .exe extension.
</exception>
</member>
<member name="M:Ionic.Zip.ZipFile.Save(System.String)">
<summary>
Save the file to a new zipfile, with the given name.
</summary>
<remarks>
<para>
This method allows the application to explicitly specify the name of the zip
file when saving. Use this when creating a new zip file, or when
updating a zip archive.
</para>
<para>
An application can also save a zip archive in several places by calling this
method multiple times in succession, with different filenames.
</para>
<para>
The <c>ZipFile</c> instance is written to storage, typically a zip file in a
filesystem, only when the caller calls <c>Save</c>. The Save operation writes
the zip content to a temporary file, and then renames the temporary file
to the desired name. If necessary, this method will delete a pre-existing file
before the rename.
</para>
</remarks>
<exception cref="T:System.ArgumentException">
Thrown if you specify a directory for the filename.
</exception>
<param name="fileName">
The name of the zip archive to save to. Existing files will
be overwritten with great prejudice.
</param>
<example>
This example shows how to create and Save a zip file.
<code>
using (ZipFile zip = new ZipFile())
{
zip.AddDirectory(@"c:\reports\January");
zip.Save("January.zip");
}
</code>
<code lang="VB">
Using zip As New ZipFile()
zip.AddDirectory("c:\reports\January")
zip.Save("January.zip")
End Using
</code>
</example>
<example>
This example shows how to update a zip file.
<code>
using (ZipFile zip = ZipFile.Read("ExistingArchive.zip"))
{
zip.AddFile("NewData.csv");
zip.Save("UpdatedArchive.zip");
}
</code>
<code lang="VB">
Using zip As ZipFile = ZipFile.Read("ExistingArchive.zip")
zip.AddFile("NewData.csv")
zip.Save("UpdatedArchive.zip")
End Using
</code>
</example>
</member>
<member name="M:Ionic.Zip.ZipFile.Save(System.IO.Stream)">
<summary>
Save the zip archive to the specified stream.
</summary>
<remarks>
<para>
The <c>ZipFile</c> instance is written to storage - typically a zip file
in a filesystem, but using this overload, the storage can be anything
accessible via a writable stream - only when the caller calls <c>Save</c>.
</para>
<para>
Use this method to save the zip content to a stream directly. A common
scenario is an ASP.NET application that dynamically generates a zip file
and allows the browser to download it. The application can call
<c>Save(Response.OutputStream)</c> to write a zipfile directly to the
output stream, without creating a zip file on the disk on the ASP.NET
server.
</para>
<para>
Be careful when saving a file to a non-seekable stream, including
<c>Response.OutputStream</c>. When DotNetZip writes to a non-seekable
stream, the zip archive is formatted in such a way that may not be
compatible with all zip tools on all platforms. It's a perfectly legal
and compliant zip file, but some people have reported problems opening
files produced this way using the Mac OS archive utility.
</para>
</remarks>
<example>
This example saves the zipfile content into a MemoryStream, and
then gets the array of bytes from that MemoryStream.
<code lang="C#">
using (var zip = new Ionic.Zip.ZipFile())
{
zip.CompressionLevel= Ionic.Zlib.CompressionLevel.BestCompression;
zip.Password = "VerySecret.";
zip.Encryption = EncryptionAlgorithm.WinZipAes128;
zip.AddFile(sourceFileName);
MemoryStream output = new MemoryStream();
zip.Save(output);
byte[] zipbytes = output.ToArray();
}
</code>
</example>
<param name="outputStream">
The <c>System.IO.Stream</c> to write to. It must be writable.
</param>
</member>
<member name="M:Ionic.Zip.ZipFile.AddItem(System.String)">
<summary>
Adds an item, either a file or a directory, to a zip file archive.
</summary>
<remarks>
<para>
This method is handy if you are adding things to zip archive and don't
want to bother distinguishing between directories or files. Any files are
added as single entries. A directory added through this method is added
recursively: all files and subdirectories contained within the directory
are added to the <c>ZipFile</c>.
</para>
<para>
The name of the item may be a relative path or a fully-qualified
path. Remember, the items contained in <c>ZipFile</c> instance get written
to the disk only when you call <see cref="M:Ionic.Zip.ZipFile.Save"/> or a similar
save method.
</para>
<para>
The directory name used for the file within the archive is the same as the
directory name (potentially a relative path) specified in the
<paramref name="fileOrDirectoryName"/>.
</para>
<para>
For <c>ZipFile</c> properties including <see cref="P:Ionic.Zip.ZipFile.Encryption"/>, <see cref="P:Ionic.Zip.ZipFile.Password"/>, <see cref="P:Ionic.Zip.ZipFile.SetCompression"/>, <see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/>, <see cref="P:Ionic.Zip.ZipFile.ExtractExistingFile"/>,
<see cref="P:Ionic.Zip.ZipFile.ZipErrorAction"/>, and <see cref="P:Ionic.Zip.ZipFile.CompressionLevel"/>, their
respective values at the time of this call will be applied to the
<c>ZipEntry</c> added.
</para>
</remarks>
<seealso cref="M:Ionic.Zip.ZipFile.AddFile(System.String)"/>
<seealso cref="M:Ionic.Zip.ZipFile.AddDirectory(System.String)"/>
<seealso cref="M:Ionic.Zip.ZipFile.UpdateItem(System.String)"/>
<overloads>This method has two overloads.</overloads>
<param name="fileOrDirectoryName">
the name of the file or directory to add.</param>
<returns>The <c>ZipEntry</c> added.</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.AddItem(System.String,System.String)">
<summary>
Adds an item, either a file or a directory, to a zip file archive,
explicitly specifying the directory path to be used in the archive.
</summary>
<remarks>
<para>
If adding a directory, the add is recursive on all files and
subdirectories contained within it.
</para>
<para>
The name of the item may be a relative path or a fully-qualified path.
The item added by this call to the <c>ZipFile</c> is not read from the
disk nor written to the zip file archive until the application calls
Save() on the <c>ZipFile</c>.
</para>
<para>
This version of the method allows the caller to explicitly specify the
directory path to be used in the archive, which would override the
"natural" path of the filesystem file.
</para>
<para>
Encryption will be used on the file data if the <c>Password</c> has been set on
the <c>ZipFile</c> object, prior to calling this method.
</para>
<para>
For <c>ZipFile</c> properties including <see cref="P:Ionic.Zip.ZipFile.Encryption"/>, <see cref="P:Ionic.Zip.ZipFile.Password"/>, <see cref="P:Ionic.Zip.ZipFile.SetCompression"/>, <see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/>, <see cref="P:Ionic.Zip.ZipFile.ExtractExistingFile"/>,
<see cref="P:Ionic.Zip.ZipFile.ZipErrorAction"/>, and <see cref="P:Ionic.Zip.ZipFile.CompressionLevel"/>, their
respective values at the time of this call will be applied to the
<c>ZipEntry</c> added.
</para>
</remarks>
<exception cref="T:System.IO.FileNotFoundException">
Thrown if the file or directory passed in does not exist.
</exception>
<param name="fileOrDirectoryName">the name of the file or directory to add.
</param>
<param name="directoryPathInArchive">
The name of the directory path to use within the zip archive. This path
need not refer to an extant directory in the current filesystem. If the
files within the zip are later extracted, this is the path used for the
extracted file. Passing <c>null</c> (<c>Nothing</c> in VB) will use the
path on the fileOrDirectoryName. Passing the empty string ("") will
insert the item at the root path within the archive.
</param>
<seealso cref="M:Ionic.Zip.ZipFile.AddFile(System.String,System.String)"/>
<seealso cref="M:Ionic.Zip.ZipFile.AddDirectory(System.String,System.String)"/>
<seealso cref="M:Ionic.Zip.ZipFile.UpdateItem(System.String,System.String)"/>
<example>
This example shows how to zip up a set of files into a flat hierarchy,
regardless of where in the filesystem the files originated. The resulting
zip archive will contain a toplevel directory named "flat", which itself
will contain files Readme.txt, MyProposal.docx, and Image1.jpg. A
subdirectory under "flat" called SupportFiles will contain all the files
in the "c:\SupportFiles" directory on disk.
<code>
String[] itemnames= {
"c:\\fixedContent\\Readme.txt",
"MyProposal.docx",
"c:\\SupportFiles", // a directory
"images\\Image1.jpg"
};
try
{
using (ZipFile zip = new ZipFile())
{
for (int i = 1; i &lt; itemnames.Length; i++)
{
// will add Files or Dirs, recurses and flattens subdirectories
zip.AddItem(itemnames[i],"flat");
}
zip.Save(ZipToCreate);
}
}
catch (System.Exception ex1)
{
System.Console.Error.WriteLine("exception: {0}", ex1);
}
</code>
<code lang="VB">
Dim itemnames As String() = _
New String() { "c:\fixedContent\Readme.txt", _
"MyProposal.docx", _
"SupportFiles", _
"images\Image1.jpg" }
Try
Using zip As New ZipFile
Dim i As Integer
For i = 1 To itemnames.Length - 1
' will add Files or Dirs, recursing and flattening subdirectories.
zip.AddItem(itemnames(i), "flat")
Next i
zip.Save(ZipToCreate)
End Using
Catch ex1 As Exception
Console.Error.WriteLine("exception: {0}", ex1.ToString())
End Try
</code>
</example>
<returns>The <c>ZipEntry</c> added.</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.AddFile(System.String)">
<summary>
Adds a File to a Zip file archive.
</summary>
<remarks>
<para>
This call collects metadata for the named file in the filesystem,
including the file attributes and the timestamp, and inserts that metadata
into the resulting ZipEntry. Only when the application calls Save() on
the <c>ZipFile</c>, does DotNetZip read the file from the filesystem and
then write the content to the zip file archive.
</para>
<para>
This method will throw an exception if an entry with the same name already
exists in the <c>ZipFile</c>.
</para>
<para>
For <c>ZipFile</c> properties including <see cref="P:Ionic.Zip.ZipFile.Encryption"/>, <see cref="P:Ionic.Zip.ZipFile.Password"/>, <see cref="P:Ionic.Zip.ZipFile.SetCompression"/>, <see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/>, <see cref="P:Ionic.Zip.ZipFile.ExtractExistingFile"/>,
<see cref="P:Ionic.Zip.ZipFile.ZipErrorAction"/>, and <see cref="P:Ionic.Zip.ZipFile.CompressionLevel"/>, their
respective values at the time of this call will be applied to the
<c>ZipEntry</c> added.
</para>
</remarks>
<example>
<para>
In this example, three files are added to a Zip archive. The ReadMe.txt
file will be placed in the root of the archive. The .png file will be
placed in a folder within the zip called photos\personal. The pdf file
will be included into a folder within the zip called Desktop.
</para>
<code>
try
{
using (ZipFile zip = new ZipFile())
{
zip.AddFile("c:\\photos\\personal\\7440-N49th.png");
zip.AddFile("c:\\Desktop\\2008-Regional-Sales-Report.pdf");
zip.AddFile("ReadMe.txt");
zip.Save("Package.zip");
}
}
catch (System.Exception ex1)
{
System.Console.Error.WriteLine("exception: " + ex1);
}
</code>
<code lang="VB">
Try
Using zip As ZipFile = New ZipFile
zip.AddFile("c:\photos\personal\7440-N49th.png")
zip.AddFile("c:\Desktop\2008-Regional-Sales-Report.pdf")
zip.AddFile("ReadMe.txt")
zip.Save("Package.zip")
End Using
Catch ex1 As Exception
Console.Error.WriteLine("exception: {0}", ex1.ToString)
End Try
</code>
</example>
<overloads>This method has two overloads.</overloads>
<seealso cref="M:Ionic.Zip.ZipFile.AddItem(System.String)"/>
<seealso cref="M:Ionic.Zip.ZipFile.AddDirectory(System.String)"/>
<seealso cref="M:Ionic.Zip.ZipFile.UpdateFile(System.String)"/>
<param name="fileName">
The name of the file to add. It should refer to a file in the filesystem.
The name of the file may be a relative path or a fully-qualified path.
</param>
<returns>The <c>ZipEntry</c> corresponding to the File added.</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.AddFile(System.String,System.String)">
<summary>
Adds a File to a Zip file archive, potentially overriding the path to be
used within the zip archive.
</summary>
<remarks>
<para>
The file added by this call to the <c>ZipFile</c> is not written to the
zip file archive until the application calls Save() on the <c>ZipFile</c>.
</para>
<para>
This method will throw an exception if an entry with the same name already
exists in the <c>ZipFile</c>.
</para>
<para>
This version of the method allows the caller to explicitly specify the
directory path to be used in the archive.
</para>
<para>
For <c>ZipFile</c> properties including <see cref="P:Ionic.Zip.ZipFile.Encryption"/>, <see cref="P:Ionic.Zip.ZipFile.Password"/>, <see cref="P:Ionic.Zip.ZipFile.SetCompression"/>, <see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/>, <see cref="P:Ionic.Zip.ZipFile.ExtractExistingFile"/>,
<see cref="P:Ionic.Zip.ZipFile.ZipErrorAction"/>, and <see cref="P:Ionic.Zip.ZipFile.CompressionLevel"/>, their
respective values at the time of this call will be applied to the
<c>ZipEntry</c> added.
</para>
</remarks>
<example>
<para>
In this example, three files are added to a Zip archive. The ReadMe.txt
file will be placed in the root of the archive. The .png file will be
placed in a folder within the zip called images. The pdf file will be
included into a folder within the zip called files\docs, and will be
encrypted with the given password.
</para>
<code>
try
{
using (ZipFile zip = new ZipFile())
{
// the following entry will be inserted at the root in the archive.
zip.AddFile("c:\\datafiles\\ReadMe.txt", "");
// this image file will be inserted into the "images" directory in the archive.
zip.AddFile("c:\\photos\\personal\\7440-N49th.png", "images");
// the following will result in a password-protected file called
// files\\docs\\2008-Regional-Sales-Report.pdf in the archive.
zip.Password = "EncryptMe!";
zip.AddFile("c:\\Desktop\\2008-Regional-Sales-Report.pdf", "files\\docs");
zip.Save("Archive.zip");
}
}
catch (System.Exception ex1)
{
System.Console.Error.WriteLine("exception: {0}", ex1);
}
</code>
<code lang="VB">
Try
Using zip As ZipFile = New ZipFile
' the following entry will be inserted at the root in the archive.
zip.AddFile("c:\datafiles\ReadMe.txt", "")
' this image file will be inserted into the "images" directory in the archive.
zip.AddFile("c:\photos\personal\7440-N49th.png", "images")
' the following will result in a password-protected file called
' files\\docs\\2008-Regional-Sales-Report.pdf in the archive.
zip.Password = "EncryptMe!"
zip.AddFile("c:\Desktop\2008-Regional-Sales-Report.pdf", "files\documents")
zip.Save("Archive.zip")
End Using
Catch ex1 As Exception
Console.Error.WriteLine("exception: {0}", ex1)
End Try
</code>
</example>
<seealso cref="M:Ionic.Zip.ZipFile.AddItem(System.String,System.String)"/>
<seealso cref="M:Ionic.Zip.ZipFile.AddDirectory(System.String,System.String)"/>
<seealso cref="M:Ionic.Zip.ZipFile.UpdateFile(System.String,System.String)"/>
<param name="fileName">
The name of the file to add. The name of the file may be a relative path
or a fully-qualified path.
</param>
<param name="directoryPathInArchive">
Specifies a directory path to use to override any path in the fileName.
This path may, or may not, correspond to a real directory in the current
filesystem. If the files within the zip are later extracted, this is the
path used for the extracted file. Passing <c>null</c> (<c>Nothing</c> in
VB) will use the path on the fileName, if any. Passing the empty string
("") will insert the item at the root path within the archive.
</param>
<returns>The <c>ZipEntry</c> corresponding to the file added.</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.RemoveEntries(System.Collections.Generic.ICollection{Ionic.Zip.ZipEntry})">
<summary>
This method removes a collection of entries from the <c>ZipFile</c>.
</summary>
<param name="entriesToRemove">
A collection of ZipEntry instances from this zip file to be removed. For
example, you can pass in an array of ZipEntry instances; or you can call
SelectEntries(), and then add or remove entries from that
ICollection&lt;ZipEntry&gt; (ICollection(Of ZipEntry) in VB), and pass
that ICollection to this method.
</param>
<seealso cref="M:Ionic.Zip.ZipFile.SelectEntries(System.String)"/>
<seealso cref="M:Ionic.Zip.ZipFile.RemoveSelectedEntries(System.String)"/>
</member>
<member name="M:Ionic.Zip.ZipFile.RemoveEntries(System.Collections.Generic.ICollection{System.String})">
<summary>
This method removes a collection of entries from the <c>ZipFile</c>, by name.
</summary>
<param name="entriesToRemove">
A collection of strings that refer to names of entries to be removed from
the <c>ZipFile</c>. For example, you can pass in an array or a List of Strings
that provide the names of entries to be removed.
</param>
<seealso cref="M:Ionic.Zip.ZipFile.SelectEntries(System.String)"/>
<seealso cref="M:Ionic.Zip.ZipFile.RemoveSelectedEntries(System.String)"/>
</member>
<member name="M:Ionic.Zip.ZipFile.AddFiles(System.Collections.Generic.IEnumerable{System.String})">
<summary>
This method adds a set of files to the <c>ZipFile</c>.
</summary>
<remarks>
<para>
Use this method to add a set of files to the zip archive, in one call.
For example, a list of files received from
<c>System.IO.Directory.GetFiles()</c> can be added to a zip archive in one
call.
</para>
<para>
For <c>ZipFile</c> properties including <see cref="P:Ionic.Zip.ZipFile.Encryption"/>, <see cref="P:Ionic.Zip.ZipFile.Password"/>, <see cref="P:Ionic.Zip.ZipFile.SetCompression"/>, <see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/>, <see cref="P:Ionic.Zip.ZipFile.ExtractExistingFile"/>,
<see cref="P:Ionic.Zip.ZipFile.ZipErrorAction"/>, and <see cref="P:Ionic.Zip.ZipFile.CompressionLevel"/>, their
respective values at the time of this call will be applied to each
ZipEntry added.
</para>
</remarks>
<param name="fileNames">
The collection of names of the files to add. Each string should refer to a
file in the filesystem. The name of the file may be a relative path or a
fully-qualified path.
</param>
<example>
This example shows how to create a zip file, and add a few files into it.
<code>
String ZipFileToCreate = "archive1.zip";
String DirectoryToZip = "c:\\reports";
using (ZipFile zip = new ZipFile())
{
// Store all files found in the top level directory, into the zip archive.
String[] filenames = System.IO.Directory.GetFiles(DirectoryToZip);
zip.AddFiles(filenames);
zip.Save(ZipFileToCreate);
}
</code>
<code lang="VB">
Dim ZipFileToCreate As String = "archive1.zip"
Dim DirectoryToZip As String = "c:\reports"
Using zip As ZipFile = New ZipFile
' Store all files found in the top level directory, into the zip archive.
Dim filenames As String() = System.IO.Directory.GetFiles(DirectoryToZip)
zip.AddFiles(filenames)
zip.Save(ZipFileToCreate)
End Using
</code>
</example>
<seealso cref="M:Ionic.Zip.ZipFile.AddSelectedFiles(System.String,System.String)"/>
</member>
<member name="M:Ionic.Zip.ZipFile.UpdateFiles(System.Collections.Generic.IEnumerable{System.String})">
<summary>
Adds or updates a set of files in the <c>ZipFile</c>.
</summary>
<remarks>
<para>
Any files that already exist in the archive are updated. Any files that
don't yet exist in the archive are added.
</para>
<para>
For <c>ZipFile</c> properties including <see cref="P:Ionic.Zip.ZipFile.Encryption"/>, <see cref="P:Ionic.Zip.ZipFile.Password"/>, <see cref="P:Ionic.Zip.ZipFile.SetCompression"/>, <see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/>, <see cref="P:Ionic.Zip.ZipFile.ExtractExistingFile"/>,
<see cref="P:Ionic.Zip.ZipFile.ZipErrorAction"/>, and <see cref="P:Ionic.Zip.ZipFile.CompressionLevel"/>, their
respective values at the time of this call will be applied to each
ZipEntry added.
</para>
</remarks>
<param name="fileNames">
The collection of names of the files to update. Each string should refer to a file in
the filesystem. The name of the file may be a relative path or a fully-qualified path.
</param>
</member>
<member name="M:Ionic.Zip.ZipFile.AddFiles(System.Collections.Generic.IEnumerable{System.String},System.String)">
<summary>
Adds a set of files to the <c>ZipFile</c>, using the
specified directory path in the archive.
</summary>
<remarks>
<para>
Any directory structure that may be present in the
filenames contained in the list is "flattened" in the
archive. Each file in the list is added to the archive in
the specified top-level directory.
</para>
<para>
For <c>ZipFile</c> properties including <see cref="P:Ionic.Zip.ZipFile.Encryption"/>, <see cref="P:Ionic.Zip.ZipFile.Password"/>, <see cref="P:Ionic.Zip.ZipFile.SetCompression"/>, <see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/>, <see cref="P:Ionic.Zip.ZipFile.ExtractExistingFile"/>, <see cref="P:Ionic.Zip.ZipFile.ZipErrorAction"/>, and <see cref="P:Ionic.Zip.ZipFile.CompressionLevel"/>, their respective values at the
time of this call will be applied to each ZipEntry added.
</para>
</remarks>
<param name="fileNames">
The names of the files to add. Each string should refer to
a file in the filesystem. The name of the file may be a
relative path or a fully-qualified path.
</param>
<param name="directoryPathInArchive">
Specifies a directory path to use to override any path in the file name.
Th is path may, or may not, correspond to a real directory in the current
filesystem. If the files within the zip are later extracted, this is the
path used for the extracted file. Passing <c>null</c> (<c>Nothing</c> in
VB) will use the path on each of the <c>fileNames</c>, if any. Passing
the empty string ("") will insert the item at the root path within the
archive.
</param>
<seealso cref="M:Ionic.Zip.ZipFile.AddSelectedFiles(System.String,System.String)"/>
</member>
<member name="M:Ionic.Zip.ZipFile.AddFiles(System.Collections.Generic.IEnumerable{System.String},System.Boolean,System.String)">
<summary>
Adds a set of files to the <c>ZipFile</c>, using the specified directory
path in the archive, and preserving the full directory structure in the
filenames.
</summary>
<remarks>
<para>
If preserveDirHierarchy is true, any directory structure present in the
filenames contained in the list is preserved in the archive. On the other
hand, if preserveDirHierarchy is false, any directory structure that may
be present in the filenames contained in the list is "flattened" in the
archive; Each file in the list is added to the archive in the specified
top-level directory.
</para>
<para>
For <c>ZipFile</c> properties including <see cref="P:Ionic.Zip.ZipFile.Encryption"/>, <see cref="P:Ionic.Zip.ZipFile.Password"/>, <see cref="P:Ionic.Zip.ZipFile.SetCompression"/>, <see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/>, <see cref="P:Ionic.Zip.ZipFile.ExtractExistingFile"/>,
<see cref="P:Ionic.Zip.ZipFile.ZipErrorAction"/>, and <see cref="P:Ionic.Zip.ZipFile.CompressionLevel"/>, their
respective values at the time of this call will be applied to each
ZipEntry added.
</para>
</remarks>
<param name="fileNames">
The names of the files to add. Each string should refer to a file in the
filesystem. The name of the file may be a relative path or a
fully-qualified path.
</param>
<param name="directoryPathInArchive">
Specifies a directory path to use to override any path in the file name.
This path may, or may not, correspond to a real directory in the current
filesystem. If the files within the zip are later extracted, this is the
path used for the extracted file. Passing <c>null</c> (<c>Nothing</c> in
VB) will use the path on each of the <c>fileNames</c>, if any. Passing
the empty string ("") will insert the item at the root path within the
archive.
</param>
<param name="preserveDirHierarchy">
whether the entries in the zip archive will reflect the directory
hierarchy that is present in the various filenames. For example, if <paramref name="fileNames"/>
includes two paths, \Animalia\Chordata\Mammalia\Info.txt and
\Plantae\Magnoliophyta\Dicotyledon\Info.txt, then calling this method with
<paramref name="preserveDirHierarchy"/> = <c>false</c> will result in an
exception because of a duplicate entry name, while calling this method
with <paramref name="preserveDirHierarchy"/> = <c>true</c> will result in the
full direcory paths being included in the entries added to the ZipFile.
</param>
<seealso cref="M:Ionic.Zip.ZipFile.AddSelectedFiles(System.String,System.String)"/>
</member>
<member name="M:Ionic.Zip.ZipFile.UpdateFiles(System.Collections.Generic.IEnumerable{System.String},System.String)">
<summary>
Adds or updates a set of files to the <c>ZipFile</c>, using the specified
directory path in the archive.
</summary>
<remarks>
<para>
Any files that already exist in the archive are updated. Any files that
don't yet exist in the archive are added.
</para>
<para>
For <c>ZipFile</c> properties including <see cref="P:Ionic.Zip.ZipFile.Encryption"/>, <see cref="P:Ionic.Zip.ZipFile.Password"/>, <see cref="P:Ionic.Zip.ZipFile.SetCompression"/>, <see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/>, <see cref="P:Ionic.Zip.ZipFile.ExtractExistingFile"/>,
<see cref="P:Ionic.Zip.ZipFile.ZipErrorAction"/>, and <see cref="P:Ionic.Zip.ZipFile.CompressionLevel"/>, their
respective values at the time of this call will be applied to each
ZipEntry added.
</para>
</remarks>
<param name="fileNames">
The names of the files to add or update. Each string should refer to a
file in the filesystem. The name of the file may be a relative path or a
fully-qualified path.
</param>
<param name="directoryPathInArchive">
Specifies a directory path to use to override any path in the file name.
This path may, or may not, correspond to a real directory in the current
filesystem. If the files within the zip are later extracted, this is the
path used for the extracted file. Passing <c>null</c> (<c>Nothing</c> in
VB) will use the path on each of the <c>fileNames</c>, if any. Passing
the empty string ("") will insert the item at the root path within the
archive.
</param>
<seealso cref="M:Ionic.Zip.ZipFile.AddSelectedFiles(System.String,System.String)"/>
</member>
<member name="M:Ionic.Zip.ZipFile.UpdateFile(System.String)">
<summary>
Adds or Updates a File in a Zip file archive.
</summary>
<remarks>
<para>
This method adds a file to a zip archive, or, if the file already exists
in the zip archive, this method Updates the content of that given filename
in the zip archive. The <c>UpdateFile</c> method might more accurately be
called "AddOrUpdateFile".
</para>
<para>
Upon success, there is no way for the application to learn whether the file
was added versus updated.
</para>
<para>
For <c>ZipFile</c> properties including <see cref="P:Ionic.Zip.ZipFile.Encryption"/>, <see cref="P:Ionic.Zip.ZipFile.Password"/>, <see cref="P:Ionic.Zip.ZipFile.SetCompression"/>, <see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/>, <see cref="P:Ionic.Zip.ZipFile.ExtractExistingFile"/>,
<see cref="P:Ionic.Zip.ZipFile.ZipErrorAction"/>, and <see cref="P:Ionic.Zip.ZipFile.CompressionLevel"/>, their
respective values at the time of this call will be applied to the
<c>ZipEntry</c> added.
</para>
</remarks>
<example>
This example shows how to Update an existing entry in a zipfile. The first
call to UpdateFile adds the file to the newly-created zip archive. The
second call to UpdateFile updates the content for that file in the zip
archive.
<code>
using (ZipFile zip1 = new ZipFile())
{
// UpdateFile might more accurately be called "AddOrUpdateFile"
zip1.UpdateFile("MyDocuments\\Readme.txt");
zip1.UpdateFile("CustomerList.csv");
zip1.Comment = "This zip archive has been created.";
zip1.Save("Content.zip");
}
using (ZipFile zip2 = ZipFile.Read("Content.zip"))
{
zip2.UpdateFile("Updates\\Readme.txt");
zip2.Comment = "This zip archive has been updated: The Readme.txt file has been changed.";
zip2.Save();
}
</code>
<code lang="VB">
Using zip1 As New ZipFile
' UpdateFile might more accurately be called "AddOrUpdateFile"
zip1.UpdateFile("MyDocuments\Readme.txt")
zip1.UpdateFile("CustomerList.csv")
zip1.Comment = "This zip archive has been created."
zip1.Save("Content.zip")
End Using
Using zip2 As ZipFile = ZipFile.Read("Content.zip")
zip2.UpdateFile("Updates\Readme.txt")
zip2.Comment = "This zip archive has been updated: The Readme.txt file has been changed."
zip2.Save
End Using
</code>
</example>
<seealso cref="M:Ionic.Zip.ZipFile.AddFile(System.String)"/>
<seealso cref="M:Ionic.Zip.ZipFile.UpdateDirectory(System.String)"/>
<seealso cref="M:Ionic.Zip.ZipFile.UpdateItem(System.String)"/>
<param name="fileName">
The name of the file to add or update. It should refer to a file in the
filesystem. The name of the file may be a relative path or a
fully-qualified path.
</param>
<returns>
The <c>ZipEntry</c> corresponding to the File that was added or updated.
</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.UpdateFile(System.String,System.String)">
<summary>
Adds or Updates a File in a Zip file archive.
</summary>
<remarks>
<para>
This method adds a file to a zip archive, or, if the file already exists
in the zip archive, this method Updates the content of that given filename
in the zip archive.
</para>
<para>
This version of the method allows the caller to explicitly specify the
directory path to be used in the archive. The entry to be added or
updated is found by using the specified directory path, combined with the
basename of the specified filename.
</para>
<para>
Upon success, there is no way for the application to learn if the file was
added versus updated.
</para>
<para>
For <c>ZipFile</c> properties including <see cref="P:Ionic.Zip.ZipFile.Encryption"/>, <see cref="P:Ionic.Zip.ZipFile.Password"/>, <see cref="P:Ionic.Zip.ZipFile.SetCompression"/>, <see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/>, <see cref="P:Ionic.Zip.ZipFile.ExtractExistingFile"/>,
<see cref="P:Ionic.Zip.ZipFile.ZipErrorAction"/>, and <see cref="P:Ionic.Zip.ZipFile.CompressionLevel"/>, their
respective values at the time of this call will be applied to the
<c>ZipEntry</c> added.
</para>
</remarks>
<seealso cref="M:Ionic.Zip.ZipFile.AddFile(System.String,System.String)"/>
<seealso cref="M:Ionic.Zip.ZipFile.UpdateDirectory(System.String,System.String)"/>
<seealso cref="M:Ionic.Zip.ZipFile.UpdateItem(System.String,System.String)"/>
<param name="fileName">
The name of the file to add or update. It should refer to a file in the
filesystem. The name of the file may be a relative path or a
fully-qualified path.
</param>
<param name="directoryPathInArchive">
Specifies a directory path to use to override any path in the
<c>fileName</c>. This path may, or may not, correspond to a real
directory in the current filesystem. If the files within the zip are
later extracted, this is the path used for the extracted file. Passing
<c>null</c> (<c>Nothing</c> in VB) will use the path on the
<c>fileName</c>, if any. Passing the empty string ("") will insert the
item at the root path within the archive.
</param>
<returns>
The <c>ZipEntry</c> corresponding to the File that was added or updated.
</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.UpdateDirectory(System.String)">
<summary>
Add or update a directory in a zip archive.
</summary>
<remarks>
If the specified directory does not exist in the archive, then this method
is equivalent to calling <c>AddDirectory()</c>. If the specified
directory already exists in the archive, then this method updates any
existing entries, and adds any new entries. Any entries that are in the
zip archive but not in the specified directory, are left alone. In other
words, the contents of the zip file will be a union of the previous
contents and the new files.
</remarks>
<seealso cref="M:Ionic.Zip.ZipFile.UpdateFile(System.String)"/>
<seealso cref="M:Ionic.Zip.ZipFile.AddDirectory(System.String)"/>
<seealso cref="M:Ionic.Zip.ZipFile.UpdateItem(System.String)"/>
<param name="directoryName">
The path to the directory to be added to the zip archive, or updated in
the zip archive.
</param>
<returns>
The <c>ZipEntry</c> corresponding to the Directory that was added or updated.
</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.UpdateDirectory(System.String,System.String)">
<summary>
Add or update a directory in the zip archive at the specified root
directory in the archive.
</summary>
<remarks>
If the specified directory does not exist in the archive, then this method
is equivalent to calling <c>AddDirectory()</c>. If the specified
directory already exists in the archive, then this method updates any
existing entries, and adds any new entries. Any entries that are in the
zip archive but not in the specified directory, are left alone. In other
words, the contents of the zip file will be a union of the previous
contents and the new files.
</remarks>
<seealso cref="M:Ionic.Zip.ZipFile.UpdateFile(System.String,System.String)"/>
<seealso cref="M:Ionic.Zip.ZipFile.AddDirectory(System.String,System.String)"/>
<seealso cref="M:Ionic.Zip.ZipFile.UpdateItem(System.String,System.String)"/>
<param name="directoryName">
The path to the directory to be added to the zip archive, or updated in the
zip archive.
</param>
<param name="directoryPathInArchive">
Specifies a directory path to use to override any path in the
<c>directoryName</c>. This path may, or may not, correspond to a real
directory in the current filesystem. If the files within the zip are
later extracted, this is the path used for the extracted file. Passing
<c>null</c> (<c>Nothing</c> in VB) will use the path on the
<c>directoryName</c>, if any. Passing the empty string ("") will insert
the item at the root path within the archive.
</param>
<returns>
The <c>ZipEntry</c> corresponding to the Directory that was added or updated.
</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.UpdateItem(System.String)">
<summary>
Add or update a file or directory in the zip archive.
</summary>
<remarks>
<para>
This is useful when the application is not sure or does not care if the
item to be added is a file or directory, and does not know or does not
care if the item already exists in the <c>ZipFile</c>. Calling this method
is equivalent to calling <c>RemoveEntry()</c> if an entry by the same name
already exists, followed calling by <c>AddItem()</c>.
</para>
<para>
For <c>ZipFile</c> properties including <see cref="P:Ionic.Zip.ZipFile.Encryption"/>, <see cref="P:Ionic.Zip.ZipFile.Password"/>, <see cref="P:Ionic.Zip.ZipFile.SetCompression"/>, <see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/>, <see cref="P:Ionic.Zip.ZipFile.ExtractExistingFile"/>,
<see cref="P:Ionic.Zip.ZipFile.ZipErrorAction"/>, and <see cref="P:Ionic.Zip.ZipFile.CompressionLevel"/>, their
respective values at the time of this call will be applied to the
<c>ZipEntry</c> added.
</para>
</remarks>
<seealso cref="M:Ionic.Zip.ZipFile.AddItem(System.String)"/>
<seealso cref="M:Ionic.Zip.ZipFile.UpdateFile(System.String)"/>
<seealso cref="M:Ionic.Zip.ZipFile.UpdateDirectory(System.String)"/>
<param name="itemName">the path to the file or directory to be added or updated.</param>
</member>
<member name="M:Ionic.Zip.ZipFile.UpdateItem(System.String,System.String)">
<summary>
Add or update a file or directory.
</summary>
<remarks>
<para>
This method is useful when the application is not sure or does not care if
the item to be added is a file or directory, and does not know or does not
care if the item already exists in the <c>ZipFile</c>. Calling this method
is equivalent to calling <c>RemoveEntry()</c>, if an entry by that name
exists, and then calling <c>AddItem()</c>.
</para>
<para>
This version of the method allows the caller to explicitly specify the
directory path to be used for the item being added to the archive. The
entry or entries that are added or updated will use the specified
<c>DirectoryPathInArchive</c>. Extracting the entry from the archive will
result in a file stored in that directory path.
</para>
<para>
For <c>ZipFile</c> properties including <see cref="P:Ionic.Zip.ZipFile.Encryption"/>, <see cref="P:Ionic.Zip.ZipFile.Password"/>, <see cref="P:Ionic.Zip.ZipFile.SetCompression"/>, <see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/>, <see cref="P:Ionic.Zip.ZipFile.ExtractExistingFile"/>,
<see cref="P:Ionic.Zip.ZipFile.ZipErrorAction"/>, and <see cref="P:Ionic.Zip.ZipFile.CompressionLevel"/>, their
respective values at the time of this call will be applied to the
<c>ZipEntry</c> added.
</para>
</remarks>
<seealso cref="M:Ionic.Zip.ZipFile.AddItem(System.String,System.String)"/>
<seealso cref="M:Ionic.Zip.ZipFile.UpdateFile(System.String,System.String)"/>
<seealso cref="M:Ionic.Zip.ZipFile.UpdateDirectory(System.String,System.String)"/>
<param name="itemName">The path for the File or Directory to be added or updated.</param>
<param name="directoryPathInArchive">
Specifies a directory path to use to override any path in the
<c>itemName</c>. This path may, or may not, correspond to a real
directory in the current filesystem. If the files within the zip are
later extracted, this is the path used for the extracted file. Passing
<c>null</c> (<c>Nothing</c> in VB) will use the path on the
<c>itemName</c>, if any. Passing the empty string ("") will insert the
item at the root path within the archive.
</param>
</member>
<member name="M:Ionic.Zip.ZipFile.AddEntry(System.String,System.String)">
<summary>
Adds a named entry into the zip archive, taking content for the entry
from a string.
</summary>
<remarks>
Calling this method creates an entry using the given fileName and
directory path within the archive. There is no need for a file by the
given name to exist in the filesystem; the name is used within the zip
archive only. The content for the entry is encoded using the default text
encoding (<see cref="P:System.Text.Encoding.Default"/>).
</remarks>
<param name="content">
The content of the file, should it be extracted from the zip.
</param>
<param name="entryName">
The name, including any path, to use for the entry within the archive.
</param>
<returns>The <c>ZipEntry</c> added.</returns>
<example>
This example shows how to add an entry to the zipfile, using a string as
content for that entry.
<code lang="C#">
string Content = "This string will be the content of the Readme.txt file in the zip archive.";
using (ZipFile zip1 = new ZipFile())
{
zip1.AddFile("MyDocuments\\Resume.doc", "files");
zip1.AddEntry("Readme.txt", Content);
zip1.Comment = "This zip file was created at " + System.DateTime.Now.ToString("G");
zip1.Save("Content.zip");
}
</code>
<code lang="VB">
Public Sub Run()
Dim Content As String = "This string will be the content of the Readme.txt file in the zip archive."
Using zip1 As ZipFile = New ZipFile
zip1.AddEntry("Readme.txt", Content)
zip1.AddFile("MyDocuments\Resume.doc", "files")
zip1.Comment = ("This zip file was created at " &amp; DateTime.Now.ToString("G"))
zip1.Save("Content.zip")
End Using
End Sub
</code>
</example>
</member>
<member name="M:Ionic.Zip.ZipFile.AddEntry(System.String,System.String,System.Text.Encoding)">
<summary>
Adds a named entry into the zip archive, taking content for the entry
from a string, and using the specified text encoding.
</summary>
<remarks>
<para>
Calling this method creates an entry using the given fileName and
directory path within the archive. There is no need for a file by the
given name to exist in the filesystem; the name is used within the zip
archive only.
</para>
<para>
The content for the entry, a string value, is encoded using the given text
encoding. No Byte-order-mark (BOM) is emitted into the file.
</para>
<para>
If you wish to create within a zip file a file entry with Unicode-encoded
content that includes a byte-order-mark, you can convert your string to a
byte array using the appropriate <see cref="M:System.Text.Encoding.GetBytes(System.String)">System.Text.Encoding.GetBytes()</see>
method, then prepend to that byte array the output of <see cref="M:System.Text.Encoding.GetPreamble">System.Text.Encoding.GetPreamble()</see>,
and use the <see cref="M:Ionic.Zip.ZipFile.AddEntry(System.String,System.Byte[])"/> method, to add the
entry.
</para>
</remarks>
<param name="entryName">
The name, including any path, to use within the archive for the entry.
</param>
<param name="content">
The content of the file, should it be extracted from the zip.
</param>
<param name="encoding">
The text encoding to use when encoding the string. Be aware: This is
distinct from the text encoding used to encode the fileName, as specified
in <see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/>.
</param>
<returns>The <c>ZipEntry</c> added.</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.AddEntry(System.String,System.IO.Stream)">
<summary>
Create an entry in the <c>ZipFile</c> using the given <c>Stream</c> as input.
The entry will have the given filename.
</summary>
<remarks>
<para>
The application can provide an open, readable stream; in this case it will
be read during the call to <see cref="M:Ionic.Zip.ZipFile.Save"/> or one of its
overloads.
</para>
<para>
In cases where a large number of streams will be added to the
<c>ZipFile</c>, the application may wish to avoid maintaining all of the
streams open simultaneously. To handle this situation, the application
should use the <see cref="M:Ionic.Zip.ZipFile.AddEntry(System.String,Ionic.Zip.OpenDelegate,Ionic.Zip.CloseDelegate)"/>
overload.
</para>
<para>
For <c>ZipFile</c> properties including <see cref="P:Ionic.Zip.ZipFile.Encryption"/>, <see cref="P:Ionic.Zip.ZipFile.Password"/>, <see cref="P:Ionic.Zip.ZipFile.SetCompression"/>, <see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/>, <see cref="P:Ionic.Zip.ZipFile.ExtractExistingFile"/>,
<see cref="P:Ionic.Zip.ZipFile.ZipErrorAction"/>, and <see cref="P:Ionic.Zip.ZipFile.CompressionLevel"/>, their
respective values at the time of this call will be applied to the
<c>ZipEntry</c> added.
</para>
</remarks>
<example>
<para>
This example adds a single entry to a <c>ZipFile</c> via a <c>Stream</c>.
</para>
<code lang="C#">
String zipToCreate = "Content.zip";
String fileNameInArchive = "Content-From-Stream.bin";
using (System.IO.Stream streamToRead = MyStreamOpener())
{
using (ZipFile zip = new ZipFile())
{
ZipEntry entry= zip.AddEntry(fileNameInArchive, streamToRead);
zip.AddFile("Readme.txt");
zip.Save(zipToCreate); // the stream is read implicitly here
}
}
</code>
<code lang="VB">
Dim zipToCreate As String = "Content.zip"
Dim fileNameInArchive As String = "Content-From-Stream.bin"
Using streamToRead as System.IO.Stream = MyStreamOpener()
Using zip As ZipFile = New ZipFile()
Dim entry as ZipEntry = zip.AddEntry(fileNameInArchive, streamToRead)
zip.AddFile("Readme.txt")
zip.Save(zipToCreate) '' the stream is read implicitly, here
End Using
End Using
</code>
</example>
<seealso cref="M:Ionic.Zip.ZipFile.UpdateEntry(System.String,System.IO.Stream)"/>
<param name="entryName">
The name, including any path, which is shown in the zip file for the added
entry.
</param>
<param name="stream">The input stream from which to grab content for the file</param>
<returns>The <c>ZipEntry</c> added.</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.AddEntry(System.String,Ionic.Zip.WriteDelegate)">
<summary>
Add a ZipEntry for which content is written directly by the application.
</summary>
<remarks>
<para>
When the application needs to write the zip entry data, use this method to
add the ZipEntry. For example, in the case that the application wishes to
write the XML representation of a DataSet into a ZipEntry, the application
can use this method to do so.
</para>
<para>
For <c>ZipFile</c> properties including <see cref="P:Ionic.Zip.ZipFile.Encryption"/>, <see cref="P:Ionic.Zip.ZipFile.Password"/>, <see cref="P:Ionic.Zip.ZipFile.SetCompression"/>, <see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/>, <see cref="P:Ionic.Zip.ZipFile.ExtractExistingFile"/>,
<see cref="P:Ionic.Zip.ZipFile.ZipErrorAction"/>, and <see cref="P:Ionic.Zip.ZipFile.CompressionLevel"/>, their
respective values at the time of this call will be applied to the
<c>ZipEntry</c> added.
</para>
<para>
NB: With PKZip encryption, it's necessary to compute the CRC before
compressing or encrypting the data. Therefore, when using PKZip
encryption with a WriteDelegate, the WriteDelegate will be called twice:
once to compute the CRC, and the second time to (potentially) compress and
encrypt. For each call of the delegate, your application must stream the
same entry data in its entirety. If your application writes different data
during the second call, it will result in a corrupt zip file.
</para>
</remarks>
<param name="entryName">the name of the entry to add</param>
<param name="writer">the delegate which will write the entry content</param>
<returns>the ZipEntry added</returns>
<example>
This example shows an application filling a DataSet, then saving the
contents of that DataSet as XML, into a ZipEntry in a ZipFile, using an
anonymous delegate in C#. The DataSet XML is never saved to a disk file.
<code lang="C#">
var c1= new System.Data.SqlClient.SqlConnection(connstring1);
var da = new System.Data.SqlClient.SqlDataAdapter()
{
SelectCommand= new System.Data.SqlClient.SqlCommand(strSelect, c1)
};
DataSet ds1 = new DataSet();
da.Fill(ds1, "Invoices");
using(Ionic.Zip.ZipFile zip = new Ionic.Zip.ZipFile())
{
zip.AddEntry(zipEntryName, (name,stream) =&gt; ds1.WriteXml(stream) );
zip.Save(zipFileName);
}
</code>
</example>
<example>
This example uses an anonymous method in C# as the WriteDelegate to provide
the data for the ZipEntry. The example is a bit contrived - the
<c>AddFile()</c> method is a simpler way to insert the contents of a file
into an entry in a zip file. On the other hand, if there is some sort of
processing or transformation of the file contents required before writing,
the application could use the <c>WriteDelegate</c> to do it, in this way.
<code lang="C#">
using (var input = File.Open(filename, FileMode.Open, FileAccess.Read, FileShare.ReadWrite ))
{
using(Ionic.Zip.ZipFile zip = new Ionic.Zip.ZipFile())
{
zip.AddEntry(zipEntryName, (name,output) =&gt;
{
byte[] buffer = new byte[BufferSize];
int n;
while ((n = input.Read(buffer, 0, buffer.Length)) != 0)
{
// could transform the data here...
output.Write(buffer, 0, n);
// could update a progress bar here
}
});
zip.Save(zipFileName);
}
}
</code>
</example>
<example>
This example uses a named delegate in VB to write data for the given
ZipEntry (VB9 does not have anonymous delegates). The example here is a bit
contrived - a simpler way to add the contents of a file to a ZipEntry is to
simply use the appropriate <c>AddFile()</c> method. The key scenario for
which the <c>WriteDelegate</c> makes sense is saving a DataSet, in XML
format, to the zip file. The DataSet can write XML to a stream, and the
WriteDelegate is the perfect place to write into the zip file. There may be
other data structures that can write to a stream, but cannot be read as a
stream. The <c>WriteDelegate</c> would be appropriate for those cases as
well.
<code lang="VB">
Private Sub WriteEntry (ByVal name As String, ByVal output As Stream)
Using input As FileStream = File.Open(filename, FileMode.Open, FileAccess.Read, FileShare.ReadWrite)
Dim n As Integer = -1
Dim buffer As Byte() = New Byte(BufferSize){}
Do While n &lt;&gt; 0
n = input.Read(buffer, 0, buffer.Length)
output.Write(buffer, 0, n)
Loop
End Using
End Sub
Public Sub Run()
Using zip = New ZipFile
zip.AddEntry(zipEntryName, New WriteDelegate(AddressOf WriteEntry))
zip.Save(zipFileName)
End Using
End Sub
</code>
</example>
</member>
<member name="M:Ionic.Zip.ZipFile.AddEntry(System.String,Ionic.Zip.OpenDelegate,Ionic.Zip.CloseDelegate)">
<summary>
Add an entry, for which the application will provide a stream, just-in-time.
</summary>
<remarks>
<para>
In cases where the application wishes to open the stream that holds the content for
the ZipEntry, on a just-in-time basis, the application can use this method and
provide delegates to open and close the stream.
</para>
<para>
For <c>ZipFile</c> properties including <see cref="P:Ionic.Zip.ZipFile.Encryption"/>, <see cref="P:Ionic.Zip.ZipFile.Password"/>, <see cref="P:Ionic.Zip.ZipFile.SetCompression"/>, <see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/>, <see cref="P:Ionic.Zip.ZipFile.ExtractExistingFile"/>,
<see cref="P:Ionic.Zip.ZipFile.ZipErrorAction"/>, and <see cref="P:Ionic.Zip.ZipFile.CompressionLevel"/>, their
respective values at the time of this call will be applied to the
<c>ZipEntry</c> added.
</para>
</remarks>
<example>
This example uses anonymous methods in C# to open and close
the source stream for the content for a zip entry. In a real application, the
logic for the OpenDelegate would probably be more involved.
<code lang="C#">
using(Ionic.Zip.ZipFile zip = new Ionic.Zip.ZipFile())
{
zip.AddEntry(zipEntryName,
(name) =&gt; File.Open(filename, FileMode.Open, FileAccess.Read, FileShare.ReadWrite ),
(name, stream) =&gt; stream.Close()
);
zip.Save(zipFileName);
}
</code>
</example>
<example>
This example uses delegates in VB.NET to open and close the
the source stream for the content for a zip entry. VB 9.0 lacks
support for "Sub" lambda expressions, and so the CloseDelegate must
be an actual, named Sub.
<code lang="VB">
Function MyStreamOpener(ByVal entryName As String) As Stream
'' This simply opens a file. You probably want to do somethinig
'' more involved here: open a stream to read from a database,
'' open a stream on an HTTP connection, and so on.
Return File.OpenRead(entryName)
End Function
Sub MyStreamCloser(entryName As String, stream As Stream)
stream.Close()
End Sub
Public Sub Run()
Dim dirToZip As String = "fodder"
Dim zipFileToCreate As String = "Archive.zip"
Dim opener As OpenDelegate = AddressOf MyStreamOpener
Dim closer As CloseDelegate = AddressOf MyStreamCloser
Dim numFilestoAdd As Int32 = 4
Using zip As ZipFile = New ZipFile
Dim i As Integer
For i = 0 To numFilesToAdd - 1
zip.AddEntry(String.Format("content-{0:000}.txt"), opener, closer)
Next i
zip.Save(zipFileToCreate)
End Using
End Sub
</code>
</example>
<param name="entryName">the name of the entry to add</param>
<param name="opener">the delegate that will be invoked to open the stream</param>
<param name="closer">the delegate that will be invoked to close the stream</param>
<returns>the ZipEntry added</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.UpdateEntry(System.String,System.String)">
<summary>
Updates the given entry in the <c>ZipFile</c>, using the given string as
input.
</summary>
<remarks>
<para>
Calling this method is equivalent to removing the <c>ZipEntry</c> for the
given file name and directory path, if it exists, and then calling <see cref="M:Ionic.Zip.ZipFile.AddEntry(System.String,System.String)"/>. See the documentation for that
method for further explanation.
</para>
</remarks>
<param name="entryName">
The name, including any path, to use within the archive for the entry.
</param>
<param name="content">
The content of the file, should it be extracted from the zip.
</param>
<returns>The <c>ZipEntry</c> added.</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.UpdateEntry(System.String,System.String,System.Text.Encoding)">
<summary>
Updates the given entry in the <c>ZipFile</c>, using the given string as
content for the <c>ZipEntry</c>.
</summary>
<remarks>
Calling this method is equivalent to removing the <c>ZipEntry</c> for the
given file name and directory path, if it exists, and then calling <see cref="M:Ionic.Zip.ZipFile.AddEntry(System.String,System.String,System.Text.Encoding)"/>. See the
documentation for that method for further explanation.
</remarks>
<param name="entryName">
The name, including any path, to use within the archive for the entry.
</param>
<param name="content">
The content of the file, should it be extracted from the zip.
</param>
<param name="encoding">
The text encoding to use when encoding the string. Be aware: This is
distinct from the text encoding used to encode the filename. See <see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/>.
</param>
<returns>The <c>ZipEntry</c> added.</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.UpdateEntry(System.String,System.IO.Stream)">
<summary>
Updates the given entry in the <c>ZipFile</c>, using the given stream as
input, and the given filename and given directory Path.
</summary>
<remarks>
<para>
Calling the method is equivalent to calling <c>RemoveEntry()</c> if an
entry by the same name already exists, and then calling <c>AddEntry()</c>
with the given <c>fileName</c> and stream.
</para>
<para>
The stream must be open and readable during the call to
<c>ZipFile.Save</c>. You can dispense the stream on a just-in-time basis
using the <see cref="P:Ionic.Zip.ZipEntry.InputStream"/> property. Check the
documentation of that property for more information.
</para>
<para>
For <c>ZipFile</c> properties including <see cref="P:Ionic.Zip.ZipFile.Encryption"/>, <see cref="P:Ionic.Zip.ZipFile.Password"/>, <see cref="P:Ionic.Zip.ZipFile.SetCompression"/>, <see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/>, <see cref="P:Ionic.Zip.ZipFile.ExtractExistingFile"/>,
<see cref="P:Ionic.Zip.ZipFile.ZipErrorAction"/>, and <see cref="P:Ionic.Zip.ZipFile.CompressionLevel"/>, their
respective values at the time of this call will be applied to the
<c>ZipEntry</c> added.
</para>
</remarks>
<seealso cref="M:Ionic.Zip.ZipFile.AddEntry(System.String,System.IO.Stream)"/>
<seealso cref="P:Ionic.Zip.ZipEntry.InputStream"/>
<param name="entryName">
The name, including any path, to use within the archive for the entry.
</param>
<param name="stream">The input stream from which to read file data.</param>
<returns>The <c>ZipEntry</c> added.</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.AddEntry(System.String,System.Byte[])">
<summary>
Add an entry into the zip archive using the given filename and directory
path within the archive, and the given content for the file. No file is
created in the filesystem.
</summary>
<param name="byteContent">The data to use for the entry.</param>
<param name="entryName">
The name, including any path, to use within the archive for the entry.
</param>
<returns>The <c>ZipEntry</c> added.</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.UpdateEntry(System.String,System.Byte[])">
<summary>
Updates the given entry in the <c>ZipFile</c>, using the given byte array as
content for the entry.
</summary>
<remarks>
Calling this method is equivalent to removing the <c>ZipEntry</c> for the
given filename and directory path, if it exists, and then calling <see cref="M:Ionic.Zip.ZipFile.AddEntry(System.String,System.Byte[])"/>.
See the documentation for that method for further explanation.
</remarks>
<param name="entryName">
The name, including any path, to use within the archive for the entry.
</param>
<param name="byteContent">The content to use for the <c>ZipEntry</c>.</param>
<returns>The <c>ZipEntry</c> added.</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.AddDirectory(System.String)">
<summary>
Adds the contents of a filesystem directory to a Zip file archive.
</summary>
<remarks>
<para>
The name of the directory may be a relative path or a fully-qualified
path. Any files within the named directory are added to the archive. Any
subdirectories within the named directory are also added to the archive,
recursively.
</para>
<para>
Top-level entries in the named directory will appear as top-level entries
in the zip archive. Entries in subdirectories in the named directory will
result in entries in subdirectories in the zip archive.
</para>
<para>
If you want the entries to appear in a containing directory in the zip
archive itself, then you should call the AddDirectory() overload that
allows you to explicitly specify a directory path for use in the archive.
</para>
<para>
For <c>ZipFile</c> properties including <see cref="P:Ionic.Zip.ZipFile.Encryption"/>, <see cref="P:Ionic.Zip.ZipFile.Password"/>, <see cref="P:Ionic.Zip.ZipFile.SetCompression"/>, <see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/>, <see cref="P:Ionic.Zip.ZipFile.ExtractExistingFile"/>,
<see cref="P:Ionic.Zip.ZipFile.ZipErrorAction"/>, and <see cref="P:Ionic.Zip.ZipFile.CompressionLevel"/>, their
respective values at the time of this call will be applied to each
ZipEntry added.
</para>
</remarks>
<seealso cref="M:Ionic.Zip.ZipFile.AddItem(System.String)"/>
<seealso cref="M:Ionic.Zip.ZipFile.AddFile(System.String)"/>
<seealso cref="M:Ionic.Zip.ZipFile.UpdateDirectory(System.String)"/>
<seealso cref="M:Ionic.Zip.ZipFile.AddDirectory(System.String,System.String)"/>
<overloads>This method has 2 overloads.</overloads>
<param name="directoryName">The name of the directory to add.</param>
<returns>The <c>ZipEntry</c> added.</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.AddDirectory(System.String,System.String)">
<summary>
Adds the contents of a filesystem directory to a Zip file archive,
overriding the path to be used for entries in the archive.
</summary>
<remarks>
<para>
The name of the directory may be a relative path or a fully-qualified
path. The add operation is recursive, so that any files or subdirectories
within the name directory are also added to the archive.
</para>
<para>
Top-level entries in the named directory will appear as top-level entries
in the zip archive. Entries in subdirectories in the named directory will
result in entries in subdirectories in the zip archive.
</para>
<para>
For <c>ZipFile</c> properties including <see cref="P:Ionic.Zip.ZipFile.Encryption"/>, <see cref="P:Ionic.Zip.ZipFile.Password"/>, <see cref="P:Ionic.Zip.ZipFile.SetCompression"/>, <see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/>, <see cref="P:Ionic.Zip.ZipFile.ExtractExistingFile"/>,
<see cref="P:Ionic.Zip.ZipFile.ZipErrorAction"/>, and <see cref="P:Ionic.Zip.ZipFile.CompressionLevel"/>, their
respective values at the time of this call will be applied to each
ZipEntry added.
</para>
</remarks>
<example>
<para>
In this code, calling the ZipUp() method with a value of "c:\reports" for
the directory parameter will result in a zip file structure in which all
entries are contained in a toplevel "reports" directory.
</para>
<code lang="C#">
public void ZipUp(string targetZip, string directory)
{
using (var zip = new ZipFile())
{
zip.AddDirectory(directory, System.IO.Path.GetFileName(directory));
zip.Save(targetZip);
}
}
</code>
</example>
<seealso cref="M:Ionic.Zip.ZipFile.AddItem(System.String,System.String)"/>
<seealso cref="M:Ionic.Zip.ZipFile.AddFile(System.String,System.String)"/>
<seealso cref="M:Ionic.Zip.ZipFile.UpdateDirectory(System.String,System.String)"/>
<param name="directoryName">The name of the directory to add.</param>
<param name="directoryPathInArchive">
Specifies a directory path to use to override any path in the
DirectoryName. This path may, or may not, correspond to a real directory
in the current filesystem. If the zip is later extracted, this is the
path used for the extracted file or directory. Passing <c>null</c>
(<c>Nothing</c> in VB) or the empty string ("") will insert the items at
the root path within the archive.
</param>
<returns>The <c>ZipEntry</c> added.</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.AddDirectoryByName(System.String)">
<summary>
Creates a directory in the zip archive.
</summary>
<remarks>
<para>
Use this when you want to create a directory in the archive but there is
no corresponding filesystem representation for that directory.
</para>
<para>
You will probably not need to do this in your code. One of the only times
you will want to do this is if you want an empty directory in the zip
archive. The reason: if you add a file to a zip archive that is stored
within a multi-level directory, all of the directory tree is implicitly
created in the zip archive.
</para>
</remarks>
<param name="directoryNameInArchive">
The name of the directory to create in the archive.
</param>
<returns>The <c>ZipEntry</c> added.</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.AddSelectedFiles(System.String)">
<summary>
Adds to the ZipFile a set of files from the disk that conform to the
specified criteria.
</summary>
<remarks>
<para>
This method selects files from the the current working directory matching
the specified criteria, and adds them to the ZipFile. The selection does
not recurse into subdirectories.
</para>
<para>
Specify the criteria in statements of 3 elements: a noun, an operator, and
a value. Consider the string "name != *.doc" . The noun is "name". The
operator is "!=", implying "Not Equal". The value is "*.doc". That
criterion, in English, says "all files with a name that does not end in
the .doc extension."
</para>
<para>
Supported nouns include "name" for the filename; "atime", "mtime", and
"ctime" for last access time, last modfied time, and created time of the
file, respectively; "attributes" for the file attributes; and "size" for
the file length (uncompressed). The "attributes" and "name" nouns both
support = and != as operators. The "size", "atime", "mtime", and "ctime"
nouns support = and !=, and &gt;, &gt;=, &lt;, &lt;= as well. The times
are taken to be expressed in "local time".
</para>
<para>
Specify values for the file attributes as a string with one or more of the
characters H,R,S,A in any order, implying Hidden, ReadOnly, System, and
Archive, respectively. To specify a time, use YYYY-MM-DD-HH:mm:ss as the
format. If you omit the HH:mm:ss portion, it is assumed to be 00:00:00
(midnight). The value for a size criterion is expressed in integer
quantities of bytes, kilobytes (use k or kb after the number), megabytes
(m or mb), or gigabytes (g or gb). The value for a name is a pattern to
match against the filename, potentially including wildcards. The pattern
follows CMD.exe glob rules: * implies one or more of any character (not
including dot), while ? implies one character (not including dot). If the
name pattern contains any slashes, it is matched to the entire filename,
including the path; otherwise, it is matched against only the filename
without the path. This means a pattern of "*\*.*" matches all files one
directory level deep, while a pattern of "*.*" matches all files in all
directories.
</para>
<para>
To specify a name pattern that includes spaces, use single quotes around
the pattern. A pattern of "'* *.*'" will match all files that have spaces
in the filename. The full criteria string for that would be "name = '*
*.*'" .
</para>
<para>
Some examples:
</para>
<list type="table">
<listheader>
<term>criteria</term>
<description>Files retrieved</description>
</listheader>
<item>
<term>name != *.xls </term>
<description>any file with an extension that is not .xls
</description>
</item>
<item>
<term>name = *.mp3 </term>
<description>any file with a .mp3 extension.
</description>
</item>
<item>
<term>*.mp3</term>
<description>(same as above) any file with a .mp3 extension.
</description>
</item>
<item>
<term>attributes = A </term>
<description>all files whose attributes include the Archive bit.
</description>
</item>
<item>
<term>attributes != H </term>
<description>all files whose attributes do not include the Hidden bit.
</description>
</item>
<item>
<term>mtime > 2009-01-01</term>
<description>all files with a last modified time after January 1st, 2009.
</description>
</item>
<item>
<term>size > 2gb</term>
<description>all files whose uncompressed size is greater than 2gb.
</description>
</item>
</list>
<para>
You can combine criteria with the conjunctions AND or OR. Using a string like "name
= *.txt AND size &gt;= 100k" for the selectionCriteria retrieves entries whose names
end in .txt, and whose uncompressed size is greater than or equal to
100 kilobytes.
</para>
<para>
For more complex combinations of criteria, you can use parenthesis to group clauses
in the boolean logic. Without parenthesis, the precedence of the criterion atoms is
determined by order of appearance. Unlike the C# language, the AND conjunction does
not take precendence over the logical OR. This is important only in strings that
contain 3 or more criterion atoms. In other words, "name = *.txt and size &gt; 1000
or attributes = H" implies "((name = *.txt AND size &gt; 1000) OR attributes = H)"
while "attributes = H OR name = *.txt and size &gt; 1000" evaluates to "((attributes
= H OR name = *.txt) AND size &gt; 1000)". When in doubt, use parenthesis.
</para>
<para>
Using time properties requires some extra care. If you want to retrieve all entries
that were last updated on 2009 February 14, specify a time range like so:"mtime
&gt;= 2009-02-14 AND mtime &lt; 2009-02-15". Read this to say: all files updated
after 12:00am on February 14th, until 12:00am on February 15th. You can use the
same bracketing approach to specify any time period - a year, a month, a week, and
so on.
</para>
<para>
The syntax allows one special case: if you provide a string with no spaces, it is
treated as a pattern to match for the filename. Therefore a string like "*.xls"
will be equivalent to specifying "name = *.xls".
</para>
<para>
There is no logic in this method that insures that the file inclusion criteria are
internally consistent. For example, it's possible to specify criteria that says
the file must have a size of less than 100 bytes, as well as a size that is
greater than 1000 bytes. Obviously no file will ever satisfy such criteria, but
this method does not detect such logical inconsistencies. The caller is
responsible for insuring the criteria are sensible.
</para>
</remarks>
<example>
This example zips up all *.csv files in the current working directory.
<code>
using (ZipFile zip = new ZipFile())
{
// To just match on filename wildcards,
// use the shorthand form of the selectionCriteria string.
zip.AddSelectedFiles("*.csv");
zip.Save(PathToZipArchive);
}
</code>
<code lang="VB">
Using zip As ZipFile = New ZipFile()
zip.AddSelectedFiles("*.csv")
zip.Save(PathToZipArchive)
End Using
</code>
</example>
<param name="selectionCriteria">The criteria for file selection</param>
</member>
<member name="M:Ionic.Zip.ZipFile.AddSelectedFiles(System.String,System.Boolean)">
<summary>
Adds to the ZipFile a set of files from the disk that conform to the specified criteria.
</summary>
<remarks>
<para>
This method selects files from the the current working directory matching the specified
criteria, and adds them to the ZipFile. If <c>recurseDirectories</c> is true, files are also
selected from subdirectories, and the directory structure in the filesystem is reproduced
in the zip archive, rooted at the directory specified by <c>directoryOnDisk</c>.
</para>
<para>
For details on the syntax for the selectionCriteria parameter, see <see cref="M:Ionic.Zip.ZipFile.AddSelectedFiles(System.String)"/>.
</para>
</remarks>
<example>
This example zips up all *.xml files in the current working directory, or any
subdirectory, that are larger than 1mb.
<code>
using (ZipFile zip = new ZipFile())
{
// Use a compound expression in the selectionCriteria string.
zip.AddSelectedFiles("name = *.xml and size &gt; 1024kb", true);
zip.Save(PathToZipArchive);
}
</code>
<code lang="VB">
Using zip As ZipFile = New ZipFile()
' Use a compound expression in the selectionCriteria string.
zip.AddSelectedFiles("name = *.xml and size &gt; 1024kb", true)
zip.Save(PathToZipArchive)
End Using
</code>
</example>
<param name="selectionCriteria">The criteria for file selection</param>
<param name="recurseDirectories">
If true, the file selection will recurse into subdirectories.
</param>
</member>
<member name="M:Ionic.Zip.ZipFile.AddSelectedFiles(System.String,System.String)">
<summary>
Adds to the ZipFile a set of files from the disk that conform to the specified criteria.
</summary>
<remarks>
This method selects files from the the specified disk directory matching the specified
criteria, and adds them to the ZipFile. The search does not recurse into
subdirectores. For details on the syntax for the selectionCriteria parameter, see <see cref="M:Ionic.Zip.ZipFile.AddSelectedFiles(System.String)"/>.
</remarks>
<example>
This example zips up all *.xml files larger than 1mb in the directory given by "d:\rawdata".
<code>
using (ZipFile zip = new ZipFile())
{
// Use a compound expression in the selectionCriteria string.
zip.AddSelectedFiles("name = *.xml and size &gt; 1024kb", "d:\\rawdata");
zip.Save(PathToZipArchive);
}
</code>
<code lang="VB">
Using zip As ZipFile = New ZipFile()
' Use a compound expression in the selectionCriteria string.
zip.AddSelectedFiles("name = *.xml and size &gt; 1024kb", "d:\rawdata)
zip.Save(PathToZipArchive)
End Using
</code>
</example>
<param name="selectionCriteria">The criteria for file selection</param>
<param name="directoryOnDisk">
The name of the directory on the disk from which to select files.
</param>
</member>
<member name="M:Ionic.Zip.ZipFile.AddSelectedFiles(System.String,System.String,System.Boolean)">
<summary>
Adds to the ZipFile a set of files from the disk that conform to the specified criteria.
</summary>
<remarks>
This method selects files from the the specified disk directory matching the specified
selection criteria, and adds them to the ZipFile. If <c>recurseDirectories</c> is true,
files are also selected from subdirectories, and the directory structure in the
filesystem is reproduced in the zip archive, rooted at the directory specified by
<c>directoryOnDisk</c>. For details on the syntax for the selectionCriteria parameter,
see <see cref="M:Ionic.Zip.ZipFile.AddSelectedFiles(System.String)"/>.
</remarks>
<example>
This example zips up all *.csv files in the "files" directory, or any subdirectory, that
have been saved since 2009 February 14th.
<code>
using (ZipFile zip = new ZipFile())
{
// Use a compound expression in the selectionCriteria string.
zip.AddSelectedFiles("name = *.csv and mtime &gt; 2009-02-14", "files", true);
zip.Save(PathToZipArchive);
}
</code>
<code lang="VB">
Using zip As ZipFile = New ZipFile()
' Use a compound expression in the selectionCriteria string.
zip.AddSelectedFiles("name = *.csv and mtime &gt; 2009-02-14", "files", true)
zip.Save(PathToZipArchive)
End Using
</code>
</example>
<param name="selectionCriteria">The criteria for file selection</param>
<param name="directoryOnDisk">
The name of the directory on the disk from which to select files.
</param>
<param name="recurseDirectories">
If true, the file selection will recurse into subdirectories.
</param>
</member>
<member name="M:Ionic.Zip.ZipFile.AddSelectedFiles(System.String,System.String,System.String)">
<summary>
Adds to the ZipFile a selection of files from the disk that conform to the
specified criteria.
</summary>
<remarks>
This method selects files from the specified disk directory matching the specified
selection criteria, and adds those files to the ZipFile, using the specified directory
path in the archive. The search does not recurse into subdirectories. For details on
the syntax for the selectionCriteria parameter, see <see cref="M:Ionic.Zip.ZipFile.AddSelectedFiles(System.String)"/>.
</remarks>
<example>
This example zips up all *.psd files in the "photos" directory that have been saved
since 2009 February 14th, and puts them all in a zip file, using the directory name of
"content" in the zip archive itself. When the zip archive is unzipped, the folder
containing the .psd files will be named "content".
<code>
using (ZipFile zip = new ZipFile())
{
// Use a compound expression in the selectionCriteria string.
zip.AddSelectedFiles("name = *.psd and mtime &gt; 2009-02-14", "photos", "content");
zip.Save(PathToZipArchive);
}
</code>
<code lang="VB">
Using zip As ZipFile = New ZipFile
zip.AddSelectedFiles("name = *.psd and mtime &gt; 2009-02-14", "photos", "content")
zip.Save(PathToZipArchive)
End Using
</code>
</example>
<param name="selectionCriteria">The criteria for selection of files to Add</param>
<param name="directoryOnDisk">
The name of the directory on the disk from which to select files.
</param>
<param name="directoryPathInArchive">
Specifies a directory path to use to override any path in the FileName. This path may,
or may not, correspond to a real directory in the current filesystem. If the files
within the zip are later extracted, this is the path used for the extracted file.
Passing null (nothing in VB) will use the path on the FileName, if any. Passing the
empty string ("") will insert the item at the root path within the archive.
</param>
</member>
<member name="M:Ionic.Zip.ZipFile.AddSelectedFiles(System.String,System.String,System.String,System.Boolean)">
<summary>
Adds to the ZipFile a selection of files from the disk that conform to the specified criteria.
</summary>
<remarks>
This method selects files from the specified disk directory that match the specified
selection criteria, and adds those files to the ZipFile, using the specified directory
path in the archive. If <c>recurseDirectories</c> is true, files are also selected from
subdirectories, and the directory structure in the filesystem is reproduced in the zip
archive, rooted at the directory specified by <c>directoryOnDisk</c>. For details on the
syntax for the selectionCriteria parameter, see <see cref="M:Ionic.Zip.ZipFile.AddSelectedFiles(System.String)"/>.
</remarks>
<example>
This example zips up all files that are NOT *.pst files, in the current working
directory and any subdirectories.
<code>
using (ZipFile zip = new ZipFile())
{
zip.AddSelectedFiles("name != *.pst", SourceDirectory, "backup", true);
zip.Save(PathToZipArchive);
}
</code>
<code lang="VB">
Using zip As ZipFile = New ZipFile
zip.AddSelectedFiles("name != *.pst", SourceDirectory, "backup", true)
zip.Save(PathToZipArchive)
End Using
</code>
</example>
<param name="selectionCriteria">The criteria for selection of files to Add</param>
<param name="directoryOnDisk">
The name of the directory on the disk from which to select files.
</param>
<param name="directoryPathInArchive">
Specifies a directory path to use to override any path in the FileName. This path may,
or may not, correspond to a real directory in the current filesystem. If the files
within the zip are later extracted, this is the path used for the extracted file.
Passing null (nothing in VB) will use the path on the FileName, if any. Passing the
empty string ("") will insert the item at the root path within the archive.
</param>
<param name="recurseDirectories">
If true, the method also scans subdirectories for files matching the criteria.
</param>
</member>
<member name="M:Ionic.Zip.ZipFile.UpdateSelectedFiles(System.String,System.String,System.String,System.Boolean)">
<summary>
Updates the ZipFile with a selection of files from the disk that conform to
the specified criteria.
</summary>
<remarks>
This method selects files from the specified disk directory that match the
specified selection criteria, and Updates the <c>ZipFile</c> with those
files, using the specified directory path in the archive. If
<c>recurseDirectories</c> is true, files are also selected from
subdirectories, and the directory structure in the filesystem is reproduced
in the zip archive, rooted at the directory specified by
<c>directoryOnDisk</c>. For details on the syntax for the selectionCriteria
parameter, see <see cref="M:Ionic.Zip.ZipFile.AddSelectedFiles(System.String)"/>.
</remarks>
<param name="selectionCriteria">The criteria for selection of files to Add</param>
<param name="directoryOnDisk">
The name of the directory on the disk from which to select files.
</param>
<param name="directoryPathInArchive">
Specifies a directory path to use to override any path in the FileName. This path may,
or may not, correspond to a real directory in the current filesystem. If the files
within the zip are later extracted, this is the path used for the extracted file.
Passing null (nothing in VB) will use the path on the FileName, if any. Passing the
empty string ("") will insert the item at the root path within the archive.
</param>
<param name="recurseDirectories">
If true, the method also scans subdirectories for files matching the criteria.
</param>
<seealso cref="M:Ionic.Zip.ZipFile.AddSelectedFiles(System.String,System.String,System.String,System.Boolean)"/>
</member>
<member name="M:Ionic.Zip.ZipFile.SelectEntries(System.String)">
<summary>
Retrieve entries from the zipfile by specified criteria.
</summary>
<remarks>
<para>
This method allows callers to retrieve the collection of entries from the zipfile
that fit the specified criteria. The criteria are described in a string format, and
can include patterns for the filename; constraints on the size of the entry;
constraints on the last modified, created, or last accessed time for the file
described by the entry; or the attributes of the entry.
</para>
<para>
For details on the syntax for the selectionCriteria parameter, see <see cref="M:Ionic.Zip.ZipFile.AddSelectedFiles(System.String)"/>.
</para>
<para>
This method is intended for use with a ZipFile that has been read from storage.
When creating a new ZipFile, this method will work only after the ZipArchive has
been Saved to the disk (the ZipFile class subsequently and implicitly reads the Zip
archive from storage.) Calling SelectEntries on a ZipFile that has not yet been
saved will deliver undefined results.
</para>
</remarks>
<exception cref="T:System.Exception">
Thrown if selectionCriteria has an invalid syntax.
</exception>
<example>
This example selects all the PhotoShop files from within an archive, and extracts them
to the current working directory.
<code>
using (ZipFile zip1 = ZipFile.Read(ZipFileName))
{
var PhotoShopFiles = zip1.SelectEntries("*.psd");
foreach (ZipEntry psd in PhotoShopFiles)
{
psd.Extract();
}
}
</code>
<code lang="VB">
Using zip1 As ZipFile = ZipFile.Read(ZipFileName)
Dim PhotoShopFiles as ICollection(Of ZipEntry)
PhotoShopFiles = zip1.SelectEntries("*.psd")
Dim psd As ZipEntry
For Each psd In PhotoShopFiles
psd.Extract
Next
End Using
</code>
</example>
<param name="selectionCriteria">the string that specifies which entries to select</param>
<returns>a collection of ZipEntry objects that conform to the inclusion spec</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.SelectEntries(System.String,System.String)">
<summary>
Retrieve entries from the zipfile by specified criteria.
</summary>
<remarks>
<para>
This method allows callers to retrieve the collection of entries from the zipfile
that fit the specified criteria. The criteria are described in a string format, and
can include patterns for the filename; constraints on the size of the entry;
constraints on the last modified, created, or last accessed time for the file
described by the entry; or the attributes of the entry.
</para>
<para>
For details on the syntax for the selectionCriteria parameter, see <see cref="M:Ionic.Zip.ZipFile.AddSelectedFiles(System.String)"/>.
</para>
<para>
This method is intended for use with a ZipFile that has been read from storage.
When creating a new ZipFile, this method will work only after the ZipArchive has
been Saved to the disk (the ZipFile class subsequently and implicitly reads the Zip
archive from storage.) Calling SelectEntries on a ZipFile that has not yet been
saved will deliver undefined results.
</para>
</remarks>
<exception cref="T:System.Exception">
Thrown if selectionCriteria has an invalid syntax.
</exception>
<example>
<code>
using (ZipFile zip1 = ZipFile.Read(ZipFileName))
{
var UpdatedPhotoShopFiles = zip1.SelectEntries("*.psd", "UpdatedFiles");
foreach (ZipEntry e in UpdatedPhotoShopFiles)
{
// prompt for extract here
if (WantExtract(e.FileName))
e.Extract();
}
}
</code>
<code lang="VB">
Using zip1 As ZipFile = ZipFile.Read(ZipFileName)
Dim UpdatedPhotoShopFiles As ICollection(Of ZipEntry) = zip1.SelectEntries("*.psd", "UpdatedFiles")
Dim e As ZipEntry
For Each e In UpdatedPhotoShopFiles
' prompt for extract here
If Me.WantExtract(e.FileName) Then
e.Extract
End If
Next
End Using
</code>
</example>
<param name="selectionCriteria">the string that specifies which entries to select</param>
<param name="directoryPathInArchive">
the directory in the archive from which to select entries. If null, then
all directories in the archive are used.
</param>
<returns>a collection of ZipEntry objects that conform to the inclusion spec</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.RemoveSelectedEntries(System.String)">
<summary>
Remove entries from the zipfile by specified criteria.
</summary>
<remarks>
<para>
This method allows callers to remove the collection of entries from the zipfile
that fit the specified criteria. The criteria are described in a string format, and
can include patterns for the filename; constraints on the size of the entry;
constraints on the last modified, created, or last accessed time for the file
described by the entry; or the attributes of the entry.
</para>
<para>
For details on the syntax for the selectionCriteria parameter, see <see cref="M:Ionic.Zip.ZipFile.AddSelectedFiles(System.String)"/>.
</para>
<para>
This method is intended for use with a ZipFile that has been read from storage.
When creating a new ZipFile, this method will work only after the ZipArchive has
been Saved to the disk (the ZipFile class subsequently and implicitly reads the Zip
archive from storage.) Calling SelectEntries on a ZipFile that has not yet been
saved will deliver undefined results.
</para>
</remarks>
<exception cref="T:System.Exception">
Thrown if selectionCriteria has an invalid syntax.
</exception>
<example>
This example removes all entries in a zip file that were modified prior to January 1st, 2008.
<code>
using (ZipFile zip1 = ZipFile.Read(ZipFileName))
{
// remove all entries from prior to Jan 1, 2008
zip1.RemoveEntries("mtime &lt; 2008-01-01");
// don't forget to save the archive!
zip1.Save();
}
</code>
<code lang="VB">
Using zip As ZipFile = ZipFile.Read(ZipFileName)
' remove all entries from prior to Jan 1, 2008
zip1.RemoveEntries("mtime &lt; 2008-01-01")
' do not forget to save the archive!
zip1.Save
End Using
</code>
</example>
<param name="selectionCriteria">the string that specifies which entries to select</param>
<returns>the number of entries removed</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.RemoveSelectedEntries(System.String,System.String)">
<summary>
Remove entries from the zipfile by specified criteria, and within the specified
path in the archive.
</summary>
<remarks>
<para>
This method allows callers to remove the collection of entries from the zipfile
that fit the specified criteria. The criteria are described in a string format, and
can include patterns for the filename; constraints on the size of the entry;
constraints on the last modified, created, or last accessed time for the file
described by the entry; or the attributes of the entry.
</para>
<para>
For details on the syntax for the selectionCriteria parameter, see <see cref="M:Ionic.Zip.ZipFile.AddSelectedFiles(System.String)"/>.
</para>
<para>
This method is intended for use with a ZipFile that has been read from storage.
When creating a new ZipFile, this method will work only after the ZipArchive has
been Saved to the disk (the ZipFile class subsequently and implicitly reads the Zip
archive from storage.) Calling SelectEntries on a ZipFile that has not yet been
saved will deliver undefined results.
</para>
</remarks>
<exception cref="T:System.Exception">
Thrown if selectionCriteria has an invalid syntax.
</exception>
<example>
<code>
using (ZipFile zip1 = ZipFile.Read(ZipFileName))
{
// remove all entries from prior to Jan 1, 2008
zip1.RemoveEntries("mtime &lt; 2008-01-01", "documents");
// a call to ZipFile.Save will make the modifications permanent
zip1.Save();
}
</code>
<code lang="VB">
Using zip As ZipFile = ZipFile.Read(ZipFileName)
' remove all entries from prior to Jan 1, 2008
zip1.RemoveEntries("mtime &lt; 2008-01-01", "documents")
' a call to ZipFile.Save will make the modifications permanent
zip1.Save
End Using
</code>
</example>
<param name="selectionCriteria">the string that specifies which entries to select</param>
<param name="directoryPathInArchive">
the directory in the archive from which to select entries. If null, then
all directories in the archive are used.
</param>
<returns>the number of entries removed</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.ExtractSelectedEntries(System.String)">
<summary>
Selects and Extracts a set of Entries from the ZipFile.
</summary>
<remarks>
<para>
The entries are extracted into the current working directory.
</para>
<para>
If any of the files to be extracted already exist, then the action taken is as
specified in the <see cref="P:Ionic.Zip.ZipEntry.ExtractExistingFile"/> property on the
corresponding ZipEntry instance. By default, the action taken in this case is to
throw an exception.
</para>
<para>
For information on the syntax of the selectionCriteria string,
see <see cref="M:Ionic.Zip.ZipFile.AddSelectedFiles(System.String)"/>.
</para>
</remarks>
<example>
This example shows how extract all XML files modified after 15 January 2009.
<code>
using (ZipFile zip = ZipFile.Read(zipArchiveName))
{
zip.ExtractSelectedEntries("name = *.xml and mtime &gt; 2009-01-15");
}
</code>
</example>
<param name="selectionCriteria">the selection criteria for entries to extract.</param>
<seealso cref="M:Ionic.Zip.ZipFile.ExtractSelectedEntries(System.String,Ionic.Zip.ExtractExistingFileAction)"/>
</member>
<member name="M:Ionic.Zip.ZipFile.ExtractSelectedEntries(System.String,Ionic.Zip.ExtractExistingFileAction)">
<summary>
Selects and Extracts a set of Entries from the ZipFile.
</summary>
<remarks>
<para>
The entries are extracted into the current working directory. When extraction would would
overwrite an existing filesystem file, the action taken is as specified in the
<paramref name="extractExistingFile"/> parameter.
</para>
<para>
For information on the syntax of the string describing the entry selection criteria,
see <see cref="M:Ionic.Zip.ZipFile.AddSelectedFiles(System.String)"/>.
</para>
</remarks>
<example>
This example shows how extract all XML files modified after 15 January 2009,
overwriting any existing files.
<code>
using (ZipFile zip = ZipFile.Read(zipArchiveName))
{
zip.ExtractSelectedEntries("name = *.xml and mtime &gt; 2009-01-15",
ExtractExistingFileAction.OverwriteSilently);
}
</code>
</example>
<param name="selectionCriteria">the selection criteria for entries to extract.</param>
<param name="extractExistingFile">
The action to take if extraction would overwrite an existing file.
</param>
</member>
<member name="M:Ionic.Zip.ZipFile.ExtractSelectedEntries(System.String,System.String)">
<summary>
Selects and Extracts a set of Entries from the ZipFile.
</summary>
<remarks>
<para>
The entries are selected from the specified directory within the archive, and then
extracted into the current working directory.
</para>
<para>
If any of the files to be extracted already exist, then the action taken is as
specified in the <see cref="P:Ionic.Zip.ZipEntry.ExtractExistingFile"/> property on the
corresponding ZipEntry instance. By default, the action taken in this case is to
throw an exception.
</para>
<para>
For information on the syntax of the string describing the entry selection criteria,
see <see cref="M:Ionic.Zip.ZipFile.AddSelectedFiles(System.String)"/>.
</para>
</remarks>
<example>
This example shows how extract all XML files modified after 15 January 2009,
and writes them to the "unpack" directory.
<code>
using (ZipFile zip = ZipFile.Read(zipArchiveName))
{
zip.ExtractSelectedEntries("name = *.xml and mtime &gt; 2009-01-15","unpack");
}
</code>
</example>
<param name="selectionCriteria">the selection criteria for entries to extract.</param>
<param name="directoryPathInArchive">
the directory in the archive from which to select entries. If null, then
all directories in the archive are used.
</param>
<seealso cref="M:Ionic.Zip.ZipFile.ExtractSelectedEntries(System.String,System.String,System.String,Ionic.Zip.ExtractExistingFileAction)"/>
</member>
<member name="M:Ionic.Zip.ZipFile.ExtractSelectedEntries(System.String,System.String,System.String)">
<summary>
Selects and Extracts a set of Entries from the ZipFile.
</summary>
<remarks>
<para>
The entries are extracted into the specified directory. If any of the files to be
extracted already exist, an exception will be thrown.
</para>
<para>
For information on the syntax of the string describing the entry selection criteria,
see <see cref="M:Ionic.Zip.ZipFile.AddSelectedFiles(System.String)"/>.
</para>
</remarks>
<param name="selectionCriteria">the selection criteria for entries to extract.</param>
<param name="directoryInArchive">
the directory in the archive from which to select entries. If null, then
all directories in the archive are used.
</param>
<param name="extractDirectory">
the directory on the disk into which to extract. It will be created
if it does not exist.
</param>
</member>
<member name="M:Ionic.Zip.ZipFile.ExtractSelectedEntries(System.String,System.String,System.String,Ionic.Zip.ExtractExistingFileAction)">
<summary>
Selects and Extracts a set of Entries from the ZipFile.
</summary>
<remarks>
<para>
The entries are extracted into the specified directory. When extraction would would
overwrite an existing filesystem file, the action taken is as specified in the
<paramref name="extractExistingFile"/> parameter.
</para>
<para>
For information on the syntax of the string describing the entry selection criteria,
see <see cref="M:Ionic.Zip.ZipFile.AddSelectedFiles(System.String)"/>.
</para>
</remarks>
<example>
This example shows how extract all files with an XML extension or with a size larger than 100,000 bytes,
and puts them in the unpack directory. For any files that already exist in
that destination directory, they will not be overwritten.
<code>
using (ZipFile zip = ZipFile.Read(zipArchiveName))
{
zip.ExtractSelectedEntries("name = *.xml or size &gt; 100000",
null,
"unpack",
ExtractExistingFileAction.DontOverwrite);
}
</code>
</example>
<param name="selectionCriteria">the selection criteria for entries to extract.</param>
<param name="extractDirectory">
The directory on the disk into which to extract. It will be created if it does not exist.
</param>
<param name="directoryPathInArchive">
The directory in the archive from which to select entries. If null, then
all directories in the archive are used.
</param>
<param name="extractExistingFile">
The action to take if extraction would overwrite an existing file.
</param>
</member>
<member name="M:Ionic.Zip.ZipFile.ExtractAll(System.String)">
<summary>
Extracts all of the items in the zip archive, to the specified path in the
filesystem. The path can be relative or fully-qualified.
</summary>
<remarks>
<para>
This method will extract all entries in the <c>ZipFile</c> to the specified path.
</para>
<para>
If an extraction of a file from the zip archive would overwrite an existing
file in the filesystem, the action taken is dictated by the
ExtractExistingFile property, which overrides any setting you may have made
on individual ZipEntry instances. By default, if you have not set that
property on the <c>ZipFile</c> instance, the entry will not be extracted,
the existing file will not be overwritten and an exception will be
thrown. To change this, set the property, or use the <see cref="M:Ionic.Zip.ZipFile.ExtractAll(System.String,Ionic.Zip.ExtractExistingFileAction)"/>
overload that allows you to specify an ExtractExistingFileAction parameter.
</para>
<para>
The action to take when an extract would overwrite an existing file applies
to all entries. If you want to set this on a per-entry basis, then you must
use one of the <see cref="M:ZipEntry.Extract">ZipEntry.Extract</see> methods.
</para>
<para>
This method will send verbose output messages to the
<see cref="P:Ionic.Zip.ZipFile.StatusMessageTextWriter"/>, if it is set on the <c>ZipFile</c> instance.
</para>
<para>
You may wish to take advantage of the <c>ExtractProgress</c> event.
</para>
<para>
About Timestamps: When extracting a file entry from a zip archive, the
extracted file gets the last modified time of the entry as stored in the
archive. The archive may also store extended file timestamp information,
including last accessed and created times. If these are present in the
<c>ZipEntry</c>, then the extracted file will also get these times.
</para>
<para>
A Directory entry is somewhat different. It will get the times as described
for a file entry, but, if there are file entries in the zip archive that,
when extracted, appear in the just-created directory, then when those file
entries are extracted, the last modified and last accessed times of the
directory will change, as a side effect. The result is that after an
extraction of a directory and a number of files within the directory, the
last modified and last accessed timestamps on the directory will reflect the
time that the last file was extracted into the directory, rather than the
time stored in the zip archive for the directory.
</para>
<para>
To compensate, when extracting an archive with <c>ExtractAll</c>, DotNetZip
will extract all the file and directory entries as described above, but it
will then make a second pass on the directories, and reset the times on the
directories to reflect what is stored in the zip archive.
</para>
<para>
This compensation is performed only within the context of an
<c>ExtractAll</c>. If you call <c>ZipEntry.Extract</c> on a directory entry,
the timestamps on directory in the filesystem will reflect the times stored
in the zip. If you then call <c>ZipEntry.Extract</c> on a file entry, which
is extracted into the directory, the timestamps on the directory will be
updated to the current time.
</para>
</remarks>
<example>
This example extracts all the entries in a zip archive file, to the
specified target directory. The extraction will overwrite any existing
files silently.
<code>
String TargetDirectory= "unpack";
using(ZipFile zip= ZipFile.Read(ZipFileToExtract))
{
zip.ExtractExistingFile= ExtractExistingFileAction.OverwriteSilently;
zip.ExtractAll(TargetDirectory);
}
</code>
<code lang="VB">
Dim TargetDirectory As String = "unpack"
Using zip As ZipFile = ZipFile.Read(ZipFileToExtract)
zip.ExtractExistingFile= ExtractExistingFileAction.OverwriteSilently
zip.ExtractAll(TargetDirectory)
End Using
</code>
</example>
<seealso cref="E:Ionic.Zip.ZipFile.ExtractProgress"/>
<seealso cref="P:Ionic.Zip.ZipFile.ExtractExistingFile"/>
<param name="path">
The path to which the contents of the zipfile will be extracted.
The path can be relative or fully-qualified.
</param>
</member>
<member name="M:Ionic.Zip.ZipFile.ExtractAll(System.String,Ionic.Zip.ExtractExistingFileAction)">
<summary>
Extracts all of the items in the zip archive, to the specified path in the
filesystem, using the specified behavior when extraction would overwrite an
existing file.
</summary>
<remarks>
<para>
This method will extract all entries in the <c>ZipFile</c> to the specified
path. For an extraction that would overwrite an existing file, the behavior
is dictated by <paramref name="extractExistingFile"/>, which overrides any
setting you may have made on individual ZipEntry instances.
</para>
<para>
The action to take when an extract would overwrite an existing file
applies to all entries. If you want to set this on a per-entry basis,
then you must use <see cref="M:Ionic.Zip.ZipEntry.Extract(System.String,Ionic.Zip.ExtractExistingFileAction)"/> or one of the similar methods.
</para>
<para>
Calling this method is equivalent to setting the <see cref="P:Ionic.Zip.ZipFile.ExtractExistingFile"/> property and then calling <see cref="M:Ionic.Zip.ZipFile.ExtractAll(System.String)"/>.
</para>
<para>
This method will send verbose output messages to the
<see cref="P:Ionic.Zip.ZipFile.StatusMessageTextWriter"/>, if it is set on the <c>ZipFile</c> instance.
</para>
</remarks>
<example>
This example extracts all the entries in a zip archive file, to the
specified target directory. It does not overwrite any existing files.
<code>
String TargetDirectory= "c:\\unpack";
using(ZipFile zip= ZipFile.Read(ZipFileToExtract))
{
zip.ExtractAll(TargetDirectory, ExtractExistingFileAction.DontOverwrite);
}
</code>
<code lang="VB">
Dim TargetDirectory As String = "c:\unpack"
Using zip As ZipFile = ZipFile.Read(ZipFileToExtract)
zip.ExtractAll(TargetDirectory, ExtractExistingFileAction.DontOverwrite)
End Using
</code>
</example>
<param name="path">
The path to which the contents of the zipfile will be extracted.
The path can be relative or fully-qualified.
</param>
<param name="extractExistingFile">
The action to take if extraction would overwrite an existing file.
</param>
<seealso cref="M:Ionic.Zip.ZipFile.ExtractSelectedEntries(System.String,Ionic.Zip.ExtractExistingFileAction)"/>
</member>
<member name="M:Ionic.Zip.ZipFile.Read(System.String)">
<summary>
Reads a zip file archive and returns the instance.
</summary>
<remarks>
<para>
The stream is read using the default <c>System.Text.Encoding</c>, which is the
<c>IBM437</c> codepage.
</para>
</remarks>
<exception cref="T:System.Exception">
Thrown if the <c>ZipFile</c> 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>
<overloads>This method has a bunch of interesting overloads. They are all
static (Shared in VB). One of them is bound to be right for you. The
reason there are so many is that there are a few properties on the
<c>ZipFile</c> class that must be set before you read the zipfile in, for
them to be useful. The set of overloads covers the most interesting cases.
Probably there are still too many, though.</overloads>
<returns>The instance read from the zip archive.</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.Read(System.String,System.EventHandler{Ionic.Zip.ReadProgressEventArgs})">
<summary>
Reads a zip file archive and returns the instance, using the specified
ReadProgress event handler.
</summary>
<param name="fileName">
The name of the zip archive to open.
This can be a fully-qualified or relative pathname.
</param>
<param name="readProgress">
An event handler for Read operations.
</param>
<returns>The instance read from the zip archive.</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.Read(System.String,System.IO.TextWriter)">
<summary>
Reads a zip file archive using the specified text encoding, and returns the
instance.
</summary>
<remarks>
<para>
This version of the method allows the caller to pass in a <c>TextWriter</c>.
The ZipFile is read in using the default IBM437 encoding for entries where UTF-8
encoding is not explicitly specified.
</para>
</remarks>
<example>
<code lang="C#">
var sw = new System.IO.StringWriter();
using (ZipFile zip = ZipFile.Read("PackedDocuments.zip", sw))
{
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&lt;ZipEntry&gt;();
foreach (ZipEntry e in zip)
{
if (e.LastModified &lt; 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 sw As New System.IO.StringWriter
Using zip As ZipFile = ZipFile.Read("PackedDocuments.zip", sw)
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 &lt; 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="T: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="statusMessageWriter">
The <c>System.IO.TextWriter</c> to use for writing verbose status messages
during operations on the zip archive. A console application may wish to
pass <c>System.Console.Out</c> to get messages on the Console. A graphical
or headless application may wish to capture the messages in a different
<c>TextWriter</c>, such as a <c>System.IO.StringWriter</c>.
</param>
<returns>The instance read from the zip archive.</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.Read(System.String,System.IO.TextWriter,System.EventHandler{Ionic.Zip.ReadProgressEventArgs})">
<summary>
Reads a zip file archive using the specified text encoding, and the
specified ReadProgress event handler, and returns the instance.
</summary>
<param name="fileName">
The name of the zip archive to open.
This can be a fully-qualified or relative pathname.
</param>
<param name="readProgress">
An event handler for Read operations.
</param>
<param name="statusMessageWriter">
The <c>System.IO.TextWriter</c> to use for writing verbose status messages
during operations on the zip archive. A console application may wish to
pass <c>System.Console.Out</c> to get messages on the Console. A graphical
or headless application may wish to capture the messages in a different
<c>TextWriter</c>, such as a <c>System.IO.StringWriter</c>.
</param>
<returns>The instance read from the zip archive.</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.Read(System.String,System.Text.Encoding)">
<summary>
Reads a zip file archive using the specified text encoding, and returns the instance.
</summary>
<remarks>
<para>
This version of the method allows the caller to pass in an <c>Encoding</c>.
The ZipFile is read in using the specified encoding for entries where UTF-8
encoding is not explicitly specified.
</para>
</remarks>
<example>
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. For this code to work as
desired, 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.
<code lang="C#">
using (ZipFile zip = ZipFile.Read(ZipToExtract,
System.Text.Encoding.GetEncoding(950)))
{
foreach (ZipEntry e in zip)
{
e.Extract(extractDirectory);
}
}
</code>
<code lang="VB">
Using zip As ZipFile = ZipFile.Read(ZipToExtract, System.Text.Encoding.GetEncoding(950))
Dim e As ZipEntry
For Each e In zip
e.Extract(extractDirectory)
Next
End Using
</code>
</example>
<exception cref="T: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="encoding">
The <c>System.Text.Encoding</c> to use when reading in the zip archive. Be
careful specifying the encoding. If the value you use here is not the same
as the Encoding used when the zip archive was created (possibly by a
different archiver) you will get unexpected results and possibly exceptions.
</param>
<seealso cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/>.
<returns>The instance read from the zip archive.</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.Read(System.String,System.Text.Encoding,System.EventHandler{Ionic.Zip.ReadProgressEventArgs})">
<summary>
Reads a zip file archive using the specified text encoding and ReadProgress
event handler, and returns the instance.
</summary>
<param name="fileName">
The name of the zip archive to open.
This can be a fully-qualified or relative pathname.
</param>
<param name="readProgress">
An event handler for Read operations.
</param>
<param name="encoding">
The <c>System.Text.Encoding</c> to use when reading in the zip archive. Be
careful specifying the encoding. If the value you use here is not the same
as the Encoding used when the zip archive was created (possibly by a
different archiver) you will get unexpected results and possibly exceptions.
</param>
<returns>The instance read from the zip archive.</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.Read(System.String,System.IO.TextWriter,System.Text.Encoding)">
<summary>
Reads a zip file archive using the specified text encoding and the specified
TextWriter for status messages, and returns the instance.
</summary>
<remarks>
<para>
This version of the method allows the caller to pass in a <c>TextWriter</c>
and an <c>Encoding</c>. The ZipFile is read in using the specified encoding
for entries where UTF-8 encoding is not explicitly specified.
</para>
</remarks>
<example>
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.
<code lang="C#">
using (ZipFile zip = ZipFile.Read(ZipToExtract,
System.Console.Out,
System.Text.Encoding.GetEncoding(950)))
{
foreach (ZipEntry e in zip)
{
e.Extract(extractDirectory);
}
}
</code>
</example>
<exception cref="T: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="statusMessageWriter">
The <c>System.IO.TextWriter</c> to use for writing verbose status messages
during operations on the zip archive. A console application may wish to
pass <c>System.Console.Out</c> to get messages on the Console. A graphical
or headless application may wish to capture the messages in a different
<c>TextWriter</c>, such as a <c>System.IO.StringWriter</c>.
</param>
<param name="encoding">
The <c>System.Text.Encoding</c> to use when reading in the zip archive. Be
careful specifying the encoding. If the value you use here is not the same
as the Encoding used when the zip archive was created (possibly by a
different archiver) you will get unexpected results and possibly exceptions.
</param>
<seealso cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/>
<returns>The instance read from the zip archive.</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.Read(System.String,System.IO.TextWriter,System.Text.Encoding,System.EventHandler{Ionic.Zip.ReadProgressEventArgs})">
<summary>
Reads a zip file archive using the specified text encoding, the specified
TextWriter for status messages, and the specified ReadProgress event handler,
and returns the instance.
</summary>
<param name="fileName">
The name of the zip archive to open.
This can be a fully-qualified or relative pathname.
</param>
<param name="readProgress">
An event handler for Read operations.
</param>
<param name="statusMessageWriter">
The <c>System.IO.TextWriter</c> to use for writing verbose status messages
during operations on the zip archive. A console application may wish to
pass <c>System.Console.Out</c> to get messages on the Console. A graphical
or headless application may wish to capture the messages in a different
<c>TextWriter</c>, such as a <c>System.IO.StringWriter</c>.
</param>
<param name="encoding">
The <c>System.Text.Encoding</c> to use when reading in the zip archive. Be
careful specifying the encoding. If the value you use here is not the same
as the Encoding used when the zip archive was created (possibly by a
different archiver) you will get unexpected results and possibly exceptions.
</param>
<returns>The instance read from the zip archive.</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.Read(System.IO.Stream)">
<summary>
Reads a zip archive from a stream.
</summary>
<remarks>
<para>
This is useful when when the zip archive content is available from an
already-open stream. The stream must be open and readable when calling this
method. The stream is left open when the reading is completed.
</para>
<para>
Using this overload, the stream is read using the default
<c>System.Text.Encoding</c>, which is the <c>IBM437</c> codepage. If you
want to specify the encoding to use when reading the zipfile content, check
out the other overloads of the ZipFile constructor.
</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="T: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). 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>
<example>
<para>
This example shows how to Read zip content from a stream, and extract one
entry into a different stream. In this example, the filename
"NameOfEntryInArchive.doc", refers only to the name of the entry within the
zip archive. A file by that name is not created in the filesystem. The I/O
is done strictly with the given streams.
</para>
<code>
using (ZipFile zip = ZipFile.Read(InputStream))
{
zip.Extract("NameOfEntryInArchive.doc", OutputStream);
}
</code>
<code lang="VB">
Using zip as ZipFile = ZipFile.Read(InputStream)
zip.Extract("NameOfEntryInArchive.doc", OutputStream)
End Using
</code>
</example>
<param name="zipStream">the stream containing the zip data.</param>
<returns>an instance of ZipFile</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.Read(System.IO.Stream,System.EventHandler{Ionic.Zip.ReadProgressEventArgs})">
<summary>
Reads a zip archive from a stream, with a given ReadProgress event handler.
</summary>
<remarks>
<para>
When opening large zip archives, you may want to display a progress bar or
other indicator of status progress while reading. This Read() method allows
you to specify a ReadProgress Event Handler directly. The stream is read
using the default encoding (IBM437).
</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="T: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). 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="readProgress">
An event handler for Read operations.
</param>
<returns>an instance of ZipFile corresponding to the stream being read.</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.Read(System.IO.Stream,System.IO.TextWriter)">
<summary>
Reads a zip archive from a stream, using the specified TextWriter for status
messages.
</summary>
<remarks>
<para>
This method is useful when when the zip archive content is available from
an already-open stream. The stream must be open and readable when calling this
method. The stream is left open when the reading is completed.
</para>
<para>
The stream is read using the default <c>System.Text.Encoding</c>, which is
the <c>IBM437</c> codepage. For more information on the encoding, see the
<see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/> property.
</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="T: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). 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="statusMessageWriter">
The <c>System.IO.TextWriter</c> to which verbose status messages are written
during operations on the <c>ZipFile</c>. For example, in a console
application, System.Console.Out works, and will get a message for each entry
added to the ZipFile. If the TextWriter is <c>null</c>, no verbose messages
are written.
</param>
<returns>an instance of ZipFile</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.Read(System.IO.Stream,System.IO.TextWriter,System.EventHandler{Ionic.Zip.ReadProgressEventArgs})">
<summary>
Reads a zip archive from a stream, using the specified TextWriter for status
messages, and the specified ReadProgress event handler.
</summary>
<remarks>
<para>
The stream is read using the default <c>System.Text.Encoding</c>, which is
the <c>IBM437</c> codepage. For more information on the encoding, see the
<see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/> property.
</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="T: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). 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="statusMessageWriter">
The <c>System.IO.TextWriter</c> to which verbose status messages are written
during operations on the <c>ZipFile</c>. For example, in a console
application, System.Console.Out works, and will get a message for each entry
added to the ZipFile. If the TextWriter is <c>null</c>, no verbose messages
are written.
</param>
<param name="readProgress">
An event handler for Read operations.
</param>
<returns>an instance of ZipFile</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.Read(System.IO.Stream,System.Text.Encoding)">
<summary>
Reads a zip archive from a stream, using the specified encoding.
</summary>
<remarks>
<para>
This method is useful when when the zip archive content is available from
an already-open stream. The stream must be open and readable 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="T: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). 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="encoding">
The text encoding to use when reading entries that do not have the UTF-8
encoding bit set. Be careful specifying the encoding. If the value you use
here is not the same as the Encoding used when the zip archive was created
(possibly by a different archiver) you will get unexpected results and
possibly exceptions. See the <see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/>
property for more information.
</param>
<returns>an instance of ZipFile</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.Read(System.IO.Stream,System.Text.Encoding,System.EventHandler{Ionic.Zip.ReadProgressEventArgs})">
<summary>
Reads a zip archive from a stream, using the specified encoding, and
and the specified ReadProgress event handler.
</summary>
<remarks>
<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="T: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). 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="encoding">
The text encoding to use when reading entries that do not have the UTF-8
encoding bit set. Be careful specifying the encoding. If the value you use
here is not the same as the Encoding used when the zip archive was created
(possibly by a different archiver) you will get unexpected results and
possibly exceptions. See the <see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/>
property for more information.
</param>
<param name="readProgress">
An event handler for Read operations.
</param>
<returns>an instance of ZipFile</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.Read(System.IO.Stream,System.IO.TextWriter,System.Text.Encoding)">
<summary>
Reads a zip archive from a stream, using the specified text Encoding and the
specified TextWriter for status messages.
</summary>
<remarks>
<para>
This method is useful when when the zip archive content is available from an
already-open stream. The stream must be open and readable 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="T: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). 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="statusMessageWriter">
The <c>System.IO.TextWriter</c> to which verbose status messages are written
during operations on the <c>ZipFile</c>. For example, in a console
application, System.Console.Out works, and will get a message for each entry
added to the ZipFile. If the TextWriter is <c>null</c>, no verbose messages
are written.
</param>
<param name="encoding">
The text encoding to use when reading entries that do not have the UTF-8
encoding bit set. Be careful specifying the encoding. If the value you use
here is not the same as the Encoding used when the zip archive was created
(possibly by a different archiver) you will get unexpected results and
possibly exceptions. See the <see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/>
property for more information.
</param>
<returns>an instance of ZipFile</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.Read(System.IO.Stream,System.IO.TextWriter,System.Text.Encoding,System.EventHandler{Ionic.Zip.ReadProgressEventArgs})">
<summary>
Reads a zip archive from a stream, using the specified text Encoding, the
specified TextWriter for status messages,
and the specified ReadProgress event handler.
</summary>
<remarks>
<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="T: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). 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="statusMessageWriter">
The <c>System.IO.TextWriter</c> to which verbose status messages are written
during operations on the <c>ZipFile</c>. For example, in a console
application, System.Console.Out works, and will get a message for each entry
added to the ZipFile. If the TextWriter is <c>null</c>, no verbose messages
are written.
</param>
<param name="encoding">
The text encoding to use when reading entries that do not have the UTF-8
encoding bit set. Be careful specifying the encoding. If the value you use
here is not the same as the Encoding used when the zip archive was created
(possibly by a different archiver) you will get unexpected results and
possibly exceptions. See the <see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/>
property for more information.
</param>
<param name="readProgress">
An event handler for Read operations.
</param>
<returns>an instance of ZipFile</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.Read(System.Byte[])">
<summary>
Reads a zip archive from a byte array.
</summary>
<remarks>
This is useful when the data for the zipfile is contained in a byte array,
for example, downloaded from an FTP server without being saved to a
filesystem.
</remarks>
<param name="buffer">
The byte array containing the zip data.
(I don't know why, but sometimes the compiled helpfile (.chm) indicates a 2d
array when it is just one-dimensional. This is a one-dimensional array.)
</param>
<returns>
an instance of ZipFile. The name on the <c>ZipFile</c> will be <c>null</c>
(<c>Nothing</c> in VB).
</returns>
<seealso cref="M:Ionic.Zip.ZipFile.Read(System.IO.Stream)"/>
</member>
<member name="M:Ionic.Zip.ZipFile.Read(System.Byte[],System.IO.TextWriter)">
<summary>
Reads a zip archive from a byte array, using the given StatusMessageWriter.
</summary>
<remarks>
<para>
This method is useful when the data for the zipfile is contained in a byte
array, for example when retrieving the data from a database or other
non-filesystem store. The default Text Encoding (IBM437) is used to read
the zipfile data.
</para>
</remarks>
<param name="buffer">the byte array containing the zip data.</param>
<param name="statusMessageWriter">
The <c>System.IO.TextWriter</c> to which verbose status messages are written
during operations on the <c>ZipFile</c>. For example, in a console
application, System.Console.Out works, and will get a message for each entry
added to the ZipFile. If the TextWriter is <c>null</c>, no verbose messages
are written.
</param>
<returns>
an instance of ZipFile. The name is set to <c>null</c> (<c>Nothing</c> in VB).
</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.Read(System.Byte[],System.IO.TextWriter,System.Text.Encoding)">
<summary>
Reads a zip archive from a byte array, using the given StatusMessageWriter and text Encoding.
</summary>
<remarks>
<para>
This method is useful when the data for the zipfile is contained in a byte
array, for example when retrieving the data from a database or other
non-filesystem store.
</para>
</remarks>
<param name="buffer">the byte array containing the zip data.</param>
<param name="statusMessageWriter">
The <c>System.IO.TextWriter</c> to which verbose status messages are written
during operations on the <c>ZipFile</c>. For example, in a console
application, System.Console.Out works, and will get a message for each entry
added to the ZipFile. If the TextWriter is <c>null</c>, no verbose messages
are written.
</param>
<param name="encoding">
The text encoding to use when reading entries that do not have the UTF-8
encoding bit set. Be careful specifying the encoding. If the value you use
here is not the same as the Encoding used when the zip archive was created
(possibly by a different archiver) you will get unexpected results and
possibly exceptions. See the <see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/>
property for more information.
</param>
<returns>
an instance of ZipFile. The name is set to <c>null</c> (<c>Nothing</c> in VB).
</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.IsZipFile(System.String)">
<summary>
Checks the given file to see if it appears to be a valid zip file.
</summary>
<remarks>
<para>
Calling this method is equivalent to calling <see cref="M:Ionic.Zip.ZipFile.IsZipFile(System.String,System.Boolean)"/> with the testExtract parameter set to false.
</para>
</remarks>
<param name="fileName">The file to check.</param>
<returns>true if the file appears to be a zip file.</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.IsZipFile(System.String,System.Boolean)">
<summary>
Checks a file to see if it is a valid zip file.
</summary>
<remarks>
<para>
This method opens the specified zip file, reads in the zip archive,
verifying the ZIP metadata as it reads.
</para>
<para>
If everything succeeds, then the method returns true. If anything fails -
for example if an incorrect signature or CRC is found, indicating a
corrupt file, the the method returns false. This method also returns
false for a file that does not exist.
</para>
<para>
If <paramref name="testExtract"/> is true, as part of its check, this
method reads in the content for each entry, expands it, and checks CRCs.
This provides an additional check beyond verifying the zip header and
directory data.
</para>
<para>
If <paramref name="testExtract"/> is true, and if any of the zip entries
are protected with a password, this method will return false. If you want
to verify a <c>ZipFile</c> that has entries which are protected with a
password, you will need to do that manually.
</para>
</remarks>
<param name="fileName">The zip file to check.</param>
<param name="testExtract">true if the caller wants to extract each entry.</param>
<returns>true if the file contains a valid zip file.</returns>
</member>
<member name="M:Ionic.Zip.ZipFile.IsZipFile(System.IO.Stream,System.Boolean)">
<summary>
Checks a stream to see if it contains a valid zip archive.
</summary>
<remarks>
<para>
This method reads the zip archive contained in the specified stream, verifying
the ZIP metadata as it reads. If testExtract is true, this method also extracts
each entry in the archive, dumping all the bits into <see cref="F:System.IO.Stream.Null"/>.
</para>
<para>
If everything succeeds, then the method returns true. If anything fails -
for example if an incorrect signature or CRC is found, indicating a corrupt
file, the the method returns false. This method also returns false for a
file that does not exist.
</para>
<para>
If <c>testExtract</c> is true, this method reads in the content for each
entry, expands it, and checks CRCs. This provides an additional check
beyond verifying the zip header data.
</para>
<para>
If <c>testExtract</c> is true, and if any of the zip entries are protected
with a password, this method will return false. If you want to verify a
ZipFile that has entries which are protected with a password, you will need
to do that manually.
</para>
</remarks>
<seealso cref="M:Ionic.Zip.ZipFile.IsZipFile(System.String,System.Boolean)"/>
<param name="stream">The stream to check.</param>
<param name="testExtract">true if the caller wants to extract each entry.</param>
<returns>true if the stream contains a valid zip archive.</returns>
</member>
<member name="P:Ionic.Zip.ZipFile.FullScan">
<summary>
Indicates whether to perform a full scan of the zip file when reading it.
</summary>
<remarks>
<para>
You almost never want to use this property.
</para>
<para>
When reading a zip file, if this flag is <c>true</c> (<c>True</c> in
VB), the entire zip archive will be scanned and searched for entries.
For large archives, this can take a very, long time. The much more
efficient default behavior is to read the zip directory, which is
stored at the end of the zip file. But, in some cases the directory is
corrupted and you need to perform a full scan of the zip file to
determine the contents of the zip file. This property lets you do
that, when necessary.
</para>
<para>
This flag is effective only when calling <see cref="M:Ionic.Zip.ZipFile.Initialize(System.String)"/>. Normally you would read a ZipFile with the
static <see cref="M:Ionic.Zip.ZipFile.Read(System.String)">ZipFile.Read</see>
method. But you can't set the <c>FullScan</c> property on the
<c>ZipFile</c> instance when you use a static factory method like
<c>ZipFile.Read</c>.
</para>
</remarks>
<example>
This example shows how to read a zip file using the full scan approach,
and then save it, thereby producing a corrected zip file.
<code lang="C#">
using (var zip = new ZipFile())
{
zip.FullScan = true;
zip.Initialize(zipFileName);
zip.Save(newName);
}
</code>
<code lang="VB">
Using zip As New ZipFile
zip.FullScan = True
zip.Initialize(zipFileName)
zip.Save(newName)
End Using
</code>
</example>
</member>
<member name="P:Ionic.Zip.ZipFile.SortEntriesBeforeSaving">
<summary>
Whether to sort the ZipEntries before saving the file.
</summary>
<remarks>
The default is false. If you have a large number of zip entries, the sort
alone can consume significant time.
</remarks>
<example>
<code lang="C#">
using (var zip = new ZipFile())
{
zip.AddFiles(filesToAdd);
zip.SortEntriesBeforeSaving = true;
zip.Save(name);
}
</code>
<code lang="VB">
Using zip As New ZipFile
zip.AddFiles(filesToAdd)
zip.SortEntriesBeforeSaving = True
zip.Save(name)
End Using
</code>
</example>
</member>
<member name="P:Ionic.Zip.ZipFile.AddDirectoryWillTraverseReparsePoints">
<summary>
Indicates whether NTFS Reparse Points, like junctions, should be
traversed during calls to <c>AddDirectory()</c>.
</summary>
<remarks>
By default, calls to AddDirectory() will traverse NTFS reparse
points, like mounted volumes, and directory junctions. An example
of a junction is the "My Music" directory in Windows Vista. In some
cases you may not want DotNetZip to traverse those directories. In
that case, set this property to false.
</remarks>
<example>
<code lang="C#">
using (var zip = new ZipFile())
{
zip.AddDirectoryWillTraverseReparsePoints = false;
zip.AddDirectory(dirToZip,"fodder");
zip.Save(zipFileToCreate);
}
</code>
</example>
</member>
<member name="P:Ionic.Zip.ZipFile.BufferSize">
<summary>
Size of the IO buffer used while saving.
</summary>
<remarks>
<para>
First, let me say that you really don't need to bother with this. It is
here to allow for optimizations that you probably won't make! It will work
fine if you don't set or get this property at all. Ok?
</para>
<para>
Now that we have <em>that</em> out of the way, the fine print: This
property affects the size of the buffer that is used for I/O for each
entry contained in the zip file. When a file is read in to be compressed,
it uses a buffer given by the size here. When you update a zip file, the
data for unmodified entries is copied from the first zip file to the
other, through a buffer given by the size here.
</para>
<para>
Changing the buffer size affects a few things: first, for larger buffer
sizes, the memory used by the <c>ZipFile</c>, obviously, will be larger
during I/O operations. This may make operations faster for very much
larger files. Last, for any given entry, when you use a larger buffer
there will be fewer progress events during I/O operations, because there's
one progress event generated for each time the buffer is filled and then
emptied.
</para>
<para>
The default buffer size is 8k. Increasing the buffer size may speed
things up as you compress larger files. But there are no hard-and-fast
rules here, eh? You won't know til you test it. And there will be a
limit where ever larger buffers actually slow things down. So as I said
in the beginning, it's probably best if you don't set or get this property
at all.
</para>
</remarks>
<example>
This example shows how you might set a large buffer size for efficiency when
dealing with zip entries that are larger than 1gb.
<code lang="C#">
using (ZipFile zip = new ZipFile())
{
zip.SaveProgress += this.zip1_SaveProgress;
zip.AddDirectory(directoryToZip, "");
zip.UseZip64WhenSaving = Zip64Option.Always;
zip.BufferSize = 65536*8; // 65536 * 8 = 512k
zip.Save(ZipFileToCreate);
}
</code>
</example>
</member>
<member name="P:Ionic.Zip.ZipFile.CodecBufferSize">
<summary>
Size of the work buffer to use for the ZLIB codec during compression.
</summary>
<remarks>
Setting this affects the performance and memory efficiency of compression
and decompression. For larger files, setting this to a larger size may
improve performance, but the exact numbers vary depending on available
memory, and a bunch of other variables. I don't have good firm
recommendations on how to set it. You'll have to test it yourself. Or
just leave it alone and accept the default.
</remarks>
</member>
<member name="P:Ionic.Zip.ZipFile.FlattenFoldersOnExtract">
<summary>
Indicates whether extracted files should keep their paths as
stored in the zip archive.
</summary>
<remarks>
<para>
This property affects Extraction. It is not used when creating zip
archives.
</para>
<para>
With this property set to <c>false</c>, the default, extracting entries
from a zip file will create files in the filesystem that have the full
path associated to the entry within the zip file. With this property set
to <c>true</c>, extracting entries from the zip file results in files
with no path: the folders are "flattened."
</para>
<para>
An example: suppose the zip file contains entries /directory1/file1.txt and
/directory2/file2.txt. With <c>FlattenFoldersOnExtract</c> set to false,
the files created will be \directory1\file1.txt and \directory2\file2.txt.
With the property set to true, the files created are file1.txt and file2.txt.
</para>
</remarks>
</member>
<member name="P:Ionic.Zip.ZipFile.Strategy">
<summary>
The compression strategy to use for all entries.
</summary>
<remarks>
Set the Strategy used by the ZLIB-compatible compressor, when compressing
entries. Different compression strategies work better on different sorts
of data. The strategy parameter can affect the compression ratio and the
speed of compression but not the correctness of the compresssion. For
more information see <see cref="T:Ionic.Zlib.CompressionStrategy">Ionic.Zlib.CompressionStrategy</see>.
</remarks>
</member>
<member name="P:Ionic.Zip.ZipFile.Name">
<summary>
The name of the <c>ZipFile</c>, on disk.
</summary>
<remarks>
<para>
When the <c>ZipFile</c> instance was created by reading an archive using
one of the <c>ZipFile.Read</c> methods, this property represents the name
of the zip file that was read. When the <c>ZipFile</c> instance was
created by using the no-argument constructor, this value is <c>null</c>
(<c>Nothing</c> in VB).
</para>
<para>
If you use the no-argument constructor, and you then explicitly set this
property, when you call <see cref="M:Ionic.Zip.ZipFile.Save"/>, this name will
specify the name of the zip file created. Doing so is equivalent to
calling <see cref="M:Ionic.Zip.ZipFile.Save(System.String)"/>. When instantiating a
<c>ZipFile</c> by reading from a stream or byte array, the <c>Name</c>
property remains <c>null</c>. When saving to a stream, the <c>Name</c>
property is implicitly set to <c>null</c>.
</para>
</remarks>
</member>
<member name="P:Ionic.Zip.ZipFile.CompressionLevel">
<summary>
Sets the compression level to be used for entries subsequently added to
the zip archive.
</summary>
<remarks>
<para>
Varying the compression level used on entries can affect the
size-vs-speed tradeoff when compression and decompressing data streams
or files.
</para>
<para>
As with some other properties on the <c>ZipFile</c> class, like <see cref="P:Ionic.Zip.ZipFile.Password"/>, <see cref="P:Ionic.Zip.ZipFile.Encryption"/>, and <see cref="P:Ionic.Zip.ZipFile.ZipErrorAction"/>, setting this property on a <c>ZipFile</c>
instance will cause the specified <c>CompressionLevel</c> to be used on all
<see cref="T:Ionic.Zip.ZipEntry"/> items that are subsequently added to the
<c>ZipFile</c> instance. If you set this property after you have added
items to the <c>ZipFile</c>, but before you have called <c>Save()</c>,
those items will not use the specified compression level.
</para>
<para>
If you do not set this property, the default compression level is used,
which normally gives a good balance of compression efficiency and
compression speed. In some tests, using <c>BestCompression</c> can
double the time it takes to compress, while delivering just a small
increase in compression efficiency. This behavior will vary with the
type of data you compress. If you are in doubt, just leave this setting
alone, and accept the default.
</para>
</remarks>
</member>
<member name="P:Ionic.Zip.ZipFile.Comment">
<summary>
A comment attached to the zip archive.
</summary>
<remarks>
<para>
This property is read/write. It allows the application to specify a
comment for the <c>ZipFile</c>, or read the comment for the
<c>ZipFile</c>. After setting this property, changes are only made
permanent when you call a <c>Save()</c> method.
</para>
<para>
According to <see href="http://www.pkware.com/documents/casestudies/APPNOTE.TXT">PKWARE's
zip specification</see>, the comment is not encrypted, even if there is a
password set on the zip file.
</para>
<para>
The zip spec does not describe how to encode the comment string in a code
page other than IBM437. Therefore, for "compliant" zip tools and
libraries, comments will use IBM437. However, there are situations where
you want an encoded Comment, for example using code page 950 "Big-5
Chinese". DotNetZip will encode the comment in the code page specified by
<see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/>, at the time of the call to
<c>ZipFile.Save()</c>.
</para>
<para>
When creating a zip archive using this library, it is possible to change
the value of <see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/> between each
entry you add, and between adding entries and the call to
<c>Save()</c>. Don't do this. It will likely result in a zip file that is
not readable by any tool or application. For best interoperability, leave
<see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/> alone, or specify it only
once, before adding any entries to the <c>ZipFile</c> instance.
</para>
</remarks>
</member>
<member name="P:Ionic.Zip.ZipFile.EmitTimesInWindowsFormatWhenSaving">
<summary>
Specifies whether the Creation, Access, and Modified times for entries
added to the zip file will be emitted in "Windows format" when the zip
archive is saved.
</summary>
<remarks>
<para>
An application creating a zip archive can use this flag to explicitly
specify that the file times for the entries should or should not be stored
in the zip archive in the format used by Windows. By default this flag is
<c>true</c>, meaning the Windows-format times are stored in the zip
archive.
</para>
<para>
When adding an entry from a file or directory, the Creation (<see cref="P:Ionic.Zip.ZipEntry.CreationTime"/>), Access (<see cref="P:Ionic.Zip.ZipEntry.AccessedTime"/>), and Modified (<see cref="P:Ionic.Zip.ZipEntry.ModifiedTime"/>) times for the given entry are
automatically set from the filesystem values. When adding an entry from a
stream or string, all three values are implicitly set to
<c>DateTime.Now</c>. Applications can also explicitly set those times by
calling <see cref="M:Ionic.Zip.ZipEntry.SetEntryTimes(System.DateTime,System.DateTime,System.DateTime)"/>.
</para>
<para>
<see href="http://www.pkware.com/documents/casestudies/APPNOTE.TXT">PKWARE's
zip specification</see> describes multiple ways to format these times in a
zip file. One is the format Windows applications normally use: 100ns ticks
since January 1, 1601 UTC. The other is a format Unix applications typically
use: seconds since January 1, 1970 UTC. Each format can be stored in an
"extra field" in the zip entry when saving the zip archive. The former
uses an extra field with a Header Id of 0x000A, while the latter uses a
header ID of 0x5455, although you probably don't need to know that.
</para>
<para>
Not all tools and libraries can interpret these fields. Windows
compressed folders is one that can read the Windows Format timestamps,
while I believe <see href="http://www.info-zip.org/">the Infozip
tools</see> can read the Unix format timestamps. Some tools and libraries
may be able to read only one or the other. DotNetZip can read or write
times in either or both formats.
</para>
<para>
The times stored are taken from <see cref="P:Ionic.Zip.ZipEntry.ModifiedTime"/>, <see cref="P:Ionic.Zip.ZipEntry.AccessedTime"/>, and <see cref="P:Ionic.Zip.ZipEntry.CreationTime"/>.
</para>
<para>
The value set here applies to all entries subsequently added to the
<c>ZipFile</c>.
</para>
<para>
This property is not mutually exclusive of the <see cref="P:Ionic.Zip.ZipFile.EmitTimesInUnixFormatWhenSaving"/> property. It is possible and
legal and valid to produce a zip file that contains timestamps encoded in
the Unix format as well as in the Windows format, in addition to the <see cref="P:Ionic.Zip.ZipEntry.LastModified">LastModified</see> time attached to each
entry in the archive, a time that is always stored in "DOS format". And,
notwithstanding the names PKWare uses for these time formats, any of them
can be read and written by any computer, on any operating system. But,
there are no guarantees that a program running on Mac or Linux will
gracefully handle a zip file with "Windows" formatted times, or that an
application that does not use DotNetZip but runs on Windows will be able to
handle file times in Unix format.
</para>
<para>
When in doubt, test. Sorry, I haven't got a complete list of tools and
which sort of timestamps they can use and will tolerate. If you get any
good information and would like to pass it on, please do so and I will
include that information in this documentation.
</para>
</remarks>
<example>
This example shows how to save a zip file that contains file timestamps
in a format normally used by Unix.
<code lang="C#">
using (var zip = new ZipFile())
{
// produce a zip file the Mac will like
zip.EmitTimesInWindowsFormatWhenSaving = false;
zip.EmitTimesInUnixFormatWhenSaving = true;
zip.AddDirectory(directoryToZip, "files");
zip.Save(outputFile);
}
</code>
<code lang="VB">
Using zip As New ZipFile
'' produce a zip file the Mac will like
zip.EmitTimesInWindowsFormatWhenSaving = False
zip.EmitTimesInUnixFormatWhenSaving = True
zip.AddDirectory(directoryToZip, "files")
zip.Save(outputFile)
End Using
</code>
</example>
<seealso cref="P:Ionic.Zip.ZipEntry.EmitTimesInWindowsFormatWhenSaving"/>
<seealso cref="P:Ionic.Zip.ZipFile.EmitTimesInUnixFormatWhenSaving"/>
</member>
<member name="P:Ionic.Zip.ZipFile.EmitTimesInUnixFormatWhenSaving">
<summary>
Specifies whether the Creation, Access, and Modified times
for entries added to the zip file will be emitted in "Unix(tm)
format" when the zip archive is saved.
</summary>
<remarks>
<para>
An application creating a zip archive can use this flag to explicitly
specify that the file times for the entries should or should not be stored
in the zip archive in the format used by Unix. By default this flag is
<c>false</c>, meaning the Unix-format times are not stored in the zip
archive.
</para>
<para>
When adding an entry from a file or directory, the Creation (<see cref="P:Ionic.Zip.ZipEntry.CreationTime"/>), Access (<see cref="P:Ionic.Zip.ZipEntry.AccessedTime"/>), and Modified (<see cref="P:Ionic.Zip.ZipEntry.ModifiedTime"/>) times for the given entry are
automatically set from the filesystem values. When adding an entry from a
stream or string, all three values are implicitly set to DateTime.Now.
Applications can also explicitly set those times by calling <see cref="M:Ionic.Zip.ZipEntry.SetEntryTimes(System.DateTime,System.DateTime,System.DateTime)"/>.
</para>
<para>
<see href="http://www.pkware.com/documents/casestudies/APPNOTE.TXT">PKWARE's
zip specification</see> describes multiple ways to format these times in a
zip file. One is the format Windows applications normally use: 100ns ticks
since January 1, 1601 UTC. The other is a format Unix applications
typically use: seconds since January 1, 1970 UTC. Each format can be
stored in an "extra field" in the zip entry when saving the zip
archive. The former uses an extra field with a Header Id of 0x000A, while
the latter uses a header ID of 0x5455, although you probably don't need to
know that.
</para>
<para>
Not all tools and libraries can interpret these fields. Windows
compressed folders is one that can read the Windows Format timestamps,
while I believe the <see href="http://www.info-zip.org/">Infozip</see>
tools can read the Unix format timestamps. Some tools and libraries may be
able to read only one or the other. DotNetZip can read or write times in
either or both formats.
</para>
<para>
The times stored are taken from <see cref="P:Ionic.Zip.ZipEntry.ModifiedTime"/>, <see cref="P:Ionic.Zip.ZipEntry.AccessedTime"/>, and <see cref="P:Ionic.Zip.ZipEntry.CreationTime"/>.
</para>
<para>
This property is not mutually exclusive of the <see cref="P:Ionic.Zip.ZipFile.EmitTimesInWindowsFormatWhenSaving"/> property. It is possible and
legal and valid to produce a zip file that contains timestamps encoded in
the Unix format as well as in the Windows format, in addition to the <see cref="P:Ionic.Zip.ZipEntry.LastModified">LastModified</see> time attached to each
entry in the zip archive, a time that is always stored in "DOS
format". And, notwithstanding the names PKWare uses for these time
formats, any of them can be read and written by any computer, on any
operating system. But, there are no guarantees that a program running on
Mac or Linux will gracefully handle a zip file with "Windows" formatted
times, or that an application that does not use DotNetZip but runs on
Windows will be able to handle file times in Unix format.
</para>
<para>
When in doubt, test. Sorry, I haven't got a complete list of tools and
which sort of timestamps they can use and will tolerate. If you get any
good information and would like to pass it on, please do so and I will
include that information in this documentation.
</para>
</remarks>
<seealso cref="P:Ionic.Zip.ZipEntry.EmitTimesInUnixFormatWhenSaving"/>
<seealso cref="P:Ionic.Zip.ZipFile.EmitTimesInWindowsFormatWhenSaving"/>
</member>
<member name="P:Ionic.Zip.ZipFile.Verbose">
<summary>
Indicates whether verbose output is sent to the <see cref="P:Ionic.Zip.ZipFile.StatusMessageTextWriter"/> during <c>AddXxx()</c> and
<c>ReadXxx()</c> operations.
</summary>
<remarks>
This is a <em>synthetic</em> property. It returns true if the <see cref="P:Ionic.Zip.ZipFile.StatusMessageTextWriter"/> is non-null.
</remarks>
</member>
<member name="P:Ionic.Zip.ZipFile.CaseSensitiveRetrieval">
<summary>
Indicates whether to perform case-sensitive matching on the filename when
retrieving entries in the zipfile via the string-based indexer.
</summary>
<remarks>
The default value is <c>false</c>, which means don't do case-sensitive
matching. In other words, retrieving zip["ReadMe.Txt"] is the same as
zip["readme.txt"]. It really makes sense to set this to <c>true</c> only
if you are not running on Windows, which has case-insensitive
filenames. But since this library is not built for non-Windows platforms,
in most cases you should just leave this property alone.
</remarks>
</member>
<member name="P:Ionic.Zip.ZipFile.UseUnicodeAsNecessary">
<summary>
Indicates whether to encode entry filenames and entry comments using Unicode
(UTF-8).
</summary>
<remarks>
<para>
<see href="http://www.pkware.com/documents/casestudies/APPNOTE.TXT">The
PKWare zip specification</see> provides for encoding file names and file
comments in either the IBM437 code page, or in UTF-8. This flag selects
the encoding according to that specification. By default, this flag is
false, and filenames and comments are encoded into the zip file in the
IBM437 codepage. Setting this flag to true will specify that filenames
and comments that cannot be encoded with IBM437 will be encoded with
UTF-8.
</para>
<para>
Zip files created with strict adherence to the PKWare specification with
respect to UTF-8 encoding can contain entries with filenames containing
any combination of Unicode characters, including the full range of
characters from Chinese, Latin, Hebrew, Greek, Cyrillic, and many other
alphabets. However, because at this time, the UTF-8 portion of the PKWare
specification is not broadly supported by other zip libraries and
utilities, such zip files may not be readable by your favorite zip tool or
archiver. In other words, interoperability will decrease if you set this
flag to true.
</para>
<para>
In particular, Zip files created with strict adherence to the PKWare
specification with respect to UTF-8 encoding will not work well with
Explorer in Windows XP or Windows Vista, because Windows compressed
folders, as far as I know, do not support UTF-8 in zip files. Vista can
read the zip files, but shows the filenames incorrectly. Unpacking from
Windows Vista Explorer will result in filenames that have rubbish
characters in place of the high-order UTF-8 bytes.
</para>
<para>
Also, zip files that use UTF-8 encoding will not work well with Java
applications that use the java.util.zip classes, as of v5.0 of the Java
runtime. The Java runtime does not correctly implement the PKWare
specification in this regard.
</para>
<para>
As a result, we have the unfortunate situation that "correct" behavior by
the DotNetZip library with regard to Unicode encoding of filenames during
zip creation will result in zip files that are readable by strictly
compliant and current tools (for example the most recent release of the
commercial WinZip tool); but these zip files will not be readable by
various other tools or libraries, including Windows Explorer.
</para>
<para>
The DotNetZip library can read and write zip files with UTF8-encoded
entries, according to the PKware spec. If you use DotNetZip for both
creating and reading the zip file, and you use UTF-8, there will be no
loss of information in the filenames. For example, using a self-extractor
created by this library will allow you to unpack files correctly with no
loss of information in the filenames.
</para>
<para>
If you do not set this flag, it will remain false. If this flag is false,
your <c>ZipFile</c> will encode all filenames and comments using the
IBM437 codepage. This can cause "loss of information" on some filenames,
but the resulting zipfile will be more interoperable with other
utilities. As an example of the loss of information, diacritics can be
lost. The o-tilde character will be down-coded to plain o. The c with a
cedilla (Unicode 0xE7) used in Portugese will be downcoded to a c.
Likewise, the O-stroke character (Unicode 248), used in Danish and
Norwegian, will be down-coded to plain o. Chinese characters cannot be
represented in codepage IBM437; when using the default encoding, Chinese
characters in filenames will be represented as ?. These are all examples
of "information loss".
</para>
<para>
The loss of information associated to the use of the IBM437 encoding is
inconvenient, and can also lead to runtime errors. For example, using
IBM437, any sequence of 4 Chinese characters will be encoded as ????. If
your application creates a <c>ZipFile</c>, then adds two files, each with
names of four Chinese characters each, this will result in a duplicate
filename exception. In the case where you add a single file with a name
containing four Chinese characters, calling Extract() on the entry that
has question marks in the filename will result in an exception, because
the question mark is not legal for use within filenames on Windows. These
are just a few examples of the problems associated to loss of information.
</para>
<para>
This flag is independent of the encoding of the content within the entries
in the zip file. Think of the zip file as a container - it supports an
encoding. Within the container are other "containers" - the file entries
themselves. The encoding within those entries is independent of the
encoding of the zip archive container for those entries.
</para>
<para>
Rather than specify the encoding in a binary fashion using this flag, an
application can specify an arbitrary encoding via the <see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/> property. Setting the encoding
explicitly when creating zip archives will result in non-compliant zip
files that, curiously, are fairly interoperable. The challenge is, the
PKWare specification does not provide for a way to specify that an entry
in a zip archive uses a code page that is neither IBM437 nor UTF-8.
Therefore if you set the encoding explicitly when creating a zip archive,
you must take care upon reading the zip archive to use the same code page.
If you get it wrong, the behavior is undefined and may result in incorrect
filenames, exceptions, stomach upset, hair loss, and acne.
</para>
</remarks>
<seealso cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/>
</member>
<member name="P:Ionic.Zip.ZipFile.UseZip64WhenSaving">
<summary>
Specify whether to use ZIP64 extensions when saving a zip archive.
</summary>
<remarks>
<para>
When creating a zip file, the default value for the property is <see cref="F:Ionic.Zip.Zip64Option.Never"/>. <see cref="F:Ionic.Zip.Zip64Option.AsNecessary"/> is
safest, in the sense that you will not get an Exception if a pre-ZIP64
limit is exceeded.
</para>
<para>
You may set the property at any time before calling Save().
</para>
<para>
When reading a zip file via the <c>Zipfile.Read()</c> method, DotNetZip
will properly read ZIP64-endowed zip archives, regardless of the value of
this property. DotNetZip will always read ZIP64 archives. This property
governs only whether DotNetZip will write them. Therefore, when updating
archives, be careful about setting this property after reading an archive
that may use ZIP64 extensions.
</para>
<para>
An interesting question is, if you have set this property to
<c>AsNecessary</c>, and then successfully saved, does the resulting
archive use ZIP64 extensions or not? To learn this, check the <see cref="P:Ionic.Zip.ZipFile.OutputUsedZip64"/> property, after calling <c>Save()</c>.
</para>
<para>
Have you thought about
<see href="http://cheeso.members.winisp.net/DotNetZipDonate.aspx">donating</see>?
</para>
</remarks>
<seealso cref="P:Ionic.Zip.ZipFile.RequiresZip64"/>
</member>
<member name="P:Ionic.Zip.ZipFile.RequiresZip64">
<summary>
Indicates whether the archive requires ZIP64 extensions.
</summary>
<remarks>
<para>
This property is <c>null</c> (or <c>Nothing</c> in VB) if the archive has
not been saved, and there are fewer than 65334 <c>ZipEntry</c> items
contained in the archive.
</para>
<para>
The <c>Value</c> is true if any of the following four conditions holds:
the uncompressed size of any entry is larger than 0xFFFFFFFF; the
compressed size of any entry is larger than 0xFFFFFFFF; the relative
offset of any entry within the zip archive is larger than 0xFFFFFFFF; or
there are more than 65534 entries in the archive. (0xFFFFFFFF =
4,294,967,295). The result may not be known until a <c>Save()</c> is attempted
on the zip archive. The Value of this <see cref="T:System.Nullable"/>
property may be set only AFTER one of the Save() methods has been called.
</para>
<para>
If none of the four conditions holds, and the archive has been saved, then
the <c>Value</c> is false.
</para>
<para>
A <c>Value</c> of false does not indicate that the zip archive, as saved,
does not use ZIP64. It merely indicates that ZIP64 is not required. An
archive may use ZIP64 even when not required if the <see cref="P:Ionic.Zip.ZipFile.UseZip64WhenSaving"/> property is set to <see cref="F:Ionic.Zip.Zip64Option.Always"/>, or if the <see cref="P:Ionic.Zip.ZipFile.UseZip64WhenSaving"/> property is set to <see cref="F:Ionic.Zip.Zip64Option.AsNecessary"/> and the output stream was not
seekable. Use the <see cref="P:Ionic.Zip.ZipFile.OutputUsedZip64"/> property to determine if
the most recent <c>Save()</c> method resulted in an archive that utilized
the ZIP64 extensions.
</para>
</remarks>
<seealso cref="P:Ionic.Zip.ZipFile.UseZip64WhenSaving"/>
<seealso cref="P:Ionic.Zip.ZipFile.OutputUsedZip64"/>
</member>
<member name="P:Ionic.Zip.ZipFile.OutputUsedZip64">
<summary>
Indicates whether the most recent <c>Save()</c> operation used ZIP64 extensions.
</summary>
<remarks>
<para>
The use of ZIP64 extensions within an archive is not always necessary, and
for interoperability concerns, it may be desired to NOT use ZIP64 if
possible. The <see cref="P:Ionic.Zip.ZipFile.UseZip64WhenSaving"/> property can be
set to use ZIP64 extensions only when necessary. In those cases,
Sometimes applications want to know whether a Save() actually used ZIP64
extensions. Applications can query this read-only property to learn
whether ZIP64 has been used in a just-saved <c>ZipFile</c>.
</para>
<para>
The value is <c>null</c> (or <c>Nothing</c> in VB) if the archive has not
been saved.
</para>
<para>
Non-null values (<c>HasValue</c> is true) indicate whether ZIP64
extensions were used during the most recent <c>Save()</c> operation. The
ZIP64 extensions may have been used as required by any particular entry
because of its uncompressed or compressed size, or because the archive is
larger than 4294967295 bytes, or because there are more than 65534 entries
in the archive, or because the <c>UseZip64WhenSaving</c> property was set
to <see cref="F:Ionic.Zip.Zip64Option.Always"/>, or because the
<c>UseZip64WhenSaving</c> property was set to <see cref="F:Ionic.Zip.Zip64Option.AsNecessary"/> and the output stream was not seekable.
The value of this property does not indicate the reason the ZIP64
extensions were used.
</para>
</remarks>
<seealso cref="P:Ionic.Zip.ZipFile.UseZip64WhenSaving"/>
<seealso cref="P:Ionic.Zip.ZipFile.RequiresZip64"/>
</member>
<member name="P:Ionic.Zip.ZipFile.InputUsesZip64">
<summary>
Indicates whether the most recent <c>Read()</c> operation read a zip file that uses
ZIP64 extensions.
</summary>
<remarks>
This property will return null (Nothing in VB) if you've added an entry after reading
the zip file.
</remarks>
</member>
<member name="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding">
<summary>
The text encoding to use when writing new entries to the <c>ZipFile</c>,
for those entries that cannot be encoded with the default (IBM437)
encoding; or, the text encoding that was used when reading the entries
from the <c>ZipFile</c>.
</summary>
<remarks>
<para>
In <see href="http://www.pkware.com/documents/casestudies/APPNOTE.TXT">its
zip specification</see>, PKWare describes two options for encoding
filenames and comments: using IBM437 or UTF-8. But, some archiving tools
or libraries do not follow the specification, and instead encode
characters using the system default code page. For example, WinRAR when
run on a machine in Shanghai may encode filenames with the Big-5 Chinese
(950) code page. This behavior is contrary to the Zip specification, but
it occurs anyway.
</para>
<para>
When using DotNetZip to write zip archives that will be read by one of
these other archivers, set this property to specify the code page to use
when encoding the <see cref="P:Ionic.Zip.ZipEntry.FileName"/> and <see cref="P:Ionic.Zip.ZipEntry.Comment"/> for each <c>ZipEntry</c> in the zip file, for
values that cannot be encoded with the default codepage for zip files,
IBM437. This is why this property is "provisional". In all cases, IBM437
is used where possible, in other words, where no loss of data would
result. It is possible, therefore, to have a given entry with a
<c>Comment</c> encoded in IBM437 and a <c>FileName</c> encoded with the
specified "provisional" codepage.
</para>
<para>
Be aware that a zip file created after you've explicitly set the <see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/> property to a value other than
IBM437 may not be compliant to the PKWare specification, and may not be
readable by compliant archivers. On the other hand, many (most?)
archivers are non-compliant and can read zip files created in arbitrary
code pages. The trick is to use or specify the proper codepage when
reading the zip.
</para>
<para>
When creating a zip archive using this library, it is possible to change
the value of <see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/> between each
entry you add, and between adding entries and the call to
<c>Save()</c>. Don't do this. It will likely result in a zipfile that is
not readable. For best interoperability, either leave <see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/> alone, or specify it only once,
before adding any entries to the <c>ZipFile</c> instance. There is one
exception to this recommendation, described later.
</para>
<para>
When using an arbitrary, non-UTF8 code page for encoding, there is no
standard way for the creator application - whether DotNetZip, WinZip,
WinRar, or something else - to formally specify in the zip file which
codepage has been used for the entries. As a result, readers of zip files
are not able to inspect the zip file and determine the codepage that was
used for the entries contained within it. It is left to the application
or user to determine the necessary codepage when reading zip files encoded
this way. In other words, if you explicitly specify the codepage when you
create the zipfile, you must explicitly specify the same codepage when
reading the zipfile.
</para>
<para>
The way you specify the code page to use when reading a zip file varies
depending on the tool or library you use to read the zip. In DotNetZip,
you use a ZipFile.Read() method that accepts an encoding parameter. It
isn't possible with Windows Explorer, as far as I know, to specify an
explicit codepage to use when reading a zip. If you use an incorrect
codepage when reading a zipfile, you will get entries with filenames that
are incorrect, and the incorrect filenames may even contain characters
that are not legal for use within filenames in Windows. Extracting entries
with illegal characters in the filenames will lead to exceptions. It's too
bad, but this is just the way things are with code pages in zip
files. Caveat Emptor.
</para>
<para>
Example: Suppose you create a zipfile that contains entries with
filenames that have Danish characters. If you use <see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/> equal to "iso-8859-1" (cp 28591),
the filenames will be correctly encoded in the zip. But, to read that
zipfile correctly, you have to specify the same codepage at the time you
read it. If try to read that zip file with Windows Explorer or another
application that is not flexible with respect to the codepage used to
decode filenames in zipfiles, you will get a filename like "Inf°.txt".
</para>
<para>
When using DotNetZip to read a zip archive, and the zip archive uses an
arbitrary code page, you must specify the encoding to use before or when
the <c>Zipfile</c> is READ. This means you must use a <c>ZipFile.Read()</c>
method that allows you to specify a System.Text.Encoding parameter. Setting
the ProvisionalAlternateEncoding property after your application has read in
the zip archive will not affect the entry names of entries that have already
been read in.
</para>
<para>
And now, the exception to the rule described above. One strategy for
specifying the code page for a given zip file is to describe the code page
in a human-readable form in the Zip comment. For example, the comment may
read "Entries in this archive are encoded in the Big5 code page". For
maximum interoperability, the zip comment in this case should be encoded
in the default, IBM437 code page. In this case, the zip comment is
encoded using a different page than the filenames. To do this, Specify
<c>ProvisionalAlternateEncoding</c> to your desired region-specific code
page, once before adding any entries, and then reset
<c>ProvisionalAlternateEncoding</c> to IBM437 before setting the <see cref="P:Ionic.Zip.ZipFile.Comment"/> property and calling Save().
</para>
</remarks>
<example>
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. For this code to work as
desired, the <c>Zipfile</c> 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 <c>ZipFile.Read()</c>, then names of entries within the
zip archive would not be correctly retrieved.
<code>
using (var zip = ZipFile.Read(zipFileName, System.Text.Encoding.GetEncoding("big5")))
{
// retrieve and extract an entry using a name encoded with CP950
zip[MyDesiredEntry].Extract("unpack");
}
</code>
<code lang="VB">
Using zip As ZipFile = ZipFile.Read(ZipToExtract, System.Text.Encoding.GetEncoding("big5"))
' retrieve and extract an entry using a name encoded with CP950
zip(MyDesiredEntry).Extract("unpack")
End Using
</code>
</example>
<seealso cref="F:Ionic.Zip.ZipFile.DefaultEncoding">DefaultEncoding</seealso>
</member>
<member name="P:Ionic.Zip.ZipFile.StatusMessageTextWriter">
<summary>
Gets or sets the <c>TextWriter</c> to which status messages are delivered
for the instance.
</summary>
<remarks>
If the TextWriter is set to a non-null value, then verbose output is sent
to the <c>TextWriter</c> during <c>Add</c><c>, Read</c><c>, Save</c> and
<c>Extract</c> operations. Typically, console applications might use
<c>Console.Out</c> and graphical or headless applications might use a
<c>System.IO.StringWriter</c>. The output of this is suitable for viewing
by humans.
</remarks>
<example>
<para>
In this example, a console application instantiates a <c>ZipFile</c>, then
sets the <c>StatusMessageTextWriter</c> to <c>Console.Out</c>. At that
point, all verbose status messages for that <c>ZipFile</c> are sent to the
console.
</para>
<code lang="C#">
using (ZipFile zip= ZipFile.Read(FilePath))
{
zip.StatusMessageTextWriter= System.Console.Out;
// messages are sent to the console during extraction
zip.ExtractAll();
}
</code>
<code lang="VB">
Using zip As ZipFile = ZipFile.Read(FilePath)
zip.StatusMessageTextWriter= System.Console.Out
'Status Messages will be sent to the console during extraction
zip.ExtractAll()
End Using
</code>
<para>
In this example, a Windows Forms application instantiates a
<c>ZipFile</c>, then sets the <c>StatusMessageTextWriter</c> to a
<c>StringWriter</c>. At that point, all verbose status messages for that
<c>ZipFile</c> are sent to the <c>StringWriter</c>.
</para>
<code lang="C#">
var sw = new System.IO.StringWriter();
using (ZipFile zip= ZipFile.Read(FilePath))
{
zip.StatusMessageTextWriter= sw;
zip.ExtractAll();
}
Console.WriteLine("{0}", sw.ToString());
</code>
<code lang="VB">
Dim sw as New System.IO.StringWriter
Using zip As ZipFile = ZipFile.Read(FilePath)
zip.StatusMessageTextWriter= sw
zip.ExtractAll()
End Using
'Status Messages are now available in sw
</code>
</example>
</member>
<member name="P:Ionic.Zip.ZipFile.TempFileFolder">
<summary>
Gets or sets the name for the folder to store the temporary file
this library writes when saving a zip archive.
</summary>
<remarks>
<para>
This library will create a temporary file when saving a Zip archive to a
file. This file is written when calling one of the <c>Save()</c> methods
that does not save to a stream, or one of the <c>SaveSelfExtractor()</c>
methods.
</para>
<para>
By default, the library will create the temporary file in the directory
specified for the file itself, via the <see cref="P:Ionic.Zip.ZipFile.Name"/> property or via
the <see cref="M:Ionic.Zip.ZipFile.Save(System.String)"/> method.
</para>
<para>
Setting this property allows applications to override this default
behavior, so that the library will create the temporary file in the
specified folder. For example, to have the library create the temporary
file in the current working directory, regardless where the <c>ZipFile</c>
is saved, specfy ".". To revert to the default behavior, set this
property to <c>null</c> (<c>Nothing</c> in VB).
</para>
<para>
When setting the property to a non-null value, the folder specified must
exist; if it does not an exception is thrown. The application should have
write and delete permissions on the folder. The permissions are not
explicitly checked ahead of time; if the application does not have the
appropriate rights, an exception will be thrown at the time <c>Save()</c>
is called.
</para>
<para>
There is no temporary file created when reading a zip archive. When
saving to a Stream, there is no temporary file created. For example, if
the application is an ASP.NET application and calls <c>Save()</c>
specifying the <c>Response.OutputStream</c> as the output stream, there is
no temporary file created.
</para>
</remarks>
<exception cref="T:System.IO.FileNotFoundException">
Thrown when setting the property if the directory does not exist.
</exception>
</member>
<member name="P:Ionic.Zip.ZipFile.Password">
<summary>
Sets the password to be used on the <c>ZipFile</c> instance.
</summary>
<remarks>
<para>
When writing a zip archive, this password is applied to the entries, not
to the zip archive itself. It applies to any <c>ZipEntry</c> subsequently
added to the <c>ZipFile</c>, using one of the <c>AddFile</c>,
<c>AddDirectory</c>, <c>AddEntry</c>, or <c>AddItem</c> methods, etc.
When reading a zip archive, this property applies to any entry
subsequently extracted from the <c>ZipFile</c> using one of the Extract
methods on the <c>ZipFile</c> class.
</para>
<para>
When writing a zip archive, keep this in mind: though the password is set
on the ZipFile object, according to the Zip spec, the "directory" of the
archive - in other words the list of entries or files contained in the archive - is
not encrypted with the password, or protected in any way. If you set the
Password property, the password actually applies to individual entries
that are added to the archive, subsequent to the setting of this property.
The list of filenames in the archive that is eventually created will
appear in clear text, but the contents of the individual files are
encrypted. This is how Zip encryption works.
</para>
<para>
One simple way around this limitation is to simply double-wrap sensitive
filenames: Store the files in a zip file, and then store that zip file
within a second, "outer" zip file. If you apply a password to the outer
zip file, then readers will be able to see that the outer zip file
contains an inner zip file. But readers will not be able to read the
directory or file list of the inner zip file.
</para>
<para>
If you set the password on the <c>ZipFile</c>, and then add a set of files
to the archive, then each entry is encrypted with that password. You may
also want to change the password between adding different entries. If you
set the password, add an entry, then set the password to <c>null</c>
(<c>Nothing</c> in VB), and add another entry, the first entry is
encrypted and the second is not. If you call <c>AddFile()</c>, then set
the <c>Password</c> property, then call <c>ZipFile.Save</c>, the file
added will not be password-protected, and no warning will be generated.
</para>
<para>
When setting the Password, you may also want to explicitly set the <see cref="P:Ionic.Zip.ZipFile.Encryption"/> property, to specify how to encrypt the entries added
to the ZipFile. If you set the Password to a non-null value and do not
set <see cref="P:Ionic.Zip.ZipFile.Encryption"/>, then PKZip 2.0 ("Weak") encryption is used.
This encryption is relatively weak but is very interoperable. If you set
the password to a <c>null</c> value (<c>Nothing</c> in VB), Encryption is
reset to None.
</para>
<para>
All of the preceding applies to writing zip archives, in other words when
you use one of the Save methods. To use this property when reading or an
existing ZipFile, do the following: set the Password property on the
<c>ZipFile</c>, then call one of the Extract() overloads on the <see cref="T:Ionic.Zip.ZipEntry"/>. In this case, the entry is extracted using the
<c>Password</c> that is specified on the <c>ZipFile</c> instance. If you
have not set the <c>Password</c> property, then the password is
<c>null</c>, and the entry is extracted with no password.
</para>
<para>
If you set the Password property on the <c>ZipFile</c>, then call
<c>Extract()</c> an entry that has not been encrypted with a password, the
password is not used for that entry, and the <c>ZipEntry</c> is extracted
as normal. In other words, the password is used only if necessary.
</para>
<para>
The <see cref="T:Ionic.Zip.ZipEntry"/> class also has a <see cref="P:Ionic.Zip.ZipEntry.Password">Password</see> property. It takes precedence
over this property on the <c>ZipFile</c>. Typically, you would use the
per-entry Password when most entries in the zip archive use one password,
and a few entries use a different password. If all entries in the zip
file use the same password, then it is simpler to just set this property
on the <c>ZipFile</c> itself, whether creating a zip archive or extracting
a zip archive.
</para>
</remarks>
<example>
<para>
This example creates a zip file, using password protection for the
entries, and then extracts the entries from the zip file. When creating
the zip file, the Readme.txt file is not protected with a password, but
the other two are password-protected as they are saved. During extraction,
each file is extracted with the appropriate password.
</para>
<code>
// create a file with encryption
using (ZipFile zip = new ZipFile())
{
zip.AddFile("ReadMe.txt");
zip.Password= "!Secret1";
zip.AddFile("MapToTheSite-7440-N49th.png");
zip.AddFile("2008-Regional-Sales-Report.pdf");
zip.Save("EncryptedArchive.zip");
}
// extract entries that use encryption
using (ZipFile zip = ZipFile.Read("EncryptedArchive.zip"))
{
zip.Password= "!Secret1";
zip.ExtractAll("extractDir");
}
</code>
<code lang="VB">
Using zip As New ZipFile
zip.AddFile("ReadMe.txt")
zip.Password = "123456!"
zip.AddFile("MapToTheSite-7440-N49th.png")
zip.Password= "!Secret1";
zip.AddFile("2008-Regional-Sales-Report.pdf")
zip.Save("EncryptedArchive.zip")
End Using
' extract entries that use encryption
Using (zip as ZipFile = ZipFile.Read("EncryptedArchive.zip"))
zip.Password= "!Secret1"
zip.ExtractAll("extractDir")
End Using
</code>
</example>
<seealso cref="P:Ionic.Zip.ZipFile.Encryption">ZipFile.Encryption</seealso>
<seealso cref="P:Ionic.Zip.ZipEntry.Password">ZipEntry.Password</seealso>
</member>
<member name="P:Ionic.Zip.ZipFile.ExtractExistingFile">
<summary>
The action the library should take when extracting a file that already
exists.
</summary>
<remarks>
<para>
This property affects the behavior of the Extract methods (one of the
<c>Extract()</c> or <c>ExtractWithPassword()</c> overloads), when
extraction would would overwrite an existing filesystem file. If you do
not set this property, the library throws an exception when extracting an
entry would overwrite an existing file.
</para>
<para>
This property has no effect when extracting to a stream, or when the file
to be extracted does not already exist.
</para>
</remarks>
<seealso cref="P:Ionic.Zip.ZipEntry.ExtractExistingFile"/>
</member>
<member name="P:Ionic.Zip.ZipFile.ZipErrorAction">
<summary>
The action the library should take when an error is encountered while
opening or reading files as they are saved into a zip archive.
</summary>
<remarks>
<para>
Errors can occur as a file is being saved to the zip archive. For
example, the File.Open may fail, or a File.Read may fail, because of
lock conflicts or other reasons.
</para>
<para>
The first problem might occur after having called AddDirectory() on a
directory that contains a Clipper .dbf file; the file is locked by
Clipper and cannot be opened for read by another process. An example of
the second problem might occur when trying to zip a .pst file that is in
use by Microsoft Outlook. Outlook locks a range on the file, which allows
other processes to open the file, but not read it in its entirety.
</para>
<para>
This property tells DotNetZip what you would like to do in the case of
these errors. The primary options are: <c>ZipErrorAction.Throw</c> to
throw an exception (this is the default behavior if you don't set this
property); <c>ZipErrorAction.Skip</c> to Skip the file for which there
was an error and continue saving; <c>ZipErrorAction.Retry</c> to Retry
the entry that caused the problem; or
<c>ZipErrorAction.InvokeErrorEvent</c> to invoke an event handler.
</para>
<para>
This property is implicitly set to <c>ZipErrorAction.InvokeErrorEvent</c>
if you add a handler to the <see cref="E:Ionic.Zip.ZipFile.ZipError"/> event. If you set
this property to something other than
<c>ZipErrorAction.InvokeErrorEvent</c>, then the <c>ZipError</c>
event is implicitly cleared. What it means is you can set one or the
other (or neither), depending on what you want, but you never need to set
both.
</para>
<para>
As with some other properties on the <c>ZipFile</c> class, like <see cref="P:Ionic.Zip.ZipFile.Password"/>, <see cref="P:Ionic.Zip.ZipFile.Encryption"/>, and <see cref="P:Ionic.Zip.ZipFile.CompressionLevel"/>, setting this property on a <c>ZipFile</c>
instance will cause the specified <c>ZipErrorAction</c> to be used on all
<see cref="T:Ionic.Zip.ZipEntry"/> items that are subsequently added to the
<c>ZipFile</c> instance. If you set this property after you have added
items to the <c>ZipFile</c>, but before you have called <c>Save()</c>,
those items will not use the specified error handling action.
</para>
<para>
If you want to handle any errors that occur with any entry in the zip
file in the same way, then set this property once, before adding any
entries to the zip archive.
</para>
<para>
If you set this property to <c>ZipErrorAction.Skip</c> and you'd like to
learn which files may have been skipped after a <c>Save()</c>, you can
set the <see cref="P:Ionic.Zip.ZipFile.StatusMessageTextWriter"/> on the ZipFile before
calling <c>Save()</c>. A message will be emitted into that writer for
each skipped file, if any.
</para>
</remarks>
<example>
This example shows how to tell DotNetZip to skip any files for which an
error is generated during the Save().
<code lang="VB">
Public Sub SaveZipFile()
Dim SourceFolder As String = "fodder"
Dim DestFile As String = "eHandler.zip"
Dim sw as New StringWriter
Using zipArchive As ZipFile = New ZipFile
' Tell DotNetZip to skip any files for which it encounters an error
zipArchive.ZipErrorAction = ZipErrorAction.Skip
zipArchive.StatusMessageTextWriter = sw
zipArchive.AddDirectory(SourceFolder)
zipArchive.Save(DestFile)
End Using
' examine sw here to see any messages
End Sub
</code>
</example>
<seealso cref="P:Ionic.Zip.ZipEntry.ZipErrorAction"/>
<seealso cref="E:Ionic.Zip.ZipFile.ZipError"/>
</member>
<member name="P:Ionic.Zip.ZipFile.Encryption">
<summary>
The Encryption to use for entries added to the <c>ZipFile</c>.
</summary>
<remarks>
<para>
Set this when creating a zip archive, or when updating a zip archive. The
specified Encryption is applied to the entries subsequently added to the
<c>ZipFile</c> instance. Applications do not need to set the
<c>Encryption</c> property when reading or extracting a zip archive.
</para>
<para>
If you set this to something other than EncryptionAlgorithm.None, you
will also need to set the <see cref="P:Ionic.Zip.ZipFile.Password"/>.
</para>
<para>
As with some other properties on the <c>ZipFile</c> class, like <see cref="P:Ionic.Zip.ZipFile.Password"/> and <see cref="P:Ionic.Zip.ZipFile.CompressionLevel"/>, setting this
property on a <c>ZipFile</c> instance will cause the specified
<c>EncryptionAlgorithm</c> to be used on all <see cref="T:Ionic.Zip.ZipEntry"/> items
that are subsequently added to the <c>ZipFile</c> instance. In other
words, if you set this property after you have added items to the
<c>ZipFile</c>, but before you have called <c>Save()</c>, those items will
not be encrypted or protected with a password in the resulting zip
archive. To get a zip archive with encrypted entries, set this property,
along with the <see cref="P:Ionic.Zip.ZipFile.Password"/> property, before calling
<c>AddFile</c>, <c>AddItem</c>, or <c>AddDirectory</c> (etc.) on the
<c>ZipFile</c> instance.
</para>
<para>
If you read a <c>ZipFile</c>, you can modify the <c>Encryption</c> on an
encrypted entry, only by setting the <c>Encryption</c> property on the
<c>ZipEntry</c> itself. Setting the <c>Encryption</c> property on the
<c>ZipFile</c>, once it has been created via a call to
<c>ZipFile.Read()</c>, does not affect entries that were previously read.
</para>
<para>
For example, suppose you read a <c>ZipFile</c>, and there is an encrypted
entry. Setting the <c>Encryption</c> property on that <c>ZipFile</c> and
then calling <c>Save()</c> on the <c>ZipFile</c> does not update the
<c>Encryption</c> used for the entries in the archive. Neither is an
exception thrown. Instead, what happens during the <c>Save()</c> is that
all previously existing entries are copied through to the new zip archive,
with whatever encryption and password that was used when originally
creating the zip archive. Upon re-reading that archive, to extract
entries, applications should use the original password or passwords, if
any.
</para>
<para>
Suppose an application reads a <c>ZipFile</c>, and there is an encrypted
entry. Setting the <c>Encryption</c> property on that <c>ZipFile</c> and
then adding new entries (via <c>AddFile()</c>, <c>AddEntry()</c>, etc)
and then calling <c>Save()</c> on the <c>ZipFile</c> does not update the
<c>Encryption</c> on any of the entries that had previously been in the
<c>ZipFile</c>. The <c>Encryption</c> property applies only to the
newly-added entries.
</para>
</remarks>
<example>
<para>
This example creates a zip archive that uses encryption, and then extracts
entries from the archive. When creating the zip archive, the ReadMe.txt
file is zipped without using a password or encryption. The other files
use encryption.
</para>
<code>
// Create a zip archive with AES Encryption.
using (ZipFile zip = new ZipFile())
{
zip.AddFile("ReadMe.txt");
zip.Encryption= EncryptionAlgorithm.WinZipAes256;
zip.Password= "Top.Secret.No.Peeking!";
zip.AddFile("7440-N49th.png");
zip.AddFile("2008-Regional-Sales-Report.pdf");
zip.Save("EncryptedArchive.zip");
}
// Extract a zip archive that uses AES Encryption.
// You do not need to specify the algorithm during extraction.
using (ZipFile zip = ZipFile.Read("EncryptedArchive.zip"))
{
zip.Password= "Top.Secret.No.Peeking!";
zip.ExtractAll("extractDirectory");
}
</code>
<code lang="VB">
' Create a zip that uses Encryption.
Using zip As New ZipFile()
zip.Encryption= EncryptionAlgorithm.WinZipAes256
zip.Password= "Top.Secret.No.Peeking!"
zip.AddFile("ReadMe.txt")
zip.AddFile("7440-N49th.png")
zip.AddFile("2008-Regional-Sales-Report.pdf")
zip.Save("EncryptedArchive.zip")
End Using
' Extract a zip archive that uses AES Encryption.
' You do not need to specify the algorithm during extraction.
Using (zip as ZipFile = ZipFile.Read("EncryptedArchive.zip"))
zip.Password= "Top.Secret.No.Peeking!"
zip.ExtractAll("extractDirectory")
End Using
</code>
</example>
<seealso cref="P:Ionic.Zip.ZipFile.Password">ZipFile.Password</seealso>
<seealso cref="P:Ionic.Zip.ZipEntry.Encryption">ZipEntry.Encryption</seealso>
</member>
<member name="P:Ionic.Zip.ZipFile.SetCompression">
<summary>
A callback that allows the application to specify the compression level
to use for entries subsequently added to the zip archive.
</summary>
<remarks>
<para>
With this callback, the DotNetZip library allows the application to
determine whether compression will be used, at the time of the <c>Save</c>. This
may be useful if the application wants to favor speed over size, and wants
to defer the decision until the time of <c>Save</c>.
</para>
<para>
Typically applications set the <see cref="P:Ionic.Zip.ZipFile.CompressionLevel"/> property on
the <c>ZipFile</c> or on each <c>ZipEntry</c> to determine the level of
compression used. This is done at the time the entry is added to the
<c>ZipFile</c>. Setting the property to
<c>Ionic.Zlib.CompressionLevel.None</c> means no compression will be used.
</para>
<para>
This callback allows the application to defer the decision on the
<c>CompressionLevel</c> to use, until the time of the call to
<c>ZipFile.Save()</c>. The callback is invoked once per <c>ZipEntry</c>,
at the time the data for the entry is being written out as part of a
<c>Save()</c> operation. The application can use whatever criteria it
likes in determining the level to return. For example, an application may
wish that no .mp3 files should be compressed, because they are already
compressed and the extra compression is not worth the CPU time incurred,
and so can return <c>None</c> for all .mp3 entries.
</para>
<para>
The library determines whether compression will be attempted for an entry
this way: If the entry is a zero length file, or a directory, no
compression is used. Otherwise, if this callback is set, it is invoked
and the <c>CompressionLevel</c> is set to the return value. If this
callback has not been set, then the previously set value for
<c>CompressionLevel</c> is used.
</para>
</remarks>
</member>
<member name="P:Ionic.Zip.ZipFile.MaxOutputSegmentSize">
<summary>
The maximum size of an output segment, when saving a split Zip file.
</summary>
<remarks>
<para>
Set this to a non-zero value before calling <see cref="M:Ionic.Zip.ZipFile.Save"/> or <see cref="M:Ionic.Zip.ZipFile.Save(System.String)"/> to specify that the ZipFile should be saved as a
split archive, also sometimes called a spanned archive. Some also
call them multi-file archives.
</para>
<para>
A split zip archive is saved in a set of discrete filesystem files,
rather than in a single file. This is handy when transmitting the
archive in email or some other mechanism that has file size limits. The
first file in a split archive will be named <c>basename.z01</c>, the
second will be named <c>basename.z02</c>, and so on. The final file is
named <c>basename.zip</c>.
</para>
<para>
The value of this property determines the maximum size of a split
segment when writing a split archive. According to the zip
specification from PKWare, the minimum value is 65536, for a 64k segment
size. For example, suppose you have a <c>ZipFile</c> that would save to
a single file of 200k. If you set the <c>MaxOutputSegmentSize</c> to
65536 before calling <c>Save()</c>, you will get four distinct output
files. On the other hand if you set this property to 256k, then you will
get a single-file archive for that <c>ZipFile</c>.
</para>
<para>
The size of each split output file will often but not always be exactly
the maximum size set here. The zip specification requires that some data
fields in a zip archive may not span a split boundary. An output segment
may be not completely filled if necessary to avoid that problem. Also,
obviously the final segment of the archive may be smaller than the
maximum segment size. Segments will never be larger than the value set
with this property.
</para>
<para>
You can save a split Zip file only when saving to a regular filesystem
file. It's not possible to save a split zip file as a self-extracting
archive, nor is it possible to save a split zip file to a stream. When
saving to a SFX or to a Stream, this property is ignored.
</para>
<para>
About interoperability: Split or spanned zip files produced by DotNetZip
can be read by WinZip or PKZip, and vice-versa. Segmented zip files may
not be readable by other tools, if those other tools don't support zip
spanning or splitting. When in doubt, test. I don't believe Windows
Explorer can extract a split archive.
</para>
<para>
This property has no effect when reading a split archive. You can read
a split archive in the normal way with DotNetZip.
</para>
<para>
When saving a zip file, if you want a regular zip file rather than a
split zip file, don't set this property, or set it to Zero.
</para>
<para>
If you read a split archive, with <see cref="M:Ionic.Zip.ZipFile.Read(System.String)"/> and
then subsequently call <c>ZipFile.Save()</c>, unless you set this
property before calling <c>Save()</c>, you will get a normal,
single-file archive.
</para>
</remarks>
<seealso cref="P:Ionic.Zip.ZipFile.NumberOfSegmentsForMostRecentSave"/>
</member>
<member name="P:Ionic.Zip.ZipFile.NumberOfSegmentsForMostRecentSave">
<summary>
Returns the number of segments used in the most recent Save() operation.
</summary>
<remarks>
<para>
This is normally zero, unless you have set the <see cref="P:Ionic.Zip.ZipFile.MaxOutputSegmentSize"/> property. If you have set <see cref="P:Ionic.Zip.ZipFile.MaxOutputSegmentSize"/>, and then you save a file, after the call to
Save() completes, you can read this value to learn the number of segments that
were created.
</para>
<para>
If you call Save("Archive.zip"), and it creates 5 segments, then you
will have filesystem files named Archive.z01, Archive.z02, Archive.z03,
Archive.z04, and Archive.zip, and the value of this property will be 5.
</para>
</remarks>
<seealso cref="P:Ionic.Zip.ZipFile.MaxOutputSegmentSize"/>
</member>
<member name="P:Ionic.Zip.ZipFile.ParallelDeflateThreshold">
<summary>
The size threshold for an entry, above which a parallel deflate is used.
</summary>
<remarks>
<para>
DotNetZip will use multiple threads to compress any ZipEntry,
if the entry is larger than the given size. Zero means "always
use parallel deflate", while -1 means "never use parallel
deflate". The default value for this property is 512k. Aside
from the special values of 0 and 1, the minimum value is 65536.
</para>
<para>
If the entry size cannot be known before compression, as with a
read-forward stream, then Parallel deflate will never be
performed, unless the value of this property is zero.
</para>
<para>
A parallel deflate operations will speed up the compression of
large files, on computers with multiple CPUs or multiple CPU
cores. For files above 1mb, on a dual core or dual-cpu (2p)
machine, the time required to compress the file can be 70% of the
single-threaded deflate. For very large files on 4p machines the
compression can be done in 30% of the normal time. The downside
is that parallel deflate consumes extra memory during the deflate,
and the deflation is not as effective.
</para>
<para>
Parallel deflate tends to not be as effective as single-threaded deflate
because the original data stream is split into multiple independent
buffers, each of which is compressed in parallel. But because they are
treated independently, there is no opportunity to share compression
dictionaries. For that reason, a deflated stream may be slightly larger
when compressed using parallel deflate, as compared to a traditional
single-threaded deflate. Sometimes the increase over the normal deflate
is as much as 5% of the total compressed size. For larger files it can
be as small as 0.1%.
</para>
<para>
Multi-threaded compression does not give as much an advantage when using
Encryption. This is primarily because encryption tends to slow down
the entire pipeline. Also, multi-threaded compression gives less of an
advantage when using lower compression levels, for example <see cref="F:Ionic.Zlib.CompressionLevel.BestSpeed"/>. You may have to perform
some tests to determine the best approach for your situation.
</para>
</remarks>
</member>
<member name="P:Ionic.Zip.ZipFile.LibraryVersion">
<summary>
Returns the version number on the DotNetZip assembly.
</summary>
<remarks>
<para>
This property is exposed as a convenience. Callers could also get the
version value by retrieving GetName().Version on the
System.Reflection.Assembly object pointing to the DotNetZip
assembly. But sometimes it is not clear which assembly is being loaded.
This property makes it clear.
</para>
<para>
This static property is primarily useful for diagnostic purposes.
</para>
</remarks>
</member>
<member name="P:Ionic.Zip.ZipFile.Item(System.Int32)">
<summary>
This is an integer indexer into the Zip archive.
</summary>
<remarks>
<para>
This property is read-only.
</para>
<para>
Internally, the <c>ZipEntry</c> instances that belong to the
<c>ZipFile</c> are stored in a Dictionary. When you use this
indexer the first time, it creates a read-only
<c>List&lt;ZipEntry&gt;</c> from the Dictionary.Values Collection.
If at any time you modify the set of entries in the <c>ZipFile</c>,
either by adding an entry, removing an entry, or renaming an
entry, a new List will be created, and the numeric indexes for the
remaining entries may be different.
</para>
<para>
This means you cannot rename any ZipEntry from
inside an enumeration of the zip file.
</para>
<param name="ix">
The index value.
</param>
</remarks>
<returns>
The <c>ZipEntry</c> within the Zip archive at the specified index. If the
entry does not exist in the archive, this indexer throws.
</returns>
</member>
<member name="P:Ionic.Zip.ZipFile.Item(System.String)">
<summary>
This is a name-based indexer into the Zip archive.
</summary>
<remarks>
<para>
This property is read-only.
</para>
<para>
The <see cref="P:Ionic.Zip.ZipFile.CaseSensitiveRetrieval"/> property on the <c>ZipFile</c>
determines whether retrieval via this indexer is done via case-sensitive
comparisons. By default, retrieval is not case sensitive. This makes
sense on Windows, in which filesystems are not case sensitive.
</para>
<para>
Regardless of case-sensitivity, it is not always the case that
<c>this[value].FileName == value</c>. In other words, the <c>FileName</c>
property of the <c>ZipEntry</c> retrieved with this indexer, may or may
not be equal to the index value.
</para>
<para>
This is because DotNetZip performs a normalization of filenames passed to
this indexer, before attempting to retrieve the item. That normalization
includes: removal of a volume letter and colon, swapping backward slashes
for forward slashes. So, <c>zip["dir1\\entry1.txt"].FileName ==
"dir1/entry.txt"</c>.
</para>
<para>
Directory entries in the zip file may be retrieved via this indexer only
with names that have a trailing slash. DotNetZip automatically appends a
trailing slash to the names of any directory entries added to a zip.
</para>
</remarks>
<example>
This example extracts only the entries in a zip file that are .txt files.
<code>
using (ZipFile zip = ZipFile.Read("PackedDocuments.zip"))
{
foreach (string s1 in zip.EntryFilenames)
{
if (s1.EndsWith(".txt"))
zip[s1].Extract("textfiles");
}
}
</code>
<code lang="VB">
Using zip As ZipFile = ZipFile.Read("PackedDocuments.zip")
Dim s1 As String
For Each s1 In zip.EntryFilenames
If s1.EndsWith(".txt") Then
zip(s1).Extract("textfiles")
End If
Next
End Using
</code>
</example>
<seealso cref="M:Ionic.Zip.ZipFile.RemoveEntry(System.String)"/>
<exception cref="T:System.ArgumentException">
Thrown if the caller attempts to assign a non-null value to the indexer.
</exception>
<param name="fileName">
The name of the file, including any directory path, to retrieve from the
zip. The filename match is not case-sensitive by default; you can use the
<see cref="P:Ionic.Zip.ZipFile.CaseSensitiveRetrieval"/> property to change this behavior. The
pathname can use forward-slashes or backward slashes.
</param>
<returns>
The <c>ZipEntry</c> within the Zip archive, given by the specified
filename. If the named entry does not exist in the archive, this indexer
returns <c>null</c> (<c>Nothing</c> in VB).
</returns>
</member>
<member name="P:Ionic.Zip.ZipFile.EntryFileNames">
<summary>
The list of filenames for the entries contained within the zip archive.
</summary>
<remarks>
According to the ZIP specification, the names of the entries use forward
slashes in pathnames. If you are scanning through the list, you may have
to swap forward slashes for backslashes.
</remarks>
<seealso cref="P:Ionic.Zip.ZipFile.Item(System.String)"/>
<example>
This example shows one way to test if a filename is already contained
within a zip archive.
<code>
String zipFileToRead= "PackedDocuments.zip";
string candidate = "DatedMaterial.xps";
using (ZipFile zip = new ZipFile(zipFileToRead))
{
if (zip.EntryFilenames.Contains(candidate))
Console.WriteLine("The file '{0}' exists in the zip archive '{1}'",
candidate,
zipFileName);
else
Console.WriteLine("The file, '{0}', does not exist in the zip archive '{1}'",
candidate,
zipFileName);
Console.WriteLine();
}
</code>
<code lang="VB">
Dim zipFileToRead As String = "PackedDocuments.zip"
Dim candidate As String = "DatedMaterial.xps"
Using zip As ZipFile.Read(ZipFileToRead)
If zip.EntryFilenames.Contains(candidate) Then
Console.WriteLine("The file '{0}' exists in the zip archive '{1}'", _
candidate, _
zipFileName)
Else
Console.WriteLine("The file, '{0}', does not exist in the zip archive '{1}'", _
candidate, _
zipFileName)
End If
Console.WriteLine
End Using
</code>
</example>
<returns>
The list of strings for the filenames contained within the Zip archive.
</returns>
</member>
<member name="P:Ionic.Zip.ZipFile.Entries">
<summary>
Returns the readonly collection of entries in the Zip archive.
</summary>
<remarks>
<para>
If there are no entries in the current <c>ZipFile</c>, the value returned is a
non-null zero-element collection. If there are entries in the zip file,
the elements are returned in no particular order.
</para>
<para>
This is the implied enumerator on the <c>ZipFile</c> class. If you use a
<c>ZipFile</c> instance in a context that expects an enumerator, you will
get this collection.
</para>
</remarks>
<seealso cref="P:Ionic.Zip.ZipFile.EntriesSorted"/>
</member>
<member name="P:Ionic.Zip.ZipFile.EntriesSorted">
<summary>
Returns a readonly collection of entries in the Zip archive, sorted by FileName.
</summary>
<remarks>
If there are no entries in the current <c>ZipFile</c>, the value returned
is a non-null zero-element collection. If there are entries in the zip
file, the elements are returned sorted by the name of the entry.
</remarks>
<example>
This example fills a Windows Forms ListView with the entries in a zip file.
<code lang="C#">
using (ZipFile zip = ZipFile.Read(zipFile))
{
foreach (ZipEntry entry in zip.EntriesSorted)
{
ListViewItem item = new ListViewItem(n.ToString());
n++;
string[] subitems = new string[] {
entry.FileName.Replace("/","\\"),
entry.LastModified.ToString("yyyy-MM-dd HH:mm:ss"),
entry.UncompressedSize.ToString(),
String.Format("{0,5:F0}%", entry.CompressionRatio),
entry.CompressedSize.ToString(),
(entry.UsesEncryption) ? "Y" : "N",
String.Format("{0:X8}", entry.Crc)};
foreach (String s in subitems)
{
ListViewItem.ListViewSubItem subitem = new ListViewItem.ListViewSubItem();
subitem.Text = s;
item.SubItems.Add(subitem);
}
this.listView1.Items.Add(item);
}
}
</code>
</example>
<seealso cref="P:Ionic.Zip.ZipFile.Entries"/>
</member>
<member name="P:Ionic.Zip.ZipFile.Count">
<summary>
Returns the number of entries in the Zip archive.
</summary>
</member>
<member name="P:Ionic.Zip.ZipFile.Info">
<summary>
Provides a human-readable string with information about the ZipFile.
</summary>
<remarks>
<para>
The information string contains 10 lines or so, about each ZipEntry,
describing whether encryption is in use, the compressed and uncompressed
length of the entry, the offset of the entry, and so on. As a result the
information string can be very long for zip files that contain many
entries.
</para>
<para>
This information is mostly useful for diagnostic purposes.
</para>
</remarks>
</member>
<member name="E:Ionic.Zip.ZipFile.SaveProgress">
<summary>
An event handler invoked when a Save() starts, before and after each entry has been
written to the archive, when a Save() completes, and during other Save events.
</summary>
<remarks>
<para>
Depending on the particular event, different properties on the
<see cref="T:Ionic.Zip.SaveProgressEventArgs"/> parameter are set. The following table
summarizes the available EventTypes and the conditions under which this
event handler is invoked with a <c>SaveProgressEventArgs</c> with the given EventType.
</para>
<list type="table">
<listheader>
<term>value of EntryType</term>
<description>Meaning and conditions</description>
</listheader>
<item>
<term>ZipProgressEventType.Saving_Started</term>
<description>Fired when ZipFile.Save() begins.
</description>
</item>
<item>
<term>ZipProgressEventType.Saving_BeforeSaveEntry</term>
<description>Fired within ZipFile.Save(), just before writing data for each particular entry.
</description>
</item>
<item>
<term>ZipProgressEventType.Saving_AfterSaveEntry</term>
<description>Fired within ZipFile.Save(), just after having finished writing data for each
particular entry.
</description>
</item>
<item>
<term>ZipProgressEventType.Saving_Completed</term>
<description>Fired when ZipFile.Save() has completed.
</description>
</item>
<item>
<term>ZipProgressEventType.Saving_AfterSaveTempArchive</term>
<description>Fired after the temporary file has been created. This happens only
when saving to a disk file. This event will not be invoked when saving to a stream.
</description>
</item>
<item>
<term>ZipProgressEventType.Saving_BeforeRenameTempArchive</term>
<description>Fired just before renaming the temporary file to the permanent location. This
happens only when saving to a disk file. This event will not be invoked when saving to a stream.
</description>
</item>
<item>
<term>ZipProgressEventType.Saving_AfterRenameTempArchive</term>
<description>Fired just after renaming the temporary file to the permanent location. This
happens only when saving to a disk file. This event will not be invoked when saving to a stream.
</description>
</item>
<item>
<term>ZipProgressEventType.Saving_AfterCompileSelfExtractor</term>
<description>Fired after a self-extracting archive has finished compiling.
This EventType is used only within SaveSelfExtractor().
</description>
</item>
<item>
<term>ZipProgressEventType.Saving_BytesRead</term>
<description>Set during the save of a particular entry, to update progress of the Save().
When this EventType is set, the BytesTransferred is the number of bytes that have been read from the
source stream. The TotalBytesToTransfer is the number of bytes in the uncompressed file.
</description>
</item>
</list>
</remarks>
<example>
This example uses an anonymous method to handle the
SaveProgress event, by updating a progress bar.
<code lang="C#">
progressBar1.Value = 0;
progressBar1.Max = listbox1.Items.Count;
using (ZipFile zip = new ZipFile())
{
// listbox1 contains a list of filenames
zip.AddFiles(listbox1.Items);
// do the progress bar:
zip.SaveProgress += (sender, e) =&gt; {
if (e.EventType == ZipProgressEventType.Saving_BeforeWriteEntry) {
progressBar1.PerformStep();
}
};
zip.Save(fs);
}
</code>
</example>
<example>
This example uses a named method as the
<c>SaveProgress</c> event handler, to update the user, in a
console-based application.
<code lang="C#">
static bool justHadByteUpdate= false;
public static void SaveProgress(object sender, SaveProgressEventArgs e)
{
if (e.EventType == ZipProgressEventType.Saving_Started)
Console.WriteLine("Saving: {0}", e.ArchiveName);
else if (e.EventType == ZipProgressEventType.Saving_Completed)
{
justHadByteUpdate= false;
Console.WriteLine();
Console.WriteLine("Done: {0}", e.ArchiveName);
}
else if (e.EventType == ZipProgressEventType.Saving_BeforeWriteEntry)
{
if (justHadByteUpdate)
Console.WriteLine();
Console.WriteLine(" Writing: {0} ({1}/{2})",
e.CurrentEntry.FileName, e.EntriesSaved, e.EntriesTotal);
justHadByteUpdate= false;
}
else if (e.EventType == ZipProgressEventType.Saving_EntryBytesRead)
{
if (justHadByteUpdate)
Console.SetCursorPosition(0, Console.CursorTop);
Console.Write(" {0}/{1} ({2:N0}%)", e.BytesTransferred, e.TotalBytesToTransfer,
e.BytesTransferred / (0.01 * e.TotalBytesToTransfer ));
justHadByteUpdate= true;
}
}
public static ZipUp(string targetZip, string directory)
{
using (var zip = new ZipFile()) {
zip.SaveProgress += SaveProgress;
zip.AddDirectory(directory);
zip.Save(targetZip);
}
}
</code>
<code lang="VB">
Public Sub ZipUp(ByVal targetZip As String, ByVal directory As String)
Using zip As ZipFile = New ZipFile
AddHandler zip.SaveProgress, AddressOf MySaveProgress
zip.AddDirectory(directory)
zip.Save(targetZip)
End Using
End Sub
Private Shared justHadByteUpdate As Boolean = False
Public Shared Sub MySaveProgress(ByVal sender As Object, ByVal e As SaveProgressEventArgs)
If (e.EventType Is ZipProgressEventType.Saving_Started) Then
Console.WriteLine("Saving: {0}", e.ArchiveName)
ElseIf (e.EventType Is ZipProgressEventType.Saving_Completed) Then
justHadByteUpdate = False
Console.WriteLine
Console.WriteLine("Done: {0}", e.ArchiveName)
ElseIf (e.EventType Is ZipProgressEventType.Saving_BeforeWriteEntry) Then
If justHadByteUpdate Then
Console.WriteLine
End If
Console.WriteLine(" Writing: {0} ({1}/{2})", e.CurrentEntry.FileName, e.EntriesSaved, e.EntriesTotal)
justHadByteUpdate = False
ElseIf (e.EventType Is ZipProgressEventType.Saving_EntryBytesRead) Then
If justHadByteUpdate Then
Console.SetCursorPosition(0, Console.CursorTop)
End If
Console.Write(" {0}/{1} ({2:N0}%)", e.BytesTransferred, _
e.TotalBytesToTransfer, _
(CDbl(e.BytesTransferred) / (0.01 * e.TotalBytesToTransfer)))
justHadByteUpdate = True
End If
End Sub
</code>
</example>
<example>
This is a more complete example of using the SaveProgress
events in a Windows Forms application, with a
Thread object.
<code lang="C#">
delegate void SaveEntryProgress(SaveProgressEventArgs e);
delegate void ButtonClick(object sender, EventArgs e);
public class WorkerOptions
{
public string ZipName;
public string Folder;
public string Encoding;
public string Comment;
public int ZipFlavor;
public Zip64Option Zip64;
}
private int _progress2MaxFactor;
private bool _saveCanceled;
private long _totalBytesBeforeCompress;
private long _totalBytesAfterCompress;
private Thread _workerThread;
private void btnZipup_Click(object sender, EventArgs e)
{
KickoffZipup();
}
private void btnCancel_Click(object sender, EventArgs e)
{
if (this.lblStatus.InvokeRequired)
{
this.lblStatus.Invoke(new ButtonClick(this.btnCancel_Click), new object[] { sender, e });
}
else
{
_saveCanceled = true;
lblStatus.Text = "Canceled...";
ResetState();
}
}
private void KickoffZipup()
{
_folderName = tbDirName.Text;
if (_folderName == null || _folderName == "") return;
if (this.tbZipName.Text == null || this.tbZipName.Text == "") return;
// check for existence of the zip file:
if (System.IO.File.Exists(this.tbZipName.Text))
{
var dlgResult = MessageBox.Show(String.Format("The file you have specified ({0}) already exists." +
" Do you want to overwrite this file?", this.tbZipName.Text),
"Confirmation is Required", MessageBoxButtons.YesNo, MessageBoxIcon.Question);
if (dlgResult != DialogResult.Yes) return;
System.IO.File.Delete(this.tbZipName.Text);
}
_saveCanceled = false;
_nFilesCompleted = 0;
_totalBytesAfterCompress = 0;
_totalBytesBeforeCompress = 0;
this.btnOk.Enabled = false;
this.btnOk.Text = "Zipping...";
this.btnCancel.Enabled = true;
lblStatus.Text = "Zipping...";
var options = new WorkerOptions
{
ZipName = this.tbZipName.Text,
Folder = _folderName,
Encoding = "ibm437"
};
if (this.comboBox1.SelectedIndex != 0)
{
options.Encoding = this.comboBox1.SelectedItem.ToString();
}
if (this.radioFlavorSfxCmd.Checked)
options.ZipFlavor = 2;
else if (this.radioFlavorSfxGui.Checked)
options.ZipFlavor = 1;
else options.ZipFlavor = 0;
if (this.radioZip64AsNecessary.Checked)
options.Zip64 = Zip64Option.AsNecessary;
else if (this.radioZip64Always.Checked)
options.Zip64 = Zip64Option.Always;
else options.Zip64 = Zip64Option.Never;
options.Comment = String.Format("Encoding:{0} || Flavor:{1} || ZIP64:{2}\r\nCreated at {3} || {4}\r\n",
options.Encoding,
FlavorToString(options.ZipFlavor),
options.Zip64.ToString(),
System.DateTime.Now.ToString("yyyy-MMM-dd HH:mm:ss"),
this.Text);
if (this.tbComment.Text != TB_COMMENT_NOTE)
options.Comment += this.tbComment.Text;
_workerThread = new Thread(this.DoSave);
_workerThread.Name = "Zip Saver thread";
_workerThread.Start(options);
this.Cursor = Cursors.WaitCursor;
}
private void DoSave(Object p)
{
WorkerOptions options = p as WorkerOptions;
try
{
using (var zip1 = new ZipFile())
{
zip1.ProvisionalAlternateEncoding = System.Text.Encoding.GetEncoding(options.Encoding);
zip1.Comment = options.Comment;
zip1.AddDirectory(options.Folder);
_entriesToZip = zip1.EntryFileNames.Count;
SetProgressBars();
zip1.SaveProgress += this.zip1_SaveProgress;
zip1.UseZip64WhenSaving = options.Zip64;
if (options.ZipFlavor == 1)
zip1.SaveSelfExtractor(options.ZipName, SelfExtractorFlavor.WinFormsApplication);
else if (options.ZipFlavor == 2)
zip1.SaveSelfExtractor(options.ZipName, SelfExtractorFlavor.ConsoleApplication);
else
zip1.Save(options.ZipName);
}
}
catch (System.Exception exc1)
{
MessageBox.Show(String.Format("Exception while zipping: {0}", exc1.Message));
btnCancel_Click(null, null);
}
}
void zip1_SaveProgress(object sender, SaveProgressEventArgs e)
{
switch (e.EventType)
{
case ZipProgressEventType.Saving_AfterWriteEntry:
StepArchiveProgress(e);
break;
case ZipProgressEventType.Saving_EntryBytesRead:
StepEntryProgress(e);
break;
case ZipProgressEventType.Saving_Completed:
SaveCompleted();
break;
case ZipProgressEventType.Saving_AfterSaveTempArchive:
// this event only occurs when saving an SFX file
TempArchiveSaved();
break;
}
if (_saveCanceled)
e.Cancel = true;
}
private void StepArchiveProgress(SaveProgressEventArgs e)
{
if (this.progressBar1.InvokeRequired)
{
this.progressBar1.Invoke(new SaveEntryProgress(this.StepArchiveProgress), new object[] { e });
}
else
{
if (!_saveCanceled)
{
_nFilesCompleted++;
this.progressBar1.PerformStep();
_totalBytesAfterCompress += e.CurrentEntry.CompressedSize;
_totalBytesBeforeCompress += e.CurrentEntry.UncompressedSize;
// reset the progress bar for the entry:
this.progressBar2.Value = this.progressBar2.Maximum = 1;
this.Update();
}
}
}
private void StepEntryProgress(SaveProgressEventArgs e)
{
if (this.progressBar2.InvokeRequired)
{
this.progressBar2.Invoke(new SaveEntryProgress(this.StepEntryProgress), new object[] { e });
}
else
{
if (!_saveCanceled)
{
if (this.progressBar2.Maximum == 1)
{
// reset
Int64 max = e.TotalBytesToTransfer;
_progress2MaxFactor = 0;
while (max &gt; System.Int32.MaxValue)
{
max /= 2;
_progress2MaxFactor++;
}
this.progressBar2.Maximum = (int)max;
lblStatus.Text = String.Format("{0} of {1} files...({2})",
_nFilesCompleted + 1, _entriesToZip, e.CurrentEntry.FileName);
}
int xferred = e.BytesTransferred &gt;&gt; _progress2MaxFactor;
this.progressBar2.Value = (xferred &gt;= this.progressBar2.Maximum)
? this.progressBar2.Maximum
: xferred;
this.Update();
}
}
}
private void SaveCompleted()
{
if (this.lblStatus.InvokeRequired)
{
this.lblStatus.Invoke(new MethodInvoker(this.SaveCompleted));
}
else
{
lblStatus.Text = String.Format("Done, Compressed {0} files, {1:N0}% of original.",
_nFilesCompleted, (100.00 * _totalBytesAfterCompress) / _totalBytesBeforeCompress);
ResetState();
}
}
private void ResetState()
{
this.btnCancel.Enabled = false;
this.btnOk.Enabled = true;
this.btnOk.Text = "Zip it!";
this.progressBar1.Value = 0;
this.progressBar2.Value = 0;
this.Cursor = Cursors.Default;
if (!_workerThread.IsAlive)
_workerThread.Join();
}
</code>
</example>
<seealso cref="E:Ionic.Zip.ZipFile.ReadProgress"/>
<seealso cref="E:Ionic.Zip.ZipFile.AddProgress"/>
<seealso cref="E:Ionic.Zip.ZipFile.ExtractProgress"/>
</member>
<member name="E:Ionic.Zip.ZipFile.ReadProgress">
<summary>
An event handler invoked before, during, and after the reading of a zip archive.
</summary>
<remarks>
<para>
Depending on the particular event being signaled, different properties on the
<see cref="T:Ionic.Zip.ReadProgressEventArgs"/> parameter are set. The following table
summarizes the available EventTypes and the conditions under which this
event handler is invoked with a <c>ReadProgressEventArgs</c> with the given EventType.
</para>
<list type="table">
<listheader>
<term>value of EntryType</term>
<description>Meaning and conditions</description>
</listheader>
<item>
<term>ZipProgressEventType.Reading_Started</term>
<description>Fired just as ZipFile.Read() begins. Meaningful properties: ArchiveName.
</description>
</item>
<item>
<term>ZipProgressEventType.Reading_Completed</term>
<description>Fired when ZipFile.Read() has completed. Meaningful properties: ArchiveName.
</description>
</item>
<item>
<term>ZipProgressEventType.Reading_ArchiveBytesRead</term>
<description>Fired while reading, updates the number of bytes read for the entire archive.
Meaningful properties: ArchiveName, CurrentEntry, BytesTransferred, TotalBytesToTransfer.
</description>
</item>
<item>
<term>ZipProgressEventType.Reading_BeforeReadEntry</term>
<description>Indicates an entry is about to be read from the archive.
Meaningful properties: ArchiveName, EntriesTotal.
</description>
</item>
<item>
<term>ZipProgressEventType.Reading_AfterReadEntry</term>
<description>Indicates an entry has just been read from the archive.
Meaningful properties: ArchiveName, EntriesTotal, CurrentEntry.
</description>
</item>
</list>
</remarks>
<seealso cref="E:Ionic.Zip.ZipFile.SaveProgress"/>
<seealso cref="E:Ionic.Zip.ZipFile.AddProgress"/>
<seealso cref="E:Ionic.Zip.ZipFile.ExtractProgress"/>
</member>
<member name="E:Ionic.Zip.ZipFile.ExtractProgress">
<summary>
An event handler invoked before, during, and after extraction of entries
in the zip archive.
</summary>
<remarks>
<para>
Depending on the particular event, different properties on the
<see cref="T:Ionic.Zip.ExtractProgressEventArgs"/> parameter are set. The following table
summarizes the available EventTypes and the conditions under which this
event handler is invoked with a <c>ExtractProgressEventArgs</c> with the given EventType.
</para>
<list type="table">
<listheader>
<term>value of EntryType</term>
<description>Meaning and conditions</description>
</listheader>
<item>
<term>ZipProgressEventType.Extracting_BeforeExtractAll</term>
<description>Set when ExtractAll() begins. The ArchiveName, Overwrite,
and ExtractLocation properties are meaningful.</description>
</item>
<item>
<term>ZipProgressEventType.Extracting_AfterExtractAll</term>
<description>Set when ExtractAll() has completed. The ArchiveName,
Overwrite, and ExtractLocation properties are meaningful.
</description>
</item>
<item>
<term>ZipProgressEventType.Extracting_BeforeExtractEntry</term>
<description>Set when an Extract() on an entry in the ZipFile has begun.
Properties that are meaningful: ArchiveName, EntriesTotal, CurrentEntry, Overwrite,
ExtractLocation, EntriesExtracted.
</description>
</item>
<item>
<term>ZipProgressEventType.Extracting_AfterExtractEntry</term>
<description>Set when an Extract() on an entry in the ZipFile has completed.
Properties that are meaningful: ArchiveName, EntriesTotal, CurrentEntry, Overwrite,
ExtractLocation, EntriesExtracted.
</description>
</item>
<item>
<term>ZipProgressEventType.Extracting_EntryBytesWritten</term>
<description>Set within a call to Extract() on an entry in the ZipFile, as
data is extracted for the entry. Properties that are meaningful: ArchiveName,
CurrentEntry, BytesTransferred, TotalBytesToTransfer.
</description>
</item>
<item>
<term>ZipProgressEventType.Extracting_ExtractEntryWouldOverwrite</term>
<description>Set within a call to Extract() on an entry in the ZipFile, when the
extraction would overwrite an existing file. This event type is used only when
<c>ExtractExistingFileAction</c> on the <c>ZipFile</c> or <c>ZipEntry</c> is set
to <c>InvokeExtractProgressEvent</c>.
</description>
</item>
</list>
</remarks>
<example>
<code>
private static bool justHadByteUpdate = false;
public static void ExtractProgress(object sender, ExtractProgressEventArgs e)
{
if(e.EventType == ZipProgressEventType.Extracting_EntryBytesWritten)
{
if (justHadByteUpdate)
Console.SetCursorPosition(0, Console.CursorTop);
Console.Write(" {0}/{1} ({2:N0}%)", e.BytesTransferred, e.TotalBytesToTransfer,
e.BytesTransferred / (0.01 * e.TotalBytesToTransfer ));
justHadByteUpdate = true;
}
else if(e.EventType == ZipProgressEventType.Extracting_BeforeExtractEntry)
{
if (justHadByteUpdate)
Console.WriteLine();
Console.WriteLine("Extracting: {0}", e.CurrentEntry.FileName);
justHadByteUpdate= false;
}
}
public static ExtractZip(string zipToExtract, string directory)
{
string TargetDirectory= "extract";
using (var zip = ZipFile.Read(zipToExtract)) {
zip.ExtractProgress += ExtractProgress;
foreach (var e in zip1)
{
e.Extract(TargetDirectory, true);
}
}
}
</code>
<code lang="VB">
Public Shared Sub Main(ByVal args As String())
Dim ZipToUnpack As String = "C1P3SML.zip"
Dim TargetDir As String = "ExtractTest_Extract"
Console.WriteLine("Extracting file {0} to {1}", ZipToUnpack, TargetDir)
Using zip1 As ZipFile = ZipFile.Read(ZipToUnpack)
AddHandler zip1.ExtractProgress, AddressOf MyExtractProgress
Dim e As ZipEntry
For Each e In zip1
e.Extract(TargetDir, True)
Next
End Using
End Sub
Private Shared justHadByteUpdate As Boolean = False
Public Shared Sub MyExtractProgress(ByVal sender As Object, ByVal e As ExtractProgressEventArgs)
If (e.EventType = ZipProgressEventType.Extracting_EntryBytesWritten) Then
If ExtractTest.justHadByteUpdate Then
Console.SetCursorPosition(0, Console.CursorTop)
End If
Console.Write(" {0}/{1} ({2:N0}%)", e.BytesTransferred, e.TotalBytesToTransfer, (CDbl(e.BytesTransferred) / (0.01 * e.TotalBytesToTransfer)))
ExtractTest.justHadByteUpdate = True
ElseIf (e.EventType = ZipProgressEventType.Extracting_BeforeExtractEntry) Then
If ExtractTest.justHadByteUpdate Then
Console.WriteLine
End If
Console.WriteLine("Extracting: {0}", e.CurrentEntry.FileName)
ExtractTest.justHadByteUpdate = False
End If
End Sub
</code>
</example>
<seealso cref="E:Ionic.Zip.ZipFile.SaveProgress"/>
<seealso cref="E:Ionic.Zip.ZipFile.ReadProgress"/>
<seealso cref="E:Ionic.Zip.ZipFile.AddProgress"/>
</member>
<member name="E:Ionic.Zip.ZipFile.AddProgress">
<summary>
An event handler invoked before, during, and after Adding entries to a zip archive.
</summary>
<remarks>
Adding a large number of entries to a zip file can take a long
time. For example, when calling <see cref="M:Ionic.Zip.ZipFile.AddDirectory(System.String)"/> on a
directory that contains 50,000 files, it could take 3 minutes or so.
This event handler allws an application to track the progress of the Add
operation.
</remarks>
<example>
<code lang="C#">
int _numEntriesToAdd= 0;
int _numEntriesAdded= 0;
void AddProgressHandler(object sender, AddProgressEventArgs e)
{
switch (e.EventType)
{
case ZipProgressEventType.Adding_Started:
Console.WriteLine("Adding files to the zip...");
break;
case ZipProgressEventType.Adding_AfterAddEntry:
_numEntriesAdded++;
Console.WriteLine(String.Format("Adding file {0}/{1} :: {2}",
_numEntriesAdded, _numEntriesToAdd, e.CurrentEntry.FileName));
break;
case ZipProgressEventType.Adding_Completed:
Console.WriteLine("Added all files");
break;
}
}
void CreateTheZip()
{
using (ZipFile zip = new ZipFile())
{
zip.AddProgress += AddProgressHandler;
zip.AddDirectory(System.IO.Path.GetFileName(DirToZip));
zip.Save(ZipFileToCreate);
}
}
</code>
<code lang="VB">
Private Sub AddProgressHandler(ByVal sender As Object, ByVal e As AddProgressEventArgs)
Select Case e.EventType
Case ZipProgressEventType.Adding_Started
Console.WriteLine("Adding files to the zip...")
Exit Select
Case ZipProgressEventType.Adding_AfterAddEntry
Console.WriteLine(String.Format("Adding file {0}", e.CurrentEntry.FileName))
Exit Select
Case ZipProgressEventType.Adding_Completed
Console.WriteLine("Added all files")
Exit Select
End Select
End Sub
Sub CreateTheZip()
Using zip as ZipFile = New ZipFile
AddHandler zip.AddProgress, AddressOf AddProgressHandler
zip.AddDirectory(System.IO.Path.GetFileName(DirToZip))
zip.Save(ZipFileToCreate);
End Using
End Sub
</code>
</example>
<seealso cref="E:Ionic.Zip.ZipFile.SaveProgress"/>
<seealso cref="E:Ionic.Zip.ZipFile.ReadProgress"/>
<seealso cref="E:Ionic.Zip.ZipFile.ExtractProgress"/>
</member>
<member name="E:Ionic.Zip.ZipFile.ZipError">
<summary>
An event that is raised when an error occurs during open or read of files
while saving a zip archive.
</summary>
<remarks>
<para>
Errors can occur as a file is being saved to the zip archive. For
example, the File.Open may fail, or a File.Read may fail, because of
lock conflicts or other reasons. If you add a handler to this event,
you can handle such errors in your own code. If you don't add a
handler, the library will throw an exception if it encounters an I/O
error during a call to <c>Save()</c>.
</para>
<para>
Setting a handler implicitly sets <see cref="P:Ionic.Zip.ZipFile.ZipErrorAction"/> to
<c>ZipErrorAction.InvokeErrorEvent</c>.
</para>
<para>
The handler you add applies to all <see cref="T:Ionic.Zip.ZipEntry"/> items that are
subsequently added to the <c>ZipFile</c> instance. If you set this
property after you have added items to the <c>ZipFile</c>, but before you
have called <c>Save()</c>, errors that occur while saving those items
will not cause the error handler to be invoked.
</para>
<para>
If you want to handle any errors that occur with any entry in the zip
file using the same error handler, then add your error handler once,
before adding any entries to the zip archive.
</para>
<para>
In the error handler method, you need to set the <see cref="P:Ionic.Zip.ZipEntry.ZipErrorAction"/> property on the
<c>ZipErrorEventArgs.CurrentEntry</c>. This communicates back to
DotNetZip what you would like to do with this particular error. Within
an error handler, if you set the <c>ZipEntry.ZipErrorAction</c> property
on the <c>ZipEntry</c> to <c>ZipErrorAction.InvokeErrorEvent</c> or if
you don't set it at all, the library will throw the exception. (It is the
same as if you had set the <c>ZipEntry.ZipErrorAction</c> property on the
<c>ZipEntry</c> to <c>ZipErrorAction.Throw</c>.) If you set the
<c>ZipErrorEventArgs.Cancel</c> to true, the entire <c>Save()</c> will be
canceled.
</para>
</remarks>
<example>
This example shows how to use an event handler to handle
errors during save of the zip file.
<code lang="C#">
public static void MyZipError(object sender, ZipErrorEventArgs e)
{
Console.WriteLine("Error saving {0}...", e.FileName);
Console.WriteLine(" Exception: {0}", e.exception);
ZipEntry entry = e.CurrentEntry;
string response = null;
// Ask the user whether he wants to skip this error or not
do
{
Console.Write("Retry, Skip, Throw, or Cancel ? (R/S/T/C) ");
response = Console.ReadLine();
Console.WriteLine();
} while (response != null &amp;&amp;
response[0]!='S' &amp;&amp; response[0]!='s' &amp;&amp;
response[0]!='R' &amp;&amp; response[0]!='r' &amp;&amp;
response[0]!='T' &amp;&amp; response[0]!='t' &amp;&amp;
response[0]!='C' &amp;&amp; response[0]!='c');
e.Cancel = (response[0]=='C' || response[0]=='c');
if (response[0]=='S' || response[0]=='s')
entry.ZipErrorAction = ZipErrorAction.Skip;
else if (response[0]=='R' || response[0]=='r')
entry.ZipErrorAction = ZipErrorAction.Retry;
else if (response[0]=='T' || response[0]=='t')
entry.ZipErrorAction = ZipErrorAction.Throw;
}
public void SaveTheFile()
{
string directoryToZip = "fodder";
string directoryInArchive = "files";
string zipFileToCreate = "Archive.zip";
using (var zip = new ZipFile())
{
// set the event handler before adding any entries
zip.ZipError += MyZipError;
zip.AddDirectory(directoryToZip, directoryInArchive);
zip.Save(zipFileToCreate);
}
}
</code>
<code lang="VB">
Private Sub MyZipError(ByVal sender As Object, ByVal e As Ionic.Zip.ZipErrorEventArgs)
' At this point, the application could prompt the user for an action to take.
' But in this case, this application will simply automatically skip the file, in case of error.
Console.WriteLine("Zip Error, entry {0}", e.CurrentEntry.FileName)
Console.WriteLine(" Exception: {0}", e.exception)
' set the desired ZipErrorAction on the CurrentEntry to communicate that to DotNetZip
e.CurrentEntry.ZipErrorAction = Zip.ZipErrorAction.Skip
End Sub
Public Sub SaveTheFile()
Dim directoryToZip As String = "fodder"
Dim directoryInArchive As String = "files"
Dim zipFileToCreate as String = "Archive.zip"
Using zipArchive As ZipFile = New ZipFile
' set the event handler before adding any entries
AddHandler zipArchive.ZipError, AddressOf MyZipError
zipArchive.AddDirectory(directoryToZip, directoryInArchive)
zipArchive.Save(zipFileToCreate)
End Using
End Sub
</code>
</example>
<seealso cref="P:Ionic.Zip.ZipFile.ZipErrorAction"/>
</member>
<member name="T:Ionic.Zip.Zip64Option">
<summary>
Options for using ZIP64 extensions when saving zip archives.
</summary>
<remarks>
<para>
Designed many years ago, the <see href="http://www.pkware.com/documents/casestudies/APPNOTE.TXT">original zip
specification from PKWARE</see> allowed for 32-bit quantities for the
compressed and uncompressed sizes of zip entries, as well as a 32-bit quantity
for specifying the length of the zip archive itself, and a maximum of 65535
entries. These limits are now regularly exceeded in many backup and archival
scenarios. Recently, PKWare added extensions to the original zip spec, called
"ZIP64 extensions", to raise those limitations. This property governs whether
DotNetZip will use those extensions when writing zip archives. The use of
these extensions is optional and explicit in DotNetZip because, despite the
status of ZIP64 as a bona fide standard, many other zip tools and libraries do
not support ZIP64, and therefore a zip file with ZIP64 extensions may be
unreadable by some of those other tools.
</para>
<para>
Set this property to <see cref="F:Ionic.Zip.Zip64Option.Always"/> to always use ZIP64
extensions when saving, regardless of whether your zip archive needs it.
Suppose you add 5 files, each under 100k, to a ZipFile. If you specify Always
for this flag, you will get a ZIP64 archive, though the archive does not need
to use ZIP64 because none of the original zip limits had been exceeded.
</para>
<para>
Set this property to <see cref="F:Ionic.Zip.Zip64Option.Never"/> to tell the DotNetZip
library to never use ZIP64 extensions. This is useful for maximum
compatibility and interoperability, at the expense of the capability of
handling large files or large archives. NB: Windows Explorer in Windows XP
and Windows Vista cannot currently extract files from a zip64 archive, so if
you want to guarantee that a zip archive produced by this library will work in
Windows Explorer, use <c>Never</c>. If you set this property to <see cref="F:Ionic.Zip.Zip64Option.Never"/>, and your application creates a zip that would
exceed one of the Zip limits, the library will throw an exception while saving
the zip file.
</para>
<para>
Set this property to <see cref="F:Ionic.Zip.Zip64Option.AsNecessary"/> to tell the
DotNetZip library to use the ZIP64 extensions when required by the
entry. After the file is compressed, the original and compressed sizes are
checked, and if they exceed the limits described above, then zip64 can be
used. That is the general idea, but there is an additional wrinkle when saving
to a non-seekable device, like the ASP.NET <c>Response.OutputStream</c>, or
<c>Console.Out</c>. When using non-seekable streams for output, the entry
header - which indicates whether zip64 is in use - is emitted before it is
known if zip64 is necessary. It is only after all entries have been saved
that it can be known if ZIP64 will be required. On seekable output streams,
after saving all entries, the library can seek backward and re-emit the zip
file header to be consistent with the actual ZIP64 requirement. But using a
non-seekable output stream, the library cannot seek backward, so the header
can never be changed. In other words, the archive's use of ZIP64 extensions is
not alterable after the header is emitted. Therefore, when saving to
non-seekable streams, using <see cref="F:Ionic.Zip.Zip64Option.AsNecessary"/> is the same
as using <see cref="F:Ionic.Zip.Zip64Option.Always"/>: it will always produce a zip
archive that uses ZIP64 extensions.
</para>
</remarks>
</member>
<member name="F:Ionic.Zip.Zip64Option.Default">
<summary>
The default behavior, which is "Never".
(For COM clients, this is a 0 (zero).)
</summary>
</member>
<member name="F:Ionic.Zip.Zip64Option.Never">
<summary>
Do not use ZIP64 extensions when writing zip archives.
(For COM clients, this is a 0 (zero).)
</summary>
</member>
<member name="F:Ionic.Zip.Zip64Option.AsNecessary">
<summary>
Use ZIP64 extensions when writing zip archives, as necessary.
For example, when a single entry exceeds 0xFFFFFFFF in size, or when the archive as a whole
exceeds 0xFFFFFFFF in size, or when there are more than 65535 entries in an archive.
(For COM clients, this is a 1.)
</summary>
</member>
<member name="F:Ionic.Zip.Zip64Option.Always">
<summary>
Always use ZIP64 extensions when writing zip archives, even when unnecessary.
(For COM clients, this is a 2.)
</summary>
</member>
<member name="T:Ionic.Zip.SharedUtilities">
<summary>
Collects general purpose utility methods.
</summary>
</member>
<member name="M:Ionic.Zip.SharedUtilities.#ctor">
private null constructor
</member>
<member name="M:Ionic.Zip.SharedUtilities.NormalizePathForUseInZipFile(System.String)">
<summary>
Utility routine for transforming path names from filesystem format (on Windows that means backslashes) to
a format suitable for use within zipfiles. This means trimming the volume letter and colon (if any) And
swapping backslashes for forward slashes.
</summary>
<param name="pathName">source path.</param>
<returns>transformed path</returns>
</member>
<member name="M:Ionic.Zip.SharedUtilities.FindSignature(System.IO.Stream,System.Int32)">
<summary>
Finds a signature in the zip stream. This is useful for finding
the end of a zip entry, for example, or the beginning of the next ZipEntry.
</summary>
<remarks>
<para>
Scans through 64k at a time.
</para>
<para>
If the method fails to find the requested signature, the stream Position
after completion of this method is unchanged. If the method succeeds in
finding the requested signature, the stream position after completion is
direct AFTER the signature found in the stream.
</para>
</remarks>
<param name="stream">The stream to search</param>
<param name="SignatureToFind">The 4-byte signature to find</param>
<returns>The number of bytes read</returns>
</member>
<member name="M:Ionic.Zip.SharedUtilities.CreateAndOpenUniqueTempFile(System.String,System.IO.Stream@,System.String@)">
<summary>
Create a pseudo-random filename, suitable for use as a temporary file, and open it.
</summary>
<remarks>
<para>
The System.IO.Path.GetRandomFileName() method is not available on the Compact
Framework, so this library provides its own substitute on NETCF.
</para>
<para>
produces a filename of the form DotNetZip-xxxxxxxx.tmp, where xxxxxxxx is replaced
by randomly chosen characters, and creates that file.
</para>
</remarks>
</member>
<member name="M:Ionic.Zip.SharedUtilities.ReadWithRetry(System.IO.Stream,System.Byte[],System.Int32,System.Int32,System.String)">
<summary>
Workitem 7889: handle ERROR_LOCK_VIOLATION during read
</summary>
<remarks>
This could be gracefully handled with an extension attribute, but
This assembly is built for .NET 2.0, so I cannot use them.
</remarks>
</member>
<member name="T:Ionic.Zip.CountingStream">
<summary>
A Stream wrapper, used for bookkeeping on input or output
streams. In some cases, it is not possible to get the Position
of a stream, let's say, on a write-only output stream like
ASP.NET's Response.Output, or on a different write-only stream
provided as the destination for the zip by the application.
In this case, we can use this counting stream to count the bytes
read or written.
</summary>
</member>
<member name="M:Ionic.Zip.CountingStream.#ctor(System.IO.Stream)">
<summary>
The constructor.
</summary>
<param name="s">The underlying stream</param>
</member>
<member name="T:Ionic.Zip.ComHelper">
<summary>
This class exposes a set of COM-accessible wrappers for static
methods available on the ZipFile class. You don't need this
class unless you are using DotNetZip from a COM environment.
</summary>
</member>
<member name="M:Ionic.Zip.ComHelper.IsZipFile(System.String)">
<summary>
A wrapper for <see cref="M:Ionic.Zip.ZipFile.IsZipFile(System.String)">ZipFile.IsZipFile(string)</see>
</summary>
<param name="filename">The filename to of the zip file to check.</param>
<returns>true if the file contains a valid zip file.</returns>
</member>
<member name="M:Ionic.Zip.ComHelper.IsZipFileWithExtract(System.String)">
<summary>
A wrapper for <see cref="M:Ionic.Zip.ZipFile.IsZipFile(System.String,System.Boolean)">ZipFile.IsZipFile(string, bool)</see>
</summary>
<remarks>
We cannot use "overloaded" Method names in COM interop.
So, here, we use a unique name.
</remarks>
<param name="filename">The filename to of the zip file to check.</param>
<returns>true if the file contains a valid zip file.</returns>
</member>
<member name="M:Ionic.Zip.ComHelper.CheckZip(System.String)">
<summary>
A wrapper for <see cref="M:Ionic.Zip.ZipFile.CheckZip(System.String)">ZipFile.CheckZip(string)</see>
</summary>
<param name="filename">The filename to of the zip file to check.</param>
<returns>true if the named zip file checks OK. Otherwise, false. </returns>
</member>
<member name="M:Ionic.Zip.ComHelper.FixZipDirectory(System.String)">
<summary>
A wrapper for <see cref="M:Ionic.Zip.ZipFile.FixZipDirectory(System.String)">ZipFile.FixZipDirectory(string)</see>
</summary>
<param name="filename">The filename to of the zip file to fix.</param>
</member>
<member name="M:Ionic.Zip.ComHelper.GetZipLibraryVersion">
<summary>
A wrapper for <see cref="P:Ionic.Zip.ZipFile.LibraryVersion">ZipFile.LibraryVersion</see>
</summary>
<returns>
the version number on the DotNetZip assembly, formatted as a string.
</returns>
</member>
<member name="T:Ionic.Zip.SelfExtractorFlavor">
<summary>
An enum that provides the different self-extractor flavors
</summary>
</member>
<member name="F:Ionic.Zip.SelfExtractorFlavor.ConsoleApplication">
<summary>
A self-extracting zip archive that runs from the console or command line.
</summary>
</member>
<member name="F:Ionic.Zip.SelfExtractorFlavor.WinFormsApplication">
<summary>
A self-extracting zip archive that presents a graphical user interface when it is executed..
</summary>
</member>
<member name="T:Ionic.Zip.SelfExtractorSaveOptions">
<summary>
The options for generating a self-extracting archive.
</summary>
</member>
<member name="P:Ionic.Zip.SelfExtractorSaveOptions.Flavor">
<summary>
The type of SFX to create.
</summary>
</member>
<member name="P:Ionic.Zip.SelfExtractorSaveOptions.PostExtractCommandLine">
<summary>
The command to run after extraction.
</summary>
<remarks>
<para>
This is optional. Leave it empty (<c>null</c> in C# or <c>Nothing</c> in
VB) to run no command after extraction.
</para>
<para>
If it is non-empty, the SFX will execute the command specified in this
string on the user's machine, and using the extract directory as the
working directory for the process, after unpacking the archive. The
program to execute can include a path, if you like. If you want to execute
a program that accepts arguments, specify the program name, followed by a
space, and then the arguments for the program, each separated by a space,
just as you would on a normal command line. Example: <c>program.exe arg1
arg2</c>. The string prior to the first space will be taken as the
program name, and the string following the first space specifies the
arguments to the program.
</para>
<para>
If you want to execute a program that has a space in the name or path of
the file, surround the program name in double-quotes. The first character
of the command line should be a double-quote character, and there must be
a matching double-quote following the end of the program file name. Any
optional arguments to the program follow that, separated by
spaces. Example: <c>"c:\project files\program name.exe" arg1 arg2</c>.
</para>
<para>
If the flavor of the SFX is <c>SelfExtractorFlavor.ConsoleApplication</c>,
then the SFX starts a new process, using this string as the post-extract
command line. The SFX waits for the process to exit. The exit code of
the post-extract command line is returned as the exit code of the
command-line self-extractor exe. A non-zero exit code is typically used to
indicated a failure by the program. In the case of an SFX, a non-zero exit
code may indicate a failure during extraction, OR, it may indicate a
failure of the run-after-extract program if specified, OR, it may indicate
the run-after-extract program could not be fuond. There is no way to
distinguish these conditions from the calling shell, aside from parsing
the output of the SFX. If you have Quiet set to <c>true</c>, you may not
see error messages, if a problem occurs.
</para>
<para>
If the flavor of the SFX is
<c>SelfExtractorFlavor.WinFormsApplication</c>, then the SFX starts a new
process, using this string as the post-extract command line, and using the
extract directory as the working directory for the process. The SFX does
not wait for the command to complete, and does not check the exit code of
the program. If the run-after-extract program cannot be fuond, a message
box is displayed indicating that fact.
</para>
<para>
You can specify environment variables within this string, with a format like
<c>%NAME%</c>. The value of these variables will be expanded at the time
the SFX is run. Example: <c>%WINDIR%\system32\xcopy.exe</c> may expand at
runtime to <c>c:\Windows\System32\xcopy.exe</c>.
</para>
<para>
By combining this with the <c>RemoveUnpackedFilesAfterExecute</c> flag,
you can create an SFX that extracts itself, runs a file that was
extracted, then deletes all the files that were extracted. If you want it
to run "invisibly" then set <c>Flavor</c> to
<c>SelfExtractorFlavor.ConsoleApplication</c>, and set <c>Quiet</c> to
true. You may also want to specify the default extract location, with
<c>DefaultExtractDirectory</c>.
</para>
<para>
If you set <c>Flavor</c> to
<c>SelfExtractorFlavor.WinFormsApplication</c>, and set <c>Quiet</c> to
true, then a GUI with progressbars is displayed, but it is
"non-interactive" - it accepts no input from the user. Instead the SFX
just automatically unpacks and exits.
</para>
</remarks>
</member>
<member name="P:Ionic.Zip.SelfExtractorSaveOptions.DefaultExtractDirectory">
<summary>
The default extract directory the user will see when
running the self-extracting archive.
</summary>
<remarks>
<para>
Passing null (or Nothing in VB) here will cause the Self Extractor to use
the the user's personal directory (<see cref="F:System.Environment.SpecialFolder.Personal"/>) for the default extract
location.
</para>
<para>
This is only a default location. The actual extract location will be
settable on the command line when the SFX is executed.
</para>
<para>
You can specify environment variables within this string,
with <c>%NAME%</c>. The value of these variables will be
expanded at the time the SFX is run. Example:
<c>%USERPROFILE%\Documents\unpack</c> may expand at runtime to
<c>c:\users\melvin\Documents\unpack</c>.
</para>
</remarks>
</member>
<member name="P:Ionic.Zip.SelfExtractorSaveOptions.IconFile">
<summary>
The name of an .ico file in the filesystem to use for the application icon
for the generated SFX.
</summary>
<remarks>
<para>
Normally, DotNetZip will embed an "zipped folder" icon into the generated
SFX. If you prefer to use a different icon, you can specify it here. It
should be a .ico file. This file is passed as the <c>/win32icon</c>
option to the csc.exe compiler when constructing the SFX file.
</para>
</remarks>
</member>
<member name="P:Ionic.Zip.SelfExtractorSaveOptions.Quiet">
<summary>
Whether the ConsoleApplication SFX will be quiet during extraction.
</summary>
<remarks>
<para>
This option affects the way the generated SFX runs. By default it is
false. When you set it to true,...
</para>
<list type="table">
<listheader>
<term>Flavor</term>
<description>Behavior</description>
</listheader>
<item>
<term><c>ConsoleApplication</c></term>
<description>no messages will be emitted during successful operation.
</description>
</item>
<item>
<term><c>WinFormsApplication</c></term>
<description>the SFX extracts automatically when the application
is launched, with no additional user input.
</description>
</item>
</list>
<para>
When you set it to false,...
</para>
<list type="table">
<listheader>
<term>Flavor</term>
<description>Behavior</description>
</listheader>
<item>
<term><c>ConsoleApplication</c></term>
<description>the extractor will emit a
message to the console for each entry extracted.
</description>
</item>
<item>
<term><c>WinFormsApplication</c></term>
<description>the SFX presents a forms UI and allows the user to select
options before extracting.
</description>
</item>
</list>
</remarks>
</member>
<member name="P:Ionic.Zip.SelfExtractorSaveOptions.ExtractExistingFile">
<summary>
Specify what the self-extractor will do when extracting an entry
would overwrite an existing file.
</summary>
<remarks>
<para>
The default behavvior is to Throw.
</para>
</remarks>
</member>
<member name="P:Ionic.Zip.SelfExtractorSaveOptions.RemoveUnpackedFilesAfterExecute">
<summary>
Whether to remove the files that have been unpacked, after executing the
PostUnpackCommand.
</summary>
<remarks>
<para>
If true, and if there is a PostUnpackCommand, and if the command runs
successfully, then the files that the SFX unpacked will be removed,
afterwards. If the command does not complete successfully (non-zero
return code) then the files will not be removed.
</para>
<para>
Setting this flag, and setting <c>Flavor</c> to
<c>SelfExtractorFlavor.ConsoleApplication</c>, and setting <c>Quiet</c> to
true, results in an SFX that extracts itself, runs a file that was
extracted, then deletes all the files that were extracted, with no
intervention by the user. You may also want to specify the default
extract location, with <c>DefaultExtractDirectory</c>.
</para>
</remarks>
</member>
<member name="P:Ionic.Zip.SelfExtractorSaveOptions.FileVersion">
<summary>
The file version number to embed into the generated EXE. It will show up, for
example, during a mouseover in Windows Explorer.
</summary>
</member>
<member name="P:Ionic.Zip.SelfExtractorSaveOptions.ProductVersion">
<summary>
The product version to embed into the generated EXE. It will show up, for
example, during a mouseover in Windows Explorer.
</summary>
<remarks>
You can use any arbitrary string, but a human-readable version number is
recommended. For example "v1.2 alpha" or "v4.2 RC2". If you specify nothing,
then there is no product version embedded into the EXE.
</remarks>
</member>
<member name="P:Ionic.Zip.SelfExtractorSaveOptions.Copyright">
<summary>
The copyright notice, if any, to embed into the generated EXE.
</summary>
<remarks>
It will show up, for example, while viewing properties of the file in
Windows Explorer. You can use any arbitrary string, but typically you
want something like "Copyright © Dino Chiesa 2008, 2009".
</remarks>
</member>
<member name="P:Ionic.Zip.SelfExtractorSaveOptions.Description">
<summary>
The description to embed into the generated EXE.
</summary>
<remarks>
Use any arbitrary string. It will show up, for example, during a
mouseover in Windows Explorer. If you specify nothing, then the string
"DotNetZip SFX Archive" is embedded into the EXE as the description.
</remarks>
</member>
<member name="P:Ionic.Zip.SelfExtractorSaveOptions.ProductName">
<summary>
The product name to embed into the generated EXE.
</summary>
<remarks>
Use any arbitrary string.
It will show up, for example, while viewing properties of the EXE file in
Windows Explorer.
</remarks>
</member>
<member name="T:Ionic.Zip.WriteDelegate">
<summary>
Delegate in which the application writes the <c>ZipEntry</c> content for the named entry.
</summary>
<param name="entryName">The name of the entry that must be written.</param>
<param name="stream">The stream to which the entry data should be written.</param>
<remarks>
When you add an entry and specify a <c>WriteDelegate</c>, via <see cref="M:Ionic.Zip.ZipFile.AddEntry(System.String,Ionic.Zip.WriteDelegate)"/>, the application
code provides the logic that writes the entry data directly into the zip file.
</remarks>
<example>
This example shows how to define a WriteDelegate that obtains a DataSet, and then
writes the XML for the DataSet into the zip archive. There's no need to
save the XML to a disk file first.
<code lang="C#">
private void WriteEntry (String filename, Stream output)
{
DataSet ds1 = ObtainDataSet();
ds1.WriteXml(output);
}
private void Run()
{
using (var zip = new ZipFile())
{
zip.AddEntry(zipEntryName, WriteEntry);
zip.Save(zipFileName);
}
}
</code>
<code lang="vb">
Private Sub WriteEntry (ByVal filename As String, ByVal output As Stream)
DataSet ds1 = ObtainDataSet()
ds1.WriteXml(stream)
End Sub
Public Sub Run()
Using zip = New ZipFile
zip.AddEntry(zipEntryName, New WriteDelegate(AddressOf WriteEntry))
zip.Save(zipFileName)
End Using
End Sub
</code>
</example>
<seealso cref="M:Ionic.Zip.ZipFile.AddEntry(System.String,Ionic.Zip.WriteDelegate)"/>
</member>
<member name="T:Ionic.Zip.OpenDelegate">
<summary>
Delegate in which the application opens the stream, just-in-time, for the named entry.
</summary>
<param name="entryName">
The name of the ZipEntry that the application should open the stream for.
</param>
<remarks>
When you add an entry via <see cref="M:Ionic.Zip.ZipFile.AddEntry(System.String,Ionic.Zip.OpenDelegate,Ionic.Zip.CloseDelegate)"/>, the application code provides the logic that
opens and closes the stream for the given ZipEntry.
</remarks>
<seealso cref="M:Ionic.Zip.ZipFile.AddEntry(System.String,Ionic.Zip.OpenDelegate,Ionic.Zip.CloseDelegate)"/>
</member>
<member name="T:Ionic.Zip.CloseDelegate">
<summary>
Delegate in which the application closes the stream, just-in-time, for the named entry.
</summary>
<param name="entryName">
The name of the ZipEntry that the application should close the stream for.
</param>
<param name="stream">The stream to be closed.</param>
<remarks>
When you add an entry via <see cref="M:Ionic.Zip.ZipFile.AddEntry(System.String,Ionic.Zip.OpenDelegate,Ionic.Zip.CloseDelegate)"/>, the application code provides the logic that
opens and closes the stream for the given ZipEntry.
</remarks>
<seealso cref="M:Ionic.Zip.ZipFile.AddEntry(System.String,Ionic.Zip.OpenDelegate,Ionic.Zip.CloseDelegate)"/>
</member>
<member name="T:Ionic.Zip.SetCompressionCallback">
<summary>
Delegate for the callback by which the application tells the
library the CompressionLevel to use for a file.
</summary>
<remarks>
<para>
Using this callback, the application can, for example, specify that
previously-compressed files (.mp3, .png, .docx, etc) should use a
<c>CompressionLevel</c> of <c>None</c>, or can set the compression level based
on any other factor.
</para>
</remarks>
<seealso cref="P:Ionic.Zip.ZipFile.SetCompression"/>
</member>
<member name="T:Ionic.Zip.ZipProgressEventType">
<summary>
In an EventArgs type, indicates which sort of progress event is being reported.
</summary>
<remarks>
There are events for reading, events for saving, and events for extracting.
</remarks>
</member>
<member name="F:Ionic.Zip.ZipProgressEventType.Adding_Started">
<summary>
Indicates that a Add() operation has started.
</summary>
</member>
<member name="F:Ionic.Zip.ZipProgressEventType.Adding_AfterAddEntry">
<summary>
Indicates that an individual entry in the archive has been added.
</summary>
</member>
<member name="F:Ionic.Zip.ZipProgressEventType.Adding_Completed">
<summary>
Indicates that a Add() operation has completed.
</summary>
</member>
<member name="F:Ionic.Zip.ZipProgressEventType.Reading_Started">
<summary>
Indicates that a Read() operation has started.
</summary>
</member>
<member name="F:Ionic.Zip.ZipProgressEventType.Reading_BeforeReadEntry">
<summary>
Indicates that an individual entry in the archive is about to be read.
</summary>
</member>
<member name="F:Ionic.Zip.ZipProgressEventType.Reading_AfterReadEntry">
<summary>
Indicates that an individual entry in the archive has just been read.
</summary>
</member>
<member name="F:Ionic.Zip.ZipProgressEventType.Reading_Completed">
<summary>
Indicates that a Read() operation has completed.
</summary>
</member>
<member name="F:Ionic.Zip.ZipProgressEventType.Reading_ArchiveBytesRead">
<summary>
The given event reports the number of bytes read so far
during a Read() operation.
</summary>
</member>
<member name="F:Ionic.Zip.ZipProgressEventType.Saving_Started">
<summary>
Indicates that a Save() operation has started.
</summary>
</member>
<member name="F:Ionic.Zip.ZipProgressEventType.Saving_BeforeWriteEntry">
<summary>
Indicates that an individual entry in the archive is about to be written.
</summary>
</member>
<member name="F:Ionic.Zip.ZipProgressEventType.Saving_AfterWriteEntry">
<summary>
Indicates that an individual entry in the archive has just been saved.
</summary>
</member>
<member name="F:Ionic.Zip.ZipProgressEventType.Saving_Completed">
<summary>
Indicates that a Save() operation has completed.
</summary>
</member>
<member name="F:Ionic.Zip.ZipProgressEventType.Saving_AfterSaveTempArchive">
<summary>
Indicates that the zip archive has been created in a
temporary location during a Save() operation.
</summary>
</member>
<member name="F:Ionic.Zip.ZipProgressEventType.Saving_BeforeRenameTempArchive">
<summary>
Indicates that the temporary file is about to be renamed to the final archive
name during a Save() operation.
</summary>
</member>
<member name="F:Ionic.Zip.ZipProgressEventType.Saving_AfterRenameTempArchive">
<summary>
Indicates that the temporary file is has just been renamed to the final archive
name during a Save() operation.
</summary>
</member>
<member name="F:Ionic.Zip.ZipProgressEventType.Saving_AfterCompileSelfExtractor">
<summary>
Indicates that the self-extracting archive has been compiled
during a Save() operation.
</summary>
</member>
<member name="F:Ionic.Zip.ZipProgressEventType.Saving_EntryBytesRead">
<summary>
The given event is reporting the number of source bytes that have run through the compressor so far
during a Save() operation.
</summary>
</member>
<member name="F:Ionic.Zip.ZipProgressEventType.Extracting_BeforeExtractEntry">
<summary>
Indicates that an entry is about to be extracted.
</summary>
</member>
<member name="F:Ionic.Zip.ZipProgressEventType.Extracting_AfterExtractEntry">
<summary>
Indicates that an entry has just been extracted.
</summary>
</member>
<member name="F:Ionic.Zip.ZipProgressEventType.Extracting_ExtractEntryWouldOverwrite">
<summary>
Indicates that extraction of an entry would overwrite an existing filesystem file.
</summary>
</member>
<member name="F:Ionic.Zip.ZipProgressEventType.Extracting_EntryBytesWritten">
<summary>
The given event is reporting the number of bytes written so far for the current entry
during an Extract() operation.
</summary>
</member>
<member name="F:Ionic.Zip.ZipProgressEventType.Extracting_BeforeExtractAll">
<summary>
Indicates that an ExtractAll operation is about to begin.
</summary>
</member>
<member name="F:Ionic.Zip.ZipProgressEventType.Extracting_AfterExtractAll">
<summary>
Indicates that an ExtractAll operation has completed.
</summary>
</member>
<member name="F:Ionic.Zip.ZipProgressEventType.Error_Saving">
<summary>
Indicates that an error has occurred while saving a zip file.
This generally means the file cannot be opened, because it has been
removed, or because it is locked by another process. It can also
mean that the file cannot be Read, because of a range lock conflict.
</summary>
</member>
<member name="T:Ionic.Zip.ZipProgressEventArgs">
<summary>
Provides information about the progress of a save, read, or extract operation.
This is a base class; you will probably use one of the classes derived from this one.
</summary>
</member>
<member name="P:Ionic.Zip.ZipProgressEventArgs.EntriesTotal">
<summary>
The total number of entries to be saved or extracted.
</summary>
</member>
<member name="P:Ionic.Zip.ZipProgressEventArgs.CurrentEntry">
<summary>
The name of the last entry saved or extracted.
</summary>
</member>
<member name="P:Ionic.Zip.ZipProgressEventArgs.Cancel">
<summary>
In an event handler, set this to cancel the save or extract
operation that is in progress.
</summary>
</member>
<member name="P:Ionic.Zip.ZipProgressEventArgs.EventType">
<summary>
The type of event being reported.
</summary>
</member>
<member name="P:Ionic.Zip.ZipProgressEventArgs.ArchiveName">
<summary>
Returns the archive name associated to this event.
</summary>
</member>
<member name="P:Ionic.Zip.ZipProgressEventArgs.BytesTransferred">
<summary>
The number of bytes read or written so far for this entry.
</summary>
</member>
<member name="P:Ionic.Zip.ZipProgressEventArgs.TotalBytesToTransfer">
<summary>
Total number of bytes that will be read or written for this entry.
This number will be -1 if the value cannot be determined.
</summary>
</member>
<member name="T:Ionic.Zip.ReadProgressEventArgs">
<summary>
Provides information about the progress of a Read operation.
</summary>
</member>
<member name="T:Ionic.Zip.AddProgressEventArgs">
<summary>
Provides information about the progress of a Add operation.
</summary>
</member>
<member name="T:Ionic.Zip.SaveProgressEventArgs">
<summary>
Provides information about the progress of a save operation.
</summary>
</member>
<member name="M:Ionic.Zip.SaveProgressEventArgs.#ctor(System.String,System.Boolean,System.Int32,System.Int32,Ionic.Zip.ZipEntry)">
<summary>
Constructor for the SaveProgressEventArgs.
</summary>
<param name="archiveName">the name of the zip archive.</param>
<param name="before">whether this is before saving the entry, or after</param>
<param name="entriesTotal">The total number of entries in the zip archive.</param>
<param name="entriesSaved">Number of entries that have been saved.</param>
<param name="entry">The entry involved in the event.</param>
</member>
<member name="P:Ionic.Zip.SaveProgressEventArgs.EntriesSaved">
<summary>
Number of entries saved so far.
</summary>
</member>
<member name="T:Ionic.Zip.ExtractProgressEventArgs">
<summary>
Provides information about the progress of the extract operation.
</summary>
</member>
<member name="M:Ionic.Zip.ExtractProgressEventArgs.#ctor(System.String,System.Boolean,System.Int32,System.Int32,Ionic.Zip.ZipEntry,System.String)">
<summary>
Constructor for the ExtractProgressEventArgs.
</summary>
<param name="archiveName">the name of the zip archive.</param>
<param name="before">whether this is before saving the entry, or after</param>
<param name="entriesTotal">The total number of entries in the zip archive.</param>
<param name="entriesExtracted">Number of entries that have been extracted.</param>
<param name="entry">The entry involved in the event.</param>
<param name="extractLocation">The location to which entries are extracted.</param>
</member>
<member name="P:Ionic.Zip.ExtractProgressEventArgs.EntriesExtracted">
<summary>
Number of entries extracted so far. This is set only if the
EventType is Extracting_BeforeExtractEntry or Extracting_AfterExtractEntry, and
the Extract() is occurring witin the scope of a call to ExtractAll().
</summary>
</member>
<member name="P:Ionic.Zip.ExtractProgressEventArgs.ExtractLocation">
<summary>
Returns the extraction target location, a filesystem path.
</summary>
</member>
<member name="T:Ionic.Zip.ZipErrorEventArgs">
<summary>
Provides information about the an error that occurred while zipping.
</summary>
</member>
<member name="P:Ionic.Zip.ZipErrorEventArgs.Exception">
<summary>
Returns the exception that occurred, if any.
</summary>
</member>
<member name="P:Ionic.Zip.ZipErrorEventArgs.FileName">
<summary>
Returns the name of the file that caused the exception, if any.
</summary>
</member>
<member name="T:Ionic.Zip.ZipErrorAction">
<summary>
An enum providing the options when an error occurs during opening or reading
of a file or directory that is being saved to a zip file.
</summary>
<remarks>
<para>
This enum describes the actions that the library can take when an error occurs
opening or reading a file, as it is being saved into a Zip archive.
</para>
<para>
In some cases an error will occur when DotNetZip tries to open a file to be
added to the zip archive. In other cases, an error might occur after the
file has been successfully opened, while DotNetZip is reading the file.
</para>
<para>
The first problem might occur when calling AddDirectory() on a directory
that contains a Clipper .dbf file; the file is locked by Clipper and
cannot be opened by another process. An example of the second problem is
the ERROR_LOCK_VIOLATION that results when a file is opened by another
process, but not locked, and a range lock has been taken on the file.
Microsoft Outlook takes range locks on .PST files.
</para>
</remarks>
</member>
<member name="F:Ionic.Zip.ZipErrorAction.Throw">
<summary>
Throw an exception when an error occurs while zipping. This is the default
behavior. (For COM clients, this is a 0 (zero).)
</summary>
</member>
<member name="F:Ionic.Zip.ZipErrorAction.Skip">
<summary>
When an error occurs during zipping, for example a file cannot be opened,
skip the file causing the error, and continue zipping. (For COM clients,
this is a 1.)
</summary>
</member>
<member name="F:Ionic.Zip.ZipErrorAction.Retry">
<summary>
When an error occurs during zipping, for example a file cannot be opened,
retry the operation that caused the error. Be careful with this option. If
the error is not temporary, the library will retry forever. (For COM
clients, this is a 2.)
</summary>
</member>
<member name="F:Ionic.Zip.ZipErrorAction.InvokeErrorEvent">
<summary>
When an error occurs, invoke the zipError event. The event type used is
<see cref="F:Ionic.Zip.ZipProgressEventType.Error_Saving"/>. A typical use of this option:
a GUI application may wish to pop up a dialog to allow the user to view the
error that occurred, and choose an appropriate action. After your
processing in the error event, if you want to skip the file, set <see cref="P:Ionic.Zip.ZipEntry.ZipErrorAction"/> on the
<c>ZipProgressEventArgs.CurrentEntry</c> to <c>Skip</c>. If you want the
exception to be thrown, set <c>ZipErrorAction</c> on the <c>CurrentEntry</c>
to <c>Throw</c>. If you want to cancel the zip, set
<c>ZipProgressEventArgs.Cancel</c> to true. Cancelling differs from using
Skip in that a cancel will not save any further entries, if there are any.
(For COM clients, the value of this enum is a 3.)
</summary>
</member>
<member name="T:Ionic.Zip.EncryptionAlgorithm">
<summary>
An enum that provides the various encryption algorithms supported by this
library.
</summary>
<remarks>
<para>
<c>PkzipWeak</c> implies the use of Zip 2.0 encryption, which is known to be
weak and subvertible.
</para>
<para>
A note on interoperability: Values of <c>PkzipWeak</c> and <c>None</c> are
specified in <see href="http://www.pkware.com/documents/casestudies/APPNOTE.TXT">PKWARE's zip
specification</see>, and are considered to be "standard". Zip archives
produced using these options will be interoperable with many other zip tools
and libraries, including Windows Explorer.
</para>
<para>
Values of <c>WinZipAes128</c> and <c>WinZipAes256</c> are not part of the Zip
specification, but rather imply the use of a vendor-specific extension from
WinZip. If you want to produce interoperable Zip archives, do not use these
values. For example, if you produce a zip archive using WinZipAes256, you
will be able to open it in Windows Explorer on Windows XP and Vista, but you
will not be able to extract entries; trying this will lead to an "unspecified
error". For this reason, some people have said that a zip archive that uses
WinZip's AES encryption is not actually a zip archive at all. A zip archive
produced this way will be readable with the WinZip tool (Version 11 and
beyond).
</para>
<para>
There are other third-party tools and libraries, both commercial and
otherwise, that support WinZip's AES encryption. These will be able to read
AES-encrypted zip archives produced by DotNetZip, and conversely applications
that use DotNetZip to read zip archives will be able to read AES-encrypted
archives produced by those tools or libraries. Consult the documentation for
those other tools and libraries to find out if WinZip's AES encryption is
supported.
</para>
<para>
In case you care: According to <see href="http://www.winzip.com/aes_info.htm">the WinZip specification</see>, the
actual AES key used is derived from the <see cref="P:Ionic.Zip.ZipEntry.Password"/> via an
algorithm that complies with <see href="http://www.ietf.org/rfc/rfc2898.txt">RFC 2898</see>, using an iteration
count of 1000. The algorithm is sometimes referred to as PBKDF2, which stands
for "Password Based Key Derivation Function #2".
</para>
<para>
A word about password strength and length: The AES encryption technology is
very good, but any system is only as secure as the weakest link. If you want
to secure your data, be sure to use a password that is hard to guess. To make
it harder to guess (increase its "entropy"), you should make it longer. If
you use normal characters from an ASCII keyboard, a password of length 20 will
be strong enough that it will be impossible to guess. For more information on
that, I'd encourage you to read <see href="http://www.redkestrel.co.uk/Articles/RandomPasswordStrength.html">this
article.</see>
</para>
<para>
The WinZip AES algorithms are not supported with the version of DotNetZip that
runs on the .NET Compact Framework. This is because .NET CF lacks the
HMACSHA1 class that is required for producing the archive.
</para>
</remarks>
</member>
<member name="F:Ionic.Zip.EncryptionAlgorithm.None">
<summary>
No encryption at all.
</summary>
</member>
<member name="F:Ionic.Zip.EncryptionAlgorithm.PkzipWeak">
<summary>
Traditional or Classic pkzip encryption.
</summary>
</member>
<member name="F:Ionic.Zip.EncryptionAlgorithm.WinZipAes128">
<summary>
WinZip AES encryption (128 key bits).
</summary>
</member>
<member name="F:Ionic.Zip.EncryptionAlgorithm.WinZipAes256">
<summary>
WinZip AES encryption (256 key bits).
</summary>
</member>
<member name="F:Ionic.Zip.EncryptionAlgorithm.Unsupported">
<summary>
An encryption algorithm that is not supported by DotNetZip.
</summary>
</member>
<member name="T:Ionic.FileSelector">
<summary>
FileSelector encapsulates logic that selects files from a source - a zip file
or the filesystem - based on a set of criteria. This class is used internally
by the DotNetZip library, in particular for the AddSelectedFiles() methods.
This class can also be used independently of the zip capability in DotNetZip.
</summary>
<remarks>
<para>
The FileSelector class is used internally by the ZipFile class for selecting
files for inclusion into the ZipFile, when the <see cref="M:Ionic.Zip.ZipFile.AddSelectedFiles(System.String,System.String)"/> method, or one of
its overloads, is called. It's also used for the <see cref="M:Ionic.Zip.ZipFile.ExtractSelectedEntries(System.String)"/> methods. Typically, an
application that creates or manipulates Zip archives will not directly
interact with the FileSelector class.
</para>
<para>
Some applications may wish to use the FileSelector class directly, to
select files from disk volumes based on a set of criteria, without creating or
querying Zip archives. The file selection criteria include: a pattern to
match the filename; the last modified, created, or last accessed time of the
file; the size of the file; and the attributes of the file.
</para>
<para>
Consult the documentation for <see cref="P:Ionic.FileSelector.SelectionCriteria"/>
for more information on specifying the selection criteria.
</para>
</remarks>
</member>
<member name="M:Ionic.FileSelector.SelectEntries(Ionic.Zip.ZipFile)">
<summary>
Retrieve the ZipEntry items in the ZipFile that conform to the specified criteria.
</summary>
<remarks>
<para>
This method applies the criteria set in the FileSelector instance (as described in
the <see cref="P:Ionic.FileSelector.SelectionCriteria"/>) to the specified ZipFile. Using this
method, for example, you can retrieve all entries from the given ZipFile that
have filenames ending in .txt.
</para>
<para>
Normally, applications would not call this method directly. This method is used
by the ZipFile class.
</para>
<para>
Using the appropriate SelectionCriteria, you can retrieve entries based on size,
time, and attributes. See <see cref="P:Ionic.FileSelector.SelectionCriteria"/> for a
description of the syntax of the SelectionCriteria string.
</para>
</remarks>
<param name="zip">The ZipFile from which to retrieve entries.</param>
<returns>a collection of ZipEntry objects that conform to the criteria.</returns>
</member>
<member name="M:Ionic.FileSelector.SelectEntries(Ionic.Zip.ZipFile,System.String)">
<summary>
Retrieve the ZipEntry items in the ZipFile that conform to the specified criteria.
</summary>
<remarks>
<para>
This method applies the criteria set in the FileSelector instance (as described in
the <see cref="P:Ionic.FileSelector.SelectionCriteria"/>) to the specified ZipFile. Using this
method, for example, you can retrieve all entries from the given ZipFile that
have filenames ending in .txt.
</para>
<para>
Normally, applications would not call this method directly. This method is used
by the ZipFile class.
</para>
<para>
This overload allows the selection of ZipEntry instances from the ZipFile to be restricted
to entries contained within a particular directory in the ZipFile.
</para>
<para>
Using the appropriate SelectionCriteria, you can retrieve entries based on size,
time, and attributes. See <see cref="P:Ionic.FileSelector.SelectionCriteria"/> for a
description of the syntax of the SelectionCriteria string.
</para>
</remarks>
<param name="zip">The ZipFile from which to retrieve entries.</param>
<param name="directoryPathInArchive">
the directory in the archive from which to select entries. If null, then
all directories in the archive are used.
</param>
<returns>a collection of ZipEntry objects that conform to the criteria.</returns>
</member>
<member name="M:Ionic.FileSelector.#ctor(System.String)">
<summary>
Constructor that allows the caller to specify file selection criteria.
</summary>
<remarks>
<para>
This constructor allows the caller to specify a set of criteria for selection of files.
</para>
<para>
See <see cref="P:Ionic.FileSelector.SelectionCriteria"/> for a description of the syntax of
the selectionCriteria string.
</para>
<para>
By default the FileSelector will traverse NTFS Reparse Points.
To change this, use <see cref="M:Ionic.FileSelector.#ctor(System.String,System.Boolean)">FileSelector(String, bool)</see>.
</para>
</remarks>
<param name="selectionCriteria">The criteria for file selection.</param>
</member>
<member name="M:Ionic.FileSelector.#ctor(System.String,System.Boolean)">
<summary>
Constructor that allows the caller to specify file selection criteria.
</summary>
<remarks>
<para>
This constructor allows the caller to specify a set of criteria for selection of files.
</para>
<para>
See <see cref="P:Ionic.FileSelector.SelectionCriteria"/> for a description of the syntax of
the selectionCriteria string.
</para>
</remarks>
<param name="selectionCriteria">The criteria for file selection.</param>
<param name="traverseDirectoryReparsePoints">
whether to traverse NTFS reparse points (junctions).
</param>
</member>
<member name="M:Ionic.FileSelector.ToString">
<summary>
Returns a string representation of the FileSelector object.
</summary>
<returns>The string representation of the boolean logic statement of the file
selection criteria for this instance. </returns>
</member>
<member name="M:Ionic.FileSelector.SelectFiles(System.String)">
<summary>
Returns the names of the files in the specified directory
that fit the selection criteria specified in the FileSelector.
</summary>
<remarks>
This is equivalent to calling <see cref="M:Ionic.FileSelector.SelectFiles(System.String,System.Boolean)"/>
with recurseDirectories = false.
</remarks>
<param name="directory">
The name of the directory over which to apply the FileSelector criteria.
</param>
<returns>
A collection of strings containing fully-qualified pathnames of files
that match the criteria specified in the FileSelector instance.
</returns>
</member>
<member name="M:Ionic.FileSelector.SelectFiles(System.String,System.Boolean)">
<summary>
Returns the names of the files in the specified directory that fit the selection
criteria specified in the FileSelector, optionally recursing through subdirectories.
</summary>
<remarks>
This method applies the file selection criteria contained in the FileSelector to the
files contained in the given directory, and returns the names of files that
conform to the criteria.
</remarks>
<param name="directory">
The name of the directory over which to apply the FileSelector criteria.
</param>
<param name="recurseDirectories">
Whether to recurse through subdirectories when applying the file selection criteria.
</param>
<returns>
An collection of strings containing fully-qualified pathnames of files
that match the criteria specified in the FileSelector instance.
</returns>
</member>
<member name="P:Ionic.FileSelector.SelectionCriteria">
<summary>
The string specifying which files to include when retrieving.
</summary>
<remarks>
<para>
Specify the criteria in statements of 3 elements: a noun, an operator, and a value.
Consider the string "name != *.doc" . The noun is "name". The operator is "!=",
implying "Not Equal". The value is "*.doc". That criterion, in English, says "all
files with a name that does not end in the .doc extension."
</para>
<para>
Supported nouns include "name" (or "filename") for the filename; "atime",
"mtime", and "ctime" for last access time, last modfied time, and created
time of the file, respectively; "attributes" (or "attrs") for the file
attributes; "size" (or "length") for the file length (uncompressed); and
"type" for the type of object, either a file or a directory. The
"attributes", "type", and "name" nouns all support = and != as operators.
The "size", "atime", "mtime", and "ctime" nouns support = and !=, and &gt;,
&gt;=, &lt;, &lt;= as well. The times are taken to be expressed in "local
time".
</para>
<para>
Specify values for the file attributes as a string with one or more of the
characters H,R,S,A,I,L in any order, implying file attributes of Hidden,
ReadOnly, System, Archive, NotContextIndexed, and ReparsePoint (symbolic
link) respectively.
</para>
<para>
To specify a time, use YYYY-MM-DD-HH:mm:ss or YYYY/MM/DD-HH:mm:ss as the
format. If you omit the HH:mm:ss portion, it is assumed to be 00:00:00
(midnight).
</para>
<para>
The value for a size criterion is expressed in integer quantities of bytes,
kilobytes (use k or kb after the number), megabytes (m or mb), or gigabytes
(g or gb).
</para>
<para>
The value for a name is a pattern to match against the filename, potentially
including wildcards. The pattern follows CMD.exe glob rules: * implies one
or more of any character, while ? implies one character. If the name
pattern contains any slashes, it is matched to the entire filename,
including the path; otherwise, it is matched against only the filename
without the path. This means a pattern of "*\*.*" matches all files one
directory level deep, while a pattern of "*.*" matches all files in all
directories.
</para>
<para>
To specify a name pattern that includes spaces, use single quotes around the
pattern. A pattern of "'* *.*'" will match all files that have spaces in
the filename. The full criteria string for that would be "name = '* *.*'" .
</para>
<para>
The value for a type criterion is either F (implying a file) or D (implying
a directory).
</para>
<para>
Some examples:
</para>
<list type="table">
<listheader>
<term>criteria</term>
<description>Files retrieved</description>
</listheader>
<item>
<term>name != *.xls </term>
<description>any file with an extension that is not .xls
</description>
</item>
<item>
<term>name = *.mp3 </term>
<description>any file with a .mp3 extension.
</description>
</item>
<item>
<term>*.mp3</term>
<description>(same as above) any file with a .mp3 extension.
</description>
</item>
<item>
<term>attributes = A </term>
<description>all files whose attributes include the Archive bit.
</description>
</item>
<item>
<term>attributes != H </term>
<description>all files whose attributes do not include the Hidden bit.
</description>
</item>
<item>
<term>mtime &gt; 2009-01-01</term>
<description>all files with a last modified time after January 1st, 2009.
</description>
</item>
<item>
<term>ctime &gt; 2009/01/01-03:00:00</term>
<description>all files with a created time after 3am (local time), on January 1st, 2009.
</description>
</item>
<item>
<term>size &gt; 2gb</term>
<description>all files whose uncompressed size is greater than 2gb.
</description>
</item>
<item>
<term>type = D</term>
<description>all directories in the filesystem. </description>
</item>
</list>
<para>
You can combine criteria with the conjunctions AND, OR, and XOR. Using a string like
"name = *.txt AND size &gt;= 100k" for the selectionCriteria retrieves entries whose
names end in .txt, and whose uncompressed size is greater than or equal to 100
kilobytes.
</para>
<para>
For more complex combinations of criteria, you can use parenthesis to group clauses
in the boolean logic. Absent parenthesis, the precedence of the criterion atoms is
determined by order of appearance. Unlike the C# language, the AND conjunction does
not take precendence over the logical OR. This is important only in strings that
contain 3 or more criterion atoms. In other words, "name = *.txt and size &gt; 1000
or attributes = H" implies "((name = *.txt AND size &gt; 1000) OR attributes = H)"
while "attributes = H OR name = *.txt and size &gt; 1000" evaluates to "((attributes
= H OR name = *.txt) AND size &gt; 1000)". When in doubt, use parenthesis.
</para>
<para>
Using time properties requires some extra care. If you want to retrieve all entries
that were last updated on 2009 February 14, specify "mtime &gt;= 2009-02-14 AND
mtime &lt; 2009-02-15". Read this to say: all files updated after 12:00am on
February 14th, until 12:00am on February 15th. You can use the same bracketing
approach to specify any time period - a year, a month, a week, and so on.
</para>
<para>
The syntax allows one special case: if you provide a string with no spaces, it is treated as
a pattern to match for the filename. Therefore a string like "*.xls" will be equivalent to
specifying "name = *.xls". This "shorthand" notation does not work with compound criteria.
</para>
<para>
There is no logic in this class that insures that the inclusion criteria
are internally consistent. For example, it's possible to specify criteria that
says the file must have a size of less than 100 bytes, as well as a size that
is greater than 1000 bytes. Obviously no file will ever satisfy such criteria,
but this class does not check for or detect such inconsistencies.
</para>
</remarks>
<exception cref="T:System.Exception">
Thrown in the setter if the value has an invalid syntax.
</exception>
</member>
<member name="P:Ionic.FileSelector.TraverseReparsePoints">
<summary>
Indicates whether searches will traverse NTFS reparse points, like Junctions.
</summary>
</member>
<member name="T:Ionic.Zip.ExtractExistingFileAction">
<summary>
An enum for the options when extracting an entry would overwrite an existing file.
</summary>
<remarks>
<para>
This enum describes the actions that the library can take when an
<c>Extract()</c> or <c>ExtractWithPassword()</c> method is called to extract an
entry to a filesystem, and the extraction would overwrite an existing filesystem
file.
</para>
</remarks>
</member>
<member name="F:Ionic.Zip.ExtractExistingFileAction.Throw">
<summary>
Throw an exception when extraction would overwrite an existing file. (For
COM clients, this is a 0 (zero).)
</summary>
</member>
<member name="F:Ionic.Zip.ExtractExistingFileAction.OverwriteSilently">
<summary>
When extraction would overwrite an existing file, overwrite the file silently.
The overwrite will happen even if the target file is marked as read-only.
(For COM clients, this is a 1.)
</summary>
</member>
<member name="F:Ionic.Zip.ExtractExistingFileAction.DoNotOverwrite">
<summary>
When extraction would overwrite an existing file, don't overwrite the file, silently.
(For COM clients, this is a 2.)
</summary>
</member>
<member name="F:Ionic.Zip.ExtractExistingFileAction.InvokeExtractProgressEvent">
<summary>
When extraction would overwrite an existing file, invoke the ExtractProgress
event, using an event type of <see cref="F:Ionic.Zip.ZipProgressEventType.Extracting_ExtractEntryWouldOverwrite"/>. In
this way, the application can decide, just-in-time, whether to overwrite the
file. For example, a GUI application may wish to pop up a dialog to allow
the user to choose. You may want to examine the <see cref="P:Ionic.Zip.ExtractProgressEventArgs.ExtractLocation"/> property before making
the decision. If, after your processing in the Extract progress event, you
want to NOT extract the file, set <see cref="P:Ionic.Zip.ZipEntry.ExtractExistingFile"/>
on the <c>ZipProgressEventArgs.CurrentEntry</c> to <c>DoNotOverwrite</c>.
If you do want to extract the file, set <c>ZipEntry.ExtractExistingFile</c>
to <c>OverwriteSilently</c>. If you want to cancel the Extraction, set
<c>ZipProgressEventArgs.Cancel</c> to true. Cancelling differs from using
DoNotOverwrite in that a cancel will not extract any further entries, if
there are any. (For COM clients, the value of this enum is a 3.)
</summary>
</member>
<member name="T:Ionic.Zip.ZipEntrySource">
<summary>
An enum that specifies the source of the ZipEntry.
</summary>
</member>
<member name="F:Ionic.Zip.ZipEntrySource.None">
<summary>
Default value. Invalid on a bonafide ZipEntry.
</summary>
</member>
<member name="F:Ionic.Zip.ZipEntrySource.FileSystem">
<summary>
The entry was instantiated by calling AddFile() or another method that
added an entry from the filesystem.
</summary>
</member>
<member name="F:Ionic.Zip.ZipEntrySource.Stream">
<summary>
The entry was instantiated via <see cref="M:Ionic.Zip.ZipFile.AddEntry(System.String,System.String)"/> or
<see cref="M:Ionic.Zip.ZipFile.AddEntry(System.String,System.IO.Stream)"/> .
</summary>
</member>
<member name="F:Ionic.Zip.ZipEntrySource.ZipFile">
<summary>
The ZipEntry was instantiated by reading a zipfile.
</summary>
</member>
<member name="F:Ionic.Zip.ZipEntrySource.WriteDelegate">
<summary>
The content for the ZipEntry will be or was provided by the WriteDelegate.
</summary>
</member>
<member name="F:Ionic.Zip.ZipEntrySource.JitStream">
<summary>
The content for the ZipEntry will be obtained from the stream dispensed by the <c>OpenDelegate</c>.
The entry was instantiated via <see cref="M:Ionic.Zip.ZipFile.AddEntry(System.String,Ionic.Zip.OpenDelegate,Ionic.Zip.CloseDelegate)"/>.
</summary>
</member>
<member name="F:Ionic.Zip.ZipEntrySource.ZipOutputStream">
<summary>
The content for the ZipEntry will be or was obtained from a <c>ZipOutputStream</c>.
</summary>
</member>
<member name="M:Ionic.Zip.ZipSegmentedStream.Read(System.Byte[],System.Int32,System.Int32)">
<summary>
Read from the stream
</summary>
<param name="buffer">the buffer to read</param>
<param name="offset">the offset at which to start</param>
<param name="count">the number of bytes to read</param>
<returns>the number of bytes actually read</returns>
</member>
<member name="M:Ionic.Zip.ZipSegmentedStream.Write(System.Byte[],System.Int32,System.Int32)">
<summary>
Write to the stream.
</summary>
<param name="buffer">the buffer from which to write</param>
<param name="offset">the offset at which to start writing</param>
<param name="count">the number of bytes to write</param>
</member>
<member name="T:Ionic.Zip.ZipOutputStream">
<summary>
Provides a stream metaphor for generating zip files.
</summary>
<remarks>
<para>
This class provides an alternative programming model to the one enabled by the
<see cref="T:Ionic.Zip.ZipFile"/> class. Use this when creating zip files, as an
alternative to the <see cref="T:Ionic.Zip.ZipFile"/> class, when you would like to use a
Stream class to write the zip file.
</para>
<para>
Some designs require a writable stream for output. This stream can be used to
produce a zip file, as it is written.
</para>
<para>
Both the <c>ZipOutputStream</c> class and the <c>ZipFile</c> class can be used
to create zip files. Both of them support many of the common zip features,
including Unicode, different compression levels, and ZIP64. For example, when
creating a zip file via calls to the <c>PutNextEntry()</c> and <c>Write()</c>
methods on the <c>ZipOutputStream</c> class, the caller is responsible for
opening the file, reading the bytes from the file, writing those bytes into
the <c>ZipOutputStream</c>, setting the attributes on the <c>ZipEntry</c>, and
setting the created, last modified, and last accessed timestamps on the zip
entry. All of these things are done automatically by a call to <see cref="M:Ionic.Zip.ZipFile.AddFile(System.String,System.String)">ZipFile.AddFile()</see>. For this
reason, the <c>ZipOutputStream</c> is generally recommended for when your
application wants to emit the arbitrary data, not necessarily data from a
filesystem file, directly into a zip file.
</para>
<para>
Aside from the differences in programming model, there are other
differences in capability between the two classes.
</para>
<list type="bullet">
<item>
<c>ZipFile</c> can be used to read and extract zip files, in addition to
creating zip files. <c>ZipOutputStream</c> cannot read zip files. If you want
to use a stream to read zip files, check out the <see cref="T:Ionic.Zip.ZipInputStream"/> class.
</item>
<item>
<c>ZipOutputStream</c> does not support the creation of segmented or spanned
zip files.
</item>
<item>
<c>ZipOutputStream</c> cannot produce a self-extracting archive.
</item>
</list>
</remarks>
</member>
<member name="M:Ionic.Zip.ZipOutputStream.#ctor(System.IO.Stream)">
<summary>
Create a ZipOutputStream, wrapping an existing stream.
</summary>
<remarks>
<para>
The <see cref="T:Ionic.Zip.ZipFile"/> class is generally easier to use when creating
zip files. The ZipOutputStream offers a different metaphor for creating a
zip file, based on the <see cref="T:System.IO.Stream"/> class.
</para>
<para>
On the desktop .NET Framework, DotNetZip can use a multi-threaded
compression implementation that provides significant speed increases on
large files, over 300k or so, at the cost of increased memory use at
runtime. (The output of the compression is almost exactly the same size).
But, the multi-threaded approach incurs a performance hit on smaller
files. There's no way for the ZipOutputStream to know whether parallel
compression will be beneficial, because the ZipOutputStream does not know
how much data you will write through the stream. you may wish to set the
<see cref="P:Ionic.Zip.ZipOutputStream.ParallelDeflateThreshold"/> property to zero, if you are
compressing large files through <c>ZipOutputStream</c>. This will cause
parallel compression to be used, always.
</para>
</remarks>
<param name="stream">
The stream to wrap. It must be writable. This stream will be closed at
the time the ZipOutputStream is closed.
</param>
<example>
This example shows how to create a zip file, using the
ZipOutputStream class.
<code lang="C#">
private void Zipup()
{
if (filesToZip.Count == 0)
{
System.Console.WriteLine("Nothing to do.");
return;
}
using (var raw = File.Open(_outputFileName, FileMode.Create, FileAccess.ReadWrite ))
{
using (var output= new ZipOutputStream(raw))
{
output.Password = "VerySecret!";
output.Encryption = EncryptionAlgorithm.WinZipAes256;
foreach (string inputFileName in filesToZip)
{
System.Console.WriteLine("file: {0}", inputFileName);
output.PutNextEntry(inputFileName);
using (var input = File.Open(inputFileName, FileMode.Open, FileAccess.Read, FileShare.Read | FileShare.Write ))
{
byte[] buffer= new byte[2048];
int n;
while ((n= input.Read(buffer,0,buffer.Length)) &gt; 0)
{
output.Write(buffer,0,n);
}
}
}
}
}
}
</code>
<code lang="VB">
Private Sub Zipup()
Dim outputFileName As String = "XmlData.zip"
Dim filesToZip As String() = Directory.GetFiles(".", "*.xml")
If (filesToZip.Length = 0) Then
Console.WriteLine("Nothing to do.")
Else
Using raw As FileStream = File.Open(outputFileName, FileMode.Create, FileAccess.ReadWrite)
Using output As ZipOutputStream = New ZipOutputStream(raw)
output.Password = "VerySecret!"
output.Encryption = EncryptionAlgorithm.WinZipAes256
Dim inputFileName As String
For Each inputFileName In filesToZip
Console.WriteLine("file: {0}", inputFileName)
output.PutNextEntry(inputFileName)
Using input As FileStream = File.Open(inputFileName, FileMode.Open, FileAccess.Read, FileShare.ReadWrite)
Dim n As Integer
Dim buffer As Byte() = New Byte(2048) {}
Do While (n = input.Read(buffer, 0, buffer.Length) &gt; 0)
output.Write(buffer, 0, n)
Loop
End Using
Next
End Using
End Using
End If
End Sub
</code>
</example>
</member>
<member name="M:Ionic.Zip.ZipOutputStream.#ctor(System.String)">
<summary>
Create a ZipOutputStream that writes to a filesystem file.
</summary>
<remarks>
The <see cref="T:Ionic.Zip.ZipFile"/> class is generally easier to use when creating
zip files. The ZipOutputStream offers a different metaphor for creating a
zip file, based on the <see cref="T:System.IO.Stream"/> class.
</remarks>
<param name="fileName">
The name of the zip file to create.
</param>
<example>
This example shows how to create a zip file, using the
ZipOutputStream class.
<code lang="C#">
private void Zipup()
{
if (filesToZip.Count == 0)
{
System.Console.WriteLine("Nothing to do.");
return;
}
using (var output= new ZipOutputStream(outputFileName))
{
output.Password = "VerySecret!";
output.Encryption = EncryptionAlgorithm.WinZipAes256;
foreach (string inputFileName in filesToZip)
{
System.Console.WriteLine("file: {0}", inputFileName);
output.PutNextEntry(inputFileName);
using (var input = File.Open(inputFileName, FileMode.Open, FileAccess.Read,
FileShare.Read | FileShare.Write ))
{
byte[] buffer= new byte[2048];
int n;
while ((n= input.Read(buffer,0,buffer.Length)) &gt; 0)
{
output.Write(buffer,0,n);
}
}
}
}
}
</code>
<code lang="VB">
Private Sub Zipup()
Dim outputFileName As String = "XmlData.zip"
Dim filesToZip As String() = Directory.GetFiles(".", "*.xml")
If (filesToZip.Length = 0) Then
Console.WriteLine("Nothing to do.")
Else
Using output As ZipOutputStream = New ZipOutputStream(outputFileName)
output.Password = "VerySecret!"
output.Encryption = EncryptionAlgorithm.WinZipAes256
Dim inputFileName As String
For Each inputFileName In filesToZip
Console.WriteLine("file: {0}", inputFileName)
output.PutNextEntry(inputFileName)
Using input As FileStream = File.Open(inputFileName, FileMode.Open, FileAccess.Read, FileShare.ReadWrite)
Dim n As Integer
Dim buffer As Byte() = New Byte(2048) {}
Do While (n = input.Read(buffer, 0, buffer.Length) &gt; 0)
output.Write(buffer, 0, n)
Loop
End Using
Next
End Using
End If
End Sub
</code>
</example>
</member>
<member name="M:Ionic.Zip.ZipOutputStream.#ctor(System.IO.Stream,System.Boolean)">
<summary>
Create a ZipOutputStream.
</summary>
<remarks>
See the documentation for the <see cref="M:Ionic.Zip.ZipOutputStream.#ctor(System.IO.Stream)">ZipOutputStream(Stream)</see>
constructor for an example.
</remarks>
<param name="stream">
The stream to wrap. It must be writable.
</param>
<param name="leaveOpen">
true if the application would like the stream
to remain open after the <c>ZipOutputStream</c> has been closed.
</param>
</member>
<member name="M:Ionic.Zip.ZipOutputStream.ToString">
<summary>Provides a string representation of the instance.</summary>
<remarks>
<para>
This can be useful for debugging purposes.
</para>
</remarks>
<returns>a string representation of the instance.</returns>
</member>
<member name="M:Ionic.Zip.ZipOutputStream.ContainsEntry(System.String)">
<summary>
Returns true if an entry by the given name has already been written
to the ZipOutputStream.
</summary>
<param name="name">
The name of the entry to scan for.
</param>
<returns>
true if an entry by the given name has already been written.
</returns>
</member>
<member name="M:Ionic.Zip.ZipOutputStream.Write(System.Byte[],System.Int32,System.Int32)">
<summary>
Write the data from the buffer to the stream.
</summary>
<remarks>
As the application writes data into this stream, the data may be
compressed and encrypted before being written out to the underlying
stream, depending on the settings of the <see cref="P:Ionic.Zip.ZipOutputStream.CompressionLevel"/>
and the <see cref="P:Ionic.Zip.ZipOutputStream.Encryption"/> properties.
</remarks>
<param name="buffer">The buffer holding data to write to the stream.</param>
<param name="offset">the offset within that data array to find the first byte to write.</param>
<param name="count">the number of bytes to write.</param>
</member>
<member name="M:Ionic.Zip.ZipOutputStream.PutNextEntry(System.String)">
<summary>
Specify the name of the next entry that will be written to the zip file.
</summary>
<remarks>
<para>
Call this method just before calling <see cref="M:Ionic.Zip.ZipOutputStream.Write(System.Byte[],System.Int32,System.Int32)"/>, to
specify the name of the entry that the next set of bytes written to
the <c>ZipOutputStream</c> belongs to. All subsequent calls to <c>Write</c>,
until the next call to <c>PutNextEntry</c>,
will be inserted into the named entry in the zip file.
</para>
<para>
If the <paramref name="entryName"/> used in <c>PutNextEntry()</c> ends in
a slash, then the entry added is marked as a directory. Because directory
entries do not contain data, a call to <c>Write()</c>, before an
intervening additional call to <c>PutNextEntry()</c>, will throw an
exception.
</para>
<para>
If you don't call <c>Write()</c> between two calls to
<c>PutNextEntry()</c>, the first entry is inserted into the zip file as a
file of zero size. This may be what you want.
</para>
<para>
Because <c>PutNextEntry()</c> closes out the prior entry, if any, this
method may throw if there is a problem with the prior entry.
</para>
<para>
This method returns the <c>ZipEntry</c>. You can modify public properties
on the <c>ZipEntry</c>, such as <see cref="P:Ionic.Zip.ZipEntry.Encryption"/>, <see cref="P:Ionic.Zip.ZipEntry.Password"/>, and so on, until the first call to
<c>ZipOutputStream.Write()</c>, or until the next call to
<c>PutNextEntry()</c>. If you modify the <c>ZipEntry</c> <em>after</em>
having called <c>Write()</c>, you may get a runtime exception, or you may
silently get an invalid zip archive.
</para>
</remarks>
<example>
This example shows how to create a zip file, using the
<c>ZipOutputStream</c> class.
<code>
private void Zipup()
{
using (FileStream fs raw = File.Open(_outputFileName, FileMode.Create, FileAccess.ReadWrite ))
{
using (var output= new ZipOutputStream(fs))
{
output.Password = "VerySecret!";
output.Encryption = EncryptionAlgorithm.WinZipAes256;
output.PutNextEntry("entry1.txt");
byte[] buffer= System.Text.Encoding.ASCII.GetBytes("This is the content for entry #1.");
output.Write(buffer,0,buffer.Length);
output.PutNextEntry("entry2.txt"); // this will be zero length
output.PutNextEntry("entry3.txt");
buffer= System.Text.Encoding.ASCII.GetBytes("This is the content for entry #3.");
output.Write(buffer,0,buffer.Length);
}
}
}
</code>
</example>
<param name="entryName">
The name of the entry to be added, including any path to be used
within the zip file.
</param>
<returns>
The ZipEntry created.
</returns>
</member>
<member name="M:Ionic.Zip.ZipOutputStream.Dispose(System.Boolean)">
<summary>
Dispose the stream
</summary>
<remarks>
<para>
This method writes the Zip Central directory, then closes the stream. The
application must call Dispose() (or Close) in order to produce a valid zip file.
</para>
<para>
Typically the application will call <c>Dispose()</c> implicitly, via a <c>using</c>
statement in C#, or a <c>Using</c> statement in VB.
</para>
</remarks>
<param name="notCalledFromFinalizer">set this to true, always.</param>
</member>
<member name="M:Ionic.Zip.ZipOutputStream.Flush">
<summary>
This is a no-op.
</summary>
</member>
<member name="M:Ionic.Zip.ZipOutputStream.Read(System.Byte[],System.Int32,System.Int32)">
<summary>
This method always throws a NotSupportedException.
</summary>
<param name="buffer">ignored</param>
<param name="offset">ignored</param>
<param name="count">ignored</param>
<returns>nothing</returns>
</member>
<member name="M:Ionic.Zip.ZipOutputStream.Seek(System.Int64,System.IO.SeekOrigin)">
<summary>
This method always throws a NotSupportedException.
</summary>
<param name="offset">ignored</param>
<param name="origin">ignored</param>
<returns>nothing</returns>
</member>
<member name="M:Ionic.Zip.ZipOutputStream.SetLength(System.Int64)">
<summary>
This method always throws a NotSupportedException.
</summary>
<param name="value">ignored</param>
</member>
<member name="P:Ionic.Zip.ZipOutputStream.Password">
<summary>
Sets the password to be used on the <c>ZipOutputStream</c> instance.
</summary>
<remarks>
<para>
When writing a zip archive, this password is applied to the entries, not
to the zip archive itself. It applies to any <c>ZipEntry</c> subsequently
written to the <c>ZipOutputStream</c>.
</para>
<para>
Using a password does not encrypt or protect the "directory" of the
archive - the list of entries contained in the archive. If you set the
<c>Password</c> property, the password actually applies to individual
entries that are added to the archive, subsequent to the setting of this
property. The list of filenames in the archive that is eventually created
will appear in clear text, but the contents of the individual files are
encrypted. This is how Zip encryption works.
</para>
<para>
If you set this property, and then add a set of entries to the archive via
calls to <c>PutNextEntry</c>, then each entry is encrypted with that
password. You may also want to change the password between adding
different entries. If you set the password, add an entry, then set the
password to <c>null</c> (<c>Nothing</c> in VB), and add another entry, the
first entry is encrypted and the second is not.
</para>
<para>
When setting the <c>Password</c>, you may also want to explicitly set the <see cref="P:Ionic.Zip.ZipOutputStream.Encryption"/> property, to specify how to encrypt the entries added
to the ZipFile. If you set the <c>Password</c> to a non-null value and do not
set <see cref="P:Ionic.Zip.ZipOutputStream.Encryption"/>, then PKZip 2.0 ("Weak") encryption is used.
This encryption is relatively weak but is very interoperable. If
you set the password to a <c>null</c> value (<c>Nothing</c> in VB),
<c>Encryption</c> is reset to None.
</para>
<para>
Special case: if you wrap a ZipOutputStream around a non-seekable stream,
and use encryption, and emit an entry of zero bytes, the <c>Close()</c> or
<c>PutNextEntry()</c> following the entry will throw an exception.
</para>
</remarks>
</member>
<member name="P:Ionic.Zip.ZipOutputStream.Encryption">
<summary>
The Encryption to use for entries added to the <c>ZipOutputStream</c>.
</summary>
<remarks>
<para>
The specified Encryption is applied to the entries subsequently
written to the <c>ZipOutputStream</c> instance.
</para>
<para>
If you set this to something other than
EncryptionAlgorithm.None, you will also need to set the
<see cref="P:Ionic.Zip.ZipOutputStream.Password"/> to a non-null, non-empty value in
order to actually get encryption on the entry.
</para>
</remarks>
<seealso cref="P:Ionic.Zip.ZipOutputStream.Password">ZipOutputStream.Password</seealso>
<seealso cref="P:Ionic.Zip.ZipEntry.Encryption">ZipEntry.Encryption</seealso>
</member>
<member name="P:Ionic.Zip.ZipOutputStream.CodecBufferSize">
<summary>
Size of the work buffer to use for the ZLIB codec during compression.
</summary>
<remarks>
Setting this may affect performance. For larger files, setting this to a
larger size may improve performance, but I'm not sure. Sorry, I don't
currently have good recommendations on how to set it. You can test it if
you like.
</remarks>
</member>
<member name="P:Ionic.Zip.ZipOutputStream.Strategy">
<summary>
The compression strategy to use for all entries.
</summary>
<remarks>
Set the Strategy used by the ZLIB-compatible compressor, when compressing
data for the entries in the zip archive. Different compression strategies
work better on different sorts of data. The strategy parameter can affect
the compression ratio and the speed of compression but not the correctness
of the compresssion. For more information see <see cref="T:Ionic.Zlib.CompressionStrategy"/>.
</remarks>
</member>
<member name="P:Ionic.Zip.ZipOutputStream.Timestamp">
<summary>
The type of timestamp attached to the ZipEntry.
</summary>
<remarks>
Set this in order to specify the kind of timestamp that should be emitted
into the zip file for each entry.
</remarks>
</member>
<member name="P:Ionic.Zip.ZipOutputStream.CompressionLevel">
<summary>
Sets the compression level to be used for entries subsequently added to
the zip archive.
</summary>
<remarks>
<para>
Varying the compression level used on entries can affect the
size-vs-speed tradeoff when compression and decompressing data streams
or files.
</para>
<para>
As with some other properties on the <c>ZipOutputStream</c> class, like <see cref="P:Ionic.Zip.ZipOutputStream.Password"/>, and <see cref="P:Ionic.Zip.ZipOutputStream.Encryption"/>,
setting this property on a <c>ZipOutputStream</c>
instance will cause the specified <c>CompressionLevel</c> to be used on all
<see cref="T:Ionic.Zip.ZipEntry"/> items that are subsequently added to the
<c>ZipOutputStream</c> instance.
</para>
<para>
If you do not set this property, the default compression level is used,
which normally gives a good balance of compression efficiency and
compression speed. In some tests, using <c>BestCompression</c> can
double the time it takes to compress, while delivering just a small
increase in compression efficiency. This behavior will vary with the
type of data you compress. If you are in doubt, just leave this setting
alone, and accept the default.
</para>
</remarks>
</member>
<member name="P:Ionic.Zip.ZipOutputStream.Comment">
<summary>
A comment attached to the zip archive.
</summary>
<remarks>
<para>
The application sets this property to specify a comment to be embedded
into the generated zip archive.
</para>
<para>
According to <see href="http://www.pkware.com/documents/casestudies/APPNOTE.TXT">PKWARE's
zip specification</see>, the comment is not encrypted, even if there is a
password set on the zip file.
</para>
<para>
The zip specification does not describe how to encode the comment string
in a code page other than IBM437. Therefore, for "compliant" zip tools and
libraries, comments will use IBM437. However, there are situations where
you want an encoded Comment, for example using code page 950 "Big-5
Chinese". DotNetZip will encode the comment in the code page specified by
<see cref="P:Ionic.Zip.ZipOutputStream.ProvisionalAlternateEncoding"/>, at the time of the call to
<c>Close()</c> or <c>Dispose</c>.
</para>
</remarks>
</member>
<member name="P:Ionic.Zip.ZipOutputStream.EnableZip64">
<summary>
Specify whether to use ZIP64 extensions when saving a zip archive.
</summary>
<remarks>
<para>
The default value for the property is <see cref="F:Ionic.Zip.Zip64Option.Never"/>. <see cref="F:Ionic.Zip.Zip64Option.AsNecessary"/> is
safest, in the sense that you will not get an Exception if a
pre-ZIP64 limit is exceeded.
</para>
<para>
You must set this property before calling <c>Write()</c>.
</para>
</remarks>
</member>
<member name="P:Ionic.Zip.ZipOutputStream.OutputUsedZip64">
<summary>
Indicates whether ZIP64 extensions were used when saving the zip archive.
</summary>
<remarks>
The value is defined only after the <c>ZipOutputStream</c> has been closed.
</remarks>
</member>
<member name="P:Ionic.Zip.ZipOutputStream.IgnoreCase">
<summary>
Whether the ZipOutputStream should use case-insensitive comparisons when
checking for uniqueness of zip entries.
</summary>
<remarks>
<para>
Though the zip specification doesn't prohibit zipfiles with duplicate
entries, Sane zip files have no duplicates, and the DotNetZip library
cannot create zip files with duplicate entries. If an application attempts
to call <see cref="M:Ionic.Zip.ZipOutputStream.PutNextEntry(System.String)"/> with a name that duplicates one
already used within the archive, the library will throw an Exception.
</para>
<para>
This property allows the application to specify whether the
ZipOutputStream instance considers ordinal case when checking for
uniqueness of zip entries.
</para>
</remarks>
</member>
<member name="P:Ionic.Zip.ZipOutputStream.UseUnicodeAsNecessary">
<summary>
Indicates whether to encode entry filenames and entry comments using
Unicode (UTF-8).
</summary>
<remarks>
<para>
<see href="http://www.pkware.com/documents/casestudies/APPNOTE.TXT">The
PKWare zip specification</see> provides for encoding file names and file
comments in either the IBM437 code page, or in UTF-8. This flag selects
the encoding according to that specification. By default, this flag is
false, and filenames and comments are encoded into the zip file in the
IBM437 codepage. Setting this flag to true will specify that filenames
and comments that cannot be encoded with IBM437 will be encoded with
UTF-8.
</para>
<para>
Zip files created with strict adherence to the PKWare specification with
respect to UTF-8 encoding can contain entries with filenames containing
any combination of Unicode characters, including the full range of
characters from Chinese, Latin, Hebrew, Greek, Cyrillic, and many other
alphabets. However, because at this time, the UTF-8 portion of the PKWare
specification is not broadly supported by other zip libraries and
utilities, such zip files may not be readable by your favorite zip tool or
archiver. In other words, interoperability will decrease if you set this
flag to true.
</para>
<para>
In particular, Zip files created with strict adherence to the PKWare
specification with respect to UTF-8 encoding will not work well with
Explorer in Windows XP or Windows Vista, because Windows compressed
folders, as far as I know, do not support UTF-8 in zip files. Vista can
read the zip files, but shows the filenames incorrectly. Unpacking from
Windows Vista Explorer will result in filenames that have rubbish
characters in place of the high-order UTF-8 bytes.
</para>
<para>
Also, zip files that use UTF-8 encoding will not work well with Java
applications that use the java.util.zip classes, as of v5.0 of the Java
runtime. The Java runtime does not correctly implement the PKWare
specification in this regard.
</para>
<para>
As a result, we have the unfortunate situation that "correct" behavior by
the DotNetZip library with regard to Unicode encoding of filenames during
zip creation will result in zip files that are readable by strictly
compliant and current tools (for example the most recent release of the
commercial WinZip tool); but these zip files will not be readable by
various other tools or libraries, including Windows Explorer.
</para>
<para>
The DotNetZip library can read and write zip files with UTF8-encoded
entries, according to the PKware spec. If you use DotNetZip for both
creating and reading the zip file, and you use UTF-8, there will be no
loss of information in the filenames. For example, using a self-extractor
created by this library will allow you to unpack files correctly with no
loss of information in the filenames.
</para>
<para>
If you do not set this flag, it will remain false. If this flag is false,
the <c>ZipOutputStream</c> will encode all filenames and comments using
the IBM437 codepage. This can cause "loss of information" on some
filenames, but the resulting zipfile will be more interoperable with other
utilities. As an example of the loss of information, diacritics can be
lost. The o-tilde character will be down-coded to plain o. The c with a
cedilla (Unicode 0xE7) used in Portugese will be downcoded to a c.
Likewise, the O-stroke character (Unicode 248), used in Danish and
Norwegian, will be down-coded to plain o. Chinese characters cannot be
represented in codepage IBM437; when using the default encoding, Chinese
characters in filenames will be represented as ?. These are all examples
of "information loss".
</para>
<para>
The loss of information associated to the use of the IBM437 encoding is
inconvenient, and can also lead to runtime errors. For example, using
IBM437, any sequence of 4 Chinese characters will be encoded as ????. If
your application creates a <c>ZipOutputStream</c>, does not set the
encoding, then adds two files, each with names of four Chinese characters
each, this will result in a duplicate filename exception. In the case
where you add a single file with a name containing four Chinese
characters, the zipfile will save properly, but extracting that file
later, with any zip tool, will result in an error, because the question
mark is not legal for use within filenames on Windows. These are just a
few examples of the problems associated to loss of information.
</para>
<para>
This flag is independent of the encoding of the content within the entries
in the zip file. Think of the zip file as a container - it supports an
encoding. Within the container are other "containers" - the file entries
themselves. The encoding within those entries is independent of the
encoding of the zip archive container for those entries.
</para>
<para>
Rather than specify the encoding in a binary fashion using this flag, an
application can specify an arbitrary encoding via the <see cref="P:Ionic.Zip.ZipOutputStream.ProvisionalAlternateEncoding"/> property. Setting the encoding
explicitly when creating zip archives will result in non-compliant zip
files that, curiously, are fairly interoperable. The challenge is, the
PKWare specification does not provide for a way to specify that an entry
in a zip archive uses a code page that is neither IBM437 nor UTF-8.
Therefore if you set the encoding explicitly when creating a zip archive,
you must take care upon reading the zip archive to use the same code page.
If you get it wrong, the behavior is undefined and may result in incorrect
filenames, exceptions, stomach upset, hair loss, and acne.
</para>
</remarks>
<seealso cref="P:Ionic.Zip.ZipOutputStream.ProvisionalAlternateEncoding"/>
</member>
<member name="P:Ionic.Zip.ZipOutputStream.ProvisionalAlternateEncoding">
<summary>
The text encoding to use when emitting entries into the zip archive, for
those entries whose filenames or comments cannot be encoded with the
default (IBM437) encoding.
</summary>
<remarks>
<para>
In <see href="http://www.pkware.com/documents/casestudies/APPNOTE.TXT">its
zip specification</see>, PKWare describes two options for encoding
filenames and comments: using IBM437 or UTF-8. But, some archiving tools
or libraries do not follow the specification, and instead encode
characters using the system default code page. For example, WinRAR when
run on a machine in Shanghai may encode filenames with the Big-5 Chinese
(950) code page. This behavior is contrary to the Zip specification, but
it occurs anyway.
</para>
<para>
When using DotNetZip to write zip archives that will be read by one of
these other archivers, set this property to specify the code page to use
when encoding the <see cref="P:Ionic.Zip.ZipEntry.FileName"/> and <see cref="P:Ionic.Zip.ZipEntry.Comment"/> for each <c>ZipEntry</c> in the zip file, for
values that cannot be encoded with the default codepage for zip files,
IBM437. This is why this property is "provisional". In all cases, IBM437
is used where possible, in other words, where no loss of data would
result. It is possible, therefore, to have a given entry with a
<c>Comment</c> encoded in IBM437 and a <c>FileName</c> encoded with the
specified "provisional" codepage.
</para>
<para>
Be aware that a zip file created after you've explicitly set the
<c>ProvisionalAlternateEncoding</c> property to a value other than
IBM437 may not be compliant to the PKWare specification, and may not be
readable by compliant archivers. On the other hand, many (most?)
archivers are non-compliant and can read zip files created in arbitrary
code pages. The trick is to use or specify the proper codepage when
reading the zip.
</para>
<para>
When creating a zip archive using this library, it is possible to change
the value of <c>ProvisionalAlternateEncoding</c> between each
entry you add, and between adding entries and the call to
<c>Close()</c>. Don't do this. It will likely result in a zipfile that is
not readable. For best interoperability, either leave
<c>ProvisionalAlternateEncoding</c> alone, or specify it only once,
before adding any entries to the <c>ZipOutputStream</c> instance. There is one
exception to this recommendation, described later.
</para>
<para>
When using an arbitrary, non-UTF8 code page for encoding, there is no
standard way for the creator application - whether DotNetZip, WinZip,
WinRar, or something else - to formally specify in the zip file which
codepage has been used for the entries. As a result, readers of zip files
are not able to inspect the zip file and determine the codepage that was
used for the entries contained within it. It is left to the application
or user to determine the necessary codepage when reading zip files encoded
this way. If you use an incorrect codepage when reading a zipfile, you
will get entries with filenames that are incorrect, and the incorrect
filenames may even contain characters that are not legal for use within
filenames in Windows. Extracting entries with illegal characters in the
filenames will lead to exceptions. It's too bad, but this is just the way
things are with code pages in zip files. Caveat Emptor.
</para>
<para>
One possible approach for specifying the code page for a given zip file is
to describe the code page in a human-readable form in the Zip comment. For
example, the comment may read "Entries in this archive are encoded in the
Big5 code page". For maximum interoperability, the zip comment in this
case should be encoded in the default, IBM437 code page. In this case,
the zip comment is encoded using a different page than the filenames. To
do this, Specify <c>ProvisionalAlternateEncoding</c> to your desired
region-specific code page, once before adding any entries, and then set
the <see cref="P:Ionic.Zip.ZipOutputStream.Comment"/> property and reset
<c>ProvisionalAlternateEncoding</c> to IBM437 before calling <c>Close()</c>.
</para>
</remarks>
</member>
<member name="P:Ionic.Zip.ZipOutputStream.ParallelDeflateThreshold">
<summary>
The size threshold for an entry, above which a parallel deflate is used.
</summary>
<remarks>
<para>
DotNetZip will use multiple threads to compress any ZipEntry,
if the entry is larger than the given size. Zero means "always
use parallel deflate", while -1 means "never use parallel
deflate".
</para>
<para>
If the entry size cannot be known before compression, as with any entry
added via a ZipOutputStream, then Parallel deflate will never be
performed, unless the value of this property is zero.
</para>
<para>
A parallel deflate operations will speed up the compression of
large files, on computers with multiple CPUs or multiple CPU
cores. For files above 1mb, on a dual core or dual-cpu (2p)
machine, the time required to compress the file can be 70% of the
single-threaded deflate. For very large files on 4p machines the
compression can be done in 30% of the normal time. The downside
is that parallel deflate consumes extra memory during the deflate,
and the deflation is slightly less effective.
</para>
<para>
Parallel deflate tends to not be as effective as single-threaded deflate
because the original data stream is split into multiple independent
buffers, each of which is compressed in parallel. But because they are
treated independently, there is no opportunity to share compression
dictionaries, and additional framing bytes must be added to the output
stream. For that reason, a deflated stream may be slightly larger when
compressed using parallel deflate, as compared to a traditional
single-threaded deflate. For files of about 512k, the increase over the
normal deflate is as much as 5% of the total compressed size. For larger
files, the difference can be as small as 0.1%.
</para>
<para>
Multi-threaded compression does not give as much an advantage when using
Encryption. This is primarily because encryption tends to slow down
the entire pipeline. Also, multi-threaded compression gives less of an
advantage when using lower compression levels, for example <see cref="F:Ionic.Zlib.CompressionLevel.BestSpeed"/>. You may have to perform
some tests to determine the best approach for your situation.
</para>
<para>
The default value for this property is -1, which means parallel
compression will not be performed unless you set it to zero.
</para>
</remarks>
</member>
<member name="P:Ionic.Zip.ZipOutputStream.CanRead">
<summary>
Always returns false.
</summary>
</member>
<member name="P:Ionic.Zip.ZipOutputStream.CanSeek">
<summary>
Always returns false.
</summary>
</member>
<member name="P:Ionic.Zip.ZipOutputStream.CanWrite">
<summary>
Always returns true.
</summary>
</member>
<member name="P:Ionic.Zip.ZipOutputStream.Length">
<summary>
Always returns a NotSupportedException.
</summary>
</member>
<member name="P:Ionic.Zip.ZipOutputStream.Position">
<summary>
Setting this property always returns a NotSupportedException. Getting it
returns the value of the Position on the underlying stream.
</summary>
</member>
<member name="T:Ionic.Zip.BadPasswordException">
<summary>
Issued when an <c>ZipEntry.ExtractWithPassword()</c> method is invoked
with an incorrect password.
</summary>
</member>
<member name="T:Ionic.Zip.ZipException">
<summary>
Base class for all exceptions defined by and throw by the Zip library.
</summary>
</member>
<member name="M:Ionic.Zip.ZipException.#ctor">
<summary>
Default ctor.
</summary>
</member>
<member name="M:Ionic.Zip.ZipException.#ctor(System.String)">
<summary>
Come on, you know how exceptions work. Why are you looking at this documentation?
</summary>
<param name="message">The message in the exception.</param>
</member>
<member name="M:Ionic.Zip.ZipException.#ctor(System.String,System.Exception)">
<summary>
Come on, you know how exceptions work. Why are you looking at this documentation?
</summary>
<param name="message">The message in the exception.</param>
<param name="innerException">The innerException for this exception.</param>
</member>
<member name="M:Ionic.Zip.ZipException.#ctor(System.Runtime.Serialization.SerializationInfo,System.Runtime.Serialization.StreamingContext)">
<summary>
Come on, you know how exceptions work. Why are you looking at this documentation?
</summary>
<param name="info">The serialization info for the exception.</param>
<param name="context">The streaming context from which to deserialize.</param>
</member>
<member name="M:Ionic.Zip.BadPasswordException.#ctor">
<summary>
Default ctor.
</summary>
</member>
<member name="M:Ionic.Zip.BadPasswordException.#ctor(System.String)">
<summary>
Come on, you know how exceptions work. Why are you looking at this documentation?
</summary>
<param name="message">The message in the exception.</param>
</member>
<member name="M:Ionic.Zip.BadPasswordException.#ctor(System.String,System.Exception)">
<summary>
Come on, you know how exceptions work. Why are you looking at this documentation?
</summary>
<param name="message">The message in the exception.</param>
<param name="innerException">The innerException for this exception.</param>
</member>
<member name="M:Ionic.Zip.BadPasswordException.#ctor(System.Runtime.Serialization.SerializationInfo,System.Runtime.Serialization.StreamingContext)">
<summary>
Come on, you know how exceptions work. Why are you looking at this documentation?
</summary>
<param name="info">The serialization info for the exception.</param>
<param name="context">The streaming context from which to deserialize.</param>
</member>
<member name="T:Ionic.Zip.BadReadException">
<summary>
Indicates that a read was attempted on a stream, and bad or incomplete data was
received.
</summary>
</member>
<member name="M:Ionic.Zip.BadReadException.#ctor">
<summary>
Default ctor.
</summary>
</member>
<member name="M:Ionic.Zip.BadReadException.#ctor(System.String)">
<summary>
Come on, you know how exceptions work. Why are you looking at this documentation?
</summary>
<param name="message">The message in the exception.</param>
</member>
<member name="M:Ionic.Zip.BadReadException.#ctor(System.String,System.Exception)">
<summary>
Come on, you know how exceptions work. Why are you looking at this documentation?
</summary>
<param name="message">The message in the exception.</param>
<param name="innerException">The innerException for this exception.</param>
</member>
<member name="M:Ionic.Zip.BadReadException.#ctor(System.Runtime.Serialization.SerializationInfo,System.Runtime.Serialization.StreamingContext)">
<summary>
Come on, you know how exceptions work. Why are you looking at this documentation?
</summary>
<param name="info">The serialization info for the exception.</param>
<param name="context">The streaming context from which to deserialize.</param>
</member>
<member name="T:Ionic.Zip.BadCrcException">
<summary>
Issued when an CRC check fails upon extracting an entry from a zip archive.
</summary>
</member>
<member name="M:Ionic.Zip.BadCrcException.#ctor">
<summary>
Default ctor.
</summary>
</member>
<member name="M:Ionic.Zip.BadCrcException.#ctor(System.String)">
<summary>
Come on, you know how exceptions work. Why are you looking at this documentation?
</summary>
<param name="message">The message in the exception.</param>
</member>
<member name="M:Ionic.Zip.BadCrcException.#ctor(System.Runtime.Serialization.SerializationInfo,System.Runtime.Serialization.StreamingContext)">
<summary>
Come on, you know how exceptions work. Why are you looking at this documentation?
</summary>
<param name="info">The serialization info for the exception.</param>
<param name="context">The streaming context from which to deserialize.</param>
</member>
<member name="T:Ionic.Zip.SfxGenerationException">
<summary>
Issued when errors occur saving a self-extracting archive.
</summary>
</member>
<member name="M:Ionic.Zip.SfxGenerationException.#ctor">
<summary>
Default ctor.
</summary>
</member>
<member name="M:Ionic.Zip.SfxGenerationException.#ctor(System.String)">
<summary>
Come on, you know how exceptions work. Why are you looking at this documentation?
</summary>
<param name="message">The message in the exception.</param>
</member>
<member name="M:Ionic.Zip.SfxGenerationException.#ctor(System.Runtime.Serialization.SerializationInfo,System.Runtime.Serialization.StreamingContext)">
<summary>
Come on, you know how exceptions work. Why are you looking at this documentation?
</summary>
<param name="info">The serialization info for the exception.</param>
<param name="context">The streaming context from which to deserialize.</param>
</member>
<member name="T:Ionic.Zip.BadStateException">
<summary>
Indicates that an operation was attempted on a ZipFile which was not possible
given the state of the instance. For example, if you call <c>Save()</c> on a ZipFile
which has no filename set, you can get this exception.
</summary>
</member>
<member name="M:Ionic.Zip.BadStateException.#ctor">
<summary>
Default ctor.
</summary>
</member>
<member name="M:Ionic.Zip.BadStateException.#ctor(System.String)">
<summary>
Come on, you know how exceptions work. Why are you looking at this documentation?
</summary>
<param name="message">The message in the exception.</param>
</member>
<member name="M:Ionic.Zip.BadStateException.#ctor(System.String,System.Exception)">
<summary>
Come on, you know how exceptions work. Why are you looking at this documentation?
</summary>
<param name="message">The message in the exception.</param>
<param name="innerException">The innerException for this exception.</param>
</member>
<member name="M:Ionic.Zip.BadStateException.#ctor(System.Runtime.Serialization.SerializationInfo,System.Runtime.Serialization.StreamingContext)">
<summary>
Come on, you know how exceptions work. Why are you looking at this documentation?
</summary>
<param name="info">The serialization info for the exception.</param>
<param name="context">The streaming context from which to deserialize.</param>
</member>
<member name="T:Ionic.Zip.ZipEntry">
<summary>
Represents a single entry in a ZipFile. Typically, applications get a ZipEntry
by enumerating the entries within a ZipFile, or by adding an entry to a ZipFile.
</summary>
</member>
<member name="M:Ionic.Zip.ZipEntry.#ctor">
<summary>
Default constructor.
</summary>
<remarks>
Applications should never need to call this directly. It is exposed to
support COM Automation environments.
</remarks>
</member>
<member name="M:Ionic.Zip.ZipEntry.SetEntryTimes(System.DateTime,System.DateTime,System.DateTime)">
<summary>
Sets the NTFS Creation, Access, and Modified times for the given entry.
</summary>
<remarks>
<para>
When adding an entry from a file or directory, the Creation, Access, and
Modified times for the given entry are automatically set from the
filesystem values. When adding an entry from a stream or string, the
values are implicitly set to DateTime.Now. The application may wish to
set these values to some arbitrary value, before saving the archive, and
can do so using the various setters. If you want to set all of the times,
this method is more efficient.
</para>
<para>
The values you set here will be retrievable with the <see cref="P:Ionic.Zip.ZipEntry.ModifiedTime"/>, <see cref="P:Ionic.Zip.ZipEntry.CreationTime"/> and <see cref="P:Ionic.Zip.ZipEntry.AccessedTime"/> properties.
</para>
<para>
When this method is called, if both <see cref="P:Ionic.Zip.ZipEntry.EmitTimesInWindowsFormatWhenSaving"/> and <see cref="P:Ionic.Zip.ZipEntry.EmitTimesInUnixFormatWhenSaving"/> are false, then the
<c>EmitTimesInWindowsFormatWhenSaving</c> flag is automatically set.
</para>
<para>
DateTime values provided here without a DateTimeKind are assumed to be Local Time.
</para>
</remarks>
<param name="created">the creation time of the entry.</param>
<param name="accessed">the last access time of the entry.</param>
<param name="modified">the last modified time of the entry.</param>
<seealso cref="P:Ionic.Zip.ZipEntry.EmitTimesInWindowsFormatWhenSaving"/>
<seealso cref="P:Ionic.Zip.ZipEntry.EmitTimesInUnixFormatWhenSaving"/>
<seealso cref="P:Ionic.Zip.ZipEntry.AccessedTime"/>
<seealso cref="P:Ionic.Zip.ZipEntry.CreationTime"/>
<seealso cref="P:Ionic.Zip.ZipEntry.ModifiedTime"/>
</member>
<member name="M:Ionic.Zip.ZipEntry.ToString">
<summary>Provides a string representation of the instance.</summary>
<returns>a string representation of the instance.</returns>
</member>
<member name="M:Ionic.Zip.ZipEntry.ReadDirEntry(Ionic.Zip.ZipFile)">
<summary>
Reads one entry from the zip directory structure in the zip file.
</summary>
<param name="zf">
The zipfile for which a directory entry will be read. From this param, the
method gets the ReadStream and the expected text encoding
(ProvisionalAlternateEncoding) which is used if the entry is not marked
UTF-8.
</param>
<returns>the entry read from the archive.</returns>
</member>
<member name="M:Ionic.Zip.ZipEntry.IsNotValidZipDirEntrySig(System.Int32)">
<summary>
Returns true if the passed-in value is a valid signature for a ZipDirEntry.
</summary>
<param name="signature">the candidate 4-byte signature value.</param>
<returns>true, if the signature is valid according to the PKWare spec.</returns>
</member>
<member name="M:Ionic.Zip.ZipEntry.PrepSourceStream">
<summary>
Stores the position of the entry source stream, or, if the position is
already stored, seeks to that position.
</summary>
<remarks>
<para>
This method is called in prep for reading the source stream. If PKZIP
encryption is used, then we need to calc the CRC32 before doing the
encryption, because the CRC is used in the 12th byte of the PKZIP
encryption header. So, we need to be able to seek backward in the source
when saving the ZipEntry. This method is called from the place that
calculates the CRC, and also from the method that does the encryption of
the file data.
</para>
<para>
The first time through, this method sets the _sourceStreamOriginalPosition
field. Subsequent calls to this method seek to that position.
</para>
</remarks>
</member>
<member name="M:Ionic.Zip.ZipEntry.CopyMetaData(Ionic.Zip.ZipEntry)">
<summary>
Copy metadata that may have been changed by the app. We do this when
resetting the zipFile instance. If the app calls Save() on a ZipFile, then
tries to party on that file some more, we may need to Reset() it , which
means re-reading the entries and then copying the metadata. I think.
</summary>
</member>
<member name="M:Ionic.Zip.ZipEntry.SetInputAndFigureFileLength(System.IO.Stream@)">
<summary>
Set the input stream and get its length, if possible. The
length is used for progress updates, AND, to allow an
optimization in case of a stream/file of zero length. In
that case we skip the Encrypt and DeflateStream.
</summary>
</member>
<member name="M:Ionic.Zip.ZipEntry.Extract">
<summary>
Extract the entry to the filesystem, starting at the current working directory.
</summary>
<overloads>
This method has a bunch of overloads! One of them is sure to be
the right one for you... If you don't like these, check out the
<c>ExtractWithPassword()</c> methods.
</overloads>
<seealso cref="P:Ionic.Zip.ZipEntry.ExtractExistingFile"/>
<seealso cref="M:Ionic.Zip.ZipEntry.Extract(Ionic.Zip.ExtractExistingFileAction)"/>
<remarks>
<para> This method extracts an entry from a zip file into the current working
directory. The path of the entry as extracted is the full path as specified in
the zip archive, relative to the current working directory. After the file is
extracted successfully, the file attributes and timestamps are set. </para>
<para>
The action taken when extraction an entry would overwrite an existing file
is determined by the <see cref="P:Ionic.Zip.ZipEntry.ExtractExistingFile"/> property.
</para>
<para>
See the remarks the <see cref="P:Ionic.Zip.ZipEntry.LastModified"/> property, for some details
about how the last modified time of the file is set after extraction.
</para>
</remarks>
</member>
<member name="M:Ionic.Zip.ZipEntry.Extract(Ionic.Zip.ExtractExistingFileAction)">
<summary>
Extract the entry to a file in the filesystem, using the specified behavior
when extraction would overwrite an existing file.
</summary>
<remarks>
<para>
See the remarks on the <see cref="P:Ionic.Zip.ZipEntry.LastModified"/> property, for some details
about how the last modified time of the file is set after extraction.
</para>
</remarks>
<param name="extractExistingFile">The action to take if extraction would
overwrite an existing file.</param>
</member>
<member name="M:Ionic.Zip.ZipEntry.Extract(System.IO.Stream)">
<summary>
Extracts the entry to the specified stream.
</summary>
<remarks>
<para>
The caller can specify any write-able stream, for example <see cref="M:System.Console.OpenStandardOutput"/>, a <see cref="T:System.IO.FileStream"/>, a <see cref="T:System.IO.MemoryStream"/>, or
ASP.NET's <c>Response.OutputStream</c>.
The content will be decrypted and decompressed as necessary. If the entry is
encrypted and no password is provided, this method will throw.
</para>
</remarks>
<param name="stream">the stream to which the entry should be extracted. </param>
</member>
<member name="M:Ionic.Zip.ZipEntry.Extract(System.String)">
<summary>
Extract the entry to the filesystem, starting at the specified base directory.
</summary>
<param name="baseDirectory">the pathname of the base directory</param>
<seealso cref="P:Ionic.Zip.ZipEntry.ExtractExistingFile"/>
<seealso cref="M:Ionic.Zip.ZipEntry.Extract(System.String,Ionic.Zip.ExtractExistingFileAction)"/>
<example>
This example extracts only the entries in a zip file that are .txt files,
into a directory called "textfiles".
<code lang="C#">
using (ZipFile zip = ZipFile.Read("PackedDocuments.zip"))
{
foreach (string s1 in zip.EntryFilenames)
{
if (s1.EndsWith(".txt"))
{
zip[s1].Extract("textfiles");
}
}
}
</code>
<code lang="VB">
Using zip As ZipFile = ZipFile.Read("PackedDocuments.zip")
Dim s1 As String
For Each s1 In zip.EntryFilenames
If s1.EndsWith(".txt") Then
zip(s1).Extract("textfiles")
End If
Next
End Using
</code>
</example>
<remarks>
<para> Using this method, existing entries in the filesystem will not be
overwritten. If you would like to force the overwrite of existing files, see the
<see cref="P:Ionic.Zip.ZipEntry.ExtractExistingFile"/> property, or call <see cref="M:Ionic.Zip.ZipEntry.Extract(System.String,Ionic.Zip.ExtractExistingFileAction)"/>. </para>
<para>
See the remarks on the <see cref="P:Ionic.Zip.ZipEntry.LastModified"/> property, for some details
about how the last modified time of the created file is set.
</para>
</remarks>
</member>
<member name="M:Ionic.Zip.ZipEntry.Extract(System.String,Ionic.Zip.ExtractExistingFileAction)">
<summary>
Extract the entry to the filesystem, starting at the specified base directory, and
using the specified behavior when extraction would overwrite an existing file.
</summary>
<remarks>
<para>
See the remarks on the <see cref="P:Ionic.Zip.ZipEntry.LastModified"/> property, for some details
about how the last modified time of the created file is set.
</para>
</remarks>
<example>
<code lang="C#">
String sZipPath = "Airborne.zip";
String sFilePath = "Readme.txt";
String sRootFolder = "Digado";
using (ZipFile zip = ZipFile.Read(sZipPath))
{
if (zip.EntryFileNames.Contains(sFilePath))
{
// use the string indexer on the zip file
zip[sFileName].Extract(sRootFolder,
ExtractExistingFileAction.OverwriteSilently);
}
}
</code>
<code lang="VB">
Dim sZipPath as String = "Airborne.zip"
Dim sFilePath As String = "Readme.txt"
Dim sRootFolder As String = "Digado"
Using zip As ZipFile = ZipFile.Read(sZipPath)
If zip.EntryFileNames.Contains(sFilePath)
' use the string indexer on the zip file
zip(sFilePath).Extract(sRootFolder, _
ExtractExistingFileAction.OverwriteSilently)
End If
End Using
</code>
</example>
<param name="baseDirectory">the pathname of the base directory</param>
<param name="extractExistingFile">
The action to take if extraction would overwrite an existing file.
</param>
</member>
<member name="M:Ionic.Zip.ZipEntry.ExtractWithPassword(System.String)">
<summary>
Extract the entry to the filesystem, using the current working directory
and the specified password.
</summary>
<overloads>
This method has a bunch of overloads! One of them is sure to be
the right one for you...
</overloads>
<seealso cref="P:Ionic.Zip.ZipEntry.ExtractExistingFile"/>
<seealso cref="M:Ionic.Zip.ZipEntry.ExtractWithPassword(Ionic.Zip.ExtractExistingFileAction,System.String)"/>
<remarks>
<para> Existing entries in the filesystem will not be overwritten. If you would
like to force the overwrite of existing files, see the <see cref="P:Ionic.Zip.ZipEntry.ExtractExistingFile"/>property, or call <see cref="M:Ionic.Zip.ZipEntry.ExtractWithPassword(Ionic.Zip.ExtractExistingFileAction,System.String)"/>.</para>
<para>
See the remarks on the <see cref="P:Ionic.Zip.ZipEntry.LastModified"/> property for some details
about how the "last modified" time of the created file is set.
</para>
</remarks>
<example>
In this example, entries that use encryption are extracted using a particular password.
<code>
using (var zip = ZipFile.Read(FilePath))
{
foreach (ZipEntry e in zip)
{
if (e.UsesEncryption)
e.ExtractWithPassword("Secret!");
else
e.Extract();
}
}
</code>
<code lang="VB">
Using zip As ZipFile = ZipFile.Read(FilePath)
Dim e As ZipEntry
For Each e In zip
If (e.UsesEncryption)
e.ExtractWithPassword("Secret!")
Else
e.Extract
End If
Next
End Using
</code>
</example>
<param name="password">The Password to use for decrypting the entry.</param>
</member>
<member name="M:Ionic.Zip.ZipEntry.ExtractWithPassword(System.String,System.String)">
<summary>
Extract the entry to the filesystem, starting at the specified base directory,
and using the specified password.
</summary>
<seealso cref="P:Ionic.Zip.ZipEntry.ExtractExistingFile"/>
<seealso cref="M:Ionic.Zip.ZipEntry.ExtractWithPassword(System.String,Ionic.Zip.ExtractExistingFileAction,System.String)"/>
<remarks>
<para> Existing entries in the filesystem will not be overwritten. If you would
like to force the overwrite of existing files, see the <see cref="P:Ionic.Zip.ZipEntry.ExtractExistingFile"/>property, or call <see cref="M:Ionic.Zip.ZipEntry.ExtractWithPassword(Ionic.Zip.ExtractExistingFileAction,System.String)"/>.</para>
<para>
See the remarks on the <see cref="P:Ionic.Zip.ZipEntry.LastModified"/> property, for some details
about how the last modified time of the created file is set.
</para>
</remarks>
<param name="baseDirectory">The pathname of the base directory.</param>
<param name="password">The Password to use for decrypting the entry.</param>
</member>
<member name="M:Ionic.Zip.ZipEntry.ExtractWithPassword(Ionic.Zip.ExtractExistingFileAction,System.String)">
<summary>
Extract the entry to a file in the filesystem, relative to the current directory,
using the specified behavior when extraction would overwrite an existing file.
</summary>
<remarks>
<para>
See the remarks on the <see cref="P:Ionic.Zip.ZipEntry.LastModified"/> property, for some details
about how the last modified time of the created file is set.
</para>
</remarks>
<param name="password">The Password to use for decrypting the entry.</param>
<param name="extractExistingFile">
The action to take if extraction would overwrite an existing file.
</param>
</member>
<member name="M:Ionic.Zip.ZipEntry.ExtractWithPassword(System.String,Ionic.Zip.ExtractExistingFileAction,System.String)">
<summary>
Extract the entry to the filesystem, starting at the specified base directory, and
using the specified behavior when extraction would overwrite an existing file.
</summary>
<remarks>
See the remarks on the <see cref="P:Ionic.Zip.ZipEntry.LastModified"/> property, for some details
about how the last modified time of the created file is set.
</remarks>
<param name="baseDirectory">the pathname of the base directory</param>
<param name="extractExistingFile">The action to take if extraction would
overwrite an existing file.</param>
<param name="password">The Password to use for decrypting the entry.</param>
</member>
<member name="M:Ionic.Zip.ZipEntry.ExtractWithPassword(System.IO.Stream,System.String)">
<summary>
Extracts the entry to the specified stream, using the specified Password.
For example, the caller could extract to Console.Out, or to a MemoryStream.
</summary>
<remarks>
See the remarks on the <see cref="P:Ionic.Zip.ZipEntry.LastModified"/> property, for some details
about how the last modified time of the created file is set.
</remarks>
<param name="stream">the stream to which the entry should be extracted. </param>
<param name="password">The password to use for decrypting the entry.</param>
</member>
<member name="M:Ionic.Zip.ZipEntry.OpenReader">
<summary>
Opens the backing stream for the zip entry in the archive, for reading.
</summary>
<remarks>
<para>
DotNetZip offers a variety of ways to extract entries from a zip file. This
method allows an application to extract and entry by reading a Stream.
</para>
<para>
The return value is a <see cref="T:Ionic.Zlib.CrcCalculatorStream"/>. Use it
as you would any stream for reading. The data you get by calling <see cref="M:System.IO.Stream.Read(System.Byte[],System.Int32,System.Int32)"/> on that stream will be decrypted and
decompressed.
</para>
<para>
CrcCalculatorStream adds one additional feature: it keeps a CRC32 checksum
on the bytes of the stream as it is read. The CRC value is available in the
<see cref="P:Ionic.Zlib.CrcCalculatorStream.Crc"/> property on the
<c>CrcCalculatorStream</c>. When the read is complete, this CRC
<em>should</em> be checked against the <see cref="P:Ionic.Zip.ZipEntry.Crc"/> property
on the <c>ZipEntry</c> to validate the content of the ZipEntry. You don't
have to validate the entry using the CRC, but you should. Check the example
for how to do this.
</para>
<para>
If the entry is protected with a password, then you need to provide a
password prior to calling <see cref="M:Ionic.Zip.ZipEntry.OpenReader"/>, either by setting the
<see cref="P:Ionic.Zip.ZipEntry.Password"/> property on the entry, or the <see cref="P:Ionic.Zip.ZipFile.Password"/> property on the <c>ZipFile</c> itself. Or, you can
use <see cref="M:Ionic.Zip.ZipEntry.OpenReader(System.String)"/>, the overload of OpenReader that
accepts a password parameter.
</para>
<para>
If you want to extract entry data into a stream that is already opened, like
a <see cref="T:System.IO.FileStream"/>, consider the <see cref="M:Ionic.Zip.ZipEntry.Extract(System.IO.Stream)"/> method.
</para>
</remarks>
<example>
This example shows how to open a zip archive, then read in a named entry via
a stream. After the read loop is complete, the code compares the calculated
during the read loop with the expected CRC on the <c>ZipEntry</c>, to verify
the extraction.
<code>
using (ZipFile zip = new ZipFile(ZipFileToRead))
{
ZipEntry e1= zip["Elevation.mp3"];
using (Ionic.Zlib.CrcCalculatorStream s = e1.OpenReader())
{
byte[] buffer = new byte[4096];
int n, totalBytesRead= 0;
do {
n = s.Read(buffer,0, buffer.Length);
totalBytesRead+=n;
} while (n&gt;0);
if (s.Crc32 != e1.Crc32)
throw new Exception(string.Format("The Zip Entry failed the CRC Check. (0x{0:X8}!=0x{1:X8})", s.Crc32, e1.Crc32));
if (totalBytesRead != e1.UncompressedSize)
throw new Exception(string.Format("We read an unexpected number of bytes. ({0}!={1})", totalBytesRead, e1.UncompressedSize));
}
}
</code>
<code lang="VB">
Using zip As New ZipFile(ZipFileToRead)
Dim e1 As ZipEntry = zip.Item("Elevation.mp3")
Using s As Ionic.Zlib.CrcCalculatorStream = e1.OpenReader
Dim n As Integer
Dim buffer As Byte() = New Byte(4096) {}
Dim totalBytesRead As Integer = 0
Do
n = s.Read(buffer, 0, buffer.Length)
totalBytesRead = (totalBytesRead + n)
Loop While (n &gt; 0)
If (s.Crc32 &lt;&gt; e1.Crc32) Then
Throw New Exception(String.Format("The Zip Entry failed the CRC Check. (0x{0:X8}!=0x{1:X8})", s.Crc32, e1.Crc32))
End If
If (totalBytesRead &lt;&gt; e1.UncompressedSize) Then
Throw New Exception(String.Format("We read an unexpected number of bytes. ({0}!={1})", totalBytesRead, e1.UncompressedSize))
End If
End Using
End Using
</code>
</example>
<seealso cref="M:Ionic.Zip.ZipEntry.Extract(System.IO.Stream)"/>
<returns>The Stream for reading.</returns>
</member>
<member name="M:Ionic.Zip.ZipEntry.OpenReader(System.String)">
<summary>
Opens the backing stream for an encrypted zip entry in the archive, for reading.
</summary>
<remarks>
<para>
See the documentation on the <see cref="M:Ionic.Zip.ZipEntry.OpenReader"/> method for full
details. This overload allows the application to specify a password for the
<c>ZipEntry</c> to be read.
</para>
</remarks>
<param name="password">The password to use for decrypting the entry.</param>
<returns>The Stream for reading.</returns>
</member>
<member name="M:Ionic.Zip.ZipEntry.ValidateOutput(System.String,System.IO.Stream,System.String@)">
<summary>
Validates that the args are consistent.
</summary>
<remarks>
Only one of {baseDir, outStream} can be non-null.
If baseDir is non-null, then the outputFile is created.
</remarks>
</member>
<member name="M:Ionic.Zip.ZipEntry.ReadEntry(Ionic.Zip.ZipContainer,System.Boolean)">
<summary>
Reads one <c>ZipEntry</c> from the given stream. If the entry is encrypted, we don't
decrypt at this point. We also do not decompress. Mostly we read metadata.
</summary>
<param name="zc">the ZipContainer this entry belongs to.</param>
<param name="first">true of this is the first entry being read from the stream.</param>
<returns>the <c>ZipEntry</c> read from the stream.</returns>
</member>
<member name="P:Ionic.Zip.ZipEntry.LastModified">
<summary>
The time and date at which the file indicated by the <c>ZipEntry</c> was
last modified.
</summary>
<remarks>
<para>
The DotNetZip library sets the LastModified value for an entry, equal to
the Last Modified time of the file in the filesystem. If an entry is
added from a stream, the library uses <c>System.DateTime.Now</c> for this
value, for the given entry.
</para>
<para>
This property allows the application to retrieve and possibly set the
LastModified value on an entry, to an arbitrary value. <see cref="T:System.DateTime"/> values with a <see cref="T:System.DateTimeKind"/>
setting of <c>DateTimeKind.Unspecified</c> are taken to be expressed as
<c>DateTimeKind.Local</c>.
</para>
<para>
Be aware that because of the way <see href="http://www.pkware.com/documents/casestudies/APPNOTE.TXT">PKWare's
Zip specification</see> describes how times are stored in the zip file,
the full precision of the <c>System.DateTime</c> datatype is not stored
for the last modified time when saving zip files. For more information on
how times are formatted, see the PKZip specification.
</para>
<para>
The actual last modified time of a file can be stored in multiple ways in
the zip file, and they are not mutually exclusive:
</para>
<list type="bullet">
<item>
In the so-called "DOS" format, which has a 2-second precision. Values
are rounded to the nearest even second. For example, if the time on the
file is 12:34:43, then it will be stored as 12:34:44. This first value
is accessible via the <c>LastModified</c> property. This value is always
present in the metadata for each zip entry. In some cases the value is
invalid, or zero.
</item>
<item>
In the so-called "Windows" or "NTFS" format, as an 8-byte integer
quantity expressed as the number of 1/10 milliseconds (in other words
the number of 100 nanosecond units) since January 1, 1601 (UTC). This
format is how Windows represents file times. This time is accessible
via the <c>ModifiedTime</c> property.
</item>
<item>
In the "Unix" format, a 4-byte quantity specifying the number of seconds since
January 1, 1970 UTC.
</item>
<item>
In an older format, now deprecated but still used by some current
tools. This format is also a 4-byte quantity specifying the number of
seconds since January 1, 1970 UTC.
</item>
</list>
<para>
Zip tools and libraries will always at least handle (read or write) the
DOS time, and may also handle the other time formats. Keep in mind that
while the names refer to particular operating systems, there is nothing in
the time formats themselves that prevents their use on other operating
systems.
</para>
<para>
When reading ZIP files, The DotNetZip library reads the Windoes-formatted
time, if it is stored in the entry, and sets both <c>LastModified</c> and
<c>ModifiedTime</c> to that value. When writing ZIP files, the DotNetZip
library by default will write both time quantities. It can also emit the
Unix-formatted time if desired (See <see cref="P:Ionic.Zip.ZipEntry.EmitTimesInUnixFormatWhenSaving"/>.)
</para>
<para>
The last modified time of the file created upon a call to
<c>ZipEntry.Extract()</c> may be adjusted during extraction to compensate
for differences in how the .NET Base Class Library deals with daylight
saving time (DST) versus how the Windows filesystem deals with daylight
saving time. Raymond Chen <see href="http://blogs.msdn.com/oldnewthing/archive/2003/10/24/55413.aspx">provides
some good context</see>.
</para>
<para>
In a nutshell: Daylight savings time rules change regularly. In 2007, for
example, the inception week of DST changed. In 1977, DST was in place all
year round. In 1945, likewise. And so on. Win32 does not attempt to
guess which time zone rules were in effect at the time in question. It
will render a time as "standard time" and allow the app to change to DST
as necessary. .NET makes a different choice.
</para>
<para>
Compare the output of FileInfo.LastWriteTime.ToString("f") with what you
see in the Windows Explorer property sheet for a file that was last
written to on the other side of the DST transition. For example, suppose
the file was last modified on October 17, 2003, during DST but DST is not
currently in effect. Explorer's file properties reports Thursday, October
17, 2003, 8:45:38 AM, but .NETs FileInfo reports Thursday, October 17,
2003, 9:45 AM.
</para>
<para>
Win32 says, "Thursday, October 17, 2002 8:45:38 AM PST". Note: Pacific
STANDARD Time. Even though October 17 of that year occurred during Pacific
Daylight Time, Win32 displays the time as standard time because that's
what time it is NOW.
</para>
<para>
.NET BCL assumes that the current DST rules were in place at the time in
question. So, .NET says, "Well, if the rules in effect now were also in
effect on October 17, 2003, then that would be daylight time" so it
displays "Thursday, October 17, 2003, 9:45 AM PDT" - daylight time.
</para>
<para>
So .NET gives a value which is more intuitively correct, but is also
potentially incorrect, and which is not invertible. Win32 gives a value
which is intuitively incorrect, but is strictly correct.
</para>
<para>
Because of this funkiness, this library adds one hour to the LastModified
time on the extracted file, if necessary. That is to say, if the time in
question had occurred in what the .NET Base Class Library assumed to be
DST. This assumption may be wrong given the constantly changing DST rules,
but it is the best we can do.
</para>
</remarks>
</member>
<member name="P:Ionic.Zip.ZipEntry.ModifiedTime">
<summary>
Last Modified time for the file represented by the entry.
</summary>
<remarks>
<para>
This value corresponds to the "last modified" time in the NTFS file times
as described in <see href="http://www.pkware.com/documents/casestudies/APPNOTE.TXT">the Zip
specification</see>. When getting this property, the value may be
different from <see cref="P:Ionic.Zip.ZipEntry.LastModified"/>. When setting the property,
the <see cref="P:Ionic.Zip.ZipEntry.LastModified"/> property also gets set, but with a lower
precision.
</para>
<para>
Let me explain. It's going to take a while, so get
comfortable. Originally, waaaaay back in 1989 when the ZIP specification
was originally described by the esteemed Mr. Phil Katz, the dominant
operating system of the time was MS-DOS. MSDOS stored file times with a
2-second precision, because, c'mon, <em>who is ever going to need better
resolution than THAT?</em> And so ZIP files, regardless of the platform on
which the zip file was created, store file times in exactly <see href="http://www.vsft.com/hal/dostime.htm">the same format that DOS used
in 1989</see>.
</para>
<para>
Since then, the ZIP spec has evolved, but the internal format for file
timestamps remains the same. Despite the fact that the way times are
stored in a zip file is rooted in DOS heritage, any program on any
operating system can format a time in this way, and most zip tools and
libraries DO - they round file times to the nearest even second and store
it just like DOS did 25+ years ago.
</para>
<para>
PKWare extended the ZIP specification to allow a zip file to store what
are called "NTFS Times" and "Unix(tm) times" for a file. These are the
<em>last write</em>, <em>last access</em>, and <em>file creation</em>
times of a particular file. These metadata are not actually specific to
NTFS or Unix. They are tracked for each file by NTFS and by various Unix
filesystems, but they are also tracked by other filesystems, too. The key
point is that the times are <em>formatted in the zip file</em> in the same
way that NTFS formats the time (ticks since win32 epoch), or in the same
way that Unix formats the time (seconds since Unix epoch).
</para>
<para>
These extended times are higher precision quantities than the DOS time.
As described above, the (DOS) LastModified has a precision of 2 seconds.
The Unix time is stored with a precision of 1 second. The NTFS time is
stored with a precision of 0.0000001 seconds. The quantities are easily
convertible, except for the loss of precision you may incur.
</para>
<para>
A zip archive can store the {C,A,M} times in NTFS format, in Unix format,
or not at all. Often a tool running on Unix or Mac will embed the times
in Unix format (1 second precision), while WinZip running on Windows might
embed the times in NTFS format (precision of of 0.0000001 seconds). When
reading a zip file with these "extended" times, in either format,
DotNetZip represents the values with the
<c>ModifiedTime</c>, <c>AccessedTime</c> and <c>CreationTime</c>
properties on the <c>ZipEntry</c>.
</para>
<para>
As with the DOS time, any tool or library running on any operating system
is capable of formatting a time in one of these ways and embedding it into
the zip file. The key is, not all zip tools or libraries support all these
formats. Storing the higher-precision times for each entry is optional
for zip files, and many tools and libraries don't use the higher precision
quantities at all, though it is much nicer than the DOS time. And futher,
there are also cases where the timestamp of the file entry is not known,
and is not stored. For example, this happens when content for the entry is
obtained from a stream. The bottom line is that the higher-resolution
times, in either format, are not guaranteed to be present for a ZipEntry.
The old DOS time, represented by <see cref="P:Ionic.Zip.ZipEntry.LastModified"/>, is guaranteed
to be present, though it sometimes unset.
</para>
<para>
Ok, getting back to the question about how the <c>LastModified</c>
property relates to this <c>ModifiedTime</c>
property... <c>LastModified</c> is always set, while <c>ModifiedTime</c>
is not. (The other times stored in the <em>NTFS times extension</em>,
<c>CreationTime</c> and <c>AccessedTime</c> also may not be set on an
entry that is read from an existing zip file.) When reading a zip file,
then <c>LastModified</c> takes the DOS time that is stored with the
file. If the DOS time has been stored as zero in the zipfile, then this
library will use <c>DateTime.Now</c> for the <c>LastModified</c> value.
If the ZIP file was created by an evolved tool, then there will also be
NTFS times in the zip file. In that case, this library will read those
times, and set <c>LastModified</c> and <c>ModifiedTime</c> to the same
value, the one corresponding to the last write time of the file. If there
are no "NTFS times" stored for the entry, then <c>ModifiedTime</c> remains
unset (likewise <c>AccessedTime</c> and <c>CreationTime</c>), and
<c>LastModified</c> keeps its DOS time.
</para>
<para>
When creating zip files with this library, by default the extended time
properties (<c>ModifiedTime</c>, <c>AccessedTime</c>, and
<c>CreationTime</c>) are set on the ZipEntry instance, and these data are
stored in the zip archive for each entry, in NTFS format. If you add an
entry from an actual filesystem file, then the entry gets the actual file
times for that file, to NTFS-level precision. If you add an entry from a
stream, or a string, then the times get the value <c>DateTime.Now</c>. In
this case <c>LastModified</c> and <c>ModifiedTime</c> will be identical,
to 2 seconds of precision. You can explicitly set the
<c>CreationTime</c>, <c>AccessedTime</c>, and <c>ModifiedTime</c> of an
entry using the property setters. If you want to set all of those
quantities, it's more efficient to use the <see cref="M:Ionic.Zip.ZipEntry.SetEntryTimes(System.DateTime,System.DateTime,System.DateTime)"/> method. Those
changes are not made permanent in the zip file until you call <see cref="M:Ionic.Zip.ZipFile.Save"/> or one of its cousins.
</para>
<para>
When creating a zip file, you can override the default behavior for
formatting times in the zip file, disabling the embedding of file times in
NTFS format or enabling the storage of file times in Unix format, or both.
You may want to do this, for example, when creating a zip file on Windows,
that will be consumed on a Mac, by an application that is not hip to the
"NTFS times" format. To do this, use the <see cref="P:Ionic.Zip.ZipEntry.EmitTimesInWindowsFormatWhenSaving"/> and <see cref="P:Ionic.Zip.ZipEntry.EmitTimesInUnixFormatWhenSaving"/> properties. A valid zip file may
store the file times in both formats. But, there are no guarantees that a
program running on Mac or Linux will gracefully handle the NTFS Formatted
times, or that a non-DotNetZip-powered application running on Windows will
be able to handle file times in Unix format. When in doubt, test.
</para>
<para>
I'll bet you didn't think one person could type so much about time, eh?
And reading it was so enjoyable, too! Well, in appreciation, <see href="http://cheeso.members.winisp.net/DotNetZipDonate.aspx">maybe you
should donate</see>?
</para>
</remarks>
<seealso cref="P:Ionic.Zip.ZipEntry.AccessedTime"/>
<seealso cref="P:Ionic.Zip.ZipEntry.CreationTime"/>
<seealso cref="P:Ionic.Zip.ZipEntry.LastModified"/>
<seealso cref="M:Ionic.Zip.ZipEntry.SetEntryTimes(System.DateTime,System.DateTime,System.DateTime)"/>
</member>
<member name="P:Ionic.Zip.ZipEntry.AccessedTime">
<summary>
Last Access time for the file represented by the entry.
</summary>
<remarks>
This value may or may not be meaningful. If the <c>ZipEntry</c> was read from an existing
Zip archive, this information may not be available. For an explanation of why, see
<see cref="P:Ionic.Zip.ZipEntry.ModifiedTime"/>.
</remarks>
<seealso cref="P:Ionic.Zip.ZipEntry.ModifiedTime"/>
<seealso cref="P:Ionic.Zip.ZipEntry.CreationTime"/>
<seealso cref="M:Ionic.Zip.ZipEntry.SetEntryTimes(System.DateTime,System.DateTime,System.DateTime)"/>
</member>
<member name="P:Ionic.Zip.ZipEntry.CreationTime">
<summary>
The file creation time for the file represented by the entry.
</summary>
<remarks>
This value may or may not be meaningful. If the <c>ZipEntry</c> was read
from an existing zip archive, and the creation time was not set on the entry
when the zip file was created, then this property may be meaningless. For an
explanation of why, see <see cref="P:Ionic.Zip.ZipEntry.ModifiedTime"/>.
</remarks>
<seealso cref="P:Ionic.Zip.ZipEntry.ModifiedTime"/>
<seealso cref="P:Ionic.Zip.ZipEntry.AccessedTime"/>
<seealso cref="M:Ionic.Zip.ZipEntry.SetEntryTimes(System.DateTime,System.DateTime,System.DateTime)"/>
</member>
<member name="P:Ionic.Zip.ZipEntry.EmitTimesInWindowsFormatWhenSaving">
<summary>
Specifies whether the Creation, Access, and Modified times for the given
entry will be emitted in "Windows format" when the zip archive is saved.
</summary>
<remarks>
<para>
An application creating a zip archive can use this flag to explicitly
specify that the file times for the entry should or should not be stored
in the zip archive in the format used by Windows. The default value of
this property is <c>true</c>.
</para>
<para>
When adding an entry from a file or directory, the Creation (<see cref="P:Ionic.Zip.ZipEntry.CreationTime"/>), Access (<see cref="P:Ionic.Zip.ZipEntry.AccessedTime"/>), and Modified
(<see cref="P:Ionic.Zip.ZipEntry.ModifiedTime"/>) times for the given entry are automatically
set from the filesystem values. When adding an entry from a stream or
string, all three values are implicitly set to DateTime.Now. Applications
can also explicitly set those times by calling <see cref="M:Ionic.Zip.ZipEntry.SetEntryTimes(System.DateTime,System.DateTime,System.DateTime)"/>.
</para>
<para>
<see href="http://www.pkware.com/documents/casestudies/APPNOTE.TXT">PKWARE's
zip specification</see> describes multiple ways to format these times in a
zip file. One is the format Windows applications normally use: 100ns ticks
since Jan 1, 1601 UTC. The other is a format Unix applications typically
use: seconds since January 1, 1970 UTC. Each format can be stored in an
"extra field" in the zip entry when saving the zip archive. The former
uses an extra field with a Header Id of 0x000A, while the latter uses a
header ID of 0x5455.
</para>
<para>
Not all zip tools and libraries can interpret these fields. Windows
compressed folders is one that can read the Windows Format timestamps,
while I believe the <see href="http://www.info-zip.org/">Infozip</see>
tools can read the Unix format timestamps. Although the time values are
easily convertible, subject to a loss of precision, some tools and
libraries may be able to read only one or the other. DotNetZip can read or
write times in either or both formats.
</para>
<para>
The times stored are taken from <see cref="P:Ionic.Zip.ZipEntry.ModifiedTime"/>, <see cref="P:Ionic.Zip.ZipEntry.AccessedTime"/>, and <see cref="P:Ionic.Zip.ZipEntry.CreationTime"/>.
</para>
<para>
This property is not mutually exclusive from the <see cref="P:Ionic.Zip.ZipEntry.EmitTimesInUnixFormatWhenSaving"/> property. It is
possible that a zip entry can embed the timestamps in both forms, one
form, or neither. But, there are no guarantees that a program running on
Mac or Linux will gracefully handle NTFS Formatted times, or that a
non-DotNetZip-powered application running on Windows will be able to
handle file times in Unix format. When in doubt, test.
</para>
<para>
Normally you will use the <see cref="P:Ionic.Zip.ZipFile.EmitTimesInWindowsFormatWhenSaving">ZipFile.EmitTimesInWindowsFormatWhenSaving</see>
property, to specify the behavior for all entries in a zip, rather than
the property on each individual entry.
</para>
</remarks>
<seealso cref="M:Ionic.Zip.ZipEntry.SetEntryTimes(System.DateTime,System.DateTime,System.DateTime)"/>
<seealso cref="P:Ionic.Zip.ZipEntry.EmitTimesInUnixFormatWhenSaving"/>
<seealso cref="P:Ionic.Zip.ZipEntry.CreationTime"/>
<seealso cref="P:Ionic.Zip.ZipEntry.AccessedTime"/>
<seealso cref="P:Ionic.Zip.ZipEntry.ModifiedTime"/>
</member>
<member name="P:Ionic.Zip.ZipEntry.EmitTimesInUnixFormatWhenSaving">
<summary>
Specifies whether the Creation, Access, and Modified times for the given
entry will be emitted in "Unix(tm) format" when the zip archive is saved.
</summary>
<remarks>
<para>
An application creating a zip archive can use this flag to explicitly
specify that the file times for the entry should or should not be stored
in the zip archive in the format used by Unix. By default this flag is
<c>false</c>, meaning the Unix-format times are not stored in the zip
archive.
</para>
<para>
When adding an entry from a file or directory, the Creation (<see cref="P:Ionic.Zip.ZipEntry.CreationTime"/>), Access (<see cref="P:Ionic.Zip.ZipEntry.AccessedTime"/>), and Modified
(<see cref="P:Ionic.Zip.ZipEntry.ModifiedTime"/>) times for the given entry are automatically
set from the filesystem values. When adding an entry from a stream or
string, all three values are implicitly set to DateTime.Now. Applications
can also explicitly set those times by calling <see cref="M:Ionic.Zip.ZipEntry.SetEntryTimes(System.DateTime,System.DateTime,System.DateTime)"/>.
</para>
<para>
<see href="http://www.pkware.com/documents/casestudies/APPNOTE.TXT">PKWARE's
zip specification</see> describes multiple ways to format these times in a
zip file. One is the format Windows applications normally use: 100ns ticks
since Jan 1, 1601 UTC. The other is a format Unix applications typically
use: seconds since Jan 1, 1970 UTC. Each format can be stored in an
"extra field" in the zip entry when saving the zip archive. The former
uses an extra field with a Header Id of 0x000A, while the latter uses a
header ID of 0x5455.
</para>
<para>
Not all tools and libraries can interpret these fields. Windows
compressed folders is one that can read the Windows Format timestamps,
while I believe the <see href="http://www.info-zip.org/">Infozip</see>
tools can read the Unix format timestamps. Although the time values are
easily convertible, subject to a loss of precision, some tools and
libraries may be able to read only one or the other. DotNetZip can read or
write times in either or both formats.
</para>
<para>
The times stored are taken from <see cref="P:Ionic.Zip.ZipEntry.ModifiedTime"/>, <see cref="P:Ionic.Zip.ZipEntry.AccessedTime"/>, and <see cref="P:Ionic.Zip.ZipEntry.CreationTime"/>.
</para>
<para>
This property is not mutually exclusive from the <see cref="P:Ionic.Zip.ZipEntry.EmitTimesInWindowsFormatWhenSaving"/> property. It is
possible that a zip entry can embed the timestamps in both forms, one
form, or neither. But, there are no guarantees that a program running on
Mac or Linux will gracefully handle NTFS Formatted times, or that a
non-DotNetZip-powered application running on Windows will be able to
handle file times in Unix format. When in doubt, test.
</para>
<para>
Normally you will use the <see cref="P:Ionic.Zip.ZipFile.EmitTimesInUnixFormatWhenSaving">ZipFile.EmitTimesInUnixFormatWhenSaving</see>
property, to specify the behavior for all entries, rather than the
property on each individual entry.
</para>
</remarks>
<seealso cref="M:Ionic.Zip.ZipEntry.SetEntryTimes(System.DateTime,System.DateTime,System.DateTime)"/>
<seealso cref="P:Ionic.Zip.ZipEntry.EmitTimesInWindowsFormatWhenSaving"/>
<seealso cref="P:Ionic.Zip.ZipFile.EmitTimesInUnixFormatWhenSaving"/>
<seealso cref="P:Ionic.Zip.ZipEntry.CreationTime"/>
<seealso cref="P:Ionic.Zip.ZipEntry.AccessedTime"/>
<seealso cref="P:Ionic.Zip.ZipEntry.ModifiedTime"/>
</member>
<member name="P:Ionic.Zip.ZipEntry.Timestamp">
<summary>
The type of timestamp attached to the ZipEntry.
</summary>
<remarks>
This property is valid only for a ZipEntry that was read from a zip archive.
It indicates the type of timestamp attached to the entry.
</remarks>
<seealso cref="P:Ionic.Zip.ZipEntry.EmitTimesInWindowsFormatWhenSaving"/>
<seealso cref="P:Ionic.Zip.ZipEntry.EmitTimesInUnixFormatWhenSaving"/>
</member>
<member name="P:Ionic.Zip.ZipEntry.Attributes">
<summary>
The file attributes for the entry.
</summary>
<remarks>
<para>
The <see cref="T:System.IO.FileAttributes">attributes</see> in NTFS include
ReadOnly, Archive, Hidden, System, and Indexed. When adding a
<c>ZipEntry</c> to a ZipFile, these attributes are set implicitly when
adding an entry from the filesystem. When adding an entry from a stream
or string, the Attributes are not set implicitly. Regardless of the way
an entry was added to a <c>ZipFile</c>, you can set the attributes
explicitly if you like.
</para>
<para>
When reading a <c>ZipEntry</c> from a <c>ZipFile</c>, the attributes are
set according to the data stored in the <c>ZipFile</c>. If you extract the
entry from the archive to a filesystem file, DotNetZip will set the
attributes on the resulting file accordingly.
</para>
<para>
The attributes can be set explicitly by the application. For example the
application may wish to set the <c>FileAttributes.ReadOnly</c> bit for all
entries added to an archive, so that on unpack, this attribute will be set
on the extracted file. Any changes you make to this property are made
permanent only when you call a <c>Save()</c> method on the <c>ZipFile</c>
instance that contains the ZipEntry.
</para>
<para>
For example, an application may wish to zip up a directory and set the
ReadOnly bit on every file in the archive, so that upon later extraction,
the resulting files will be marked as ReadOnly. Not every extraction tool
respects these attributes, but if you unpack with DotNetZip, as for
example in a self-extracting archive, then the attributes will be set as
they are stored in the <c>ZipFile</c>.
</para>
<para>
These attributes may not be interesting or useful if the resulting archive
is extracted on a non-Windows platform. How these attributes get used
upon extraction depends on the platform and tool used.
</para>
</remarks>
</member>
<member name="P:Ionic.Zip.ZipEntry.LocalFileName">
<summary>
The name of the filesystem file, referred to by the ZipEntry.
</summary>
<remarks>
<para>
This property specifies the thing-to-be-zipped on disk, and is set only
when the <c>ZipEntry</c> is being created from a filesystem file. If the
<c>ZipFile</c> is instantiated by reading an existing .zip archive, then
the LocalFileName will be <c>null</c> (<c>Nothing</c> in VB).
</para>
<para>
When it is set, the value of this property may be different than <see cref="P:Ionic.Zip.ZipEntry.FileName"/>, which is the path used in the archive itself. If you
call <c>Zip.AddFile("foop.txt", AlternativeDirectory)</c>, then the path
used for the <c>ZipEntry</c> within the zip archive will be different
than this path.
</para>
<para>
If the entry is being added from a stream, then this is null (Nothing in VB).
</para>
</remarks>
<seealso cref="P:Ionic.Zip.ZipEntry.FileName"/>
</member>
<member name="P:Ionic.Zip.ZipEntry.FileName">
<summary>
The name of the file contained in the ZipEntry.
</summary>
<remarks>
<para>
This is the name of the entry in the <c>ZipFile</c> itself. When creating
a zip archive, if the <c>ZipEntry</c> has been created from a filesystem
file, via a call to <see cref="M:Ionic.Zip.ZipFile.AddFile(System.String,System.String)"/> or <see cref="M:Ionic.Zip.ZipFile.AddItem(System.String,System.String)"/>, or a related overload, the value
of this property is derived from the name of that file. The
<c>FileName</c> property does not include drive letters, and may include a
different directory path, depending on the value of the
<c>directoryPathInArchive</c> parameter used when adding the entry into
the <c>ZipFile</c>.
</para>
<para>
In some cases there is no related filesystem file - for example when a
<c>ZipEntry</c> is created using <see cref="M:Ionic.Zip.ZipFile.AddEntry(System.String,System.String)"/> or one of the similar overloads. In this case, the value of
this property is derived from the fileName and the directory path passed
to that method.
</para>
<para>
When reading a zip file, this property takes the value of the entry name
as stored in the zip file. If you extract such an entry, the extracted
file will take the name given by this property.
</para>
<para>
Applications can set this property when creating new zip archives or when
reading existing archives. When setting this property, the actual value
that is set will replace backslashes with forward slashes, in accordance
with <see href="http://www.pkware.com/documents/casestudies/APPNOTE.TXT">the Zip
specification</see>, for compatibility with Unix(tm) and ... get
this.... Amiga!
</para>
<para>
If an application reads a <c>ZipFile</c> via <see cref="M:Ionic.Zip.ZipFile.Read(System.String)"/> or a related overload, and then explicitly
sets the FileName on an entry contained within the <c>ZipFile</c>, and
then calls <see cref="M:Ionic.Zip.ZipFile.Save"/>, the application will effectively
rename the entry within the zip archive.
</para>
<para>
If an application sets the value of <c>FileName</c>, then calls
<c>Extract()</c> on the entry, the entry is extracted to a file using the
newly set value as the filename. The <c>FileName</c> value is made
permanent in the zip archive only <em>after</em> a call to one of the
<c>ZipFile.Save()</c> methods on the <c>ZipFile</c> that contains the
ZipEntry.
</para>
<para>
If an application attempts to set the <c>FileName</c> to a value that
would result in a duplicate entry in the <c>ZipFile</c>, an exception is
thrown.
</para>
</remarks>
</member>
<member name="P:Ionic.Zip.ZipEntry.InputStream">
<summary>
The stream that provides content for the ZipEntry.
</summary>
<remarks>
<para>
The application can use this property to set the input stream for an
entry on a just-in-time basis. Imagine a scenario where the application
creates a <c>ZipFile</c> comprised of content obtained from hundreds of
files, via calls to <c>AddFile()</c>. The DotNetZip library opens streams
on these files on a just-in-time basis, only when writing the entry out to
an external store within the scope of a <c>ZipFile.Save()</c> call. Only
one input stream is opened at a time, as each entry is being written out.
</para>
<para>
Now imagine a different application that creates a <c>ZipFile</c>
with content obtained from hundreds of streams, added through <see cref="M:Ionic.Zip.ZipFile.AddEntry(System.String,System.IO.Stream)"/>. Normally the
application would supply an open stream to that call. But when large
numbers of streams are being added, this can mean many open streams at one
time, unnecessarily.
</para>
<para>
To avoid this, call <see cref="M:Ionic.Zip.ZipFile.AddEntry(System.String,Ionic.Zip.OpenDelegate,Ionic.Zip.CloseDelegate)"/> and specify delegates that open and close the stream at
the time of Save.
</para>
<para>
Setting the value of this property when the entry was not added from a
stream (for example, when the <c>ZipEntry</c> was added with <see cref="M:Ionic.Zip.ZipFile.AddFile(System.String)"/> or <see cref="M:Ionic.Zip.ZipFile.AddDirectory(System.String)"/>, or when the entry was added by
reading an existing zip archive) will throw an exception.
</para>
</remarks>
</member>
<member name="P:Ionic.Zip.ZipEntry.InputStreamWasJitProvided">
<summary>
A flag indicating whether the InputStream was provided Just-in-time.
</summary>
<remarks>
<para>
When creating a zip archive, an application can obtain content for one or
more of the <c>ZipEntry</c> instances from streams, using the <see cref="M:Ionic.Zip.ZipFile.AddEntry(System.String,System.IO.Stream)"/> method. At the time
of calling that method, the application can supply null as the value of
the stream parameter. By doing so, the application indicates to the
library that it will provide a stream for the entry on a just-in-time
basis, at the time one of the <c>ZipFile.Save()</c> methods is called and
the data for the various entries are being compressed and written out.
</para>
<para>
In this case, the application can set the <see cref="P:Ionic.Zip.ZipEntry.InputStream"/>
property, typically within the SaveProgress event (event type: <see cref="F:Ionic.Zip.ZipProgressEventType.Saving_BeforeWriteEntry"/>) for that entry.
</para>
<para>
The application will later want to call Close() and Dispose() on that
stream. In the SaveProgress event, when the event type is <see cref="F:Ionic.Zip.ZipProgressEventType.Saving_AfterWriteEntry"/>, the application can
do so. This flag indicates that the stream has been provided by the
application on a just-in-time basis and that it is the application's
responsibility to call Close/Dispose on that stream.
</para>
</remarks>
<seealso cref="P:Ionic.Zip.ZipEntry.InputStream"/>
</member>
<member name="P:Ionic.Zip.ZipEntry.Source">
<summary>
An enum indicating the source of the ZipEntry.
</summary>
</member>
<member name="P:Ionic.Zip.ZipEntry.VersionNeeded">
<summary>
The version of the zip engine needed to read the ZipEntry.
</summary>
<remarks>
<para>
This is a readonly property, indicating the version of <a
href="http://www.pkware.com/documents/casestudies/APPNOTE.TXT">the Zip
specification</a> that the extracting tool or library must support to
extract the given entry. Generally higher versions indicate newer
features. Older zip engines obviously won't know about new features, and
won't be able to extract entries that depend on those newer features.
</para>
<list type="table">
<listheader>
<term>value</term>
<description>Features</description>
</listheader>
<item>
<term>20</term>
<description>a basic Zip Entry, potentially using PKZIP encryption.
</description>
</item>
<item>
<term>45</term>
<description>The ZIP64 extension is used on the entry.
</description>
</item>
<item>
<term>46</term>
<description> File is compressed using BZIP2 compression*</description>
</item>
<item>
<term>50</term>
<description> File is encrypted using PkWare's DES, 3DES, (broken) RC2 or RC4</description>
</item>
<item>
<term>51</term>
<description> File is encrypted using PKWare's AES encryption or corrected RC2 encryption.</description>
</item>
<item>
<term>52</term>
<description> File is encrypted using corrected RC2-64 encryption**</description>
</item>
<item>
<term>61</term>
<description> File is encrypted using non-OAEP key wrapping***</description>
</item>
<item>
<term>63</term>
<description> File is compressed using LZMA, PPMd+, Blowfish, or Twofish</description>
</item>
</list>
<para>
There are other values possible, not listed here. DotNetZip supports
regular PKZip encryption, and ZIP64 extensions. DotNetZip cannot extract
entries that require a zip engine higher than 45.
</para>
<para>
This value is set upon reading an existing zip file, or after saving a zip
archive.
</para>
</remarks>
</member>
<member name="P:Ionic.Zip.ZipEntry.Comment">
<summary>
The comment attached to the ZipEntry.
</summary>
<remarks>
<para>
Each entry in a zip file can optionally have a comment associated to
it. The comment might be displayed by a zip tool during extraction, for
example.
</para>
<para>
By default, the <c>Comment</c> is encoded in IBM437 code page. You can
specify an alternative with <see cref="P:Ionic.Zip.ZipEntry.ProvisionalAlternateEncoding"/>
</para>
</remarks>
<seealso cref="P:Ionic.Zip.ZipEntry.ProvisionalAlternateEncoding"/>
</member>
<member name="P:Ionic.Zip.ZipEntry.RequiresZip64">
<summary>
Indicates whether the entry requires ZIP64 extensions.
</summary>
<remarks>
<para>
This property is null (Nothing in VB) until a <c>Save()</c> method on the
containing <see cref="T:Ionic.Zip.ZipFile"/> instance has been called. The property is
non-null (<c>HasValue</c> is true) only after a <c>Save()</c> method has
been called.
</para>
<para>
After the containing <c>ZipFile</c> has been saved, the Value of this
property is true if any of the following three conditions holds: the
uncompressed size of the entry is larger than 0xFFFFFFFF; the compressed
size of the entry is larger than 0xFFFFFFFF; the relative offset of the
entry within the zip archive is larger than 0xFFFFFFFF. These quantities
are not known until a <c>Save()</c> is attempted on the zip archive and
the compression is applied.
</para>
<para>
If none of the three conditions holds, then the <c>Value</c> is false.
</para>
<para>
A <c>Value</c> of false does not indicate that the entry, as saved in the
zip archive, does not use ZIP64. It merely indicates that ZIP64 is
<em>not required</em>. An entry may use ZIP64 even when not required if
the <see cref="P:Ionic.Zip.ZipFile.UseZip64WhenSaving"/> property on the containing
<c>ZipFile</c> instance is set to <see cref="F:Ionic.Zip.Zip64Option.Always"/>, or if
the <see cref="P:Ionic.Zip.ZipFile.UseZip64WhenSaving"/> property on the containing
<c>ZipFile</c> instance is set to <see cref="F:Ionic.Zip.Zip64Option.AsNecessary"/>
and the output stream was not seekable.
</para>
</remarks>
<seealso cref="P:Ionic.Zip.ZipEntry.OutputUsedZip64"/>
</member>
<member name="P:Ionic.Zip.ZipEntry.OutputUsedZip64">
<summary>
Indicates whether the entry actually used ZIP64 extensions, as it was most
recently written to the output file or stream.
</summary>
<remarks>
<para>
This Nullable property is null (Nothing in VB) until a <c>Save()</c>
method on the containing <see cref="T:Ionic.Zip.ZipFile"/> instance has been
called. <c>HasValue</c> is true only after a <c>Save()</c> method has been
called.
</para>
<para>
The value of this property for a particular <c>ZipEntry</c> may change
over successive calls to <c>Save()</c> methods on the containing ZipFile,
even if the file that corresponds to the <c>ZipEntry</c> does not. This
may happen if other entries contained in the <c>ZipFile</c> expand,
causing the offset for this particular entry to exceed 0xFFFFFFFF.
</para>
</remarks>
<seealso cref="P:Ionic.Zip.ZipEntry.RequiresZip64"/>
</member>
<member name="P:Ionic.Zip.ZipEntry.BitField">
<summary>
The bitfield for the entry as defined in the zip spec. You probably never need to look at this.
</summary>
<remarks>
<list type="table">
<listheader>
<term>bit</term>
<description>meaning</description>
</listheader>
<item>
<term>0</term>
<description>set if encryption is used.</description>
</item>
<item>
<term>1-2</term>
<description>
set to determine whether normal, max, fast deflation. DotNetZip library
always leaves these bits unset when writing (indicating "normal"
deflation"), but can read an entry with any value here.
</description>
</item>
<item>
<term>3</term>
<description>
Indicates that the Crc32, Compressed and Uncompressed sizes are zero in the
local header. This bit gets set on an entry during writing a zip file, when
it is saved to a non-seekable output stream.
</description>
</item>
<item>
<term>4</term>
<description>reserved for "enhanced deflating". This library doesn't do enhanced deflating.</description>
</item>
<item>
<term>5</term>
<description>set to indicate the zip is compressed patched data. This library doesn't do that.</description>
</item>
<item>
<term>6</term>
<description>
set if PKWare's strong encryption is used (must also set bit 1 if bit 6 is
set). This bit is not set if WinZip's AES encryption is set.</description>
</item>
<item>
<term>7</term>
<description>not used</description>
</item>
<item>
<term>8</term>
<description>not used</description>
</item>
<item>
<term>9</term>
<description>not used</description>
</item>
<item>
<term>10</term>
<description>not used</description>
</item>
<item>
<term>11</term>
<description>
Language encoding flag (EFS). If this bit is set, the filename and comment
fields for this file must be encoded using UTF-8. This library currently
does not support UTF-8.
</description>
</item>
<item>
<term>12</term>
<description>Reserved by PKWARE for enhanced compression.</description>
</item>
<item>
<term>13</term>
<description>
Used when encrypting the Central Directory to indicate selected data
values in the Local Header are masked to hide their actual values. See
the section in <a
href="http://www.pkware.com/documents/casestudies/APPNOTE.TXT">the Zip
specification</a> describing the Strong Encryption Specification for
details.
</description>
</item>
<item>
<term>14</term>
<description>Reserved by PKWARE.</description>
</item>
<item>
<term>15</term>
<description>Reserved by PKWARE.</description>
</item>
</list>
</remarks>
</member>
<member name="P:Ionic.Zip.ZipEntry.CompressionMethod">
<summary>
The compression method employed for this ZipEntry.
</summary>
<remarks>
<para>
<see href="http://www.pkware.com/documents/casestudies/APPNOTE.TXT">The
Zip specification</see> allows a variety of compression methods. This
library supports just two: 0x08 = Deflate. 0x00 = Store (no compression),
for reading or writing.
</para>
<para>
When reading an entry from an existing zipfile, the value you retrieve
here indicates the compression method used on the entry by the original
creator of the zip. When writing a zipfile, you can specify either 0x08
(Deflate) or 0x00 (None). If you try setting something else, you will get
an exception.
</para>
<para>
You may wish to set <c>CompressionMethod</c> to <c>CompressionMethod.None</c> (0)
when zipping already-compressed data like a jpg, png, or mp3 file.
This can save time and cpu cycles.
</para>
<para>
When setting this property on a <c>ZipEntry</c> that is read from an
existing zip file, calling <c>ZipFile.Save()</c> will cause the new
CompressionMethod to be used on the entry in the newly saved zip file.
</para>
<para>
Setting this property may have the side effect of modifying the
<c>CompressionLevel</c> property. If you set the <c>CompressionMethod</c> to a
value other than <c>None</c>, and <c>CompressionLevel</c> is previously
set to <c>None</c>, then <c>CompressionLevel</c> will be set to
<c>Default</c>.
</para>
</remarks>
<seealso cref="P:Ionic.Zip.ZipEntry.CompressionMethod"/>
<example>
In this example, the first entry added to the zip archive uses the default
behavior - compression is used where it makes sense. The second entry,
the MP3 file, is added to the archive without being compressed.
<code>
using (ZipFile zip = new ZipFile(ZipFileToCreate))
{
ZipEntry e1= zip.AddFile(@"notes\Readme.txt");
ZipEntry e2= zip.AddFile(@"music\StopThisTrain.mp3");
e2.CompressionMethod = CompressionMethod.None;
zip.Save();
}
</code>
<code lang="VB">
Using zip As New ZipFile(ZipFileToCreate)
zip.AddFile("notes\Readme.txt")
Dim e2 as ZipEntry = zip.AddFile("music\StopThisTrain.mp3")
e2.CompressionMethod = CompressionMethod.None
zip.Save
End Using
</code>
</example>
</member>
<member name="P:Ionic.Zip.ZipEntry.CompressionLevel">
<summary>
Sets the compression level to be used for the entry when saving the zip
archive.
</summary>
<remarks>
<para>
Varying the compression level used on entries can affect the
size-vs-speed tradeoff when compression and decompressing data streams
or files.
</para>
<para>
If you do not set this property, the default compression level is used,
which normally gives a good balance of compression efficiency and
compression speed. In some tests, using <c>BestCompression</c> can
double the time it takes to compress, while delivering just a small
increase in compression efficiency. This behavior will vary with the
type of data you compress. If you are in doubt, just leave this setting
alone, and accept the default.
</para>
<para>
When setting this property on a <c>ZipEntry</c> that is read from an
existing zip file, calling <c>ZipFile.Save()</c> will cause the new
<c>CompressionLevel</c> to be used on the entry in the newly saved zip file.
</para>
<para>
Setting this property may have the side effect of modifying the
<c>CompressionMethod</c> property. If you set the <c>CompressionLevel</c>
to a value other than <c>None</c>, <c>CompressionMethod</c> will be set
to <c>Deflate</c>, if it was previously <c>None</c>.
</para>
</remarks>
<seealso cref="P:Ionic.Zip.ZipEntry.CompressionMethod"/>
</member>
<member name="P:Ionic.Zip.ZipEntry.CompressedSize">
<summary>
The compressed size of the file, in bytes, within the zip archive.
</summary>
<remarks>
The compressed size is computed during compression. The value is valid
AFTER reading in an existing zip file, or AFTER saving a zipfile you are
creating.
</remarks>
<seealso cref="P:Ionic.Zip.ZipEntry.UncompressedSize"/>
</member>
<member name="P:Ionic.Zip.ZipEntry.UncompressedSize">
<summary>
The size of the file, in bytes, before compression, or after extraction.
</summary>
<remarks>
This property is valid AFTER reading in an existing zip file, or AFTER saving the
<c>ZipFile</c> that contains the ZipEntry.
</remarks>
<seealso cref="P:Ionic.Zip.ZipEntry.CompressedSize"/>
</member>
<member name="P:Ionic.Zip.ZipEntry.CompressionRatio">
<summary>
The ratio of compressed size to uncompressed size of the ZipEntry.
</summary>
<remarks>
<para>
This is a ratio of the compressed size to the uncompressed size of the
entry, expressed as a double in the range of 0 to 100+. A value of 100
indicates no compression at all. It could be higher than 100 when the
compression algorithm actually inflates the data, as may occur for small
files, or uncompressible data that is encrypted.
</para>
<para>
You could format it for presentation to a user via a format string of
"{3,5:F0}%" to see it as a percentage.
</para>
<para>
If the size of the original uncompressed file is 0, (indicating a
denominator of 0) the return value will be zero.
</para>
<para>
This property is valid AFTER reading in an existing zip file, or AFTER
saving the <c>ZipFile</c> that contains the ZipEntry. You cannot know the
effect of a compression transform until you try it.
</para>
</remarks>
</member>
<member name="P:Ionic.Zip.ZipEntry.Crc">
<summary>
The 32-bit CRC (Cyclic Redundancy Check) on the contents of the ZipEntry.
</summary>
<remarks>
<para> You probably don't need to concern yourself with this. It is used
internally by DotNetZip to verify files or streams upon extraction. </para>
<para> The value is a <see href="http://en.wikipedia.org/wiki/CRC32">32-bit
CRC</see> using 0xEDB88320 for the polynomial. This is the same CRC-32 used in
PNG, MPEG-2, and other protocols and formats. It is a read-only property; when
creating a Zip archive, the CRC for each entry is set only after a call to
<c>Save()</c> on the containing ZipFile. When reading an existing zip file, the value
of this property reflects the stored CRC for the entry. </para>
</remarks>
</member>
<member name="P:Ionic.Zip.ZipEntry.IsDirectory">
<summary>
True if the entry is a directory (not a file).
This is a readonly property on the entry.
</summary>
</member>
<member name="P:Ionic.Zip.ZipEntry.UsesEncryption">
<summary>
A derived property that is <c>true</c> if the entry uses encryption.
</summary>
<remarks>
<para>
This is a readonly property on the entry. When reading a zip file,
the value for the <c>ZipEntry</c> is determined by the data read
from the zip file. After saving a ZipFile, the value of this
property for each <c>ZipEntry</c> indicates whether encryption was
actually used (which will have been true if the <see cref="P:Ionic.Zip.ZipEntry.Password"/> was set and the <see cref="P:Ionic.Zip.ZipEntry.Encryption"/> property
was something other than <see cref="F:Ionic.Zip.EncryptionAlgorithm.None"/>.
</para>
</remarks>
</member>
<member name="P:Ionic.Zip.ZipEntry.Encryption">
<summary>
Set this to specify which encryption algorithm to use for the entry when
saving it to a zip archive.
</summary>
<remarks>
<para>
Set this property in order to encrypt the entry when the <c>ZipFile</c> is
saved. When setting this property, you must also set a <see cref="P:Ionic.Zip.ZipEntry.Password"/> on the entry. If you set a value other than <see cref="F:Ionic.Zip.EncryptionAlgorithm.None"/> on this property and do not set a
<c>Password</c> then the entry will not be encrypted. The <c>ZipEntry</c>
data is encrypted as the <c>ZipFile</c> is saved, when you call <see cref="M:Ionic.Zip.ZipFile.Save"/> or one of its cousins on the containing
<c>ZipFile</c> instance. You do not need to specify the <c>Encryption</c>
when extracting entries from an archive.
</para>
<para>
The Zip specification from PKWare defines a set of encryption algorithms,
and the data formats for the zip archive that support them, and PKWare
supports those algorithms in the tools it produces. Other vendors of tools
and libraries, such as WinZip or Xceed, typically support <em>a
subset</em> of the algorithms specified by PKWare. These tools can
sometimes support additional different encryption algorithms and data
formats, not specified by PKWare. The AES Encryption specified and
supported by WinZip is the most popular example. This library supports a
subset of the complete set of algorithms specified by PKWare and other
vendors.
</para>
<para>
There is no common, ubiquitous multi-vendor standard for strong encryption
within zip files. There is broad support for so-called "traditional" Zip
encryption, sometimes called Zip 2.0 encryption, as <see href="http://www.pkware.com/documents/casestudies/APPNOTE.TXT">specified
by PKWare</see>, but this encryption is considered weak and
breakable. This library currently supports the Zip 2.0 "weak" encryption,
and also a stronger WinZip-compatible AES encryption, using either 128-bit
or 256-bit key strength. If you want DotNetZip to support an algorithm
that is not currently supported, call the author of this library and maybe
we can talk business.
</para>
<para>
The <see cref="T:Ionic.Zip.ZipFile"/> class also has a <see cref="P:Ionic.Zip.ZipFile.Encryption"/> property. In most cases you will use
<em>that</em> property when setting encryption. This property takes
precedence over any <c>Encryption</c> set on the <c>ZipFile</c> itself.
Typically, you would use the per-entry Encryption when most entries in the
zip archive use one encryption algorithm, and a few entries use a
different one. If all entries in the zip file use the same Encryption,
then it is simpler to just set this property on the ZipFile itself, when
creating a zip archive.
</para>
<para>
Some comments on updating archives: If you read a <c>ZipFile</c>, you can
modify the Encryption on an encrypted entry: you can remove encryption
from an entry that was encrypted; you can encrypt an entry that was not
encrypted previously; or, you can change the encryption algorithm. The
changes in encryption are not made permanent until you call Save() on the
<c>ZipFile</c>. To effect changes in encryption, the entry content is
streamed through several transformations, depending on the modification
the application has requested. For example if the entry is not encrypted
and the application sets <c>Encryption</c> to <c>PkzipWeak</c>, then at
the time of <c>Save()</c>, the original entry is read and decompressed,
then re-compressed and encrypted. Conversely, if the original entry is
encrypted with <c>PkzipWeak</c> encryption, and the application sets the
<c>Encryption</c> property to <c>WinZipAes128</c>, then at the time of
<c>Save()</c>, the original entry is decrypted via PKZIP encryption and
decompressed, then re-compressed and re-encrypted with AES. This all
happens automatically within the library, but it can be time-consuming for
large entries.
</para>
<para>
Additionally, when updating archives, it is not possible to change the
password when changing the encryption algorithm. To change both the
algorithm and the password, you need to Save() the zipfile twice. First
set the <c>Encryption</c> to None, then call <c>Save()</c>. Then set the
<c>Encryption</c> to the new value (not "None"), then call <c>Save()</c>
once again.
</para>
<para>
The WinZip AES encryption algorithms are not supported on the .NET Compact
Framework.
</para>
</remarks>
<example>
<para>
This example creates a zip archive that uses encryption, and then extracts
entries from the archive. When creating the zip archive, the ReadMe.txt
file is zipped without using a password or encryption. The other file
uses encryption.
</para>
<code>
// Create a zip archive with AES Encryption.
using (ZipFile zip = new ZipFile())
{
zip.AddFile("ReadMe.txt")
ZipEntry e1= zip.AddFile("2008-Regional-Sales-Report.pdf");
e1.Encryption= EncryptionAlgorithm.WinZipAes256;
e1.Password= "Top.Secret.No.Peeking!";
zip.Save("EncryptedArchive.zip");
}
// Extract a zip archive that uses AES Encryption.
// You do not need to specify the algorithm during extraction.
using (ZipFile zip = ZipFile.Read("EncryptedArchive.zip"))
{
// Specify the password that is used during extraction, for
// all entries that require a password:
zip.Password= "Top.Secret.No.Peeking!";
zip.ExtractAll("extractDirectory");
}
</code>
<code lang="VB">
' Create a zip that uses Encryption.
Using zip As New ZipFile()
zip.AddFile("ReadMe.txt")
Dim e1 as ZipEntry
e1= zip.AddFile("2008-Regional-Sales-Report.pdf")
e1.Encryption= EncryptionAlgorithm.WinZipAes256
e1.Password= "Top.Secret.No.Peeking!"
zip.Save("EncryptedArchive.zip")
End Using
' Extract a zip archive that uses AES Encryption.
' You do not need to specify the algorithm during extraction.
Using (zip as ZipFile = ZipFile.Read("EncryptedArchive.zip"))
' Specify the password that is used during extraction, for
' all entries that require a password:
zip.Password= "Top.Secret.No.Peeking!"
zip.ExtractAll("extractDirectory")
End Using
</code>
</example>
<exception cref="T:System.InvalidOperationException">
Thrown in the setter if EncryptionAlgorithm.Unsupported is specified.
</exception>
<seealso cref="P:Ionic.Zip.ZipEntry.Password">ZipEntry.Password</seealso>
<seealso cref="P:Ionic.Zip.ZipFile.Encryption">ZipFile.Encryption</seealso>
</member>
<member name="P:Ionic.Zip.ZipEntry.Password">
<summary>
The Password to be used when encrypting a <c>ZipEntry</c> upon
<c>ZipFile.Save()</c>, or when decrypting an entry upon Extract().
</summary>
<remarks>
<para>
This is a write-only property on the entry. Set this to request that the
entry be encrypted when writing the zip archive, or set it to specify the
password to be used when extracting an existing entry that is encrypted.
</para>
<para>
The password set here is implicitly used to encrypt the entry during the
<see cref="M:Ionic.Zip.ZipFile.Save"/> operation, or to decrypt during the <see cref="M:Ionic.Zip.ZipEntry.Extract"/> or <see cref="M:Ionic.Zip.ZipEntry.OpenReader"/> operation. If you set
the Password on a <c>ZipEntry</c> after calling <c>Save()</c>, there is no
effect.
</para>
<para>
Consider setting the <see cref="P:Ionic.Zip.ZipEntry.Encryption"/> property when using a
password. Answering concerns that the standard password protection
supported by all zip tools is weak, WinZip has extended the ZIP
specification with a way to use AES Encryption to protect entries in the
Zip file. Unlike the "PKZIP 2.0" encryption specified in the PKZIP
specification, <see href="http://en.wikipedia.org/wiki/Advanced_Encryption_Standard">AES
Encryption</see> uses a standard, strong, tested, encryption
algorithm. DotNetZip can create zip archives that use WinZip-compatible
AES encryption, if you set the <see cref="P:Ionic.Zip.ZipEntry.Encryption"/> property. But,
archives created that use AES encryption may not be readable by all other
tools and libraries. For example, Windows Explorer cannot read a
"compressed folder" (a zip file) that uses AES encryption, though it can
read a zip file that uses "PKZIP encryption."
</para>
<para>
The <see cref="T:Ionic.Zip.ZipFile"/> class also has a <see cref="P:Ionic.Zip.ZipFile.Password"/>
property. This property takes precedence over any password set on the
ZipFile itself. Typically, you would use the per-entry Password when most
entries in the zip archive use one password, and a few entries use a
different password. If all entries in the zip file use the same password,
then it is simpler to just set this property on the ZipFile itself,
whether creating a zip archive or extracting a zip archive.
</para>
<para>
Some comments on updating archives: If you read a <c>ZipFile</c>, you
cannot modify the password on any encrypted entry, except by extracting
the entry with the original password (if any), removing the original entry
via <see cref="M:Ionic.Zip.ZipFile.RemoveEntry(Ionic.Zip.ZipEntry)"/>, and then adding a new
entry with a new Password.
</para>
<para>
For example, suppose you read a <c>ZipFile</c>, and there is an encrypted
entry. Setting the Password property on that <c>ZipEntry</c> and then
calling <c>Save()</c> on the <c>ZipFile</c> does not update the password
on that entry in the archive. Neither is an exception thrown. Instead,
what happens during the <c>Save()</c> is the existing entry is copied
through to the new zip archive, in its original encrypted form. Upon
re-reading that archive, the entry can be decrypted with its original
password.
</para>
<para>
If you read a ZipFile, and there is an un-encrypted entry, you can set the
<c>Password</c> on the entry and then call Save() on the ZipFile, and get
encryption on that entry.
</para>
</remarks>
<example>
<para>
This example creates a zip file with two entries, and then extracts the
entries from the zip file. When creating the zip file, the two files are
added to the zip file using password protection. Each entry uses a
different password. During extraction, each file is extracted with the
appropriate password.
</para>
<code>
// create a file with encryption
using (ZipFile zip = new ZipFile())
{
ZipEntry entry;
entry= zip.AddFile("Declaration.txt");
entry.Password= "123456!";
entry = zip.AddFile("Report.xls");
entry.Password= "1Secret!";
zip.Save("EncryptedArchive.zip");
}
// extract entries that use encryption
using (ZipFile zip = ZipFile.Read("EncryptedArchive.zip"))
{
ZipEntry entry;
entry = zip["Declaration.txt"];
entry.Password = "123456!";
entry.Extract("extractDir");
entry = zip["Report.xls"];
entry.Password = "1Secret!";
entry.Extract("extractDir");
}
</code>
<code lang="VB">
Using zip As New ZipFile
Dim entry as ZipEntry
entry= zip.AddFile("Declaration.txt")
entry.Password= "123456!"
entry = zip.AddFile("Report.xls")
entry.Password= "1Secret!"
zip.Save("EncryptedArchive.zip")
End Using
' extract entries that use encryption
Using (zip as ZipFile = ZipFile.Read("EncryptedArchive.zip"))
Dim entry as ZipEntry
entry = zip("Declaration.txt")
entry.Password = "123456!"
entry.Extract("extractDir")
entry = zip("Report.xls")
entry.Password = "1Secret!"
entry.Extract("extractDir")
End Using
</code>
</example>
<seealso cref="P:Ionic.Zip.ZipEntry.Encryption"/>
<seealso cref="P:Ionic.Zip.ZipFile.Password">ZipFile.Password</seealso>
</member>
<member name="P:Ionic.Zip.ZipEntry.ExtractExistingFile">
<summary>
The action the library should take when extracting a file that already exists.
</summary>
<remarks>
<para>
This property affects the behavior of the Extract methods (one of the
<c>Extract()</c> or <c>ExtractWithPassword()</c> overloads), when
extraction would would overwrite an existing filesystem file. If you do
not set this property, the library throws an exception when extracting
an entry would overwrite an existing file.
</para>
<para>
This property has no effect when extracting to a stream, or when the file to be
extracted does not already exist.
</para>
</remarks>
<seealso cref="P:Ionic.Zip.ZipFile.ExtractExistingFile"/>
<example>
This example shows how to set the <c>ExtractExistingFile</c> property in
an <c>ExtractProgress</c> event, in response to user input. The
<c>ExtractProgress</c> event is invoked if and only if the
<c>ExtractExistingFile</c> property was previously set to
<c>ExtractExistingFileAction.InvokeExtractProgressEvent</c>.
<code lang="C#">
public static void ExtractProgress(object sender, ExtractProgressEventArgs e)
{
if (e.EventType == ZipProgressEventType.Extracting_BeforeExtractEntry)
Console.WriteLine("extract {0} ", e.CurrentEntry.FileName);
else if (e.EventType == ZipProgressEventType.Extracting_ExtractEntryWouldOverwrite)
{
ZipEntry entry = e.CurrentEntry;
string response = null;
// Ask the user if he wants overwrite the file
do
{
Console.Write("Overwrite {0} in {1} ? (y/n/C) ", entry.FileName, e.ExtractLocation);
response = Console.ReadLine();
Console.WriteLine();
} while (response != null &amp;&amp; response[0]!='Y' &amp;&amp;
response[0]!='N' &amp;&amp; response[0]!='C');
if (response[0]=='C')
e.Cancel = true;
else if (response[0]=='Y')
entry.ExtractExistingFile = ExtractExistingFileAction.OverwriteSilently;
else
entry.ExtractExistingFile= ExtractExistingFileAction.DoNotOverwrite;
}
}
</code>
</example>
</member>
<member name="P:Ionic.Zip.ZipEntry.ZipErrorAction">
<summary>
The action to take when an error is encountered while
opening or reading files as they are saved into a zip archive.
</summary>
<remarks>
<para>
Errors can occur within a call to <see cref="M:Ionic.Zip.ZipFile.Save">ZipFile.Save</see>, as the various files contained
in a ZipFile are being saved into the zip archive. During the
<c>Save</c>, DotNetZip will perform a <c>File.Open</c> on the file
associated to the ZipEntry, and then will read the entire contents of
the file as it is zipped. Either the open or the Read may fail, because
of lock conflicts or other reasons. Using this property, you can
specify the action to take when such errors occur.
</para>
<para>
Typically you will NOT set this property on individual ZipEntry
instances. Instead, you will set the <see cref="P:Ionic.Zip.ZipFile.ZipErrorAction">ZipFile.ZipErrorAction</see> property on
the ZipFile instance, before adding any entries to the
<c>ZipFile</c>. If you do this, errors encountered on behalf of any of
the entries in the ZipFile will be handled the same way.
</para>
<para>
But, if you use a <see cref="E:Ionic.Zip.ZipFile.ZipError"/> handler, you will want
to set this property on the <c>ZipEntry</c> within the handler, to
communicate back to DotNetZip what you would like to do with the
particular error.
</para>
</remarks>
<seealso cref="P:Ionic.Zip.ZipFile.ZipErrorAction"/>
<seealso cref="E:Ionic.Zip.ZipFile.ZipError"/>
</member>
<member name="P:Ionic.Zip.ZipEntry.IncludedInMostRecentSave">
<summary>
Indicates whether the entry was included in the most recent save.
</summary>
<remarks>
An entry can be excluded or skipped from a save if there is an error
opening or reading the entry.
</remarks>
<seealso cref="P:Ionic.Zip.ZipEntry.ZipErrorAction"/>
</member>
<member name="P:Ionic.Zip.ZipEntry.SetCompression">
<summary>
A callback that allows the application to specify the compression to use
for a given entry that is about to be added to the zip archive.
</summary>
<remarks>
<para>
See <see cref="P:Ionic.Zip.ZipFile.SetCompression"/>
</para>
</remarks>
</member>
<member name="P:Ionic.Zip.ZipEntry.UseUnicodeAsNecessary">
<summary>
Set to indicate whether to use UTF-8 encoding for filenames and comments.
</summary>
<remarks>
<para>
If this flag is set, the comment and filename for the entry will be
encoded with UTF-8, as described in <see href="http://www.pkware.com/documents/casestudies/APPNOTE.TXT">the Zip
specification</see>, if necessary. "Necessary" means, the filename or
entry comment (if any) cannot be reflexively encoded and decoded using the
default code page, IBM437.
</para>
<para>
Setting this flag to true is equivalent to setting <see cref="P:Ionic.Zip.ZipEntry.ProvisionalAlternateEncoding"/> to <c>System.Text.Encoding.UTF8</c>.
</para>
<para>
This flag has no effect or relation to the text encoding used within the
file itself.
</para>
</remarks>
</member>
<member name="P:Ionic.Zip.ZipEntry.ProvisionalAlternateEncoding">
<summary>
The text encoding to use for the FileName and Comment on this ZipEntry, when the
default encoding is insufficient.
</summary>
<remarks>
<para>
This is a long and odd name for a property, but there's a good reason for
it. According to <see
href="http://www.pkware.com/documents/casestudies/APPNOTE.TXT">the Zip
specification from PKWare</see>, filenames and comments for a
<c>ZipEntry</c> are encoded either with IBM437 or with UTF8. But, some
zip archiver tools or libraries do not follow the specification, and
instead encode characters using the system default code page, or an
arbitrary code page. For example, WinRAR when run on a machine in
Shanghai may encode filenames with the Chinese (Big-5) code page. This
behavior is contrary to the Zip specification, but it occurs anyway. This
property exists to support that non-compliant behavior when reading or
writing zip files.
</para>
<para>
When writing zip archives that will be read by one of these other
archivers, use this property to specify the code page to use when encoding
filenames and comments into the zip file, when the IBM437 code page will
not suffice.
</para>
<para>
Be aware that a zip file created after you've explicitly specified the
code page will not be compliant to the PKWare specification, and may not
be readable by compliant archivers. On the other hand, many archivers are
non-compliant and can read zip files created in arbitrary code pages. For
example, if you run WinRar on your PC desktop in Kyoto, Japan, you will
probably be able to open zip files that we encoded by DotNetZip in the
Shift_JIS code page.
</para>
<para>
When using an arbitrary, non-UTF8 code page for encoding, there is no
standard way for the creator (DotNetZip) to specify in the zip file which
code page has been used. DotNetZip is not able to inspect the zip file and
determine the codepage used for the entries within it. Therefore, you, the
application author, must determine that. If you read a zip file using a
codepage other than the one used to encode the zipfile, this may result in
filenames that are not legal in the filesystem, and you will get
exceptions during calls to <c>Extract()</c> methods for those entries.
Caveat Emptor.
</para>
</remarks>
</member>
<member name="P:Ionic.Zip.ZipEntry.ActualEncoding">
<summary>
The text encoding actually used for this ZipEntry.
</summary>
<remarks>
<para>
This read-only property describes the encoding used by the
<c>ZipEntry</c>. If the entry has been read in from an existing ZipFile,
then it may take the value UTF-8, if the entry is coded to specify UTF-8.
If the entry does not specify UTF-8, the typical case, then the encoding
used is whatever the application specified in the call to
<c>ZipFile.Read()</c>. If the application has used one of the overloads of
<c>ZipFile.Read()</c> that does not accept an encoding parameter, then the
encoding used is IBM437, which is the default encoding described in the
ZIP specification. </para>
<para>
If the entry is being created, then the value of ActualEncoding is taken
according to the logic described in the documentation for <see cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/>. </para>
<para>
An application might be interested in retrieving this property to see if
an entry read in from a file has used Unicode (UTF-8). </para>
</remarks>
<seealso cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/>
</member>
<member name="P:Ionic.Zip.ZipEntry.IsText">
<summary>
Indicates whether an entry is mark as a text file.
</summary>
<remarks>
<para>
The ZIP format includes a provision for specifying whether an entry in the
zip archive is a text or binary file. Such a distinction may seem
irrelevant now, but some zip tools or libraries, in particular older
PKUnzip on IBM mainframes, require this bit to be set in order to unzip
text and binary files properly. Set this property to true to set the Text
bit for an entry that represents a text file, if you want your zip files
to be readable by these older zip tools and libraries.
</para>
<para>
When writing a zip file, you must set the property before calling
<c>Save()</c> on the ZipFile.
</para>
<para>
If you are not having compatibility problems with zip archives, you can
safely ignore this property.
</para>
</remarks>
<example>
<code>
using (var zip = new ZipFile())
{
var e = zip.UpdateFile("Descriptions.txt", "");
e.IsText = true;
zip.Save(zipPath);
}
</code>
<code lang="VB">
Using zip As New ZipFile
Dim e2 as ZipEntry = zip.AddFile("Descriptions.txt", "")
e.IsText= True
zip.Save(zipPath)
End Using
</code>
</example>
</member>
<member name="P:Ionic.Zip.ZipEntry.AttributesIndicateDirectory">
<summary>
True if the referenced entry is a directory.
</summary>
</member>
<member name="P:Ionic.Zip.ZipEntry.Info">
<summary>
Provides a human-readable string with information about the ZipEntry.
</summary>
</member>
<member name="T:Ionic.Zip.ZipEntryTimestamp">
<summary>
An enum that specifies the type of timestamp available on the ZipEntry.
</summary>
<remarks>
<para>
The last modified time of a file can be stored in multiple ways in
a zip file, and they are not mutually exclusive:
</para>
<list type="bullet">
<item>
In the so-called "DOS" format, which has a 2-second precision. Values
are rounded to the nearest even second. For example, if the time on the
file is 12:34:43, then it will be stored as 12:34:44. This first value
is accessible via the <c>LastModified</c> property. This value is always
present in the metadata for each zip entry. In some cases the value is
invalid, or zero.
</item>
<item>
In the so-called "Windows" or "NTFS" format, as an 8-byte integer
quantity expressed as the number of 1/10 milliseconds (in other words
the number of 100 nanosecond units) since January 1, 1601 (UTC). This
format is how Windows represents file times. This time is accessible
via the <c>ModifiedTime</c> property.
</item>
<item>
In the "Unix" format, a 4-byte quantity specifying the number of seconds since
January 1, 1970 UTC.
</item>
<item>
In an older format, now deprecated but still used by some current
tools. This format is also a 4-byte quantity specifying the number of
seconds since January 1, 1970 UTC.
</item>
</list>
<para>
This bit field describes which of the formats were found in a <c>ZipEntry</c> that was read.
</para>
</remarks>
</member>
<member name="F:Ionic.Zip.ZipEntryTimestamp.None">
<summary>
Default value.
</summary>
</member>
<member name="F:Ionic.Zip.ZipEntryTimestamp.DOS">
<summary>
A DOS timestamp with 2-second precision.
</summary>
</member>
<member name="F:Ionic.Zip.ZipEntryTimestamp.Windows">
<summary>
A Windows timestamp with 100-ns precision.
</summary>
</member>
<member name="F:Ionic.Zip.ZipEntryTimestamp.Unix">
<summary>
A Unix timestamp with 1-second precision.
</summary>
</member>
<member name="F:Ionic.Zip.ZipEntryTimestamp.InfoZip1">
<summary>
A Unix timestamp with 1-second precision, stored in InfoZip v1 format. This
format is outdated and is supported for reading archives only.
</summary>
</member>
<member name="T:Ionic.Zip.CompressionMethod">
<summary>
The method of compression to use for a particular ZipEntry.
</summary>
<remarks>
<see
href="http://www.pkware.com/documents/casestudies/APPNOTE.TXT">PKWare's
ZIP Specification</see> describes a number of distinct
cmopression methods that can be used within a zip file. The
standard DEFLATE method is the only one supported by this
library. Imploding, Deflate64, LZMA, and others are not
supported by this library, either for reading or writing zip
archives.
</remarks>
</member>
<member name="F:Ionic.Zip.CompressionMethod.None">
<summary>
No compression at all. For COM environments, the value is 0 (zero).
</summary>
</member>
<member name="F:Ionic.Zip.CompressionMethod.Deflate">
<summary>
DEFLATE cmopression, as described in <see
href="http://www.ietf.org/rfc/rfc1951.txt">IETF RFC
1951</see>. This is the "normal" compression used in zip
files. For COM environments, the value is 8.
</summary>
</member>
<member name="T:Ionic.Zip.ZipCrypto">
<summary>
This class implements the "traditional" or "classic" PKZip encryption,
which today is considered to be weak. On the other hand it is
ubiquitous. This class is intended for use only by the DotNetZip library.
</summary>
<remarks>
Most uses of the DotNetZip library will not involve direct calls into the
ZipCrypto class. Instead, the ZipCrypto class is instantiated and used by
the ZipEntry() class when encryption or decryption on an entry is employed.
If for some reason you really wanted to use a weak encryption algorithm
in some other application, you might use this library. But you would be much
better off using one of the built-in strong encryption libraries in the
.NET Framework, like the AES algorithm or SHA.
</remarks>
</member>
<member name="M:Ionic.Zip.ZipCrypto.#ctor">
<summary>
The default constructor for ZipCrypto.
</summary>
<remarks>
This class is intended for internal use by the library only. It's probably not useful to you. Seriously.
Stop reading this documentation. It's a waste of your time. Go do something else.
Check the football scores. Go get an ice cream with a friend. Seriously.
</remarks>
</member>
<member name="M:Ionic.Zip.ZipCrypto.DecryptMessage(System.Byte[],System.Int32)">
<summary>
Call this method on a cipher text to render the plaintext. You must
first initialize the cipher with a call to InitCipher.
</summary>
<example>
<code>
var cipher = new ZipCrypto();
cipher.InitCipher(Password);
// Decrypt the header. This has a side effect of "further initializing the
// encryption keys" in the traditional zip encryption.
byte[] DecryptedMessage = cipher.DecryptMessage(EncryptedMessage);
</code>
</example>
<param name="cipherText">The encrypted buffer.</param>
<param name="length">
The number of bytes to encrypt.
Should be less than or equal to CipherText.Length.
</param>
<returns>The plaintext.</returns>
</member>
<member name="M:Ionic.Zip.ZipCrypto.EncryptMessage(System.Byte[],System.Int32)">
<summary>
This is the converse of DecryptMessage. It encrypts the plaintext
and produces a ciphertext.
</summary>
<param name="plaintext">The plain text buffer.</param>
<param name="length">
The number of bytes to encrypt.
Should be less than or equal to PlainText.Length.
</param>
<returns>The ciphertext.</returns>
</member>
<member name="M:Ionic.Zip.ZipCrypto.InitCipher(System.String)">
<summary>
This initializes the cipher with the given password.
See AppNote.txt for details.
</summary>
<param name="passphrase">The passphrase for encrypting or decrypting with this cipher.
</param>
<remarks>
<code>
Step 1 - Initializing the encryption keys
-----------------------------------------
Start with these keys:
Key(0) := 305419896 (0x12345678)
Key(1) := 591751049 (0x23456789)
Key(2) := 878082192 (0x34567890)
Then, initialize the keys with a password:
loop for i from 0 to length(password)-1
update_keys(password(i))
end loop
Where update_keys() is defined as:
update_keys(char):
Key(0) := crc32(key(0),char)
Key(1) := Key(1) + (Key(0) bitwiseAND 000000ffH)
Key(1) := Key(1) * 134775813 + 1
Key(2) := crc32(key(2),key(1) rightshift 24)
end update_keys
Where crc32(old_crc,char) is a routine that given a CRC value and a
character, returns an updated CRC value after applying the CRC-32
algorithm described elsewhere in this document.
</code>
<para>
After the keys are initialized, then you can use the cipher to encrypt
the plaintext.
</para>
<para>
Essentially we encrypt the password with the keys, then discard the
ciphertext for the password. This initializes the keys for later use.
</para>
</remarks>
</member>
<member name="P:Ionic.Zip.ZipCrypto.MagicByte">
<summary>
From AppNote.txt:
unsigned char decrypt_byte()
local unsigned short temp
temp :=- Key(2) | 2
decrypt_byte := (temp * (temp ^ 1)) bitshift-right 8
end decrypt_byte
</summary>
</member>
<member name="T:Ionic.Zip.ZipCipherStream">
<summary>
A Stream for reading and concurrently decrypting data from a zip file,
or for writing and concurrently encrypting data to a zip file.
</summary>
</member>
<member name="M:Ionic.Zip.ZipCipherStream.#ctor(System.IO.Stream,Ionic.Zip.ZipCrypto,Ionic.Zip.CryptoMode)">
<summary>
The constructor.
</summary>
<param name="s">The underlying stream</param>
<param name="mode">To either encrypt or decrypt.</param>
<param name="cipher">The pre-initialized ZipCrypto object.</param>
</member>
<member name="T:Ionic.Zip.WinZipAesCrypto">
<summary>
This is a helper class supporting WinZip AES encryption.
This class is intended for use only by the DotNetZip library.
</summary>
<remarks>
Most uses of the DotNetZip library will not involve direct calls into the
WinZipAesCrypto class. Instead, the WinZipAesCrypto class is instantiated and
used by the ZipEntry() class when WinZip AES encryption or decryption on an
entry is employed.
</remarks>
</member>
<member name="T:Ionic.Zip.WinZipAesCipherStream">
<summary>
A stream that encrypts as it writes, or decrypts as it reads. The Crypto is AES in
CTR (counter) mode, which is
compatible with the AES encryption employed by WinZip 12.0.
</summary>
</member>
<member name="M:Ionic.Zip.WinZipAesCipherStream.#ctor(System.IO.Stream,Ionic.Zip.WinZipAesCrypto,System.Int64,Ionic.Zip.CryptoMode)">
<summary>
The constructor.
</summary>
<param name="s">The underlying stream</param>
<param name="mode">To either encrypt or decrypt.</param>
<param name="cryptoParams">The pre-initialized WinZipAesCrypto object.</param>
<param name="length">The maximum number of bytes to read from the stream.</param>
</member>
<member name="M:Ionic.Zip.WinZipAesCipherStream.Close">
<summary>
Close the stream.
</summary>
</member>
<member name="M:Ionic.Zip.WinZipAesCipherStream.Flush">
<summary>
Flush the content in the stream.
</summary>
</member>
<member name="M:Ionic.Zip.WinZipAesCipherStream.Seek(System.Int64,System.IO.SeekOrigin)">
<summary>
This method throws a NotImplementedException.
</summary>
</member>
<member name="M:Ionic.Zip.WinZipAesCipherStream.SetLength(System.Int64)">
<summary>
This method throws a NotImplementedException.
</summary>
</member>
<member name="P:Ionic.Zip.WinZipAesCipherStream.FinalAuthentication">
<summary>
Returns the final HMAC-SHA1-80 for the data that was encrypted.
</summary>
</member>
<member name="P:Ionic.Zip.WinZipAesCipherStream.CanRead">
<summary>
Returns true if the stream can be read.
</summary>
</member>
<member name="P:Ionic.Zip.WinZipAesCipherStream.CanSeek">
<summary>
Always returns false.
</summary>
</member>
<member name="P:Ionic.Zip.WinZipAesCipherStream.CanWrite">
<summary>
Returns true if the CryptoMode is Encrypt.
</summary>
</member>
<member name="P:Ionic.Zip.WinZipAesCipherStream.Length">
<summary>
Getting this property throws a NotImplementedException.
</summary>
</member>
<member name="P:Ionic.Zip.WinZipAesCipherStream.Position">
<summary>
Getting or Setting this property throws a NotImplementedException.
</summary>
</member>
<member name="T:Ionic.LogicalConjunction">
<summary>
Enumerates the options for a logical conjunction. This enum is intended for use
internally by the FileSelector class.
</summary>
</member>
<member name="T:Ionic.EnumUtil">
<summary>
Summary description for EnumUtil.
</summary>
</member>
<member name="M:Ionic.EnumUtil.GetDescription(System.Enum)">
<summary>
Returns the value of the DescriptionAttribute if the specified Enum value has one.
If not, returns the ToString() representation of the Enum value.
</summary>
<param name="value">The Enum to get the description for</param>
<returns></returns>
</member>
<member name="M:Ionic.EnumUtil.Parse(System.Type,System.String)">
<summary>
Converts the string representation of the name or numeric value of one or more
enumerated constants to an equivalent enumerated object.
Note: use the DescriptionAttribute on enum values to enable this.
</summary>
<param name="enumType">The System.Type of the enumeration.</param>
<param name="stringRepresentation">A string containing the name or value to convert.</param>
<returns></returns>
</member>
<member name="M:Ionic.EnumUtil.Parse(System.Type,System.String,System.Boolean)">
<summary>
Converts the string representation of the name or numeric value of one or more
enumerated constants to an equivalent enumerated object.
A parameter specified whether the operation is case-sensitive.
Note: use the DescriptionAttribute on enum values to enable this.
</summary>
<param name="enumType">The System.Type of the enumeration.</param>
<param name="stringRepresentation">A string containing the name or value to convert.</param>
<param name="ignoreCase">Whether the operation is case-sensitive or not.</param>
<returns></returns>
</member>
<member name="T:Ionic.Zip.ZipInputStream">
<summary>
Provides a stream metaphor for reading zip files.
</summary>
<remarks>
<para>
This class provides an alternative programming model for reading zip files to
the one enabled by the <see cref="T:Ionic.Zip.ZipFile"/> class. Use this when reading zip
files, as an alternative to the <see cref="T:Ionic.Zip.ZipFile"/> class, when you would
like to use a Stream class to read the file.
</para>
<para>
Some application designs require a readable stream for input. This stream can
be used to read a zip file, and extract entries.
</para>
<para>
Both the <c>ZipInputStream</c> class and the <c>ZipFile</c> class can be used
to read and extract zip files. Both of them support many of the common zip
features, including Unicode, different compression levels, and ZIP64. The
programming models differ. For example, when extracting entries via calls to
the <c>GetNextEntry()</c> and <c>Read()</c> methods on the
<c>ZipInputStream</c> class, the caller is responsible for creating the file,
writing the bytes into the file, setting the attributes on the file, and
setting the created, last modified, and last accessed timestamps on the
file. All of these things are done automatically by a call to <see cref="M:Ionic.Zip.ZipEntry.Extract">ZipEntry.Extract()</see>. For this reason, the
<c>ZipInputStream</c> is generally recommended for when your application wants
to extract the data, without storing that data into a file.
</para>
<para>
Aside from the obvious differences in programming model, there are some
differences in capability between the <c>ZipFile</c> class and the
<c>ZipInputStream</c> class.
</para>
<list type="bullet">
<item>
<c>ZipFile</c> can be used to create or update zip files, or read and
extract zip files. <c>ZipInputStream</c> can be used only to read and
extract zip files. If you want to use a stream to create zip files, check
out the <see cref="T:Ionic.Zip.ZipOutputStream"/>.
</item>
<item>
<c>ZipInputStream</c> cannot read segmented or spanned
zip files.
</item>
<item>
<c>ZipInputStream</c> will not read Zip file comments.
</item>
<item>
When reading larger files, <c>ZipInputStream</c> will always underperform
<c>ZipFile</c>. This is because the <c>ZipInputStream</c> does a full scan on the
zip file, while the <c>ZipFile</c> class reads the central directory of the
zip file.
</item>
</list>
</remarks>
</member>
<member name="M:Ionic.Zip.ZipInputStream.#ctor(System.IO.Stream)">
<summary>
Create a <c>ZipInputStream</c>, wrapping it around an existing stream.
</summary>
<remarks>
<para>
While the <see cref="T:Ionic.Zip.ZipFile"/> class is generally easier
to use, this class provides an alternative to those
applications that want to read from a zipfile directly,
using a <see cref="T:System.IO.Stream"/>.
</para>
<para>
Both the <c>ZipInputStream</c> class and the <c>ZipFile</c> class can be used
to read and extract zip files. Both of them support many of the common zip
features, including Unicode, different compression levels, and ZIP64. The
programming models differ. For example, when extracting entries via calls to
the <c>GetNextEntry()</c> and <c>Read()</c> methods on the
<c>ZipInputStream</c> class, the caller is responsible for creating the file,
writing the bytes into the file, setting the attributes on the file, and
setting the created, last modified, and last accessed timestamps on the
file. All of these things are done automatically by a call to <see cref="M:Ionic.Zip.ZipEntry.Extract">ZipEntry.Extract()</see>. For this reason, the
<c>ZipInputStream</c> is generally recommended for when your application wants
to extract the data, without storing that data into a file.
</para>
<para>
Aside from the obvious differences in programming model, there are some
differences in capability between the <c>ZipFile</c> class and the
<c>ZipInputStream</c> class.
</para>
<list type="bullet">
<item>
<c>ZipFile</c> can be used to create or update zip files, or read and extract
zip files. <c>ZipInputStream</c> can be used only to read and extract zip
files. If you want to use a stream to create zip files, check out the <see cref="T:Ionic.Zip.ZipOutputStream"/>.
</item>
<item>
<c>ZipInputStream</c> cannot read segmented or spanned
zip files.
</item>
<item>
<c>ZipInputStream</c> will not read Zip file comments.
</item>
<item>
When reading larger files, <c>ZipInputStream</c> will always underperform
<c>ZipFile</c>. This is because the <c>ZipInputStream</c> does a full scan on the
zip file, while the <c>ZipFile</c> class reads the central directory of the
zip file.
</item>
</list>
</remarks>
<param name="stream">
The stream to read. It must be readable. This stream will be closed at
the time the <c>ZipInputStream</c> is closed.
</param>
<example>
This example shows how to read a zip file, and extract entries, using the
<c>ZipInputStream</c> class.
<code lang="C#">
private void Unzip()
{
byte[] buffer= new byte[2048];
int n;
using (var raw = File.Open(inputFileName, FileMode.Open, FileAccess.Read))
{
using (var input= new ZipInputStream(raw))
{
ZipEntry e;
while (( e = input.GetNextEntry()) != null)
{
if (e.IsDirectory) continue;
string outputPath = Path.Combine(extractDir, e.FileName);
using (var output = File.Open(outputPath, FileMode.Create, FileAccess.ReadWrite))
{
while ((n= input.Read(buffer, 0, buffer.Length)) &gt; 0)
{
output.Write(buffer,0,n);
}
}
}
}
}
}
</code>
<code lang="VB">
Private Sub UnZip()
Dim inputFileName As String = "MyArchive.zip"
Dim extractDir As String = "extract"
Dim buffer As Byte() = New Byte(2048) {}
Using raw As FileStream = File.Open(inputFileName, FileMode.Open, FileAccess.Read)
Using input As ZipInputStream = New ZipInputStream(raw)
Dim e As ZipEntry
Do While (Not e = input.GetNextEntry Is Nothing)
If Not e.IsDirectory Then
Using output As FileStream = File.Open(Path.Combine(extractDir, e.FileName), _
FileMode.Create, FileAccess.ReadWrite)
Dim n As Integer
Do While (n = input.Read(buffer, 0, buffer.Length) &gt; 0)
output.Write(buffer, 0, n)
Loop
End Using
End If
Loop
End Using
End Using
End Sub
</code>
</example>
</member>
<member name="M:Ionic.Zip.ZipInputStream.#ctor(System.String)">
<summary>
Create a <c>ZipInputStream</c>, given the name of an existing zip file.
</summary>
<remarks>
<para>
This constructor opens a <c>FileStream</c> for the given zipfile, and
wraps a <c>ZipInputStream</c> around that. See the documentation for the
<see cref="M:Ionic.Zip.ZipInputStream.#ctor(System.IO.Stream)"/> constructor for full details.
</para>
<para>
While the <see cref="T:Ionic.Zip.ZipFile"/> class is generally easier
to use, this class provides an alternative to those
applications that want to read from a zipfile directly,
using a <see cref="T:System.IO.Stream"/>.
</para>
</remarks>
<param name="fileName">
The name of the filesystem file to read.
</param>
<example>
This example shows how to read a zip file, and extract entries, using the
<c>ZipInputStream</c> class.
<code lang="C#">
private void Unzip()
{
byte[] buffer= new byte[2048];
int n;
using (var input= new ZipInputStream(inputFileName))
{
ZipEntry e;
while (( e = input.GetNextEntry()) != null)
{
if (e.IsDirectory) continue;
string outputPath = Path.Combine(extractDir, e.FileName);
using (var output = File.Open(outputPath, FileMode.Create, FileAccess.ReadWrite))
{
while ((n= input.Read(buffer, 0, buffer.Length)) &gt; 0)
{
output.Write(buffer,0,n);
}
}
}
}
}
</code>
<code lang="VB">
Private Sub UnZip()
Dim inputFileName As String = "MyArchive.zip"
Dim extractDir As String = "extract"
Dim buffer As Byte() = New Byte(2048) {}
Using input As ZipInputStream = New ZipInputStream(inputFileName)
Dim e As ZipEntry
Do While (Not e = input.GetNextEntry Is Nothing)
If Not e.IsDirectory Then
Using output As FileStream = File.Open(Path.Combine(extractDir, e.FileName), _
FileMode.Create, FileAccess.ReadWrite)
Dim n As Integer
Do While (n = input.Read(buffer, 0, buffer.Length) &gt; 0)
output.Write(buffer, 0, n)
Loop
End Using
End If
Loop
End Using
End Sub
</code>
</example>
</member>
<member name="M:Ionic.Zip.ZipInputStream.#ctor(System.IO.Stream,System.Boolean)">
<summary>
Create a <c>ZipInputStream</c>, explicitly specifying whether to
keep the underlying stream open.
</summary>
<remarks>
See the documentation for the <see cref="M:Ionic.Zip.ZipInputStream.#ctor(System.IO.Stream)">ZipInputStream(Stream)</see>
constructor for a discussion of the class, and an example of how to use the class.
</remarks>
<param name="stream">
The stream to read from. It must be readable.
</param>
<param name="leaveOpen">
true if the application would like the stream
to remain open after the <c>ZipInputStream</c> has been closed.
</param>
</member>
<member name="M:Ionic.Zip.ZipInputStream.ToString">
<summary>Provides a string representation of the instance.</summary>
<remarks>
<para>
This can be useful for debugging purposes.
</para>
</remarks>
<returns>a string representation of the instance.</returns>
</member>
<member name="M:Ionic.Zip.ZipInputStream.Read(System.Byte[],System.Int32,System.Int32)">
<summary>
Read the data from the stream into the buffer.
</summary>
<remarks>
<para>
The data for the zipentry will be decrypted and uncompressed, as
necessary, before being copied into the buffer.
</para>
<para>
You must set the <see cref="P:Ionic.Zip.ZipInputStream.Password"/> property before calling
<c>Read()</c> the first time for an encrypted entry. To determine if an
entry is encrypted and requires a password, check the <see cref="P:Ionic.Zip.ZipEntry.Encryption">ZipEntry.Encryption</see> property.
</para>
</remarks>
<param name="buffer">The buffer to hold the data read from the stream.</param>
<param name="offset">the offset within the buffer to copy the first byte read.</param>
<param name="count">the number of bytes to read.</param>
<returns>the number of bytes read, after decryption and decompression.</returns>
</member>
<member name="M:Ionic.Zip.ZipInputStream.GetNextEntry">
<summary>
Read the next entry from the zip file.
</summary>
<remarks>
<para>
Call this method just before calling <see cref="M:Ionic.Zip.ZipInputStream.Read(System.Byte[],System.Int32,System.Int32)"/>,
to position the pointer in the zip file to the next entry that can be
read. Subsequent calls to <c>Read()</c>, will decrypt and decompress the
data in the zip file, until <c>Read()</c> returns 0.
</para>
<para>
Each time you call <c>GetNextEntry()</c>, the pointer in the wrapped
stream is moved to the next entry in the zip file. If you call <see cref="M:Ionic.Zip.ZipInputStream.Seek(System.Int64,System.IO.SeekOrigin)"/>, and thus re-position the pointer within
the file, you will need to call <c>GetNextEntry()</c> again, to insure
that the file pointer is positioned at the beginning of a zip entry.
</para>
<para>
This method returns the <c>ZipEntry</c>. Using a stream approach, you will
read the raw bytes for an entry in a zip file via calls to <c>Read()</c>.
Alternatively, you can extract an entry into a file, or a stream, by
calling <see cref="M:Ionic.Zip.ZipEntry.Extract"/>, or one of its siblings.
</para>
</remarks>
<returns>
The <c>ZipEntry</c> read. Returns null (or Nothing in VB) if there are no more
entries in the zip file.
</returns>
</member>
<member name="M:Ionic.Zip.ZipInputStream.Dispose(System.Boolean)">
<summary>
Dispose the stream.
</summary>
<remarks>
<para>
This method disposes the ZipInputStream. It may also close the underlying
stream, depending on which constructor was used.
</para>
<para>
Typically the application will call <c>Dispose()</c> implicitly, via a <c>using</c>
statement in C#, or a <c>Using</c> statement in VB.
</para>
</remarks>
</member>
<member name="M:Ionic.Zip.ZipInputStream.Flush">
<summary>
This is a no-op.
</summary>
</member>
<member name="M:Ionic.Zip.ZipInputStream.Write(System.Byte[],System.Int32,System.Int32)">
<summary>
This method always throws a NotSupportedException.
</summary>
<param name="buffer">ignored</param>
<param name="offset">ignored</param>
<param name="count">ignored</param>
</member>
<member name="M:Ionic.Zip.ZipInputStream.Seek(System.Int64,System.IO.SeekOrigin)">
<summary>
This method seeks in the underlying stream.
</summary>
<remarks>
<para>
Call this method if you want to seek around within the zip file for random access.
</para>
<para>
Applications can intermix calls to <c>Seek()</c> with calls to <see cref="M:Ionic.Zip.ZipInputStream.GetNextEntry"/>. After a call to <c>Seek()</c>,
<c>GetNextEntry()</c> will get the next <c>ZipEntry</c> that falls after
the current position in the input stream. You're on your own for finding
out just where to seek in the stream, to get to the various entries.
</para>
</remarks>
<param name="offset">the offset point to seek to</param>
<param name="origin">the reference point from which to seek</param>
<returns>The new position</returns>
</member>
<member name="M:Ionic.Zip.ZipInputStream.SetLength(System.Int64)">
<summary>
This method always throws a NotSupportedException.
</summary>
<param name="value">ignored</param>
</member>
<member name="P:Ionic.Zip.ZipInputStream.ProvisionalAlternateEncoding">
<summary>
The text encoding to use when reading entries into the zip archive, for
those entries whose filenames or comments cannot be encoded with the
default (IBM437) encoding.
</summary>
<remarks>
<para>
In <see href="http://www.pkware.com/documents/casestudies/APPNOTE.TXT">its
zip specification</see>, PKWare describes two options for encoding
filenames and comments: using IBM437 or UTF-8. But, some archiving tools
or libraries do not follow the specification, and instead encode
characters using the system default code page. For example, WinRAR when
run on a machine in Shanghai may encode filenames with the Big-5 Chinese
(950) code page. This behavior is contrary to the Zip specification, but
it occurs anyway.
</para>
<para>
When using DotNetZip to read zip archives that use something other than
UTF-8 or IBM437, set this property to specify the code page to use when
reading encoded filenames and comments for each <c>ZipEntry</c> in the zip
file.
</para>
<para>
This property is "provisional". When the entry in the zip archive is not
explicitly marked as using UTF-8, then IBM437 is used to decode filenames
and comments. If a loss of data would result from using IBM436 -
specifically when encoding and decoding is not reflexive - the codepage
specified here is used. It is possible, therefore, to have a given entry
with a <c>Comment</c> encoded in IBM437 and a <c>FileName</c> encoded with
the specified "provisional" codepage.
</para>
<para>
When a zip file uses an arbitrary, non-UTF8 code page for encoding, there
is no standard way for the reader application - whether DotNetZip, WinZip,
WinRar, or something else - to know which codepage has been used for the
entries. Readers of zip files are not able to inspect the zip file and
determine the codepage that was used for the entries contained within it.
It is left to the application or user to determine the necessary codepage
when reading zip files encoded this way. If you use an incorrect codepage
when reading a zipfile, you will get entries with filenames that are
incorrect, and the incorrect filenames may even contain characters that
are not legal for use within filenames in Windows. Extracting entries with
illegal characters in the filenames will lead to exceptions. It's too bad,
but this is just the way things are with code pages in zip files. Caveat
Emptor.
</para>
</remarks>
</member>
<member name="P:Ionic.Zip.ZipInputStream.CodecBufferSize">
<summary>
Size of the work buffer to use for the ZLIB codec during decompression.
</summary>
<remarks>
Setting this affects the performance and memory efficiency of compression
and decompression. For larger files, setting this to a larger size may
improve performance, but the exact numbers vary depending on available
memory, and a bunch of other variables. I don't have good firm
recommendations on how to set it. You'll have to test it yourself. Or
just leave it alone and accept the default.
</remarks>
</member>
<member name="P:Ionic.Zip.ZipInputStream.Password">
<summary>
Sets the password to be used on the <c>ZipInputStream</c> instance.
</summary>
<remarks>
<para>
When reading a zip archive, this password is used to read and decrypt the
entries that are encrypted within the zip file. When entries within a zip
file use different passwords, set the appropriate password for the entry
before the first call to <c>Read()</c> for each entry.
</para>
<para>
When reading an entry that is not encrypted, the value of this property is
ignored.
</para>
</remarks>
<example>
This example uses the ZipInputStream to read and extract entries from a
zip file, using a potentially different password for each entry.
<code lang="C#">
byte[] buffer= new byte[2048];
int n;
using (var raw = File.Open(_inputFileName, FileMode.Open, FileAccess.Read ))
{
using (var input= new ZipInputStream(raw))
{
ZipEntry e;
while (( e = input.GetNextEntry()) != null)
{
input.Password = PasswordForEntry(e.FileName);
if (e.IsDirectory) continue;
string outputPath = Path.Combine(_extractDir, e.FileName);
using (var output = File.Open(outputPath, FileMode.Create, FileAccess.ReadWrite))
{
while ((n= input.Read(buffer,0,buffer.Length)) > 0)
{
output.Write(buffer,0,n);
}
}
}
}
}
</code>
</example>
</member>
<member name="P:Ionic.Zip.ZipInputStream.CanRead">
<summary>
Always returns true.
</summary>
</member>
<member name="P:Ionic.Zip.ZipInputStream.CanSeek">
<summary>
Returns the value of <c>CanSeek</c> for the underlying (wrapped) stream.
</summary>
</member>
<member name="P:Ionic.Zip.ZipInputStream.CanWrite">
<summary>
Always returns false.
</summary>
</member>
<member name="P:Ionic.Zip.ZipInputStream.Length">
<summary>
Returns the length of the underlying stream.
</summary>
</member>
<member name="P:Ionic.Zip.ZipInputStream.Position">
<summary>
Gets or sets the position of the underlying stream.
</summary>
<remarks>
Setting the position is equivalent to calling <c>Seek(value, SeekOrigin.Begin)</c>.
</remarks>
</member>
</members>
</doc>
Reference in New Issue View Git Blame Copy Permalink