// ZipOutputStream.cs

//

// ------------------------------------------------------------------

//

// Copyright (c) 2009 Dino Chiesa.

// All rights reserved.

//

// This code module is part of DotNetZip, a zipfile class library.

//

// ------------------------------------------------------------------

//

// This code is licensed under the Microsoft Public License.

// See the file License.txt for the license details.

// More info on: http://dotnetzip.codeplex.com

//

// ------------------------------------------------------------------

//

// last saved (in emacs):

// Time-stamp: <2011-July-28 06:34:30>

//

// ------------------------------------------------------------------

//

// This module defines the ZipOutputStream class, which is a stream metaphor for

// generating zip files. This class does not depend on Ionic.Zip.ZipFile, but rather

// stands alongside it as an alternative "container" for ZipEntry. It replicates a

// subset of the properties, including these:

//

// - Comment

// - Encryption

// - Password

// - CodecBufferSize

// - CompressionLevel

// - CompressionMethod

// - EnableZip64 (UseZip64WhenSaving)

// - IgnoreCase (!CaseSensitiveRetrieval)

//

// It adds these novel methods:

//

// - PutNextEntry

//

//

// ------------------------------------------------------------------

//

using System;

using System.Threading;

using System.Collections.Generic;

using System.IO;

using Ionic.Zip;

namespace Ionic.Zip

{

/// <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="ZipFile"/> class. Use this when creating zip files, as an

/// alternative to the <see cref="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="ZipFile.AddFile(string,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="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="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="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>

public class ZipOutputStream : Stream

{

/// <summary>

/// Create a ZipOutputStream, wrapping an existing stream.

/// </summary>

///

/// <remarks>

/// <para>

/// The <see cref="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="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>

public ZipOutputStream(Stream stream) : this(stream, false) { }

/// <summary>

/// Create a ZipOutputStream that writes to a filesystem file.

/// </summary>

///

/// <remarks>

/// The <see cref="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="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>

public ZipOutputStream(String fileName)

{

Stream stream = File.Open(fileName, FileMode.Create, FileAccess.ReadWrite, FileShare.None);

_Init(stream, false, fileName);

}

/// <summary>

/// Create a ZipOutputStream.

/// </summary>

///

/// <remarks>

/// See the documentation for the <see

/// cref="ZipOutputStream(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>

public ZipOutputStream(Stream stream, bool leaveOpen)

{

_Init(stream, leaveOpen, null);

}

private void _Init(Stream stream, bool leaveOpen, string name)

{

// workitem 9307

_outputStream = stream.CanRead ? stream : new CountingStream(stream);

CompressionLevel = Ionic.Zlib.CompressionLevel.Default;

CompressionMethod = Ionic.Zip.CompressionMethod.Deflate;

_encryption = EncryptionAlgorithm.None;

_entriesWritten = new Dictionary<String, ZipEntry>(StringComparer.Ordinal);

_zip64 = Zip64Option.Never;

_leaveUnderlyingStreamOpen = leaveOpen;

Strategy = Ionic.Zlib.CompressionStrategy.Default;

_name = name ?? "(stream)";

#if !NETCF

ParallelDeflateThreshold = -1L;

#endif

}

/// <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>

public override String ToString()

{

return String.Format ("ZipOutputStream::{0}(leaveOpen({1})))", _name, _leaveUnderlyingStreamOpen);

}

/// <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="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="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>

public String Password

{

set

{

if (_disposed)

{

_exceptionPending = true;

throw new System.InvalidOperationException("The stream has been closed.");

}

_password = value;

if (_password == null)

{

_encryption = EncryptionAlgorithm.None;

}

else if (_encryption == EncryptionAlgorithm.None)

{

_encryption = EncryptionAlgorithm.PkzipWeak;

}

}

}

/// <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="Password"/> to a non-null, non-empty value in

/// order to actually get encryption on the entry.

/// </para>

///

/// </remarks>

///

/// <seealso cref="Password">ZipOutputStream.Password</seealso>

/// <seealso cref="Ionic.Zip.ZipEntry.Encryption">ZipEntry.Encryption</seealso>

public EncryptionAlgorithm Encryption

{

get

{

return _encryption;

}

set

{

if (_disposed)

{

_exceptionPending = true;

throw new System.InvalidOperationException("The stream has been closed.");

}

if (value == EncryptionAlgorithm.Unsupported)

{

_exceptionPending = true;

throw new InvalidOperationException("You may not set Encryption to that value.");

}

_encryption = value;

}

}

/// <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>

public int CodecBufferSize

{

get;

set;

}

/// <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="Ionic.Zlib.CompressionStrategy "/>.

/// </remarks>

public Ionic.Zlib.CompressionStrategy Strategy

{

get;

set;

}

/// <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>

public ZipEntryTimestamp Timestamp

{

get

{

return _timestamp;

}

set

{

if (_disposed)

{

_exceptionPending = true;

throw new System.InvalidOperationException("The stream has been closed.");

}

_timestamp = value;

}

}

/// <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="Password"/>, and <see cref="Encryption"/>,

/// setting this property on a <c>ZipOutputStream</c>

/// instance will cause the specified <c>CompressionLevel</c> to be used on all

/// <see cref="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>

public Ionic.Zlib.CompressionLevel CompressionLevel

{

get;

set;

}

/// <summary>

/// The compression method used on each entry added to the ZipOutputStream.

/// </summary>

public Ionic.Zip.CompressionMethod CompressionMethod

{

get;

set;

}

/// <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="AlternateEncodingUsage"/> is

/// <c>Never</c>, it uses the default encoding (IBM437). (b) if <see

/// cref="AlternateEncodingUsage"/> is <c>Always</c>, it always uses the

/// alternate encoding (<see cref="AlternateEncoding"/>). (c) if <see

/// cref="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>

public string Comment

{

get { return _comment; }

set

{

if (_disposed)

{

_exceptionPending = true;

throw new System.InvalidOperationException("The stream has been closed.");

}

_comment = value;

}

}

/// <summary>

/// Specify whether to use ZIP64 extensions when saving a zip archive.

/// </summary>

///

/// <remarks>

/// <para>

/// The default value for the property is <see

/// cref="Zip64Option.Never"/>. <see cref="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>

public Zip64Option EnableZip64

{

get

{

return _zip64;

}

set

{

if (_disposed)

{

_exceptionPending = true;

throw new System.InvalidOperationException("The stream has been closed.");

}

_zip64 = value;

}

}

/// <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>

public bool OutputUsedZip64

{

get

{

return _anyEntriesUsedZip64 || _directoryNeededZip64;

}

}

/// <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="PutNextEntry(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>

public bool IgnoreCase

{

get

{

return !_DontIgnoreCase;

}

set

{

_DontIgnoreCase = !value;

}

}

/// <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="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="ProvisionalAlternateEncoding"/>

[Obsolete("Beginning with v1.9.1.6 of DotNetZip, this property is obsolete. It will be removed in a future version of the library. Use AlternateEncoding and AlternateEncodingUsage instead.")]

public bool UseUnicodeAsNecessary

{

get

{

return (_alternateEncoding == System.Text.Encoding.UTF8) &&

(AlternateEncodingUsage == ZipOption.AsNecessary);

}

set

{

if (value)

{

_alternateEncoding = System.Text.Encoding.UTF8;

_alternateEncodingUsage = ZipOption.AsNecessary;

}

else

{

_alternateEncoding = Ionic.Zip.ZipOutputStream.DefaultEncoding;

_alternateEncodingUsage = ZipOption.Never;

}

}

}

/// <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="ZipEntry.FileName"/> and <see

/// cref="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="Comment"/> property and reset

/// <c>ProvisionalAlternateEncoding</c> to IBM437 before calling <c>Close()</c>.

/// </para>

/// </remarks>

[Obsolete("use AlternateEncoding and AlternateEncodingUsage instead.")]

public System.Text.Encoding ProvisionalAlternateEncoding

{

get

{

if (_alternateEncodingUsage == ZipOption.AsNecessary)

return _alternateEncoding;

return null;

}

set

{

_alternateEncoding = value;

_alternateEncodingUsage = ZipOption.AsNecessary;

}

}

/// <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="AlternateEncodingUsage"/>.

/// </para>

/// </remarks>

public System.Text.Encoding AlternateEncoding

{

get

{

return _alternateEncoding;

}

set

{

_alternateEncoding = value;

}

}

/// <summary>

/// A flag that tells if and when this instance should apply

/// AlternateEncoding to encode the filenames and comments associated to