您最多选择25个主题
主题必须以中文或者字母或数字开头，可以包含连字符 (-)，并且长度不得超过35个字符
18132 行
870 KiB
18132 行
870 KiB
<?xml version="1.0"?>
|
|
<doc>
|
|
<assembly>
|
|
<name>Ionic.Zip</name>
|
|
</assembly>
|
|
<members>
|
|
<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="T:Ionic.Zip.ZipOutputStream">
|
|
<summary>
|
|
Provides a stream metaphor for generating zip files.
|
|
</summary>
|
|
|
|
<remarks>
|
|
<para>
|
|
This class writes zip files, as defined in the <see href="http://www.pkware.com/documents/casestudies/APPNOTE.TXT">specification
|
|
for zip files described by PKWare</see>. 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.
|
|
</para>
|
|
|
|
<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
|
|
<c>Stream</c> type to write the zip file.
|
|
</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. They provide
|
|
very similar performance when creating zip files.
|
|
</para>
|
|
|
|
<para>
|
|
The <c>ZipFile</c> class is generally easier to use than
|
|
<c>ZipOutputStream</c> and should be considered a higher-level interface. 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 use
|
|
only when your application emits arbitrary data, not necessarily data from a
|
|
filesystem file, directly into a zip file, and does so using a <c>Stream</c>
|
|
metaphor.
|
|
</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>
|
|
|
|
<para>
|
|
Be aware that the <c>ZipOutputStream</c> class implements the <see cref="T:System.IDisposable"/> interface. In order for
|
|
<c>ZipOutputStream</c> to produce a valid zip file, you use use it within
|
|
a using clause (<c>Using</c> in VB), or call the <c>Dispose()</c> method
|
|
explicitly. See the examples for how to employ a using clause.
|
|
</para>
|
|
|
|
<para>
|
|
Also, a note regarding compression performance: 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>
|
|
</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>
|
|
|
|
</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)) > 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) > 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)) > 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) > 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="disposing">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.CompressionMethod">
|
|
<summary>
|
|
The compression method used on each entry added to the ZipOutputStream.
|
|
</summary>
|
|
</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 specification does not describe how to indicate the encoding used
|
|
on a comment string. Many "compliant" zip tools and libraries use
|
|
IBM437 as the code page for comments; DotNetZip, too, follows that
|
|
practice. On the other hand, there are situations where you want a
|
|
Comment to be encoded with something else, for example using code page
|
|
950 "Big-5 Chinese". To fill that need, DotNetZip will encode the
|
|
comment following the same procedure it follows for encoding
|
|
filenames: (a) if <see cref="P:Ionic.Zip.ZipOutputStream.AlternateEncodingUsage"/> is
|
|
<c>Never</c>, it uses the default encoding (IBM437). (b) if <see cref="P:Ionic.Zip.ZipOutputStream.AlternateEncodingUsage"/> is <c>Always</c>, it always uses the
|
|
alternate encoding (<see cref="P:Ionic.Zip.ZipOutputStream.AlternateEncoding"/>). (c) if <see cref="P:Ionic.Zip.ZipOutputStream.AlternateEncodingUsage"/> is <c>AsNecessary</c>, it uses the
|
|
alternate encoding only if the default encoding is not sufficient for
|
|
encoding the comment - in other words if decoding the result does not
|
|
produce the original string. This decision is taken at the time of
|
|
the call to <c>ZipFile.Save()</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.AlternateEncoding">
|
|
<summary>
|
|
A Text Encoding to use when encoding the filenames and comments for
|
|
all the ZipEntry items, during a ZipFile.Save() operation.
|
|
</summary>
|
|
<remarks>
|
|
<para>
|
|
Whether the encoding specified here is used during the save depends
|
|
on <see cref="P:Ionic.Zip.ZipOutputStream.AlternateEncodingUsage"/>.
|
|
</para>
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.Zip.ZipOutputStream.AlternateEncodingUsage">
|
|
<summary>
|
|
A flag that tells if and when this instance should apply
|
|
AlternateEncoding to encode the filenames and comments associated to
|
|
of ZipEntry objects contained within this instance.
|
|
</summary>
|
|
</member>
|
|
<member name="P:Ionic.Zip.ZipOutputStream.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="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, when
|
|
the <c>CompressionMethod</c> is Deflate, and 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.ParallelDeflateMaxBufferPairs">
|
|
<summary>
|
|
The maximum number of buffer pairs to use when performing
|
|
parallel compression.
|
|
</summary>
|
|
|
|
<remarks>
|
|
<para>
|
|
This property sets an upper limit on the number of memory
|
|
buffer pairs to create when performing parallel
|
|
compression. The implementation of the parallel
|
|
compression stream allocates multiple buffers to
|
|
facilitate parallel compression. As each buffer fills up,
|
|
the stream uses <see cref="M:System.Threading.ThreadPool.QueueUserWorkItem(System.Threading.WaitCallback)">
|
|
ThreadPool.QueueUserWorkItem()</see> to compress those
|
|
buffers in a background threadpool thread. After a buffer
|
|
is compressed, it is re-ordered and written to the output
|
|
stream.
|
|
</para>
|
|
|
|
<para>
|
|
A higher number of buffer pairs enables a higher degree of
|
|
parallelism, which tends to increase the speed of compression on
|
|
multi-cpu computers. On the other hand, a higher number of buffer
|
|
pairs also implies a larger memory consumption, more active worker
|
|
threads, and a higher cpu utilization for any compression. This
|
|
property enables the application to limit its memory consumption and
|
|
CPU utilization behavior depending on requirements.
|
|
</para>
|
|
|
|
<para>
|
|
For each compression "task" that occurs in parallel, there are 2
|
|
buffers allocated: one for input and one for output. This property
|
|
sets a limit for the number of pairs. The total amount of storage
|
|
space allocated for buffering will then be (N*S*2), where N is the
|
|
number of buffer pairs, S is the size of each buffer (<see cref="P:Ionic.Zip.ZipOutputStream.CodecBufferSize"/>). By default, DotNetZip allocates 4 buffer
|
|
pairs per CPU core, so if your machine has 4 cores, and you retain
|
|
the default buffer size of 128k, then the
|
|
ParallelDeflateOutputStream will use 4 * 4 * 2 * 128kb of buffer
|
|
memory in total, or 4mb, in blocks of 128kb. If you then set this
|
|
property to 8, then the number will be 8 * 2 * 128kb of buffer
|
|
memory, or 2mb.
|
|
</para>
|
|
|
|
<para>
|
|
CPU utilization will also go up with additional buffers, because a
|
|
larger number of buffer pairs allows a larger number of background
|
|
threads to compress in parallel. If you find that parallel
|
|
compression is consuming too much memory or CPU, you can adjust this
|
|
value downward.
|
|
</para>
|
|
|
|
<para>
|
|
The default value is 16. Different values may deliver better or
|
|
worse results, depending on your priorities and the dynamic
|
|
performance characteristics of your storage and compute resources.
|
|
</para>
|
|
|
|
<para>
|
|
This property is not the number of buffer pairs to use; it is an
|
|
upper limit. An illustration: Suppose you have an application that
|
|
uses the default value of this property (which is 16), and it runs
|
|
on a machine with 2 CPU cores. In that case, DotNetZip will allocate
|
|
4 buffer pairs per CPU core, for a total of 8 pairs. The upper
|
|
limit specified by this property has no effect.
|
|
</para>
|
|
|
|
<para>
|
|
The application can set this value at any time, but it is
|
|
effective only if set before calling
|
|
<c>ZipOutputStream.Write()</c> for the first time.
|
|
</para>
|
|
</remarks>
|
|
|
|
<seealso cref="P:Ionic.Zip.ZipOutputStream.ParallelDeflateThreshold"/>
|
|
|
|
</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.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)) > 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) > 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)) > 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) > 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>
|
|
|
|
<para>
|
|
Application code won't call this code directly. This method may
|
|
be invoked in two distinct scenarios. If disposing == true, the
|
|
method has been called directly or indirectly by a user's code,
|
|
for example via the public Dispose() method. In this case, both
|
|
managed and unmanaged resources can be referenced and disposed.
|
|
If disposing == false, the method has been called by the runtime
|
|
from inside the object finalizer and this method should not
|
|
reference other objects; in that case only unmanaged resources
|
|
must be referenced or disposed.
|
|
</para>
|
|
</remarks>
|
|
|
|
<param name="disposing">
|
|
true if the Dispose method was invoked by user code.
|
|
</param>
|
|
</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>
|
|
<member name="M:Ionic.Zip.ZipSegmentedStream.ForUpdate(System.String,System.UInt32)">
|
|
<summary>
|
|
Sort-of like a factory method, ForUpdate is used only when
|
|
the application needs to update the zip entry metadata for
|
|
a segmented zip file, when the starting segment is earlier
|
|
than the ending segment, for a particular entry.
|
|
</summary>
|
|
<remarks>
|
|
<para>
|
|
The update is always contiguous, never rolls over. As a
|
|
result, this method doesn't need to return a ZSS; it can
|
|
simply return a FileStream. That's why it's "sort of"
|
|
like a Factory method.
|
|
</para>
|
|
<para>
|
|
Caller must Close/Dispose the stream object returned by
|
|
this method.
|
|
</para>
|
|
</remarks>
|
|
</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="P:Ionic.Zip.ZipSegmentedStream.CurrentName">
|
|
<summary>
|
|
Name of the filesystem file corresponding to the current segment.
|
|
</summary>
|
|
<remarks>
|
|
<para>
|
|
The name is not always the name currently being used in the
|
|
filesystem. When rwMode is RwMode.Write, the filesystem file has a
|
|
temporary name until the stream is closed or until the next segment is
|
|
started.
|
|
</para>
|
|
</remarks>
|
|
</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.CheckZipPassword(System.String,System.String)">
|
|
<summary>
|
|
A COM-friendly wrapper for the static method <see cref="M:Ionic.Zip.ZipFile.CheckZipPassword(System.String,System.String)"/>.
|
|
</summary>
|
|
|
|
<param name="filename">The filename to of the zip file to check.</param>
|
|
|
|
<param name="password">The password 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.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.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.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.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.#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>
|
|
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.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="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 >, >=, <, <= 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 > 2009-01-01</term>
|
|
<description>all files with a last modified time after January 1st, 2009.
|
|
</description>
|
|
</item>
|
|
|
|
<item>
|
|
<term>ctime > 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 > 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 >= 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 > 1000 or attributes = H" implies "((name = *.txt AND size
|
|
> 1000) OR attributes = H)" while "attributes = H OR name = *.txt
|
|
and size > 1000" evaluates to "((attributes = H OR name = *.txt)
|
|
AND size > 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 >= 2009-02-14 AND mtime < 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.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.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>
|
|
<remarks>
|
|
<para>
|
|
The AES/CTR encryption protocol used by WinZip works like this:
|
|
|
|
- start with a counter, initialized to zero.
|
|
|
|
- to encrypt, take the data by 16-byte blocks. For each block:
|
|
- apply the transform to the counter
|
|
- increement the counter
|
|
- XOR the result of the transform with the plaintext to
|
|
get the ciphertext.
|
|
- compute the mac on the encrypted bytes
|
|
- when finished with all blocks, store the computed MAC.
|
|
|
|
- to decrypt, take the data by 16-byte blocks. For each block:
|
|
- compute the mac on the encrypted bytes,
|
|
- apply the transform to the counter
|
|
- increement the counter
|
|
- XOR the result of the transform with the ciphertext to
|
|
get the plaintext.
|
|
- when finished with all blocks, compare the computed MAC against
|
|
the stored MAC
|
|
|
|
</para>
|
|
</remarks>
|
|
</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.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.SharedUtilities">
|
|
<summary>
|
|
Collects general purpose utility methods.
|
|
</summary>
|
|
</member>
|
|
<member name="M:Ionic.Zip.SharedUtilities.GetFileLength(System.String)">
|
|
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>
|
|
This method 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 decorator stream. It wraps another stream, and performs bookkeeping
|
|
to keep track of the stream Position.
|
|
</summary>
|
|
<remarks>
|
|
<para>
|
|
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
|
|
<c>Response.OutputStream</c>, or on a different write-only stream
|
|
provided as the destination for the zip by the application. In this
|
|
case, programmers can use this counting stream to count the bytes read
|
|
or written.
|
|
</para>
|
|
<para>
|
|
Consider the scenario of an application that saves a self-extracting
|
|
archive (SFX), that uses a custom SFX stub.
|
|
</para>
|
|
<para>
|
|
Saving to a filesystem file, the application would open the
|
|
filesystem file (getting a <c>FileStream</c>), save the custom sfx stub
|
|
into it, and then call <c>ZipFile.Save()</c>, specifying the same
|
|
FileStream. <c>ZipFile.Save()</c> does the right thing for the zipentry
|
|
offsets, by inquiring the Position of the <c>FileStream</c> before writing
|
|
any data, and then adding that initial offset into any ZipEntry
|
|
offsets in the zip directory. Everything works fine.
|
|
</para>
|
|
<para>
|
|
Now suppose the application is an ASPNET application and it saves
|
|
directly to <c>Response.OutputStream</c>. It's not possible for DotNetZip to
|
|
inquire the <c>Position</c>, so the offsets for the SFX will be wrong.
|
|
</para>
|
|
<para>
|
|
The workaround is for the application to use this class to wrap
|
|
<c>HttpResponse.OutputStream</c>, then write the SFX stub and the ZipFile
|
|
into that wrapper stream. Because <c>ZipFile.Save()</c> can inquire the
|
|
<c>Position</c>, it will then do the right thing with the offsets.
|
|
</para>
|
|
</remarks>
|
|
</member>
|
|
<member name="M:Ionic.Zip.CountingStream.#ctor(System.IO.Stream)">
|
|
<summary>
|
|
The constructor.
|
|
</summary>
|
|
<param name="stream">The underlying stream</param>
|
|
</member>
|
|
<member name="M:Ionic.Zip.CountingStream.Adjust(System.Int64)">
|
|
<summary>
|
|
Adjust the byte count on the stream.
|
|
</summary>
|
|
|
|
<param name='delta'>
|
|
the number of bytes to subtract from the count.
|
|
</param>
|
|
|
|
<remarks>
|
|
<para>
|
|
Subtract delta from the count of bytes written to the stream.
|
|
This is necessary when seeking back, and writing additional data,
|
|
as happens in some cases when saving Zip files.
|
|
</para>
|
|
</remarks>
|
|
</member>
|
|
<member name="M:Ionic.Zip.CountingStream.Read(System.Byte[],System.Int32,System.Int32)">
|
|
<summary>
|
|
The read method.
|
|
</summary>
|
|
<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.CountingStream.Write(System.Byte[],System.Int32,System.Int32)">
|
|
<summary>
|
|
Write data into the stream.
|
|
</summary>
|
|
<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.CountingStream.Flush">
|
|
<summary>
|
|
Flushes the underlying stream.
|
|
</summary>
|
|
</member>
|
|
<member name="M:Ionic.Zip.CountingStream.Seek(System.Int64,System.IO.SeekOrigin)">
|
|
<summary>
|
|
Seek in the stream.
|
|
</summary>
|
|
<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.CountingStream.SetLength(System.Int64)">
|
|
<summary>
|
|
Set the length of the underlying stream. Be careful with this!
|
|
</summary>
|
|
|
|
<param name='value'>the length to set on the underlying stream.</param>
|
|
</member>
|
|
<member name="P:Ionic.Zip.CountingStream.WrappedStream">
|
|
<summary>
|
|
Gets the wrapped stream.
|
|
</summary>
|
|
</member>
|
|
<member name="P:Ionic.Zip.CountingStream.BytesWritten">
|
|
<summary>
|
|
The count of bytes written out to the stream.
|
|
</summary>
|
|
</member>
|
|
<member name="P:Ionic.Zip.CountingStream.BytesRead">
|
|
<summary>
|
|
the count of bytes that have been read from the stream.
|
|
</summary>
|
|
</member>
|
|
<member name="P:Ionic.Zip.CountingStream.CanRead">
|
|
<summary>
|
|
Whether the stream can be read.
|
|
</summary>
|
|
</member>
|
|
<member name="P:Ionic.Zip.CountingStream.CanSeek">
|
|
<summary>
|
|
Whether it is possible to call Seek() on the stream.
|
|
</summary>
|
|
</member>
|
|
<member name="P:Ionic.Zip.CountingStream.CanWrite">
|
|
<summary>
|
|
Whether it is possible to call Write() on the stream.
|
|
</summary>
|
|
</member>
|
|
<member name="P:Ionic.Zip.CountingStream.Length">
|
|
<summary>
|
|
The length of the underlying stream.
|
|
</summary>
|
|
</member>
|
|
<member name="P:Ionic.Zip.CountingStream.ComputedPosition">
|
|
<summary>
|
|
Returns the sum of number of bytes written, plus the initial
|
|
offset before writing.
|
|
</summary>
|
|
</member>
|
|
<member name="P:Ionic.Zip.CountingStream.Position">
|
|
<summary>
|
|
The Position of the stream.
|
|
</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.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. This enumeration allows a single EventArgs type to be sued to
|
|
describe one of multiple subevents. For example, a SaveProgress event is
|
|
invoked before, after, and during the saving of a single entry. The value
|
|
of an enum with this type, specifies which event is being triggered. The
|
|
same applies to Extraction, Reading and Adding events.
|
|
</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. You must use
|
|
<see cref="F:Ionic.Zip.ExtractExistingFileAction.InvokeExtractProgressEvent">
|
|
ExtractExistingFileAction.InvokeExtractProgressEvent</see> in the call
|
|
to <c>ZipEntry.Extract()</c> in order to receive this event.
|
|
</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.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.ReadDirEntry(Ionic.Zip.ZipFile,System.Collections.Generic.Dictionary{System.String,System.Object})">
|
|
<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>
|
|
|
|
<param name="previouslySeen">
|
|
a list of previously seen entry names; used to prevent duplicates.
|
|
</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.#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.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>
|
|
Within the call to <c>Extract()</c>, the content for the entry is
|
|
written into a filesystem file, and then the last modified time of the
|
|
file is set according to the <see cref="P:Ionic.Zip.ZipEntry.LastModified"/> property on
|
|
the entry. See the remarks the <see cref="P:Ionic.Zip.ZipEntry.LastModified"/> property for
|
|
some details about the last modified time.
|
|
</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 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>
|
|
<para>
|
|
The position on the stream is not reset by this method before it extracts.
|
|
You may want to call stream.Seek() before calling ZipEntry.Extract().
|
|
</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>
|
|
<para>
|
|
The caller can specify any write-able stream, for example 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>
|
|
<para>
|
|
The position on the stream is not reset by this method before it extracts.
|
|
You may want to call stream.Seek() before calling ZipEntry.Extract().
|
|
</para>
|
|
</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 a readable stream corresponding to the zip entry in the
|
|
archive. The stream decompresses and decrypts as necessary, as it
|
|
is read.
|
|
</summary>
|
|
|
|
<remarks>
|
|
|
|
<para>
|
|
DotNetZip offers a variety of ways to extract entries from a zip
|
|
file. This method allows an application to extract an entry by
|
|
reading a <see cref="T:System.IO.Stream"/>.
|
|
</para>
|
|
|
|
<para>
|
|
The return value is of type <see cref="T:Ionic.Crc.CrcCalculatorStream"/>. Use it as you would any
|
|
stream for reading. When an application calls <see cref="M:System.IO.Stream.Read(System.Byte[],System.Int32,System.Int32)"/> on that stream, it will
|
|
receive data from the zip entry that is decrypted and decompressed
|
|
as necessary.
|
|
</para>
|
|
|
|
<para>
|
|
<c>CrcCalculatorStream</c> 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.Crc.CrcCalculatorStream.Crc"/> property on the
|
|
<c>CrcCalculatorStream</c>. When the read is complete, your
|
|
application
|
|
<em>should</em> check this CRC 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, to verify integrity. 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 write-able stream that is
|
|
already opened, like a <see cref="T:System.IO.FileStream"/>, do not
|
|
use this method. Instead, use <see cref="M:Ionic.Zip.ZipEntry.Extract(System.IO.Stream)"/>.
|
|
</para>
|
|
|
|
<para>
|
|
Your application may use only one stream created by OpenReader() at
|
|
a time, and you should not call other Extract methods before
|
|
completing your reads on a stream obtained from OpenReader(). This
|
|
is because there is really only one source stream for the compressed
|
|
content. A call to OpenReader() seeks in the source stream, to the
|
|
beginning of the compressed content. A subsequent call to
|
|
OpenReader() on a different entry will seek to a different position
|
|
in the source stream, as will a call to Extract() or one of its
|
|
overloads. This will corrupt the state for the decompressing stream
|
|
from the original call to OpenReader().
|
|
</para>
|
|
|
|
<para>
|
|
The <c>OpenReader()</c> method works only when the ZipEntry is
|
|
obtained from an instance of <c>ZipFile</c>. This method will throw
|
|
an exception if the ZipEntry is obtained from a <see cref="T:Ionic.Zip.ZipInputStream"/>.
|
|
</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>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 > 0)
|
|
If (s.Crc32 <> 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 <> 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 a readable stream for an encrypted zip entry in the archive.
|
|
The stream decompresses and decrypts as necessary, as it is read.
|
|
</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. The content for
|
|
the entry does not get decompressed or decrypted. This method
|
|
basically reads metadata, and seeks.
|
|
</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="M:Ionic.Zip.ZipEntry.FindExtraFieldSegment(System.Byte[],System.Int32,System.UInt16)">
|
|
<summary>
|
|
Finds a particular segment in the given extra field.
|
|
This is used when modifying a previously-generated
|
|
extra field, in particular when removing the AES crypto
|
|
segment in the extra field.
|
|
</summary>
|
|
</member>
|
|
<member name="M:Ionic.Zip.ZipEntry.ProcessExtraField(System.IO.Stream,System.Int16)">
|
|
<summary>
|
|
At current cursor position in the stream, read the extra
|
|
field, and set the properties on the ZipEntry instance
|
|
appropriately. This can be called when processing the
|
|
Extra field in the Central Directory, or in the local
|
|
header.
|
|
</summary>
|
|
</member>
|
|
<member name="M:Ionic.Zip.ZipEntry.GetEncodedFileNameBytes">
|
|
<summary>
|
|
generate and return a byte array that encodes the filename
|
|
for the entry.
|
|
</summary>
|
|
<remarks>
|
|
<para>
|
|
side effects: generate and store into _CommentBytes the
|
|
byte array for any comment attached to the entry. Also
|
|
sets _actualEncoding to indicate the actual encoding
|
|
used. The same encoding is used for both filename and
|
|
comment.
|
|
</para>
|
|
</remarks>
|
|
</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
|
|
compression Stream. (like DeflateStream or BZip2OutputStream)
|
|
</summary>
|
|
</member>
|
|
<member name="M:Ionic.Zip.ZipEntry.PrepOutputStream(System.IO.Stream,System.Int64,Ionic.Zip.CountingStream@,System.IO.Stream@,System.IO.Stream@,Ionic.Crc.CrcCalculatorStream@)">
|
|
<summary>
|
|
Prepare the given stream for output - wrap it in a CountingStream, and
|
|
then in a CRC stream, and an encryptor and deflator as appropriate.
|
|
</summary>
|
|
<remarks>
|
|
<para>
|
|
Previously this was used in ZipEntry.Write(), but in an effort to
|
|
introduce some efficiencies in that method I've refactored to put the
|
|
code inline. This method still gets called by ZipOutputStream.
|
|
</para>
|
|
</remarks>
|
|
</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="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 Windows-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). 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.
|
|
</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>
|
|
While any zip application or library, regardless of the platform it
|
|
runs on, could use any of the time formats allowed by the ZIP
|
|
specification, not all zip tools or libraries do 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. 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 higher precision NTFS or Unix 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
|
|
higher precision 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 of
|
|
this library 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 when Unix times are present, or that a
|
|
non-DotNetZip-powered application running on Windows will be able to
|
|
handle file times in Unix format. DotNetZip will always do something
|
|
reasonable; other libraries or tools may not. 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>
|
|
|
|
<para>
|
|
This property is only partially supported in the Silverlight version
|
|
of the library: applications can read attributes on entries within
|
|
ZipFiles. But extracting entries within Silverlight will not set the
|
|
attributes on the extracted files.
|
|
</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>
|
|
|
|
<para>
|
|
When a <c>ZipEntry</c> is contained within a <c>ZipFile</c>, applications
|
|
cannot rename the entry within the context of a <c>foreach</c> (<c>For
|
|
Each</c> in VB) loop, because of the way the <c>ZipFile</c> stores
|
|
entries. If you need to enumerate through all the entries and rename one
|
|
or more of them, use <see cref="P:Ionic.Zip.ZipFile.EntriesSorted">ZipFile.EntriesSorted</see> as the
|
|
collection. See also, <see cref="M:Ionic.Zip.ZipFile.GetEnumerator">ZipFile.GetEnumerator()</see>.
|
|
</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.AlternateEncoding"/> and
|
|
<see cref="P:Ionic.Zip.ZipEntry.AlternateEncodingUsage"/>.
|
|
</para>
|
|
</remarks>
|
|
<seealso cref="P:Ionic.Zip.ZipEntry.AlternateEncoding"/>
|
|
<seealso cref="P:Ionic.Zip.ZipEntry.AlternateEncodingUsage"/>
|
|
</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>
|
|
<para>
|
|
You probably do not need to concern yourself with the contents of this
|
|
property, but in case you do:
|
|
</para>
|
|
|
|
<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. This applies only for CompressionMethod = DEFLATE.
|
|
</summary>
|
|
|
|
<remarks>
|
|
<para>
|
|
When using the DEFLATE compression method, 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>
|
|
|
|
<para>
|
|
Setting this property has no effect if the <c>CompressionMethod</c> is something
|
|
other than <c>Deflate</c> or <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>
|
|
When reading a <c>ZipFile</c>, this value is read in from the existing
|
|
zip file. When creating or updating a <c>ZipFile</c>, the compressed
|
|
size is computed during compression. Therefore the value on a
|
|
<c>ZipEntry</c> is valid after a call to <c>Save()</c> (or one of its
|
|
overloads) in that case.
|
|
</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>
|
|
When reading a <c>ZipFile</c>, this value is read in from the existing
|
|
zip file. When creating or updating a <c>ZipFile</c>, the uncompressed
|
|
size is computed during compression. Therefore the value on a
|
|
<c>ZipEntry</c> is valid after a call to <c>Save()</c> (or one of its
|
|
overloads) in that case.
|
|
</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, implying 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 && response[0]!='Y' &&
|
|
response[0]!='N' && 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>
|
|
Don't use this property. See <see cref="P:Ionic.Zip.ZipEntry.AlternateEncoding"/>.
|
|
</para>
|
|
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.Zip.ZipEntry.AlternateEncoding">
|
|
<summary>
|
|
Specifies the alternate text encoding used by this ZipEntry
|
|
</summary>
|
|
<remarks>
|
|
<para>
|
|
The default text encoding used in Zip files for encoding filenames and
|
|
comments is IBM437, which is something like a superset of ASCII. In
|
|
cases where this is insufficient, applications can specify an
|
|
alternate encoding.
|
|
</para>
|
|
<para>
|
|
When creating a zip file, the usage of the alternate encoding is
|
|
governed by the <see cref="P:Ionic.Zip.ZipEntry.AlternateEncodingUsage"/> property.
|
|
Typically you would set both properties to tell DotNetZip to employ an
|
|
encoding that is not IBM437 in the zipfile you are creating.
|
|
</para>
|
|
<para>
|
|
Keep in mind that because the ZIP specification states that the only
|
|
valid encodings to use are IBM437 and UTF-8, if you use something
|
|
other than that, then zip tools and libraries may not be able to
|
|
successfully read the zip archive you generate.
|
|
</para>
|
|
<para>
|
|
The zip specification states that applications should presume that
|
|
IBM437 is in use, except when a special bit is set, which indicates
|
|
UTF-8. There is no way to specify an arbitrary code page, within the
|
|
zip file itself. When you create a zip file encoded with gb2312 or
|
|
ibm861 or anything other than IBM437 or UTF-8, then the application
|
|
that reads the zip file needs to "know" which code page to use. In
|
|
some cases, the code page used when reading is chosen implicitly. For
|
|
example, WinRar uses the ambient code page for the host desktop
|
|
operating system. The pitfall here is that if you create a zip in
|
|
Copenhagen and send it to Tokyo, the reader of the zipfile may not be
|
|
able to decode successfully.
|
|
</para>
|
|
</remarks>
|
|
<example>
|
|
This example shows how to create a zipfile encoded with a
|
|
language-specific encoding:
|
|
<code>
|
|
using (var zip = new ZipFile())
|
|
{
|
|
zip.AlternateEnoding = System.Text.Encoding.GetEncoding("ibm861");
|
|
zip.AlternateEnodingUsage = ZipOption.Always;
|
|
zip.AddFileS(arrayOfFiles);
|
|
zip.Save("Myarchive-Encoded-in-IBM861.zip");
|
|
}
|
|
</code>
|
|
</example>
|
|
<seealso cref="P:Ionic.Zip.ZipFile.AlternateEncodingUsage"/>
|
|
</member>
|
|
<member name="P:Ionic.Zip.ZipEntry.AlternateEncodingUsage">
|
|
<summary>
|
|
Describes if and when this instance should apply
|
|
AlternateEncoding to encode the FileName and Comment, when
|
|
saving.
|
|
</summary>
|
|
<seealso cref="P:Ionic.Zip.ZipFile.AlternateEncoding"/>
|
|
</member>
|
|
<member name="P:Ionic.Zip.ZipEntry.IsText">
|
|
<summary>
|
|
Indicates whether an entry is marked as a text file. Be careful when
|
|
using on this property. Unless you have a good reason, you should
|
|
probably ignore this property.
|
|
</summary>
|
|
|
|
<remarks>
|
|
<para>
|
|
The ZIP format includes a provision for specifying whether an entry in
|
|
the zip archive is a text or binary file. This property exposes that
|
|
metadata item. Be careful when using this property: It's not clear
|
|
that this property as a firm meaning, across tools and libraries.
|
|
</para>
|
|
|
|
<para>
|
|
To be clear, when reading a zip file, the property value may or may
|
|
not be set, and its value may or may not be valid. Not all entries
|
|
that you may think of as "text" entries will be so marked, and entries
|
|
marked as "text" are not guaranteed in any way to be text entries.
|
|
Whether the value is set and set correctly depends entirely on the
|
|
application that produced the zip file.
|
|
</para>
|
|
|
|
<para>
|
|
There are many zip tools available, and when creating zip files, some
|
|
of them "respect" the IsText metadata field, and some of them do not.
|
|
Unfortunately, even when an application tries to do "the right thing",
|
|
it's not always clear what "the right thing" is.
|
|
</para>
|
|
|
|
<para>
|
|
There's no firm definition of just what it means to be "a text file",
|
|
and the zip specification does not help in this regard. Twenty years
|
|
ago, text was ASCII, each byte was less than 127. IsText meant, all
|
|
bytes in the file were less than 127. These days, it is not the case
|
|
that all text files have all bytes less than 127. Any unicode file
|
|
may have bytes that are above 0x7f. The zip specification has nothing
|
|
to say on this topic. Therefore, it's not clear what IsText really
|
|
means.
|
|
</para>
|
|
|
|
<para>
|
|
This property merely tells a reading application what is stored in the
|
|
metadata for an entry, without guaranteeing its validity or its
|
|
meaning.
|
|
</para>
|
|
|
|
<para>
|
|
When DotNetZip is used to create a zipfile, it attempts to set this
|
|
field "correctly." For example, if a file ends in ".txt", this field
|
|
will be set. Your application may override that default setting. When
|
|
writing a zip file, you must set the property before calling
|
|
<c>Save()</c> on the ZipFile.
|
|
</para>
|
|
|
|
<para>
|
|
When reading a zip file, a more general way to decide just what kind
|
|
of file is contained in a particular entry is to use the file type
|
|
database stored in the operating system. The operating system stores
|
|
a table that says, a file with .jpg extension is a JPG image file, a
|
|
file with a .xml extension is an XML document, a file with a .txt is a
|
|
pure ASCII text document, and so on. To get this information on
|
|
Windows, <see
|
|
href="http://www.codeproject.com/KB/cs/GetFileTypeAndIcon.aspx"> you
|
|
need to read and parse the registry.</see> </para>
|
|
</remarks>
|
|
|
|
<example>
|
|
<code>
|
|
using (var zip = new ZipFile())
|
|
{
|
|
var e = zip.UpdateFile("Descriptions.mme", "");
|
|
e.IsText = true;
|
|
zip.Save(zipPath);
|
|
}
|
|
</code>
|
|
|
|
<code lang="VB">
|
|
Using zip As New ZipFile
|
|
Dim e2 as ZipEntry = zip.AddFile("Descriptions.mme", "")
|
|
e.IsText= True
|
|
zip.Save(zipPath)
|
|
End Using
|
|
</code>
|
|
</example>
|
|
</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. DotNetZip supports a subset of them.
|
|
</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 compression, 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="F:Ionic.Zip.CompressionMethod.BZip2">
|
|
<summary>
|
|
BZip2 compression, a compression algorithm developed by Julian Seward.
|
|
For COM environments, the value is 12.
|
|
</summary>
|
|
</member>
|
|
<member name="T:Ionic.Zip.ZipFile">
|
|
<summary>
|
|
The ZipFile type represents a zip archive file.
|
|
</summary>
|
|
|
|
<remarks>
|
|
<para>
|
|
This is the main type in the DotNetZip class library. This class reads and
|
|
writes zip files, as defined in the <see href="http://www.pkware.com/documents/casestudies/APPNOTE.TXT">specification
|
|
for zip files described by PKWare</see>. 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.
|
|
</para>
|
|
|
|
<para>
|
|
This class provides a general purpose zip file capability. Use it to read,
|
|
create, or update zip files. When you want to create zip files using a
|
|
<c>Stream</c> type to write the zip file, you may want to consider the <see cref="T:Ionic.Zip.ZipOutputStream"/> class.
|
|
</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 methods and levels,
|
|
and ZIP64. They provide very similar performance when creating zip
|
|
files.
|
|
</para>
|
|
|
|
<para>
|
|
The <c>ZipFile</c> class is generally easier to use than
|
|
<c>ZipOutputStream</c> and should be considered a higher-level interface. 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 use
|
|
only when your application emits arbitrary data, not necessarily data from a
|
|
filesystem file, directly into a zip file, and does so using a <c>Stream</c>
|
|
metaphor.
|
|
</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>
|
|
|
|
<para>
|
|
Be aware that the <c>ZipFile</c> class implements the <see cref="T:System.IDisposable"/> interface. In order for <c>ZipFile</c> to
|
|
produce a valid zip file, you use use it within a using clause (<c>Using</c>
|
|
in VB), or call the <c>Dispose()</c> method explicitly. See the examples
|
|
for how to employ a using clause.
|
|
</para>
|
|
|
|
</remarks>
|
|
</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 < 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<ZipEntry> (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 for the machine, or on Silverlight, using UTF-8.
|
|
</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 " & 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. A BOM (byte-order-mark) is emitted into the file, if the
|
|
Encoding parameter is set for that.
|
|
</para>
|
|
|
|
<para>
|
|
Most Encoding classes support a constructor that accepts a boolean,
|
|
indicating whether to emit a BOM or not. For example see <see cref="M:System.Text.UTF8Encoding.#ctor(System.Boolean)"/>.
|
|
</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 should 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>
|
|
The passed stream will be read from its current position. If
|
|
necessary, callers should set the position in the stream before
|
|
calling AddEntry(). This might be appropriate when using this method
|
|
with a MemoryStream, for example.
|
|
</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>
|
|
About progress events: When using the WriteDelegate, DotNetZip does
|
|
not issue any SaveProgress events with <c>EventType</c> = <see cref="F:Ionic.Zip.ZipProgressEventType.Saving_EntryBytesRead">
|
|
Saving_EntryBytesRead</see>. (This is because it is the
|
|
application's code that runs in WriteDelegate - there's no way for
|
|
DotNetZip to know when to issue a EntryBytesRead event.)
|
|
Applications that want to update a progress bar or similar status
|
|
indicator should do so from within the WriteDelegate
|
|
itself. DotNetZip will issue the other SaveProgress events,
|
|
including <see cref="F:Ionic.Zip.ZipProgressEventType.Saving_Started">
|
|
Saving_Started</see>,
|
|
<see cref="F:Ionic.Zip.ZipProgressEventType.Saving_BeforeWriteEntry">
|
|
Saving_BeforeWriteEntry</see>, and <see cref="F:Ionic.Zip.ZipProgressEventType.Saving_AfterWriteEntry">
|
|
Saving_AfterWriteEntry</see>.
|
|
</para>
|
|
|
|
<para>
|
|
Note: When you use PKZip encryption, it's normally necessary to
|
|
compute the CRC of the content to be encrypted, before compressing or
|
|
encrypting it. Therefore, when using PKZip encryption with a
|
|
WriteDelegate, the WriteDelegate CAN BE called twice: once to compute
|
|
the CRC, and the second time to potentially compress and
|
|
encrypt. Surprising, but true. This is because PKWARE specified that
|
|
the encryption initialization data depends on the CRC.
|
|
If this happens, 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>
|
|
|
|
<para>
|
|
The double-read behavior happens with all types of entries, not only
|
|
those that use WriteDelegate. It happens if you add an entry from a
|
|
filesystem file, or using a string, or a stream, or an opener/closer
|
|
pair. But in those cases, DotNetZip takes care of reading twice; in
|
|
the case of the WriteDelegate, the application code gets invoked
|
|
twice. Be aware.
|
|
</para>
|
|
|
|
<para>
|
|
As you can imagine, this can cause performance problems for large
|
|
streams, and it can lead to correctness problems when you use a
|
|
<c>WriteDelegate</c>. This is a pretty big pitfall. There are two
|
|
ways to avoid it. First, and most preferred: don't use PKZIP
|
|
encryption. If you use the WinZip AES encryption, this problem
|
|
doesn't occur, because the encryption protocol doesn't require the CRC
|
|
up front. Second: if you do choose to use PKZIP encryption, write out
|
|
to a non-seekable stream (like standard output, or the
|
|
Response.OutputStream in an ASP.NET application). In this case,
|
|
DotNetZip will use an alternative encryption protocol that does not
|
|
rely on the CRC of the content. This also implies setting bit 3 in
|
|
the zip entry, which still presents problems for some zip tools.
|
|
</para>
|
|
|
|
<para>
|
|
In the future I may modify DotNetZip to *always* use bit 3 when PKZIP
|
|
encryption is in use. This seems like a win overall, but there will
|
|
be some work involved. If you feel strongly about it, visit the
|
|
DotNetZip forums and vote up <see href="http://dotnetzip.codeplex.com/workitem/13686">the Workitem
|
|
tracking this issue</see>.
|
|
</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) => 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) =>
|
|
{
|
|
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 <> 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) => File.Open(filename, FileMode.Open, FileAccess.Read, FileShare.ReadWrite ),
|
|
(name, stream) => 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 content for the <c>ZipEntry</c>.
|
|
</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. The string content is encoded
|
|
using the default encoding for the machine, or on Silverlight, using
|
|
UTF-8. This encoding is distinct from the encoding used for the
|
|
filename itself. See <see cref="P:Ionic.Zip.ZipFile.AlternateEncoding"/>.
|
|
</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.AlternateEncoding"/>.
|
|
</param>
|
|
|
|
<returns>The <c>ZipEntry</c> added.</returns>
|
|
|
|
</member>
|
|
<member name="M:Ionic.Zip.ZipFile.UpdateEntry(System.String,Ionic.Zip.WriteDelegate)">
|
|
<summary>
|
|
Updates the given entry in the <c>ZipFile</c>, using the given delegate
|
|
as the source for 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,Ionic.Zip.WriteDelegate)"/>. 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="writer">the delegate which will write the entry content.</param>
|
|
|
|
<returns>The <c>ZipEntry</c> added.</returns>
|
|
|
|
</member>
|
|
<member name="M:Ionic.Zip.ZipFile.UpdateEntry(System.String,Ionic.Zip.OpenDelegate,Ionic.Zip.CloseDelegate)">
|
|
<summary>
|
|
Updates the given entry in the <c>ZipFile</c>, using the given delegates
|
|
to open and close the stream that provides the 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,Ionic.Zip.OpenDelegate,Ionic.Zip.CloseDelegate)"/>. 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="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 <c>ZipEntry</c> added or updated.</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.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.IO.TextWriter)"/>
|
|
</member>
|
|
<member name="M:Ionic.Zip.ZipFile.CheckZip(System.String,System.Boolean,System.IO.TextWriter)">
|
|
<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="writer">
|
|
a TextWriter in which messages generated while checking will be written.
|
|
</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.IO.TextWriter)"/>
|
|
</member>
|
|
<member name="M:Ionic.Zip.ZipFile.CheckZipPassword(System.String,System.String)">
|
|
<summary>
|
|
Verify the password on a zip file.
|
|
</summary>
|
|
|
|
<remarks>
|
|
<para>
|
|
Keep in mind that passwords in zipfiles are applied to
|
|
zip entries, not to the entire zip file. So testing a
|
|
zipfile for a particular password doesn't work in the
|
|
general case. On the other hand, it's often the case
|
|
that a single password will be used on all entries in a
|
|
zip file. This method works for that case.
|
|
</para>
|
|
<para>
|
|
There is no way to check a password without doing the
|
|
decryption. So this code decrypts and extracts the given
|
|
zipfile into <see cref="F:System.IO.Stream.Null"/>
|
|
</para>
|
|
</remarks>
|
|
|
|
<param name="zipFileName">The filename to of the zip file to fix.</param>
|
|
|
|
<param name="password">The password to check.</param>
|
|
|
|
<returns>a bool indicating whether the password matches.</returns>
|
|
</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>
|
|
|
|
<param name='name'>the name of the entry to find</param>
|
|
<returns>true if an entry with the given name exists; otherwise false.
|
|
</returns>
|
|
</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<ZipEntry>();
|
|
foreach (ZipEntry e in zip)
|
|
{
|
|
if (e.LastModified < 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 < 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.BufferSizeDefault">
|
|
<summary>
|
|
Default size of the buffer used for IO.
|
|
</summary>
|
|
</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:Ionic.Zip.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>
|
|
|
|
<seealso cref="M:Ionic.Zip.ZipFile.Read(System.String,Ionic.Zip.ReadOptions)"/>.
|
|
|
|
<returns>The instance read from the zip archive.</returns>
|
|
|
|
</member>
|
|
<member name="M:Ionic.Zip.ZipFile.Read(System.String,Ionic.Zip.ReadOptions)">
|
|
<summary>
|
|
Reads a zip file archive from the named filesystem file using the
|
|
specified options.
|
|
</summary>
|
|
|
|
<remarks>
|
|
<para>
|
|
This version of the <c>Read()</c> method allows the caller to pass
|
|
in a <c>TextWriter</c> an <c>Encoding</c>, via an instance of the
|
|
<c>ReadOptions</c> class. The <c>ZipFile</c> is read in using the
|
|
specified encoding for entries where UTF-8 encoding is not
|
|
explicitly specified.
|
|
</para>
|
|
</remarks>
|
|
|
|
<example>
|
|
|
|
<para>
|
|
This example shows how to read a zip file using the Big-5 Chinese
|
|
code page (950), and extract each entry in the zip file, while
|
|
sending status messages out to the Console.
|
|
</para>
|
|
|
|
<para>
|
|
For this code to work as intended, the zipfile must have been
|
|
created using the big5 code page (CP950). This is typical, for
|
|
example, when using WinRar on a machine with CP950 set as the
|
|
default code page. In that case, the names of entries within the
|
|
Zip archive will be stored in that code page, and reading the zip
|
|
archive must be done using that code page. If the application did
|
|
not use the correct code page in ZipFile.Read(), then names of
|
|
entries within the zip archive would not be correctly retrieved.
|
|
</para>
|
|
|
|
<code lang="C#">
|
|
string zipToExtract = "MyArchive.zip";
|
|
string extractDirectory = "extract";
|
|
var options = new ReadOptions
|
|
{
|
|
StatusMessageWriter = System.Console.Out,
|
|
Encoding = System.Text.Encoding.GetEncoding(950)
|
|
};
|
|
using (ZipFile zip = ZipFile.Read(zipToExtract, options))
|
|
{
|
|
foreach (ZipEntry e in zip)
|
|
{
|
|
e.Extract(extractDirectory);
|
|
}
|
|
}
|
|
</code>
|
|
|
|
|
|
<code lang="VB">
|
|
Dim zipToExtract as String = "MyArchive.zip"
|
|
Dim extractDirectory as String = "extract"
|
|
Dim options as New ReadOptions
|
|
options.Encoding = System.Text.Encoding.GetEncoding(950)
|
|
options.StatusMessageWriter = System.Console.Out
|
|
Using zip As ZipFile = ZipFile.Read(zipToExtract, options)
|
|
Dim e As ZipEntry
|
|
For Each e In zip
|
|
e.Extract(extractDirectory)
|
|
Next
|
|
End Using
|
|
</code>
|
|
</example>
|
|
|
|
|
|
<example>
|
|
|
|
<para>
|
|
This example shows how to read a zip file using the default
|
|
code page, to remove entries that have a modified date before a given threshold,
|
|
sending status messages out to a <c>StringWriter</c>.
|
|
</para>
|
|
|
|
<code lang="C#">
|
|
var options = new ReadOptions
|
|
{
|
|
StatusMessageWriter = new System.IO.StringWriter()
|
|
};
|
|
using (ZipFile zip = ZipFile.Read("PackedDocuments.zip", options))
|
|
{
|
|
var Threshold = new DateTime(2007,7,4);
|
|
// We cannot remove the entry from the list, within the context of
|
|
// an enumeration of said list.
|
|
// So we add the doomed entry to a list to be removed later.
|
|
// pass 1: mark the entries for removal
|
|
var MarkedEntries = new System.Collections.Generic.List<ZipEntry>();
|
|
foreach (ZipEntry e in zip)
|
|
{
|
|
if (e.LastModified < Threshold)
|
|
MarkedEntries.Add(e);
|
|
}
|
|
// pass 2: actually remove the entry.
|
|
foreach (ZipEntry zombie in MarkedEntries)
|
|
zip.RemoveEntry(zombie);
|
|
zip.Comment = "This archive has been updated.";
|
|
zip.Save();
|
|
}
|
|
// can now use contents of sw, eg store in an audit log
|
|
</code>
|
|
|
|
<code lang="VB">
|
|
Dim options as New ReadOptions
|
|
options.StatusMessageWriter = New System.IO.StringWriter
|
|
Using zip As ZipFile = ZipFile.Read("PackedDocuments.zip", options)
|
|
Dim Threshold As New DateTime(2007, 7, 4)
|
|
' We cannot remove the entry from the list, within the context of
|
|
' an enumeration of said list.
|
|
' So we add the doomed entry to a list to be removed later.
|
|
' pass 1: mark the entries for removal
|
|
Dim MarkedEntries As New System.Collections.Generic.List(Of ZipEntry)
|
|
Dim e As ZipEntry
|
|
For Each e In zip
|
|
If (e.LastModified < Threshold) Then
|
|
MarkedEntries.Add(e)
|
|
End If
|
|
Next
|
|
' pass 2: actually remove the entry.
|
|
Dim zombie As ZipEntry
|
|
For Each zombie In MarkedEntries
|
|
zip.RemoveEntry(zombie)
|
|
Next
|
|
zip.Comment = "This archive has been updated."
|
|
zip.Save
|
|
End Using
|
|
' can now use contents of sw, eg store in an audit log
|
|
</code>
|
|
</example>
|
|
|
|
<exception cref="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="options">
|
|
The set of options to use when reading the zip file.
|
|
</param>
|
|
|
|
<returns>The ZipFile instance read from the zip archive.</returns>
|
|
|
|
<seealso cref="M:Ionic.Zip.ZipFile.Read(System.IO.Stream,Ionic.Zip.ReadOptions)"/>
|
|
|
|
</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>
|
|
When reading from a file, it's probably easier to just use
|
|
<see cref="M:Ionic.Zip.ZipFile.Read(System.String,Ionic.Zip.ReadOptions)">ZipFile.Read(String, ReadOptions)</see>. This
|
|
overload is useful when when the zip archive content is
|
|
available from an already-open stream. The stream must be
|
|
open and readable and seekable when calling this method. The
|
|
stream is left open when the reading is completed.
|
|
</para>
|
|
|
|
<para>
|
|
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, see
|
|
<see cref="M:Ionic.Zip.ZipFile.Read(System.IO.Stream,Ionic.Zip.ReadOptions)">ZipFile.Read(Stream, ReadOptions)</see>. This
|
|
</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; they can be read as normal
|
|
ZIP files). Another example might be a stream being read from
|
|
a database, where the zip content is embedded within an
|
|
aggregate stream of data.
|
|
</para>
|
|
|
|
</remarks>
|
|
|
|
<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>The ZipFile instance read from the stream</returns>
|
|
|
|
</member>
|
|
<member name="M:Ionic.Zip.ZipFile.Read(System.IO.Stream,Ionic.Zip.ReadOptions)">
|
|
<summary>
|
|
Reads a zip file archive from the given stream using the
|
|
specified options.
|
|
</summary>
|
|
|
|
<remarks>
|
|
|
|
<para>
|
|
When reading from a file, it's probably easier to just use
|
|
<see cref="M:Ionic.Zip.ZipFile.Read(System.String,Ionic.Zip.ReadOptions)">ZipFile.Read(String, ReadOptions)</see>. This
|
|
overload is useful when when the zip archive content is
|
|
available from an already-open stream. The stream must be
|
|
open and readable and seekable when calling this method. The
|
|
stream is left open when the reading is completed.
|
|
</para>
|
|
|
|
<para>
|
|
Reading of zip content begins at the current position in the
|
|
stream. This means if you have a stream that concatenates
|
|
regular data and zip data, if you position the open, readable
|
|
stream at the start of the zip data, you will be able to read
|
|
the zip archive using this constructor, or any of the ZipFile
|
|
constructors that accept a <see cref="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; they can be read as normal
|
|
ZIP files). Another example might be a stream being read from
|
|
a database, where the zip content is embedded within an
|
|
aggregate stream of data.
|
|
</para>
|
|
</remarks>
|
|
|
|
<param name="zipStream">the stream containing the zip data.</param>
|
|
|
|
<param name="options">
|
|
The set of options to use when reading the zip file.
|
|
</param>
|
|
|
|
<exception cref="T:System.Exception">
|
|
Thrown if the zip archive cannot be read.
|
|
</exception>
|
|
|
|
<returns>The ZipFile instance read from the stream.</returns>
|
|
|
|
<seealso cref="M:Ionic.Zip.ZipFile.Read(System.String,Ionic.Zip.ReadOptions)"/>
|
|
|
|
</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.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="M:Ionic.Zip.ZipFile.DeleteFileWithRetry(System.String)">
|
|
<summary>
|
|
Delete file with retry on UnauthorizedAccessException.
|
|
</summary>
|
|
|
|
<remarks>
|
|
<para>
|
|
When calling File.Delete() on a file that has been "recently"
|
|
created, the call sometimes fails with
|
|
UnauthorizedAccessException. This method simply retries the Delete 3
|
|
times with a sleep between tries.
|
|
</para>
|
|
</remarks>
|
|
|
|
<param name='filename'>the name of the file to be deleted</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>. In the typical
|
|
case, 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>
|
|
|
|
<exception cref="T:System.OverflowException">
|
|
Thrown if <see cref="P:Ionic.Zip.ZipFile.MaxOutputSegmentSize"/> is non-zero, and the number
|
|
of segments that would be generated for the spanned zip file during the
|
|
save operation exceeds 99. If this happens, you need to increase the
|
|
segment size.
|
|
</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>
|
|
|
|
<example>
|
|
<para>
|
|
This example shows a pitfall you should avoid. DO NOT read
|
|
from a stream, then try to save to the same stream. DO
|
|
NOT DO THIS:
|
|
</para>
|
|
|
|
<code lang="C#">
|
|
using (var fs = new FileSteeam(filename, FileMode.Open))
|
|
{
|
|
using (var zip = Ionic.Zip.ZipFile.Read(inputStream))
|
|
{
|
|
zip.AddEntry("Name1.txt", "this is the content");
|
|
zip.Save(inputStream); // NO NO NO!!
|
|
}
|
|
}
|
|
</code>
|
|
|
|
<para>
|
|
Better like this:
|
|
</para>
|
|
|
|
<code lang="C#">
|
|
using (var zip = Ionic.Zip.ZipFile.Read(filename))
|
|
{
|
|
zip.AddEntry("Name1.txt", "this is the content");
|
|
zip.Save(); // YES!
|
|
}
|
|
</code>
|
|
|
|
</example>
|
|
|
|
<param name="outputStream">
|
|
The <c>System.IO.Stream</c> to write to. It must be
|
|
writable. If you created the ZipFile instanct by calling
|
|
ZipFile.Read(), this stream must not be the same stream
|
|
you passed to ZipFile.Read().
|
|
</param>
|
|
</member>
|
|
<member name="M:Ionic.Zip.ZipFile.AddSelectedFiles(System.String)">
|
|
<summary>
|
|
Adds to the ZipFile a set of files from the current working directory on
|
|
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.
|
|
</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" (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", "name" and "type" nouns both support = and != as operators.
|
|
The "size", "atime", "mtime", and "ctime" nouns support = and !=, and
|
|
>, >=, <, <= 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 > 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>
|
|
|
|
<item>
|
|
<term>type = D</term>
|
|
<description>all directories in the filesystem. </description>
|
|
</item>
|
|
|
|
</list>
|
|
|
|
<para>
|
|
You can combine criteria with the conjunctions AND or OR. Using a string
|
|
like "name = *.txt AND size >= 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 > 1000 or attributes = H" implies
|
|
"((name = *.txt AND size > 1000) OR attributes = H)" while "attributes =
|
|
H OR name = *.txt and size > 1000" evaluates to "((attributes = H OR name
|
|
= *.txt) AND size > 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 >= 2009-02-14 AND mtime < 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>
|
|
|
|
<para>
|
|
Using this method, the file selection does not recurse into
|
|
subdirectories, and the full path of the selected files is included in the
|
|
entries added into the zip archive. If you don't like these behaviors,
|
|
see the other overloads of this method.
|
|
</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, optionally recursing into subdirectories.
|
|
</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 current working directory.
|
|
</para>
|
|
|
|
<para>
|
|
Using this method, the full path of the selected files is included in the
|
|
entries added into the zip archive. If you don't want this behavior, use
|
|
one of the overloads of this method that allows the specification of a
|
|
<c>directoryInArchive</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 > 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 > 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 a specified directory in the
|
|
filesystem, that conform to the specified criteria.
|
|
</summary>
|
|
|
|
<remarks>
|
|
<para>
|
|
This method selects files that conform to the specified criteria, from the
|
|
the specified directory on disk, and adds them to the ZipFile. The search
|
|
does not recurse into subdirectores.
|
|
</para>
|
|
|
|
<para>
|
|
Using this method, the full filesystem path of the files on disk is
|
|
reproduced on the entries added to the zip file. If you don't want this
|
|
behavior, use one of the other overloads of this method.
|
|
</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 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 > 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 > 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 specified directory on disk,
|
|
that conform to the specified criteria.
|
|
</summary>
|
|
|
|
<remarks>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
The full directory structure in the filesystem is reproduced on the
|
|
entries added to the zip archive. If you don't want this behavior, use
|
|
one of the overloads of this method that allows the specification of a
|
|
<c>directoryInArchive</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 *.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 > 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 > 2009-02-14", "files", true)
|
|
zip.Save(PathToZipArchive)
|
|
End Using
|
|
</code>
|
|
</example>
|
|
|
|
<example>
|
|
This example zips up all files in the current working
|
|
directory, and all its child directories, except those in
|
|
the <c>excludethis</c> subdirectory.
|
|
<code lang="VB">
|
|
Using Zip As ZipFile = New ZipFile(zipfile)
|
|
Zip.AddSelectedFfiles("name != 'excludethis\*.*'", datapath, True)
|
|
Zip.Save()
|
|
End Using
|
|
</code>
|
|
</example>
|
|
|
|
<param name="selectionCriteria">The criteria for file selection</param>
|
|
|
|
<param name="directoryOnDisk">
|
|
The filesystem path 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 specified directory on
|
|
disk, that conform to the specified criteria, and using a specified root
|
|
path for entries added to the zip archive.
|
|
</summary>
|
|
|
|
<remarks>
|
|
<para>
|
|
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)"/>.
|
|
</para>
|
|
|
|
</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 > 2009-02-14", "photos", "content");
|
|
zip.Save(PathToZipArchive);
|
|
}
|
|
</code>
|
|
<code lang="VB">
|
|
Using zip As ZipFile = New ZipFile
|
|
zip.AddSelectedFiles("name = *.psd and mtime > 2009-02-14", "photos", "content")
|
|
zip.Save(PathToZipArchive)
|
|
End Using
|
|
</code>
|
|
</example>
|
|
|
|
<param name="selectionCriteria">
|
|
The criteria for selection of files to add to the <c>ZipFile</c>.
|
|
</param>
|
|
|
|
<param name="directoryOnDisk">
|
|
The path to the directory in the filesystem from which to select files.
|
|
</param>
|
|
|
|
<param name="directoryPathInArchive">
|
|
Specifies a directory path to use to in place of the
|
|
<c>directoryOnDisk</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
|
|
null (nothing in VB) will use the path on the file name, if any; in other
|
|
words it would use <c>directoryOnDisk</c>, plus any subdirectory. 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 specified directory on
|
|
disk, that conform to the specified criteria, optionally recursing through
|
|
subdirectories, and using a specified root path for entries added to the
|
|
zip archive.
|
|
</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 to the <c>ZipFile</c>.
|
|
</param>
|
|
|
|
<param name="directoryOnDisk">
|
|
The path to the directory in the filesystem from which to select files.
|
|
</param>
|
|
|
|
<param name="directoryPathInArchive">
|
|
Specifies a directory path to use to in place of the
|
|
<c>directoryOnDisk</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
|
|
null (nothing in VB) will use the path on the file name, if any; in other
|
|
words it would use <c>directoryOnDisk</c>, plus any subdirectory. 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 to the <c>ZipFile</c>.
|
|
</param>
|
|
|
|
<param name="directoryOnDisk">
|
|
The path to the directory in the filesystem from which to select files.
|
|
</param>
|
|
|
|
<param name="directoryPathInArchive">
|
|
Specifies a directory path to use to in place of the
|
|
<c>directoryOnDisk</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 null (nothing in VB) will use the path on the file name, if
|
|
any; in other words it would use <c>directoryOnDisk</c>, plus any
|
|
subdirectory. 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 < 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 < 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 < 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 < 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 > 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 > 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 > 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 > 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.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">Environment.SpecialFolder.Personal</see>)
|
|
will be used as the default extract location. If you want to set the
|
|
default extract location, you should use the other overload of
|
|
<c>SaveSelfExtractor()</c>/ 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 WinForms-based self-extracting archive EXE that
|
|
will use c:\ExtractHere as the default extract location. The C# code
|
|
shows syntax for .NET 3.0, which uses an object initializer for
|
|
the SelfExtractorOptions object.
|
|
<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 WinForms-based exe";
|
|
var options = new SelfExtractorOptions
|
|
{
|
|
Flavor = SelfExtractorFlavor.WinFormsApplication,
|
|
DefaultExtractDirectory = "%USERPROFILE%\\ExtractHere",
|
|
PostExtractCommandLine = ExeToRunAfterExtract,
|
|
SfxExeWindowTitle = "My Custom Window Title",
|
|
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.WinFormsApplication
|
|
options.DefaultExtractDirectory = "%USERPROFILE%\\ExtractHere"
|
|
options.PostExtractCommandLine = ExeToRunAfterExtract
|
|
options.SfxExeWindowTitle = "My Custom Window Title"
|
|
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 creating the
|
|
Self-extracting archive.</param>
|
|
</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) & "{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="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="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>
|
|
<para>
|
|
When doing ZLIB or Deflate compression, the library fills a buffer,
|
|
then passes it to the compressor for compression. Then the library
|
|
reads out the compressed bytes. This happens repeatedly until there
|
|
is no more uncompressed data to compress. This property sets the
|
|
size of the buffer that will be used for chunk-wise compression. In
|
|
order for the setting to take effect, your application needs to set
|
|
this property before calling one of the <c>ZipFile.Save()</c>
|
|
overloads.
|
|
</para>
|
|
<para>
|
|
Setting this affects the performance and memory efficiency of
|
|
compression and decompression. For larger files, setting this to a
|
|
larger size may improve compression performance, but the exact
|
|
numbers vary depending on available memory, the size of the streams
|
|
you are compressing, 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.
|
|
</para>
|
|
</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 using the DEFLATE method. 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.CompressionMethod">
|
|
<summary>
|
|
The compression method for the zipfile.
|
|
</summary>
|
|
<remarks>
|
|
<para>
|
|
By default, the compression method is <c>CompressionMethod.Deflate.</c>
|
|
</para>
|
|
</remarks>
|
|
<seealso cref="T:Ionic.Zip.CompressionMethod"/>
|
|
</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 specification does not describe how to indicate the encoding used
|
|
on a comment string. Many "compliant" zip tools and libraries use
|
|
IBM437 as the code page for comments; DotNetZip, too, follows that
|
|
practice. On the other hand, there are situations where you want a
|
|
Comment to be encoded with something else, for example using code page
|
|
950 "Big-5 Chinese". To fill that need, DotNetZip will encode the
|
|
comment following the same procedure it follows for encoding
|
|
filenames: (a) if <see cref="P:Ionic.Zip.ZipFile.AlternateEncodingUsage"/> is
|
|
<c>Never</c>, it uses the default encoding (IBM437). (b) if <see cref="P:Ionic.Zip.ZipFile.AlternateEncodingUsage"/> is <c>Always</c>, it always uses the
|
|
alternate encoding (<see cref="P:Ionic.Zip.ZipFile.AlternateEncoding"/>). (c) if <see cref="P:Ionic.Zip.ZipFile.AlternateEncodingUsage"/> is <c>AsNecessary</c>, it uses the
|
|
alternate encoding only if the default encoding is not sufficient for
|
|
encoding the comment - in other words if decoding the result does not
|
|
produce the original string. This decision is taken 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.AlternateEncoding"/> 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.AlternateEncoding"/> 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="P:Ionic.Zip.ZipFile.DefaultEncoding">DefaultEncoding</seealso>
|
|
</member>
|
|
<member name="P:Ionic.Zip.ZipFile.AlternateEncoding">
|
|
<summary>
|
|
A Text Encoding to use when encoding the filenames and comments for
|
|
all the ZipEntry items, during a ZipFile.Save() operation.
|
|
</summary>
|
|
<remarks>
|
|
<para>
|
|
Whether the encoding specified here is used during the save depends
|
|
on <see cref="P:Ionic.Zip.ZipFile.AlternateEncodingUsage"/>.
|
|
</para>
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.Zip.ZipFile.AlternateEncodingUsage">
|
|
<summary>
|
|
A flag that tells if and when this instance should apply
|
|
AlternateEncoding to encode the filenames and comments associated to
|
|
of ZipEntry objects contained within this instance.
|
|
</summary>
|
|
</member>
|
|
<member name="P: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="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 a limit to the size of
|
|
each file. 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>. According to the zip
|
|
specification from PKWare, the minimum value is 65536, for a 64k segment
|
|
size. The maximum number of segments allows in a split archive is 99.
|
|
</para>
|
|
|
|
<para>
|
|
The value of this property determines the maximum size of a split
|
|
segment when writing a split archive. 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 be as large as possible, up to
|
|
the maximum size set here. The zip specification requires that some data
|
|
fields in a zip archive may not span a split boundary, and an output
|
|
segment may be smaller than the maximum 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 yield slightly less compression when
|
|
compared to as single-threaded deflate; this is 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>
|
|
|
|
<seealso cref="P:Ionic.Zip.ZipFile.ParallelDeflateMaxBufferPairs"/>
|
|
|
|
</member>
|
|
<member name="P:Ionic.Zip.ZipFile.ParallelDeflateMaxBufferPairs">
|
|
<summary>
|
|
The maximum number of buffer pairs to use when performing
|
|
parallel compression.
|
|
</summary>
|
|
|
|
<remarks>
|
|
<para>
|
|
This property sets an upper limit on the number of memory
|
|
buffer pairs to create when performing parallel
|
|
compression. The implementation of the parallel
|
|
compression stream allocates multiple buffers to
|
|
facilitate parallel compression. As each buffer fills up,
|
|
the stream uses <see cref="M:System.Threading.ThreadPool.QueueUserWorkItem(System.Threading.WaitCallback)">
|
|
ThreadPool.QueueUserWorkItem()</see> to compress those
|
|
buffers in a background threadpool thread. After a buffer
|
|
is compressed, it is re-ordered and written to the output
|
|
stream.
|
|
</para>
|
|
|
|
<para>
|
|
A higher number of buffer pairs enables a higher degree of
|
|
parallelism, which tends to increase the speed of compression on
|
|
multi-cpu computers. On the other hand, a higher number of buffer
|
|
pairs also implies a larger memory consumption, more active worker
|
|
threads, and a higher cpu utilization for any compression. This
|
|
property enables the application to limit its memory consumption and
|
|
CPU utilization behavior depending on requirements.
|
|
</para>
|
|
|
|
<para>
|
|
For each compression "task" that occurs in parallel, there are 2
|
|
buffers allocated: one for input and one for output. This property
|
|
sets a limit for the number of pairs. The total amount of storage
|
|
space allocated for buffering will then be (N*S*2), where N is the
|
|
number of buffer pairs, S is the size of each buffer (<see cref="P:Ionic.Zip.ZipFile.BufferSize"/>). By default, DotNetZip allocates 4 buffer
|
|
pairs per CPU core, so if your machine has 4 cores, and you retain
|
|
the default buffer size of 128k, then the
|
|
ParallelDeflateOutputStream will use 4 * 4 * 2 * 128kb of buffer
|
|
memory in total, or 4mb, in blocks of 128kb. If you then set this
|
|
property to 8, then the number will be 8 * 2 * 128kb of buffer
|
|
memory, or 2mb.
|
|
</para>
|
|
|
|
<para>
|
|
CPU utilization will also go up with additional buffers, because a
|
|
larger number of buffer pairs allows a larger number of background
|
|
threads to compress in parallel. If you find that parallel
|
|
compression is consuming too much memory or CPU, you can adjust this
|
|
value downward.
|
|
</para>
|
|
|
|
<para>
|
|
The default value is 16. Different values may deliver better or
|
|
worse results, depending on your priorities and the dynamic
|
|
performance characteristics of your storage and compute resources.
|
|
</para>
|
|
|
|
<para>
|
|
This property is not the number of buffer pairs to use; it is an
|
|
upper limit. An illustration: Suppose you have an application that
|
|
uses the default value of this property (which is 16), and it runs
|
|
on a machine with 2 CPU cores. In that case, DotNetZip will allocate
|
|
4 buffer pairs per CPU core, for a total of 8 pairs. The upper
|
|
limit specified by this property has no effect.
|
|
</para>
|
|
|
|
<para>
|
|
The application can set this value at any time
|
|
before calling <c>ZipFile.Save()</c>.
|
|
</para>
|
|
</remarks>
|
|
|
|
<seealso cref="P:Ionic.Zip.ZipFile.ParallelDeflateThreshold"/>
|
|
|
|
</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<ZipEntry></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="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) => {
|
|
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 > 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 >> _progress2MaxFactor;
|
|
|
|
this.progressBar2.Value = (xferred >= 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, and to optionally cancel a lengthy 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>
|
|
|
|
<para>
|
|
In the case that you use <c>ZipErrorAction.Skip</c>, implying that
|
|
you want to skip the entry for which there's been an error, DotNetZip
|
|
tries to seek backwards in the output stream, and truncate all bytes
|
|
written on behalf of that particular entry. This works only if the
|
|
output stream is seekable. It will not work, for example, when using
|
|
ASPNET's Response.OutputStream.
|
|
</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 &&
|
|
response[0]!='S' && response[0]!='s' &&
|
|
response[0]!='R' && response[0]!='r' &&
|
|
response[0]!='T' && response[0]!='t' &&
|
|
response[0]!='C' && 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.ZipOption">
|
|
<summary>
|
|
An enum representing the values on a three-way toggle switch
|
|
for various options in the library. This might be used to
|
|
specify whether to employ a particular text encoding, or to use
|
|
ZIP64 extensions, or some other option.
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zip.ZipOption.Default">
|
|
<summary>
|
|
The default behavior. This is the same as "Never".
|
|
(For COM clients, this is a 0 (zero).)
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zip.ZipOption.Never">
|
|
<summary>
|
|
Never use the associated option.
|
|
(For COM clients, this is a 0 (zero).)
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zip.ZipOption.AsNecessary">
|
|
<summary>
|
|
Use the associated behavior "as necessary."
|
|
(For COM clients, this is a 1.)
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zip.ZipOption.Always">
|
|
<summary>
|
|
Use the associated behavior Always, whether necessary or not.
|
|
(For COM clients, this is a 2.)
|
|
</summary>
|
|
</member>
|
|
<member name="T:Ionic.Zip.ReadOptions">
|
|
<summary>
|
|
A class for collecting the various options that can be used when
|
|
Reading zip files for extraction or update.
|
|
</summary>
|
|
|
|
<remarks>
|
|
<para>
|
|
When reading a zip file, there are several options an
|
|
application can set, to modify how the file is read, or what
|
|
the library does while reading. This class collects those
|
|
options into one container.
|
|
</para>
|
|
|
|
<para>
|
|
Pass an instance of the <c>ReadOptions</c> class into the
|
|
<c>ZipFile.Read()</c> method.
|
|
</para>
|
|
|
|
<seealso cref="M:Ionic.Zip.ZipFile.Read(System.String,Ionic.Zip.ReadOptions)"/>.
|
|
<seealso cref="M:Ionic.Zip.ZipFile.Read(System.IO.Stream,Ionic.Zip.ReadOptions)"/>.
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.Zip.ReadOptions.ReadProgress">
|
|
<summary>
|
|
An event handler for Read operations. When opening large zip
|
|
archives, you may want to display a progress bar or other
|
|
indicator of status progress while reading. This parameter
|
|
allows you to specify a ReadProgress Event Handler directly.
|
|
When you call <c>Read()</c>, the progress event is invoked as
|
|
necessary.
|
|
</summary>
|
|
</member>
|
|
<member name="P:Ionic.Zip.ReadOptions.StatusMessageWriter">
|
|
<summary>
|
|
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>.
|
|
</summary>
|
|
</member>
|
|
<member name="P:Ionic.Zip.ReadOptions.Encoding">
|
|
<summary>
|
|
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.
|
|
</summary>
|
|
|
|
<seealso cref="P:Ionic.Zip.ZipFile.ProvisionalAlternateEncoding"/>
|
|
|
|
</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. The user running such an EXE will see a console window
|
|
appear, then disappear quickly. 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><para>no messages will be emitted during successful
|
|
operation.</para> <para> Double-clicking the SFX in Windows
|
|
Explorer or as an attachment in an email will cause a console
|
|
window to appear briefly, before it disappears. If you run the
|
|
ConsoleApplication SFX from the cmd.exe prompt, it runs as a
|
|
normal console app; by default, because it is quiet, it displays
|
|
no messages to the console. If you pass the -v+ command line
|
|
argument to the Console SFX when you run it, you will get verbose
|
|
messages to the console. </para>
|
|
</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><para>the extractor will emit a
|
|
message to the console for each entry extracted.</para>
|
|
<para>
|
|
When double-clicking to launch the SFX, the console window will
|
|
remain, and the SFX will emit a message for each file as it
|
|
extracts. The messages fly by quickly, they won't be easily
|
|
readable, unless the extracted files are fairly large.
|
|
</para>
|
|
</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
|
|
PostExtractCommandLine.
|
|
</summary>
|
|
|
|
<remarks>
|
|
<para>
|
|
If true, and if there is a <see cref="P:Ionic.Zip.SelfExtractorSaveOptions.PostExtractCommandLine">
|
|
PostExtractCommandLine</see>, 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),
|
|
that is interpreted as a failure, and the extracted 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 2011".
|
|
</remarks>
|
|
|
|
</member>
|
|
<member name="P:Ionic.Zip.SelfExtractorSaveOptions.Description">
|
|
<summary>
|
|
The description to embed into the generated EXE.
|
|
</summary>
|
|
|
|
<remarks>
|
|
Use any arbitrary string. This text will be displayed 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. This text will be displayed
|
|
while viewing properties of the EXE file in
|
|
Windows Explorer.
|
|
</remarks>
|
|
|
|
</member>
|
|
<member name="P:Ionic.Zip.SelfExtractorSaveOptions.SfxExeWindowTitle">
|
|
<summary>
|
|
The title to display in the Window of a GUI SFX, while it extracts.
|
|
</summary>
|
|
|
|
<remarks>
|
|
<para>
|
|
By default the title show in the GUI window of a self-extractor
|
|
is "DotNetZip Self-extractor (http://DotNetZip.codeplex.com/)".
|
|
You can change that by setting this property before saving the SFX.
|
|
</para>
|
|
|
|
<para>
|
|
This property has an effect only when producing a Self-extractor
|
|
of flavor <c>SelfExtractorFlavor.WinFormsApplication</c>.
|
|
</para>
|
|
</remarks>
|
|
|
|
</member>
|
|
<member name="P:Ionic.Zip.SelfExtractorSaveOptions.AdditionalCompilerSwitches">
|
|
<summary>
|
|
Additional options for the csc.exe compiler, when producing the SFX
|
|
EXE.
|
|
</summary>
|
|
<exclude/>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BitWriter.Reset">
|
|
<summary>
|
|
Reset the BitWriter.
|
|
</summary>
|
|
<remarks>
|
|
<para>
|
|
This is useful when the BitWriter writes into a MemoryStream, and
|
|
is used by a BZip2Compressor, which itself is re-used for multiple
|
|
distinct data blocks.
|
|
</para>
|
|
</remarks>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BitWriter.WriteBits(System.Int32,System.UInt32)">
|
|
<summary>
|
|
Write some number of bits from the given value, into the output.
|
|
</summary>
|
|
<remarks>
|
|
<para>
|
|
The nbits value should be a max of 25, for safety. For performance
|
|
reasons, this method does not check!
|
|
</para>
|
|
</remarks>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BitWriter.WriteByte(System.Byte)">
|
|
<summary>
|
|
Write a full 8-bit byte into the output.
|
|
</summary>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BitWriter.WriteInt(System.UInt32)">
|
|
<summary>
|
|
Write four 8-bit bytes into the output.
|
|
</summary>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BitWriter.Flush">
|
|
<summary>
|
|
Write all available byte-aligned bytes.
|
|
</summary>
|
|
<remarks>
|
|
<para>
|
|
This method writes no new output, but flushes any accumulated
|
|
bits. At completion, the accumulator may contain up to 7
|
|
bits.
|
|
</para>
|
|
<para>
|
|
This is necessary when re-assembling output from N independent
|
|
compressors, one for each of N blocks. The output of any
|
|
particular compressor will in general have some fragment of a byte
|
|
remaining. This fragment needs to be accumulated into the
|
|
parent BZip2OutputStream.
|
|
</para>
|
|
</remarks>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BitWriter.FinishAndPad">
|
|
<summary>
|
|
Writes all available bytes, and emits padding for the final byte as
|
|
necessary. This must be the last method invoked on an instance of
|
|
BitWriter.
|
|
</summary>
|
|
</member>
|
|
<member name="P:Ionic.BZip2.BitWriter.RemainingBits">
|
|
<summary>
|
|
Delivers the remaining bits, left-aligned, in a byte.
|
|
</summary>
|
|
<remarks>
|
|
<para>
|
|
This is valid only if NumRemainingBits is less than 8;
|
|
in other words it is valid only after a call to Flush().
|
|
</para>
|
|
</remarks>
|
|
</member>
|
|
<member name="F:Ionic.BZip2.BZip2Compressor.increments">
|
|
Knuth's increments seem to work better than Incerpi-Sedgewick here.
|
|
Possibly because the number of elems to sort is usually small, typically
|
|
<= 20.
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BZip2Compressor.#ctor(Ionic.BZip2.BitWriter)">
|
|
<summary>
|
|
BZip2Compressor writes its compressed data out via a BitWriter. This
|
|
is necessary because BZip2 does byte shredding.
|
|
</summary>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BZip2Compressor.Fill(System.Byte[],System.Int32,System.Int32)">
|
|
<summary>
|
|
Accept new bytes into the compressor data buffer
|
|
</summary>
|
|
<remarks>
|
|
<para>
|
|
This method does the first-level (cheap) run-length encoding, and
|
|
stores the encoded data into the rle block.
|
|
</para>
|
|
</remarks>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BZip2Compressor.write0(System.Byte)">
|
|
<summary>
|
|
Process one input byte into the block.
|
|
</summary>
|
|
|
|
<remarks>
|
|
<para>
|
|
To "process" the byte means to do the run-length encoding.
|
|
There are 3 possible return values:
|
|
|
|
0 - the byte was not written, in other words, not
|
|
encoded into the block. This happens when the
|
|
byte b would require the start of a new run, and
|
|
the block has no more room for new runs.
|
|
|
|
1 - the byte was written, and the block is not full.
|
|
|
|
2 - the byte was written, and the block is full.
|
|
|
|
</para>
|
|
</remarks>
|
|
<returns>0 if the byte was not written, non-zero if written.</returns>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BZip2Compressor.AddRunToOutputBlock(System.Boolean)">
|
|
<summary>
|
|
Append one run to the output block.
|
|
</summary>
|
|
|
|
<remarks>
|
|
<para>
|
|
This compressor does run-length-encoding before BWT and etc. This
|
|
method simply appends a run to the output block. The append always
|
|
succeeds. The return value indicates whether the block is full:
|
|
false (not full) implies that at least one additional run could be
|
|
processed.
|
|
</para>
|
|
</remarks>
|
|
<returns>true if the block is now full; otherwise false.</returns>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BZip2Compressor.CompressAndWrite">
|
|
<summary>
|
|
Compress the data that has been placed (Run-length-encoded) into the
|
|
block. The compressed data goes into the CompressedBytes array.
|
|
</summary>
|
|
<remarks>
|
|
<para>
|
|
Side effects: 1. fills the CompressedBytes array. 2. sets the
|
|
AvailableBytesOut property.
|
|
</para>
|
|
</remarks>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BZip2Compressor.mainSimpleSort(Ionic.BZip2.BZip2Compressor.CompressionState,System.Int32,System.Int32,System.Int32)">
|
|
This is the most hammered method of this class.
|
|
|
|
<p>
|
|
This is the version using unrolled loops.
|
|
</p>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BZip2Compressor.mainQSort3(Ionic.BZip2.BZip2Compressor.CompressionState,System.Int32,System.Int32,System.Int32)">
|
|
Method "mainQSort3", file "blocksort.c", BZip2 1.0.2
|
|
</member>
|
|
<member name="P:Ionic.BZip2.BZip2Compressor.UncompressedBytes">
|
|
<summary>
|
|
The number of uncompressed bytes being held in the buffer.
|
|
</summary>
|
|
<remarks>
|
|
<para>
|
|
I am thinking this may be useful in a Stream that uses this
|
|
compressor class. In the Close() method on the stream it could
|
|
check this value to see if anything has been written at all. You
|
|
may think the stream could easily track the number of bytes it
|
|
wrote, which would eliminate the need for this. But, there is the
|
|
case where the stream writes a complete block, and it is full, and
|
|
then writes no more. In that case the stream may want to check.
|
|
</para>
|
|
</remarks>
|
|
</member>
|
|
<member name="F:Ionic.BZip2.BZip2Compressor.CompressionState.quadrant">
|
|
Array instance identical to sfmap, both are used only
|
|
temporarily and independently, so we do not need to allocate
|
|
additional memory.
|
|
</member>
|
|
<member name="T:Ionic.BZip2.BZip2InputStream">
|
|
<summary>
|
|
A read-only decorator stream that performs BZip2 decompression on Read.
|
|
</summary>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BZip2InputStream.#ctor(System.IO.Stream)">
|
|
<summary>
|
|
Create a BZip2InputStream, wrapping it around the given input Stream.
|
|
</summary>
|
|
<remarks>
|
|
<para>
|
|
The input stream will be closed when the BZip2InputStream is closed.
|
|
</para>
|
|
</remarks>
|
|
<param name='input'>The stream from which to read compressed data</param>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BZip2InputStream.#ctor(System.IO.Stream,System.Boolean)">
|
|
<summary>
|
|
Create a BZip2InputStream with the given stream, and
|
|
specifying whether to leave the wrapped stream open when
|
|
the BZip2InputStream is closed.
|
|
</summary>
|
|
<param name='input'>The stream from which to read compressed data</param>
|
|
<param name='leaveOpen'>
|
|
Whether to leave the input stream open, when the BZip2InputStream closes.
|
|
</param>
|
|
|
|
<example>
|
|
|
|
This example reads a bzip2-compressed file, decompresses it,
|
|
and writes the decompressed data into a newly created file.
|
|
|
|
<code>
|
|
var fname = "logfile.log.bz2";
|
|
using (var fs = File.OpenRead(fname))
|
|
{
|
|
using (var decompressor = new Ionic.BZip2.BZip2InputStream(fs))
|
|
{
|
|
var outFname = fname + ".decompressed";
|
|
using (var output = File.Create(outFname))
|
|
{
|
|
byte[] buffer = new byte[2048];
|
|
int n;
|
|
while ((n = decompressor.Read(buffer, 0, buffer.Length)) > 0)
|
|
{
|
|
output.Write(buffer, 0, n);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
</code>
|
|
</example>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BZip2InputStream.Read(System.Byte[],System.Int32,System.Int32)">
|
|
<summary>
|
|
Read data from the stream.
|
|
</summary>
|
|
|
|
<remarks>
|
|
<para>
|
|
To decompress a BZip2 data stream, create a <c>BZip2InputStream</c>,
|
|
providing a stream that reads compressed data. Then call Read() on
|
|
that <c>BZip2InputStream</c>, and the data read will be decompressed
|
|
as you read.
|
|
</para>
|
|
|
|
<para>
|
|
A <c>BZip2InputStream</c> can be used only for <c>Read()</c>, not for <c>Write()</c>.
|
|
</para>
|
|
</remarks>
|
|
|
|
<param name="buffer">The buffer into which the read data should be placed.</param>
|
|
<param name="offset">the offset within that data array to put the first byte read.</param>
|
|
<param name="count">the number of bytes to read.</param>
|
|
<returns>the number of bytes actually read</returns>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BZip2InputStream.ReadByte">
|
|
<summary>
|
|
Read a single byte from the stream.
|
|
</summary>
|
|
<returns>the byte read from the stream, or -1 if EOF</returns>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BZip2InputStream.Flush">
|
|
<summary>
|
|
Flush the stream.
|
|
</summary>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BZip2InputStream.Seek(System.Int64,System.IO.SeekOrigin)">
|
|
<summary>
|
|
Calling this method always throws a <see cref="T:System.NotImplementedException"/>.
|
|
</summary>
|
|
<param name="offset">this is irrelevant, since it will always throw!</param>
|
|
<param name="origin">this is irrelevant, since it will always throw!</param>
|
|
<returns>irrelevant!</returns>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BZip2InputStream.SetLength(System.Int64)">
|
|
<summary>
|
|
Calling this method always throws a <see cref="T:System.NotImplementedException"/>.
|
|
</summary>
|
|
<param name="value">this is irrelevant, since it will always throw!</param>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BZip2InputStream.Write(System.Byte[],System.Int32,System.Int32)">
|
|
<summary>
|
|
Calling this method always throws a <see cref="T:System.NotImplementedException"/>.
|
|
</summary>
|
|
<param name="buffer">this parameter is never used</param>
|
|
<param name="offset">this parameter is never used</param>
|
|
<param name="count">this parameter is never used</param>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BZip2InputStream.Dispose(System.Boolean)">
|
|
<summary>
|
|
Dispose the stream.
|
|
</summary>
|
|
<param name="disposing">
|
|
indicates whether the Dispose method was invoked by user code.
|
|
</param>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BZip2InputStream.Close">
|
|
<summary>
|
|
Close the stream.
|
|
</summary>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BZip2InputStream.GetBits(System.Int32)">
|
|
<summary>
|
|
Read n bits from input, right justifying the result.
|
|
</summary>
|
|
<remarks>
|
|
<para>
|
|
For example, if you read 1 bit, the result is either 0
|
|
or 1.
|
|
</para>
|
|
</remarks>
|
|
<param name ="n">
|
|
The number of bits to read, always between 1 and 32.
|
|
</param>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BZip2InputStream.hbCreateDecodeTables(System.Int32[],System.Int32[],System.Int32[],System.Char[],System.Int32,System.Int32,System.Int32)">
|
|
Called by createHuffmanDecodingTables() exclusively.
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BZip2InputStream.createHuffmanDecodingTables(System.Int32,System.Int32)">
|
|
Called by recvDecodingTables() exclusively.
|
|
</member>
|
|
<member name="P:Ionic.BZip2.BZip2InputStream.CanRead">
|
|
<summary>
|
|
Indicates whether the stream can be read.
|
|
</summary>
|
|
<remarks>
|
|
The return value depends on whether the captive stream supports reading.
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.BZip2.BZip2InputStream.CanSeek">
|
|
<summary>
|
|
Indicates whether the stream supports Seek operations.
|
|
</summary>
|
|
<remarks>
|
|
Always returns false.
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.BZip2.BZip2InputStream.CanWrite">
|
|
<summary>
|
|
Indicates whether the stream can be written.
|
|
</summary>
|
|
<remarks>
|
|
The return value depends on whether the captive stream supports writing.
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.BZip2.BZip2InputStream.Length">
|
|
<summary>
|
|
Reading this property always throws a <see cref="T:System.NotImplementedException"/>.
|
|
</summary>
|
|
</member>
|
|
<member name="P:Ionic.BZip2.BZip2InputStream.Position">
|
|
<summary>
|
|
The position of the stream pointer.
|
|
</summary>
|
|
|
|
<remarks>
|
|
Setting this property always throws a <see cref="T:System.NotImplementedException"/>. Reading will return the
|
|
total number of uncompressed bytes read in.
|
|
</remarks>
|
|
</member>
|
|
<member name="T:Ionic.BZip2.BZip2InputStream.CState">
|
|
<summary>
|
|
Compressor State
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.BZip2.BZip2InputStream.DecompressionState.unzftab">
|
|
Freq table collected to save a pass over the data during
|
|
decompression.
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BZip2InputStream.DecompressionState.initTT(System.Int32)">
|
|
Initializes the tt array.
|
|
|
|
This method is called when the required length of the array is known.
|
|
I don't initialize it at construction time to avoid unneccessary
|
|
memory allocation when compressing small files.
|
|
</member>
|
|
<member name="T:Ionic.BZip2.BZip2OutputStream">
|
|
<summary>
|
|
A write-only decorator stream that compresses data as it is
|
|
written using the BZip2 algorithm.
|
|
</summary>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BZip2OutputStream.#ctor(System.IO.Stream)">
|
|
<summary>
|
|
Constructs a new <c>BZip2OutputStream</c>, that sends its
|
|
compressed output to the given output stream.
|
|
</summary>
|
|
|
|
<param name='output'>
|
|
The destination stream, to which compressed output will be sent.
|
|
</param>
|
|
|
|
<example>
|
|
|
|
This example reads a file, then compresses it with bzip2 file,
|
|
and writes the compressed data into a newly created file.
|
|
|
|
<code>
|
|
var fname = "logfile.log";
|
|
using (var fs = File.OpenRead(fname))
|
|
{
|
|
var outFname = fname + ".bz2";
|
|
using (var output = File.Create(outFname))
|
|
{
|
|
using (var compressor = new Ionic.BZip2.BZip2OutputStream(output))
|
|
{
|
|
byte[] buffer = new byte[2048];
|
|
int n;
|
|
while ((n = fs.Read(buffer, 0, buffer.Length)) > 0)
|
|
{
|
|
compressor.Write(buffer, 0, n);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
</code>
|
|
</example>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BZip2OutputStream.#ctor(System.IO.Stream,System.Int32)">
|
|
<summary>
|
|
Constructs a new <c>BZip2OutputStream</c> with specified blocksize.
|
|
</summary>
|
|
<param name = "output">the destination stream.</param>
|
|
<param name = "blockSize">
|
|
The blockSize in units of 100000 bytes.
|
|
The valid range is 1..9.
|
|
</param>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BZip2OutputStream.#ctor(System.IO.Stream,System.Boolean)">
|
|
<summary>
|
|
Constructs a new <c>BZip2OutputStream</c>.
|
|
</summary>
|
|
<param name = "output">the destination stream.</param>
|
|
<param name = "leaveOpen">
|
|
whether to leave the captive stream open upon closing this stream.
|
|
</param>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BZip2OutputStream.#ctor(System.IO.Stream,System.Int32,System.Boolean)">
|
|
<summary>
|
|
Constructs a new <c>BZip2OutputStream</c> with specified blocksize,
|
|
and explicitly specifies whether to leave the wrapped stream open.
|
|
</summary>
|
|
|
|
<param name = "output">the destination stream.</param>
|
|
<param name = "blockSize">
|
|
The blockSize in units of 100000 bytes.
|
|
The valid range is 1..9.
|
|
</param>
|
|
<param name = "leaveOpen">
|
|
whether to leave the captive stream open upon closing this stream.
|
|
</param>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BZip2OutputStream.Close">
|
|
<summary>
|
|
Close the stream.
|
|
</summary>
|
|
<remarks>
|
|
<para>
|
|
This may or may not close the underlying stream. Check the
|
|
constructors that accept a bool value.
|
|
</para>
|
|
</remarks>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BZip2OutputStream.Flush">
|
|
<summary>
|
|
Flush the stream.
|
|
</summary>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BZip2OutputStream.Write(System.Byte[],System.Int32,System.Int32)">
|
|
<summary>
|
|
Write data to the stream.
|
|
</summary>
|
|
<remarks>
|
|
|
|
<para>
|
|
Use the <c>BZip2OutputStream</c> to compress data while writing:
|
|
create a <c>BZip2OutputStream</c> with a writable output stream.
|
|
Then call <c>Write()</c> on that <c>BZip2OutputStream</c>, providing
|
|
uncompressed data as input. The data sent to the output stream will
|
|
be the compressed form of the input data.
|
|
</para>
|
|
|
|
<para>
|
|
A <c>BZip2OutputStream</c> can be used only for <c>Write()</c> not for <c>Read()</c>.
|
|
</para>
|
|
|
|
</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.BZip2.BZip2OutputStream.Seek(System.Int64,System.IO.SeekOrigin)">
|
|
<summary>
|
|
Calling this method always throws a <see cref="T:System.NotImplementedException"/>.
|
|
</summary>
|
|
<param name="offset">this is irrelevant, since it will always throw!</param>
|
|
<param name="origin">this is irrelevant, since it will always throw!</param>
|
|
<returns>irrelevant!</returns>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BZip2OutputStream.SetLength(System.Int64)">
|
|
<summary>
|
|
Calling this method always throws a <see cref="T:System.NotImplementedException"/>.
|
|
</summary>
|
|
<param name="value">this is irrelevant, since it will always throw!</param>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.BZip2OutputStream.Read(System.Byte[],System.Int32,System.Int32)">
|
|
<summary>
|
|
Calling this method always throws a <see cref="T:System.NotImplementedException"/>.
|
|
</summary>
|
|
<param name="buffer">this parameter is never used</param>
|
|
<param name="offset">this parameter is never used</param>
|
|
<param name="count">this parameter is never used</param>
|
|
<returns>never returns anything; always throws</returns>
|
|
</member>
|
|
<member name="P:Ionic.BZip2.BZip2OutputStream.BlockSize">
|
|
<summary>
|
|
The blocksize parameter specified at construction time.
|
|
</summary>
|
|
</member>
|
|
<member name="P:Ionic.BZip2.BZip2OutputStream.CanRead">
|
|
<summary>
|
|
Indicates whether the stream can be read.
|
|
</summary>
|
|
<remarks>
|
|
The return value is always false.
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.BZip2.BZip2OutputStream.CanSeek">
|
|
<summary>
|
|
Indicates whether the stream supports Seek operations.
|
|
</summary>
|
|
<remarks>
|
|
Always returns false.
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.BZip2.BZip2OutputStream.CanWrite">
|
|
<summary>
|
|
Indicates whether the stream can be written.
|
|
</summary>
|
|
<remarks>
|
|
The return value should always be true, unless and until the
|
|
object is disposed and closed.
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.BZip2.BZip2OutputStream.Length">
|
|
<summary>
|
|
Reading this property always throws a <see cref="T:System.NotImplementedException"/>.
|
|
</summary>
|
|
</member>
|
|
<member name="P:Ionic.BZip2.BZip2OutputStream.Position">
|
|
<summary>
|
|
The position of the stream pointer.
|
|
</summary>
|
|
|
|
<remarks>
|
|
Setting this property always throws a <see cref="T:System.NotImplementedException"/>. Reading will return the
|
|
total number of uncompressed bytes written through.
|
|
</remarks>
|
|
</member>
|
|
<member name="T:Ionic.BZip2.ParallelBZip2OutputStream">
|
|
<summary>
|
|
A write-only decorator stream that compresses data as it is
|
|
written using the BZip2 algorithm. This stream compresses by
|
|
block using multiple threads.
|
|
</summary>
|
|
<para>
|
|
This class performs BZIP2 compression through writing. For
|
|
more information on the BZIP2 algorithm, see
|
|
<see href="http://en.wikipedia.org/wiki/BZIP2"/>.
|
|
</para>
|
|
|
|
<para>
|
|
This class is similar to <see cref="T:Ionic.BZip2.BZip2OutputStream"/>,
|
|
except that this implementation uses an approach that employs multiple
|
|
worker threads to perform the compression. On a multi-cpu or multi-core
|
|
computer, the performance of this class can be significantly higher than
|
|
the single-threaded BZip2OutputStream, particularly for larger streams.
|
|
How large? Anything over 10mb is a good candidate for parallel
|
|
compression.
|
|
</para>
|
|
|
|
<para>
|
|
The tradeoff is that this class uses more memory and more CPU than the
|
|
vanilla <c>BZip2OutputStream</c>. Also, for small files, the
|
|
<c>ParallelBZip2OutputStream</c> can be much slower than the vanilla
|
|
<c>BZip2OutputStream</c>, because of the overhead associated to using the
|
|
thread pool.
|
|
</para>
|
|
|
|
<seealso cref="T:Ionic.BZip2.BZip2OutputStream"/>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.ParallelBZip2OutputStream.#ctor(System.IO.Stream)">
|
|
<summary>
|
|
Constructs a new <c>ParallelBZip2OutputStream</c>, that sends its
|
|
compressed output to the given output stream.
|
|
</summary>
|
|
|
|
<param name='output'>
|
|
The destination stream, to which compressed output will be sent.
|
|
</param>
|
|
|
|
<example>
|
|
|
|
This example reads a file, then compresses it with bzip2 file,
|
|
and writes the compressed data into a newly created file.
|
|
|
|
<code>
|
|
var fname = "logfile.log";
|
|
using (var fs = File.OpenRead(fname))
|
|
{
|
|
var outFname = fname + ".bz2";
|
|
using (var output = File.Create(outFname))
|
|
{
|
|
using (var compressor = new Ionic.BZip2.ParallelBZip2OutputStream(output))
|
|
{
|
|
byte[] buffer = new byte[2048];
|
|
int n;
|
|
while ((n = fs.Read(buffer, 0, buffer.Length)) > 0)
|
|
{
|
|
compressor.Write(buffer, 0, n);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
</code>
|
|
</example>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.ParallelBZip2OutputStream.#ctor(System.IO.Stream,System.Int32)">
|
|
<summary>
|
|
Constructs a new <c>ParallelBZip2OutputStream</c> with specified blocksize.
|
|
</summary>
|
|
<param name = "output">the destination stream.</param>
|
|
<param name = "blockSize">
|
|
The blockSize in units of 100000 bytes.
|
|
The valid range is 1..9.
|
|
</param>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.ParallelBZip2OutputStream.#ctor(System.IO.Stream,System.Boolean)">
|
|
<summary>
|
|
Constructs a new <c>ParallelBZip2OutputStream</c>.
|
|
</summary>
|
|
<param name = "output">the destination stream.</param>
|
|
<param name = "leaveOpen">
|
|
whether to leave the captive stream open upon closing this stream.
|
|
</param>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.ParallelBZip2OutputStream.#ctor(System.IO.Stream,System.Int32,System.Boolean)">
|
|
<summary>
|
|
Constructs a new <c>ParallelBZip2OutputStream</c> with specified blocksize,
|
|
and explicitly specifies whether to leave the wrapped stream open.
|
|
</summary>
|
|
|
|
<param name = "output">the destination stream.</param>
|
|
<param name = "blockSize">
|
|
The blockSize in units of 100000 bytes.
|
|
The valid range is 1..9.
|
|
</param>
|
|
<param name = "leaveOpen">
|
|
whether to leave the captive stream open upon closing this stream.
|
|
</param>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.ParallelBZip2OutputStream.Close">
|
|
<summary>
|
|
Close the stream.
|
|
</summary>
|
|
<remarks>
|
|
<para>
|
|
This may or may not close the underlying stream. Check the
|
|
constructors that accept a bool value.
|
|
</para>
|
|
</remarks>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.ParallelBZip2OutputStream.Flush">
|
|
<summary>
|
|
Flush the stream.
|
|
</summary>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.ParallelBZip2OutputStream.Write(System.Byte[],System.Int32,System.Int32)">
|
|
<summary>
|
|
Write data to the stream.
|
|
</summary>
|
|
<remarks>
|
|
|
|
<para>
|
|
Use the <c>ParallelBZip2OutputStream</c> to compress data while
|
|
writing: create a <c>ParallelBZip2OutputStream</c> with a writable
|
|
output stream. Then call <c>Write()</c> on that
|
|
<c>ParallelBZip2OutputStream</c>, providing uncompressed data as
|
|
input. The data sent to the output stream will be the compressed
|
|
form of the input data.
|
|
</para>
|
|
|
|
<para>
|
|
A <c>ParallelBZip2OutputStream</c> can be used only for
|
|
<c>Write()</c> not for <c>Read()</c>.
|
|
</para>
|
|
|
|
</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.BZip2.ParallelBZip2OutputStream.Seek(System.Int64,System.IO.SeekOrigin)">
|
|
<summary>
|
|
Calling this method always throws a <see cref="T:System.NotImplementedException"/>.
|
|
</summary>
|
|
<param name="offset">this is irrelevant, since it will always throw!</param>
|
|
<param name="origin">this is irrelevant, since it will always throw!</param>
|
|
<returns>irrelevant!</returns>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.ParallelBZip2OutputStream.SetLength(System.Int64)">
|
|
<summary>
|
|
Calling this method always throws a <see cref="T:System.NotImplementedException"/>.
|
|
</summary>
|
|
<param name="value">this is irrelevant, since it will always throw!</param>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.ParallelBZip2OutputStream.Read(System.Byte[],System.Int32,System.Int32)">
|
|
<summary>
|
|
Calling this method always throws a <see cref="T:System.NotImplementedException"/>.
|
|
</summary>
|
|
<param name="buffer">this parameter is never used</param>
|
|
<param name="offset">this parameter is never used</param>
|
|
<param name="count">this parameter is never used</param>
|
|
<returns>never returns anything; always throws</returns>
|
|
</member>
|
|
<member name="P:Ionic.BZip2.ParallelBZip2OutputStream.MaxWorkers">
|
|
<summary>
|
|
The maximum number of concurrent compression worker threads to use.
|
|
</summary>
|
|
|
|
<remarks>
|
|
<para>
|
|
This property sets an upper limit on the number of concurrent worker
|
|
threads to employ for compression. The implementation of this stream
|
|
employs multiple threads from the .NET thread pool, via <see cref="M:System.Threading.ThreadPool.QueueUserWorkItem(System.Threading.WaitCallback)">
|
|
ThreadPool.QueueUserWorkItem()</see>, to compress the incoming data by
|
|
block. As each block of data is compressed, this stream re-orders the
|
|
compressed blocks and writes them to the output stream.
|
|
</para>
|
|
|
|
<para>
|
|
A higher number of workers enables a higher degree of
|
|
parallelism, which tends to increase the speed of compression on
|
|
multi-cpu computers. On the other hand, a higher number of buffer
|
|
pairs also implies a larger memory consumption, more active worker
|
|
threads, and a higher cpu utilization for any compression. This
|
|
property enables the application to limit its memory consumption and
|
|
CPU utilization behavior depending on requirements.
|
|
</para>
|
|
|
|
<para>
|
|
By default, DotNetZip allocates 4 workers per CPU core, subject to the
|
|
upper limit specified in this property. For example, suppose the
|
|
application sets this property to 16. Then, on a machine with 2
|
|
cores, DotNetZip will use 8 workers; that number does not exceed the
|
|
upper limit specified by this property, so the actual number of
|
|
workers used will be 4 * 2 = 8. On a machine with 4 cores, DotNetZip
|
|
will use 16 workers; again, the limit does not apply. On a machine
|
|
with 8 cores, DotNetZip will use 16 workers, because of the limit.
|
|
</para>
|
|
|
|
<para>
|
|
For each compression "worker thread" that occurs in parallel, there is
|
|
up to 2mb of memory allocated, for buffering and processing. The
|
|
actual number depends on the <see cref="P:Ionic.BZip2.ParallelBZip2OutputStream.BlockSize"/> property.
|
|
</para>
|
|
|
|
<para>
|
|
CPU utilization will also go up with additional workers, because a
|
|
larger number of buffer pairs allows a larger number of background
|
|
threads to compress in parallel. If you find that parallel
|
|
compression is consuming too much memory or CPU, you can adjust this
|
|
value downward.
|
|
</para>
|
|
|
|
<para>
|
|
The default value is 16. Different values may deliver better or
|
|
worse results, depending on your priorities and the dynamic
|
|
performance characteristics of your storage and compute resources.
|
|
</para>
|
|
|
|
<para>
|
|
The application can set this value at any time, but it is effective
|
|
only before the first call to Write(), which is when the buffers are
|
|
allocated.
|
|
</para>
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.BZip2.ParallelBZip2OutputStream.BlockSize">
|
|
<summary>
|
|
The blocksize parameter specified at construction time.
|
|
</summary>
|
|
</member>
|
|
<member name="P:Ionic.BZip2.ParallelBZip2OutputStream.CanRead">
|
|
<summary>
|
|
Indicates whether the stream can be read.
|
|
</summary>
|
|
<remarks>
|
|
The return value is always false.
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.BZip2.ParallelBZip2OutputStream.CanSeek">
|
|
<summary>
|
|
Indicates whether the stream supports Seek operations.
|
|
</summary>
|
|
<remarks>
|
|
Always returns false.
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.BZip2.ParallelBZip2OutputStream.CanWrite">
|
|
<summary>
|
|
Indicates whether the stream can be written.
|
|
</summary>
|
|
<remarks>
|
|
The return value depends on whether the captive stream supports writing.
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.BZip2.ParallelBZip2OutputStream.Length">
|
|
<summary>
|
|
Reading this property always throws a <see cref="T:System.NotImplementedException"/>.
|
|
</summary>
|
|
</member>
|
|
<member name="P:Ionic.BZip2.ParallelBZip2OutputStream.Position">
|
|
<summary>
|
|
The position of the stream pointer.
|
|
</summary>
|
|
|
|
<remarks>
|
|
Setting this property always throws a <see cref="T:System.NotImplementedException"/>. Reading will return the
|
|
total number of uncompressed bytes written through.
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.BZip2.ParallelBZip2OutputStream.BytesWrittenOut">
|
|
<summary>
|
|
The total number of bytes written out by the stream.
|
|
</summary>
|
|
<remarks>
|
|
This value is meaningful only after a call to Close().
|
|
</remarks>
|
|
</member>
|
|
<member name="M:Ionic.BZip2.Rand.Rnums(System.Int32)">
|
|
<summary>
|
|
Returns the "random" number at a specific index.
|
|
</summary>
|
|
<param name='i'>the index</param>
|
|
<returns>the random number</returns>
|
|
</member>
|
|
<member name="T:Ionic.Zlib.DeflateStream">
|
|
<summary>
|
|
A class for compressing and decompressing streams using the Deflate algorithm.
|
|
</summary>
|
|
|
|
<remarks>
|
|
|
|
<para>
|
|
The DeflateStream is a <see href="http://en.wikipedia.org/wiki/Decorator_pattern">Decorator</see> on a <see cref="T:System.IO.Stream"/>. It adds DEFLATE compression or decompression to any
|
|
stream.
|
|
</para>
|
|
|
|
<para>
|
|
Using this stream, applications can compress or decompress data via stream
|
|
<c>Read</c> and <c>Write</c> operations. Either compresssion or decompression
|
|
can occur through either reading or writing. The compression format used is
|
|
DEFLATE, which is documented in <see href="http://www.ietf.org/rfc/rfc1951.txt">IETF RFC 1951</see>, "DEFLATE
|
|
Compressed Data Format Specification version 1.3.".
|
|
</para>
|
|
|
|
<para>
|
|
This class is similar to <see cref="T:Ionic.Zlib.ZlibStream"/>, except that
|
|
<c>ZlibStream</c> adds the <see href="http://www.ietf.org/rfc/rfc1950.txt">RFC
|
|
1950 - ZLIB</see> framing bytes to a compressed stream when compressing, or
|
|
expects the RFC1950 framing bytes when decompressing. The <c>DeflateStream</c>
|
|
does not.
|
|
</para>
|
|
|
|
</remarks>
|
|
|
|
<seealso cref="T:Ionic.Zlib.ZlibStream"/>
|
|
<seealso cref="T:Ionic.Zlib.GZipStream"/>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.DeflateStream.#ctor(System.IO.Stream,Ionic.Zlib.CompressionMode)">
|
|
<summary>
|
|
Create a DeflateStream using the specified CompressionMode.
|
|
</summary>
|
|
|
|
<remarks>
|
|
When mode is <c>CompressionMode.Compress</c>, the DeflateStream will use
|
|
the default compression level. The "captive" stream will be closed when
|
|
the DeflateStream is closed.
|
|
</remarks>
|
|
|
|
<example>
|
|
This example uses a DeflateStream to compress data from a file, and writes
|
|
the compressed data to another file.
|
|
<code>
|
|
using (System.IO.Stream input = System.IO.File.OpenRead(fileToCompress))
|
|
{
|
|
using (var raw = System.IO.File.Create(fileToCompress + ".deflated"))
|
|
{
|
|
using (Stream compressor = new DeflateStream(raw, CompressionMode.Compress))
|
|
{
|
|
byte[] buffer = new byte[WORKING_BUFFER_SIZE];
|
|
int n;
|
|
while ((n= input.Read(buffer, 0, buffer.Length)) != 0)
|
|
{
|
|
compressor.Write(buffer, 0, n);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
</code>
|
|
|
|
<code lang="VB">
|
|
Using input As Stream = File.OpenRead(fileToCompress)
|
|
Using raw As FileStream = File.Create(fileToCompress & ".deflated")
|
|
Using compressor As Stream = New DeflateStream(raw, CompressionMode.Compress)
|
|
Dim buffer As Byte() = New Byte(4096) {}
|
|
Dim n As Integer = -1
|
|
Do While (n <> 0)
|
|
If (n > 0) Then
|
|
compressor.Write(buffer, 0, n)
|
|
End If
|
|
n = input.Read(buffer, 0, buffer.Length)
|
|
Loop
|
|
End Using
|
|
End Using
|
|
End Using
|
|
</code>
|
|
</example>
|
|
<param name="stream">The stream which will be read or written.</param>
|
|
<param name="mode">Indicates whether the DeflateStream will compress or decompress.</param>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.DeflateStream.#ctor(System.IO.Stream,Ionic.Zlib.CompressionMode,Ionic.Zlib.CompressionLevel)">
|
|
<summary>
|
|
Create a DeflateStream using the specified CompressionMode and the specified CompressionLevel.
|
|
</summary>
|
|
|
|
<remarks>
|
|
|
|
<para>
|
|
When mode is <c>CompressionMode.Decompress</c>, the level parameter is
|
|
ignored. The "captive" stream will be closed when the DeflateStream is
|
|
closed.
|
|
</para>
|
|
|
|
</remarks>
|
|
|
|
<example>
|
|
|
|
This example uses a DeflateStream to compress data from a file, and writes
|
|
the compressed data to another file.
|
|
|
|
<code>
|
|
using (System.IO.Stream input = System.IO.File.OpenRead(fileToCompress))
|
|
{
|
|
using (var raw = System.IO.File.Create(fileToCompress + ".deflated"))
|
|
{
|
|
using (Stream compressor = new DeflateStream(raw,
|
|
CompressionMode.Compress,
|
|
CompressionLevel.BestCompression))
|
|
{
|
|
byte[] buffer = new byte[WORKING_BUFFER_SIZE];
|
|
int n= -1;
|
|
while (n != 0)
|
|
{
|
|
if (n > 0)
|
|
compressor.Write(buffer, 0, n);
|
|
n= input.Read(buffer, 0, buffer.Length);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
</code>
|
|
|
|
<code lang="VB">
|
|
Using input As Stream = File.OpenRead(fileToCompress)
|
|
Using raw As FileStream = File.Create(fileToCompress & ".deflated")
|
|
Using compressor As Stream = New DeflateStream(raw, CompressionMode.Compress, CompressionLevel.BestCompression)
|
|
Dim buffer As Byte() = New Byte(4096) {}
|
|
Dim n As Integer = -1
|
|
Do While (n <> 0)
|
|
If (n > 0) Then
|
|
compressor.Write(buffer, 0, n)
|
|
End If
|
|
n = input.Read(buffer, 0, buffer.Length)
|
|
Loop
|
|
End Using
|
|
End Using
|
|
End Using
|
|
</code>
|
|
</example>
|
|
<param name="stream">The stream to be read or written while deflating or inflating.</param>
|
|
<param name="mode">Indicates whether the <c>DeflateStream</c> will compress or decompress.</param>
|
|
<param name="level">A tuning knob to trade speed for effectiveness.</param>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.DeflateStream.#ctor(System.IO.Stream,Ionic.Zlib.CompressionMode,System.Boolean)">
|
|
<summary>
|
|
Create a <c>DeflateStream</c> using the specified
|
|
<c>CompressionMode</c>, and explicitly specify whether the
|
|
stream should be left open after Deflation or Inflation.
|
|
</summary>
|
|
|
|
<remarks>
|
|
|
|
<para>
|
|
This constructor allows the application to request that the captive stream
|
|
remain open after the deflation or inflation occurs. By default, after
|
|
<c>Close()</c> is called on the stream, the captive stream is also
|
|
closed. In some cases this is not desired, for example if the stream is a
|
|
memory stream that will be re-read after compression. Specify true for
|
|
the <paramref name="leaveOpen"/> parameter to leave the stream open.
|
|
</para>
|
|
|
|
<para>
|
|
The <c>DeflateStream</c> will use the default compression level.
|
|
</para>
|
|
|
|
<para>
|
|
See the other overloads of this constructor for example code.
|
|
</para>
|
|
</remarks>
|
|
|
|
<param name="stream">
|
|
The stream which will be read or written. This is called the
|
|
"captive" stream in other places in this documentation.
|
|
</param>
|
|
|
|
<param name="mode">
|
|
Indicates whether the <c>DeflateStream</c> will compress or decompress.
|
|
</param>
|
|
|
|
<param name="leaveOpen">true if the application would like the stream to
|
|
remain open after inflation/deflation.</param>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.DeflateStream.#ctor(System.IO.Stream,Ionic.Zlib.CompressionMode,Ionic.Zlib.CompressionLevel,System.Boolean)">
|
|
<summary>
|
|
Create a <c>DeflateStream</c> using the specified <c>CompressionMode</c>
|
|
and the specified <c>CompressionLevel</c>, and explicitly specify whether
|
|
the stream should be left open after Deflation or Inflation.
|
|
</summary>
|
|
|
|
<remarks>
|
|
|
|
<para>
|
|
When mode is <c>CompressionMode.Decompress</c>, the level parameter is ignored.
|
|
</para>
|
|
|
|
<para>
|
|
This constructor allows the application to request that the captive stream
|
|
remain open after the deflation or inflation occurs. By default, after
|
|
<c>Close()</c> is called on the stream, the captive stream is also
|
|
closed. In some cases this is not desired, for example if the stream is a
|
|
<see cref="T:System.IO.MemoryStream"/> that will be re-read after
|
|
compression. Specify true for the <paramref name="leaveOpen"/> parameter
|
|
to leave the stream open.
|
|
</para>
|
|
|
|
</remarks>
|
|
|
|
<example>
|
|
|
|
This example shows how to use a <c>DeflateStream</c> to compress data from
|
|
a file, and store the compressed data into another file.
|
|
|
|
<code>
|
|
using (var output = System.IO.File.Create(fileToCompress + ".deflated"))
|
|
{
|
|
using (System.IO.Stream input = System.IO.File.OpenRead(fileToCompress))
|
|
{
|
|
using (Stream compressor = new DeflateStream(output, CompressionMode.Compress, CompressionLevel.BestCompression, true))
|
|
{
|
|
byte[] buffer = new byte[WORKING_BUFFER_SIZE];
|
|
int n= -1;
|
|
while (n != 0)
|
|
{
|
|
if (n > 0)
|
|
compressor.Write(buffer, 0, n);
|
|
n= input.Read(buffer, 0, buffer.Length);
|
|
}
|
|
}
|
|
}
|
|
// can write additional data to the output stream here
|
|
}
|
|
</code>
|
|
|
|
<code lang="VB">
|
|
Using output As FileStream = File.Create(fileToCompress & ".deflated")
|
|
Using input As Stream = File.OpenRead(fileToCompress)
|
|
Using compressor As Stream = New DeflateStream(output, CompressionMode.Compress, CompressionLevel.BestCompression, True)
|
|
Dim buffer As Byte() = New Byte(4096) {}
|
|
Dim n As Integer = -1
|
|
Do While (n <> 0)
|
|
If (n > 0) Then
|
|
compressor.Write(buffer, 0, n)
|
|
End If
|
|
n = input.Read(buffer, 0, buffer.Length)
|
|
Loop
|
|
End Using
|
|
End Using
|
|
' can write additional data to the output stream here.
|
|
End Using
|
|
</code>
|
|
</example>
|
|
<param name="stream">The stream which will be read or written.</param>
|
|
<param name="mode">Indicates whether the DeflateStream will compress or decompress.</param>
|
|
<param name="leaveOpen">true if the application would like the stream to remain open after inflation/deflation.</param>
|
|
<param name="level">A tuning knob to trade speed for effectiveness.</param>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.DeflateStream.Dispose(System.Boolean)">
|
|
<summary>
|
|
Dispose the stream.
|
|
</summary>
|
|
<remarks>
|
|
<para>
|
|
This may or may not result in a <c>Close()</c> call on the captive
|
|
stream. See the constructors that have a <c>leaveOpen</c> parameter
|
|
for more information.
|
|
</para>
|
|
<para>
|
|
Application code won't call this code directly. This method may be
|
|
invoked in two distinct scenarios. If disposing == true, the method
|
|
has been called directly or indirectly by a user's code, for example
|
|
via the public Dispose() method. In this case, both managed and
|
|
unmanaged resources can be referenced and disposed. If disposing ==
|
|
false, the method has been called by the runtime from inside the
|
|
object finalizer and this method should not reference other objects;
|
|
in that case only unmanaged resources must be referenced or
|
|
disposed.
|
|
</para>
|
|
</remarks>
|
|
<param name="disposing">
|
|
true if the Dispose method was invoked by user code.
|
|
</param>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.DeflateStream.Flush">
|
|
<summary>
|
|
Flush the stream.
|
|
</summary>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.DeflateStream.Read(System.Byte[],System.Int32,System.Int32)">
|
|
<summary>
|
|
Read data from the stream.
|
|
</summary>
|
|
<remarks>
|
|
|
|
<para>
|
|
If you wish to use the <c>DeflateStream</c> to compress data while
|
|
reading, you can create a <c>DeflateStream</c> with
|
|
<c>CompressionMode.Compress</c>, providing an uncompressed data stream.
|
|
Then call Read() on that <c>DeflateStream</c>, and the data read will be
|
|
compressed as you read. If you wish to use the <c>DeflateStream</c> to
|
|
decompress data while reading, you can create a <c>DeflateStream</c> with
|
|
<c>CompressionMode.Decompress</c>, providing a readable compressed data
|
|
stream. Then call Read() on that <c>DeflateStream</c>, and the data read
|
|
will be decompressed as you read.
|
|
</para>
|
|
|
|
<para>
|
|
A <c>DeflateStream</c> can be used for <c>Read()</c> or <c>Write()</c>, but not both.
|
|
</para>
|
|
|
|
</remarks>
|
|
<param name="buffer">The buffer into which the read data should be placed.</param>
|
|
<param name="offset">the offset within that data array to put the first byte read.</param>
|
|
<param name="count">the number of bytes to read.</param>
|
|
<returns>the number of bytes actually read</returns>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.DeflateStream.Seek(System.Int64,System.IO.SeekOrigin)">
|
|
<summary>
|
|
Calling this method always throws a <see cref="T:System.NotImplementedException"/>.
|
|
</summary>
|
|
<param name="offset">this is irrelevant, since it will always throw!</param>
|
|
<param name="origin">this is irrelevant, since it will always throw!</param>
|
|
<returns>irrelevant!</returns>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.DeflateStream.SetLength(System.Int64)">
|
|
<summary>
|
|
Calling this method always throws a <see cref="T:System.NotImplementedException"/>.
|
|
</summary>
|
|
<param name="value">this is irrelevant, since it will always throw!</param>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.DeflateStream.Write(System.Byte[],System.Int32,System.Int32)">
|
|
<summary>
|
|
Write data to the stream.
|
|
</summary>
|
|
<remarks>
|
|
|
|
<para>
|
|
If you wish to use the <c>DeflateStream</c> to compress data while
|
|
writing, you can create a <c>DeflateStream</c> with
|
|
<c>CompressionMode.Compress</c>, and a writable output stream. Then call
|
|
<c>Write()</c> on that <c>DeflateStream</c>, providing uncompressed data
|
|
as input. The data sent to the output stream will be the compressed form
|
|
of the data written. If you wish to use the <c>DeflateStream</c> to
|
|
decompress data while writing, you can create a <c>DeflateStream</c> with
|
|
<c>CompressionMode.Decompress</c>, and a writable output stream. Then
|
|
call <c>Write()</c> on that stream, providing previously compressed
|
|
data. The data sent to the output stream will be the decompressed form of
|
|
the data written.
|
|
</para>
|
|
|
|
<para>
|
|
A <c>DeflateStream</c> can be used for <c>Read()</c> or <c>Write()</c>,
|
|
but not both.
|
|
</para>
|
|
|
|
</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.Zlib.DeflateStream.CompressString(System.String)">
|
|
<summary>
|
|
Compress a string into a byte array using DEFLATE (RFC 1951).
|
|
</summary>
|
|
|
|
<remarks>
|
|
Uncompress it with <see cref="M:Ionic.Zlib.DeflateStream.UncompressString(System.Byte[])"/>.
|
|
</remarks>
|
|
|
|
<seealso cref="M:Ionic.Zlib.DeflateStream.UncompressString(System.Byte[])">DeflateStream.UncompressString(byte[])</seealso>
|
|
<seealso cref="M:Ionic.Zlib.DeflateStream.CompressBuffer(System.Byte[])">DeflateStream.CompressBuffer(byte[])</seealso>
|
|
<seealso cref="M:Ionic.Zlib.GZipStream.CompressString(System.String)">GZipStream.CompressString(string)</seealso>
|
|
<seealso cref="M:Ionic.Zlib.ZlibStream.CompressString(System.String)">ZlibStream.CompressString(string)</seealso>
|
|
|
|
<param name="s">
|
|
A string to compress. The string will first be encoded
|
|
using UTF8, then compressed.
|
|
</param>
|
|
|
|
<returns>The string in compressed form</returns>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.DeflateStream.CompressBuffer(System.Byte[])">
|
|
<summary>
|
|
Compress a byte array into a new byte array using DEFLATE.
|
|
</summary>
|
|
|
|
<remarks>
|
|
Uncompress it with <see cref="M:Ionic.Zlib.DeflateStream.UncompressBuffer(System.Byte[])"/>.
|
|
</remarks>
|
|
|
|
<seealso cref="M:Ionic.Zlib.DeflateStream.CompressString(System.String)">DeflateStream.CompressString(string)</seealso>
|
|
<seealso cref="M:Ionic.Zlib.DeflateStream.UncompressBuffer(System.Byte[])">DeflateStream.UncompressBuffer(byte[])</seealso>
|
|
<seealso cref="M:Ionic.Zlib.GZipStream.CompressBuffer(System.Byte[])">GZipStream.CompressBuffer(byte[])</seealso>
|
|
<seealso cref="M:Ionic.Zlib.ZlibStream.CompressBuffer(System.Byte[])">ZlibStream.CompressBuffer(byte[])</seealso>
|
|
|
|
<param name="b">
|
|
A buffer to compress.
|
|
</param>
|
|
|
|
<returns>The data in compressed form</returns>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.DeflateStream.UncompressString(System.Byte[])">
|
|
<summary>
|
|
Uncompress a DEFLATE'd byte array into a single string.
|
|
</summary>
|
|
|
|
<seealso cref="M:Ionic.Zlib.DeflateStream.CompressString(System.String)">DeflateStream.CompressString(String)</seealso>
|
|
<seealso cref="M:Ionic.Zlib.DeflateStream.UncompressBuffer(System.Byte[])">DeflateStream.UncompressBuffer(byte[])</seealso>
|
|
<seealso cref="M:Ionic.Zlib.GZipStream.UncompressString(System.Byte[])">GZipStream.UncompressString(byte[])</seealso>
|
|
<seealso cref="M:Ionic.Zlib.ZlibStream.UncompressString(System.Byte[])">ZlibStream.UncompressString(byte[])</seealso>
|
|
|
|
<param name="compressed">
|
|
A buffer containing DEFLATE-compressed data.
|
|
</param>
|
|
|
|
<returns>The uncompressed string</returns>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.DeflateStream.UncompressBuffer(System.Byte[])">
|
|
<summary>
|
|
Uncompress a DEFLATE'd byte array into a byte array.
|
|
</summary>
|
|
|
|
<seealso cref="M:Ionic.Zlib.DeflateStream.CompressBuffer(System.Byte[])">DeflateStream.CompressBuffer(byte[])</seealso>
|
|
<seealso cref="M:Ionic.Zlib.DeflateStream.UncompressString(System.Byte[])">DeflateStream.UncompressString(byte[])</seealso>
|
|
<seealso cref="M:Ionic.Zlib.GZipStream.UncompressBuffer(System.Byte[])">GZipStream.UncompressBuffer(byte[])</seealso>
|
|
<seealso cref="M:Ionic.Zlib.ZlibStream.UncompressBuffer(System.Byte[])">ZlibStream.UncompressBuffer(byte[])</seealso>
|
|
|
|
<param name="compressed">
|
|
A buffer containing data that has been compressed with DEFLATE.
|
|
</param>
|
|
|
|
<returns>The data in uncompressed form</returns>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.DeflateStream.FlushMode">
|
|
<summary>
|
|
This property sets the flush behavior on the stream.
|
|
</summary>
|
|
<remarks> See the ZLIB documentation for the meaning of the flush behavior.
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.DeflateStream.BufferSize">
|
|
<summary>
|
|
The size of the working buffer for the compression codec.
|
|
</summary>
|
|
|
|
<remarks>
|
|
<para>
|
|
The working buffer is used for all stream operations. The default size is
|
|
1024 bytes. The minimum size is 128 bytes. You may get better performance
|
|
with a larger buffer. Then again, you might not. You would have to test
|
|
it.
|
|
</para>
|
|
|
|
<para>
|
|
Set this before the first call to <c>Read()</c> or <c>Write()</c> on the
|
|
stream. If you try to set it afterwards, it will throw.
|
|
</para>
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.DeflateStream.Strategy">
|
|
<summary>
|
|
The ZLIB strategy to be used during compression.
|
|
</summary>
|
|
|
|
<remarks>
|
|
By tweaking this parameter, you may be able to optimize the compression for
|
|
data with particular characteristics.
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.DeflateStream.TotalIn">
|
|
<summary> Returns the total number of bytes input so far.</summary>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.DeflateStream.TotalOut">
|
|
<summary> Returns the total number of bytes output so far.</summary>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.DeflateStream.CanRead">
|
|
<summary>
|
|
Indicates whether the stream can be read.
|
|
</summary>
|
|
<remarks>
|
|
The return value depends on whether the captive stream supports reading.
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.DeflateStream.CanSeek">
|
|
<summary>
|
|
Indicates whether the stream supports Seek operations.
|
|
</summary>
|
|
<remarks>
|
|
Always returns false.
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.DeflateStream.CanWrite">
|
|
<summary>
|
|
Indicates whether the stream can be written.
|
|
</summary>
|
|
<remarks>
|
|
The return value depends on whether the captive stream supports writing.
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.DeflateStream.Length">
|
|
<summary>
|
|
Reading this property always throws a <see cref="T:System.NotImplementedException"/>.
|
|
</summary>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.DeflateStream.Position">
|
|
<summary>
|
|
The position of the stream pointer.
|
|
</summary>
|
|
|
|
<remarks>
|
|
Setting this property always throws a <see cref="T:System.NotImplementedException"/>. Reading will return the total bytes
|
|
written out, if used in writing, or the total bytes read in, if used in
|
|
reading. The count may refer to compressed bytes or uncompressed bytes,
|
|
depending on how you've used the stream.
|
|
</remarks>
|
|
</member>
|
|
<member name="T:Ionic.Zlib.GZipStream">
|
|
<summary>
|
|
A class for compressing and decompressing GZIP streams.
|
|
</summary>
|
|
<remarks>
|
|
|
|
<para>
|
|
The <c>GZipStream</c> is a <see href="http://en.wikipedia.org/wiki/Decorator_pattern">Decorator</see> on a
|
|
<see cref="T:System.IO.Stream"/>. It adds GZIP compression or decompression to any
|
|
stream.
|
|
</para>
|
|
|
|
<para>
|
|
Like the <c>System.IO.Compression.GZipStream</c> in the .NET Base Class Library, the
|
|
<c>Ionic.Zlib.GZipStream</c> can compress while writing, or decompress while
|
|
reading, but not vice versa. The compression method used is GZIP, which is
|
|
documented in <see href="http://www.ietf.org/rfc/rfc1952.txt">IETF RFC
|
|
1952</see>, "GZIP file format specification version 4.3".</para>
|
|
|
|
<para>
|
|
A <c>GZipStream</c> can be used to decompress data (through <c>Read()</c>) or
|
|
to compress data (through <c>Write()</c>), but not both.
|
|
</para>
|
|
|
|
<para>
|
|
If you wish to use the <c>GZipStream</c> to compress data, you must wrap it
|
|
around a write-able stream. As you call <c>Write()</c> on the <c>GZipStream</c>, the
|
|
data will be compressed into the GZIP format. If you want to decompress data,
|
|
you must wrap the <c>GZipStream</c> around a readable stream that contains an
|
|
IETF RFC 1952-compliant stream. The data will be decompressed as you call
|
|
<c>Read()</c> on the <c>GZipStream</c>.
|
|
</para>
|
|
|
|
<para>
|
|
Though the GZIP format allows data from multiple files to be concatenated
|
|
together, this stream handles only a single segment of GZIP format, typically
|
|
representing a single file.
|
|
</para>
|
|
|
|
<para>
|
|
This class is similar to <see cref="T:Ionic.Zlib.ZlibStream"/> and <see cref="T:Ionic.Zlib.DeflateStream"/>.
|
|
<c>ZlibStream</c> handles RFC1950-compliant streams. <see cref="T:Ionic.Zlib.DeflateStream"/>
|
|
handles RFC1951-compliant streams. This class handles RFC1952-compliant streams.
|
|
</para>
|
|
|
|
</remarks>
|
|
|
|
<seealso cref="T:Ionic.Zlib.DeflateStream"/>
|
|
<seealso cref="T:Ionic.Zlib.ZlibStream"/>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.GZipStream.LastModified">
|
|
<summary>
|
|
The last modified time for the GZIP stream.
|
|
</summary>
|
|
|
|
<remarks>
|
|
GZIP allows the storage of a last modified time with each GZIP entry.
|
|
When compressing data, you can set this before the first call to
|
|
<c>Write()</c>. When decompressing, you can retrieve this value any time
|
|
after the first call to <c>Read()</c>.
|
|
</remarks>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.GZipStream.#ctor(System.IO.Stream,Ionic.Zlib.CompressionMode)">
|
|
<summary>
|
|
Create a <c>GZipStream</c> using the specified <c>CompressionMode</c>.
|
|
</summary>
|
|
<remarks>
|
|
|
|
<para>
|
|
When mode is <c>CompressionMode.Compress</c>, the <c>GZipStream</c> will use the
|
|
default compression level.
|
|
</para>
|
|
|
|
<para>
|
|
As noted in the class documentation, the <c>CompressionMode</c> (Compress
|
|
or Decompress) also establishes the "direction" of the stream. A
|
|
<c>GZipStream</c> with <c>CompressionMode.Compress</c> works only through
|
|
<c>Write()</c>. A <c>GZipStream</c> with
|
|
<c>CompressionMode.Decompress</c> works only through <c>Read()</c>.
|
|
</para>
|
|
|
|
</remarks>
|
|
|
|
<example>
|
|
This example shows how to use a GZipStream to compress data.
|
|
<code>
|
|
using (System.IO.Stream input = System.IO.File.OpenRead(fileToCompress))
|
|
{
|
|
using (var raw = System.IO.File.Create(outputFile))
|
|
{
|
|
using (Stream compressor = new GZipStream(raw, CompressionMode.Compress))
|
|
{
|
|
byte[] buffer = new byte[WORKING_BUFFER_SIZE];
|
|
int n;
|
|
while ((n= input.Read(buffer, 0, buffer.Length)) != 0)
|
|
{
|
|
compressor.Write(buffer, 0, n);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
</code>
|
|
<code lang="VB">
|
|
Dim outputFile As String = (fileToCompress & ".compressed")
|
|
Using input As Stream = File.OpenRead(fileToCompress)
|
|
Using raw As FileStream = File.Create(outputFile)
|
|
Using compressor As Stream = New GZipStream(raw, CompressionMode.Compress)
|
|
Dim buffer As Byte() = New Byte(4096) {}
|
|
Dim n As Integer = -1
|
|
Do While (n <> 0)
|
|
If (n > 0) Then
|
|
compressor.Write(buffer, 0, n)
|
|
End If
|
|
n = input.Read(buffer, 0, buffer.Length)
|
|
Loop
|
|
End Using
|
|
End Using
|
|
End Using
|
|
</code>
|
|
</example>
|
|
|
|
<example>
|
|
This example shows how to use a GZipStream to uncompress a file.
|
|
<code>
|
|
private void GunZipFile(string filename)
|
|
{
|
|
if (!filename.EndsWith(".gz))
|
|
throw new ArgumentException("filename");
|
|
var DecompressedFile = filename.Substring(0,filename.Length-3);
|
|
byte[] working = new byte[WORKING_BUFFER_SIZE];
|
|
int n= 1;
|
|
using (System.IO.Stream input = System.IO.File.OpenRead(filename))
|
|
{
|
|
using (Stream decompressor= new Ionic.Zlib.GZipStream(input, CompressionMode.Decompress, true))
|
|
{
|
|
using (var output = System.IO.File.Create(DecompressedFile))
|
|
{
|
|
while (n !=0)
|
|
{
|
|
n= decompressor.Read(working, 0, working.Length);
|
|
if (n > 0)
|
|
{
|
|
output.Write(working, 0, n);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
</code>
|
|
|
|
<code lang="VB">
|
|
Private Sub GunZipFile(ByVal filename as String)
|
|
If Not (filename.EndsWith(".gz)) Then
|
|
Throw New ArgumentException("filename")
|
|
End If
|
|
Dim DecompressedFile as String = filename.Substring(0,filename.Length-3)
|
|
Dim working(WORKING_BUFFER_SIZE) as Byte
|
|
Dim n As Integer = 1
|
|
Using input As Stream = File.OpenRead(filename)
|
|
Using decompressor As Stream = new Ionic.Zlib.GZipStream(input, CompressionMode.Decompress, True)
|
|
Using output As Stream = File.Create(UncompressedFile)
|
|
Do
|
|
n= decompressor.Read(working, 0, working.Length)
|
|
If n > 0 Then
|
|
output.Write(working, 0, n)
|
|
End IF
|
|
Loop While (n > 0)
|
|
End Using
|
|
End Using
|
|
End Using
|
|
End Sub
|
|
</code>
|
|
</example>
|
|
|
|
<param name="stream">The stream which will be read or written.</param>
|
|
<param name="mode">Indicates whether the GZipStream will compress or decompress.</param>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.GZipStream.#ctor(System.IO.Stream,Ionic.Zlib.CompressionMode,Ionic.Zlib.CompressionLevel)">
|
|
<summary>
|
|
Create a <c>GZipStream</c> using the specified <c>CompressionMode</c> and
|
|
the specified <c>CompressionLevel</c>.
|
|
</summary>
|
|
<remarks>
|
|
|
|
<para>
|
|
The <c>CompressionMode</c> (Compress or Decompress) also establishes the
|
|
"direction" of the stream. A <c>GZipStream</c> with
|
|
<c>CompressionMode.Compress</c> works only through <c>Write()</c>. A
|
|
<c>GZipStream</c> with <c>CompressionMode.Decompress</c> works only
|
|
through <c>Read()</c>.
|
|
</para>
|
|
|
|
</remarks>
|
|
|
|
<example>
|
|
|
|
This example shows how to use a <c>GZipStream</c> to compress a file into a .gz file.
|
|
|
|
<code>
|
|
using (System.IO.Stream input = System.IO.File.OpenRead(fileToCompress))
|
|
{
|
|
using (var raw = System.IO.File.Create(fileToCompress + ".gz"))
|
|
{
|
|
using (Stream compressor = new GZipStream(raw,
|
|
CompressionMode.Compress,
|
|
CompressionLevel.BestCompression))
|
|
{
|
|
byte[] buffer = new byte[WORKING_BUFFER_SIZE];
|
|
int n;
|
|
while ((n= input.Read(buffer, 0, buffer.Length)) != 0)
|
|
{
|
|
compressor.Write(buffer, 0, n);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
</code>
|
|
|
|
<code lang="VB">
|
|
Using input As Stream = File.OpenRead(fileToCompress)
|
|
Using raw As FileStream = File.Create(fileToCompress & ".gz")
|
|
Using compressor As Stream = New GZipStream(raw, CompressionMode.Compress, CompressionLevel.BestCompression)
|
|
Dim buffer As Byte() = New Byte(4096) {}
|
|
Dim n As Integer = -1
|
|
Do While (n <> 0)
|
|
If (n > 0) Then
|
|
compressor.Write(buffer, 0, n)
|
|
End If
|
|
n = input.Read(buffer, 0, buffer.Length)
|
|
Loop
|
|
End Using
|
|
End Using
|
|
End Using
|
|
</code>
|
|
</example>
|
|
<param name="stream">The stream to be read or written while deflating or inflating.</param>
|
|
<param name="mode">Indicates whether the <c>GZipStream</c> will compress or decompress.</param>
|
|
<param name="level">A tuning knob to trade speed for effectiveness.</param>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.GZipStream.#ctor(System.IO.Stream,Ionic.Zlib.CompressionMode,System.Boolean)">
|
|
<summary>
|
|
Create a <c>GZipStream</c> using the specified <c>CompressionMode</c>, and
|
|
explicitly specify whether the stream should be left open after Deflation
|
|
or Inflation.
|
|
</summary>
|
|
|
|
<remarks>
|
|
<para>
|
|
This constructor allows the application to request that the captive stream
|
|
remain open after the deflation or inflation occurs. By default, after
|
|
<c>Close()</c> is called on the stream, the captive stream is also
|
|
closed. In some cases this is not desired, for example if the stream is a
|
|
memory stream that will be re-read after compressed data has been written
|
|
to it. Specify true for the <paramref name="leaveOpen"/> parameter to leave
|
|
the stream open.
|
|
</para>
|
|
|
|
<para>
|
|
The <see cref="T:Ionic.Zlib.CompressionMode"/> (Compress or Decompress) also
|
|
establishes the "direction" of the stream. A <c>GZipStream</c> with
|
|
<c>CompressionMode.Compress</c> works only through <c>Write()</c>. A <c>GZipStream</c>
|
|
with <c>CompressionMode.Decompress</c> works only through <c>Read()</c>.
|
|
</para>
|
|
|
|
<para>
|
|
The <c>GZipStream</c> will use the default compression level. If you want
|
|
to specify the compression level, see <see cref="M:Ionic.Zlib.GZipStream.#ctor(System.IO.Stream,Ionic.Zlib.CompressionMode,Ionic.Zlib.CompressionLevel,System.Boolean)"/>.
|
|
</para>
|
|
|
|
<para>
|
|
See the other overloads of this constructor for example code.
|
|
</para>
|
|
|
|
</remarks>
|
|
|
|
<param name="stream">
|
|
The stream which will be read or written. This is called the "captive"
|
|
stream in other places in this documentation.
|
|
</param>
|
|
|
|
<param name="mode">Indicates whether the GZipStream will compress or decompress.
|
|
</param>
|
|
|
|
<param name="leaveOpen">
|
|
true if the application would like the base stream to remain open after
|
|
inflation/deflation.
|
|
</param>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.GZipStream.#ctor(System.IO.Stream,Ionic.Zlib.CompressionMode,Ionic.Zlib.CompressionLevel,System.Boolean)">
|
|
<summary>
|
|
Create a <c>GZipStream</c> using the specified <c>CompressionMode</c> and the
|
|
specified <c>CompressionLevel</c>, and explicitly specify whether the
|
|
stream should be left open after Deflation or Inflation.
|
|
</summary>
|
|
|
|
<remarks>
|
|
|
|
<para>
|
|
This constructor allows the application to request that the captive stream
|
|
remain open after the deflation or inflation occurs. By default, after
|
|
<c>Close()</c> is called on the stream, the captive stream is also
|
|
closed. In some cases this is not desired, for example if the stream is a
|
|
memory stream that will be re-read after compressed data has been written
|
|
to it. Specify true for the <paramref name="leaveOpen"/> parameter to
|
|
leave the stream open.
|
|
</para>
|
|
|
|
<para>
|
|
As noted in the class documentation, the <c>CompressionMode</c> (Compress
|
|
or Decompress) also establishes the "direction" of the stream. A
|
|
<c>GZipStream</c> with <c>CompressionMode.Compress</c> works only through
|
|
<c>Write()</c>. A <c>GZipStream</c> with <c>CompressionMode.Decompress</c> works only
|
|
through <c>Read()</c>.
|
|
</para>
|
|
|
|
</remarks>
|
|
|
|
<example>
|
|
This example shows how to use a <c>GZipStream</c> to compress data.
|
|
<code>
|
|
using (System.IO.Stream input = System.IO.File.OpenRead(fileToCompress))
|
|
{
|
|
using (var raw = System.IO.File.Create(outputFile))
|
|
{
|
|
using (Stream compressor = new GZipStream(raw, CompressionMode.Compress, CompressionLevel.BestCompression, true))
|
|
{
|
|
byte[] buffer = new byte[WORKING_BUFFER_SIZE];
|
|
int n;
|
|
while ((n= input.Read(buffer, 0, buffer.Length)) != 0)
|
|
{
|
|
compressor.Write(buffer, 0, n);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
</code>
|
|
<code lang="VB">
|
|
Dim outputFile As String = (fileToCompress & ".compressed")
|
|
Using input As Stream = File.OpenRead(fileToCompress)
|
|
Using raw As FileStream = File.Create(outputFile)
|
|
Using compressor As Stream = New GZipStream(raw, CompressionMode.Compress, CompressionLevel.BestCompression, True)
|
|
Dim buffer As Byte() = New Byte(4096) {}
|
|
Dim n As Integer = -1
|
|
Do While (n <> 0)
|
|
If (n > 0) Then
|
|
compressor.Write(buffer, 0, n)
|
|
End If
|
|
n = input.Read(buffer, 0, buffer.Length)
|
|
Loop
|
|
End Using
|
|
End Using
|
|
End Using
|
|
</code>
|
|
</example>
|
|
<param name="stream">The stream which will be read or written.</param>
|
|
<param name="mode">Indicates whether the GZipStream will compress or decompress.</param>
|
|
<param name="leaveOpen">true if the application would like the stream to remain open after inflation/deflation.</param>
|
|
<param name="level">A tuning knob to trade speed for effectiveness.</param>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.GZipStream.Dispose(System.Boolean)">
|
|
<summary>
|
|
Dispose the stream.
|
|
</summary>
|
|
<remarks>
|
|
<para>
|
|
This may or may not result in a <c>Close()</c> call on the captive
|
|
stream. See the constructors that have a <c>leaveOpen</c> parameter
|
|
for more information.
|
|
</para>
|
|
<para>
|
|
This method may be invoked in two distinct scenarios. If disposing
|
|
== true, the method has been called directly or indirectly by a
|
|
user's code, for example via the public Dispose() method. In this
|
|
case, both managed and unmanaged resources can be referenced and
|
|
disposed. If disposing == false, the method has been called by the
|
|
runtime from inside the object finalizer and this method should not
|
|
reference other objects; in that case only unmanaged resources must
|
|
be referenced or disposed.
|
|
</para>
|
|
</remarks>
|
|
<param name="disposing">
|
|
indicates whether the Dispose method was invoked by user code.
|
|
</param>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.GZipStream.Flush">
|
|
<summary>
|
|
Flush the stream.
|
|
</summary>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.GZipStream.Read(System.Byte[],System.Int32,System.Int32)">
|
|
<summary>
|
|
Read and decompress data from the source stream.
|
|
</summary>
|
|
|
|
<remarks>
|
|
With a <c>GZipStream</c>, decompression is done through reading.
|
|
</remarks>
|
|
|
|
<example>
|
|
<code>
|
|
byte[] working = new byte[WORKING_BUFFER_SIZE];
|
|
using (System.IO.Stream input = System.IO.File.OpenRead(_CompressedFile))
|
|
{
|
|
using (Stream decompressor= new Ionic.Zlib.GZipStream(input, CompressionMode.Decompress, true))
|
|
{
|
|
using (var output = System.IO.File.Create(_DecompressedFile))
|
|
{
|
|
int n;
|
|
while ((n= decompressor.Read(working, 0, working.Length)) !=0)
|
|
{
|
|
output.Write(working, 0, n);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
</code>
|
|
</example>
|
|
<param name="buffer">The buffer into which the decompressed data should be placed.</param>
|
|
<param name="offset">the offset within that data array to put the first byte read.</param>
|
|
<param name="count">the number of bytes to read.</param>
|
|
<returns>the number of bytes actually read</returns>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.GZipStream.Seek(System.Int64,System.IO.SeekOrigin)">
|
|
<summary>
|
|
Calling this method always throws a <see cref="T:System.NotImplementedException"/>.
|
|
</summary>
|
|
<param name="offset">irrelevant; it will always throw!</param>
|
|
<param name="origin">irrelevant; it will always throw!</param>
|
|
<returns>irrelevant!</returns>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.GZipStream.SetLength(System.Int64)">
|
|
<summary>
|
|
Calling this method always throws a <see cref="T:System.NotImplementedException"/>.
|
|
</summary>
|
|
<param name="value">irrelevant; this method will always throw!</param>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.GZipStream.Write(System.Byte[],System.Int32,System.Int32)">
|
|
<summary>
|
|
Write data to the stream.
|
|
</summary>
|
|
|
|
<remarks>
|
|
<para>
|
|
If you wish to use the <c>GZipStream</c> to compress data while writing,
|
|
you can create a <c>GZipStream</c> with <c>CompressionMode.Compress</c>, and a
|
|
writable output stream. Then call <c>Write()</c> on that <c>GZipStream</c>,
|
|
providing uncompressed data as input. The data sent to the output stream
|
|
will be the compressed form of the data written.
|
|
</para>
|
|
|
|
<para>
|
|
A <c>GZipStream</c> can be used for <c>Read()</c> or <c>Write()</c>, but not
|
|
both. Writing implies compression. Reading implies decompression.
|
|
</para>
|
|
|
|
</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.Zlib.GZipStream.CompressString(System.String)">
|
|
<summary>
|
|
Compress a string into a byte array using GZip.
|
|
</summary>
|
|
|
|
<remarks>
|
|
Uncompress it with <see cref="M:Ionic.Zlib.GZipStream.UncompressString(System.Byte[])"/>.
|
|
</remarks>
|
|
|
|
<seealso cref="M:Ionic.Zlib.GZipStream.UncompressString(System.Byte[])"/>
|
|
<seealso cref="M:Ionic.Zlib.GZipStream.CompressBuffer(System.Byte[])"/>
|
|
|
|
<param name="s">
|
|
A string to compress. The string will first be encoded
|
|
using UTF8, then compressed.
|
|
</param>
|
|
|
|
<returns>The string in compressed form</returns>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.GZipStream.CompressBuffer(System.Byte[])">
|
|
<summary>
|
|
Compress a byte array into a new byte array using GZip.
|
|
</summary>
|
|
|
|
<remarks>
|
|
Uncompress it with <see cref="M:Ionic.Zlib.GZipStream.UncompressBuffer(System.Byte[])"/>.
|
|
</remarks>
|
|
|
|
<seealso cref="M:Ionic.Zlib.GZipStream.CompressString(System.String)"/>
|
|
<seealso cref="M:Ionic.Zlib.GZipStream.UncompressBuffer(System.Byte[])"/>
|
|
|
|
<param name="b">
|
|
A buffer to compress.
|
|
</param>
|
|
|
|
<returns>The data in compressed form</returns>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.GZipStream.UncompressString(System.Byte[])">
|
|
<summary>
|
|
Uncompress a GZip'ed byte array into a single string.
|
|
</summary>
|
|
|
|
<seealso cref="M:Ionic.Zlib.GZipStream.CompressString(System.String)"/>
|
|
<seealso cref="M:Ionic.Zlib.GZipStream.UncompressBuffer(System.Byte[])"/>
|
|
|
|
<param name="compressed">
|
|
A buffer containing GZIP-compressed data.
|
|
</param>
|
|
|
|
<returns>The uncompressed string</returns>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.GZipStream.UncompressBuffer(System.Byte[])">
|
|
<summary>
|
|
Uncompress a GZip'ed byte array into a byte array.
|
|
</summary>
|
|
|
|
<seealso cref="M:Ionic.Zlib.GZipStream.CompressBuffer(System.Byte[])"/>
|
|
<seealso cref="M:Ionic.Zlib.GZipStream.UncompressString(System.Byte[])"/>
|
|
|
|
<param name="compressed">
|
|
A buffer containing data that has been compressed with GZip.
|
|
</param>
|
|
|
|
<returns>The data in uncompressed form</returns>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.GZipStream.Comment">
|
|
<summary>
|
|
The comment on the GZIP stream.
|
|
</summary>
|
|
|
|
<remarks>
|
|
<para>
|
|
The GZIP format allows for each file to optionally have an associated
|
|
comment stored with the file. The comment is encoded with the ISO-8859-1
|
|
code page. To include a comment in a GZIP stream you create, set this
|
|
property before calling <c>Write()</c> for the first time on the
|
|
<c>GZipStream</c>.
|
|
</para>
|
|
|
|
<para>
|
|
When using <c>GZipStream</c> to decompress, you can retrieve this property
|
|
after the first call to <c>Read()</c>. If no comment has been set in the
|
|
GZIP bytestream, the Comment property will return <c>null</c>
|
|
(<c>Nothing</c> in VB).
|
|
</para>
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.GZipStream.FileName">
|
|
<summary>
|
|
The FileName for the GZIP stream.
|
|
</summary>
|
|
|
|
<remarks>
|
|
|
|
<para>
|
|
The GZIP format optionally allows each file to have an associated
|
|
filename. When compressing data (through <c>Write()</c>), set this
|
|
FileName before calling <c>Write()</c> the first time on the <c>GZipStream</c>.
|
|
The actual filename is encoded into the GZIP bytestream with the
|
|
ISO-8859-1 code page, according to RFC 1952. It is the application's
|
|
responsibility to insure that the FileName can be encoded and decoded
|
|
correctly with this code page.
|
|
</para>
|
|
|
|
<para>
|
|
When decompressing (through <c>Read()</c>), you can retrieve this value
|
|
any time after the first <c>Read()</c>. In the case where there was no filename
|
|
encoded into the GZIP bytestream, the property will return <c>null</c> (<c>Nothing</c>
|
|
in VB).
|
|
</para>
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.GZipStream.Crc32">
|
|
<summary>
|
|
The CRC on the GZIP stream.
|
|
</summary>
|
|
<remarks>
|
|
This is used for internal error checking. You probably don't need to look at this property.
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.GZipStream.FlushMode">
|
|
<summary>
|
|
This property sets the flush behavior on the stream.
|
|
</summary>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.GZipStream.BufferSize">
|
|
<summary>
|
|
The size of the working buffer for the compression codec.
|
|
</summary>
|
|
|
|
<remarks>
|
|
<para>
|
|
The working buffer is used for all stream operations. The default size is
|
|
1024 bytes. The minimum size is 128 bytes. You may get better performance
|
|
with a larger buffer. Then again, you might not. You would have to test
|
|
it.
|
|
</para>
|
|
|
|
<para>
|
|
Set this before the first call to <c>Read()</c> or <c>Write()</c> on the
|
|
stream. If you try to set it afterwards, it will throw.
|
|
</para>
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.GZipStream.TotalIn">
|
|
<summary> Returns the total number of bytes input so far.</summary>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.GZipStream.TotalOut">
|
|
<summary> Returns the total number of bytes output so far.</summary>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.GZipStream.CanRead">
|
|
<summary>
|
|
Indicates whether the stream can be read.
|
|
</summary>
|
|
<remarks>
|
|
The return value depends on whether the captive stream supports reading.
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.GZipStream.CanSeek">
|
|
<summary>
|
|
Indicates whether the stream supports Seek operations.
|
|
</summary>
|
|
<remarks>
|
|
Always returns false.
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.GZipStream.CanWrite">
|
|
<summary>
|
|
Indicates whether the stream can be written.
|
|
</summary>
|
|
<remarks>
|
|
The return value depends on whether the captive stream supports writing.
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.GZipStream.Length">
|
|
<summary>
|
|
Reading this property always throws a <see cref="T:System.NotImplementedException"/>.
|
|
</summary>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.GZipStream.Position">
|
|
<summary>
|
|
The position of the stream pointer.
|
|
</summary>
|
|
|
|
<remarks>
|
|
Setting this property always throws a <see cref="T:System.NotImplementedException"/>. Reading will return the total bytes
|
|
written out, if used in writing, or the total bytes read in, if used in
|
|
reading. The count may refer to compressed bytes or uncompressed bytes,
|
|
depending on how you've used the stream.
|
|
</remarks>
|
|
</member>
|
|
<member name="T:Ionic.Zlib.ParallelDeflateOutputStream">
|
|
<summary>
|
|
A class for compressing streams using the
|
|
Deflate algorithm with multiple threads.
|
|
</summary>
|
|
|
|
<remarks>
|
|
<para>
|
|
This class performs DEFLATE compression through writing. For
|
|
more information on the Deflate algorithm, see IETF RFC 1951,
|
|
"DEFLATE Compressed Data Format Specification version 1.3."
|
|
</para>
|
|
|
|
<para>
|
|
This class is similar to <see cref="T:Ionic.Zlib.DeflateStream"/>, except
|
|
that this class is for compression only, and this implementation uses an
|
|
approach that employs multiple worker threads to perform the DEFLATE. On
|
|
a multi-cpu or multi-core computer, the performance of this class can be
|
|
significantly higher than the single-threaded DeflateStream, particularly
|
|
for larger streams. How large? Anything over 10mb is a good candidate
|
|
for parallel compression.
|
|
</para>
|
|
|
|
<para>
|
|
The tradeoff is that this class uses more memory and more CPU than the
|
|
vanilla DeflateStream, and also is less efficient as a compressor. For
|
|
large files the size of the compressed data stream can be less than 1%
|
|
larger than the size of a compressed data stream from the vanialla
|
|
DeflateStream. For smaller files the difference can be larger. The
|
|
difference will also be larger if you set the BufferSize to be lower than
|
|
the default value. Your mileage may vary. Finally, for small files, the
|
|
ParallelDeflateOutputStream can be much slower than the vanilla
|
|
DeflateStream, because of the overhead associated to using the thread
|
|
pool.
|
|
</para>
|
|
|
|
</remarks>
|
|
<seealso cref="T:Ionic.Zlib.DeflateStream"/>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ParallelDeflateOutputStream.#ctor(System.IO.Stream)">
|
|
<summary>
|
|
Create a ParallelDeflateOutputStream.
|
|
</summary>
|
|
<remarks>
|
|
|
|
<para>
|
|
This stream compresses data written into it via the DEFLATE
|
|
algorithm (see RFC 1951), and writes out the compressed byte stream.
|
|
</para>
|
|
|
|
<para>
|
|
The instance will use the default compression level, the default
|
|
buffer sizes and the default number of threads and buffers per
|
|
thread.
|
|
</para>
|
|
|
|
<para>
|
|
This class is similar to <see cref="T:Ionic.Zlib.DeflateStream"/>,
|
|
except that this implementation uses an approach that employs
|
|
multiple worker threads to perform the DEFLATE. On a multi-cpu or
|
|
multi-core computer, the performance of this class can be
|
|
significantly higher than the single-threaded DeflateStream,
|
|
particularly for larger streams. How large? Anything over 10mb is
|
|
a good candidate for parallel compression.
|
|
</para>
|
|
|
|
</remarks>
|
|
|
|
<example>
|
|
|
|
This example shows how to use a ParallelDeflateOutputStream to compress
|
|
data. It reads a file, compresses it, and writes the compressed data to
|
|
a second, output file.
|
|
|
|
<code>
|
|
byte[] buffer = new byte[WORKING_BUFFER_SIZE];
|
|
int n= -1;
|
|
String outputFile = fileToCompress + ".compressed";
|
|
using (System.IO.Stream input = System.IO.File.OpenRead(fileToCompress))
|
|
{
|
|
using (var raw = System.IO.File.Create(outputFile))
|
|
{
|
|
using (Stream compressor = new ParallelDeflateOutputStream(raw))
|
|
{
|
|
while ((n= input.Read(buffer, 0, buffer.Length)) != 0)
|
|
{
|
|
compressor.Write(buffer, 0, n);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
</code>
|
|
<code lang="VB">
|
|
Dim buffer As Byte() = New Byte(4096) {}
|
|
Dim n As Integer = -1
|
|
Dim outputFile As String = (fileToCompress & ".compressed")
|
|
Using input As Stream = File.OpenRead(fileToCompress)
|
|
Using raw As FileStream = File.Create(outputFile)
|
|
Using compressor As Stream = New ParallelDeflateOutputStream(raw)
|
|
Do While (n <> 0)
|
|
If (n > 0) Then
|
|
compressor.Write(buffer, 0, n)
|
|
End If
|
|
n = input.Read(buffer, 0, buffer.Length)
|
|
Loop
|
|
End Using
|
|
End Using
|
|
End Using
|
|
</code>
|
|
</example>
|
|
<param name="stream">The stream to which compressed data will be written.</param>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ParallelDeflateOutputStream.#ctor(System.IO.Stream,Ionic.Zlib.CompressionLevel)">
|
|
<summary>
|
|
Create a ParallelDeflateOutputStream using the specified CompressionLevel.
|
|
</summary>
|
|
<remarks>
|
|
See the <see cref="M:Ionic.Zlib.ParallelDeflateOutputStream.#ctor(System.IO.Stream)"/>
|
|
constructor for example code.
|
|
</remarks>
|
|
<param name="stream">The stream to which compressed data will be written.</param>
|
|
<param name="level">A tuning knob to trade speed for effectiveness.</param>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ParallelDeflateOutputStream.#ctor(System.IO.Stream,System.Boolean)">
|
|
<summary>
|
|
Create a ParallelDeflateOutputStream and specify whether to leave the captive stream open
|
|
when the ParallelDeflateOutputStream is closed.
|
|
</summary>
|
|
<remarks>
|
|
See the <see cref="M:Ionic.Zlib.ParallelDeflateOutputStream.#ctor(System.IO.Stream)"/>
|
|
constructor for example code.
|
|
</remarks>
|
|
<param name="stream">The stream to which compressed data will be written.</param>
|
|
<param name="leaveOpen">
|
|
true if the application would like the stream to remain open after inflation/deflation.
|
|
</param>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ParallelDeflateOutputStream.#ctor(System.IO.Stream,Ionic.Zlib.CompressionLevel,System.Boolean)">
|
|
<summary>
|
|
Create a ParallelDeflateOutputStream and specify whether to leave the captive stream open
|
|
when the ParallelDeflateOutputStream is closed.
|
|
</summary>
|
|
<remarks>
|
|
See the <see cref="M:Ionic.Zlib.ParallelDeflateOutputStream.#ctor(System.IO.Stream)"/>
|
|
constructor for example code.
|
|
</remarks>
|
|
<param name="stream">The stream to which compressed data will be written.</param>
|
|
<param name="level">A tuning knob to trade speed for effectiveness.</param>
|
|
<param name="leaveOpen">
|
|
true if the application would like the stream to remain open after inflation/deflation.
|
|
</param>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ParallelDeflateOutputStream.#ctor(System.IO.Stream,Ionic.Zlib.CompressionLevel,Ionic.Zlib.CompressionStrategy,System.Boolean)">
|
|
<summary>
|
|
Create a ParallelDeflateOutputStream using the specified
|
|
CompressionLevel and CompressionStrategy, and specifying whether to
|
|
leave the captive stream open when the ParallelDeflateOutputStream is
|
|
closed.
|
|
</summary>
|
|
<remarks>
|
|
See the <see cref="M:Ionic.Zlib.ParallelDeflateOutputStream.#ctor(System.IO.Stream)"/>
|
|
constructor for example code.
|
|
</remarks>
|
|
<param name="stream">The stream to which compressed data will be written.</param>
|
|
<param name="level">A tuning knob to trade speed for effectiveness.</param>
|
|
<param name="strategy">
|
|
By tweaking this parameter, you may be able to optimize the compression for
|
|
data with particular characteristics.
|
|
</param>
|
|
<param name="leaveOpen">
|
|
true if the application would like the stream to remain open after inflation/deflation.
|
|
</param>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ParallelDeflateOutputStream.Write(System.Byte[],System.Int32,System.Int32)">
|
|
<summary>
|
|
Write data to the stream.
|
|
</summary>
|
|
|
|
<remarks>
|
|
|
|
<para>
|
|
To use the ParallelDeflateOutputStream to compress data, create a
|
|
ParallelDeflateOutputStream with CompressionMode.Compress, passing a
|
|
writable output stream. Then call Write() on that
|
|
ParallelDeflateOutputStream, providing uncompressed data as input. The
|
|
data sent to the output stream will be the compressed form of the data
|
|
written.
|
|
</para>
|
|
|
|
<para>
|
|
To decompress data, use the <see cref="T:Ionic.Zlib.DeflateStream"/> class.
|
|
</para>
|
|
|
|
</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.Zlib.ParallelDeflateOutputStream.Flush">
|
|
<summary>
|
|
Flush the stream.
|
|
</summary>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ParallelDeflateOutputStream.Close">
|
|
<summary>
|
|
Close the stream.
|
|
</summary>
|
|
<remarks>
|
|
You must call Close on the stream to guarantee that all of the data written in has
|
|
been compressed, and the compressed data has been written out.
|
|
</remarks>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ParallelDeflateOutputStream.Dispose">
|
|
<summary>Dispose the object</summary>
|
|
<remarks>
|
|
<para>
|
|
Because ParallelDeflateOutputStream is IDisposable, the
|
|
application must call this method when finished using the instance.
|
|
</para>
|
|
<para>
|
|
This method is generally called implicitly upon exit from
|
|
a <c>using</c> scope in C# (<c>Using</c> in VB).
|
|
</para>
|
|
</remarks>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ParallelDeflateOutputStream.Dispose(System.Boolean)">
|
|
<summary>The Dispose method</summary>
|
|
<param name="disposing">
|
|
indicates whether the Dispose method was invoked by user code.
|
|
</param>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ParallelDeflateOutputStream.Reset(System.IO.Stream)">
|
|
<summary>
|
|
Resets the stream for use with another stream.
|
|
</summary>
|
|
<remarks>
|
|
Because the ParallelDeflateOutputStream is expensive to create, it
|
|
has been designed so that it can be recycled and re-used. You have
|
|
to call Close() on the stream first, then you can call Reset() on
|
|
it, to use it again on another stream.
|
|
</remarks>
|
|
|
|
<param name="stream">
|
|
The new output stream for this era.
|
|
</param>
|
|
|
|
<example>
|
|
<code>
|
|
ParallelDeflateOutputStream deflater = null;
|
|
foreach (var inputFile in listOfFiles)
|
|
{
|
|
string outputFile = inputFile + ".compressed";
|
|
using (System.IO.Stream input = System.IO.File.OpenRead(inputFile))
|
|
{
|
|
using (var outStream = System.IO.File.Create(outputFile))
|
|
{
|
|
if (deflater == null)
|
|
deflater = new ParallelDeflateOutputStream(outStream,
|
|
CompressionLevel.Best,
|
|
CompressionStrategy.Default,
|
|
true);
|
|
deflater.Reset(outStream);
|
|
|
|
while ((n= input.Read(buffer, 0, buffer.Length)) != 0)
|
|
{
|
|
deflater.Write(buffer, 0, n);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
</code>
|
|
</example>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ParallelDeflateOutputStream.Read(System.Byte[],System.Int32,System.Int32)">
|
|
<summary>
|
|
This method always throws a NotSupportedException.
|
|
</summary>
|
|
<param name="buffer">
|
|
The buffer into which data would be read, IF THIS METHOD
|
|
ACTUALLY DID ANYTHING.
|
|
</param>
|
|
<param name="offset">
|
|
The offset within that data array at which to insert the
|
|
data that is read, IF THIS METHOD ACTUALLY DID
|
|
ANYTHING.
|
|
</param>
|
|
<param name="count">
|
|
The number of bytes to write, IF THIS METHOD ACTUALLY DID
|
|
ANYTHING.
|
|
</param>
|
|
<returns>nothing.</returns>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ParallelDeflateOutputStream.Seek(System.Int64,System.IO.SeekOrigin)">
|
|
<summary>
|
|
This method always throws a NotSupportedException.
|
|
</summary>
|
|
<param name="offset">
|
|
The offset to seek to....
|
|
IF THIS METHOD ACTUALLY DID ANYTHING.
|
|
</param>
|
|
<param name="origin">
|
|
The reference specifying how to apply the offset.... IF
|
|
THIS METHOD ACTUALLY DID ANYTHING.
|
|
</param>
|
|
<returns>nothing. It always throws.</returns>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ParallelDeflateOutputStream.SetLength(System.Int64)">
|
|
<summary>
|
|
This method always throws a NotSupportedException.
|
|
</summary>
|
|
<param name="value">
|
|
The new value for the stream length.... IF
|
|
THIS METHOD ACTUALLY DID ANYTHING.
|
|
</param>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.ParallelDeflateOutputStream.Strategy">
|
|
<summary>
|
|
The ZLIB strategy to be used during compression.
|
|
</summary>
|
|
|
|
</member>
|
|
<member name="P:Ionic.Zlib.ParallelDeflateOutputStream.MaxBufferPairs">
|
|
<summary>
|
|
The maximum number of buffer pairs to use.
|
|
</summary>
|
|
|
|
<remarks>
|
|
<para>
|
|
This property sets an upper limit on the number of memory buffer
|
|
pairs to create. The implementation of this stream allocates
|
|
multiple buffers to facilitate parallel compression. As each buffer
|
|
fills up, this stream uses <see cref="M:System.Threading.ThreadPool.QueueUserWorkItem(System.Threading.WaitCallback)">
|
|
ThreadPool.QueueUserWorkItem()</see>
|
|
to compress those buffers in a background threadpool thread. After a
|
|
buffer is compressed, it is re-ordered and written to the output
|
|
stream.
|
|
</para>
|
|
|
|
<para>
|
|
A higher number of buffer pairs enables a higher degree of
|
|
parallelism, which tends to increase the speed of compression on
|
|
multi-cpu computers. On the other hand, a higher number of buffer
|
|
pairs also implies a larger memory consumption, more active worker
|
|
threads, and a higher cpu utilization for any compression. This
|
|
property enables the application to limit its memory consumption and
|
|
CPU utilization behavior depending on requirements.
|
|
</para>
|
|
|
|
<para>
|
|
For each compression "task" that occurs in parallel, there are 2
|
|
buffers allocated: one for input and one for output. This property
|
|
sets a limit for the number of pairs. The total amount of storage
|
|
space allocated for buffering will then be (N*S*2), where N is the
|
|
number of buffer pairs, S is the size of each buffer (<see cref="P:Ionic.Zlib.ParallelDeflateOutputStream.BufferSize"/>). By default, DotNetZip allocates 4 buffer
|
|
pairs per CPU core, so if your machine has 4 cores, and you retain
|
|
the default buffer size of 128k, then the
|
|
ParallelDeflateOutputStream will use 4 * 4 * 2 * 128kb of buffer
|
|
memory in total, or 4mb, in blocks of 128kb. If you then set this
|
|
property to 8, then the number will be 8 * 2 * 128kb of buffer
|
|
memory, or 2mb.
|
|
</para>
|
|
|
|
<para>
|
|
CPU utilization will also go up with additional buffers, because a
|
|
larger number of buffer pairs allows a larger number of background
|
|
threads to compress in parallel. If you find that parallel
|
|
compression is consuming too much memory or CPU, you can adjust this
|
|
value downward.
|
|
</para>
|
|
|
|
<para>
|
|
The default value is 16. Different values may deliver better or
|
|
worse results, depending on your priorities and the dynamic
|
|
performance characteristics of your storage and compute resources.
|
|
</para>
|
|
|
|
<para>
|
|
This property is not the number of buffer pairs to use; it is an
|
|
upper limit. An illustration: Suppose you have an application that
|
|
uses the default value of this property (which is 16), and it runs
|
|
on a machine with 2 CPU cores. In that case, DotNetZip will allocate
|
|
4 buffer pairs per CPU core, for a total of 8 pairs. The upper
|
|
limit specified by this property has no effect.
|
|
</para>
|
|
|
|
<para>
|
|
The application can set this value at any time, but it is effective
|
|
only before the first call to Write(), which is when the buffers are
|
|
allocated.
|
|
</para>
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.ParallelDeflateOutputStream.BufferSize">
|
|
<summary>
|
|
The size of the buffers used by the compressor threads.
|
|
</summary>
|
|
<remarks>
|
|
|
|
<para>
|
|
The default buffer size is 128k. The application can set this value
|
|
at any time, but it is effective only before the first Write().
|
|
</para>
|
|
|
|
<para>
|
|
Larger buffer sizes implies larger memory consumption but allows
|
|
more efficient compression. Using smaller buffer sizes consumes less
|
|
memory but may result in less effective compression. For example,
|
|
using the default buffer size of 128k, the compression delivered is
|
|
within 1% of the compression delivered by the single-threaded <see cref="T:Ionic.Zlib.DeflateStream"/>. On the other hand, using a
|
|
BufferSize of 8k can result in a compressed data stream that is 5%
|
|
larger than that delivered by the single-threaded
|
|
<c>DeflateStream</c>. Excessively small buffer sizes can also cause
|
|
the speed of the ParallelDeflateOutputStream to drop, because of
|
|
larger thread scheduling overhead dealing with many many small
|
|
buffers.
|
|
</para>
|
|
|
|
<para>
|
|
The total amount of storage space allocated for buffering will be
|
|
(N*S*2), where N is the number of buffer pairs, and S is the size of
|
|
each buffer (this property). There are 2 buffers used by the
|
|
compressor, one for input and one for output. By default, DotNetZip
|
|
allocates 4 buffer pairs per CPU core, so if your machine has 4
|
|
cores, then the number of buffer pairs used will be 16. If you
|
|
accept the default value of this property, 128k, then the
|
|
ParallelDeflateOutputStream will use 16 * 2 * 128kb of buffer memory
|
|
in total, or 4mb, in blocks of 128kb. If you set this property to
|
|
64kb, then the number will be 16 * 2 * 64kb of buffer memory, or
|
|
2mb.
|
|
</para>
|
|
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.ParallelDeflateOutputStream.Crc32">
|
|
<summary>
|
|
The CRC32 for the data that was written out, prior to compression.
|
|
</summary>
|
|
<remarks>
|
|
This value is meaningful only after a call to Close().
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.ParallelDeflateOutputStream.BytesProcessed">
|
|
<summary>
|
|
The total number of uncompressed bytes processed by the ParallelDeflateOutputStream.
|
|
</summary>
|
|
<remarks>
|
|
This value is meaningful only after a call to Close().
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.ParallelDeflateOutputStream.CanSeek">
|
|
<summary>
|
|
Indicates whether the stream supports Seek operations.
|
|
</summary>
|
|
<remarks>
|
|
Always returns false.
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.ParallelDeflateOutputStream.CanRead">
|
|
<summary>
|
|
Indicates whether the stream supports Read operations.
|
|
</summary>
|
|
<remarks>
|
|
Always returns false.
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.ParallelDeflateOutputStream.CanWrite">
|
|
<summary>
|
|
Indicates whether the stream supports Write operations.
|
|
</summary>
|
|
<remarks>
|
|
Returns true if the provided stream is writable.
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.ParallelDeflateOutputStream.Length">
|
|
<summary>
|
|
Reading this property always throws a NotSupportedException.
|
|
</summary>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.ParallelDeflateOutputStream.Position">
|
|
<summary>
|
|
Returns the current position of the output stream.
|
|
</summary>
|
|
<remarks>
|
|
<para>
|
|
Because the output gets written by a background thread,
|
|
the value may change asynchronously. Setting this
|
|
property always throws a NotSupportedException.
|
|
</para>
|
|
</remarks>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.Tree.DistanceCode(System.Int32)">
|
|
<summary>
|
|
Map from a distance to a distance code.
|
|
</summary>
|
|
<remarks>
|
|
No side effects. _dist_code[256] and _dist_code[257] are never used.
|
|
</remarks>
|
|
</member>
|
|
<member name="T:Ionic.Zlib.FlushType">
|
|
<summary>
|
|
Describes how to flush the current deflate operation.
|
|
</summary>
|
|
<remarks>
|
|
The different FlushType values are useful when using a Deflate in a streaming application.
|
|
</remarks>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.FlushType.None">
|
|
<summary>No flush at all.</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.FlushType.Partial">
|
|
<summary>Closes the current block, but doesn't flush it to
|
|
the output. Used internally only in hypothetical
|
|
scenarios. This was supposed to be removed by Zlib, but it is
|
|
still in use in some edge cases.
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.FlushType.Sync">
|
|
<summary>
|
|
Use this during compression to specify that all pending output should be
|
|
flushed to the output buffer and the output should be aligned on a byte
|
|
boundary. You might use this in a streaming communication scenario, so that
|
|
the decompressor can get all input data available so far. When using this
|
|
with a ZlibCodec, <c>AvailableBytesIn</c> will be zero after the call if
|
|
enough output space has been provided before the call. Flushing will
|
|
degrade compression and so it should be used only when necessary.
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.FlushType.Full">
|
|
<summary>
|
|
Use this during compression to specify that all output should be flushed, as
|
|
with <c>FlushType.Sync</c>, but also, the compression state should be reset
|
|
so that decompression can restart from this point if previous compressed
|
|
data has been damaged or if random access is desired. Using
|
|
<c>FlushType.Full</c> too often can significantly degrade the compression.
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.FlushType.Finish">
|
|
<summary>Signals the end of the compression/decompression stream.</summary>
|
|
</member>
|
|
<member name="T:Ionic.Zlib.CompressionLevel">
|
|
<summary>
|
|
The compression level to be used when using a DeflateStream or ZlibStream with CompressionMode.Compress.
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.CompressionLevel.None">
|
|
<summary>
|
|
None means that the data will be simply stored, with no change at all.
|
|
If you are producing ZIPs for use on Mac OSX, be aware that archives produced with CompressionLevel.None
|
|
cannot be opened with the default zip reader. Use a different CompressionLevel.
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.CompressionLevel.Level0">
|
|
<summary>
|
|
Same as None.
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.CompressionLevel.BestSpeed">
|
|
<summary>
|
|
The fastest but least effective compression.
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.CompressionLevel.Level1">
|
|
<summary>
|
|
A synonym for BestSpeed.
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.CompressionLevel.Level2">
|
|
<summary>
|
|
A little slower, but better, than level 1.
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.CompressionLevel.Level3">
|
|
<summary>
|
|
A little slower, but better, than level 2.
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.CompressionLevel.Level4">
|
|
<summary>
|
|
A little slower, but better, than level 3.
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.CompressionLevel.Level5">
|
|
<summary>
|
|
A little slower than level 4, but with better compression.
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.CompressionLevel.Default">
|
|
<summary>
|
|
The default compression level, with a good balance of speed and compression efficiency.
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.CompressionLevel.Level6">
|
|
<summary>
|
|
A synonym for Default.
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.CompressionLevel.Level7">
|
|
<summary>
|
|
Pretty good compression!
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.CompressionLevel.Level8">
|
|
<summary>
|
|
Better compression than Level7!
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.CompressionLevel.BestCompression">
|
|
<summary>
|
|
The "best" compression, where best means greatest reduction in size of the input data stream.
|
|
This is also the slowest compression.
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.CompressionLevel.Level9">
|
|
<summary>
|
|
A synonym for BestCompression.
|
|
</summary>
|
|
</member>
|
|
<member name="T:Ionic.Zlib.CompressionStrategy">
|
|
<summary>
|
|
Describes options for how the compression algorithm is executed. Different 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.
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.CompressionStrategy.Default">
|
|
<summary>
|
|
The default strategy is probably the best for normal data.
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.CompressionStrategy.Filtered">
|
|
<summary>
|
|
The <c>Filtered</c> strategy is intended to be used most effectively with data produced by a
|
|
filter or predictor. By this definition, filtered data consists mostly of small
|
|
values with a somewhat random distribution. In this case, the compression algorithm
|
|
is tuned to compress them better. The effect of <c>Filtered</c> is to force more Huffman
|
|
coding and less string matching; it is a half-step between <c>Default</c> and <c>HuffmanOnly</c>.
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.CompressionStrategy.HuffmanOnly">
|
|
<summary>
|
|
Using <c>HuffmanOnly</c> will force the compressor to do Huffman encoding only, with no
|
|
string matching.
|
|
</summary>
|
|
</member>
|
|
<member name="T:Ionic.Zlib.CompressionMode">
|
|
<summary>
|
|
An enum to specify the direction of transcoding - whether to compress or decompress.
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.CompressionMode.Compress">
|
|
<summary>
|
|
Used to specify that the stream should compress the data.
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.CompressionMode.Decompress">
|
|
<summary>
|
|
Used to specify that the stream should decompress the data.
|
|
</summary>
|
|
</member>
|
|
<member name="T:Ionic.Zlib.ZlibException">
|
|
<summary>
|
|
A general purpose exception class for exceptions in the Zlib library.
|
|
</summary>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ZlibException.#ctor">
|
|
<summary>
|
|
The ZlibException class captures exception information generated
|
|
by the Zlib library.
|
|
</summary>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ZlibException.#ctor(System.String)">
|
|
<summary>
|
|
This ctor collects a message attached to the exception.
|
|
</summary>
|
|
<param name="s">the message for the exception.</param>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.SharedUtils.URShift(System.Int32,System.Int32)">
|
|
<summary>
|
|
Performs an unsigned bitwise right shift with the specified number
|
|
</summary>
|
|
<param name="number">Number to operate on</param>
|
|
<param name="bits">Ammount of bits to shift</param>
|
|
<returns>The resulting number from the shift operation</returns>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.SharedUtils.ReadInput(System.IO.TextReader,System.Byte[],System.Int32,System.Int32)">
|
|
<summary>
|
|
Reads a number of characters from the current source TextReader and writes
|
|
the data to the target array at the specified index.
|
|
</summary>
|
|
|
|
<param name="sourceTextReader">The source TextReader to read from</param>
|
|
<param name="target">Contains the array of characteres read from the source TextReader.</param>
|
|
<param name="start">The starting index of the target array.</param>
|
|
<param name="count">The maximum number of characters to read from the source TextReader.</param>
|
|
|
|
<returns>
|
|
The number of characters read. The number will be less than or equal to
|
|
count depending on the data available in the source TextReader. Returns -1
|
|
if the end of the stream is reached.
|
|
</returns>
|
|
</member>
|
|
<member name="T:Ionic.Zlib.Adler">
|
|
<summary>
|
|
Computes an Adler-32 checksum.
|
|
</summary>
|
|
<remarks>
|
|
The Adler checksum is similar to a CRC checksum, but faster to compute, though less
|
|
reliable. It is used in producing RFC1950 compressed streams. The Adler checksum
|
|
is a required part of the "ZLIB" standard. Applications will almost never need to
|
|
use this class directly.
|
|
</remarks>
|
|
|
|
<exclude/>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.Adler.Adler32(System.UInt32,System.Byte[],System.Int32,System.Int32)">
|
|
<summary>
|
|
Calculates the Adler32 checksum.
|
|
</summary>
|
|
<remarks>
|
|
<para>
|
|
This is used within ZLIB. You probably don't need to use this directly.
|
|
</para>
|
|
</remarks>
|
|
<example>
|
|
To compute an Adler32 checksum on a byte array:
|
|
<code>
|
|
var adler = Adler.Adler32(0, null, 0, 0);
|
|
adler = Adler.Adler32(adler, buffer, index, length);
|
|
</code>
|
|
</example>
|
|
</member>
|
|
<member name="T:Ionic.Zlib.ZlibCodec">
|
|
<summary>
|
|
Encoder and Decoder for ZLIB and DEFLATE (IETF RFC1950 and RFC1951).
|
|
</summary>
|
|
|
|
<remarks>
|
|
This class compresses and decompresses data according to the Deflate algorithm
|
|
and optionally, the ZLIB format, as documented in <see
|
|
href="http://www.ietf.org/rfc/rfc1950.txt">RFC 1950 - ZLIB</see> and <see
|
|
href="http://www.ietf.org/rfc/rfc1951.txt">RFC 1951 - DEFLATE</see>.
|
|
</remarks>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.ZlibCodec.InputBuffer">
|
|
<summary>
|
|
The buffer from which data is taken.
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.ZlibCodec.NextIn">
|
|
<summary>
|
|
An index into the InputBuffer array, indicating where to start reading.
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.ZlibCodec.AvailableBytesIn">
|
|
<summary>
|
|
The number of bytes available in the InputBuffer, starting at NextIn.
|
|
</summary>
|
|
<remarks>
|
|
Generally you should set this to InputBuffer.Length before the first Inflate() or Deflate() call.
|
|
The class will update this number as calls to Inflate/Deflate are made.
|
|
</remarks>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.ZlibCodec.TotalBytesIn">
|
|
<summary>
|
|
Total number of bytes read so far, through all calls to Inflate()/Deflate().
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.ZlibCodec.OutputBuffer">
|
|
<summary>
|
|
Buffer to store output data.
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.ZlibCodec.NextOut">
|
|
<summary>
|
|
An index into the OutputBuffer array, indicating where to start writing.
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.ZlibCodec.AvailableBytesOut">
|
|
<summary>
|
|
The number of bytes available in the OutputBuffer, starting at NextOut.
|
|
</summary>
|
|
<remarks>
|
|
Generally you should set this to OutputBuffer.Length before the first Inflate() or Deflate() call.
|
|
The class will update this number as calls to Inflate/Deflate are made.
|
|
</remarks>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.ZlibCodec.TotalBytesOut">
|
|
<summary>
|
|
Total number of bytes written to the output so far, through all calls to Inflate()/Deflate().
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.ZlibCodec.Message">
|
|
<summary>
|
|
used for diagnostics, when something goes wrong!
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.ZlibCodec.CompressLevel">
|
|
<summary>
|
|
The compression level to use in this codec. Useful only in compression mode.
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.ZlibCodec.WindowBits">
|
|
<summary>
|
|
The number of Window Bits to use.
|
|
</summary>
|
|
<remarks>
|
|
This gauges the size of the sliding window, and hence the
|
|
compression effectiveness as well as memory consumption. It's best to just leave this
|
|
setting alone if you don't know what it is. The maximum value is 15 bits, which implies
|
|
a 32k window.
|
|
</remarks>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.ZlibCodec.Strategy">
|
|
<summary>
|
|
The compression strategy to use.
|
|
</summary>
|
|
<remarks>
|
|
This is only effective in compression. The theory offered by ZLIB is that different
|
|
strategies could potentially produce significant differences in compression behavior
|
|
for different data sets. Unfortunately I don't have any good recommendations for how
|
|
to set it differently. When I tested changing the strategy I got minimally different
|
|
compression performance. It's best to leave this property alone if you don't have a
|
|
good feel for it. Or, you may want to produce a test harness that runs through the
|
|
different strategy options and evaluates them on different file types. If you do that,
|
|
let me know your results.
|
|
</remarks>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ZlibCodec.#ctor">
|
|
<summary>
|
|
Create a ZlibCodec.
|
|
</summary>
|
|
<remarks>
|
|
If you use this default constructor, you will later have to explicitly call
|
|
InitializeInflate() or InitializeDeflate() before using the ZlibCodec to compress
|
|
or decompress.
|
|
</remarks>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ZlibCodec.#ctor(Ionic.Zlib.CompressionMode)">
|
|
<summary>
|
|
Create a ZlibCodec that either compresses or decompresses.
|
|
</summary>
|
|
<param name="mode">
|
|
Indicates whether the codec should compress (deflate) or decompress (inflate).
|
|
</param>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ZlibCodec.InitializeInflate">
|
|
<summary>
|
|
Initialize the inflation state.
|
|
</summary>
|
|
<remarks>
|
|
It is not necessary to call this before using the ZlibCodec to inflate data;
|
|
It is implicitly called when you call the constructor.
|
|
</remarks>
|
|
<returns>Z_OK if everything goes well.</returns>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ZlibCodec.InitializeInflate(System.Boolean)">
|
|
<summary>
|
|
Initialize the inflation state with an explicit flag to
|
|
govern the handling of RFC1950 header bytes.
|
|
</summary>
|
|
|
|
<remarks>
|
|
By default, the ZLIB header defined in <see
|
|
href="http://www.ietf.org/rfc/rfc1950.txt">RFC 1950</see> is expected. If
|
|
you want to read a zlib stream you should specify true for
|
|
expectRfc1950Header. If you have a deflate stream, you will want to specify
|
|
false. It is only necessary to invoke this initializer explicitly if you
|
|
want to specify false.
|
|
</remarks>
|
|
|
|
<param name="expectRfc1950Header">whether to expect an RFC1950 header byte
|
|
pair when reading the stream of data to be inflated.</param>
|
|
|
|
<returns>Z_OK if everything goes well.</returns>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ZlibCodec.InitializeInflate(System.Int32)">
|
|
<summary>
|
|
Initialize the ZlibCodec for inflation, with the specified number of window bits.
|
|
</summary>
|
|
<param name="windowBits">The number of window bits to use. If you need to ask what that is,
|
|
then you shouldn't be calling this initializer.</param>
|
|
<returns>Z_OK if all goes well.</returns>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ZlibCodec.InitializeInflate(System.Int32,System.Boolean)">
|
|
<summary>
|
|
Initialize the inflation state with an explicit flag to govern the handling of
|
|
RFC1950 header bytes.
|
|
</summary>
|
|
|
|
<remarks>
|
|
If you want to read a zlib stream you should specify true for
|
|
expectRfc1950Header. In this case, the library will expect to find a ZLIB
|
|
header, as defined in <see href="http://www.ietf.org/rfc/rfc1950.txt">RFC
|
|
1950</see>, in the compressed stream. If you will be reading a DEFLATE or
|
|
GZIP stream, which does not have such a header, you will want to specify
|
|
false.
|
|
</remarks>
|
|
|
|
<param name="expectRfc1950Header">whether to expect an RFC1950 header byte pair when reading
|
|
the stream of data to be inflated.</param>
|
|
<param name="windowBits">The number of window bits to use. If you need to ask what that is,
|
|
then you shouldn't be calling this initializer.</param>
|
|
<returns>Z_OK if everything goes well.</returns>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ZlibCodec.Inflate(Ionic.Zlib.FlushType)">
|
|
<summary>
|
|
Inflate the data in the InputBuffer, placing the result in the OutputBuffer.
|
|
</summary>
|
|
<remarks>
|
|
You must have set InputBuffer and OutputBuffer, NextIn and NextOut, and AvailableBytesIn and
|
|
AvailableBytesOut before calling this method.
|
|
</remarks>
|
|
<example>
|
|
<code>
|
|
private void InflateBuffer()
|
|
{
|
|
int bufferSize = 1024;
|
|
byte[] buffer = new byte[bufferSize];
|
|
ZlibCodec decompressor = new ZlibCodec();
|
|
|
|
Console.WriteLine("\n============================================");
|
|
Console.WriteLine("Size of Buffer to Inflate: {0} bytes.", CompressedBytes.Length);
|
|
MemoryStream ms = new MemoryStream(DecompressedBytes);
|
|
|
|
int rc = decompressor.InitializeInflate();
|
|
|
|
decompressor.InputBuffer = CompressedBytes;
|
|
decompressor.NextIn = 0;
|
|
decompressor.AvailableBytesIn = CompressedBytes.Length;
|
|
|
|
decompressor.OutputBuffer = buffer;
|
|
|
|
// pass 1: inflate
|
|
do
|
|
{
|
|
decompressor.NextOut = 0;
|
|
decompressor.AvailableBytesOut = buffer.Length;
|
|
rc = decompressor.Inflate(FlushType.None);
|
|
|
|
if (rc != ZlibConstants.Z_OK && rc != ZlibConstants.Z_STREAM_END)
|
|
throw new Exception("inflating: " + decompressor.Message);
|
|
|
|
ms.Write(decompressor.OutputBuffer, 0, buffer.Length - decompressor.AvailableBytesOut);
|
|
}
|
|
while (decompressor.AvailableBytesIn > 0 || decompressor.AvailableBytesOut == 0);
|
|
|
|
// pass 2: finish and flush
|
|
do
|
|
{
|
|
decompressor.NextOut = 0;
|
|
decompressor.AvailableBytesOut = buffer.Length;
|
|
rc = decompressor.Inflate(FlushType.Finish);
|
|
|
|
if (rc != ZlibConstants.Z_STREAM_END && rc != ZlibConstants.Z_OK)
|
|
throw new Exception("inflating: " + decompressor.Message);
|
|
|
|
if (buffer.Length - decompressor.AvailableBytesOut > 0)
|
|
ms.Write(buffer, 0, buffer.Length - decompressor.AvailableBytesOut);
|
|
}
|
|
while (decompressor.AvailableBytesIn > 0 || decompressor.AvailableBytesOut == 0);
|
|
|
|
decompressor.EndInflate();
|
|
}
|
|
|
|
</code>
|
|
</example>
|
|
<param name="flush">The flush to use when inflating.</param>
|
|
<returns>Z_OK if everything goes well.</returns>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ZlibCodec.EndInflate">
|
|
<summary>
|
|
Ends an inflation session.
|
|
</summary>
|
|
<remarks>
|
|
Call this after successively calling Inflate(). This will cause all buffers to be flushed.
|
|
After calling this you cannot call Inflate() without a intervening call to one of the
|
|
InitializeInflate() overloads.
|
|
</remarks>
|
|
<returns>Z_OK if everything goes well.</returns>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ZlibCodec.SyncInflate">
|
|
<summary>
|
|
I don't know what this does!
|
|
</summary>
|
|
<returns>Z_OK if everything goes well.</returns>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ZlibCodec.InitializeDeflate">
|
|
<summary>
|
|
Initialize the ZlibCodec for deflation operation.
|
|
</summary>
|
|
<remarks>
|
|
The codec will use the MAX window bits and the default level of compression.
|
|
</remarks>
|
|
<example>
|
|
<code>
|
|
int bufferSize = 40000;
|
|
byte[] CompressedBytes = new byte[bufferSize];
|
|
byte[] DecompressedBytes = new byte[bufferSize];
|
|
|
|
ZlibCodec compressor = new ZlibCodec();
|
|
|
|
compressor.InitializeDeflate(CompressionLevel.Default);
|
|
|
|
compressor.InputBuffer = System.Text.ASCIIEncoding.ASCII.GetBytes(TextToCompress);
|
|
compressor.NextIn = 0;
|
|
compressor.AvailableBytesIn = compressor.InputBuffer.Length;
|
|
|
|
compressor.OutputBuffer = CompressedBytes;
|
|
compressor.NextOut = 0;
|
|
compressor.AvailableBytesOut = CompressedBytes.Length;
|
|
|
|
while (compressor.TotalBytesIn != TextToCompress.Length && compressor.TotalBytesOut < bufferSize)
|
|
{
|
|
compressor.Deflate(FlushType.None);
|
|
}
|
|
|
|
while (true)
|
|
{
|
|
int rc= compressor.Deflate(FlushType.Finish);
|
|
if (rc == ZlibConstants.Z_STREAM_END) break;
|
|
}
|
|
|
|
compressor.EndDeflate();
|
|
|
|
</code>
|
|
</example>
|
|
<returns>Z_OK if all goes well. You generally don't need to check the return code.</returns>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ZlibCodec.InitializeDeflate(Ionic.Zlib.CompressionLevel)">
|
|
<summary>
|
|
Initialize the ZlibCodec for deflation operation, using the specified CompressionLevel.
|
|
</summary>
|
|
<remarks>
|
|
The codec will use the maximum window bits (15) and the specified
|
|
CompressionLevel. It will emit a ZLIB stream as it compresses.
|
|
</remarks>
|
|
<param name="level">The compression level for the codec.</param>
|
|
<returns>Z_OK if all goes well.</returns>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ZlibCodec.InitializeDeflate(Ionic.Zlib.CompressionLevel,System.Boolean)">
|
|
<summary>
|
|
Initialize the ZlibCodec for deflation operation, using the specified CompressionLevel,
|
|
and the explicit flag governing whether to emit an RFC1950 header byte pair.
|
|
</summary>
|
|
<remarks>
|
|
The codec will use the maximum window bits (15) and the specified CompressionLevel.
|
|
If you want to generate a zlib stream, you should specify true for
|
|
wantRfc1950Header. In this case, the library will emit a ZLIB
|
|
header, as defined in <see href="http://www.ietf.org/rfc/rfc1950.txt">RFC
|
|
1950</see>, in the compressed stream.
|
|
</remarks>
|
|
<param name="level">The compression level for the codec.</param>
|
|
<param name="wantRfc1950Header">whether to emit an initial RFC1950 byte pair in the compressed stream.</param>
|
|
<returns>Z_OK if all goes well.</returns>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ZlibCodec.InitializeDeflate(Ionic.Zlib.CompressionLevel,System.Int32)">
|
|
<summary>
|
|
Initialize the ZlibCodec for deflation operation, using the specified CompressionLevel,
|
|
and the specified number of window bits.
|
|
</summary>
|
|
<remarks>
|
|
The codec will use the specified number of window bits and the specified CompressionLevel.
|
|
</remarks>
|
|
<param name="level">The compression level for the codec.</param>
|
|
<param name="bits">the number of window bits to use. If you don't know what this means, don't use this method.</param>
|
|
<returns>Z_OK if all goes well.</returns>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ZlibCodec.InitializeDeflate(Ionic.Zlib.CompressionLevel,System.Int32,System.Boolean)">
|
|
<summary>
|
|
Initialize the ZlibCodec for deflation operation, using the specified
|
|
CompressionLevel, the specified number of window bits, and the explicit flag
|
|
governing whether to emit an RFC1950 header byte pair.
|
|
</summary>
|
|
|
|
<param name="level">The compression level for the codec.</param>
|
|
<param name="wantRfc1950Header">whether to emit an initial RFC1950 byte pair in the compressed stream.</param>
|
|
<param name="bits">the number of window bits to use. If you don't know what this means, don't use this method.</param>
|
|
<returns>Z_OK if all goes well.</returns>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ZlibCodec.Deflate(Ionic.Zlib.FlushType)">
|
|
<summary>
|
|
Deflate one batch of data.
|
|
</summary>
|
|
<remarks>
|
|
You must have set InputBuffer and OutputBuffer before calling this method.
|
|
</remarks>
|
|
<example>
|
|
<code>
|
|
private void DeflateBuffer(CompressionLevel level)
|
|
{
|
|
int bufferSize = 1024;
|
|
byte[] buffer = new byte[bufferSize];
|
|
ZlibCodec compressor = new ZlibCodec();
|
|
|
|
Console.WriteLine("\n============================================");
|
|
Console.WriteLine("Size of Buffer to Deflate: {0} bytes.", UncompressedBytes.Length);
|
|
MemoryStream ms = new MemoryStream();
|
|
|
|
int rc = compressor.InitializeDeflate(level);
|
|
|
|
compressor.InputBuffer = UncompressedBytes;
|
|
compressor.NextIn = 0;
|
|
compressor.AvailableBytesIn = UncompressedBytes.Length;
|
|
|
|
compressor.OutputBuffer = buffer;
|
|
|
|
// pass 1: deflate
|
|
do
|
|
{
|
|
compressor.NextOut = 0;
|
|
compressor.AvailableBytesOut = buffer.Length;
|
|
rc = compressor.Deflate(FlushType.None);
|
|
|
|
if (rc != ZlibConstants.Z_OK && rc != ZlibConstants.Z_STREAM_END)
|
|
throw new Exception("deflating: " + compressor.Message);
|
|
|
|
ms.Write(compressor.OutputBuffer, 0, buffer.Length - compressor.AvailableBytesOut);
|
|
}
|
|
while (compressor.AvailableBytesIn > 0 || compressor.AvailableBytesOut == 0);
|
|
|
|
// pass 2: finish and flush
|
|
do
|
|
{
|
|
compressor.NextOut = 0;
|
|
compressor.AvailableBytesOut = buffer.Length;
|
|
rc = compressor.Deflate(FlushType.Finish);
|
|
|
|
if (rc != ZlibConstants.Z_STREAM_END && rc != ZlibConstants.Z_OK)
|
|
throw new Exception("deflating: " + compressor.Message);
|
|
|
|
if (buffer.Length - compressor.AvailableBytesOut > 0)
|
|
ms.Write(buffer, 0, buffer.Length - compressor.AvailableBytesOut);
|
|
}
|
|
while (compressor.AvailableBytesIn > 0 || compressor.AvailableBytesOut == 0);
|
|
|
|
compressor.EndDeflate();
|
|
|
|
ms.Seek(0, SeekOrigin.Begin);
|
|
CompressedBytes = new byte[compressor.TotalBytesOut];
|
|
ms.Read(CompressedBytes, 0, CompressedBytes.Length);
|
|
}
|
|
</code>
|
|
</example>
|
|
<param name="flush">whether to flush all data as you deflate. Generally you will want to
|
|
use Z_NO_FLUSH here, in a series of calls to Deflate(), and then call EndDeflate() to
|
|
flush everything.
|
|
</param>
|
|
<returns>Z_OK if all goes well.</returns>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ZlibCodec.EndDeflate">
|
|
<summary>
|
|
End a deflation session.
|
|
</summary>
|
|
<remarks>
|
|
Call this after making a series of one or more calls to Deflate(). All buffers are flushed.
|
|
</remarks>
|
|
<returns>Z_OK if all goes well.</returns>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ZlibCodec.ResetDeflate">
|
|
<summary>
|
|
Reset a codec for another deflation session.
|
|
</summary>
|
|
<remarks>
|
|
Call this to reset the deflation state. For example if a thread is deflating
|
|
non-consecutive blocks, you can call Reset() after the Deflate(Sync) of the first
|
|
block and before the next Deflate(None) of the second block.
|
|
</remarks>
|
|
<returns>Z_OK if all goes well.</returns>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ZlibCodec.SetDeflateParams(Ionic.Zlib.CompressionLevel,Ionic.Zlib.CompressionStrategy)">
|
|
<summary>
|
|
Set the CompressionStrategy and CompressionLevel for a deflation session.
|
|
</summary>
|
|
<param name="level">the level of compression to use.</param>
|
|
<param name="strategy">the strategy to use for compression.</param>
|
|
<returns>Z_OK if all goes well.</returns>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ZlibCodec.SetDictionary(System.Byte[])">
|
|
<summary>
|
|
Set the dictionary to be used for either Inflation or Deflation.
|
|
</summary>
|
|
<param name="dictionary">The dictionary bytes to use.</param>
|
|
<returns>Z_OK if all goes well.</returns>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.ZlibCodec.Adler32">
|
|
<summary>
|
|
The Adler32 checksum on the data transferred through the codec so far. You probably don't need to look at this.
|
|
</summary>
|
|
</member>
|
|
<member name="T:Ionic.Zlib.ZlibConstants">
|
|
<summary>
|
|
A bunch of constants used in the Zlib interface.
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.ZlibConstants.WindowBitsMax">
|
|
<summary>
|
|
The maximum number of window bits for the Deflate algorithm.
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.ZlibConstants.WindowBitsDefault">
|
|
<summary>
|
|
The default number of window bits for the Deflate algorithm.
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.ZlibConstants.Z_OK">
|
|
<summary>
|
|
indicates everything is A-OK
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.ZlibConstants.Z_STREAM_END">
|
|
<summary>
|
|
Indicates that the last operation reached the end of the stream.
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.ZlibConstants.Z_NEED_DICT">
|
|
<summary>
|
|
The operation ended in need of a dictionary.
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.ZlibConstants.Z_STREAM_ERROR">
|
|
<summary>
|
|
There was an error with the stream - not enough data, not open and readable, etc.
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.ZlibConstants.Z_DATA_ERROR">
|
|
<summary>
|
|
There was an error with the data - not enough data, bad data, etc.
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.ZlibConstants.Z_BUF_ERROR">
|
|
<summary>
|
|
There was an error with the working buffer.
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.ZlibConstants.WorkingBufferSizeDefault">
|
|
<summary>
|
|
The size of the working buffer used in the ZlibCodec class. Defaults to 8192 bytes.
|
|
</summary>
|
|
</member>
|
|
<member name="F:Ionic.Zlib.ZlibConstants.WorkingBufferSizeMin">
|
|
<summary>
|
|
The minimum size of the working buffer used in the ZlibCodec class. Currently it is 128 bytes.
|
|
</summary>
|
|
</member>
|
|
<member name="T:Ionic.Zlib.ZlibStream">
|
|
<summary>
|
|
Represents a Zlib stream for compression or decompression.
|
|
</summary>
|
|
<remarks>
|
|
|
|
<para>
|
|
The ZlibStream is a <see href="http://en.wikipedia.org/wiki/Decorator_pattern">Decorator</see> on a <see cref="T:System.IO.Stream"/>. It adds ZLIB compression or decompression to any
|
|
stream.
|
|
</para>
|
|
|
|
<para> Using this stream, applications can compress or decompress data via
|
|
stream <c>Read()</c> and <c>Write()</c> operations. Either compresssion or
|
|
decompression can occur through either reading or writing. The compression
|
|
format used is ZLIB, which is documented in <see href="http://www.ietf.org/rfc/rfc1950.txt">IETF RFC 1950</see>, "ZLIB Compressed
|
|
Data Format Specification version 3.3". This implementation of ZLIB always uses
|
|
DEFLATE as the compression method. (see <see href="http://www.ietf.org/rfc/rfc1951.txt">IETF RFC 1951</see>, "DEFLATE
|
|
Compressed Data Format Specification version 1.3.") </para>
|
|
|
|
<para>
|
|
The ZLIB format allows for varying compression methods, window sizes, and dictionaries.
|
|
This implementation always uses the DEFLATE compression method, a preset dictionary,
|
|
and 15 window bits by default.
|
|
</para>
|
|
|
|
<para>
|
|
This class is similar to <see cref="T:Ionic.Zlib.DeflateStream"/>, except that it adds the
|
|
RFC1950 header and trailer bytes to a compressed stream when compressing, or expects
|
|
the RFC1950 header and trailer bytes when decompressing. It is also similar to the
|
|
<see cref="T:Ionic.Zlib.GZipStream"/>.
|
|
</para>
|
|
</remarks>
|
|
<seealso cref="T:Ionic.Zlib.DeflateStream"/>
|
|
<seealso cref="T:Ionic.Zlib.GZipStream"/>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ZlibStream.#ctor(System.IO.Stream,Ionic.Zlib.CompressionMode)">
|
|
<summary>
|
|
Create a <c>ZlibStream</c> using the specified <c>CompressionMode</c>.
|
|
</summary>
|
|
<remarks>
|
|
|
|
<para>
|
|
When mode is <c>CompressionMode.Compress</c>, the <c>ZlibStream</c>
|
|
will use the default compression level. The "captive" stream will be
|
|
closed when the <c>ZlibStream</c> is closed.
|
|
</para>
|
|
|
|
</remarks>
|
|
|
|
<example>
|
|
This example uses a <c>ZlibStream</c> to compress a file, and writes the
|
|
compressed data to another file.
|
|
<code>
|
|
using (System.IO.Stream input = System.IO.File.OpenRead(fileToCompress))
|
|
{
|
|
using (var raw = System.IO.File.Create(fileToCompress + ".zlib"))
|
|
{
|
|
using (Stream compressor = new ZlibStream(raw, CompressionMode.Compress))
|
|
{
|
|
byte[] buffer = new byte[WORKING_BUFFER_SIZE];
|
|
int n;
|
|
while ((n= input.Read(buffer, 0, buffer.Length)) != 0)
|
|
{
|
|
compressor.Write(buffer, 0, n);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
</code>
|
|
<code lang="VB">
|
|
Using input As Stream = File.OpenRead(fileToCompress)
|
|
Using raw As FileStream = File.Create(fileToCompress & ".zlib")
|
|
Using compressor As Stream = New ZlibStream(raw, CompressionMode.Compress)
|
|
Dim buffer As Byte() = New Byte(4096) {}
|
|
Dim n As Integer = -1
|
|
Do While (n <> 0)
|
|
If (n > 0) Then
|
|
compressor.Write(buffer, 0, n)
|
|
End If
|
|
n = input.Read(buffer, 0, buffer.Length)
|
|
Loop
|
|
End Using
|
|
End Using
|
|
End Using
|
|
</code>
|
|
</example>
|
|
|
|
<param name="stream">The stream which will be read or written.</param>
|
|
<param name="mode">Indicates whether the ZlibStream will compress or decompress.</param>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ZlibStream.#ctor(System.IO.Stream,Ionic.Zlib.CompressionMode,Ionic.Zlib.CompressionLevel)">
|
|
<summary>
|
|
Create a <c>ZlibStream</c> using the specified <c>CompressionMode</c> and
|
|
the specified <c>CompressionLevel</c>.
|
|
</summary>
|
|
|
|
<remarks>
|
|
|
|
<para>
|
|
When mode is <c>CompressionMode.Decompress</c>, the level parameter is ignored.
|
|
The "captive" stream will be closed when the <c>ZlibStream</c> is closed.
|
|
</para>
|
|
|
|
</remarks>
|
|
|
|
<example>
|
|
This example uses a <c>ZlibStream</c> to compress data from a file, and writes the
|
|
compressed data to another file.
|
|
|
|
<code>
|
|
using (System.IO.Stream input = System.IO.File.OpenRead(fileToCompress))
|
|
{
|
|
using (var raw = System.IO.File.Create(fileToCompress + ".zlib"))
|
|
{
|
|
using (Stream compressor = new ZlibStream(raw,
|
|
CompressionMode.Compress,
|
|
CompressionLevel.BestCompression))
|
|
{
|
|
byte[] buffer = new byte[WORKING_BUFFER_SIZE];
|
|
int n;
|
|
while ((n= input.Read(buffer, 0, buffer.Length)) != 0)
|
|
{
|
|
compressor.Write(buffer, 0, n);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
</code>
|
|
|
|
<code lang="VB">
|
|
Using input As Stream = File.OpenRead(fileToCompress)
|
|
Using raw As FileStream = File.Create(fileToCompress & ".zlib")
|
|
Using compressor As Stream = New ZlibStream(raw, CompressionMode.Compress, CompressionLevel.BestCompression)
|
|
Dim buffer As Byte() = New Byte(4096) {}
|
|
Dim n As Integer = -1
|
|
Do While (n <> 0)
|
|
If (n > 0) Then
|
|
compressor.Write(buffer, 0, n)
|
|
End If
|
|
n = input.Read(buffer, 0, buffer.Length)
|
|
Loop
|
|
End Using
|
|
End Using
|
|
End Using
|
|
</code>
|
|
</example>
|
|
|
|
<param name="stream">The stream to be read or written while deflating or inflating.</param>
|
|
<param name="mode">Indicates whether the ZlibStream will compress or decompress.</param>
|
|
<param name="level">A tuning knob to trade speed for effectiveness.</param>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ZlibStream.#ctor(System.IO.Stream,Ionic.Zlib.CompressionMode,System.Boolean)">
|
|
<summary>
|
|
Create a <c>ZlibStream</c> using the specified <c>CompressionMode</c>, and
|
|
explicitly specify whether the captive stream should be left open after
|
|
Deflation or Inflation.
|
|
</summary>
|
|
|
|
<remarks>
|
|
|
|
<para>
|
|
When mode is <c>CompressionMode.Compress</c>, the <c>ZlibStream</c> will use
|
|
the default compression level.
|
|
</para>
|
|
|
|
<para>
|
|
This constructor allows the application to request that the captive stream
|
|
remain open after the deflation or inflation occurs. By default, after
|
|
<c>Close()</c> is called on the stream, the captive stream is also
|
|
closed. In some cases this is not desired, for example if the stream is a
|
|
<see cref="T:System.IO.MemoryStream"/> that will be re-read after
|
|
compression. Specify true for the <paramref name="leaveOpen"/> parameter to leave the stream
|
|
open.
|
|
</para>
|
|
|
|
<para>
|
|
See the other overloads of this constructor for example code.
|
|
</para>
|
|
|
|
</remarks>
|
|
|
|
<param name="stream">The stream which will be read or written. This is called the
|
|
"captive" stream in other places in this documentation.</param>
|
|
<param name="mode">Indicates whether the ZlibStream will compress or decompress.</param>
|
|
<param name="leaveOpen">true if the application would like the stream to remain
|
|
open after inflation/deflation.</param>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ZlibStream.#ctor(System.IO.Stream,Ionic.Zlib.CompressionMode,Ionic.Zlib.CompressionLevel,System.Boolean)">
|
|
<summary>
|
|
Create a <c>ZlibStream</c> using the specified <c>CompressionMode</c>
|
|
and the specified <c>CompressionLevel</c>, and explicitly specify
|
|
whether the stream should be left open after Deflation or Inflation.
|
|
</summary>
|
|
|
|
<remarks>
|
|
|
|
<para>
|
|
This constructor allows the application to request that the captive
|
|
stream remain open after the deflation or inflation occurs. By
|
|
default, after <c>Close()</c> is called on the stream, the captive
|
|
stream is also closed. In some cases this is not desired, for example
|
|
if the stream is a <see cref="T:System.IO.MemoryStream"/> that will be
|
|
re-read after compression. Specify true for the <paramref name="leaveOpen"/> parameter to leave the stream open.
|
|
</para>
|
|
|
|
<para>
|
|
When mode is <c>CompressionMode.Decompress</c>, the level parameter is
|
|
ignored.
|
|
</para>
|
|
|
|
</remarks>
|
|
|
|
<example>
|
|
|
|
This example shows how to use a ZlibStream to compress the data from a file,
|
|
and store the result into another file. The filestream remains open to allow
|
|
additional data to be written to it.
|
|
|
|
<code>
|
|
using (var output = System.IO.File.Create(fileToCompress + ".zlib"))
|
|
{
|
|
using (System.IO.Stream input = System.IO.File.OpenRead(fileToCompress))
|
|
{
|
|
using (Stream compressor = new ZlibStream(output, CompressionMode.Compress, CompressionLevel.BestCompression, true))
|
|
{
|
|
byte[] buffer = new byte[WORKING_BUFFER_SIZE];
|
|
int n;
|
|
while ((n= input.Read(buffer, 0, buffer.Length)) != 0)
|
|
{
|
|
compressor.Write(buffer, 0, n);
|
|
}
|
|
}
|
|
}
|
|
// can write additional data to the output stream here
|
|
}
|
|
</code>
|
|
<code lang="VB">
|
|
Using output As FileStream = File.Create(fileToCompress & ".zlib")
|
|
Using input As Stream = File.OpenRead(fileToCompress)
|
|
Using compressor As Stream = New ZlibStream(output, CompressionMode.Compress, CompressionLevel.BestCompression, True)
|
|
Dim buffer As Byte() = New Byte(4096) {}
|
|
Dim n As Integer = -1
|
|
Do While (n <> 0)
|
|
If (n > 0) Then
|
|
compressor.Write(buffer, 0, n)
|
|
End If
|
|
n = input.Read(buffer, 0, buffer.Length)
|
|
Loop
|
|
End Using
|
|
End Using
|
|
' can write additional data to the output stream here.
|
|
End Using
|
|
</code>
|
|
</example>
|
|
|
|
<param name="stream">The stream which will be read or written.</param>
|
|
|
|
<param name="mode">Indicates whether the ZlibStream will compress or decompress.</param>
|
|
|
|
<param name="leaveOpen">
|
|
true if the application would like the stream to remain open after
|
|
inflation/deflation.
|
|
</param>
|
|
|
|
<param name="level">
|
|
A tuning knob to trade speed for effectiveness. This parameter is
|
|
effective only when mode is <c>CompressionMode.Compress</c>.
|
|
</param>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ZlibStream.Dispose(System.Boolean)">
|
|
<summary>
|
|
Dispose the stream.
|
|
</summary>
|
|
<remarks>
|
|
<para>
|
|
This may or may not result in a <c>Close()</c> call on the captive
|
|
stream. See the constructors that have a <c>leaveOpen</c> parameter
|
|
for more information.
|
|
</para>
|
|
<para>
|
|
This method may be invoked in two distinct scenarios. If disposing
|
|
== true, the method has been called directly or indirectly by a
|
|
user's code, for example via the public Dispose() method. In this
|
|
case, both managed and unmanaged resources can be referenced and
|
|
disposed. If disposing == false, the method has been called by the
|
|
runtime from inside the object finalizer and this method should not
|
|
reference other objects; in that case only unmanaged resources must
|
|
be referenced or disposed.
|
|
</para>
|
|
</remarks>
|
|
<param name="disposing">
|
|
indicates whether the Dispose method was invoked by user code.
|
|
</param>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ZlibStream.Flush">
|
|
<summary>
|
|
Flush the stream.
|
|
</summary>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ZlibStream.Read(System.Byte[],System.Int32,System.Int32)">
|
|
<summary>
|
|
Read data from the stream.
|
|
</summary>
|
|
|
|
<remarks>
|
|
|
|
<para>
|
|
If you wish to use the <c>ZlibStream</c> to compress data while reading,
|
|
you can create a <c>ZlibStream</c> with <c>CompressionMode.Compress</c>,
|
|
providing an uncompressed data stream. Then call <c>Read()</c> on that
|
|
<c>ZlibStream</c>, and the data read will be compressed. If you wish to
|
|
use the <c>ZlibStream</c> to decompress data while reading, you can create
|
|
a <c>ZlibStream</c> with <c>CompressionMode.Decompress</c>, providing a
|
|
readable compressed data stream. Then call <c>Read()</c> on that
|
|
<c>ZlibStream</c>, and the data will be decompressed as it is read.
|
|
</para>
|
|
|
|
<para>
|
|
A <c>ZlibStream</c> can be used for <c>Read()</c> or <c>Write()</c>, but
|
|
not both.
|
|
</para>
|
|
|
|
</remarks>
|
|
|
|
<param name="buffer">
|
|
The buffer into which the read data should be placed.</param>
|
|
|
|
<param name="offset">
|
|
the offset within that data array to put the first byte read.</param>
|
|
|
|
<param name="count">the number of bytes to read.</param>
|
|
|
|
<returns>the number of bytes read</returns>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ZlibStream.Seek(System.Int64,System.IO.SeekOrigin)">
|
|
<summary>
|
|
Calling this method always throws a <see cref="T:System.NotSupportedException"/>.
|
|
</summary>
|
|
<param name="offset">
|
|
The offset to seek to....
|
|
IF THIS METHOD ACTUALLY DID ANYTHING.
|
|
</param>
|
|
<param name="origin">
|
|
The reference specifying how to apply the offset.... IF
|
|
THIS METHOD ACTUALLY DID ANYTHING.
|
|
</param>
|
|
|
|
<returns>nothing. This method always throws.</returns>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ZlibStream.SetLength(System.Int64)">
|
|
<summary>
|
|
Calling this method always throws a <see cref="T:System.NotSupportedException"/>.
|
|
</summary>
|
|
<param name="value">
|
|
The new value for the stream length.... IF
|
|
THIS METHOD ACTUALLY DID ANYTHING.
|
|
</param>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ZlibStream.Write(System.Byte[],System.Int32,System.Int32)">
|
|
<summary>
|
|
Write data to the stream.
|
|
</summary>
|
|
|
|
<remarks>
|
|
|
|
<para>
|
|
If you wish to use the <c>ZlibStream</c> to compress data while writing,
|
|
you can create a <c>ZlibStream</c> with <c>CompressionMode.Compress</c>,
|
|
and a writable output stream. Then call <c>Write()</c> on that
|
|
<c>ZlibStream</c>, providing uncompressed data as input. The data sent to
|
|
the output stream will be the compressed form of the data written. If you
|
|
wish to use the <c>ZlibStream</c> to decompress data while writing, you
|
|
can create a <c>ZlibStream</c> with <c>CompressionMode.Decompress</c>, and a
|
|
writable output stream. Then call <c>Write()</c> on that stream,
|
|
providing previously compressed data. The data sent to the output stream
|
|
will be the decompressed form of the data written.
|
|
</para>
|
|
|
|
<para>
|
|
A <c>ZlibStream</c> can be used for <c>Read()</c> or <c>Write()</c>, but not both.
|
|
</para>
|
|
</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.Zlib.ZlibStream.CompressString(System.String)">
|
|
<summary>
|
|
Compress a string into a byte array using ZLIB.
|
|
</summary>
|
|
|
|
<remarks>
|
|
Uncompress it with <see cref="M:Ionic.Zlib.ZlibStream.UncompressString(System.Byte[])"/>.
|
|
</remarks>
|
|
|
|
<seealso cref="M:Ionic.Zlib.ZlibStream.UncompressString(System.Byte[])"/>
|
|
<seealso cref="M:Ionic.Zlib.ZlibStream.CompressBuffer(System.Byte[])"/>
|
|
<seealso cref="M:Ionic.Zlib.GZipStream.CompressString(System.String)"/>
|
|
|
|
<param name="s">
|
|
A string to compress. The string will first be encoded
|
|
using UTF8, then compressed.
|
|
</param>
|
|
|
|
<returns>The string in compressed form</returns>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ZlibStream.CompressBuffer(System.Byte[])">
|
|
<summary>
|
|
Compress a byte array into a new byte array using ZLIB.
|
|
</summary>
|
|
|
|
<remarks>
|
|
Uncompress it with <see cref="M:Ionic.Zlib.ZlibStream.UncompressBuffer(System.Byte[])"/>.
|
|
</remarks>
|
|
|
|
<seealso cref="M:Ionic.Zlib.ZlibStream.CompressString(System.String)"/>
|
|
<seealso cref="M:Ionic.Zlib.ZlibStream.UncompressBuffer(System.Byte[])"/>
|
|
|
|
<param name="b">
|
|
A buffer to compress.
|
|
</param>
|
|
|
|
<returns>The data in compressed form</returns>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ZlibStream.UncompressString(System.Byte[])">
|
|
<summary>
|
|
Uncompress a ZLIB-compressed byte array into a single string.
|
|
</summary>
|
|
|
|
<seealso cref="M:Ionic.Zlib.ZlibStream.CompressString(System.String)"/>
|
|
<seealso cref="M:Ionic.Zlib.ZlibStream.UncompressBuffer(System.Byte[])"/>
|
|
|
|
<param name="compressed">
|
|
A buffer containing ZLIB-compressed data.
|
|
</param>
|
|
|
|
<returns>The uncompressed string</returns>
|
|
</member>
|
|
<member name="M:Ionic.Zlib.ZlibStream.UncompressBuffer(System.Byte[])">
|
|
<summary>
|
|
Uncompress a ZLIB-compressed byte array into a byte array.
|
|
</summary>
|
|
|
|
<seealso cref="M:Ionic.Zlib.ZlibStream.CompressBuffer(System.Byte[])"/>
|
|
<seealso cref="M:Ionic.Zlib.ZlibStream.UncompressString(System.Byte[])"/>
|
|
|
|
<param name="compressed">
|
|
A buffer containing ZLIB-compressed data.
|
|
</param>
|
|
|
|
<returns>The data in uncompressed form</returns>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.ZlibStream.FlushMode">
|
|
<summary>
|
|
This property sets the flush behavior on the stream.
|
|
Sorry, though, not sure exactly how to describe all the various settings.
|
|
</summary>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.ZlibStream.BufferSize">
|
|
<summary>
|
|
The size of the working buffer for the compression codec.
|
|
</summary>
|
|
|
|
<remarks>
|
|
<para>
|
|
The working buffer is used for all stream operations. The default size is
|
|
1024 bytes. The minimum size is 128 bytes. You may get better performance
|
|
with a larger buffer. Then again, you might not. You would have to test
|
|
it.
|
|
</para>
|
|
|
|
<para>
|
|
Set this before the first call to <c>Read()</c> or <c>Write()</c> on the
|
|
stream. If you try to set it afterwards, it will throw.
|
|
</para>
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.ZlibStream.TotalIn">
|
|
<summary> Returns the total number of bytes input so far.</summary>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.ZlibStream.TotalOut">
|
|
<summary> Returns the total number of bytes output so far.</summary>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.ZlibStream.CanRead">
|
|
<summary>
|
|
Indicates whether the stream can be read.
|
|
</summary>
|
|
<remarks>
|
|
The return value depends on whether the captive stream supports reading.
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.ZlibStream.CanSeek">
|
|
<summary>
|
|
Indicates whether the stream supports Seek operations.
|
|
</summary>
|
|
<remarks>
|
|
Always returns false.
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.ZlibStream.CanWrite">
|
|
<summary>
|
|
Indicates whether the stream can be written.
|
|
</summary>
|
|
<remarks>
|
|
The return value depends on whether the captive stream supports writing.
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.ZlibStream.Length">
|
|
<summary>
|
|
Reading this property always throws a <see cref="T:System.NotSupportedException"/>.
|
|
</summary>
|
|
</member>
|
|
<member name="P:Ionic.Zlib.ZlibStream.Position">
|
|
<summary>
|
|
The position of the stream pointer.
|
|
</summary>
|
|
|
|
<remarks>
|
|
Setting this property always throws a <see cref="T:System.NotSupportedException"/>. Reading will return the total bytes
|
|
written out, if used in writing, or the total bytes read in, if used in
|
|
reading. The count may refer to compressed bytes or uncompressed bytes,
|
|
depending on how you've used the stream.
|
|
</remarks>
|
|
</member>
|
|
<member name="T:Ionic.Crc.CRC32">
|
|
<summary>
|
|
Computes a CRC-32. The CRC-32 algorithm is parameterized - you
|
|
can set the polynomial and enable or disable bit
|
|
reversal. This can be used for GZIP, BZip2, or ZIP.
|
|
</summary>
|
|
<remarks>
|
|
This type is used internally by DotNetZip; it is generally not used
|
|
directly by applications wishing to create, read, or manipulate zip
|
|
archive files.
|
|
</remarks>
|
|
</member>
|
|
<member name="M:Ionic.Crc.CRC32.GetCrc32(System.IO.Stream)">
|
|
<summary>
|
|
Returns the CRC32 for the specified stream.
|
|
</summary>
|
|
<param name="input">The stream over which to calculate the CRC32</param>
|
|
<returns>the CRC32 calculation</returns>
|
|
</member>
|
|
<member name="M:Ionic.Crc.CRC32.GetCrc32AndCopy(System.IO.Stream,System.IO.Stream)">
|
|
<summary>
|
|
Returns the CRC32 for the specified stream, and writes the input into the
|
|
output stream.
|
|
</summary>
|
|
<param name="input">The stream over which to calculate the CRC32</param>
|
|
<param name="output">The stream into which to deflate the input</param>
|
|
<returns>the CRC32 calculation</returns>
|
|
</member>
|
|
<member name="M:Ionic.Crc.CRC32.ComputeCrc32(System.Int32,System.Byte)">
|
|
<summary>
|
|
Get the CRC32 for the given (word,byte) combo. This is a
|
|
computation defined by PKzip for PKZIP 2.0 (weak) encryption.
|
|
</summary>
|
|
<param name="W">The word to start with.</param>
|
|
<param name="B">The byte to combine it with.</param>
|
|
<returns>The CRC-ized result.</returns>
|
|
</member>
|
|
<member name="M:Ionic.Crc.CRC32.SlurpBlock(System.Byte[],System.Int32,System.Int32)">
|
|
<summary>
|
|
Update the value for the running CRC32 using the given block of bytes.
|
|
This is useful when using the CRC32() class in a Stream.
|
|
</summary>
|
|
<param name="block">block of bytes to slurp</param>
|
|
<param name="offset">starting point in the block</param>
|
|
<param name="count">how many bytes within the block to slurp</param>
|
|
</member>
|
|
<member name="M:Ionic.Crc.CRC32.UpdateCRC(System.Byte)">
|
|
<summary>
|
|
Process one byte in the CRC.
|
|
</summary>
|
|
<param name = "b">the byte to include into the CRC . </param>
|
|
</member>
|
|
<member name="M:Ionic.Crc.CRC32.UpdateCRC(System.Byte,System.Int32)">
|
|
<summary>
|
|
Process a run of N identical bytes into the CRC.
|
|
</summary>
|
|
<remarks>
|
|
<para>
|
|
This method serves as an optimization for updating the CRC when a
|
|
run of identical bytes is found. Rather than passing in a buffer of
|
|
length n, containing all identical bytes b, this method accepts the
|
|
byte value and the length of the (virtual) buffer - the length of
|
|
the run.
|
|
</para>
|
|
</remarks>
|
|
<param name = "b">the byte to include into the CRC. </param>
|
|
<param name = "n">the number of times that byte should be repeated. </param>
|
|
</member>
|
|
<member name="M:Ionic.Crc.CRC32.Combine(System.Int32,System.Int32)">
|
|
<summary>
|
|
Combines the given CRC32 value with the current running total.
|
|
</summary>
|
|
<remarks>
|
|
This is useful when using a divide-and-conquer approach to
|
|
calculating a CRC. Multiple threads can each calculate a
|
|
CRC32 on a segment of the data, and then combine the
|
|
individual CRC32 values at the end.
|
|
</remarks>
|
|
<param name="crc">the crc value to be combined with this one</param>
|
|
<param name="length">the length of data the CRC value was calculated on</param>
|
|
</member>
|
|
<member name="M:Ionic.Crc.CRC32.#ctor">
|
|
<summary>
|
|
Create an instance of the CRC32 class using the default settings: no
|
|
bit reversal, and a polynomial of 0xEDB88320.
|
|
</summary>
|
|
</member>
|
|
<member name="M:Ionic.Crc.CRC32.#ctor(System.Boolean)">
|
|
<summary>
|
|
Create an instance of the CRC32 class, specifying whether to reverse
|
|
data bits or not.
|
|
</summary>
|
|
<param name='reverseBits'>
|
|
specify true if the instance should reverse data bits.
|
|
</param>
|
|
<remarks>
|
|
<para>
|
|
In the CRC-32 used by BZip2, the bits are reversed. Therefore if you
|
|
want a CRC32 with compatibility with BZip2, you should pass true
|
|
here. In the CRC-32 used by GZIP and PKZIP, the bits are not
|
|
reversed; Therefore if you want a CRC32 with compatibility with
|
|
those, you should pass false.
|
|
</para>
|
|
</remarks>
|
|
</member>
|
|
<member name="M:Ionic.Crc.CRC32.#ctor(System.Int32,System.Boolean)">
|
|
<summary>
|
|
Create an instance of the CRC32 class, specifying the polynomial and
|
|
whether to reverse data bits or not.
|
|
</summary>
|
|
<param name='polynomial'>
|
|
The polynomial to use for the CRC, expressed in the reversed (LSB)
|
|
format: the highest ordered bit in the polynomial value is the
|
|
coefficient of the 0th power; the second-highest order bit is the
|
|
coefficient of the 1 power, and so on. Expressed this way, the
|
|
polynomial for the CRC-32C used in IEEE 802.3, is 0xEDB88320.
|
|
</param>
|
|
<param name='reverseBits'>
|
|
specify true if the instance should reverse data bits.
|
|
</param>
|
|
|
|
<remarks>
|
|
<para>
|
|
In the CRC-32 used by BZip2, the bits are reversed. Therefore if you
|
|
want a CRC32 with compatibility with BZip2, you should pass true
|
|
here for the <c>reverseBits</c> parameter. In the CRC-32 used by
|
|
GZIP and PKZIP, the bits are not reversed; Therefore if you want a
|
|
CRC32 with compatibility with those, you should pass false for the
|
|
<c>reverseBits</c> parameter.
|
|
</para>
|
|
</remarks>
|
|
</member>
|
|
<member name="M:Ionic.Crc.CRC32.Reset">
|
|
<summary>
|
|
Reset the CRC-32 class - clear the CRC "remainder register."
|
|
</summary>
|
|
<remarks>
|
|
<para>
|
|
Use this when employing a single instance of this class to compute
|
|
multiple, distinct CRCs on multiple, distinct data blocks.
|
|
</para>
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.Crc.CRC32.TotalBytesRead">
|
|
<summary>
|
|
Indicates the total number of bytes applied to the CRC.
|
|
</summary>
|
|
</member>
|
|
<member name="P:Ionic.Crc.CRC32.Crc32Result">
|
|
<summary>
|
|
Indicates the current CRC for all blocks slurped in.
|
|
</summary>
|
|
</member>
|
|
<member name="T:Ionic.Crc.CrcCalculatorStream">
|
|
<summary>
|
|
A Stream that calculates a CRC32 (a checksum) on all bytes read,
|
|
or on all bytes written.
|
|
</summary>
|
|
|
|
<remarks>
|
|
<para>
|
|
This class can be used to verify the CRC of a ZipEntry when
|
|
reading from a stream, or to calculate a CRC when writing to a
|
|
stream. The stream should be used to either read, or write, but
|
|
not both. If you intermix reads and writes, the results are not
|
|
defined.
|
|
</para>
|
|
|
|
<para>
|
|
This class is intended primarily for use internally by the
|
|
DotNetZip library.
|
|
</para>
|
|
</remarks>
|
|
</member>
|
|
<member name="M:Ionic.Crc.CrcCalculatorStream.#ctor(System.IO.Stream)">
|
|
<summary>
|
|
The default constructor.
|
|
</summary>
|
|
<remarks>
|
|
<para>
|
|
Instances returned from this constructor will leave the underlying
|
|
stream open upon Close(). The stream uses the default CRC32
|
|
algorithm, which implies a polynomial of 0xEDB88320.
|
|
</para>
|
|
</remarks>
|
|
<param name="stream">The underlying stream</param>
|
|
</member>
|
|
<member name="M:Ionic.Crc.CrcCalculatorStream.#ctor(System.IO.Stream,System.Boolean)">
|
|
<summary>
|
|
The constructor allows the caller to specify how to handle the
|
|
underlying stream at close.
|
|
</summary>
|
|
<remarks>
|
|
<para>
|
|
The stream uses the default CRC32 algorithm, which implies a
|
|
polynomial of 0xEDB88320.
|
|
</para>
|
|
</remarks>
|
|
<param name="stream">The underlying stream</param>
|
|
<param name="leaveOpen">true to leave the underlying stream
|
|
open upon close of the <c>CrcCalculatorStream</c>; false otherwise.</param>
|
|
</member>
|
|
<member name="M:Ionic.Crc.CrcCalculatorStream.#ctor(System.IO.Stream,System.Int64)">
|
|
<summary>
|
|
A constructor allowing the specification of the length of the stream
|
|
to read.
|
|
</summary>
|
|
<remarks>
|
|
<para>
|
|
The stream uses the default CRC32 algorithm, which implies a
|
|
polynomial of 0xEDB88320.
|
|
</para>
|
|
<para>
|
|
Instances returned from this constructor will leave the underlying
|
|
stream open upon Close().
|
|
</para>
|
|
</remarks>
|
|
<param name="stream">The underlying stream</param>
|
|
<param name="length">The length of the stream to slurp</param>
|
|
</member>
|
|
<member name="M:Ionic.Crc.CrcCalculatorStream.#ctor(System.IO.Stream,System.Int64,System.Boolean)">
|
|
<summary>
|
|
A constructor allowing the specification of the length of the stream
|
|
to read, as well as whether to keep the underlying stream open upon
|
|
Close().
|
|
</summary>
|
|
<remarks>
|
|
<para>
|
|
The stream uses the default CRC32 algorithm, which implies a
|
|
polynomial of 0xEDB88320.
|
|
</para>
|
|
</remarks>
|
|
<param name="stream">The underlying stream</param>
|
|
<param name="length">The length of the stream to slurp</param>
|
|
<param name="leaveOpen">true to leave the underlying stream
|
|
open upon close of the <c>CrcCalculatorStream</c>; false otherwise.</param>
|
|
</member>
|
|
<member name="M:Ionic.Crc.CrcCalculatorStream.#ctor(System.IO.Stream,System.Int64,System.Boolean,Ionic.Crc.CRC32)">
|
|
<summary>
|
|
A constructor allowing the specification of the length of the stream
|
|
to read, as well as whether to keep the underlying stream open upon
|
|
Close(), and the CRC32 instance to use.
|
|
</summary>
|
|
<remarks>
|
|
<para>
|
|
The stream uses the specified CRC32 instance, which allows the
|
|
application to specify how the CRC gets calculated.
|
|
</para>
|
|
</remarks>
|
|
<param name="stream">The underlying stream</param>
|
|
<param name="length">The length of the stream to slurp</param>
|
|
<param name="leaveOpen">true to leave the underlying stream
|
|
open upon close of the <c>CrcCalculatorStream</c>; false otherwise.</param>
|
|
<param name="crc32">the CRC32 instance to use to calculate the CRC32</param>
|
|
</member>
|
|
<member name="M:Ionic.Crc.CrcCalculatorStream.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.Crc.CrcCalculatorStream.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="M:Ionic.Crc.CrcCalculatorStream.Flush">
|
|
<summary>
|
|
Flush the stream.
|
|
</summary>
|
|
</member>
|
|
<member name="M:Ionic.Crc.CrcCalculatorStream.Seek(System.Int64,System.IO.SeekOrigin)">
|
|
<summary>
|
|
Seeking is not supported on this stream. This method always throws
|
|
<see cref="T:System.NotSupportedException"/>
|
|
</summary>
|
|
<param name="offset">N/A</param>
|
|
<param name="origin">N/A</param>
|
|
<returns>N/A</returns>
|
|
</member>
|
|
<member name="M:Ionic.Crc.CrcCalculatorStream.SetLength(System.Int64)">
|
|
<summary>
|
|
This method always throws
|
|
<see cref="T:System.NotSupportedException"/>
|
|
</summary>
|
|
<param name="value">N/A</param>
|
|
</member>
|
|
<member name="M:Ionic.Crc.CrcCalculatorStream.Close">
|
|
<summary>
|
|
Closes the stream.
|
|
</summary>
|
|
</member>
|
|
<member name="P:Ionic.Crc.CrcCalculatorStream.TotalBytesSlurped">
|
|
<summary>
|
|
Gets the total number of bytes run through the CRC32 calculator.
|
|
</summary>
|
|
|
|
<remarks>
|
|
This is either the total number of bytes read, or the total number of
|
|
bytes written, depending on the direction of this stream.
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.Crc.CrcCalculatorStream.Crc">
|
|
<summary>
|
|
Provides the current CRC for all blocks slurped in.
|
|
</summary>
|
|
<remarks>
|
|
<para>
|
|
The running total of the CRC is kept as data is written or read
|
|
through the stream. read this property after all reads or writes to
|
|
get an accurate CRC for the entire stream.
|
|
</para>
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.Crc.CrcCalculatorStream.LeaveOpen">
|
|
<summary>
|
|
Indicates whether the underlying stream will be left open when the
|
|
<c>CrcCalculatorStream</c> is Closed.
|
|
</summary>
|
|
<remarks>
|
|
<para>
|
|
Set this at any point before calling <see cref="M:Ionic.Crc.CrcCalculatorStream.Close"/>.
|
|
</para>
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.Crc.CrcCalculatorStream.CanRead">
|
|
<summary>
|
|
Indicates whether the stream supports reading.
|
|
</summary>
|
|
</member>
|
|
<member name="P:Ionic.Crc.CrcCalculatorStream.CanSeek">
|
|
<summary>
|
|
Indicates whether the stream supports seeking.
|
|
</summary>
|
|
<remarks>
|
|
<para>
|
|
Always returns false.
|
|
</para>
|
|
</remarks>
|
|
</member>
|
|
<member name="P:Ionic.Crc.CrcCalculatorStream.CanWrite">
|
|
<summary>
|
|
Indicates whether the stream supports writing.
|
|
</summary>
|
|
</member>
|
|
<member name="P:Ionic.Crc.CrcCalculatorStream.Length">
|
|
<summary>
|
|
Returns the length of the underlying stream.
|
|
</summary>
|
|
</member>
|
|
<member name="P:Ionic.Crc.CrcCalculatorStream.Position">
|
|
<summary>
|
|
The getter for this property returns the total bytes read.
|
|
If you use the setter, it will throw
|
|
<see cref="T:System.NotSupportedException"/>.
|
|
</summary>
|
|
</member>
|
|
</members>
|
|
</doc>
|