diff --git a/AppInfoCli/AppInfo.cs b/AppInfoCli/AppInfo.cs deleted file mode 100644 index d549481..0000000 --- a/AppInfoCli/AppInfo.cs +++ /dev/null @@ -1,345 +0,0 @@ -using System; -using System.Collections.Generic; -using System.Drawing; -using System.IO; -using System.Text; -using System.Xml; - -namespace AppInfo -{ - class Types - { - public static int TYPE_STRING = 3; - public static int TYPE_FLOAT = 2; - public static int TYPE_INT = 1; - public static int TYPE_FILE = 8; - } - - class Tools - { - public static MemoryStream ByteToStream(byte[] Array) - { - MemoryStream ms = new MemoryStream(); - ms.Write(Array, 0x00, Array.Length); - ms.Seek(0, SeekOrigin.Begin); - return ms; - } - - public static bool IsImage(byte[] Bytes) - { - try - { - GetBitmap(Bytes); - } - catch(Exception) - { - return false; - } - return true; - } - - public static Bitmap GetBitmap(byte[] BitmapBytes) - { - MemoryStream ms = ByteToStream(BitmapBytes); - Bitmap bmp = new Bitmap(ms); - ms.Dispose(); - return bmp; - } - - public static String ReadStringAt(Stream ms, int location) - { - long ogPos = ms.Position; - ms.Seek(location, SeekOrigin.Begin); - String str = ReadString(ms); - ms.Seek(ogPos, SeekOrigin.Begin); - return str; - } - - public static int ReadIntAt(Stream ms, int location) - { - BinaryReader BinReader = new BinaryReader(ms); - long ogPos = ms.Position; - ms.Seek(location, SeekOrigin.Begin); - int i = BinReader.ReadInt32(); - ms.Seek(ogPos, SeekOrigin.Begin); - return i; - } - - public static int ReadInt(Stream ms) - { - BinaryReader BinReader = new BinaryReader(ms); - int i = BinReader.ReadInt32(); - return i; - } - - public static String ReadString(Stream ms) - { - int i = 0xFF; - - MemoryStream StringStream = new MemoryStream(); - - do - { - i = ms.ReadByte(); - if (i == 0) - break; - StringStream.WriteByte((byte)i); - } - while (true); - - byte[] StringData = StringStream.ToArray(); - - String str = Encoding.UTF8.GetString(StringData); - - return str; - - } - } - - class Parser - { - - private static bool _checkMagicNumber() - { - String Magic = Tools.ReadStringAt(InfoFile, 0x00); - - if (Magic.StartsWith("PSMA")) - { - return true; - } - else if(Magic.StartsWith("RCOF")) - { - Console.WriteLine("WARNING: .RCO files probably wont work!!\nThis tool was made for PSM's \"app.info\" files."); - return true; - } - else - { - return false; - } - } - - static FileStream InfoFile; - static MemoryStream StringTable; - static MemoryStream TreeTable; - static MemoryStream FileTable; - static BinaryReader BinaryTree; - static XmlWriter XMLFile; - - public static void Init(string Path, bool CheckMagic = true) - { - InfoFile = File.Open(Path, FileMode.Open, FileAccess.Read); - if(CheckMagic) - { - if (!_checkMagicNumber()) - { - throw new Exception("Incorrect magic number."); - } - - } - - StringTable = Tools.ByteToStream(GetStringTable()); - TreeTable = Tools.ByteToStream(GetTreeTable()); - FileTable = Tools.ByteToStream(GetFileTable()); - BinaryTree = new BinaryReader(TreeTable); - - return; - } - - public static void Term() - { - InfoFile.Close(); - StringTable.Close(); - TreeTable.Close(); - FileTable.Close(); - BinaryTree.Dispose(); - } - - public static int GetTableOffset() - { - return Tools.ReadIntAt(InfoFile,0x8); - } - - public static int GetTableSize() - { - return Tools.ReadIntAt(InfoFile, 0xC); - } - - public static int GetFileTableOffset() - { - return Tools.ReadIntAt(InfoFile, 0x48); - } - - public static int GetFileTableSize() - { - return Tools.ReadIntAt(InfoFile, 0x4C); - } - - public static int GetStringTableOffset() - { - return Tools.ReadIntAt(InfoFile, 0x20); - } - - public static int GetStringTableSize() - { - return Tools.ReadIntAt(InfoFile, 0x24); - } - - public static byte[] GetStringTable() - { - int StringTableOffset = GetStringTableOffset(); - int StringTableSize = GetStringTableSize(); - InfoFile.Seek(StringTableOffset, SeekOrigin.Begin); - byte[] StringTable = new byte[StringTableSize]; - InfoFile.Read(StringTable, 0x00, StringTableSize); - return StringTable; - } - - public static byte[] GetTreeTable() - { - int TableOffset = GetTableOffset(); - int TableSize = GetTableSize(); - InfoFile.Seek(TableOffset, SeekOrigin.Begin); - byte[] Table = new byte[TableSize]; - InfoFile.Read(Table, 0x00, TableSize); - return Table; - } - - public static byte[] GetFileTable() - { - int DataOffset = GetFileTableOffset(); - int DataLength = GetFileTableSize(); - InfoFile.Seek(DataOffset, SeekOrigin.Begin); - byte[] FileTable = new byte[DataLength]; - InfoFile.Read(FileTable, 0x00, DataLength); - return FileTable; - } - - public static void DecompileCXML(String CXMLFile, bool force = false) - { - Init(CXMLFile,force); - XmlWriterSettings XMLSettings = new XmlWriterSettings(); - XMLSettings.Indent = true; - - XMLFile = XmlWriter.Create(Path.GetFileNameWithoutExtension(CXMLFile)+".xml", XMLSettings); - XMLFile.WriteStartDocument(); - - ReadElement(); - - XMLFile.WriteEndDocument(); - XMLFile.Flush(); - - Term(); - } - - public static void ReadAttribute() - { - int AttributePtr = BinaryTree.ReadInt32(); - int AttributeType = BinaryTree.ReadInt32(); - - String AttributeName = Tools.ReadStringAt(StringTable, AttributePtr); - object AttributeValue; - Console.WriteLine("AttributeType: " + AttributeType); - - if (AttributeType == Types.TYPE_STRING) - { - int ValuePtr = BinaryTree.ReadInt32(); - AttributeValue = Tools.ReadStringAt(StringTable, ValuePtr); - TreeTable.Seek(4, SeekOrigin.Current); - } - else if(AttributeType == Types.TYPE_FLOAT) - { - AttributeValue = BinaryTree.ReadSingle(); - TreeTable.Seek(4, SeekOrigin.Current); - } - else if(AttributeType == Types.TYPE_INT) - { - AttributeValue = BinaryTree.ReadInt32(); - TreeTable.Seek(4, SeekOrigin.Current); - } - else if(AttributeType == Types.TYPE_FILE) - { - int FilePtr = BinaryTree.ReadInt32(); - int FileSz = BinaryTree.ReadInt32(); - - String FileName = ""; - - Byte[] FileData = new Byte[FileSz]; - FileTable.Seek(FilePtr,SeekOrigin.Begin); - FileTable.Read(FileData, 0, FileSz); - - if (Tools.IsImage(FileData)) - FileName = AttributeName + ".png"; - else - FileName = AttributeName + ".txt"; - - Console.WriteLine("Writing: " + FileName); - File.WriteAllBytes(FileName, FileData); - - AttributeValue = FileName; - } - else - { - Console.WriteLine("ERROR: Unknown Type '"+AttributeType+"' @ " + (TreeTable.Position - 4).ToString()); - Environment.Exit(-1); - return; - } - - Console.WriteLine(AttributeName + "=" + AttributeValue.ToString()); - XMLFile.WriteAttributeString(AttributeName, AttributeValue.ToString()); - XMLFile.Flush(); - } - - public static void ReadElement() - { - - int ElementPtr = BinaryTree.ReadInt32(); - int NumAttributes = BinaryTree.ReadInt32(); - - int ParentPtr = BinaryTree.ReadInt32(); - int PrevSibling = BinaryTree.ReadInt32(); - int NextSibling = BinaryTree.ReadInt32(); - - int FirstChild = BinaryTree.ReadInt32(); - int LastChild = BinaryTree.ReadInt32(); - - String ElementName = Tools.ReadStringAt(StringTable, ElementPtr); - Console.WriteLine("Creating Element: " + ElementName); - Console.WriteLine("Attribute Count: " + NumAttributes); - - Console.WriteLine("ParentPtr: " + ParentPtr); - Console.WriteLine("PrevSibling: " + PrevSibling); - Console.WriteLine("NextSibling: " + NextSibling); - - Console.WriteLine("FirstChild: " + FirstChild); - Console.WriteLine("LastChild: " + LastChild); - - XMLFile.WriteStartElement(ElementName); - - if(NumAttributes > 0) - { - for (int i = 0; i < NumAttributes; i++) - { - ReadAttribute(); - } - } - - if (FirstChild != -1) - { - TreeTable.Seek(FirstChild, SeekOrigin.Begin); - ReadElement(); - } - - - XMLFile.WriteEndElement(); - XMLFile.Flush(); - - if (NextSibling != -1) - { - TreeTable.Seek(NextSibling, SeekOrigin.Begin); - ReadElement(); - } - - } - - } -} diff --git a/AppInfoCli/CXML.cs b/AppInfoCli/CXML.cs new file mode 100644 index 0000000..d1de354 --- /dev/null +++ b/AppInfoCli/CXML.cs @@ -0,0 +1,780 @@ +using Ionic.Zlib; +using System; +using System.Collections.Generic; +using System.Diagnostics; +using System.Drawing; +using System.IO; +using System.Text; +using System.Xml; + +namespace CXML +{ + enum AttributeType + { + TYPE_NONE, + TYPE_INT, + TYPE_FLOAT, + TYPE_STRING, + TYPE_CHAR, + TYPE_STYLE_ID, + TYPE_INTEGER_ARRAY, + TYPE_FLOAT_ARRAY, + TYPE_FILE, + TYPE_ID_STRING_LOOPBACK, + TYPE_ID_STRING, + TYPE_ID_INT_LOOPBACK, + TYPE_ID_INT + }; + + + class Tools + { + public static String RemoveDecimals(float FloatValue) + { + String FloatStr = FloatValue.ToString(); + String[] FloatParts = FloatStr.Split('.'); + if (FloatParts.Length > 1) + if(FloatParts[1].Length > 2) + FloatParts[1] = FloatParts[1].Substring(0, 2); + + + FloatStr = String.Join(".", FloatParts); + return FloatStr; + } + public static MemoryStream ByteToStream(byte[] Array) + { + MemoryStream ms = new MemoryStream(); + ms.Write(Array, 0x00, Array.Length); + ms.Seek(0, SeekOrigin.Begin); + return ms; + } + + public static byte[] StreamToByte(Stream stream) + { + int StreamLen = (int)stream.Length; + byte[] Bytes = new byte[StreamLen]; + stream.Seek(0, SeekOrigin.Begin); + stream.Read(Bytes, 0x00, StreamLen); + return Bytes; + } + + public static string GetFileExtension(byte[] Bytes) + { + if(IsImage(Bytes)) + { + return ".png"; + } + else if(IsZlib(Bytes)) + { + return ".zlib"; + } + else if(IsGim(Bytes)) + { + return ".gim"; + } + else if(IsRcf(Bytes)) + { + return ".rcs"; + } + else if(IsDDS(Bytes)) + { + return ".dds"; + } + else if (IsVAG(Bytes)) + { + return ".vag"; + } + else + { + return ".bin"; + } + } + + public static bool IsVAG(byte[] Bytes) + { + MemoryStream Data = ByteToStream(Bytes); + String header = ReadString(Data, 4); + if (header.StartsWith("VAG")) + { + return true; + } + else + { + return false; + } + } + + public static bool IsDDS(byte[] Bytes) + { + MemoryStream Data = ByteToStream(Bytes); + String header = ReadString(Data, 4); + if (header.StartsWith("DDS")) + { + return true; + } + else + { + return false; + } + } + + + public static bool IsRcf(byte[] Bytes) + { + MemoryStream Data = ByteToStream(Bytes); + String header = ReadString(Data, 5); + if (header.StartsWith("RCSF")) + { + return true; + } + else + { + return false; + } + } + + public static bool IsGim(byte[] Bytes) + { + MemoryStream Data = ByteToStream(Bytes); + String header = ReadString(Data,4); + if(header.StartsWith("MIG")) + { + return true; + } + else + { + return false; + } + } + + public static bool IsZlib(byte[] Bytes) + { + if(Bytes[0] == 0x78) + { + if (Bytes[1] == 0x01) + return true; + if (Bytes[1] == 0x9C) + return true; + if (Bytes[1] == 0xDA) + return true; + } + return false; + } + + + + public static bool IsImage(byte[] Bytes) + { + try + { + GetBitmap(Bytes); + } + catch(Exception) + { + return false; + } + return true; + } + + public static Bitmap GetBitmap(byte[] BitmapBytes) + { + MemoryStream ms = ByteToStream(BitmapBytes); + Bitmap bmp = new Bitmap(ms); + ms.Dispose(); + return bmp; + } + + public static String ReadStringAt(Stream ms, int location) + { + long ogPos = ms.Position; + ms.Seek(location, SeekOrigin.Begin); + String str = ReadString(ms); + ms.Seek(ogPos, SeekOrigin.Begin); + return str; + } + + public static int ReadIntAt(Stream ms, int location) + { + BinaryReader BinReader = new BinaryReader(ms); + long ogPos = ms.Position; + ms.Seek(location, SeekOrigin.Begin); + int i = BinReader.ReadInt32(); + ms.Seek(ogPos, SeekOrigin.Begin); + return i; + } + + public static int ReadInt(Stream ms) + { + BinaryReader BinReader = new BinaryReader(ms); + int i = BinReader.ReadInt32(); + return i; + } + + public static String ReadString(Stream ms, int limit = -1) + { + int i = 0xFF; + + MemoryStream StringStream = new MemoryStream(); + + do + { + i = ms.ReadByte(); + if (i == 0 && i != limit) + break; + StringStream.WriteByte((byte)i); + } + while (true); + + byte[] StringData = StringStream.ToArray(); + + String str = Encoding.UTF8.GetString(StringData); + + return str; + + } + } + + class Parser + { + + private static bool _checkMagicNumber() + { + String Magic = Tools.ReadStringAt(InfoFile, 0x00); + + if (Magic.StartsWith("PSMA")) + { + return true; + } + else if(Magic.StartsWith("RCOF")) + { + return true; + } + else if (Magic.StartsWith("RCSF")) + { + return true; + } + else + { + return false; + } + } + + static FileStream InfoFile; + + static MemoryStream TreeTable; + static MemoryStream StringIDTable; + static MemoryStream IntIDTable; + static MemoryStream StringTable; + static MemoryStream CharTable; + static MemoryStream StylesIDTable; + static MemoryStream IntArrayTable; + static MemoryStream FloatArrayTable; + static MemoryStream FileTable; + + + static BinaryReader bTreeTable; + static BinaryReader bIntIDTable; + static BinaryReader bFloatArrayTable; + static BinaryReader bIntArrayTable; + static BinaryReader bStylesIDTable; + + static XmlWriter XMLFile; + + public static void Init(string Path, bool CheckMagic = true) + { + InfoFile = File.Open(Path, FileMode.Open, FileAccess.Read); + if(CheckMagic) + { + if (!_checkMagicNumber()) + { + throw new Exception("Incorrect magic number."); + } + + } + + + TreeTable = Tools.ByteToStream(GetTreeTable()); + StringIDTable = Tools.ByteToStream(GetStringIDTable()); + IntIDTable = Tools.ByteToStream(GetIntIDTable()); + StringTable = Tools.ByteToStream(GetStringTable()); + CharTable = Tools.ByteToStream(GetCharTable()); + StylesIDTable = Tools.ByteToStream(GetStyleIDTable()); + IntArrayTable = Tools.ByteToStream(GetIntArrayTable()); + FloatArrayTable = Tools.ByteToStream(GetFloatArrayTable()); + FileTable = Tools.ByteToStream(GetFileTable()); + + bTreeTable = new BinaryReader(TreeTable); + bIntIDTable = new BinaryReader(IntIDTable); + bFloatArrayTable = new BinaryReader(FloatArrayTable); + bIntArrayTable = new BinaryReader(IntArrayTable); + bStylesIDTable = new BinaryReader(StylesIDTable); + + return; + } + + public static void Term() + { + InfoFile.Close(); + TreeTable.Close(); + StringIDTable.Close(); + IntIDTable.Close(); + StringTable.Close(); + CharTable.Close(); + StylesIDTable.Close(); + IntArrayTable.Close(); + FloatArrayTable.Close(); + FileTable.Close(); + + bTreeTable.Close(); + bIntIDTable.Close(); + bFloatArrayTable.Close(); + bIntArrayTable.Close(); + bStylesIDTable.Close(); + } + + public static int GetTreeTableOffset() + { + return Tools.ReadIntAt(InfoFile,0x8); + } + + public static int GetTreeTableSize() + { + return Tools.ReadIntAt(InfoFile, 0xC); + } + + public static int GetIDStringTableOffset() + { + return Tools.ReadIntAt(InfoFile, 0x10); + } + + public static int GetIDStringTableSize() + { + return Tools.ReadIntAt(InfoFile, 0x14); + } + + public static int GetIDIntTableOffset() + { + return Tools.ReadIntAt(InfoFile, 0x18); + } + + public static int GetIDIntTableSize() + { + return Tools.ReadIntAt(InfoFile, 0x1C); + } + + public static int GetStringTableOffset() + { + return Tools.ReadIntAt(InfoFile, 0x20); + } + + public static int GetStringTableSize() + { + return Tools.ReadIntAt(InfoFile, 0x24); + } + + public static int GetCharTableOffset() + { + return Tools.ReadIntAt(InfoFile, 0x28); + } + + public static int GetCharTableSize() + { + return Tools.ReadIntAt(InfoFile, 0x2C); + } + + public static int GetStyleIDTableOffset() + { + return Tools.ReadIntAt(InfoFile, 0x30); + } + + public static int GetStyleIDTableSize() + { + return Tools.ReadIntAt(InfoFile, 0x34); + } + + public static int GetIntArrayTableOffset() + { + return Tools.ReadIntAt(InfoFile, 0x38); + } + + public static int GetIntArrayTableSize() + { + return Tools.ReadIntAt(InfoFile, 0x3C); + } + + public static int GetFloatArrayTableOffset() + { + return Tools.ReadIntAt(InfoFile, 0x40); + } + + public static int GetFloatArrayTableSize() + { + return Tools.ReadIntAt(InfoFile, 0x44); + } + + public static int GetFileTableOffset() + { + return Tools.ReadIntAt(InfoFile, 0x48); + } + + public static int GetFileTableSize() + { + return Tools.ReadIntAt(InfoFile, 0x4C); + } + + public static byte[] GetTreeTable() + { + int TableOffset = GetTreeTableOffset(); + int TableSize = GetTreeTableSize(); + InfoFile.Seek(TableOffset, SeekOrigin.Begin); + byte[] Table = new byte[TableSize]; + InfoFile.Read(Table, 0x00, TableSize); + return Table; + } + + public static byte[] GetStringIDTable() + { + int IDStrTableOffset = GetIDStringTableOffset(); + int IDStrTableSize = GetIDStringTableSize(); + InfoFile.Seek(IDStrTableOffset, SeekOrigin.Begin); + byte[] IDStringTable = new byte[IDStrTableSize]; + InfoFile.Read(IDStringTable, 0x00, IDStrTableSize); + return IDStringTable; + } + + public static byte[] GetIntIDTable() + { + int IDIntTableOffset = GetIDIntTableOffset(); + int IDIntTableSize = GetIDIntTableSize(); + InfoFile.Seek(IDIntTableOffset, SeekOrigin.Begin); + byte[] IDIntTable = new byte[IDIntTableSize]; + InfoFile.Read(IDIntTable, 0x00, IDIntTableSize); + return IDIntTable; + } + + public static byte[] GetStringTable() + { + int StringTableOffset = GetStringTableOffset(); + int StringTableSize = GetStringTableSize(); + InfoFile.Seek(StringTableOffset, SeekOrigin.Begin); + byte[] StringTable = new byte[StringTableSize]; + InfoFile.Read(StringTable, 0x00, StringTableSize); + return StringTable; + } + + public static byte[] GetCharTable() + { + int CharTableOffset = GetCharTableOffset(); + int CharTableSize = GetCharTableSize(); + InfoFile.Seek(CharTableOffset, SeekOrigin.Begin); + byte[] CharTable = new byte[CharTableSize]; + InfoFile.Read(CharTable, 0x00, CharTableSize); + return CharTable; + } + + public static byte[] GetStyleIDTable() + { + int StyleIDTableOffset = GetStyleIDTableOffset(); + int StyleIDTableSize = GetStyleIDTableSize(); + InfoFile.Seek(StyleIDTableOffset, SeekOrigin.Begin); + byte[] StyleIDTable = new byte[StyleIDTableSize]; + InfoFile.Read(StyleIDTable, 0x00, StyleIDTableSize); + return StyleIDTable; + } + + public static byte[] GetIntArrayTable() + { + int IntArrayTableOffset = GetIntArrayTableOffset(); + int IntArrayTableSize = GetIntArrayTableSize(); + InfoFile.Seek(IntArrayTableOffset, SeekOrigin.Begin); + byte[] IntArrayTable = new byte[IntArrayTableSize]; + InfoFile.Read(IntArrayTable, 0x00, IntArrayTableSize); + return IntArrayTable; + } + + public static byte[] GetFloatArrayTable() + { + int FloatArrayTableOffset = GetFloatArrayTableOffset(); + int FloatArrayTableSize = GetFloatArrayTableSize(); + InfoFile.Seek(FloatArrayTableOffset, SeekOrigin.Begin); + byte[] FloatArrayTable = new byte[FloatArrayTableSize]; + InfoFile.Read(FloatArrayTable, 0x00, FloatArrayTableSize); + return FloatArrayTable; + } + + public static byte[] GetFileTable() + { + int DataOffset = GetFileTableOffset(); + int DataLength = GetFileTableSize(); + InfoFile.Seek(DataOffset, SeekOrigin.Begin); + byte[] FileTable = new byte[DataLength]; + InfoFile.Read(FileTable, 0x00, DataLength); + return FileTable; + } + + public static void DecompileCXML(String CXMLFile, bool force = false) + { + if(Directory.Exists("files")) + Directory.Delete("files", true); + Term(); + Init(CXMLFile,force); + XmlWriterSettings XMLSettings = new XmlWriterSettings(); + XMLSettings.Indent = true; + + XMLFile = XmlWriter.Create(Path.GetFileNameWithoutExtension(CXMLFile)+".xml", XMLSettings); + XMLFile.WriteStartDocument(); + + ReadElement(); + + XMLFile.WriteEndDocument(); + XMLFile.Flush(); + + Term(); + } + + public static void ReadAttribute(String ElementName = "") + { + int AttributePtr = bTreeTable.ReadInt32(); + AttributeType Type = (AttributeType)bTreeTable.ReadInt32(); + + String AttributeName = Tools.ReadStringAt(StringTable, AttributePtr); + object AttributeValue = ""; + Console.WriteLine("AttributeType: " + Type.ToString() + " - "+ TreeTable.Position.ToString()); + switch (Type) + { + case AttributeType.TYPE_NONE: + Console.WriteLine("UNSUPPORTED TYPE @ " + TreeTable.Position); + Console.ReadKey(); + break; + case AttributeType.TYPE_INT: + AttributeValue = bTreeTable.ReadInt32(); + TreeTable.Seek(4, SeekOrigin.Current); + break; + case AttributeType.TYPE_FLOAT: + float FloatValue = bTreeTable.ReadSingle(); + AttributeValue = Tools.RemoveDecimals(FloatValue); + TreeTable.Seek(4, SeekOrigin.Current); + break; + case AttributeType.TYPE_STRING: + int StringOffset = bTreeTable.ReadInt32(); + int StringLen = bTreeTable.ReadInt32(); + + byte[] StringBytes = new byte[StringLen]; + StringTable.Seek(StringOffset, 0x00); + StringTable.Read(StringBytes, 0x00, StringLen); + + AttributeValue = Encoding.UTF8.GetString(StringBytes); + break; + case AttributeType.TYPE_CHAR: + int CharOffset = bTreeTable.ReadInt32() * 2; + int CharLen = bTreeTable.ReadInt32(); + + byte[] CharBytes = new byte[CharLen]; + CharTable.Seek(CharOffset, 0x00); + CharTable.Read(CharBytes, 0x00, CharLen); + + AttributeValue = Encoding.Unicode.GetString(CharBytes); + break; + case AttributeType.TYPE_STYLE_ID: + int StyleTableOffset = bTreeTable.ReadInt32(); + int StyleTableSize = bTreeTable.ReadInt32(); + + byte[] StyleTableData = new byte[StyleTableSize]; + + StylesIDTable.Seek(StyleTableOffset, SeekOrigin.Begin); + StylesIDTable.Read(StyleTableData, 0x00, StyleTableSize); + AttributeValue = BitConverter.ToString(StyleTableData).Replace("-",""); + break; + case AttributeType.TYPE_INTEGER_ARRAY: + int IntArrayOffset = bTreeTable.ReadInt32(); + int IntArraySize = bTreeTable.ReadInt32(); + IntArrayTable.Seek(IntArrayOffset, SeekOrigin.Begin); + + List IntList = new List(); + + for (int i = 0; i < IntArraySize; i++) + { + int IntValue = bIntArrayTable.ReadInt32(); + IntList.Add(IntValue); + } + int[] IntArray = IntList.ToArray(); + AttributeValue = String.Join(", ", IntArray); + break; + case AttributeType.TYPE_FLOAT_ARRAY: + int FloatArrayOffset = bTreeTable.ReadInt32(); + int FloatArraySize = bTreeTable.ReadInt32(); + FloatArrayTable.Seek(FloatArrayOffset, SeekOrigin.Begin); + + List StrList = new List(); + + for(int i = 0; i < FloatArraySize; i++) + { + FloatValue = bFloatArrayTable.ReadSingle(); + StrList.Add(Tools.RemoveDecimals(FloatValue)); + } + string[] StrArray = StrList.ToArray(); + AttributeValue = String.Join(", ", StrArray); + break; + case AttributeType.TYPE_FILE: + int FilePtr = bTreeTable.ReadInt32(); + int FileSz = bTreeTable.ReadInt32(); + + String FileName = ""; + + Byte[] FileData = new Byte[FileSz]; + FileTable.Seek(FilePtr, SeekOrigin.Begin); + FileTable.Read(FileData, 0, FileSz); + + if (!Directory.Exists("files")) + Directory.CreateDirectory("files"); + + int count = 0; + string CounterStr = count.ToString(); + do + { + String Extension = Tools.GetFileExtension(FileData); + CounterStr = count.ToString(); + if (count == 0) + CounterStr = ""; + FileName = "files/" + ElementName + "-" + AttributeName + CounterStr + Extension; + count++; + } + while (File.Exists(FileName)); + + Console.WriteLine("Writing: " + FileName); + if(Path.GetExtension(FileName) == ".zlib") + { + Console.WriteLine("Decompressing " + FileName); + Byte[] DecompressedData = ZlibStream.UncompressBuffer(FileData); + String Extension = Tools.GetFileExtension(DecompressedData); + if (!Directory.Exists("files/decompressed")) + Directory.CreateDirectory("files/decompressed"); + String DecompressedFilename = "files/decompressed/" + ElementName + "-" + AttributeName + CounterStr + Extension; + Console.WriteLine("Decompressed file written to: " + DecompressedFilename); + File.WriteAllBytes(DecompressedFilename, DecompressedData); + + if(Extension == ".gim") + { + if(File.Exists("GimConv/GimConv.exe")) + { + if (!Directory.Exists("files/converted")) + Directory.CreateDirectory("files/converted"); + + Console.WriteLine("Decoding GIM."); + + Process Proc = new Process(); + Proc.StartInfo.FileName = "GimConv/GimConv.exe"; + Proc.StartInfo.Arguments = Path.GetFileName(DecompressedFilename) + " -o " + "../converted/" + ElementName + "-" + AttributeName + CounterStr + ".png"; + Proc.StartInfo.RedirectStandardOutput = true; + Proc.StartInfo.RedirectStandardError = true; + Proc.StartInfo.UseShellExecute = false; + Proc.StartInfo.WorkingDirectory = Directory.GetCurrentDirectory()+ "/files/decompressed"; + Proc.Start(); + Proc.WaitForExit(); + Console.WriteLine(Proc.StandardOutput.ReadToEnd()); + + Console.WriteLine("Done!"); + } + + } + } + + File.WriteAllBytes(FileName, FileData); + + AttributeValue = FileName; + break; + case AttributeType.TYPE_ID_STRING_LOOPBACK: + int StringIdTableOffset = bTreeTable.ReadInt32(); + AttributeValue = Tools.ReadStringAt(StringIDTable, StringIdTableOffset + 0x4); + TreeTable.Seek(4, SeekOrigin.Current); + break; + case AttributeType.TYPE_ID_STRING: + Console.WriteLine("UNSUPPORTED TYPE @ " + TreeTable.Position); + Console.ReadKey(); + break; + case AttributeType.TYPE_ID_INT_LOOPBACK: + int IntIdTableOffset = bTreeTable.ReadInt32(); + IntIDTable.Seek(IntIdTableOffset, SeekOrigin.Begin); + int Loopback = bIntIDTable.ReadInt32(); + int IDValue = bIntIDTable.ReadInt32(); + + int StringPtr = Tools.ReadIntAt(TreeTable, Loopback); + String LoopbackAttribute = Tools.ReadStringAt(StringTable, StringPtr); + Console.WriteLine("Loopback: " + LoopbackAttribute); + + AttributeValue = IDValue.ToString("X8"); + TreeTable.Seek(4, SeekOrigin.Current); + break; + case AttributeType.TYPE_ID_INT: + IntIdTableOffset = bTreeTable.ReadInt32(); + IntIDTable.Seek(IntIdTableOffset + 4, SeekOrigin.Begin); + IDValue = bIntIDTable.ReadInt32(); + + AttributeValue = IDValue.ToString("X8"); + TreeTable.Seek(4, SeekOrigin.Current); + break; + default: + Console.WriteLine("UNKNOWN TYPE @ " + TreeTable.Position); + break; + }; + + + Console.WriteLine(AttributeName + "=" + AttributeValue.ToString()); + XMLFile.WriteAttributeString(AttributeName, AttributeValue.ToString()); + XMLFile.Flush(); + } + + public static void ReadElement() + { + + int ElementPtr = bTreeTable.ReadInt32(); + int NumAttributes = bTreeTable.ReadInt32(); + + int ParentPtr = bTreeTable.ReadInt32(); + int PrevSibling = bTreeTable.ReadInt32(); + int NextSibling = bTreeTable.ReadInt32(); + + int FirstChild = bTreeTable.ReadInt32(); + int LastChild = bTreeTable.ReadInt32(); + + String ElementName = Tools.ReadStringAt(StringTable, ElementPtr); + Console.WriteLine("Creating Element: " + ElementName); + Console.WriteLine("Attribute Count: " + NumAttributes); + + Console.WriteLine("ParentPtr: " + ParentPtr); + Console.WriteLine("PrevSibling: " + PrevSibling); + Console.WriteLine("NextSibling: " + NextSibling); + + Console.WriteLine("FirstChild: " + FirstChild); + Console.WriteLine("LastChild: " + LastChild); + + XMLFile.WriteStartElement(ElementName); + + if(NumAttributes > 0) + { + for (int i = 0; i < NumAttributes; i++) + { + ReadAttribute(ElementName); + } + } + + if (FirstChild != -1) + { + TreeTable.Seek(FirstChild, SeekOrigin.Begin); + ReadElement(); + } + + + XMLFile.WriteEndElement(); + XMLFile.Flush(); + + if (NextSibling != -1) + { + TreeTable.Seek(NextSibling, SeekOrigin.Begin); + ReadElement(); + } + + } + + } +} diff --git a/AppInfoCli/AppInfoCli.csproj b/AppInfoCli/CXMLCli.csproj similarity index 84% rename from AppInfoCli/AppInfoCli.csproj rename to AppInfoCli/CXMLCli.csproj index 27cd443..5296d34 100644 --- a/AppInfoCli/AppInfoCli.csproj +++ b/AppInfoCli/CXMLCli.csproj @@ -6,8 +6,8 @@ AnyCPU {BE72E673-25FF-47AB-AF5B-9448B69E3990} Exe - AppInfoCli - AppInfoCli + CXMLDecompiler + CXMLDecompiler v4.6.1 512 true @@ -33,6 +33,9 @@ 4 + + ..\packages\DotNetZip.1.13.3\lib\net40\DotNetZip.dll + @@ -44,12 +47,13 @@ - + + \ No newline at end of file diff --git a/AppInfoCli/Program.cs b/AppInfoCli/Program.cs index d10de38..31c5d5c 100644 --- a/AppInfoCli/Program.cs +++ b/AppInfoCli/Program.cs @@ -2,14 +2,15 @@ using System.IO; using System.Reflection; -namespace AppInfoCli +namespace CXMLCli { class Program { static void Main(string[] args) { - bool Check = true; + bool Check = true; + if (args.Length == 0) { Console.WriteLine("-- app.info/CXML Decompiler --"); @@ -17,11 +18,18 @@ namespace AppInfoCli Console.WriteLine("Required Arguments:"); Console.WriteLine("\t"); Console.WriteLine("Optional Arguments:"); - Console.WriteLine("\t-f --force Dont check magic number."); - Console.WriteLine("\t-s --dump-strings Dump string table."); - Console.WriteLine("\t-t --dump-tree Dump tree table."); - Console.WriteLine("\t-ft --dump-file Dump file table."); - Console.WriteLine("\t-d --decompile Decompile CXML."); + Console.WriteLine("\t-f --force Dont check magic number."); + Console.WriteLine("\t-dt --dump-tables Dump ALL tables."); + Console.WriteLine("\t-tt --dump-tree Dump tree table."); + Console.WriteLine("\t-ist --dump-string-id Dump string ID table."); + Console.WriteLine("\t-iit --dump-int-id Dump int ID table."); + Console.WriteLine("\t-st --dump-string Dump string table."); + Console.WriteLine("\t-ct --dump-char Dump char table."); + Console.WriteLine("\t-sit --dump-style-id Dump style ID table."); + Console.WriteLine("\t-iat --dump-int-array Dump int array table."); + Console.WriteLine("\t-fat --dump-float-array Dump float array table."); + Console.WriteLine("\t-ft --dump-file Dump file table."); + Console.WriteLine("\t-d --decompile Decompile CXML."); Console.WriteLine("Example: " + Path.GetFileName(Assembly.GetEntryAssembly().Location) + " app.info -f -s -t -f -d"); Console.WriteLine("Default functonality is to Decompile,\ntThis is canceled if any other arguments passed."); return; @@ -29,43 +37,83 @@ namespace AppInfoCli String ArgsFull = String.Join(" ", args); String path = args[0]; + CXML.Parser.Init(path, Check); if (ArgsFull.Contains("-f") || ArgsFull.Contains("--force")) { Check = false; } - - if (ArgsFull.Contains("-s") || ArgsFull.Contains("--dump-strings")) + if (ArgsFull.Contains("-dt") || ArgsFull.Contains("--dump-tables")) { - Console.WriteLine("Dumping string table."); - AppInfo.Parser.Init(path, Check); - File.WriteAllBytes("string-table.bin",AppInfo.Parser.GetStringTable()); - AppInfo.Parser.Term(); - + ArgsFull += "-tt -ist -iit -st -ct -sit -iat -fat -ft"; } - - if (ArgsFull.Contains("-t") || ArgsFull.Contains("--dump-tree")) + if (ArgsFull.Contains("-tt") || ArgsFull.Contains("--dump-tree")) { Console.WriteLine("Dumping tree table."); - AppInfo.Parser.Init(path, Check); - File.WriteAllBytes("tree-table.bin", AppInfo.Parser.GetTreeTable()); - AppInfo.Parser.Term(); + File.WriteAllBytes("tree-table.bin", CXML.Parser.GetTreeTable()); + } + if (ArgsFull.Contains("-ist") || ArgsFull.Contains("--dump-string-id")) + { + Console.WriteLine("Dumping string ID table."); + File.WriteAllBytes("string-id-table.bin", CXML.Parser.GetStringIDTable()); + + } + + if (ArgsFull.Contains("-iit") || ArgsFull.Contains("--dump-int-id")) + { + Console.WriteLine("Dumping int ID table."); + File.WriteAllBytes("int-id-table.bin", CXML.Parser.GetIntIDTable()); + } + + if (ArgsFull.Contains("-st") || ArgsFull.Contains("--dump-string")) + { + Console.WriteLine("Dumping string table."); + File.WriteAllBytes("string-table.bin",CXML.Parser.GetStringTable()); + + } + + if (ArgsFull.Contains("-ct") || ArgsFull.Contains("--dump-char")) + { + Console.WriteLine("Dumping char table."); + File.WriteAllBytes("char-table.bin", CXML.Parser.GetCharTable()); + } + + if (ArgsFull.Contains("-sit") || ArgsFull.Contains("--dump-style-id")) + { + Console.WriteLine("Dumping style ID table."); + File.WriteAllBytes("style-id-table.bin", CXML.Parser.GetStyleIDTable()); + } + + + if (ArgsFull.Contains("-iat") || ArgsFull.Contains("--dump-int-array")) + { + Console.WriteLine("Dumping int array table."); + File.WriteAllBytes("int-array-table.bin", CXML.Parser.GetIntArrayTable()); + } + + if (ArgsFull.Contains("-fat") || ArgsFull.Contains("--dump-float-array")) + { + Console.WriteLine("Dumping float array table."); + File.WriteAllBytes("float-array-table.bin", CXML.Parser.GetFloatArrayTable()); + } + + if (ArgsFull.Contains("-ft") || ArgsFull.Contains("--dump-tree")) { Console.WriteLine("Dumping file table."); - AppInfo.Parser.Init(path, Check); - File.WriteAllBytes("file-table.bin", AppInfo.Parser.GetTreeTable()); - AppInfo.Parser.Term(); + File.WriteAllBytes("file-table.bin", CXML.Parser.GetTreeTable()); } if (ArgsFull.Contains("-d") || ArgsFull.Contains("--decompile") || args.Length == 1) { Console.WriteLine("Decompiling."); - AppInfo.Parser.DecompileCXML(path, Check); + CXML.Parser.DecompileCXML(path, Check); + Console.WriteLine("\n\nDECOMPILATION COMPLETE!"); + Console.ReadKey(); } } } diff --git a/AppInfoCli/packages.config b/AppInfoCli/packages.config new file mode 100644 index 0000000..6438d2c --- /dev/null +++ b/AppInfoCli/packages.config @@ -0,0 +1,4 @@ + + + + \ No newline at end of file diff --git a/AppInfoParser.sln b/AppInfoParser.sln index ac070b6..463d29a 100644 --- a/AppInfoParser.sln +++ b/AppInfoParser.sln @@ -3,7 +3,7 @@ Microsoft Visual Studio Solution File, Format Version 12.00 # Visual Studio 15 VisualStudioVersion = 15.0.28010.2003 MinimumVisualStudioVersion = 10.0.40219.1 -Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "AppInfoCli", "AppInfoCli\AppInfoCli.csproj", "{BE72E673-25FF-47AB-AF5B-9448B69E3990}" +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "CXMLCli", "AppInfoCli\CXMLCli.csproj", "{BE72E673-25FF-47AB-AF5B-9448B69E3990}" EndProject Global GlobalSection(SolutionConfigurationPlatforms) = preSolution diff --git a/packages/DotNetZip.1.13.3/.signature.p7s b/packages/DotNetZip.1.13.3/.signature.p7s new file mode 100644 index 0000000..565167a Binary files /dev/null and b/packages/DotNetZip.1.13.3/.signature.p7s differ diff --git a/packages/DotNetZip.1.13.3/DotNetZip.1.13.3.nupkg b/packages/DotNetZip.1.13.3/DotNetZip.1.13.3.nupkg new file mode 100644 index 0000000..e895bc3 Binary files /dev/null and b/packages/DotNetZip.1.13.3/DotNetZip.1.13.3.nupkg differ diff --git a/packages/DotNetZip.1.13.3/lib/net40/DotNetZip.dll b/packages/DotNetZip.1.13.3/lib/net40/DotNetZip.dll new file mode 100644 index 0000000..35d0483 Binary files /dev/null and b/packages/DotNetZip.1.13.3/lib/net40/DotNetZip.dll differ diff --git a/packages/DotNetZip.1.13.3/lib/net40/DotNetZip.pdb b/packages/DotNetZip.1.13.3/lib/net40/DotNetZip.pdb new file mode 100644 index 0000000..338a808 Binary files /dev/null and b/packages/DotNetZip.1.13.3/lib/net40/DotNetZip.pdb differ diff --git a/packages/DotNetZip.1.13.3/lib/net40/DotNetZip.xml b/packages/DotNetZip.1.13.3/lib/net40/DotNetZip.xml new file mode 100644 index 0000000..69a4753 --- /dev/null +++ b/packages/DotNetZip.1.13.3/lib/net40/DotNetZip.xml @@ -0,0 +1,18520 @@ + + + + DotNetZip + + + + + Delivers the remaining bits, left-aligned, in a byte. + + + + This is valid only if NumRemainingBits is less than 8; + in other words it is valid only after a call to Flush(). + + + + + + Reset the BitWriter. + + + + 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. + + + + + + Write some number of bits from the given value, into the output. + + + + The nbits value should be a max of 25, for safety. For performance + reasons, this method does not check! + + + + + + Write a full 8-bit byte into the output. + + + + + Write four 8-bit bytes into the output. + + + + + Write all available byte-aligned bytes. + + + + This method writes no new output, but flushes any accumulated + bits. At completion, the accumulator may contain up to 7 + bits. + + + 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. + + + + + + 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. + + + + Knuth's increments seem to work better than Incerpi-Sedgewick here. + Possibly because the number of elems to sort is usually small, typically + <= 20. + + + + BZip2Compressor writes its compressed data out via a BitWriter. This + is necessary because BZip2 does byte shredding. + + + + + The number of uncompressed bytes being held in the buffer. + + + + 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. + + + + + + Accept new bytes into the compressor data buffer + + + + This method does the first-level (cheap) run-length encoding, and + stores the encoded data into the rle block. + + + + + + Process one input byte into the block. + + + + + 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. + + + + 0 if the byte was not written, non-zero if written. + + + + Append one run to the output block. + + + + + 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. + + + true if the block is now full; otherwise false. + + + + Compress the data that has been placed (Run-length-encoded) into the + block. The compressed data goes into the CompressedBytes array. + + + + Side effects: 1. fills the CompressedBytes array. 2. sets the + AvailableBytesOut property. + + + + + This is the most hammered method of this class. + +

+ This is the version using unrolled loops. +

+ + + Method "mainQSort3", file "blocksort.c", BZip2 1.0.2 + + + Array instance identical to sfmap, both are used only + temporarily and independently, so we do not need to allocate + additional memory. + + + + A read-only decorator stream that performs BZip2 decompression on Read. + + + + + Compressor State + + + + + Create a BZip2InputStream, wrapping it around the given input Stream. + + + + The input stream will be closed when the BZip2InputStream is closed. + + + The stream from which to read compressed data + + + + Create a BZip2InputStream with the given stream, and + specifying whether to leave the wrapped stream open when + the BZip2InputStream is closed. + + The stream from which to read compressed data + + Whether to leave the input stream open, when the BZip2InputStream closes. + + + + + This example reads a bzip2-compressed file, decompresses it, + and writes the decompressed data into a newly created file. + + + 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); + } + } + } + } + + + + + + Read data from the stream. + + + + + To decompress a BZip2 data stream, create a BZip2InputStream, + providing a stream that reads compressed data. Then call Read() on + that BZip2InputStream, and the data read will be decompressed + as you read. + + + + A BZip2InputStream can be used only for Read(), not for Write(). + + + + The buffer into which the read data should be placed. + the offset within that data array to put the first byte read. + the number of bytes to read. + the number of bytes actually read + + + + Read a single byte from the stream. + + the byte read from the stream, or -1 if EOF + + + + Indicates whether the stream can be read. + + + The return value depends on whether the captive stream supports reading. + + + + + Indicates whether the stream supports Seek operations. + + + Always returns false. + + + + + Indicates whether the stream can be written. + + + The return value depends on whether the captive stream supports writing. + + + + + Flush the stream. + + + + + Reading this property always throws a . + + + + + The position of the stream pointer. + + + + Setting this property always throws a . Reading will return the + total number of uncompressed bytes read in. + + + + + Calling this method always throws a . + + this is irrelevant, since it will always throw! + this is irrelevant, since it will always throw! + irrelevant! + + + + Calling this method always throws a . + + this is irrelevant, since it will always throw! + + + + Calling this method always throws a . + + this parameter is never used + this parameter is never used + this parameter is never used + + + + Dispose the stream. + + + indicates whether the Dispose method was invoked by user code. + + + + + Close the stream. + + + + + Read n bits from input, right justifying the result. + + + + For example, if you read 1 bit, the result is either 0 + or 1. + + + + The number of bits to read, always between 1 and 32. + + + + Called by createHuffmanDecodingTables() exclusively. + + + Called by recvDecodingTables() exclusively. + + + Freq table collected to save a pass over the data during + decompression. + + + 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. + + + + A write-only decorator stream that compresses data as it is + written using the BZip2 algorithm. + + + + + Constructs a new BZip2OutputStream, that sends its + compressed output to the given output stream. + + + + The destination stream, to which compressed output will be sent. + + + + + This example reads a file, then compresses it with bzip2 file, + and writes the compressed data into a newly created file. + + + 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); + } + } + } + } + + + + + + Constructs a new BZip2OutputStream with specified blocksize. + + the destination stream. + + The blockSize in units of 100000 bytes. + The valid range is 1..9. + + + + + Constructs a new BZip2OutputStream. + + the destination stream. + + whether to leave the captive stream open upon closing this stream. + + + + + Constructs a new BZip2OutputStream with specified blocksize, + and explicitly specifies whether to leave the wrapped stream open. + + + the destination stream. + + The blockSize in units of 100000 bytes. + The valid range is 1..9. + + + whether to leave the captive stream open upon closing this stream. + + + + + Close the stream. + + + + This may or may not close the underlying stream. Check the + constructors that accept a bool value. + + + + + + Flush the stream. + + + + + The blocksize parameter specified at construction time. + + + + + Write data to the stream. + + + + + Use the BZip2OutputStream to compress data while writing: + create a BZip2OutputStream with a writable output stream. + Then call Write() on that BZip2OutputStream, providing + uncompressed data as input. The data sent to the output stream will + be the compressed form of the input data. + + + + A BZip2OutputStream can be used only for Write() not for Read(). + + + + + The buffer holding data to write to the stream. + the offset within that data array to find the first byte to write. + the number of bytes to write. + + + + Indicates whether the stream can be read. + + + The return value is always false. + + + + + Indicates whether the stream supports Seek operations. + + + Always returns false. + + + + + Indicates whether the stream can be written. + + + The return value should always be true, unless and until the + object is disposed and closed. + + + + + Reading this property always throws a . + + + + + The position of the stream pointer. + + + + Setting this property always throws a . Reading will return the + total number of uncompressed bytes written through. + + + + + Calling this method always throws a . + + this is irrelevant, since it will always throw! + this is irrelevant, since it will always throw! + irrelevant! + + + + Calling this method always throws a . + + this is irrelevant, since it will always throw! + + + + Calling this method always throws a . + + this parameter is never used + this parameter is never used + this parameter is never used + never returns anything; always throws + + + + A write-only decorator stream that compresses data as it is + written using the BZip2 algorithm. This stream compresses by + block using multiple threads. + + + This class performs BZIP2 compression through writing. For + more information on the BZIP2 algorithm, see + . + + + + This class is similar to , + 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. + + + + The tradeoff is that this class uses more memory and more CPU than the + vanilla BZip2OutputStream. Also, for small files, the + ParallelBZip2OutputStream can be much slower than the vanilla + BZip2OutputStream, because of the overhead associated to using the + thread pool. + + + + + + + Constructs a new ParallelBZip2OutputStream, that sends its + compressed output to the given output stream. + + + + The destination stream, to which compressed output will be sent. + + + + + This example reads a file, then compresses it with bzip2 file, + and writes the compressed data into a newly created file. + + + 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); + } + } + } + } + + + + + + Constructs a new ParallelBZip2OutputStream with specified blocksize. + + the destination stream. + + The blockSize in units of 100000 bytes. + The valid range is 1..9. + + + + + Constructs a new ParallelBZip2OutputStream. + + the destination stream. + + whether to leave the captive stream open upon closing this stream. + + + + + Constructs a new ParallelBZip2OutputStream with specified blocksize, + and explicitly specifies whether to leave the wrapped stream open. + + + the destination stream. + + The blockSize in units of 100000 bytes. + The valid range is 1..9. + + + whether to leave the captive stream open upon closing this stream. + + + + + The maximum number of concurrent compression worker threads to use. + + + + + 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 + ThreadPool.QueueUserWorkItem(), 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. + + + + 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. + + + + 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. + + + + 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 property. + + + + 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. + + + + 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. + + + + 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. + + + + + + Close the stream. + + + + This may or may not close the underlying stream. Check the + constructors that accept a bool value. + + + + + + Flush the stream. + + + + + The blocksize parameter specified at construction time. + + + + + Write data to the stream. + + + + + Use the ParallelBZip2OutputStream to compress data while + writing: create a ParallelBZip2OutputStream with a writable + output stream. Then call Write() on that + ParallelBZip2OutputStream, providing uncompressed data as + input. The data sent to the output stream will be the compressed + form of the input data. + + + + A ParallelBZip2OutputStream can be used only for + Write() not for Read(). + + + + + The buffer holding data to write to the stream. + the offset within that data array to find the first byte to write. + the number of bytes to write. + + + + Indicates whether the stream can be read. + + + The return value is always false. + + + + + Indicates whether the stream supports Seek operations. + + + Always returns false. + + + + + Indicates whether the stream can be written. + + + The return value depends on whether the captive stream supports writing. + + + + + Reading this property always throws a . + + + + + The position of the stream pointer. + + + + Setting this property always throws a . Reading will return the + total number of uncompressed bytes written through. + + + + + The total number of bytes written out by the stream. + + + This value is meaningful only after a call to Close(). + + + + + Calling this method always throws a . + + this is irrelevant, since it will always throw! + this is irrelevant, since it will always throw! + irrelevant! + + + + Calling this method always throws a . + + this is irrelevant, since it will always throw! + + + + Calling this method always throws a . + + this parameter is never used + this parameter is never used + this parameter is never used + never returns anything; always throws + + + + Returns the "random" number at a specific index. + + the index + the random number + + + + An enum that provides the different self-extractor flavors + + + + + A self-extracting zip archive that runs from the console or + command line. + + + + + A self-extracting zip archive that presents a graphical user + interface when it is executed. + + + + + The options for generating a self-extracting archive. + + + + + The type of SFX to create. + + + + + The command to run after extraction. + + + + + This is optional. Leave it empty (null in C# or Nothing in + VB) to run no command after extraction. + + + + 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: program.exe arg1 + arg2. 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. + + + + 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:\project files\program name.exe" arg1 arg2. + + + + If the flavor of the SFX is SelfExtractorFlavor.ConsoleApplication, + 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 true, you may not + see error messages, if a problem occurs. + + + + If the flavor of the SFX is + SelfExtractorFlavor.WinFormsApplication, 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. + + + + You can specify environment variables within this string, with a format like + %NAME%. The value of these variables will be expanded at the time + the SFX is run. Example: %WINDIR%\system32\xcopy.exe may expand at + runtime to c:\Windows\System32\xcopy.exe. + + + + By combining this with the RemoveUnpackedFilesAfterExecute + 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 Flavor to + SelfExtractorFlavor.ConsoleApplication, and set Quiet + 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 DefaultExtractDirectory. + + + + If you set Flavor to + SelfExtractorFlavor.WinFormsApplication, and set Quiet 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. + + + + + + + The default extract directory the user will see when + running the self-extracting archive. + + + + + Passing null (or Nothing in VB) here will cause the Self Extractor to use + the the user's personal directory () for the default extract + location. + + + + This is only a default location. The actual extract location will be + settable on the command line when the SFX is executed. + + + + You can specify environment variables within this string, + with %NAME%. The value of these variables will be + expanded at the time the SFX is run. Example: + %USERPROFILE%\Documents\unpack may expand at runtime to + c:\users\melvin\Documents\unpack. + + + + + + The name of an .ico file in the filesystem to use for the application icon + for the generated SFX. + + + + + 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 /win32icon + option to the csc.exe compiler when constructing the SFX file. + + + + + + + Whether the ConsoleApplication SFX will be quiet during extraction. + + + + + This option affects the way the generated SFX runs. By default it is + false. When you set it to true,... + + + + + Flavor + Behavior + + + + ConsoleApplication + no messages will be emitted during successful + operation. 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. + + + + + WinFormsApplication + the SFX extracts automatically when the application + is launched, with no additional user input. + + + + + + + When you set it to false,... + + + + + Flavor + Behavior + + + + ConsoleApplication + the extractor will emit a + message to the console for each entry extracted. + + 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. + + + + + + WinFormsApplication + the SFX presents a forms UI and allows the user to select + options before extracting. + + + + + + + + + + Specify what the self-extractor will do when extracting an entry + would overwrite an existing file. + + + + The default behavvior is to Throw. + + + + + + Whether to remove the files that have been unpacked, after executing the + PostExtractCommandLine. + + + + + If true, and if there is a + PostExtractCommandLine, 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. + + + + Setting this flag, and setting Flavor to + SelfExtractorFlavor.ConsoleApplication, and setting Quiet 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 DefaultExtractDirectory. + + + + + + + The file version number to embed into the generated EXE. It will show up, for + example, during a mouseover in Windows Explorer. + + + + + + The product version to embed into the generated EXE. It will show up, for + example, during a mouseover in Windows Explorer. + + + + 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. + + + + + + The copyright notice, if any, to embed into the generated EXE. + + + + 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". + + + + + + The description to embed into the generated EXE. + + + + 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. + + + + + + The product name to embed into the generated EXE. + + + + Use any arbitrary string. This text will be displayed + while viewing properties of the EXE file in + Windows Explorer. + + + + + + The title to display in the Window of a GUI SFX, while it extracts. + + + + + 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. + + + + This property has an effect only when producing a Self-extractor + of flavor SelfExtractorFlavor.WinFormsApplication. + + + + + + + Additional options for the csc.exe compiler, when producing the SFX + EXE. + + + + + + The ZipFile type represents a zip archive file. + + + + + This is the main type in the DotNetZip class library. This class reads and + writes zip files, as defined in the specification + for zip files described by PKWare. The compression for this + implementation is provided by a managed-code version of Zlib, included with + DotNetZip in the classes in the Ionic.Zlib namespace. + + + + 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 + Stream type to write the zip file, you may want to consider the class. + + + + Both the ZipOutputStream class and the ZipFile 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. + + + + The ZipFile class is generally easier to use than + ZipOutputStream and should be considered a higher-level interface. For + example, when creating a zip file via calls to the PutNextEntry() and + Write() methods on the ZipOutputStream class, the caller is + responsible for opening the file, reading the bytes from the file, writing + those bytes into the ZipOutputStream, setting the attributes on the + ZipEntry, 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 ZipFile.AddFile(). + For this reason, the ZipOutputStream 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 Stream + metaphor. + + + + Aside from the differences in programming model, there are other + differences in capability between the two classes. + + + + + ZipFile can be used to read and extract zip files, in addition to + creating zip files. ZipOutputStream cannot read zip files. If you want + to use a stream to read zip files, check out the class. + + + + ZipOutputStream does not support the creation of segmented or spanned + zip files. + + + + ZipOutputStream cannot produce a self-extracting archive. + + + + + Be aware that the ZipFile class implements the interface. In order for ZipFile to + produce a valid zip file, you use use it within a using clause (Using + in VB), or call the Dispose() method explicitly. See the examples + for how to employ a using clause. + + + + + + + Saves the ZipFile instance to a self-extracting zip archive. + + + + + + The generated exe image will execute on any machine that has the .NET + Framework 4.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. + + + + There are two "flavors" of self-extracting archive. The + WinFormsApplication 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 ConsoleApplication. 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. + + + + 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 , which defaults to . These temporary files are + removed upon successful completion of this method. + + + + When a user runs the WinForms SFX, the user's personal directory (Environment.SpecialFolder.Personal) + will be used as the default extract location. If you want to set the + default extract location, you should use the other overload of + SaveSelfExtractor()/ 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 4.0 is required + on the computer when the self-extracting archive is run. + + + + NB: This method is not available in the "Reduced" DotNetZip library. + + + + + + + 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); + } + + + 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 + + + + + a pathname, possibly fully qualified, to be created. Typically it + will end in an .exe extension. + + Indicates whether a Winforms or Console self-extractor is + desired. + + + + Saves the ZipFile instance to a self-extracting zip archive, using + the specified save options. + + + + + 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 for more + details. + + + + 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. + + + + + + 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. + + 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); + } + + + 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 + + + + The name of the EXE to generate. + provides the options for creating the + Self-extracting archive. + + + + Adds an item, either a file or a directory, to a zip file archive. + + + + + 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 ZipFile. + + + + The name of the item may be a relative path or a fully-qualified + path. Remember, the items contained in ZipFile instance get written + to the disk only when you call or a similar + save method. + + + + The directory name used for the file within the archive is the same + as the directory name (potentially a relative path) specified in the + . + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to the + ZipEntry added. + + + + + + + + + This method has two overloads. + + the name of the file or directory to add. + + The ZipEntry added. + + + + 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. + + + + + If adding a directory, the add is recursive on all files and + subdirectories contained within it. + + + The name of the item may be a relative path or a fully-qualified path. + The item added by this call to the ZipFile is not read from the + disk nor written to the zip file archive until the application calls + Save() on the ZipFile. + + + + 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. + + + + Encryption will be used on the file data if the Password has + been set on the ZipFile object, prior to calling this method. + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to the + ZipEntry added. + + + + + + Thrown if the file or directory passed in does not exist. + + + the name of the file or directory to add. + + + + 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 null (Nothing in VB) will use the + path on the fileOrDirectoryName. Passing the empty string ("") will + insert the item at the root path within the archive. + + + + + + + + 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. + + + 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); + } + + + + 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 + + + The ZipEntry added. + + + + Adds a File to a Zip file archive. + + + + + 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 ZipFile, does DotNetZip read the file from the filesystem and + then write the content to the zip file archive. + + + + This method will throw an exception if an entry with the same name already + exists in the ZipFile. + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to the + ZipEntry added. + + + + + + + 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. + + + 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); + } + + + + 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 + + + + This method has two overloads. + + + + + + + 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. + + The ZipEntry corresponding to the File added. + + + + Adds a File to a Zip file archive, potentially overriding the path to be + used within the zip archive. + + + + + The file added by this call to the ZipFile is not written to the + zip file archive until the application calls Save() on the ZipFile. + + + + This method will throw an exception if an entry with the same name already + exists in the ZipFile. + + + + This version of the method allows the caller to explicitly specify the + directory path to be used in the archive. + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to the + ZipEntry added. + + + + + + + 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. + + + 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); + } + + + + 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 + + + + + + + + + The name of the file to add. The name of the file may be a relative path + or a fully-qualified path. + + + + Specifies a directory path to use to override any path in the fileName. + This path may, or may not, correspond to a real directory in the current + filesystem. If the files within the zip are later extracted, this is the + path used for the extracted file. Passing null (Nothing in + VB) will use the path on the fileName, if any. Passing the empty string + ("") will insert the item at the root path within the archive. + + + The ZipEntry corresponding to the file added. + + + + This method removes a collection of entries from the ZipFile. + + + + 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. + + + + + + + + This method removes a collection of entries from the ZipFile, by name. + + + + A collection of strings that refer to names of entries to be removed + from the ZipFile. For example, you can pass in an array or a + List of Strings that provide the names of entries to be removed. + + + + + + + + This method adds a set of files to the ZipFile. + + + + + Use this method to add a set of files to the zip archive, in one call. + For example, a list of files received from + System.IO.Directory.GetFiles() can be added to a zip archive in one + call. + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to each + ZipEntry added. + + + + + 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. + + + + This example shows how to create a zip file, and add a few files into it. + + 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); + } + + + + 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 + + + + + + + + Adds or updates a set of files in the ZipFile. + + + + + Any files that already exist in the archive are updated. Any files that + don't yet exist in the archive are added. + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to each + ZipEntry added. + + + + + 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. + + + + + + Adds a set of files to the ZipFile, using the + specified directory path in the archive. + + + + + 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. + + + + For ZipFile properties including , , , , , , and , their respective values at the + time of this call will be applied to each ZipEntry added. + + + + + 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. + + + + 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 null (Nothing in + VB) will use the path on each of the fileNames, if any. Passing + the empty string ("") will insert the item at the root path within the + archive. + + + + + + + Adds a set of files to the ZipFile, using the specified directory + path in the archive, and preserving the full directory structure in the + filenames. + + + + + + Think of the as a "root" or + base directory used in the archive for the files that get added. when + is true, the hierarchy of files + found in the filesystem will be placed, with the hierarchy intact, + starting at that root in the archive. When preserveDirHierarchy + is false, the path hierarchy of files is flattned, and the flattened + set of files gets placed in the root within the archive as specified in + directoryPathInArchive. + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to each + ZipEntry added. + + + + + + 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. + + + + Specifies a directory path to use as a prefix for each entry 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 null (Nothing in + VB) will use the path on each of the fileNames, if any. Passing + the empty string ("") will insert the item at the root path within the + archive. + + + + whether the entries in the zip archive will reflect the directory + hierarchy that is present in the various filenames. For example, if + includes two paths, + \Animalia\Chordata\Mammalia\Info.txt and + \Plantae\Magnoliophyta\Dicotyledon\Info.txt, then calling this method + with = false will + result in an exception because of a duplicate entry name, while + calling this method with = + true will result in the full direcory paths being included in + the entries added to the ZipFile. + + + + + + Adds or updates a set of files to the ZipFile, using the specified + directory path in the archive. + + + + + + Any files that already exist in the archive are updated. Any files that + don't yet exist in the archive are added. + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to each + ZipEntry added. + + + + + 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. + + + + 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 null (Nothing in + VB) will use the path on each of the fileNames, if any. Passing + the empty string ("") will insert the item at the root path within the + archive. + + + + + + + Adds or Updates a File in a Zip file archive. + + + + + 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 UpdateFile method might more accurately be + called "AddOrUpdateFile". + + + + Upon success, there is no way for the application to learn whether the file + was added versus updated. + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to the + ZipEntry added. + + + + + + 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. + + + 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(); + } + + + + 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 + + + + + + + + + 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. + + + + The ZipEntry corresponding to the File that was added or updated. + + + + + Adds or Updates a File in a Zip file archive. + + + + + 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. + + + + 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. + + + + Upon success, there is no way for the application to learn if the file was + added versus updated. + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to the + ZipEntry added. + + + + + + + + + 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. + + + + Specifies a directory path to use to override any path in the + fileName. This path may, or may not, correspond to a real + directory in the current filesystem. If the files within the zip are + later extracted, this is the path used for the extracted file. Passing + null (Nothing in VB) will use the path on the + fileName, if any. Passing the empty string ("") will insert the + item at the root path within the archive. + + + + The ZipEntry corresponding to the File that was added or updated. + + + + + Add or update a directory in a zip archive. + + + + If the specified directory does not exist in the archive, then this method + is equivalent to calling AddDirectory(). 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. + + + + + + + + The path to the directory to be added to the zip archive, or updated in + the zip archive. + + + + The ZipEntry corresponding to the Directory that was added or updated. + + + + + Add or update a directory in the zip archive at the specified root + directory in the archive. + + + + If the specified directory does not exist in the archive, then this method + is equivalent to calling AddDirectory(). 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. + + + + + + + + The path to the directory to be added to the zip archive, or updated + in the zip archive. + + + + 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 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 + directoryName, if any. Passing the empty string ("") will insert + the item at the root path within the archive. + + + + The ZipEntry corresponding to the Directory that was added or updated. + + + + + Add or update a file or directory in the zip archive. + + + + + 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 ZipFile. Calling this method + is equivalent to calling RemoveEntry() if an entry by the same name + already exists, followed calling by AddItem(). + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to the + ZipEntry added. + + + + + + + + + the path to the file or directory to be added or updated. + + + + + Add or update a file or directory. + + + + + 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 ZipFile. Calling this method + is equivalent to calling RemoveEntry(), if an entry by that name + exists, and then calling AddItem(). + + + + 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 + DirectoryPathInArchive. Extracting the entry from the archive will + result in a file stored in that directory path. + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to the + ZipEntry added. + + + + + + + + + The path for the File or Directory to be added or updated. + + + Specifies a directory path to use to override any path in the + itemName. 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 + itemName, if any. Passing the empty string ("") will insert the + item at the root path within the archive. + + + + + Adds a named entry into the zip archive, taking content for the entry + from a string. + + + + 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. + + + + The content of the file, should it be extracted from the zip. + + + + The name, including any path, to use for the entry within the archive. + + + The ZipEntry added. + + + + This example shows how to add an entry to the zipfile, using a string as + content for that entry. + + + 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"); + } + + + + 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 + + + + + + Adds a named entry into the zip archive, taking content for the entry + from a string, and using the specified text encoding. + + + + + + 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, 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. + + + + Most Encoding classes support a constructor that accepts a boolean, + indicating whether to emit a BOM or not. For example see . + + + + + + The name, including any path, to use within the archive for the entry. + + + + The content of the file, should it be extracted from the zip. + + + + 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 . + + + The ZipEntry added. + + + + + Create an entry in the ZipFile using the given Stream + as input. The entry will have the given filename. + + + + + + The application should provide an open, readable stream; in this case it + will be read during the call to or one of + its overloads. + + + + 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. + + + + In cases where a large number of streams will be added to the + ZipFile, the application may wish to avoid maintaining all of the + streams open simultaneously. To handle this situation, the application + should use the + overload. + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to the + ZipEntry added. + + + + + + + This example adds a single entry to a ZipFile via a Stream. + + + + 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 + } + } + + + + 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 + + + + + + + The name, including any path, which is shown in the zip file for the added + entry. + + + The input stream from which to grab content for the file + + The ZipEntry added. + + + + Add a ZipEntry for which content is written directly by the application. + + + + + 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. + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to the + ZipEntry added. + + + + About progress events: When using the WriteDelegate, DotNetZip does + not issue any SaveProgress events with EventType = + Saving_EntryBytesRead. (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 + Saving_Started, + + Saving_BeforeWriteEntry, and + Saving_AfterWriteEntry. + + + + 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. + + + + 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. + + + + As you can imagine, this can cause performance problems for large + streams, and it can lead to correctness problems when you use a + WriteDelegate. 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. + + + + 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 the Workitem + tracking this issue. + + + + + the name of the entry to add + the delegate which will write the entry content + the ZipEntry added + + + + 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. + + + 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); + } + + + + + + 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 + AddFile() 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 WriteDelegate to do it, in this way. + + + 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); + } + } + + + + + + 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 AddFile() method. The key scenario for + which the WriteDelegate 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 WriteDelegate would be appropriate for those cases as + well. + + + 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 + + + + + + Add an entry, for which the application will provide a stream + containing the entry data, on a just-in-time basis. + + + + + 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. The application provides an + opener delegate that will be called by the DotNetZip library to + obtain a readable stream that can be read to get the bytes for + the given entry. Typically, this delegate opens a stream. + Optionally, the application can provide a closer delegate as + well, which will be called by DotNetZip when all bytes have been + read from the entry. + + + + These delegates are called from within the scope of the call to + ZipFile.Save(). + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to the + ZipEntry added. + + + + + + + This example uses anonymous methods in C# to open and close the + source stream for the content for a zip entry. + + + 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); + } + + + + + + + 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. + + + + 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 + + + + + the name of the entry to add + + the delegate that will be invoked by ZipFile.Save() to get the + readable stream for the given entry. ZipFile.Save() will call + read on this stream to obtain the data for the entry. This data + will then be compressed and written to the newly created zip + file. + + + the delegate that will be invoked to close the stream. This may + be null (Nothing in VB), in which case no call is makde to close + the stream. + + the ZipEntry added + + + + + Updates the given entry in the ZipFile, using the given + string as content for the ZipEntry. + + + + + + Calling this method is equivalent to removing the ZipEntry for + the given file name and directory path, if it exists, and then calling + . See the documentation for + that method for further explanation. The string content is encoded + using the default encoding for the machine. This encoding is distinct + from the encoding used for the filename itself. See + . + + + + + + The name, including any path, to use within the archive for the entry. + + + + The content of the file, should it be extracted from the zip. + + + The ZipEntry added. + + + + + Updates the given entry in the ZipFile, using the given string as + content for the ZipEntry. + + + + Calling this method is equivalent to removing the ZipEntry for the + given file name and directory path, if it exists, and then calling . See the + documentation for that method for further explanation. + + + + The name, including any path, to use within the archive for the entry. + + + + The content of the file, should it be extracted from the zip. + + + + The text encoding to use when encoding the string. Be aware: This is + distinct from the text encoding used to encode the filename. See . + + + The ZipEntry added. + + + + + Updates the given entry in the ZipFile, using the given delegate + as the source for content for the ZipEntry. + + + + Calling this method is equivalent to removing the ZipEntry for the + given file name and directory path, if it exists, and then calling . See the + documentation for that method for further explanation. + + + + The name, including any path, to use within the archive for the entry. + + + the delegate which will write the entry content. + + The ZipEntry added. + + + + + Updates the given entry in the ZipFile, using the given delegates + to open and close the stream that provides the content for the ZipEntry. + + + + Calling this method is equivalent to removing the ZipEntry for the + given file name and directory path, if it exists, and then calling . See the + documentation for that method for further explanation. + + + + The name, including any path, to use within the archive for the entry. + + + + the delegate that will be invoked to open the stream + + + the delegate that will be invoked to close the stream + + + The ZipEntry added or updated. + + + + + Updates the given entry in the ZipFile, using the given stream as + input, and the given filename and given directory Path. + + + + + Calling the method is equivalent to calling RemoveEntry() if an + entry by the same name already exists, and then calling AddEntry() + with the given fileName and stream. + + + + The stream must be open and readable during the call to + ZipFile.Save. You can dispense the stream on a just-in-time basis + using the property. Check the + documentation of that property for more information. + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to the + ZipEntry added. + + + + + + + + + The name, including any path, to use within the archive for the entry. + + + The input stream from which to read file data. + The ZipEntry added. + + + + 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. + + + The data to use for the entry. + + + The name, including any path, to use within the archive for the entry. + + + The ZipEntry added. + + + + Updates the given entry in the ZipFile, using the given byte + array as content for the entry. + + + + Calling this method is equivalent to removing the ZipEntry + for the given filename and directory path, if it exists, and then + calling . See the + documentation for that method for further explanation. + + + + The name, including any path, to use within the archive for the entry. + + + The content to use for the ZipEntry. + + The ZipEntry added. + + + + + Adds the contents of a filesystem directory to a Zip file archive. + + + + + + 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. + + + + 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. + + + + 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. + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to each + ZipEntry added. + + + + + + + + + + This method has 2 overloads. + + The name of the directory to add. + The ZipEntry added. + + + + Adds the contents of a filesystem directory to a Zip file archive, + overriding the path to be used for entries in the archive. + + + + + 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. + + + + 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. + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to each + ZipEntry added. + + + + + + + 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. + + + + public void ZipUp(string targetZip, string directory) + { + using (var zip = new ZipFile()) + { + zip.AddDirectory(directory, System.IO.Path.GetFileName(directory)); + zip.Save(targetZip); + } + } + + + + + + + + The name of the directory to add. + + + 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 null + (Nothing in VB) or the empty string ("") will insert the items at + the root path within the archive. + + + The ZipEntry added. + + + + Creates a directory in the zip archive. + + + + + + Use this when you want to create a directory in the archive but there is + no corresponding filesystem representation for that directory. + + + + 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. + + + + + + The name of the directory to create in the archive. + + The ZipEntry added. + + + + Checks a zip file to see if its directory is consistent. + + + + + + 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. + + + This method may take a long time to run for large zip files. + + + This method is not supported in the Reduced version of DotNetZip. + + + + Developers using COM can use the ComHelper.CheckZip(String) + method. + + + + + The filename to of the zip file to check. + + true if the named zip file checks OK. Otherwise, false. + + + + + + + Checks a zip file to see if its directory is consistent, + and optionally fixes the directory if necessary. + + + + + + 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 Name_Fixed.zip. + + + + 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 + fixIfNecessary is true. + + + + This method is not supported in the Reduced version of DotNetZip. + + + + + The filename to of the zip file to check. + + If true, the method will fix the zip file if + necessary. + + + a TextWriter in which messages generated while checking will be written. + + + true if the named zip is OK; false if the file needs to be fixed. + + + + + + + Rewrite the directory within a zipfile. + + + + + + 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. + + + This can take a long time for large zip files. + + This won't work if the zip file uses a non-standard + code page - neither IBM437 nor UTF-8. + + + This method is not supported in the Reduced or Compact Framework + versions of DotNetZip. + + + + Developers using COM can use the ComHelper.FixZipDirectory(String) + method. + + + + + The filename to of the zip file to fix. + + + + + + + Verify the password on a zip file. + + + + + 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. + + + There is no way to check a password without doing the + decryption. So this code decrypts and extracts the given + zipfile into + + + + The filename to of the zip file to fix. + + The password to check. + + a bool indicating whether the password matches. + + + + Provides a human-readable string with information about the ZipFile. + + + + + 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. + + + This information is mostly useful for diagnostic purposes. + + + + + + Indicates whether to perform a full scan of the zip file when reading it. + + + + + + You almost never want to use this property. + + + + When reading a zip file, if this flag is true (True 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. + + + + This flag is effective only when calling . Normally you would read a ZipFile with the + static ZipFile.Read + method. But you can't set the FullScan property on the + ZipFile instance when you use a static factory method like + ZipFile.Read. + + + + + + + This example shows how to read a zip file using the full scan approach, + and then save it, thereby producing a corrected zip file. + + + using (var zip = new ZipFile()) + { + zip.FullScan = true; + zip.Initialize(zipFileName); + zip.Save(newName); + } + + + + Using zip As New ZipFile + zip.FullScan = True + zip.Initialize(zipFileName) + zip.Save(newName) + End Using + + + + + + + Whether to sort the ZipEntries before saving the file. + + + + The default is false. If you have a large number of zip entries, the sort + alone can consume significant time. + + + + + using (var zip = new ZipFile()) + { + zip.AddFiles(filesToAdd); + zip.SortEntriesBeforeSaving = true; + zip.Save(name); + } + + + + Using zip As New ZipFile + zip.AddFiles(filesToAdd) + zip.SortEntriesBeforeSaving = True + zip.Save(name) + End Using + + + + + + + Indicates whether NTFS Reparse Points, like junctions, should be + traversed during calls to AddDirectory(). + + + + 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. + + + + + using (var zip = new ZipFile()) + { + zip.AddDirectoryWillTraverseReparsePoints = false; + zip.AddDirectory(dirToZip,"fodder"); + zip.Save(zipFileToCreate); + } + + + + + + Size of the IO buffer used while saving. + + + + + + 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? + + + + Now that we have that 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. + + + + Changing the buffer size affects a few things: first, for larger buffer + sizes, the memory used by the ZipFile, 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. + + + + 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. + + + + + + This example shows how you might set a large buffer size for efficiency when + dealing with zip entries that are larger than 1gb. + + 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); + } + + + + + + Size of the work buffer to use for the ZLIB codec during compression. + + + + + 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 ZipFile.Save() + overloads. + + + 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. + + + + + + Indicates whether extracted files should keep their paths as + stored in the zip archive. + + + + + This property affects Extraction. It is not used when creating zip + archives. + + + + With this property set to false, 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 true, extracting entries from the zip file results in files + with no path: the folders are "flattened." + + + + An example: suppose the zip file contains entries /directory1/file1.txt and + /directory2/file2.txt. With FlattenFoldersOnExtract 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. + + + + + + + The compression strategy to use for all entries. + + + + 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 Ionic.Zlib.CompressionStrategy. + + + + + The name of the ZipFile, on disk. + + + + + + When the ZipFile instance was created by reading an archive using + one of the ZipFile.Read methods, this property represents the name + of the zip file that was read. When the ZipFile instance was + created by using the no-argument constructor, this value is null + (Nothing in VB). + + + + If you use the no-argument constructor, and you then explicitly set this + property, when you call , this name will + specify the name of the zip file created. Doing so is equivalent to + calling . When instantiating a + ZipFile by reading from a stream or byte array, the Name + property remains null. When saving to a stream, the Name + property is implicitly set to null. + + + + + + Sets the compression level to be used for entries subsequently added to + the zip archive. + + + + + Varying the compression level used on entries can affect the + size-vs-speed tradeoff when compression and decompressing data streams + or files. + + + + As with some other properties on the ZipFile class, like , , and , setting this property on a ZipFile + instance will cause the specified CompressionLevel to be used on all + items that are subsequently added to the + ZipFile instance. If you set this property after you have added + items to the ZipFile, but before you have called Save(), + those items will not use the specified compression level. + + + + 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 BestCompression 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. + + + + + + The compression method for the zipfile. + + + + By default, the compression method is CompressionMethod.Deflate. + + + + + + + A comment attached to the zip archive. + + + + + + This property is read/write. It allows the application to specify a + comment for the ZipFile, or read the comment for the + ZipFile. After setting this property, changes are only made + permanent when you call a Save() method. + + + + According to PKWARE's + zip specification, the comment is not encrypted, even if there is a + password set on the zip file. + + + + 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 is + Never, it uses the default encoding (IBM437). (b) if is Always, it always uses the + alternate encoding (). (c) if is AsNecessary, 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 ZipFile.Save(). + + + + When creating a zip archive using this library, it is possible to change + the value of between each + entry you add, and between adding entries and the call to + Save(). 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 + alone, or specify it only + once, before adding any entries to the ZipFile instance. + + + + + + + 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. + + + + + 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 + true, meaning the Windows-format times are stored in the zip + archive. + + + + 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, all three values are implicitly set to + DateTime.Now. Applications can also explicitly set those times by + calling . + + + + PKWARE's + zip specification 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. + + + + 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 Infozip + 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. + + + + The times stored are taken from , , and . + + + + The value set here applies to all entries subsequently added to the + ZipFile. + + + + This property is not mutually exclusive of the 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 LastModified 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. + + + + 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. + + + + + This example shows how to save a zip file that contains file timestamps + in a format normally used by Unix. + + 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); + } + + + + 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 + + + + + + + + + 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. + + + + + 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 + false, meaning the Unix-format times are not stored in the zip + archive. + + + + 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, all three values are implicitly set to DateTime.Now. + Applications can also explicitly set those times by calling . + + + + PKWARE's + zip specification 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. + + + + 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 Infozip + 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. + + + + The times stored are taken from , , and . + + + + This property is not mutually exclusive of the 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 LastModified 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. + + + + 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. + + + + + + + + + Indicates whether verbose output is sent to the during AddXxx() and + ReadXxx() operations. + + + + This is a synthetic property. It returns true if the is non-null. + + + + + Returns true if an entry by the given name exists in the ZipFile. + + + the name of the entry to find + true if an entry with the given name exists; otherwise false. + + + + + Indicates whether to perform case-sensitive matching on the filename when + retrieving entries in the zipfile via the string-based indexer. + + + + The default value is false, 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 true 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. + + + + + Indicates whether to ignore duplicate files (report only the first entry) + when loading a zipfile. + + + + The default value is false, which will try to make all files + available (duplicates will have a "copy" suffix appended to their name). + Setting this to true prior to using Initialize to read a + zipfile will prevent this and instead just ignore the duplicates. + + + + + Indicates whether to encode entry filenames and entry comments using Unicode + (UTF-8). + + + + + The + PKWare zip specification 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. + + + + 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. + + + + 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. + + + + 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. + + + + 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. + + + + 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. + + + + If you do not set this flag, it will remain false. If this flag is false, + your ZipFile 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". + + + + 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 ZipFile, 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. + + + + 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. + + + + Rather than specify the encoding in a binary fashion using this flag, an + application can specify an arbitrary encoding via the 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. + + + + + + + Specify whether to use ZIP64 extensions when saving a zip archive. + + + + + + When creating a zip file, the default value for the property is . is + safest, in the sense that you will not get an Exception if a pre-ZIP64 + limit is exceeded. + + + + You may set the property at any time before calling Save(). + + + + When reading a zip file via the Zipfile.Read() 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. + + + + An interesting question is, if you have set this property to + AsNecessary, and then successfully saved, does the resulting + archive use ZIP64 extensions or not? To learn this, check the property, after calling Save(). + + + + Have you thought about + donating? + + + + + + + + Indicates whether the archive requires ZIP64 extensions. + + + + + + This property is null (or Nothing in VB) if the archive has + not been saved, and there are fewer than 65334 ZipEntry items + contained in the archive. + + + + The Value 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 Save() is attempted + on the zip archive. The Value of this + property may be set only AFTER one of the Save() methods has been called. + + + + If none of the four conditions holds, and the archive has been saved, then + the Value is false. + + + + A Value 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 property is set to , or if the property is set to and the output stream was not + seekable. Use the property to determine if + the most recent Save() method resulted in an archive that utilized + the ZIP64 extensions. + + + + + + + + + Indicates whether the most recent Save() operation used ZIP64 extensions. + + + + + 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 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 ZipFile. + + + + The value is null (or Nothing in VB) if the archive has not + been saved. + + + + Non-null values (HasValue is true) indicate whether ZIP64 + extensions were used during the most recent Save() 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 UseZip64WhenSaving property was set + to , or because the + UseZip64WhenSaving property was set to and the output stream was not seekable. + The value of this property does not indicate the reason the ZIP64 + extensions were used. + + + + + + + + + Indicates whether the most recent Read() operation read a zip file that uses + ZIP64 extensions. + + + + This property will return null (Nothing in VB) if you've added an entry after reading + the zip file. + + + + + The text encoding to use when writing new entries to the ZipFile, + 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 ZipFile. + + + + + In its + zip specification, 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. + + + + 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 and for each ZipEntry 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 + Comment encoded in IBM437 and a FileName encoded with the + specified "provisional" codepage. + + + + Be aware that a zip file created after you've explicitly set the 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. + + + + When creating a zip archive using this library, it is possible to change + the value of between each + entry you add, and between adding entries and the call to + Save(). Don't do this. It will likely result in a zipfile that is + not readable. For best interoperability, either leave alone, or specify it only once, + before adding any entries to the ZipFile instance. There is one + exception to this recommendation, described later. + + + + 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. + + + + 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. + + + + Example: Suppose you create a zipfile that contains entries with + filenames that have Danish characters. If you use 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". + + + + 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 Zipfile is READ. This means you must use a ZipFile.Read() + 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. + + + + 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 + ProvisionalAlternateEncoding to your desired region-specific code + page, once before adding any entries, and then reset + ProvisionalAlternateEncoding to IBM437 before setting the property and calling Save(). + + + + + This example shows how to read a zip file using the Big-5 Chinese code page + (950), and extract each entry in the zip file. For this code to work as + desired, the Zipfile must have been created using the big5 code page + (CP950). This is typical, for example, when using WinRar on a machine with + CP950 set as the default code page. In that case, the names of entries + within the Zip archive will be stored in that code page, and reading the zip + archive must be done using that code page. If the application did not use + the correct code page in ZipFile.Read(), then names of entries within the + zip archive would not be correctly retrieved. + + 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"); + } + + + + 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 + + + + DefaultEncoding + + + + A Text Encoding to use when encoding the filenames and comments for + all the ZipEntry items, during a ZipFile.Save() operation. + + + + Whether the encoding specified here is used during the save depends + on . + + + + + + 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. + + + + + Gets or sets the TextWriter to which status messages are delivered + for the instance. + + + + If the TextWriter is set to a non-null value, then verbose output is sent + to the TextWriter during Add, Read, Save and + Extract operations. Typically, console applications might use + Console.Out and graphical or headless applications might use a + System.IO.StringWriter. The output of this is suitable for viewing + by humans. + + + + + In this example, a console application instantiates a ZipFile, then + sets the StatusMessageTextWriter to Console.Out. At that + point, all verbose status messages for that ZipFile are sent to the + console. + + + + using (ZipFile zip= ZipFile.Read(FilePath)) + { + zip.StatusMessageTextWriter= System.Console.Out; + // messages are sent to the console during extraction + zip.ExtractAll(); + } + + + + 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 + + + + In this example, a Windows Forms application instantiates a + ZipFile, then sets the StatusMessageTextWriter to a + StringWriter. At that point, all verbose status messages for that + ZipFile are sent to the StringWriter. + + + + var sw = new System.IO.StringWriter(); + using (ZipFile zip= ZipFile.Read(FilePath)) + { + zip.StatusMessageTextWriter= sw; + zip.ExtractAll(); + } + Console.WriteLine("{0}", sw.ToString()); + + + + 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 + + + + + + + Gets or sets the name for the folder to store the temporary file + this library writes when saving a zip archive. + + + + + This library will create a temporary file when saving a Zip archive to a + file. This file is written when calling one of the Save() methods + that does not save to a stream, or one of the SaveSelfExtractor() + methods. + + + + By default, the library will create the temporary file in the directory + specified for the file itself, via the property or via + the method. + + + + 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 ZipFile + is saved, specfy ".". To revert to the default behavior, set this + property to null (Nothing in VB). + + + + 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 Save() + is called. + + + + 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 Save() + specifying the Response.OutputStream as the output stream, there is + no temporary file created. + + + + + Thrown when setting the property if the directory does not exist. + + + + + + Sets the password to be used on the ZipFile instance. + + + + + + When writing a zip archive, this password is applied to the entries, not + to the zip archive itself. It applies to any ZipEntry subsequently + added to the ZipFile, using one of the AddFile, + AddDirectory, AddEntry, or AddItem methods, etc. + When reading a zip archive, this property applies to any entry + subsequently extracted from the ZipFile using one of the Extract + methods on the ZipFile class. + + + + 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. + + + + 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. + + + + If you set the password on the ZipFile, 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 null + (Nothing in VB), and add another entry, the first entry is + encrypted and the second is not. If you call AddFile(), then set + the Password property, then call ZipFile.Save, the file + added will not be password-protected, and no warning will be generated. + + + + When setting the Password, you may also want to explicitly set the 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 , then PKZip 2.0 ("Weak") encryption is used. + This encryption is relatively weak but is very interoperable. If you set + the password to a null value (Nothing in VB), Encryption is + reset to None. + + + + 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 + ZipFile, then call one of the Extract() overloads on the . In this case, the entry is extracted using the + Password that is specified on the ZipFile instance. If you + have not set the Password property, then the password is + null, and the entry is extracted with no password. + + + + If you set the Password property on the ZipFile, then call + Extract() an entry that has not been encrypted with a password, the + password is not used for that entry, and the ZipEntry is extracted + as normal. In other words, the password is used only if necessary. + + + + The class also has a Password property. It takes precedence + over this property on the ZipFile. 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. + + + + + + + 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. + + + // 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"); + } + + + + + 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 + + + + + + ZipFile.Encryption + ZipEntry.Password + + + + The action the library should take when extracting a file that already + exists. + + + + + This property affects the behavior of the Extract methods (one of the + Extract() or ExtractWithPassword() 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. + + + + This property has no effect when extracting to a stream, or when the file + to be extracted does not already exist. + + + + + + + The action the library should take when an error is encountered while + opening or reading files as they are saved into a zip archive. + + + + + 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. + + + + 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. + + + + This property tells DotNetZip what you would like to do in the case of + these errors. The primary options are: ZipErrorAction.Throw to + throw an exception (this is the default behavior if you don't set this + property); ZipErrorAction.Skip to Skip the file for which there + was an error and continue saving; ZipErrorAction.Retry to Retry + the entry that caused the problem; or + ZipErrorAction.InvokeErrorEvent to invoke an event handler. + + + + This property is implicitly set to ZipErrorAction.InvokeErrorEvent + if you add a handler to the event. If you set + this property to something other than + ZipErrorAction.InvokeErrorEvent, then the ZipError + 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. + + + + As with some other properties on the ZipFile class, like , , and , setting this property on a ZipFile + instance will cause the specified ZipErrorAction to be used on all + items that are subsequently added to the + ZipFile instance. If you set this property after you have added + items to the ZipFile, but before you have called Save(), + those items will not use the specified error handling action. + + + + 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. + + + + If you set this property to ZipErrorAction.Skip and you'd like to + learn which files may have been skipped after a Save(), you can + set the on the ZipFile before + calling Save(). A message will be emitted into that writer for + each skipped file, if any. + + + + + + This example shows how to tell DotNetZip to skip any files for which an + error is generated during the Save(). + + 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 + + + + + + + + + + The Encryption to use for entries added to the ZipFile. + + + + + 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 + ZipFile instance. Applications do not need to set the + Encryption property when reading or extracting a zip archive. + + + + If you set this to something other than EncryptionAlgorithm.None, you + will also need to set the . + + + + As with some other properties on the ZipFile class, like and , setting this + property on a ZipFile instance will cause the specified + EncryptionAlgorithm to be used on all items + that are subsequently added to the ZipFile instance. In other + words, if you set this property after you have added items to the + ZipFile, but before you have called Save(), 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 property, before calling + AddFile, AddItem, or AddDirectory (etc.) on the + ZipFile instance. + + + + If you read a ZipFile, you can modify the Encryption on an + encrypted entry, only by setting the Encryption property on the + ZipEntry itself. Setting the Encryption property on the + ZipFile, once it has been created via a call to + ZipFile.Read(), does not affect entries that were previously read. + + + + For example, suppose you read a ZipFile, and there is an encrypted + entry. Setting the Encryption property on that ZipFile and + then calling Save() on the ZipFile does not update the + Encryption used for the entries in the archive. Neither is an + exception thrown. Instead, what happens during the Save() 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. + + + + Suppose an application reads a ZipFile, and there is an encrypted + entry. Setting the Encryption property on that ZipFile and + then adding new entries (via AddFile(), AddEntry(), etc) + and then calling Save() on the ZipFile does not update the + Encryption on any of the entries that had previously been in the + ZipFile. The Encryption property applies only to the + newly-added entries. + + + + + + + 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. + + + + // 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"); + } + + + + ' 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 + + + + + ZipFile.Password + ZipEntry.Encryption + + + + A callback that allows the application to specify the compression level + to use for entries subsequently added to the zip archive. + + + + + + With this callback, the DotNetZip library allows the application to + determine whether compression will be used, at the time of the + Save. This may be useful if the application wants to favor + speed over size, and wants to defer the decision until the time of + Save. + + + + Typically applications set the property on + the ZipFile or on each ZipEntry to determine the level of + compression used. This is done at the time the entry is added to the + ZipFile. Setting the property to + Ionic.Zlib.CompressionLevel.None means no compression will be used. + + + + This callback allows the application to defer the decision on the + CompressionLevel to use, until the time of the call to + ZipFile.Save(). The callback is invoked once per ZipEntry, + at the time the data for the entry is being written out as part of a + Save() 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 None for all .mp3 entries. + + + + 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 CompressionLevel is set to the return value. If this + callback has not been set, then the previously set value for + CompressionLevel is used. + + + + + + + The maximum size of an output segment, when saving a split Zip file. + + + + Make sure you do not read from this field if you've set the value using + + + + Set this to a non-zero value before calling or 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. + + + + 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 + basename.z01, the second will be named basename.z02, and + so on. The final file is named basename.zip. 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. + + + + The value of this property determines the maximum size of a split + segment when writing a split archive. For example, suppose you have a + ZipFile that would save to a single file of 200k. If you set the + MaxOutputSegmentSize to 65536 before calling Save(), 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 + ZipFile. + + + + 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. + + + + 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. + + + + 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. + + + + This property has no effect when reading a split archive. You can read + a split archive in the normal way with DotNetZip. + + + + 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. + + + + If you read a split archive, with and + then subsequently call ZipFile.Save(), unless you set this + property before calling Save(), you will get a normal, + single-file archive. + + + + + + + + The maximum size of an output segment, when saving a split Zip file. + + + + If you set this value, make sure you do not accidently use in your code + + + + Set this to a non-zero value before calling or 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. + + + + 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 + basename.z01, the second will be named basename.z02, and + so on. The final file is named basename.zip. 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. + + + + The value of this property determines the maximum size of a split + segment when writing a split archive. For example, suppose you have a + ZipFile that would save to a single file of 200k. If you set the + MaxOutputSegmentSize to 65536 before calling Save(), 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 + ZipFile. + + + + 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. + + + + 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. + + + + 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. + + + + This property has no effect when reading a split archive. You can read + a split archive in the normal way with DotNetZip. + + + + 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. + + + + If you read a split archive, with and + then subsequently call ZipFile.Save(), unless you set this + property before calling Save(), you will get a normal, + single-file archive. + + + + + + + + Returns the number of segments used in the most recent Save() operation. + + + + This is normally zero, unless you have set the property. If you have set , 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. + + + 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. + + + + + + + The size threshold for an entry, above which a parallel deflate is used. + + + + + + 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. + + + + 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. + + + + 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. + + + + 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%. + + + + 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 . You may have to + perform some tests to determine the best approach for your situation. + + + + + + + + + + The maximum number of buffer pairs to use when performing + parallel compression. + + + + + 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 + ThreadPool.QueueUserWorkItem() to compress those + buffers in a background threadpool thread. After a buffer + is compressed, it is re-ordered and written to the output + stream. + + + + 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. + + + + 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 (). 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. + + + + 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. + + + + 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. + + + + 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. + + + + The application can set this value at any time + before calling ZipFile.Save(). + + + + + + + + Provides a string representation of the instance. + a string representation of the instance. + + + + Returns the version number on the DotNetZip assembly. + + + + + 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. + + + This static property is primarily useful for diagnostic purposes. + + + + + + Creates a new ZipFile instance, using the specified filename. + + + + + 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. + + + + 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 + ZipFile via AddDirectory(), AddFile(), AddItem() + and then write the zip archive to the disk by calling Save(). The + zip file is not actually opened and written to the disk until the + application calls ZipFile.Save(). At that point the new zip file + with the given name is created. + + + + If you won't know the name of the Zipfile until the time you call + ZipFile.Save(), or if you plan to save to a stream (which has no + name), then you should use the no-argument constructor. + + + + 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 method, + passing the name of the zip file, because using ZipFile.Read() in + your code communicates very clearly what you are doing. In either case, + the file is then read into the ZipFile 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. + + + + 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. + + + + Instances of the ZipFile 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 ZipFile instance, or you + can synchronize multi-thread access to a single instance. + + + + By the way, since DotNetZip is so easy to use, don't you think you should + donate $5 or $10? + + + + + + Thrown if name refers to an existing file that is not a valid zip file. + + + + This example shows how to create a zipfile, and add a few files into it. + + 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); + } + + + + 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 + + + + The filename to use for the new zip archive. + + + + + Creates a new ZipFile instance, using the specified name for the + filename, and the specified Encoding. + + + + + See the documentation on the ZipFile + constructor that accepts a single string argument for basic + information on all the ZipFile constructors. + + + + 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 property on the ZipFile + instance after construction. + + + + Instances of the ZipFile 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 ZipFile instance, or you + can synchronize multi-thread access to a single instance. + + + + + + Thrown if name refers to an existing file that is not a valid zip file. + + + The filename to use for the new zip archive. + The Encoding is used as the default alternate + encoding for entries with filenames or comments that cannot be encoded + with the IBM437 code page. + + + + Create a zip file, without specifying a target filename or stream to save to. + + + + + See the documentation on the ZipFile + constructor that accepts a single string argument for basic + information on all the ZipFile constructors. + + + + After instantiating with this constructor and adding entries to the + archive, the application should call or + to save to a file or a + stream, respectively. The application can also set the + property and then call the no-argument method. (This + is the preferred approach for applications that use the library through + COM interop.) If you call the no-argument method + without having set the Name of the ZipFile, either through + the parameterized constructor or through the explicit property , the + Save() will throw, because there is no place to save the file. + + + Instances of the ZipFile class are not multi-thread safe. You may + have multiple threads that each use a distinct ZipFile instance, or + you can synchronize multi-thread access to a single instance. + + + + + This example creates a Zip archive called Backup.zip, containing all the files + in the directory DirectoryToZip. Files within subdirectories are not zipped up. + + 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"); + } + + + + 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 + + + + + + Create a zip file, specifying a text Encoding, but without specifying a + target filename or stream to save to. + + + + + See the documentation on the ZipFile + constructor that accepts a single string argument for basic + information on all the ZipFile constructors. + + + + + + The Encoding is used as the default alternate encoding for entries with + filenames or comments that cannot be encoded with the IBM437 code page. + + + + + Creates a new ZipFile instance, using the specified name for the + filename, and the specified status message writer. + + + + + See the documentation on the ZipFile + constructor that accepts a single string argument for basic + information on all the ZipFile constructors. + + + + 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 + TextWriter, for example, a StringWriter, and then display + the messages in a TextBox, or generate an audit log of ZipFile operations. + + + + To encrypt the data for the files added to the ZipFile instance, + set the Password property after creating the ZipFile instance. + + + + Instances of the ZipFile 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 ZipFile instance, or you + can synchronize multi-thread access to a single instance. + + + + + + Thrown if name refers to an existing file that is not a valid zip file. + + + + + 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(); + } + + + + 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 + + + + The filename to use for the new zip archive. + A TextWriter to use for writing + verbose status messages. + + + + Creates a new ZipFile instance, using the specified name for the + filename, the specified status message writer, and the specified Encoding. + + + + + This constructor works like the ZipFile + constructor that accepts a single string argument. See that + reference for detail on what this constructor does. + + + + This version of the constructor allows the caller to pass in a + TextWriter, and an Encoding. The TextWriter 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 + System.Console.Out to get messages on the Console. A graphical or + headless application may wish to capture the messages in a different + TextWriter, for example, a StringWriter, and then display + the messages in a TextBox, or generate an audit log of + ZipFile operations. + + + + 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 a equivalent to setting the property on the ZipFile + instance after construction. + + + + To encrypt the data for the files added to the ZipFile instance, + set the Password property after creating the ZipFile + instance. + + + + Instances of the ZipFile 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 ZipFile instance, or you + can synchronize multi-thread access to a single instance. + + + + + + Thrown if fileName refers to an existing file that is not a valid zip file. + + + The filename to use for the new zip archive. + A TextWriter to use for writing verbose + status messages. + + The Encoding is used as the default alternate encoding for entries with + filenames or comments that cannot be encoded with the IBM437 code page. + + + + + Initialize a ZipFile instance by reading in a zip file. + + + + + + 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 default (no argument) + constructor, then calling Initialize() to read the contents + of an on-disk zip archive into the ZipFile instance. + + + + .NET applications are encouraged to use the ZipFile.Read() methods + for better clarity. + + + + the name of the existing zip file to read in. + + + + This is an integer indexer into the Zip archive. + + + + + This property is read-only. + + + + Internally, the ZipEntry instances that belong to the + ZipFile are stored in a Dictionary. When you use this + indexer the first time, it creates a read-only + List<ZipEntry> from the Dictionary.Values Collection. + If at any time you modify the set of entries in the ZipFile, + 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. + + + + This means you cannot rename any ZipEntry from + inside an enumeration of the zip file. + + + + The index value. + + + + + + The ZipEntry within the Zip archive at the specified index. If the + entry does not exist in the archive, this indexer throws. + + + + + + This is a name-based indexer into the Zip archive. + + + + + This property is read-only. + + + + The property on the ZipFile + 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. + + + + Regardless of case-sensitivity, it is not always the case that + this[value].FileName == value. In other words, the FileName + property of the ZipEntry retrieved with this indexer, may or may + not be equal to the index value. + + + + 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, zip["dir1\\entry1.txt"].FileName == + "dir1/entry.txt". + + + + 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. + + + + + + This example extracts only the entries in a zip file that are .txt files. + + using (ZipFile zip = ZipFile.Read("PackedDocuments.zip")) + { + foreach (string s1 in zip.EntryFilenames) + { + if (s1.EndsWith(".txt")) + zip[s1].Extract("textfiles"); + } + } + + + 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 + + + + + + Thrown if the caller attempts to assign a non-null value to the indexer. + + + + 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 + property to change this behavior. The + pathname can use forward-slashes or backward slashes. + + + + The ZipEntry within the Zip archive, given by the specified + filename. If the named entry does not exist in the archive, this indexer + returns null (Nothing in VB). + + + + + + The list of filenames for the entries contained within the zip archive. + + + + 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. + + + + + + This example shows one way to test if a filename is already contained + within a zip archive. + + 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(); + } + + + 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 + + + + + The list of strings for the filenames contained within the Zip archive. + + + + + + Returns the readonly collection of entries in the Zip archive. + + + + + + If there are no entries in the current ZipFile, 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. + + + This is the implied enumerator on the ZipFile class. If you use a + ZipFile instance in a context that expects an enumerator, you will + get this collection. + + + + + + + Returns a readonly collection of entries in the Zip archive, sorted by FileName. + + + + If there are no entries in the current ZipFile, 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. + + + + + This example fills a Windows Forms ListView with the entries in a zip file. + + + 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); + } + } + + + + + + + + Returns the number of entries in the Zip archive. + + + + + Removes the given ZipEntry from the zip archive. + + + + + After calling RemoveEntry, the application must call Save to + make the changes permanent. + + + + + Thrown if the specified ZipEntry does not exist in the ZipFile. + + + + 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. + + 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"); + } + + + + 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 + + + + + The ZipEntry to remove from the zip. + + + + + + + + Removes the ZipEntry with the given filename from the zip archive. + + + + + After calling RemoveEntry, the application must call Save to + make the changes permanent. + + + + + + Thrown if the ZipFile is not updatable. + + + + Thrown if a ZipEntry with the specified filename does not exist in + the ZipFile. + + + + + This example shows one way to remove an entry with a given filename from + an existing zip archive. + + + 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(); + } + } + + + 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 + + + + + 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 + CaseSensitiveRetrieval property to change this behavior. The + pathname can use forward-slashes or backward slashes. + + + + + + Closes the read and write streams associated + to the ZipFile, if necessary. + + + + The Dispose() method is generally employed implicitly, via a using(..) {..} + statement. (Using...End Using 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. + + + + This example extracts an entry selected by name, from the Zip file to the + Console. + + 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. + + + + 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 + + + + + + Disposes any managed resources, if the flag is set, then marks the + instance disposed. This method is typically not called explicitly from + application code. + + + + Applications should call the no-arg Dispose method. + + + + indicates whether the method should dispose streams or not. + + + + + Default size of the buffer used for IO. + + + + + 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. + + + + + Depending on the particular event, different properties on the parameter are set. The following + table summarizes the available EventTypes and the conditions under + which this event handler is invoked with a + SaveProgressEventArgs with the given EventType. + + + + + value of EntryType + Meaning and conditions + + + + ZipProgressEventType.Saving_Started + Fired when ZipFile.Save() begins. + + + + + ZipProgressEventType.Saving_BeforeSaveEntry + + Fired within ZipFile.Save(), just before writing data for each + particular entry. + + + + + ZipProgressEventType.Saving_AfterSaveEntry + + Fired within ZipFile.Save(), just after having finished writing data + for each particular entry. + + + + + ZipProgressEventType.Saving_Completed + Fired when ZipFile.Save() has completed. + + + + + ZipProgressEventType.Saving_AfterSaveTempArchive + + 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. + + + + + ZipProgressEventType.Saving_BeforeRenameTempArchive + + 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. + + + + + ZipProgressEventType.Saving_AfterRenameTempArchive + + 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. + + + + + ZipProgressEventType.Saving_AfterCompileSelfExtractor + + Fired after a self-extracting archive has finished compiling. This + EventType is used only within SaveSelfExtractor(). + + + + + ZipProgressEventType.Saving_BytesRead + + 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. + + + + + + + + + This example uses an anonymous method to handle the + SaveProgress event, by updating a progress bar. + + + 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); + } + + + + + This example uses a named method as the + SaveProgress event handler, to update the user, in a + console-based application. + + + 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); + } + } + + + + + 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 + + + + + + This is a more complete example of using the SaveProgress + events in a Windows Forms application, with a + Thread object. + + + 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(); + } + + + + + + + + + + + An event handler invoked before, during, and after the reading of a zip archive. + + + + + Depending on the particular event being signaled, different properties on the + parameter are set. The following table + summarizes the available EventTypes and the conditions under which this + event handler is invoked with a ReadProgressEventArgs with the given EventType. + + + + + value of EntryType + Meaning and conditions + + + + ZipProgressEventType.Reading_Started + Fired just as ZipFile.Read() begins. Meaningful properties: ArchiveName. + + + + + ZipProgressEventType.Reading_Completed + Fired when ZipFile.Read() has completed. Meaningful properties: ArchiveName. + + + + + ZipProgressEventType.Reading_ArchiveBytesRead + Fired while reading, updates the number of bytes read for the entire archive. + Meaningful properties: ArchiveName, CurrentEntry, BytesTransferred, TotalBytesToTransfer. + + + + + ZipProgressEventType.Reading_BeforeReadEntry + Indicates an entry is about to be read from the archive. + Meaningful properties: ArchiveName, EntriesTotal. + + + + + ZipProgressEventType.Reading_AfterReadEntry + Indicates an entry has just been read from the archive. + Meaningful properties: ArchiveName, EntriesTotal, CurrentEntry. + + + + + + + + + + + + + An event handler invoked before, during, and after extraction of + entries in the zip archive. + + + + + Depending on the particular event, different properties on the parameter are set. The following + table summarizes the available EventTypes and the conditions under + which this event handler is invoked with a + ExtractProgressEventArgs with the given EventType. + + + + + value of EntryType + Meaning and conditions + + + + ZipProgressEventType.Extracting_BeforeExtractAll + + Set when ExtractAll() begins. The ArchiveName, Overwrite, and + ExtractLocation properties are meaningful. + + + + ZipProgressEventType.Extracting_AfterExtractAll + + Set when ExtractAll() has completed. The ArchiveName, Overwrite, + and ExtractLocation properties are meaningful. + + + + + ZipProgressEventType.Extracting_BeforeExtractEntry + + Set when an Extract() on an entry in the ZipFile has begun. + Properties that are meaningful: ArchiveName, EntriesTotal, + CurrentEntry, Overwrite, ExtractLocation, EntriesExtracted. + + + + + ZipProgressEventType.Extracting_AfterExtractEntry + + Set when an Extract() on an entry in the ZipFile has completed. + Properties that are meaningful: ArchiveName, EntriesTotal, + CurrentEntry, Overwrite, ExtractLocation, EntriesExtracted. + + + + + ZipProgressEventType.Extracting_EntryBytesWritten + + 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. + + + + + ZipProgressEventType.Extracting_ExtractEntryWouldOverwrite + + 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 ExtractExistingFileAction on the ZipFile or + ZipEntry is set to InvokeExtractProgressEvent. + + + + + + + + + + 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); + } + } + } + + + + 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 + + + + + + + + + + An event handler invoked before, during, and after Adding entries to a zip archive. + + + + Adding a large number of entries to a zip file can take a long + time. For example, when calling 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. + + + + + + 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); + } + } + + + + + + 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 + + + + + + + + + + + + An event that is raised when an error occurs during open or read of files + while saving a zip archive. + + + + + 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 Save(). + + + + Setting a handler implicitly sets to + ZipErrorAction.InvokeErrorEvent. + + + + The handler you add applies to all items that are + subsequently added to the ZipFile instance. If you set this + property after you have added items to the ZipFile, but before you + have called Save(), errors that occur while saving those items + will not cause the error handler to be invoked. + + + + 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. + + + + In the error handler method, you need to set the property on the + ZipErrorEventArgs.CurrentEntry. This communicates back to + DotNetZip what you would like to do with this particular error. Within + an error handler, if you set the ZipEntry.ZipErrorAction property + on the ZipEntry to ZipErrorAction.InvokeErrorEvent 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 ZipEntry.ZipErrorAction property on the + ZipEntry to ZipErrorAction.Throw.) If you set the + ZipErrorEventArgs.Cancel to true, the entire Save() will be + canceled. + + + + In the case that you use ZipErrorAction.Skip, 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. + + + + + + + This example shows how to use an event handler to handle + errors during save of the zip file. + + + 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); + } + } + + + + 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 + + + + + + + + + Extracts all of the items in the zip archive, to the specified path in the + filesystem. The path can be relative or fully-qualified. + + + + + This method will extract all entries in the ZipFile to the + specified path. + + + + 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 ZipFile 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 + overload that allows you to + specify an ExtractExistingFileAction parameter. + + + + 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 ZipEntry.Extract methods. + + + + This method will send verbose output messages to the , if it is set on the ZipFile + instance. + + + + You may wish to take advantage of the ExtractProgress event. + + + + 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 ZipEntry, then the extracted file will also get + these times. + + + + 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. + + + + To compensate, when extracting an archive with ExtractAll, + 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. + + + + This compensation is performed only within the context of an + ExtractAll. If you call ZipEntry.Extract on a directory + entry, the timestamps on directory in the filesystem will reflect the + times stored in the zip. If you then call ZipEntry.Extract on + a file entry, which is extracted into the directory, the timestamps on + the directory will be updated to the current time. + + + + + This example extracts all the entries in a zip archive file, to the + specified target directory. The extraction will overwrite any + existing files silently. + + + String TargetDirectory= "unpack"; + using(ZipFile zip= ZipFile.Read(ZipFileToExtract)) + { + zip.ExtractExistingFile= ExtractExistingFileAction.OverwriteSilently; + zip.ExtractAll(TargetDirectory); + } + + + + Dim TargetDirectory As String = "unpack" + Using zip As ZipFile = ZipFile.Read(ZipFileToExtract) + zip.ExtractExistingFile= ExtractExistingFileAction.OverwriteSilently + zip.ExtractAll(TargetDirectory) + End Using + + + + + + + + The path to which the contents of the zipfile will be extracted. + The path can be relative or fully-qualified. + + + + + + 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. + + + + + + This method will extract all entries in the ZipFile to the specified + path. For an extraction that would overwrite an existing file, the behavior + is dictated by , which overrides any + setting you may have made on individual ZipEntry instances. + + + + 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 or one of the similar methods. + + + + Calling this method is equivalent to setting the property and then calling . + + + + This method will send verbose output messages to the + , if it is set on the ZipFile instance. + + + + + This example extracts all the entries in a zip archive file, to the + specified target directory. It does not overwrite any existing files. + + String TargetDirectory= "c:\\unpack"; + using(ZipFile zip= ZipFile.Read(ZipFileToExtract)) + { + zip.ExtractAll(TargetDirectory, ExtractExistingFileAction.DontOverwrite); + } + + + + Dim TargetDirectory As String = "c:\unpack" + Using zip As ZipFile = ZipFile.Read(ZipFileToExtract) + zip.ExtractAll(TargetDirectory, ExtractExistingFileAction.DontOverwrite) + End Using + + + + + The path to which the contents of the zipfile will be extracted. + The path can be relative or fully-qualified. + + + + The action to take if extraction would overwrite an existing file. + + + + + + Reads a zip file archive and returns the instance. + + + + + The stream is read using the default System.Text.Encoding, which is the + IBM437 codepage. + + + + + Thrown if the ZipFile cannot be read. The implementation of this method + relies on System.IO.File.OpenRead, 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. + + + + The name of the zip archive to open. This can be a fully-qualified or relative + pathname. + + + . + + The instance read from the zip archive. + + + + + Reads a zip file archive from the named filesystem file using the + specified options. + + + + + This version of the Read() method allows the caller to pass + in a TextWriter an Encoding, via an instance of the + ReadOptions class. The ZipFile is read in using the + specified encoding for entries where UTF-8 encoding is not + explicitly specified. + + + + + + + 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. + + + + 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. + + + + 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); + } + } + + + + + 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 + + + + + + + + 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 StringWriter. + + + + 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 + + + + 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 + + + + + Thrown if the zipfile cannot be read. The implementation of + this method relies on System.IO.File.OpenRead, 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. + + + + The name of the zip archive to open. + This can be a fully-qualified or relative pathname. + + + + The set of options to use when reading the zip file. + + + The ZipFile instance read from the zip archive. + + + + + + + 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. + + + + The name of the zip archive to open. + This can be a fully-qualified or relative pathname. + + + + An event handler for Read operations. + + + + The System.IO.TextWriter to use for writing verbose status messages + during operations on 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 + TextWriter, such as a System.IO.StringWriter. + + + + The System.Text.Encoding 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. + + + The instance read from the zip archive. + + + + + Reads a zip archive from a stream. + + + + + + When reading from a file, it's probably easier to just use + ZipFile.Read(String, ReadOptions). 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. + + + + Using this overload, the stream is read using the default + System.Text.Encoding, which is the IBM437 + codepage. If you want to specify the encoding to use when + reading the zipfile content, see + ZipFile.Read(Stream, ReadOptions). This + + + + 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 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. + + + + + + + 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. + + + + using (ZipFile zip = ZipFile.Read(InputStream)) + { + zip.Extract("NameOfEntryInArchive.doc", OutputStream); + } + + + + Using zip as ZipFile = ZipFile.Read(InputStream) + zip.Extract("NameOfEntryInArchive.doc", OutputStream) + End Using + + + + the stream containing the zip data. + + The ZipFile instance read from the stream + + + + + Reads a zip file archive from the given stream using the + specified options. + + + + + + When reading from a file, it's probably easier to just use + ZipFile.Read(String, ReadOptions). 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. + + + + 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 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. + + + + the stream containing the zip data. + + + The set of options to use when reading the zip file. + + + + Thrown if the zip archive cannot be read. + + + The ZipFile instance read from the stream. + + + + + + + Reads a zip archive from a stream, using the specified text Encoding, the + specified TextWriter for status messages, + and the specified ReadProgress event handler. + + + + + 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 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. + + + + the stream containing the zip data. + + + The System.IO.TextWriter to which verbose status messages are written + during operations on the ZipFile. 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 null, no verbose messages + are written. + + + + 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 + property for more information. + + + + An event handler for Read operations. + + + an instance of ZipFile + + + + Checks the given file to see if it appears to be a valid zip file. + + + + + Calling this method is equivalent to calling with the testExtract parameter set to false. + + + + The file to check. + true if the file appears to be a zip file. + + + + Checks a file to see if it is a valid zip file. + + + + + This method opens the specified zip file, reads in the zip archive, + verifying the ZIP metadata as it reads. + + + + 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. + + + + If 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. + + + + If 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. + + + + + The zip file to check. + true if the caller wants to extract each entry. + true if the file contains a valid zip file. + + + + Checks a stream to see if it contains a valid zip archive. + + + + + 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 . + + + + 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. + + + + If testExtract 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. + + + + If 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 + ZipFile that has entries which are protected with a password, you will need + to do that manually. + + + + + + The stream to check. + true if the caller wants to extract each entry. + true if the stream contains a valid zip archive. + + + + Delete file with retry on UnauthorizedAccessException. + + + + + 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. + + + + the name of the file to be deleted + + + + Saves the Zip archive to a file, specified by the Name property of the + ZipFile. + + + + + The ZipFile instance is written to storage, typically a zip file + in a filesystem, only when the caller calls Save. 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. + + + + The property is specified either explicitly, + or implicitly using one of the parameterized ZipFile constructors. For + COM Automation clients, the Name property must be set explicitly, + because COM Automation clients cannot call parameterized constructors. + + + + When using a filesystem file for the Zip output, it is possible to call + Save multiple times on the ZipFile instance. With each + call the zip content is re-written to the same output file. + + + + Data for entries that have been added to the ZipFile instance is + written to the output when the Save method is called. This means + that the input streams for those entries must be available at the time + the application calls Save. If, for example, the application + adds entries with AddEntry using a dynamically-allocated + MemoryStream, the memory stream must not have been disposed + before the call to Save. See the 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. + + + + + + + + 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. + + + + Thrown if or 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. + + + + + + Save the file to a new zipfile, with the given name. + + + + + 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. + + + + An application can also save a zip archive in several places by calling this + method multiple times in succession, with different filenames. + + + + The ZipFile instance is written to storage, typically a zip file in a + filesystem, only when the caller calls Save. 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. + + + + + + Thrown if you specify a directory for the filename. + + + + The name of the zip archive to save to. Existing files will + be overwritten with great prejudice. + + + + This example shows how to create and Save a zip file. + + using (ZipFile zip = new ZipFile()) + { + zip.AddDirectory(@"c:\reports\January"); + zip.Save("January.zip"); + } + + + + Using zip As New ZipFile() + zip.AddDirectory("c:\reports\January") + zip.Save("January.zip") + End Using + + + + + + This example shows how to update a zip file. + + using (ZipFile zip = ZipFile.Read("ExistingArchive.zip")) + { + zip.AddFile("NewData.csv"); + zip.Save("UpdatedArchive.zip"); + } + + + + Using zip As ZipFile = ZipFile.Read("ExistingArchive.zip") + zip.AddFile("NewData.csv") + zip.Save("UpdatedArchive.zip") + End Using + + + + + + + Save the zip archive to the specified stream. + + + + + The ZipFile 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 Save. + + + + 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 + Save(Response.OutputStream) to write a zipfile directly to the + output stream, without creating a zip file on the disk on the ASP.NET + server. + + + + Be careful when saving a file to a non-seekable stream, including + Response.OutputStream. 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. + + + + + + + This example saves the zipfile content into a MemoryStream, and + then gets the array of bytes from that MemoryStream. + + + 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(); + } + + + + + + 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: + + + + using (var fs = new FileStream(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!! + } + } + + + + Better like this: + + + + using (var zip = Ionic.Zip.ZipFile.Read(filename)) + { + zip.AddEntry("Name1.txt", "this is the content"); + zip.Save(); // YES! + } + + + + + + The System.IO.Stream to write to. It must be + writable. If you created the ZipFile instance by calling + ZipFile.Read(), this stream must not be the same stream + you passed to ZipFile.Read(). + + + + + Adds to the ZipFile a set of files from the current working directory on + disk, that conform to the specified criteria. + + + + + This method selects files from the the current working directory matching + the specified criteria, and adds them to the ZipFile. + + + + 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." + + + + 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. + + + + 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. + + + + 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). + + + + The value for a size criterion is expressed in integer quantities of bytes, + kilobytes (use k or kb after the number), megabytes (m or mb), or gigabytes + (g or gb). + + + + The value for a name is a pattern to match against the filename, potentially + including wildcards. The pattern follows CMD.exe glob rules: * implies one + or more of any character, 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. + + + + 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 = '* *.*'" . + + + + The value for a type criterion is either F (implying a file) or D (implying + a directory). + + + + Some examples: + + + + + criteria + Files retrieved + + + + name != *.xls + any file with an extension that is not .xls + + + + + name = *.mp3 + any file with a .mp3 extension. + + + + + *.mp3 + (same as above) any file with a .mp3 extension. + + + + + attributes = A + all files whose attributes include the Archive bit. + + + + + attributes != H + all files whose attributes do not include the Hidden bit. + + + + + mtime > 2009-01-01 + all files with a last modified time after January 1st, 2009. + + + + + size > 2gb + all files whose uncompressed size is greater than 2gb. + + + + + type = D + all directories in the filesystem. + + + + + + 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. + + + + 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. + + + + 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. + + + + 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". + + + + 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. + + + + 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. + + + + + This example zips up all *.csv files in the current working directory. + + 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); + } + + + Using zip As ZipFile = New ZipFile() + zip.AddSelectedFiles("*.csv") + zip.Save(PathToZipArchive) + End Using + + + + The criteria for file selection + + + + Adds to the ZipFile a set of files from the disk that conform to the + specified criteria, optionally recursing into subdirectories. + + + + + This method selects files from the the current working directory matching + the specified criteria, and adds them to the ZipFile. If + recurseDirectories 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. + + + + 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 + directoryInArchive. + + + + For details on the syntax for the selectionCriteria parameter, see . + + + + + + + This example zips up all *.xml files in the current working directory, or any + subdirectory, that are larger than 1mb. + + + using (ZipFile zip = new ZipFile()) + { + // Use a compound expression in the selectionCriteria string. + zip.AddSelectedFiles("name = *.xml and size > 1024kb", true); + zip.Save(PathToZipArchive); + } + + + 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 + + + + The criteria for file selection + + + If true, the file selection will recurse into subdirectories. + + + + + Adds to the ZipFile a set of files from a specified directory in the + filesystem, that conform to the specified criteria. + + + + + 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. + + + + 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. + + + + For details on the syntax for the selectionCriteria parameter, see . + + + + + + + This example zips up all *.xml files larger than 1mb in the directory + given by "d:\rawdata". + + + 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); + } + + + + 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 + + + + The criteria for file selection + + + The name of the directory on the disk from which to select files. + + + + + Adds to the ZipFile a set of files from the specified directory on disk, + that conform to the specified criteria. + + + + + + This method selects files from the the specified disk directory matching + the specified selection criteria, and adds them to the ZipFile. If + recurseDirectories is true, files are also selected from + subdirectories. + + + + 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 + directoryInArchive. + + + + For details on the syntax for the selectionCriteria parameter, see . + + + + + + This example zips up all *.csv files in the "files" directory, or any + subdirectory, that have been saved since 2009 February 14th. + + + 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); + } + + + 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 + + + + + This example zips up all files in the current working + directory, and all its child directories, except those in + the excludethis subdirectory. + + Using Zip As ZipFile = New ZipFile(zipfile) + Zip.AddSelectedFfiles("name != 'excludethis\*.*'", datapath, True) + Zip.Save() + End Using + + + + The criteria for file selection + + + The filesystem path from which to select files. + + + + If true, the file selection will recurse into subdirectories. + + + + + 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. + + + + + 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 . + + + + + + + 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". + + + 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); + } + + + Using zip As ZipFile = New ZipFile + zip.AddSelectedFiles("name = *.psd and mtime > 2009-02-14", "photos", "content") + zip.Save(PathToZipArchive) + End Using + + + + + The criteria for selection of files to add to the ZipFile. + + + + The path to the directory in the filesystem from which to select files. + + + + Specifies a directory path to use to in place of the + directoryOnDisk. 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 directoryOnDisk, plus any subdirectory. Passing + the empty string ("") will insert the item at the root path within the + archive. + + + + + 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. + + + + 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 recurseDirectories + 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 directoryOnDisk. For details on the + syntax for the selectionCriteria parameter, see . + + + + + This example zips up all files that are NOT *.pst files, in the current + working directory and any subdirectories. + + + using (ZipFile zip = new ZipFile()) + { + zip.AddSelectedFiles("name != *.pst", SourceDirectory, "backup", true); + zip.Save(PathToZipArchive); + } + + + Using zip As ZipFile = New ZipFile + zip.AddSelectedFiles("name != *.pst", SourceDirectory, "backup", true) + zip.Save(PathToZipArchive) + End Using + + + + + The criteria for selection of files to add to the ZipFile. + + + + The path to the directory in the filesystem from which to select files. + + + + Specifies a directory path to use to in place of the + directoryOnDisk. 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 directoryOnDisk, plus any subdirectory. Passing + the empty string ("") will insert the item at the root path within the + archive. + + + + If true, the method also scans subdirectories for files matching the + criteria. + + + + + Updates the ZipFile with a selection of files from the disk that conform + to the specified criteria. + + + + This method selects files from the specified disk directory that match the + specified selection criteria, and Updates the ZipFile with those + files, using the specified directory path in the archive. If + recurseDirectories 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 + directoryOnDisk. For details on the syntax for the + selectionCriteria parameter, see . + + + + The criteria for selection of files to add to the ZipFile. + + + + The path to the directory in the filesystem from which to select files. + + + + Specifies a directory path to use to in place of the + directoryOnDisk. 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 directoryOnDisk, plus any + subdirectory. Passing the empty string ("") will insert the item at + the root path within the archive. + + + + If true, the method also scans subdirectories for files matching the criteria. + + + + + + + Retrieve entries from the zipfile by specified criteria. + + + + + 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. + + + + For details on the syntax for the selectionCriteria parameter, see . + + + + 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. + + + + + Thrown if selectionCriteria has an invalid syntax. + + + + This example selects all the PhotoShop files from within an archive, and extracts them + to the current working directory. + + using (ZipFile zip1 = ZipFile.Read(ZipFileName)) + { + var PhotoShopFiles = zip1.SelectEntries("*.psd"); + foreach (ZipEntry psd in PhotoShopFiles) + { + psd.Extract(); + } + } + + + 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 + + + the string that specifies which entries to select + a collection of ZipEntry objects that conform to the inclusion spec + + + + Retrieve entries from the zipfile by specified criteria. + + + + + 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. + + + + For details on the syntax for the selectionCriteria parameter, see . + + + + 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. + + + + + Thrown if selectionCriteria has an invalid syntax. + + + + + 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(); + } + } + + + 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 + + + the string that specifies which entries to select + + + the directory in the archive from which to select entries. If null, then + all directories in the archive are used. + + + a collection of ZipEntry objects that conform to the inclusion spec + + + + Remove entries from the zipfile by specified criteria. + + + + + 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. + + + + For details on the syntax for the selectionCriteria parameter, see . + + + + 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. + + + + + Thrown if selectionCriteria has an invalid syntax. + + + + This example removes all entries in a zip file that were modified prior to January 1st, 2008. + + 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(); + } + + + 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 + + + the string that specifies which entries to select + the number of entries removed + + + + Remove entries from the zipfile by specified criteria, and within the specified + path in the archive. + + + + + 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. + + + + For details on the syntax for the selectionCriteria parameter, see . + + + + 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. + + + + + Thrown if selectionCriteria has an invalid syntax. + + + + + 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(); + } + + + 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 + + + + the string that specifies which entries to select + + the directory in the archive from which to select entries. If null, then + all directories in the archive are used. + + the number of entries removed + + + + Selects and Extracts a set of Entries from the ZipFile. + + + + + The entries are extracted into the current working directory. + + + + If any of the files to be extracted already exist, then the action taken is as + specified in the property on the + corresponding ZipEntry instance. By default, the action taken in this case is to + throw an exception. + + + + For information on the syntax of the selectionCriteria string, + see . + + + + + This example shows how extract all XML files modified after 15 January 2009. + + using (ZipFile zip = ZipFile.Read(zipArchiveName)) + { + zip.ExtractSelectedEntries("name = *.xml and mtime > 2009-01-15"); + } + + + the selection criteria for entries to extract. + + + + + + Selects and Extracts a set of Entries from the ZipFile. + + + + + 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 + parameter. + + + + For information on the syntax of the string describing the entry selection criteria, + see . + + + + + This example shows how extract all XML files modified after 15 January 2009, + overwriting any existing files. + + using (ZipFile zip = ZipFile.Read(zipArchiveName)) + { + zip.ExtractSelectedEntries("name = *.xml and mtime > 2009-01-15", + ExtractExistingFileAction.OverwriteSilently); + } + + + + the selection criteria for entries to extract. + + + The action to take if extraction would overwrite an existing file. + + + + + Selects and Extracts a set of Entries from the ZipFile. + + + + + The entries are selected from the specified directory within the archive, and then + extracted into the current working directory. + + + + If any of the files to be extracted already exist, then the action taken is as + specified in the property on the + corresponding ZipEntry instance. By default, the action taken in this case is to + throw an exception. + + + + For information on the syntax of the string describing the entry selection criteria, + see . + + + + + This example shows how extract all XML files modified after 15 January 2009, + and writes them to the "unpack" directory. + + using (ZipFile zip = ZipFile.Read(zipArchiveName)) + { + zip.ExtractSelectedEntries("name = *.xml and mtime > 2009-01-15","unpack"); + } + + + + the selection criteria for entries to extract. + + + the directory in the archive from which to select entries. If null, then + all directories in the archive are used. + + + + + + + Selects and Extracts a set of Entries from the ZipFile. + + + + + The entries are extracted into the specified directory. If any of the files to be + extracted already exist, an exception will be thrown. + + + For information on the syntax of the string describing the entry selection criteria, + see . + + + + the selection criteria for entries to extract. + + + the directory in the archive from which to select entries. If null, then + all directories in the archive are used. + + + + the directory on the disk into which to extract. It will be created + if it does not exist. + + + + + Selects and Extracts a set of Entries from the ZipFile. + + + + + 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 + parameter. + + + + For information on the syntax of the string describing the entry selection criteria, + see . + + + + + 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. + + using (ZipFile zip = ZipFile.Read(zipArchiveName)) + { + zip.ExtractSelectedEntries("name = *.xml or size > 100000", + null, + "unpack", + ExtractExistingFileAction.DontOverwrite); + } + + + + the selection criteria for entries to extract. + + + The directory on the disk into which to extract. It will be created if it does not exist. + + + + The directory in the archive from which to select entries. If null, then + all directories in the archive are used. + + + + The action to take if extraction would overwrite an existing file. + + + + + + + + Static constructor for ZipFile + + + Code Pages 437 and 1252 for English are same + Code Page 1252 Windows Latin 1 (ANSI) - + Code Page 437 MS-DOS Latin US - + + + + + The default text encoding used in zip archives. It is numeric 437, also + known as IBM437. + + + + + + Generic IEnumerator support, for use of a ZipFile in an enumeration. + + + + You probably do not want to call GetEnumerator explicitly. Instead + it is implicitly called when you use a loop in C#, or a + For Each loop in VB.NET. + + + + 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. + + 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(); + } + } + + + + 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 + + + + A generic enumerator suitable for use within a foreach loop. + + + + An IEnumerator, for use of a ZipFile in a foreach construct. + + + + 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 For Each + statement. In Javascript, this is done with new Enumerator(zipfile). + + + + The IEnumerator over the entries in the ZipFile. + + + + + 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. + + + + + A wrapper for ZipFile.IsZipFile(string) + + The filename to of the zip file to check. + true if the file contains a valid zip file. + + + + A wrapper for ZipFile.IsZipFile(string, bool) + + + We cannot use "overloaded" Method names in COM interop. + So, here, we use a unique name. + + The filename to of the zip file to check. + true if the file contains a valid zip file. + + + + A wrapper for ZipFile.CheckZip(string) + + The filename to of the zip file to check. + + true if the named zip file checks OK. Otherwise, false. + + + + A COM-friendly wrapper for the static method . + + + The filename to of the zip file to check. + + The password to check. + + true if the named zip file checks OK. Otherwise, false. + + + + A wrapper for ZipFile.FixZipDirectory(string) + + The filename to of the zip file to fix. + + + + A wrapper for ZipFile.LibraryVersion + + + the version number on the DotNetZip assembly, formatted as a string. + + + + + An enum that provides the various encryption algorithms supported by this + library. + + + + + + PkzipWeak implies the use of Zip 2.0 encryption, which is known to be + weak and subvertible. + + + + A note on interoperability: Values of PkzipWeak and None are + specified in PKWARE's zip + specification, 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. + + + + Values of WinZipAes128 and WinZipAes256 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). + + + + 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. + + + + In case you care: According to the WinZip specification, the + actual AES key used is derived from the via an + algorithm that complies with RFC 2898, using an iteration + count of 1000. The algorithm is sometimes referred to as PBKDF2, which stands + for "Password Based Key Derivation Function #2". + + + + 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 this + article. + + + + + + + No encryption at all. + + + + + Traditional or Classic pkzip encryption. + + + + + WinZip AES encryption (128 key bits). + + + + + WinZip AES encryption (256 key bits). + + + + + An encryption algorithm that is not supported by DotNetZip. + + + + + Delegate in which the application writes the ZipEntry content for the named entry. + + + The name of the entry that must be written. + The stream to which the entry data should be written. + + + When you add an entry and specify a WriteDelegate, via , the application + code provides the logic that writes the entry data directly into the zip file. + + + + + 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. + + + 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); + } + } + + + + 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 + + + + + + + Delegate in which the application opens the stream, just-in-time, for the named entry. + + + + The name of the ZipEntry that the application should open the stream for. + + + + When you add an entry via , the application code provides the logic that + opens and closes the stream for the given ZipEntry. + + + + + + + Delegate in which the application closes the stream, just-in-time, for the named entry. + + + + The name of the ZipEntry that the application should close the stream for. + + + The stream to be closed. + + + When you add an entry via , the application code provides the logic that + opens and closes the stream for the given ZipEntry. + + + + + + + Delegate for the callback by which the application tells the + library the CompressionLevel to use for a file. + + + + + Using this callback, the application can, for example, specify that + previously-compressed files (.mp3, .png, .docx, etc) should use a + CompressionLevel of None, or can set the compression level based + on any other factor. + + + + + + + In an EventArgs type, indicates which sort of progress event is being + reported. + + + 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. + + + + + Indicates that a Add() operation has started. + + + + + Indicates that an individual entry in the archive has been added. + + + + + Indicates that a Add() operation has completed. + + + + + Indicates that a Read() operation has started. + + + + + Indicates that an individual entry in the archive is about to be read. + + + + + Indicates that an individual entry in the archive has just been read. + + + + + Indicates that a Read() operation has completed. + + + + + The given event reports the number of bytes read so far + during a Read() operation. + + + + + Indicates that a Save() operation has started. + + + + + Indicates that an individual entry in the archive is about to be written. + + + + + Indicates that an individual entry in the archive has just been saved. + + + + + Indicates that a Save() operation has completed. + + + + + Indicates that the zip archive has been created in a + temporary location during a Save() operation. + + + + + Indicates that the temporary file is about to be renamed to the final archive + name during a Save() operation. + + + + + Indicates that the temporary file is has just been renamed to the final archive + name during a Save() operation. + + + + + Indicates that the self-extracting archive has been compiled + during a Save() operation. + + + + + The given event is reporting the number of source bytes that have run through the compressor so far + during a Save() operation. + + + + + Indicates that an entry is about to be extracted. + + + + + Indicates that an entry has just been extracted. + + + + + Indicates that extraction of an entry would overwrite an existing + filesystem file. You must use + + ExtractExistingFileAction.InvokeExtractProgressEvent in the call + to ZipEntry.Extract() in order to receive this event. + + + + + The given event is reporting the number of bytes written so far for + the current entry during an Extract() operation. + + + + + Indicates that an ExtractAll operation is about to begin. + + + + + Indicates that an ExtractAll operation has completed. + + + + + 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. + + + + + 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. + + + + + The total number of entries to be saved or extracted. + + + + + The name of the last entry saved or extracted. + + + + + In an event handler, set this to cancel the save or extract + operation that is in progress. + + + + + The type of event being reported. + + + + + Returns the archive name associated to this event. + + + + + The number of bytes read or written so far for this entry. + + + + + Total number of bytes that will be read or written for this entry. + This number will be -1 if the value cannot be determined. + + + + + Provides information about the progress of a Read operation. + + + + + Provides information about the progress of a Add operation. + + + + + Provides information about the progress of a save operation. + + + + + Constructor for the SaveProgressEventArgs. + + the name of the zip archive. + whether this is before saving the entry, or after + The total number of entries in the zip archive. + Number of entries that have been saved. + The entry involved in the event. + + + + Number of entries saved so far. + + + + + Provides information about the progress of the extract operation. + + + + + Constructor for the ExtractProgressEventArgs. + + the name of the zip archive. + whether this is before saving the entry, or after + The total number of entries in the zip archive. + Number of entries that have been extracted. + The entry involved in the event. + The location to which entries are extracted. + + + + 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(). + + + + + Returns the extraction target location, a filesystem path. + + + + + Provides information about the an error that occurred while zipping. + + + + + Returns the exception that occurred, if any. + + + + + Returns the name of the file that caused the exception, if any. + + + + + Issued when an ZipEntry.ExtractWithPassword() method is invoked + with an incorrect password. + + + + + Default ctor. + + + + + Come on, you know how exceptions work. Why are you looking at this documentation? + + The message in the exception. + + + + Come on, you know how exceptions work. Why are you looking at this documentation? + + The message in the exception. + The innerException for this exception. + + + + Come on, you know how exceptions work. Why are you looking at this documentation? + + The serialization info for the exception. + The streaming context from which to deserialize. + + + + Indicates that a read was attempted on a stream, and bad or incomplete data was + received. + + + + + Default ctor. + + + + + Come on, you know how exceptions work. Why are you looking at this documentation? + + The message in the exception. + + + + Come on, you know how exceptions work. Why are you looking at this documentation? + + The message in the exception. + The innerException for this exception. + + + + Come on, you know how exceptions work. Why are you looking at this documentation? + + The serialization info for the exception. + The streaming context from which to deserialize. + + + + Issued when an CRC check fails upon extracting an entry from a zip archive. + + + + + Default ctor. + + + + + Come on, you know how exceptions work. Why are you looking at this documentation? + + The message in the exception. + + + + Come on, you know how exceptions work. Why are you looking at this documentation? + + The serialization info for the exception. + The streaming context from which to deserialize. + + + + Issued when errors occur saving a self-extracting archive. + + + + + Default ctor. + + + + + Come on, you know how exceptions work. Why are you looking at this documentation? + + The message in the exception. + + + + Come on, you know how exceptions work. Why are you looking at this documentation? + + The serialization info for the exception. + The streaming context from which to deserialize. + + + + Indicates that an operation was attempted on a ZipFile which was not possible + given the state of the instance. For example, if you call Save() on a ZipFile + which has no filename set, you can get this exception. + + + + + Default ctor. + + + + + Come on, you know how exceptions work. Why are you looking at this documentation? + + The message in the exception. + + + + Come on, you know how exceptions work. Why are you looking at this documentation? + + The message in the exception. + The innerException for this exception. + + + + Come on, you know how exceptions work. Why are you looking at this documentation? + + The serialization info for the exception. + The streaming context from which to deserialize. + + + + Base class for all exceptions defined by and throw by the Zip library. + + + + + Default ctor. + + + + + Come on, you know how exceptions work. Why are you looking at this documentation? + + The message in the exception. + + + + Come on, you know how exceptions work. Why are you looking at this documentation? + + The message in the exception. + The innerException for this exception. + + + + Come on, you know how exceptions work. Why are you looking at this documentation? + + The serialization info for the exception. + The streaming context from which to deserialize. + + + + An enum for the options when extracting an entry would overwrite an existing file. + + + + + This enum describes the actions that the library can take when an + Extract() or ExtractWithPassword() method is called to extract an + entry to a filesystem, and the extraction would overwrite an existing filesystem + file. + + + + + + + Throw an exception when extraction would overwrite an existing file. (For + COM clients, this is a 0 (zero).) + + + + + 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.) + + + + + When extraction would overwrite an existing file, don't overwrite the file, silently. + (For COM clients, this is a 2.) + + + + + When extraction would overwrite an existing file, invoke the ExtractProgress + event, using an event type of . 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 property before making + the decision. If, after your processing in the Extract progress event, you + want to NOT extract the file, set + on the ZipProgressEventArgs.CurrentEntry to DoNotOverwrite. + If you do want to extract the file, set ZipEntry.ExtractExistingFile + to OverwriteSilently. If you want to cancel the Extraction, set + ZipProgressEventArgs.Cancel 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.) + + + + + Collects general purpose utility methods. + + + + private null constructor + + + + 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. + + source path. + transformed path + + + + Sanitize paths in zip files. This means making sure that relative paths in a zip file don't go outside + the top directory. Entries like something/../../../../Temp/evil.txt get sanitized to Temp/evil.txt + when extracting + + A path with forward slashes as directory separator + sanitized path + + + + 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. + + + + + Scans through 64k at a time. + + + + 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. + + + + The stream to search + The 4-byte signature to find + The number of bytes read + + + + Create a pseudo-random filename, suitable for use as a temporary + file, and open it. + + + + This method produces a filename of the form + DotNetZip-xxxxxxxx.tmp, where xxxxxxxx is replaced by randomly + chosen characters, and creates that file. + + + + + + Workitem 7889: handle ERROR_LOCK_VIOLATION during read + + + This could be gracefully handled with an extension attribute, but + This assembly used to be built for .NET 2.0, so could not use + extension methods. + + + + + A decorator stream. It wraps another stream, and performs bookkeeping + to keep track of the stream Position. + + + + In some cases, it is not possible to get the Position of a stream, let's + say, on a write-only output stream like ASP.NET's + Response.OutputStream, 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. + + + Consider the scenario of an application that saves a self-extracting + archive (SFX), that uses a custom SFX stub. + + + Saving to a filesystem file, the application would open the + filesystem file (getting a FileStream), save the custom sfx stub + into it, and then call ZipFile.Save(), specifying the same + FileStream. ZipFile.Save() does the right thing for the zipentry + offsets, by inquiring the Position of the FileStream before writing + any data, and then adding that initial offset into any ZipEntry + offsets in the zip directory. Everything works fine. + + + Now suppose the application is an ASPNET application and it saves + directly to Response.OutputStream. It's not possible for DotNetZip to + inquire the Position, so the offsets for the SFX will be wrong. + + + The workaround is for the application to use this class to wrap + HttpResponse.OutputStream, then write the SFX stub and the ZipFile + into that wrapper stream. Because ZipFile.Save() can inquire the + Position, it will then do the right thing with the offsets. + + + + + + The constructor. + + The underlying stream + + + + Gets the wrapped stream. + + + + + The count of bytes written out to the stream. + + + + + the count of bytes that have been read from the stream. + + + + + Adjust the byte count on the stream. + + + + the number of bytes to subtract from the count. + + + + + 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. + + + + + + The read method. + + The buffer to hold the data read from the stream. + the offset within the buffer to copy the first byte read. + the number of bytes to read. + the number of bytes read, after decryption and decompression. + + + + Write data into the stream. + + The buffer holding data to write to the stream. + the offset within that data array to find the first byte to write. + the number of bytes to write. + + + + Whether the stream can be read. + + + + + Whether it is possible to call Seek() on the stream. + + + + + Whether it is possible to call Write() on the stream. + + + + + Flushes the underlying stream. + + + + + The length of the underlying stream. + + + + + Returns the sum of number of bytes written, plus the initial + offset before writing. + + + + + The Position of the stream. + + + + + Seek in the stream. + + the offset point to seek to + the reference point from which to seek + The new position + + + + Set the length of the underlying stream. Be careful with this! + + + the length to set on the underlying stream. + + + + This is a helper class supporting WinZip AES encryption. + This class is intended for use only by the DotNetZip library. + + + + 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. + + + + + 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. + + + + 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 + + + + + + + The constructor. + + The underlying stream + To either encrypt or decrypt. + The pre-initialized WinZipAesCrypto object. + The maximum number of bytes to read from the stream. + + + + Returns the final HMAC-SHA1-80 for the data that was encrypted. + + + + + Close the stream. + + + + + Returns true if the stream can be read. + + + + + Always returns false. + + + + + Returns true if the CryptoMode is Encrypt. + + + + + Flush the content in the stream. + + + + + Getting this property throws a NotImplementedException. + + + + + Getting or Setting this property throws a NotImplementedException. + + + + + This method throws a NotImplementedException. + + + + + This method throws a NotImplementedException. + + + + + 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. + + + + 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. + + + + + The default constructor for ZipCrypto. + + + + 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. + + + + + + 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 + + + + + Call this method on a cipher text to render the plaintext. You must + first initialize the cipher with a call to InitCipher. + + + + + 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); + + + + The encrypted buffer. + + The number of bytes to encrypt. + Should be less than or equal to CipherText.Length. + + + The plaintext. + + + + This is the converse of DecryptMessage. It encrypts the plaintext + and produces a ciphertext. + + + The plain text buffer. + + + The number of bytes to encrypt. + Should be less than or equal to plainText.Length. + + + The ciphertext. + + + + This initializes the cipher with the given password. + See AppNote.txt for details. + + + + The passphrase for encrypting or decrypting with this cipher. + + + + + 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. + + + + + After the keys are initialized, then you can use the cipher to + encrypt the plaintext. + + + + Essentially we encrypt the password with the keys, then discard the + ciphertext for the password. This initializes the keys for later use. + + + + + + + A Stream for reading and concurrently decrypting data from a zip file, + or for writing and concurrently encrypting data to a zip file. + + + + The constructor. + The underlying stream + To either encrypt or decrypt. + The pre-initialized ZipCrypto object. + + + + 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. + + + + + True if the referenced entry is a directory. + + + + + Provides a human-readable string with information about the ZipEntry. + + + + + Reads one entry from the zip directory structure in the zip file. + + + + 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. + + + + a list of previously seen entry names; used to prevent duplicates. + + + the entry read from the archive. + + + + Returns true if the passed-in value is a valid signature for a ZipDirEntry. + + the candidate 4-byte signature value. + true, if the signature is valid according to the PKWare spec. + + + + Default constructor. + + + Applications should never need to call this directly. It is exposed to + support COM Automation environments. + + + + + The time and date at which the file indicated by the ZipEntry was + last modified. + + + + + 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 System.DateTime.Now for this + value, for the given entry. + + + + This property allows the application to retrieve and possibly set the + LastModified value on an entry, to an arbitrary value. values with a + setting of DateTimeKind.Unspecified are taken to be expressed as + DateTimeKind.Local. + + + + Be aware that because of the way PKWare's + Zip specification describes how times are stored in the zip file, + the full precision of the System.DateTime 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. + + + + The actual last modified time of a file can be stored in multiple ways in + the zip file, and they are not mutually exclusive: + + + + + 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 LastModified property. This value is always + present in the metadata for each zip entry. In some cases the value is + invalid, or zero. + + + + 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 ModifiedTime property. + + + + In the "Unix" format, a 4-byte quantity specifying the number of seconds since + January 1, 1970 UTC. + + + + 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. + + + + + + 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. + + + + When reading ZIP files, the DotNetZip library reads the Windows-formatted + time, if it is stored in the entry, and sets both LastModified and + ModifiedTime 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 .) + + + + The last modified time of the file created upon a call to + ZipEntry.Extract() 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 provides + some good context. + + + + 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. + + + + 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. + + + + 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. + + + + .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. + + + + 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. + + + + 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. + + + + + + + + Ability to set Last Modified DOS time to zero + (for using with EmitTimesInWindowsFormatWhenSaving+EmitTimesInUnixFormatWhenSaving setted to false) + some flasher hardware use as marker of first binary + + + + + Last Modified time for the file represented by the entry. + + + + + + This value corresponds to the "last modified" time in the NTFS file times + as described in the Zip + specification. When getting this property, the value may be + different from . When setting the property, + the property also gets set, but with a lower + precision. + + + + 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, who is ever going to need better + resolution than THAT? And so ZIP files, regardless of the platform on + which the zip file was created, store file times in exactly the same format that DOS used + in 1989. + + + + 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. + + + + 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 + last write, last access, and file creation + 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 formatted in the zip file + 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. + + + + 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. + + + + 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 + ModifiedTime, AccessedTime and CreationTime + properties on the ZipEntry. + + + + 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 + , is guaranteed to be present, though it + sometimes unset. + + + + Ok, getting back to the question about how the LastModified + property relates to this ModifiedTime + property... LastModified is always set, while + ModifiedTime is not. (The other times stored in the NTFS + times extension, CreationTime and AccessedTime also + may not be set on an entry that is read from an existing zip file.) + When reading a zip file, then LastModified 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 DateTime.Now for the + LastModified 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 LastModified and ModifiedTime 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 ModifiedTime + remains unset (likewise AccessedTime and CreationTime), + and LastModified keeps its DOS time. + + + + When creating zip files with this library, by default the extended time + properties (ModifiedTime, AccessedTime, and + CreationTime) 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 DateTime.Now. In + this case LastModified and ModifiedTime will be identical, + to 2 seconds of precision. You can explicitly set the + CreationTime, AccessedTime, and ModifiedTime of an + entry using the property setters. If you want to set all of those + quantities, it's more efficient to use the method. Those + changes are not made permanent in the zip file until you call or one of its cousins. + + + + 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 and + 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. + + + + 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, maybe you + should donate? + + + + + + + + + + + Last Access time for the file represented by the entry. + + + This value may or may not be meaningful. If the ZipEntry was read from an existing + Zip archive, this information may not be available. For an explanation of why, see + . + + + + + + + + The file creation time for the file represented by the entry. + + + + This value may or may not be meaningful. If the ZipEntry 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 . + + + + + + + + Sets the NTFS Creation, Access, and Modified times for the given entry. + + + + + 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. + + + + The values you set here will be retrievable with the , and properties. + + + + When this method is called, if both and are false, then the + EmitTimesInWindowsFormatWhenSaving flag is automatically set. + + + + DateTime values provided here without a DateTimeKind are assumed to be Local Time. + + + + the creation time of the entry. + the last access time of the entry. + the last modified time of the entry. + + + + + + + + + + Specifies whether the Creation, Access, and Modified times for the given + entry will be emitted in "Windows format" when the zip archive is saved. + + + + + 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 true. + + + + 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, all three values are implicitly set to DateTime.Now. Applications + can also explicitly set those times by calling . + + + + PKWARE's + zip specification 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. + + + + 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 Infozip + 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. + + + + The times stored are taken from , , and . + + + + This property is not mutually exclusive from the 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. + + + + Normally you will use the ZipFile.EmitTimesInWindowsFormatWhenSaving + property, to specify the behavior for all entries in a zip, rather than + the property on each individual entry. + + + + + + + + + + + + + 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. + + + + + 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 + false, meaning the Unix-format times are not stored in the zip + archive. + + + + 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, all three values are implicitly set to DateTime.Now. Applications + can also explicitly set those times by calling . + + + + PKWARE's + zip specification 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. + + + + 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 Infozip + 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. + + + + The times stored are taken from , , and . + + + + This property is not mutually exclusive from the 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. + + + + Normally you will use the ZipFile.EmitTimesInUnixFormatWhenSaving + property, to specify the behavior for all entries, rather than the + property on each individual entry. + + + + + + + + + + + + + The type of timestamp attached to the ZipEntry. + + + + 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. + + + + + + + + The file attributes for the entry. + + + + + + The attributes in NTFS include + ReadOnly, Archive, Hidden, System, and Indexed. When adding a + ZipEntry 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 ZipFile, you can set the attributes + explicitly if you like. + + + + When reading a ZipEntry from a ZipFile, the attributes are + set according to the data stored in the ZipFile. If you extract the + entry from the archive to a filesystem file, DotNetZip will set the + attributes on the resulting file accordingly. + + + + The attributes can be set explicitly by the application. For example the + application may wish to set the FileAttributes.ReadOnly 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 Save() method on the ZipFile + instance that contains the ZipEntry. + + + + 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 ZipFile. + + + + 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. + + + + + + + The name of the filesystem file, referred to by the ZipEntry. + + + + + This property specifies the thing-to-be-zipped on disk, and is set only + when the ZipEntry is being created from a filesystem file. If the + ZipFile is instantiated by reading an existing .zip archive, then + the LocalFileName will be null (Nothing in VB). + + + + When it is set, the value of this property may be different than , which is the path used in the archive itself. If you + call Zip.AddFile("foop.txt", AlternativeDirectory), then the path + used for the ZipEntry within the zip archive will be different + than this path. + + + + If the entry is being added from a stream, then this is null (Nothing in VB). + + + + + + + + The name of the file contained in the ZipEntry. + + + + + + This is the name of the entry in the ZipFile itself. When creating + a zip archive, if the ZipEntry has been created from a filesystem + file, via a call to or , or a related overload, the value + of this property is derived from the name of that file. The + FileName property does not include drive letters, and may include a + different directory path, depending on the value of the + directoryPathInArchive parameter used when adding the entry into + the ZipFile. + + + + In some cases there is no related filesystem file - for example when a + ZipEntry is created using 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. + + + + 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. + + + + 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 the Zip + specification, for compatibility with Unix(tm) and ... get + this.... Amiga! + + + + If an application reads a ZipFile via or a related overload, and then explicitly + sets the FileName on an entry contained within the ZipFile, and + then calls , the application will effectively + rename the entry within the zip archive. + + + + If an application sets the value of FileName, then calls + Extract() on the entry, the entry is extracted to a file using the + newly set value as the filename. The FileName value is made + permanent in the zip archive only after a call to one of the + ZipFile.Save() methods on the ZipFile that contains the + ZipEntry. + + + + If an application attempts to set the FileName to a value that + would result in a duplicate entry in the ZipFile, an exception is + thrown. + + + + When a ZipEntry is contained within a ZipFile, applications + cannot rename the entry within the context of a foreach (For + Each in VB) loop, because of the way the ZipFile stores + entries. If you need to enumerate through all the entries and rename one + or more of them, use ZipFile.EntriesSorted as the + collection. See also, ZipFile.GetEnumerator(). + + + + + + + The stream that provides content for the ZipEntry. + + + + + + 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 ZipFile comprised of content obtained from hundreds of + files, via calls to AddFile(). 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 ZipFile.Save() call. Only + one input stream is opened at a time, as each entry is being written out. + + + + Now imagine a different application that creates a ZipFile + with content obtained from hundreds of streams, added through . 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. + + + + To avoid this, call and specify delegates that open and close the stream at + the time of Save. + + + + + Setting the value of this property when the entry was not added from a + stream (for example, when the ZipEntry was added with or , or when the entry was added by + reading an existing zip archive) will throw an exception. + + + + + + + + A flag indicating whether the InputStream was provided Just-in-time. + + + + + + When creating a zip archive, an application can obtain content for one or + more of the ZipEntry instances from streams, using the 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 ZipFile.Save() methods is called and + the data for the various entries are being compressed and written out. + + + + In this case, the application can set the + property, typically within the SaveProgress event (event type: ) for that entry. + + + + The application will later want to call Close() and Dispose() on that + stream. In the SaveProgress event, when the event type is , 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. + + + + + + + + An enum indicating the source of the ZipEntry. + + + + + The version of the zip engine needed to read the ZipEntry. + + + + + This is a readonly property, indicating the version of the Zip + specification 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. + + + + + value + Features + + + + 20 + a basic Zip Entry, potentially using PKZIP encryption. + + + + + 45 + The ZIP64 extension is used on the entry. + + + + + 46 + File is compressed using BZIP2 compression* + + + + 50 + File is encrypted using PkWare's DES, 3DES, (broken) RC2 or RC4 + + + + 51 + File is encrypted using PKWare's AES encryption or corrected RC2 encryption. + + + + 52 + File is encrypted using corrected RC2-64 encryption** + + + + 61 + File is encrypted using non-OAEP key wrapping*** + + + + 63 + File is compressed using LZMA, PPMd+, Blowfish, or Twofish + + + + + + 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. + + + + This value is set upon reading an existing zip file, or after saving a zip + archive. + + + + + + The comment attached to the ZipEntry. + + + + + 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. + + + + By default, the Comment is encoded in IBM437 code page. You can + specify an alternative with and + . + + + + + + + + Indicates whether the entry requires ZIP64 extensions. + + + + + + This property is null (Nothing in VB) until a Save() method on the + containing instance has been called. The property is + non-null (HasValue is true) only after a Save() method has + been called. + + + + After the containing ZipFile 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 Save() is attempted on the zip archive and + the compression is applied. + + + + If none of the three conditions holds, then the Value is false. + + + + A Value of false does not indicate that the entry, as saved in the + zip archive, does not use ZIP64. It merely indicates that ZIP64 is + not required. An entry may use ZIP64 even when not required if + the property on the containing + ZipFile instance is set to , or if + the property on the containing + ZipFile instance is set to + and the output stream was not seekable. + + + + + + + + Indicates whether the entry actually used ZIP64 extensions, as it was most + recently written to the output file or stream. + + + + + + This Nullable property is null (Nothing in VB) until a Save() + method on the containing instance has been + called. HasValue is true only after a Save() method has been + called. + + + + The value of this property for a particular ZipEntry may change + over successive calls to Save() methods on the containing ZipFile, + even if the file that corresponds to the ZipEntry does not. This + may happen if other entries contained in the ZipFile expand, + causing the offset for this particular entry to exceed 0xFFFFFFFF. + + + + + + + The bitfield for the entry as defined in the zip spec. You probably + never need to look at this. + + + + + You probably do not need to concern yourself with the contents of this + property, but in case you do: + + + + + bit + meaning + + + + 0 + set if encryption is used. + + + + 1-2 + + 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. + + + + + 3 + + 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. + + + + + + 4 + reserved for "enhanced deflating". This library doesn't do enhanced deflating. + + + + 5 + set to indicate the zip is compressed patched data. This library doesn't do that. + + + + 6 + + 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. + + + + 7 + not used + + + + 8 + not used + + + + 9 + not used + + + + 10 + not used + + + + 11 + + 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. + + + + + 12 + Reserved by PKWARE for enhanced compression. + + + + 13 + + 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 the Zip + specification describing the Strong Encryption Specification for + details. + + + + + 14 + Reserved by PKWARE. + + + + 15 + Reserved by PKWARE. + + + + + + + + + The compression method employed for this ZipEntry. + + + + + + The + Zip specification allows a variety of compression methods. This + library supports just two: 0x08 = Deflate. 0x00 = Store (no compression), + for reading or writing. + + + + 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. + + + + You may wish to set CompressionMethod to CompressionMethod.None (0) + when zipping already-compressed data like a jpg, png, or mp3 file. + This can save time and cpu cycles. + + + + When setting this property on a ZipEntry that is read from an + existing zip file, calling ZipFile.Save() will cause the new + CompressionMethod to be used on the entry in the newly saved zip file. + + + + Setting this property may have the side effect of modifying the + CompressionLevel property. If you set the CompressionMethod to a + value other than None, and CompressionLevel is previously + set to None, then CompressionLevel will be set to + Default. + + + + + + + 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. + + 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(); + } + + + + 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 + + + + + + Sets the compression level to be used for the entry when saving the zip + archive. This applies only for CompressionMethod = DEFLATE. + + + + + 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. + + + + 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 BestCompression 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. + + + + When setting this property on a ZipEntry that is read from an + existing zip file, calling ZipFile.Save() will cause the new + CompressionLevel to be used on the entry in the newly saved zip file. + + + + Setting this property may have the side effect of modifying the + CompressionMethod property. If you set the CompressionLevel + to a value other than None, CompressionMethod will be set + to Deflate, if it was previously None. + + + + Setting this property has no effect if the CompressionMethod is something + other than Deflate or None. + + + + + + + + The compressed size of the file, in bytes, within the zip archive. + + + + When reading a ZipFile, this value is read in from the existing + zip file. When creating or updating a ZipFile, the compressed + size is computed during compression. Therefore the value on a + ZipEntry is valid after a call to Save() (or one of its + overloads) in that case. + + + + + + + The size of the file, in bytes, before compression, or after extraction. + + + + When reading a ZipFile, this value is read in from the existing + zip file. When creating or updating a ZipFile, the uncompressed + size is computed during compression. Therefore the value on a + ZipEntry is valid after a call to Save() (or one of its + overloads) in that case. + + + + + + + The ratio of compressed size to uncompressed size of the ZipEntry. + + + + + 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. + + + + You could format it for presentation to a user via a format string of + "{3,5:F0}%" to see it as a percentage. + + + + If the size of the original uncompressed file is 0, implying a + denominator of 0, the return value will be zero. + + + + This property is valid after reading in an existing zip file, or after + saving the ZipFile that contains the ZipEntry. You cannot know the + effect of a compression transform until you try it. + + + + + + + The 32-bit CRC (Cyclic Redundancy Check) on the contents of the ZipEntry. + + + + + You probably don't need to concern yourself with this. It is used + internally by DotNetZip to verify files or streams upon extraction. + + The value is a 32-bit + CRC 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 + Save() on the containing ZipFile. When reading an existing zip file, the value + of this property reflects the stored CRC for the entry. + + + + + + True if the entry is a directory (not a file). + This is a readonly property on the entry. + + + + + A derived property that is true if the entry uses encryption. + + + + + This is a readonly property on the entry. When reading a zip file, + the value for the ZipEntry is determined by the data read + from the zip file. After saving a ZipFile, the value of this + property for each ZipEntry indicates whether encryption was + actually used (which will have been true if the was set and the property + was something other than . + + + + + + Set this to specify which encryption algorithm to use for the entry when + saving it to a zip archive. + + + + + + Set this property in order to encrypt the entry when the ZipFile is + saved. When setting this property, you must also set a on the entry. If you set a value other than on this property and do not set a + Password then the entry will not be encrypted. The ZipEntry + data is encrypted as the ZipFile is saved, when you call or one of its cousins on the containing + ZipFile instance. You do not need to specify the Encryption + when extracting entries from an archive. + + + + 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 a + subset 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. + + + + 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 specified + by PKWare, 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. + + + + The class also has a property. In most cases you will use + that property when setting encryption. This property takes + precedence over any Encryption set on the ZipFile 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. + + + + Some comments on updating archives: If you read a ZipFile, 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 + ZipFile. 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 Encryption to PkzipWeak, then at + the time of Save(), the original entry is read and decompressed, + then re-compressed and encrypted. Conversely, if the original entry is + encrypted with PkzipWeak encryption, and the application sets the + Encryption property to WinZipAes128, then at the time of + Save(), 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. + + + + 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 Encryption to None, then call Save(). Then set the + Encryption to the new value (not "None"), then call Save() + once again. + + + + The WinZip AES encryption algorithms are not supported on the .NET Compact + Framework. + + + + + + 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. + + + // 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"); + } + + + + ' 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 + + + + + + Thrown in the setter if EncryptionAlgorithm.Unsupported is specified. + + + ZipEntry.Password + ZipFile.Encryption + + + + The Password to be used when encrypting a ZipEntry upon + ZipFile.Save(), or when decrypting an entry upon Extract(). + + + + + 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. + + + + The password set here is implicitly used to encrypt the entry during the + operation, or to decrypt during the or operation. If you set + the Password on a ZipEntry after calling Save(), there is no + effect. + + + + Consider setting the 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, AES + Encryption uses a standard, strong, tested, encryption + algorithm. DotNetZip can create zip archives that use WinZip-compatible + AES encryption, if you set the 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." + + + + The class also has a + 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. + + + + Some comments on updating archives: If you read a ZipFile, 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 , and then adding a new + entry with a new Password. + + + + For example, suppose you read a ZipFile, and there is an encrypted + entry. Setting the Password property on that ZipEntry and then + calling Save() on the ZipFile does not update the password + on that entry in the archive. Neither is an exception thrown. Instead, + what happens during the Save() 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. + + + + If you read a ZipFile, and there is an un-encrypted entry, you can set the + Password on the entry and then call Save() on the ZipFile, and get + encryption on that entry. + + + + + + + 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. + + + // 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"); + } + + + + + 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 + + + + + + + ZipFile.Password + + + + The action the library should take when extracting a file that already exists. + + + + + This property affects the behavior of the Extract methods (one of the + Extract() or ExtractWithPassword() 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. + + + + This property has no effect when extracting to a stream, or when the file to be + extracted does not already exist. + + + + + + + This example shows how to set the ExtractExistingFile property in + an ExtractProgress event, in response to user input. The + ExtractProgress event is invoked if and only if the + ExtractExistingFile property was previously set to + ExtractExistingFileAction.InvokeExtractProgressEvent. + + 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; + } + } + + + + + + The action to take when an error is encountered while + opening or reading files as they are saved into a zip archive. + + + + + Errors can occur within a call to ZipFile.Save, as the various files contained + in a ZipFile are being saved into the zip archive. During the + Save, DotNetZip will perform a File.Open 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. + + + + Typically you will NOT set this property on individual ZipEntry + instances. Instead, you will set the ZipFile.ZipErrorAction property on + the ZipFile instance, before adding any entries to the + ZipFile. If you do this, errors encountered on behalf of any of + the entries in the ZipFile will be handled the same way. + + + + But, if you use a handler, you will want + to set this property on the ZipEntry within the handler, to + communicate back to DotNetZip what you would like to do with the + particular error. + + + + + + + + + Indicates whether the entry was included in the most recent save. + + + An entry can be excluded or skipped from a save if there is an error + opening or reading the entry. + + + + + + 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. + + + + + See + + + + + + Set to indicate whether to use UTF-8 encoding for filenames and comments. + + + + + + If this flag is set, the comment and filename for the entry will be + encoded with UTF-8, as described in the Zip + specification, if necessary. "Necessary" means, the filename or + entry comment (if any) cannot be reflexively encoded and decoded using the + default code page, IBM437. + + + + Setting this flag to true is equivalent to setting to System.Text.Encoding.UTF8. + + + + This flag has no effect or relation to the text encoding used within the + file itself. + + + + + + + The text encoding to use for the FileName and Comment on this ZipEntry, + when the default encoding is insufficient. + + + + + + Don't use this property. See . + + + + + + + Specifies the alternate text encoding used by this ZipEntry + + + + 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. + + + When creating a zip file, the usage of the alternate encoding is + governed by the property. + Typically you would set both properties to tell DotNetZip to employ an + encoding that is not IBM437 in the zipfile you are creating. + + + 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. + + + 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. + + + + This example shows how to create a zipfile encoded with a + language-specific encoding: + + 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"); + } + + + + + + + Describes if and when this instance should apply + AlternateEncoding to encode the FileName and Comment, when + saving. + + + + + + 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. + + + + + 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. + + + + 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. + + + + 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. + + + + 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. + + + + This property merely tells a reading application what is stored in the + metadata for an entry, without guaranteeing its validity or its + meaning. + + + + 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 + Save() on the ZipFile. + + + + 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, you + need to read and parse the registry. + + + + + using (var zip = new ZipFile()) + { + var e = zip.UpdateFile("Descriptions.mme", ""); + e.IsText = true; + zip.Save(zipPath); + } + + + + Using zip As New ZipFile + Dim e2 as ZipEntry = zip.AddFile("Descriptions.mme", "") + e.IsText= True + zip.Save(zipPath) + End Using + + + + + Provides a string representation of the instance. + a string representation of the instance. + + + + Extract the entry to the filesystem, starting at the current + working directory. + + + + 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 ExtractWithPassword() methods. + + + + + + + + + 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. + + + + The action taken when extraction an entry would overwrite an + existing file is determined by the property. + + + + Within the call to Extract(), 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 property on + the entry. See the remarks the property for + some details about the last modified time. + + + + + + + Extract the entry to a file in the filesystem, using the specified + behavior when extraction would overwrite an existing file. + + + + + See the remarks on the property, for some + details about how the last modified time of the file is set after + extraction. + + + + + The action to take if extraction would overwrite an existing file. + + + + + Extracts the entry to the specified stream. + + + + + The caller can specify any write-able stream, for example a , a , or ASP.NET's + Response.OutputStream. The content will be decrypted and + decompressed as necessary. If the entry is encrypted and no password + is provided, this method will throw. + + + 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(). + + + + + the stream to which the entry should be extracted. + + + + + + Extract the entry to the filesystem, starting at the specified base + directory. + + + the pathname of the base directory + + + + + + This example extracts only the entries in a zip file that are .txt files, + into a directory called "textfiles". + + using (ZipFile zip = ZipFile.Read("PackedDocuments.zip")) + { + foreach (string s1 in zip.EntryFilenames) + { + if (s1.EndsWith(".txt")) + { + zip[s1].Extract("textfiles"); + } + } + } + + + 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 + + + + + + + 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 property, or call + . + + + + See the remarks on the property, for some + details about how the last modified time of the created file is set. + + + + + + Extract the entry to the filesystem, starting at the specified base + directory, and using the specified behavior when extraction would + overwrite an existing file. + + + + + See the remarks on the property, for some + details about how the last modified time of the created file is set. + + + + + + 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); + } + } + + + + 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 + + + + the pathname of the base directory + + The action to take if extraction would overwrite an existing file. + + + + + Extract the entry to the filesystem, using the current working directory + and the specified password. + + + + This method has a bunch of overloads! One of them is sure to be + the right one for you... + + + + + + + + + Existing entries in the filesystem will not be overwritten. If you + would like to force the overwrite of existing files, see the property, or call + . + + + + See the remarks on the property for some + details about how the "last modified" time of the created file is + set. + + + + + In this example, entries that use encryption are extracted using a + particular password. + + using (var zip = ZipFile.Read(FilePath)) + { + foreach (ZipEntry e in zip) + { + if (e.UsesEncryption) + e.ExtractWithPassword("Secret!"); + else + e.Extract(); + } + } + + + 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 + + + The Password to use for decrypting the entry. + + + + Extract the entry to the filesystem, starting at the specified base + directory, and using the specified password. + + + + + + + + Existing entries in the filesystem will not be overwritten. If you + would like to force the overwrite of existing files, see the property, or call + . + + + + See the remarks on the property, for some + details about how the last modified time of the created file is set. + + + + The pathname of the base directory. + The Password to use for decrypting the entry. + + + + 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. + + + + + See the remarks on the property, for some + details about how the last modified time of the created file is set. + + + + The Password to use for decrypting the entry. + + + The action to take if extraction would overwrite an existing file. + + + + + Extract the entry to the filesystem, starting at the specified base + directory, and using the specified behavior when extraction would + overwrite an existing file. + + + + See the remarks on the property, for some + details about how the last modified time of the created file is set. + + + the pathname of the base directory + + The action to take if extraction would + overwrite an existing file. + + The Password to use for decrypting the entry. + + + + Extracts the entry to the specified stream, using the specified + Password. For example, the caller could extract to Console.Out, or + to a MemoryStream. + + + + + The caller can specify any write-able stream, for example a , a , or ASP.NET's + Response.OutputStream. The content will be decrypted and + decompressed as necessary. If the entry is encrypted and no password + is provided, this method will throw. + + + 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(). + + + + + + the stream to which the entry should be extracted. + + + The password to use for decrypting the entry. + + + + + Opens a readable stream corresponding to the zip entry in the + archive. The stream decompresses and decrypts as necessary, as it + is read. + + + + + + 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 . + + + + The return value is of type . Use it as you would any + stream for reading. When an application calls on that stream, it will + receive data from the zip entry that is decrypted and decompressed + as necessary. + + + + CrcCalculatorStream adds one additional feature: it keeps a + CRC32 checksum on the bytes of the stream as it is read. The CRC + value is available in the property on the + CrcCalculatorStream. When the read is complete, your + application + should check this CRC against the + property on the ZipEntry 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. + + + + If the entry is protected with a password, then you need to provide + a password prior to calling , either by + setting the property on the entry, or the + property on the ZipFile + itself. Or, you can use , the + overload of OpenReader that accepts a password parameter. + + + + If you want to extract entry data into a write-able stream that is + already opened, like a , do not + use this method. Instead, use . + + + + 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(). + + + + The OpenReader() method works only when the ZipEntry is + obtained from an instance of ZipFile. This method will throw + an exception if the ZipEntry is obtained from a . + + + + + 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 ZipEntry, to verify the extraction. + + 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)); + } + } + + + 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 + + + + The Stream for reading. + + + + Opens a readable stream for an encrypted zip entry in the archive. + The stream decompresses and decrypts as necessary, as it is read. + + + + + See the documentation on the method for + full details. This overload allows the application to specify a + password for the ZipEntry to be read. + + + + The password to use for decrypting the entry. + The Stream for reading. + + + + Pass in either basedir or s, but not both. + In other words, you can extract to a stream or to a directory (filesystem), but not both! + The Password param is required for encrypted entries. + + + + + Extract to a stream + In other words, you can extract to a stream or to a directory (filesystem), but not both! + The Password param is required for encrypted entries. + + + + + Validates that the args are consistent; returning whether the caller can return + because it's done, or not (caller should continue) + + + + + Validates that the args are consistent; returning whether the caller can return + because it's done, or not (caller should continue) + + + + + Reads one ZipEntry from the given stream. The content for + the entry does not get decompressed or decrypted. This method + basically reads metadata, and seeks. + + the ZipContainer this entry belongs to. + + true of this is the first entry being read from the stream. + + the ZipEntry read from the stream. + + + + 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. + + + + + 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. + + + + + generate and return a byte array that encodes the filename + for the entry. + + + + 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. + + + + + + Stores the position of the entry source stream, or, if the position is + already stored, seeks to that position. + + + + + 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. + + + + The first time through, this method sets the _sourceStreamOriginalPosition + field. Subsequent calls to this method seek to that position. + + + + + + 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. + + + + + 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) + + + + + Prepare the given stream for output - wrap it in a CountingStream, and + then in a CRC stream, and an encryptor and deflator as appropriate. + + + + 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. + + + + + + An enum that specifies the type of timestamp available on the ZipEntry. + + + + + + The last modified time of a file can be stored in multiple ways in + a zip file, and they are not mutually exclusive: + + + + + 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 LastModified property. This value is always + present in the metadata for each zip entry. In some cases the value is + invalid, or zero. + + + + 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 ModifiedTime property. + + + + In the "Unix" format, a 4-byte quantity specifying the number of seconds since + January 1, 1970 UTC. + + + + 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. + + + + + + This bit field describes which of the formats were found in a ZipEntry that was read. + + + + + + + Default value. + + + + + A DOS timestamp with 2-second precision. + + + + + A Windows timestamp with 100-ns precision. + + + + + A Unix timestamp with 1-second precision. + + + + + A Unix timestamp with 1-second precision, stored in InfoZip v1 format. This + format is outdated and is supported for reading archives only. + + + + + The method of compression to use for a particular ZipEntry. + + + + PKWare's + ZIP Specification describes a number of distinct + cmopression methods that can be used within a zip + file. DotNetZip supports a subset of them. + + + + + No compression at all. For COM environments, the value is 0 (zero). + + + + + DEFLATE compression, as described in IETF RFC + 1951. This is the "normal" compression used in zip + files. For COM environments, the value is 8. + + + + + BZip2 compression, a compression algorithm developed by Julian Seward. + For COM environments, the value is 12. + + + + + An enum that specifies the source of the ZipEntry. + + + + + Default value. Invalid on a bonafide ZipEntry. + + + + + The entry was instantiated by calling AddFile() or another method that + added an entry from the filesystem. + + + + + The entry was instantiated via or + . + + + + + The ZipEntry was instantiated by reading a zipfile. + + + + + The content for the ZipEntry will be or was provided by the WriteDelegate. + + + + + The content for the ZipEntry will be obtained from the stream dispensed by the OpenDelegate. + The entry was instantiated via . + + + + + The content for the ZipEntry will be or was obtained from a ZipOutputStream. + + + + + 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. + + + + + 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. + + + + 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. + + + + 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. + + + + + + Throw an exception when an error occurs while zipping. This is the default + behavior. (For COM clients, this is a 0 (zero).) + + + + + 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.) + + + + + 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.) + + + + + When an error occurs, invoke the zipError event. The event type used is + . 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 on the + ZipProgressEventArgs.CurrentEntry to Skip. If you want the + exception to be thrown, set ZipErrorAction on the CurrentEntry + to Throw. If you want to cancel the zip, set + ZipProgressEventArgs.Cancel 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.) + + + + + Options for using ZIP64 extensions when saving zip archives. + + + + + + Designed many years ago, the original zip + specification from PKWARE 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. + + + + Set this property to 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. + + + + Set this property to 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 Never. If you set this property to , 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. + + + + Set this property to 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 Response.OutputStream, or + Console.Out. 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 is the same + as using : it will always produce a zip + archive that uses ZIP64 extensions. + + + + + + + The default behavior, which is "Never". + (For COM clients, this is a 0 (zero).) + + + + + Do not use ZIP64 extensions when writing zip archives. + (For COM clients, this is a 0 (zero).) + + + + + 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.) + + + + + Always use ZIP64 extensions when writing zip archives, even when unnecessary. + (For COM clients, this is a 2.) + + + + + 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. + + + + + The default behavior. This is the same as "Never". + (For COM clients, this is a 0 (zero).) + + + + + Never use the associated option. + (For COM clients, this is a 0 (zero).) + + + + + Use the associated behavior "as necessary." + (For COM clients, this is a 1.) + + + + + Use the associated behavior Always, whether necessary or not. + (For COM clients, this is a 2.) + + + + + A class for collecting the various options that can be used when + Reading zip files for extraction or update. + + + + + 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. + + + + Pass an instance of the ReadOptions class into the + ZipFile.Read() method. + + + . + . + + + + + 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 Read(), the progress event is invoked as + necessary. + + + + + The System.IO.TextWriter to use for writing verbose status messages + during operations on 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 + TextWriter, such as a System.IO.StringWriter. + + + + + The System.Text.Encoding 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. + + + + + + + + Provides a stream metaphor for reading zip files. + + + + + This class provides an alternative programming model for reading zip files to + the one enabled by the class. Use this when reading zip + files, as an alternative to the class, when you would + like to use a Stream class to read the file. + + + + Some application designs require a readable stream for input. This stream can + be used to read a zip file, and extract entries. + + + + Both the ZipInputStream class and the ZipFile 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 GetNextEntry() and Read() methods on the + ZipInputStream 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 ZipEntry.Extract(). For this reason, the + ZipInputStream is generally recommended for when your application wants + to extract the data, without storing that data into a file. + + + + Aside from the obvious differences in programming model, there are some + differences in capability between the ZipFile class and the + ZipInputStream class. + + + + + ZipFile can be used to create or update zip files, or read and + extract zip files. ZipInputStream can be used only to read and + extract zip files. If you want to use a stream to create zip files, check + out the . + + + + ZipInputStream cannot read segmented or spanned + zip files. + + + + ZipInputStream will not read Zip file comments. + + + + When reading larger files, ZipInputStream will always underperform + ZipFile. This is because the ZipInputStream does a full scan on the + zip file, while the ZipFile class reads the central directory of the + zip file. + + + + + + + + + Create a ZipInputStream, wrapping it around an existing stream. + + + + + + While the class is generally easier + to use, this class provides an alternative to those + applications that want to read from a zipfile directly, + using a . + + + + Both the ZipInputStream class and the ZipFile 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 GetNextEntry() and Read() methods on the + ZipInputStream 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 ZipEntry.Extract(). For this reason, the + ZipInputStream is generally recommended for when your application wants + to extract the data, without storing that data into a file. + + + + Aside from the obvious differences in programming model, there are some + differences in capability between the ZipFile class and the + ZipInputStream class. + + + + + ZipFile can be used to create or update zip files, or read and extract + zip files. ZipInputStream can be used only to read and extract zip + files. If you want to use a stream to create zip files, check out the . + + + + ZipInputStream cannot read segmented or spanned + zip files. + + + + ZipInputStream will not read Zip file comments. + + + + When reading larger files, ZipInputStream will always underperform + ZipFile. This is because the ZipInputStream does a full scan on the + zip file, while the ZipFile class reads the central directory of the + zip file. + + + + + + + + The stream to read. It must be readable. This stream will be closed at + the time the ZipInputStream is closed. + + + + + This example shows how to read a zip file, and extract entries, using the + ZipInputStream class. + + + 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); + } + } + } + } + } + } + + + + 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 + + + + + + Create a ZipInputStream, given the name of an existing zip file. + + + + + + This constructor opens a FileStream for the given zipfile, and + wraps a ZipInputStream around that. See the documentation for the + constructor for full details. + + + + While the class is generally easier + to use, this class provides an alternative to those + applications that want to read from a zipfile directly, + using a . + + + + + + The name of the filesystem file to read. + + + + + This example shows how to read a zip file, and extract entries, using the + ZipInputStream class. + + + 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); + } + } + } + } + } + + + + 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 + + + + + + Create a ZipInputStream, explicitly specifying whether to + keep the underlying stream open. + + + + See the documentation for the ZipInputStream(Stream) + constructor for a discussion of the class, and an example of how to use the class. + + + + The stream to read from. It must be readable. + + + + true if the application would like the stream + to remain open after the ZipInputStream has been closed. + + + + Provides a string representation of the instance. + + + This can be useful for debugging purposes. + + + a string representation of the instance. + + + + 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. + + + + + In its + zip specification, 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. + + + + 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 ZipEntry in the zip + file. + + + + 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 Comment encoded in IBM437 and a FileName encoded with + the specified "provisional" codepage. + + + + 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. + + + + + + + Size of the work buffer to use for the ZLIB codec during decompression. + + + + 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. + + + + + Sets the password to be used on the ZipInputStream instance. + + + + + + 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 Read() for each entry. + + + + When reading an entry that is not encrypted, the value of this property is + ignored. + + + + + + + This example uses the ZipInputStream to read and extract entries from a + zip file, using a potentially different password for each entry. + + + 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); + } + } + } + } + } + + + + + + + Read the data from the stream into the buffer. + + + + + The data for the zipentry will be decrypted and uncompressed, as + necessary, before being copied into the buffer. + + + + You must set the property before calling + Read() the first time for an encrypted entry. To determine if an + entry is encrypted and requires a password, check the ZipEntry.Encryption property. + + + + The buffer to hold the data read from the stream. + the offset within the buffer to copy the first byte read. + the number of bytes to read. + the number of bytes read, after decryption and decompression. + + + + Read the next entry from the zip file. + + + + + Call this method just before calling , + to position the pointer in the zip file to the next entry that can be + read. Subsequent calls to Read(), will decrypt and decompress the + data in the zip file, until Read() returns 0. + + + + Each time you call GetNextEntry(), the pointer in the wrapped + stream is moved to the next entry in the zip file. If you call , and thus re-position the pointer within + the file, you will need to call GetNextEntry() again, to insure + that the file pointer is positioned at the beginning of a zip entry. + + + + This method returns the ZipEntry. Using a stream approach, you will + read the raw bytes for an entry in a zip file via calls to Read(). + Alternatively, you can extract an entry into a file, or a stream, by + calling , or one of its siblings. + + + + + + The ZipEntry read. Returns null (or Nothing in VB) if there are no more + entries in the zip file. + + + + + + Dispose the stream. + + + + + This method disposes the ZipInputStream. It may also close the + underlying stream, depending on which constructor was used. + + + + Typically the application will call Dispose() implicitly, via + a using statement in C#, or a Using statement in VB. + + + + 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. + + + + + true if the Dispose method was invoked by user code. + + + + + Always returns true. + + + + + Returns the value of CanSeek for the underlying (wrapped) stream. + + + + + Always returns false. + + + + + Returns the length of the underlying stream. + + + + + Gets or sets the position of the underlying stream. + + + Setting the position is equivalent to calling Seek(value, SeekOrigin.Begin). + + + + + This is a no-op. + + + + + This method always throws a NotSupportedException. + + ignored + ignored + ignored + + + + This method seeks in the underlying stream. + + + + + Call this method if you want to seek around within the zip file for random access. + + + + Applications can intermix calls to Seek() with calls to . After a call to Seek(), + GetNextEntry() will get the next ZipEntry 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. + + + + + the offset point to seek to + the reference point from which to seek + The new position + + + + This method always throws a NotSupportedException. + + ignored + + + + Provides a stream metaphor for generating zip files. + + + + + This class writes zip files, as defined in the specification + for zip files described by PKWare. The compression for this + implementation is provided by a managed-code version of Zlib, included with + DotNetZip in the classes in the Ionic.Zlib namespace. + + + + This class provides an alternative programming model to the one enabled by the + class. Use this when creating zip files, as an + alternative to the class, when you would like to use a + Stream type to write the zip file. + + + + Both the ZipOutputStream class and the ZipFile 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. + + + + The ZipFile class is generally easier to use than + ZipOutputStream and should be considered a higher-level interface. For + example, when creating a zip file via calls to the PutNextEntry() and + Write() methods on the ZipOutputStream class, the caller is + responsible for opening the file, reading the bytes from the file, writing + those bytes into the ZipOutputStream, setting the attributes on the + ZipEntry, 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 ZipFile.AddFile(). + For this reason, the ZipOutputStream 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 Stream + metaphor. + + + + Aside from the differences in programming model, there are other + differences in capability between the two classes. + + + + + ZipFile can be used to read and extract zip files, in addition to + creating zip files. ZipOutputStream cannot read zip files. If you want + to use a stream to read zip files, check out the class. + + + + ZipOutputStream does not support the creation of segmented or spanned + zip files. + + + + ZipOutputStream cannot produce a self-extracting archive. + + + + + Be aware that the ZipOutputStream class implements the interface. In order for + ZipOutputStream to produce a valid zip file, you use use it within + a using clause (Using in VB), or call the Dispose() method + explicitly. See the examples for how to employ a using clause. + + + + 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 property to zero, if you are compressing + large files through ZipOutputStream. This will cause parallel + compression to be used, always. + + + + + + Create a ZipOutputStream, wrapping an existing stream. + + + + + The class is generally easier to use when creating + zip files. The ZipOutputStream offers a different metaphor for creating a + zip file, based on the class. + + + + + + The stream to wrap. It must be writable. This stream will be closed at + the time the ZipOutputStream is closed. + + + + + This example shows how to create a zip file, using the + ZipOutputStream class. + + + 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); + } + } + } + } + } + } + + + + 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 + + + + + + Create a ZipOutputStream that writes to a filesystem file. + + + + The class is generally easier to use when creating + zip files. The ZipOutputStream offers a different metaphor for creating a + zip file, based on the class. + + + + The name of the zip file to create. + + + + + This example shows how to create a zip file, using the + ZipOutputStream class. + + + 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); + } + } + } + } + } + + + + 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 + + + + + + Create a ZipOutputStream. + + + + See the documentation for the ZipOutputStream(Stream) + constructor for an example. + + + + The stream to wrap. It must be writable. + + + + true if the application would like the stream + to remain open after the ZipOutputStream has been closed. + + + + Provides a string representation of the instance. + + + This can be useful for debugging purposes. + + + a string representation of the instance. + + + + Sets the password to be used on the ZipOutputStream instance. + + + + + + When writing a zip archive, this password is applied to the entries, not + to the zip archive itself. It applies to any ZipEntry subsequently + written to the ZipOutputStream. + + + + 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 + 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. + + + + If you set this property, and then add a set of entries to the archive via + calls to PutNextEntry, 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 null (Nothing in VB), and add another entry, the + first entry is encrypted and the second is not. + + + + When setting the Password, you may also want to explicitly set the 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 , then PKZip 2.0 ("Weak") encryption is used. + This encryption is relatively weak but is very interoperable. If + you set the password to a null value (Nothing in VB), + Encryption is reset to None. + + + + Special case: if you wrap a ZipOutputStream around a non-seekable stream, + and use encryption, and emit an entry of zero bytes, the Close() or + PutNextEntry() following the entry will throw an exception. + + + + + + + The Encryption to use for entries added to the ZipOutputStream. + + + + + The specified Encryption is applied to the entries subsequently + written to the ZipOutputStream instance. + + + + If you set this to something other than + EncryptionAlgorithm.None, you will also need to set the + to a non-null, non-empty value in + order to actually get encryption on the entry. + + + + + ZipOutputStream.Password + ZipEntry.Encryption + + + + Size of the work buffer to use for the ZLIB codec during compression. + + + + 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. + + + + + The compression strategy to use for all entries. + + + + 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 . + + + + + The type of timestamp attached to the ZipEntry. + + + + Set this in order to specify the kind of timestamp that should be emitted + into the zip file for each entry. + + + + + Sets the compression level to be used for entries subsequently added to + the zip archive. + + + + + Varying the compression level used on entries can affect the + size-vs-speed tradeoff when compression and decompressing data streams + or files. + + + + As with some other properties on the ZipOutputStream class, like , and , + setting this property on a ZipOutputStream + instance will cause the specified CompressionLevel to be used on all + items that are subsequently added to the + ZipOutputStream instance. + + + + 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 BestCompression 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. + + + + + + The compression method used on each entry added to the ZipOutputStream. + + + + + A comment attached to the zip archive. + + + + + + The application sets this property to specify a comment to be embedded + into the generated zip archive. + + + + According to PKWARE's + zip specification, the comment is not encrypted, even if there is a + password set on the zip file. + + + + 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 is + Never, it uses the default encoding (IBM437). (b) if is Always, it always uses the + alternate encoding (). (c) if is AsNecessary, 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 ZipFile.Save(). + + + + + + + Specify whether to use ZIP64 extensions when saving a zip archive. + + + + + The default value for the property is . is + safest, in the sense that you will not get an Exception if a + pre-ZIP64 limit is exceeded. + + + + You must set this property before calling Write(). + + + + + + + Indicates whether ZIP64 extensions were used when saving the zip archive. + + + + The value is defined only after the ZipOutputStream has been closed. + + + + + Whether the ZipOutputStream should use case-insensitive comparisons when + checking for uniqueness of zip entries. + + + + + 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 with a name that duplicates one + already used within the archive, the library will throw an Exception. + + + This property allows the application to specify whether the + ZipOutputStream instance considers ordinal case when checking for + uniqueness of zip entries. + + + + + + Indicates whether to encode entry filenames and entry comments using + Unicode (UTF-8). + + + + + The + PKWare zip specification 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. + + + + 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. + + + + 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. + + + + 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. + + + + 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. + + + + 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. + + + + If you do not set this flag, it will remain false. If this flag is false, + the ZipOutputStream 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". + + + + 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 ZipOutputStream, 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. + + + + 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. + + + + Rather than specify the encoding in a binary fashion using this flag, an + application can specify an arbitrary encoding via the 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. + + + + + + + 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. + + + + + In its + zip specification, 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. + + + + 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 and for each ZipEntry 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 + Comment encoded in IBM437 and a FileName encoded with the + specified "provisional" codepage. + + + + Be aware that a zip file created after you've explicitly set the + 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. + + + + When creating a zip archive using this library, it is possible to change + the value of ProvisionalAlternateEncoding between each entry you + add, and between adding entries and the call to Close(). Don't do + this. It will likely result in a zipfile that is not readable. For best + interoperability, either leave ProvisionalAlternateEncoding + alone, or specify it only once, before adding any entries to the + ZipOutputStream instance. There is one exception to this + recommendation, described later. + + + + 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. + + + + 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 ProvisionalAlternateEncoding to your desired + region-specific code page, once before adding any entries, and then set + the property and reset + ProvisionalAlternateEncoding to IBM437 before calling Close(). + + + + + + A Text Encoding to use when encoding the filenames and comments for + all the ZipEntry items, during a ZipFile.Save() operation. + + + + Whether the encoding specified here is used during the save depends + on . + + + + + + 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. + + + + + The default text encoding used in zip archives. It is numeric 437, also + known as IBM437. + + + + + + The size threshold for an entry, above which a parallel deflate is used. + + + + + + DotNetZip will use multiple threads to compress any ZipEntry, when + the CompressionMethod 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". + + + + 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. + + + + 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. + + + + 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%. + + + + 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 . You may have to perform + some tests to determine the best approach for your situation. + + + + The default value for this property is -1, which means parallel + compression will not be performed unless you set it to zero. + + + + + + + The maximum number of buffer pairs to use when performing + parallel compression. + + + + + 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 + ThreadPool.QueueUserWorkItem() to compress those + buffers in a background threadpool thread. After a buffer + is compressed, it is re-ordered and written to the output + stream. + + + + 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. + + + + 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 (). 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. + + + + 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. + + + + 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. + + + + 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. + + + + The application can set this value at any time, but it is + effective only if set before calling + ZipOutputStream.Write() for the first time. + + + + + + + + + Returns true if an entry by the given name has already been written + to the ZipOutputStream. + + + + The name of the entry to scan for. + + + + true if an entry by the given name has already been written. + + + + + Write the data from the buffer to the stream. + + + + 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 + and the properties. + + + The buffer holding data to write to the stream. + the offset within that data array to find the first byte to write. + the number of bytes to write. + + + + Specify the name of the next entry that will be written to the zip file. + + + + + Call this method just before calling , to + specify the name of the entry that the next set of bytes written to + the ZipOutputStream belongs to. All subsequent calls to Write, + until the next call to PutNextEntry, + will be inserted into the named entry in the zip file. + + + + If the used in PutNextEntry() ends in + a slash, then the entry added is marked as a directory. Because directory + entries do not contain data, a call to Write(), before an + intervening additional call to PutNextEntry(), will throw an + exception. + + + + If you don't call Write() between two calls to + PutNextEntry(), the first entry is inserted into the zip file as a + file of zero size. This may be what you want. + + + + Because PutNextEntry() closes out the prior entry, if any, this + method may throw if there is a problem with the prior entry. + + + + This method returns the ZipEntry. You can modify public properties + on the ZipEntry, such as , , and so on, until the first call to + ZipOutputStream.Write(), or until the next call to + PutNextEntry(). If you modify the ZipEntry after + having called Write(), you may get a runtime exception, or you may + silently get an invalid zip archive. + + + + + + + This example shows how to create a zip file, using the + ZipOutputStream class. + + + 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); + } + } + } + + + + + The name of the entry to be added, including any path to be used + within the zip file. + + + + The ZipEntry created. + + + + + + Dispose the stream + + + + + 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. + + + + Typically the application will call Dispose() implicitly, via a using + statement in C#, or a Using statement in VB. + + + + + set this to true, always. + + + + Always returns false. + + + + + Always returns false. + + + + + Always returns true. + + + + + Always returns a NotSupportedException. + + + + + Setting this property always returns a NotSupportedException. Getting it + returns the value of the Position on the underlying stream. + + + + + This is a no-op. + + + + + This method always throws a NotSupportedException. + + ignored + ignored + ignored + nothing + + + + This method always throws a NotSupportedException. + + ignored + ignored + nothing + + + + This method always throws a NotSupportedException. + + ignored + + + + 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. + + + + 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. + + + Caller must Close/Dispose the stream object returned by + this method. + + + + + + Name of the filesystem file corresponding to the current segment. + + + + 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. + + + + + + Read from the stream + + the buffer to read + the offset at which to start + the number of bytes to read + the number of bytes actually read + + + + Write to the stream. + + the buffer from which to write + the offset at which to start writing + the number of bytes to write + + + + Enumerates the options for a logical conjunction. This enum is intended for use + internally by the FileSelector class. + + + + + 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. + + + + + + The FileSelector class is used internally by the ZipFile class for selecting + files for inclusion into the ZipFile, when the method, or one of + its overloads, is called. It's also used for the methods. Typically, an + application that creates or manipulates Zip archives will not directly + interact with the FileSelector class. + + + + 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. + + + + Consult the documentation for + for more information on specifying the selection criteria. + + + + + + + Constructor that allows the caller to specify file selection criteria. + + + + + This constructor allows the caller to specify a set of criteria for + selection of files. + + + + See for a description of + the syntax of the selectionCriteria string. + + + + By default the FileSelector will traverse NTFS Reparse Points. To + change this, use FileSelector(String, bool). + + + + The criteria for file selection. + + + + Constructor that allows the caller to specify file selection criteria. + + + + + This constructor allows the caller to specify a set of criteria for + selection of files. + + + + See for a description of + the syntax of the selectionCriteria string. + + + + The criteria for file selection. + + whether to traverse NTFS reparse points (junctions). + + + + + The string specifying which files to include when retrieving. + + + + + 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." + + + + 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. + + + + 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. + + + + 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). + + + + The value for a size criterion is expressed in integer quantities of + bytes, kilobytes (use k or kb after the number), megabytes (m or mb), + or gigabytes (g or gb). + + + + The value for a name is a pattern to match against the filename, + potentially including wildcards. The pattern follows CMD.exe glob + rules: * implies one or more of any character, 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. + + + + 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 = '* *.*'" . + + + + The value for a type criterion is either F (implying a file) or D + (implying a directory). + + + + Some examples: + + + + + criteria + Files retrieved + + + + name != *.xls + any file with an extension that is not .xls + + + + + name = *.mp3 + any file with a .mp3 extension. + + + + + *.mp3 + (same as above) any file with a .mp3 extension. + + + + + attributes = A + all files whose attributes include the Archive bit. + + + + + attributes != H + all files whose attributes do not include the Hidden bit. + + + + + mtime > 2009-01-01 + all files with a last modified time after January 1st, 2009. + + + + + ctime > 2009/01/01-03:00:00 + all files with a created time after 3am (local time), + on January 1st, 2009. + + + + + size > 2gb + all files whose uncompressed size is greater than 2gb. + + + + + type = D + all directories in the filesystem. + + + + + + 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. + + + + 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. + + + + 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. + + + + 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. + + + + 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. + + + + + + Thrown in the setter if the value has an invalid syntax. + + + + + Indicates whether searches will traverse NTFS reparse points, like Junctions. + + + + + Returns a string representation of the FileSelector object. + + The string representation of the boolean logic statement of the file + selection criteria for this instance. + + + + Returns the names of the files in the specified directory + that fit the selection criteria specified in the FileSelector. + + + + This is equivalent to calling + with recurseDirectories = false. + + + + The name of the directory over which to apply the FileSelector + criteria. + + + + A collection of strings containing fully-qualified pathnames of files + that match the criteria specified in the FileSelector instance. + + + + + Returns the names of the files in the specified directory that fit the + selection criteria specified in the FileSelector, optionally recursing + through subdirectories. + + + + 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. + + + + The name of the directory over which to apply the FileSelector + criteria. + + + + Whether to recurse through subdirectories when applying the file + selection criteria. + + + + A collection of strings containing fully-qualified pathnames of files + that match the criteria specified in the FileSelector instance. + + + + + Retrieve the ZipEntry items in the ZipFile that conform to the specified criteria. + + + + + This method applies the criteria set in the FileSelector instance (as described in + the ) to the specified ZipFile. Using this + method, for example, you can retrieve all entries from the given ZipFile that + have filenames ending in .txt. + + + + Normally, applications would not call this method directly. This method is used + by the ZipFile class. + + + + Using the appropriate SelectionCriteria, you can retrieve entries based on size, + time, and attributes. See for a + description of the syntax of the SelectionCriteria string. + + + + + The ZipFile from which to retrieve entries. + + a collection of ZipEntry objects that conform to the criteria. + + + + Retrieve the ZipEntry items in the ZipFile that conform to the specified criteria. + + + + + This method applies the criteria set in the FileSelector instance (as described in + the ) to the specified ZipFile. Using this + method, for example, you can retrieve all entries from the given ZipFile that + have filenames ending in .txt. + + + + Normally, applications would not call this method directly. This method is used + by the ZipFile class. + + + + This overload allows the selection of ZipEntry instances from the ZipFile to be restricted + to entries contained within a particular directory in the ZipFile. + + + + Using the appropriate SelectionCriteria, you can retrieve entries based on size, + time, and attributes. See for a + description of the syntax of the SelectionCriteria string. + + + + + The ZipFile from which to retrieve entries. + + + the directory in the archive from which to select entries. If null, then + all directories in the archive are used. + + + a collection of ZipEntry objects that conform to the criteria. + + + + Summary description for EnumUtil. + + + + + Returns the value of the DescriptionAttribute if the specified Enum + value has one. If not, returns the ToString() representation of the + Enum value. + + The Enum to get the description for + + + + + 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. + + The System.Type of the enumeration. + + A string containing the name or value to convert. + + + + + + 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. + + The System.Type of the enumeration. + + A string containing the name or value to convert. + + + Whether the operation is case-sensitive or not. + + + + + 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. + + + This type is used internally by DotNetZip; it is generally not used + directly by applications wishing to create, read, or manipulate zip + archive files. + + + + + Indicates the total number of bytes applied to the CRC. + + + + + Indicates the current CRC for all blocks slurped in. + + + + + Returns the CRC32 for the specified stream. + + The stream over which to calculate the CRC32 + the CRC32 calculation + + + + Returns the CRC32 for the specified stream, and writes the input into the + output stream. + + The stream over which to calculate the CRC32 + The stream into which to deflate the input + the CRC32 calculation + + + + Get the CRC32 for the given (word,byte) combo. This is a + computation defined by PKzip for PKZIP 2.0 (weak) encryption. + + The word to start with. + The byte to combine it with. + The CRC-ized result. + + + + Update the value for the running CRC32 using the given block of bytes. + This is useful when using the CRC32() class in a Stream. + + block of bytes to slurp + starting point in the block + how many bytes within the block to slurp + + + + Process one byte in the CRC. + + the byte to include into the CRC . + + + + Process a run of N identical bytes into the CRC. + + + + 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. + + + the byte to include into the CRC. + the number of times that byte should be repeated. + + + + Combines the given CRC32 value with the current running total. + + + 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. + + the crc value to be combined with this one + the length of data the CRC value was calculated on + + + + Create an instance of the CRC32 class using the default settings: no + bit reversal, and a polynomial of 0xEDB88320. + + + + + Create an instance of the CRC32 class, specifying whether to reverse + data bits or not. + + + specify true if the instance should reverse data bits. + + + + 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. + + + + + + Create an instance of the CRC32 class, specifying the polynomial and + whether to reverse data bits or not. + + + 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. + + + specify true if the instance should reverse data bits. + + + + + 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 reverseBits 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 + reverseBits parameter. + + + + + + Reset the CRC-32 class - clear the CRC "remainder register." + + + + Use this when employing a single instance of this class to compute + multiple, distinct CRCs on multiple, distinct data blocks. + + + + + + A Stream that calculates a CRC32 (a checksum) on all bytes read, + or on all bytes written. + + + + + 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. + + + + This class is intended primarily for use internally by the + DotNetZip library. + + + + + + The default constructor. + + + + 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. + + + The underlying stream + + + + The constructor allows the caller to specify how to handle the + underlying stream at close. + + + + The stream uses the default CRC32 algorithm, which implies a + polynomial of 0xEDB88320. + + + The underlying stream + true to leave the underlying stream + open upon close of the CrcCalculatorStream; false otherwise. + + + + A constructor allowing the specification of the length of the stream + to read. + + + + The stream uses the default CRC32 algorithm, which implies a + polynomial of 0xEDB88320. + + + Instances returned from this constructor will leave the underlying + stream open upon Close(). + + + The underlying stream + The length of the stream to slurp + + + + 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(). + + + + The stream uses the default CRC32 algorithm, which implies a + polynomial of 0xEDB88320. + + + The underlying stream + The length of the stream to slurp + true to leave the underlying stream + open upon close of the CrcCalculatorStream; false otherwise. + + + + 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. + + + + The stream uses the specified CRC32 instance, which allows the + application to specify how the CRC gets calculated. + + + The underlying stream + The length of the stream to slurp + true to leave the underlying stream + open upon close of the CrcCalculatorStream; false otherwise. + the CRC32 instance to use to calculate the CRC32 + + + + Gets the total number of bytes run through the CRC32 calculator. + + + + This is either the total number of bytes read, or the total number of + bytes written, depending on the direction of this stream. + + + + + Provides the current CRC for all blocks slurped in. + + + + 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. + + + + + + Indicates whether the underlying stream will be left open when the + CrcCalculatorStream is Closed. + + + + Set this at any point before calling . + + + + + + Read from the stream + + the buffer to read + the offset at which to start + the number of bytes to read + the number of bytes actually read + + + + Write to the stream. + + the buffer from which to write + the offset at which to start writing + the number of bytes to write + + + + Indicates whether the stream supports reading. + + + + + Indicates whether the stream supports seeking. + + + + Always returns false. + + + + + + Indicates whether the stream supports writing. + + + + + Flush the stream. + + + + + Returns the length of the underlying stream. + + + + + The getter for this property returns the total bytes read. + If you use the setter, it will throw + . + + + + + Seeking is not supported on this stream. This method always throws + + + N/A + N/A + N/A + + + + This method always throws + + + N/A + + + + Closes the stream. + + + + + A class for compressing and decompressing streams using the Deflate algorithm. + + + + + + The DeflateStream is a Decorator on a . It adds DEFLATE compression or decompression to any + stream. + + + + Using this stream, applications can compress or decompress data via stream + Read and Write operations. Either compresssion or decompression + can occur through either reading or writing. The compression format used is + DEFLATE, which is documented in IETF RFC 1951, "DEFLATE + Compressed Data Format Specification version 1.3.". + + + + This class is similar to , except that + ZlibStream adds the RFC + 1950 - ZLIB framing bytes to a compressed stream when compressing, or + expects the RFC1950 framing bytes when decompressing. The DeflateStream + does not. + + + + + + + + + + Create a DeflateStream using the specified CompressionMode. + + + + When mode is CompressionMode.Compress, the DeflateStream will use + the default compression level. The "captive" stream will be closed when + the DeflateStream is closed. + + + + This example uses a DeflateStream to compress data from a file, and writes + the compressed data to another file. + + 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); + } + } + } + } + + + + 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 + + + The stream which will be read or written. + Indicates whether the DeflateStream will compress or decompress. + + + + Create a DeflateStream using the specified CompressionMode and the specified CompressionLevel. + + + + + + When mode is CompressionMode.Decompress, the level parameter is + ignored. The "captive" stream will be closed when the DeflateStream is + closed. + + + + + + + This example uses a DeflateStream to compress data from a file, and writes + the compressed data to another file. + + + 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); + } + } + } + } + + + + 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 + + + The stream to be read or written while deflating or inflating. + Indicates whether the DeflateStream will compress or decompress. + A tuning knob to trade speed for effectiveness. + + + + Create a DeflateStream using the specified + CompressionMode, and explicitly specify whether the + stream should be left open after Deflation or Inflation. + + + + + + This constructor allows the application to request that the captive stream + remain open after the deflation or inflation occurs. By default, after + Close() 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 parameter to leave the stream open. + + + + The DeflateStream will use the default compression level. + + + + See the other overloads of this constructor for example code. + + + + + The stream which will be read or written. This is called the + "captive" stream in other places in this documentation. + + + + Indicates whether the DeflateStream will compress or decompress. + + + true if the application would like the stream to + remain open after inflation/deflation. + + + + Create a DeflateStream using the specified CompressionMode + and the specified CompressionLevel, and explicitly specify whether + the stream should be left open after Deflation or Inflation. + + + + + + When mode is CompressionMode.Decompress, the level parameter is ignored. + + + + This constructor allows the application to request that the captive stream + remain open after the deflation or inflation occurs. By default, after + Close() 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 + that will be re-read after + compression. Specify true for the parameter + to leave the stream open. + + + + + + + This example shows how to use a DeflateStream to compress data from + a file, and store the compressed data into another file. + + + 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 + } + + + + 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 + + + The stream which will be read or written. + Indicates whether the DeflateStream will compress or decompress. + true if the application would like the stream to remain open after inflation/deflation. + A tuning knob to trade speed for effectiveness. + + + + This property sets the flush behavior on the stream. + + See the ZLIB documentation for the meaning of the flush behavior. + + + + + The size of the working buffer for the compression codec. + + + + + 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. + + + + Set this before the first call to Read() or Write() on the + stream. If you try to set it afterwards, it will throw. + + + + + + The ZLIB strategy to be used during compression. + + + + By tweaking this parameter, you may be able to optimize the compression for + data with particular characteristics. + + + + Returns the total number of bytes input so far. + + + Returns the total number of bytes output so far. + + + + Dispose the stream. + + + + This may or may not result in a Close() call on the captive + stream. See the constructors that have a leaveOpen parameter + for more information. + + + 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. + + + + true if the Dispose method was invoked by user code. + + + + + Indicates whether the stream can be read. + + + The return value depends on whether the captive stream supports reading. + + + + + Indicates whether the stream supports Seek operations. + + + Always returns false. + + + + + Indicates whether the stream can be written. + + + The return value depends on whether the captive stream supports writing. + + + + + Flush the stream. + + + + + Reading this property always throws a . + + + + + The position of the stream pointer. + + + + Setting this property always throws a . 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. + + + + + Read data from the stream. + + + + + If you wish to use the DeflateStream to compress data while + reading, you can create a DeflateStream with + CompressionMode.Compress, providing an uncompressed data stream. + Then call Read() on that DeflateStream, and the data read will be + compressed as you read. If you wish to use the DeflateStream to + decompress data while reading, you can create a DeflateStream with + CompressionMode.Decompress, providing a readable compressed data + stream. Then call Read() on that DeflateStream, and the data read + will be decompressed as you read. + + + + A DeflateStream can be used for Read() or Write(), but not both. + + + + The buffer into which the read data should be placed. + the offset within that data array to put the first byte read. + the number of bytes to read. + the number of bytes actually read + + + + Calling this method always throws a . + + this is irrelevant, since it will always throw! + this is irrelevant, since it will always throw! + irrelevant! + + + + Calling this method always throws a . + + this is irrelevant, since it will always throw! + + + + Write data to the stream. + + + + + If you wish to use the DeflateStream to compress data while + writing, you can create a DeflateStream with + CompressionMode.Compress, and a writable output stream. Then call + Write() on that DeflateStream, 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 DeflateStream to + decompress data while writing, you can create a DeflateStream with + CompressionMode.Decompress, and a writable output stream. Then + call Write() on that stream, providing previously compressed + data. The data sent to the output stream will be the decompressed form of + the data written. + + + + A DeflateStream can be used for Read() or Write(), + but not both. + + + + + The buffer holding data to write to the stream. + the offset within that data array to find the first byte to write. + the number of bytes to write. + + + + Compress a string into a byte array using DEFLATE (RFC 1951). + + + + Uncompress it with . + + + DeflateStream.UncompressString(byte[]) + DeflateStream.CompressBuffer(byte[]) + GZipStream.CompressString(string) + ZlibStream.CompressString(string) + + + A string to compress. The string will first be encoded + using UTF8, then compressed. + + + The string in compressed form + + + + Compress a byte array into a new byte array using DEFLATE. + + + + Uncompress it with . + + + DeflateStream.CompressString(string) + DeflateStream.UncompressBuffer(byte[]) + GZipStream.CompressBuffer(byte[]) + ZlibStream.CompressBuffer(byte[]) + + + A buffer to compress. + + + The data in compressed form + + + + Uncompress a DEFLATE'd byte array into a single string. + + + DeflateStream.CompressString(String) + DeflateStream.UncompressBuffer(byte[]) + GZipStream.UncompressString(byte[]) + ZlibStream.UncompressString(byte[]) + + + A buffer containing DEFLATE-compressed data. + + + The uncompressed string + + + + Uncompress a DEFLATE'd byte array into a byte array. + + + DeflateStream.CompressBuffer(byte[]) + DeflateStream.UncompressString(byte[]) + GZipStream.UncompressBuffer(byte[]) + ZlibStream.UncompressBuffer(byte[]) + + + A buffer containing data that has been compressed with DEFLATE. + + + The data in uncompressed form + + + + A class for compressing and decompressing GZIP streams. + + + + + The GZipStream is a Decorator on a + . It adds GZIP compression or decompression to any + stream. + + + + Like the System.IO.Compression.GZipStream in the .NET Base Class Library, the + Ionic.Zlib.GZipStream can compress while writing, or decompress while + reading, but not vice versa. The compression method used is GZIP, which is + documented in IETF RFC + 1952, "GZIP file format specification version 4.3". + + + A GZipStream can be used to decompress data (through Read()) or + to compress data (through Write()), but not both. + + + + If you wish to use the GZipStream to compress data, you must wrap it + around a write-able stream. As you call Write() on the GZipStream, the + data will be compressed into the GZIP format. If you want to decompress data, + you must wrap the GZipStream around a readable stream that contains an + IETF RFC 1952-compliant stream. The data will be decompressed as you call + Read() on the GZipStream. + + + + 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. + + + + This class is similar to and . + ZlibStream handles RFC1950-compliant streams. + handles RFC1951-compliant streams. This class handles RFC1952-compliant streams. + + + + + + + + + + The comment on the GZIP stream. + + + + + 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 Write() for the first time on the + GZipStream. + + + + When using GZipStream to decompress, you can retrieve this property + after the first call to Read(). If no comment has been set in the + GZIP bytestream, the Comment property will return null + (Nothing in VB). + + + + + + The FileName for the GZIP stream. + + + + + + The GZIP format optionally allows each file to have an associated + filename. When compressing data (through Write()), set this + FileName before calling Write() the first time on the GZipStream. + 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. + + + + When decompressing (through Read()), you can retrieve this value + any time after the first Read(). In the case where there was no filename + encoded into the GZIP bytestream, the property will return null (Nothing + in VB). + + + + + + The last modified time for the GZIP stream. + + + + 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 + Write(). When decompressing, you can retrieve this value any time + after the first call to Read(). + + + + + The CRC on the GZIP stream. + + + This is used for internal error checking. You probably don't need to look at this property. + + + + + Create a GZipStream using the specified CompressionMode. + + + + + When mode is CompressionMode.Compress, the GZipStream will use the + default compression level. + + + + As noted in the class documentation, the CompressionMode (Compress + or Decompress) also establishes the "direction" of the stream. A + GZipStream with CompressionMode.Compress works only through + Write(). A GZipStream with + CompressionMode.Decompress works only through Read(). + + + + + + This example shows how to use a GZipStream to compress data. + + 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); + } + } + } + } + + + 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 + + + + + This example shows how to use a GZipStream to uncompress a file. + + 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); + } + } + } + } + } + } + + + + 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 + + + + The stream which will be read or written. + Indicates whether the GZipStream will compress or decompress. + + + + Create a GZipStream using the specified CompressionMode and + the specified CompressionLevel. + + + + + The CompressionMode (Compress or Decompress) also establishes the + "direction" of the stream. A GZipStream with + CompressionMode.Compress works only through Write(). A + GZipStream with CompressionMode.Decompress works only + through Read(). + + + + + + + This example shows how to use a GZipStream to compress a file into a .gz file. + + + 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); + } + } + } + } + + + + 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 + + + The stream to be read or written while deflating or inflating. + Indicates whether the GZipStream will compress or decompress. + A tuning knob to trade speed for effectiveness. + + + + Create a GZipStream using the specified CompressionMode, and + explicitly specify whether the stream should be left open after Deflation + or Inflation. + + + + + This constructor allows the application to request that the captive stream + remain open after the deflation or inflation occurs. By default, after + Close() 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 parameter to leave + the stream open. + + + + The (Compress or Decompress) also + establishes the "direction" of the stream. A GZipStream with + CompressionMode.Compress works only through Write(). A GZipStream + with CompressionMode.Decompress works only through Read(). + + + + The GZipStream will use the default compression level. If you want + to specify the compression level, see . + + + + See the other overloads of this constructor for example code. + + + + + + The stream which will be read or written. This is called the "captive" + stream in other places in this documentation. + + + Indicates whether the GZipStream will compress or decompress. + + + + true if the application would like the base stream to remain open after + inflation/deflation. + + + + + Create a GZipStream using the specified CompressionMode and the + specified CompressionLevel, and explicitly specify whether the + stream should be left open after Deflation or Inflation. + + + + + + This constructor allows the application to request that the captive stream + remain open after the deflation or inflation occurs. By default, after + Close() 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 parameter to + leave the stream open. + + + + As noted in the class documentation, the CompressionMode (Compress + or Decompress) also establishes the "direction" of the stream. A + GZipStream with CompressionMode.Compress works only through + Write(). A GZipStream with CompressionMode.Decompress works only + through Read(). + + + + + + This example shows how to use a GZipStream to compress data. + + 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); + } + } + } + } + + + 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 + + + The stream which will be read or written. + Indicates whether the GZipStream will compress or decompress. + true if the application would like the stream to remain open after inflation/deflation. + A tuning knob to trade speed for effectiveness. + + + + This property sets the flush behavior on the stream. + + + + + The size of the working buffer for the compression codec. + + + + + 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. + + + + Set this before the first call to Read() or Write() on the + stream. If you try to set it afterwards, it will throw. + + + + + Returns the total number of bytes input so far. + + + Returns the total number of bytes output so far. + + + + Dispose the stream. + + + + This may or may not result in a Close() call on the captive + stream. See the constructors that have a leaveOpen parameter + for more information. + + + 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. + + + + indicates whether the Dispose method was invoked by user code. + + + + + Indicates whether the stream can be read. + + + The return value depends on whether the captive stream supports reading. + + + + + Indicates whether the stream supports Seek operations. + + + Always returns false. + + + + + Indicates whether the stream can be written. + + + The return value depends on whether the captive stream supports writing. + + + + + Flush the stream. + + + + + Reading this property always throws a . + + + + + The position of the stream pointer. + + + + Setting this property always throws a . 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. + + + + + Read and decompress data from the source stream. + + + + With a GZipStream, decompression is done through reading. + + + + + 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); + } + } + } + } + + + The buffer into which the decompressed data should be placed. + the offset within that data array to put the first byte read. + the number of bytes to read. + the number of bytes actually read + + + + Calling this method always throws a . + + irrelevant; it will always throw! + irrelevant; it will always throw! + irrelevant! + + + + Calling this method always throws a . + + irrelevant; this method will always throw! + + + + Write data to the stream. + + + + + If you wish to use the GZipStream to compress data while writing, + you can create a GZipStream with CompressionMode.Compress, and a + writable output stream. Then call Write() on that GZipStream, + providing uncompressed data as input. The data sent to the output stream + will be the compressed form of the data written. + + + + A GZipStream can be used for Read() or Write(), but not + both. Writing implies compression. Reading implies decompression. + + + + The buffer holding data to write to the stream. + the offset within that data array to find the first byte to write. + the number of bytes to write. + + + + Compress a string into a byte array using GZip. + + + + Uncompress it with . + + + + + + + A string to compress. The string will first be encoded + using UTF8, then compressed. + + + The string in compressed form + + + + Compress a byte array into a new byte array using GZip. + + + + Uncompress it with . + + + + + + + A buffer to compress. + + + The data in compressed form + + + + Uncompress a GZip'ed byte array into a single string. + + + + + + + A buffer containing GZIP-compressed data. + + + The uncompressed string + + + + Uncompress a GZip'ed byte array into a byte array. + + + + + + + A buffer containing data that has been compressed with GZip. + + + The data in uncompressed form + + + + A class for compressing streams using the + Deflate algorithm with multiple threads. + + + + + 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." + + + + This class is similar to , 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. + + + + 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. + + + + + + + + Create a ParallelDeflateOutputStream. + + + + + This stream compresses data written into it via the DEFLATE + algorithm (see RFC 1951), and writes out the compressed byte stream. + + + + The instance will use the default compression level, the default + buffer sizes and the default number of threads and buffers per + thread. + + + + This class is similar to , + 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. + + + + + + + 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. + + + 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); + } + } + } + } + + + 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 + + + The stream to which compressed data will be written. + + + + Create a ParallelDeflateOutputStream using the specified CompressionLevel. + + + See the + constructor for example code. + + The stream to which compressed data will be written. + A tuning knob to trade speed for effectiveness. + + + + Create a ParallelDeflateOutputStream and specify whether to leave the captive stream open + when the ParallelDeflateOutputStream is closed. + + + See the + constructor for example code. + + The stream to which compressed data will be written. + + true if the application would like the stream to remain open after inflation/deflation. + + + + + Create a ParallelDeflateOutputStream and specify whether to leave the captive stream open + when the ParallelDeflateOutputStream is closed. + + + See the + constructor for example code. + + The stream to which compressed data will be written. + A tuning knob to trade speed for effectiveness. + + true if the application would like the stream to remain open after inflation/deflation. + + + + + Create a ParallelDeflateOutputStream using the specified + CompressionLevel and CompressionStrategy, and specifying whether to + leave the captive stream open when the ParallelDeflateOutputStream is + closed. + + + See the + constructor for example code. + + The stream to which compressed data will be written. + A tuning knob to trade speed for effectiveness. + + By tweaking this parameter, you may be able to optimize the compression for + data with particular characteristics. + + + true if the application would like the stream to remain open after inflation/deflation. + + + + + The ZLIB strategy to be used during compression. + + + + + + The maximum number of buffer pairs to use. + + + + + 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 + ThreadPool.QueueUserWorkItem() + to compress those buffers in a background threadpool thread. After a + buffer is compressed, it is re-ordered and written to the output + stream. + + + + 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. + + + + 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 (). 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. + + + + 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. + + + + 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. + + + + 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. + + + + 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. + + + + + + The size of the buffers used by the compressor threads. + + + + + The default buffer size is 128k. The application can set this value + at any time, but it is effective only before the first Write(). + + + + 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 . 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 + DeflateStream. 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. + + + + 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. + + + + + + + The CRC32 for the data that was written out, prior to compression. + + + This value is meaningful only after a call to Close(). + + + + + The total number of uncompressed bytes processed by the ParallelDeflateOutputStream. + + + This value is meaningful only after a call to Close(). + + + + + Write data to the stream. + + + + + + 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. + + + + To decompress data, use the class. + + + + The buffer holding data to write to the stream. + the offset within that data array to find the first byte to write. + the number of bytes to write. + + + + Flush the stream. + + + + + Close the stream. + + + 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. + + + + Dispose the object + + + Because ParallelDeflateOutputStream is IDisposable, the + application must call this method when finished using the instance. + + + This method is generally called implicitly upon exit from + a using scope in C# (Using in VB). + + + + + The Dispose method + + indicates whether the Dispose method was invoked by user code. + + + + + Resets the stream for use with another stream. + + + 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. + + + + The new output stream for this era. + + + + + 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); + } + } + } + } + + + + + + Indicates whether the stream supports Seek operations. + + + Always returns false. + + + + + Indicates whether the stream supports Read operations. + + + Always returns false. + + + + + Indicates whether the stream supports Write operations. + + + Returns true if the provided stream is writable. + + + + + Reading this property always throws a NotSupportedException. + + + + + Returns the current position of the output stream. + + + + Because the output gets written by a background thread, + the value may change asynchronously. Setting this + property always throws a NotSupportedException. + + + + + + This method always throws a NotSupportedException. + + + The buffer into which data would be read, IF THIS METHOD + ACTUALLY DID ANYTHING. + + + The offset within that data array at which to insert the + data that is read, IF THIS METHOD ACTUALLY DID + ANYTHING. + + + The number of bytes to write, IF THIS METHOD ACTUALLY DID + ANYTHING. + + nothing. + + + + This method always throws a NotSupportedException. + + + The offset to seek to.... + IF THIS METHOD ACTUALLY DID ANYTHING. + + + The reference specifying how to apply the offset.... IF + THIS METHOD ACTUALLY DID ANYTHING. + + nothing. It always throws. + + + + This method always throws a NotSupportedException. + + + The new value for the stream length.... IF + THIS METHOD ACTUALLY DID ANYTHING. + + + + + Map from a distance to a distance code. + + + No side effects. _dist_code[256] and _dist_code[257] are never used. + + + + + Describes how to flush the current deflate operation. + + + The different FlushType values are useful when using a Deflate in a streaming application. + + + + No flush at all. + + + 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. + + + + + 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, AvailableBytesIn 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. + + + + + Use this during compression to specify that all output should be flushed, as + with FlushType.Sync, 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 + FlushType.Full too often can significantly degrade the compression. + + + + Signals the end of the compression/decompression stream. + + + + The compression level to be used when using a DeflateStream or ZlibStream with CompressionMode.Compress. + + + + + 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. + + + + + Same as None. + + + + + The fastest but least effective compression. + + + + + A synonym for BestSpeed. + + + + + A little slower, but better, than level 1. + + + + + A little slower, but better, than level 2. + + + + + A little slower, but better, than level 3. + + + + + A little slower than level 4, but with better compression. + + + + + The default compression level, with a good balance of speed and compression efficiency. + + + + + A synonym for Default. + + + + + Pretty good compression! + + + + + Better compression than Level7! + + + + + The "best" compression, where best means greatest reduction in size of the input data stream. + This is also the slowest compression. + + + + + A synonym for BestCompression. + + + + + 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. + + + + + The default strategy is probably the best for normal data. + + + + + The Filtered 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 Filtered is to force more Huffman + coding and less string matching; it is a half-step between Default and HuffmanOnly. + + + + + Using HuffmanOnly will force the compressor to do Huffman encoding only, with no + string matching. + + + + + An enum to specify the direction of transcoding - whether to compress or decompress. + + + + + Used to specify that the stream should compress the data. + + + + + Used to specify that the stream should decompress the data. + + + + + A general purpose exception class for exceptions in the Zlib library. + + + + + The ZlibException class captures exception information generated + by the Zlib library. + + + + + This ctor collects a message attached to the exception. + + the message for the exception. + + + + Performs an unsigned bitwise right shift with the specified number + + Number to operate on + Ammount of bits to shift + The resulting number from the shift operation + + + + Reads a number of characters from the current source TextReader and writes + the data to the target array at the specified index. + + + The source TextReader to read from + Contains the array of characteres read from the source TextReader. + The starting index of the target array. + The maximum number of characters to read from the source TextReader. + + + 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. + + + + + Computes an Adler-32 checksum. + + + 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. + + + + + + + Calculates the Adler32 checksum. + + + + This is used within ZLIB. You probably don't need to use this directly. + + + + To compute an Adler32 checksum on a byte array: + + var adler = Adler.Adler32(0, null, 0, 0); + adler = Adler.Adler32(adler, buffer, index, length); + + + + + + Encoder and Decoder for ZLIB and DEFLATE (IETF RFC1950 and RFC1951). + + + + This class compresses and decompresses data according to the Deflate algorithm + and optionally, the ZLIB format, as documented in RFC 1950 - ZLIB and RFC 1951 - DEFLATE. + + + + + The buffer from which data is taken. + + + + + An index into the InputBuffer array, indicating where to start reading. + + + + + The number of bytes available in the InputBuffer, starting at NextIn. + + + 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. + + + + + Total number of bytes read so far, through all calls to Inflate()/Deflate(). + + + + + Buffer to store output data. + + + + + An index into the OutputBuffer array, indicating where to start writing. + + + + + The number of bytes available in the OutputBuffer, starting at NextOut. + + + 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. + + + + + Total number of bytes written to the output so far, through all calls to Inflate()/Deflate(). + + + + + used for diagnostics, when something goes wrong! + + + + + The compression level to use in this codec. Useful only in compression mode. + + + + + The number of Window Bits to use. + + + 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. + + + + + The compression strategy to use. + + + 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. + + + + + The Adler32 checksum on the data transferred through the codec so far. You probably don't need to look at this. + + + + + Create a ZlibCodec. + + + If you use this default constructor, you will later have to explicitly call + InitializeInflate() or InitializeDeflate() before using the ZlibCodec to compress + or decompress. + + + + + Create a ZlibCodec that either compresses or decompresses. + + + Indicates whether the codec should compress (deflate) or decompress (inflate). + + + + + Initialize the inflation state. + + + It is not necessary to call this before using the ZlibCodec to inflate data; + It is implicitly called when you call the constructor. + + Z_OK if everything goes well. + + + + Initialize the inflation state with an explicit flag to + govern the handling of RFC1950 header bytes. + + + + By default, the ZLIB header defined in RFC 1950 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. + + + whether to expect an RFC1950 header byte + pair when reading the stream of data to be inflated. + + Z_OK if everything goes well. + + + + Initialize the ZlibCodec for inflation, with the specified number of window bits. + + The number of window bits to use. If you need to ask what that is, + then you shouldn't be calling this initializer. + Z_OK if all goes well. + + + + Initialize the inflation state with an explicit flag to govern the handling of + RFC1950 header bytes. + + + + 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 RFC + 1950, 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. + + + whether to expect an RFC1950 header byte pair when reading + the stream of data to be inflated. + The number of window bits to use. If you need to ask what that is, + then you shouldn't be calling this initializer. + Z_OK if everything goes well. + + + + Inflate the data in the InputBuffer, placing the result in the OutputBuffer. + + + You must have set InputBuffer and OutputBuffer, NextIn and NextOut, and AvailableBytesIn and + AvailableBytesOut before calling this method. + + + + 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(); + } + + + + The flush to use when inflating. + Z_OK if everything goes well. + + + + Ends an inflation session. + + + 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. + + Z_OK if everything goes well. + + + + I don't know what this does! + + Z_OK if everything goes well. + + + + Initialize the ZlibCodec for deflation operation. + + + The codec will use the MAX window bits and the default level of compression. + + + + 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(); + + + + Z_OK if all goes well. You generally don't need to check the return code. + + + + Initialize the ZlibCodec for deflation operation, using the specified CompressionLevel. + + + The codec will use the maximum window bits (15) and the specified + CompressionLevel. It will emit a ZLIB stream as it compresses. + + The compression level for the codec. + Z_OK if all goes well. + + + + Initialize the ZlibCodec for deflation operation, using the specified CompressionLevel, + and the explicit flag governing whether to emit an RFC1950 header byte pair. + + + 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 RFC + 1950, in the compressed stream. + + The compression level for the codec. + whether to emit an initial RFC1950 byte pair in the compressed stream. + Z_OK if all goes well. + + + + Initialize the ZlibCodec for deflation operation, using the specified CompressionLevel, + and the specified number of window bits. + + + The codec will use the specified number of window bits and the specified CompressionLevel. + + The compression level for the codec. + the number of window bits to use. If you don't know what this means, don't use this method. + Z_OK if all goes well. + + + + 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. + + + The compression level for the codec. + whether to emit an initial RFC1950 byte pair in the compressed stream. + the number of window bits to use. If you don't know what this means, don't use this method. + Z_OK if all goes well. + + + + Deflate one batch of data. + + + You must have set InputBuffer and OutputBuffer before calling this method. + + + + 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); + } + + + 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. + + Z_OK if all goes well. + + + + End a deflation session. + + + Call this after making a series of one or more calls to Deflate(). All buffers are flushed. + + Z_OK if all goes well. + + + + Reset a codec for another deflation session. + + + 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. + + Z_OK if all goes well. + + + + Set the CompressionStrategy and CompressionLevel for a deflation session. + + the level of compression to use. + the strategy to use for compression. + Z_OK if all goes well. + + + + Set the dictionary to be used for either Inflation or Deflation. + + The dictionary bytes to use. + Z_OK if all goes well. + + + + A bunch of constants used in the Zlib interface. + + + + + The maximum number of window bits for the Deflate algorithm. + + + + + The default number of window bits for the Deflate algorithm. + + + + + indicates everything is A-OK + + + + + Indicates that the last operation reached the end of the stream. + + + + + The operation ended in need of a dictionary. + + + + + There was an error with the stream - not enough data, not open and readable, etc. + + + + + There was an error with the data - not enough data, bad data, etc. + + + + + There was an error with the working buffer. + + + + + The size of the working buffer used in the ZlibCodec class. + + + + + The minimum size of the working buffer used in the ZlibCodec class. + + + + + Represents a Zlib stream for compression or decompression. + + + + + The ZlibStream is a Decorator on a . It adds ZLIB compression or decompression to any + stream. + + + Using this stream, applications can compress or decompress data via + stream Read() and Write() operations. Either compresssion or + decompression can occur through either reading or writing. The compression + format used is ZLIB, which is documented in IETF RFC 1950, "ZLIB Compressed + Data Format Specification version 3.3". This implementation of ZLIB always uses + DEFLATE as the compression method. (see IETF RFC 1951, "DEFLATE + Compressed Data Format Specification version 1.3.") + + + 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. + + + + This class is similar to , 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 + . + + + + + + + + Create a ZlibStream using the specified CompressionMode. + + + + + When mode is CompressionMode.Compress, the ZlibStream + will use the default compression level. The "captive" stream will be + closed when the ZlibStream is closed. + + + + + + This example uses a ZlibStream to compress a file, and writes the + compressed data to another file. + + 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); + } + } + } + } + + + 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 + + + + The stream which will be read or written. + Indicates whether the ZlibStream will compress or decompress. + + + + Create a ZlibStream using the specified CompressionMode and + the specified CompressionLevel. + + + + + + When mode is CompressionMode.Decompress, the level parameter is ignored. + The "captive" stream will be closed when the ZlibStream is closed. + + + + + + This example uses a ZlibStream to compress data from a file, and writes the + compressed data to another file. + + + 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); + } + } + } + } + + + + 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 + + + + The stream to be read or written while deflating or inflating. + Indicates whether the ZlibStream will compress or decompress. + A tuning knob to trade speed for effectiveness. + + + + Create a ZlibStream using the specified CompressionMode, and + explicitly specify whether the captive stream should be left open after + Deflation or Inflation. + + + + + + When mode is CompressionMode.Compress, the ZlibStream will use + the default compression level. + + + + This constructor allows the application to request that the captive stream + remain open after the deflation or inflation occurs. By default, after + Close() 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 + that will be re-read after + compression. Specify true for the parameter to leave the stream + open. + + + + See the other overloads of this constructor for example code. + + + + + The stream which will be read or written. This is called the + "captive" stream in other places in this documentation. + Indicates whether the ZlibStream will compress or decompress. + true if the application would like the stream to remain + open after inflation/deflation. + + + + Create a ZlibStream using the specified CompressionMode + and the specified CompressionLevel, and explicitly specify + whether the stream should be left open after Deflation or Inflation. + + + + + + This constructor allows the application to request that the captive + stream remain open after the deflation or inflation occurs. By + default, after Close() 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 that will be + re-read after compression. Specify true for the parameter to leave the stream open. + + + + When mode is CompressionMode.Decompress, the level parameter is + ignored. + + + + + + + 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. + + + 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 + } + + + 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 + + + + The stream which will be read or written. + + Indicates whether the ZlibStream will compress or decompress. + + + true if the application would like the stream to remain open after + inflation/deflation. + + + + A tuning knob to trade speed for effectiveness. This parameter is + effective only when mode is CompressionMode.Compress. + + + + + This property sets the flush behavior on the stream. + Sorry, though, not sure exactly how to describe all the various settings. + + + + + The size of the working buffer for the compression codec. + + + + + 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. + + + + Set this before the first call to Read() or Write() on the + stream. If you try to set it afterwards, it will throw. + + + + + Returns the total number of bytes input so far. + + + Returns the total number of bytes output so far. + + + + Dispose the stream. + + + + This may or may not result in a Close() call on the captive + stream. See the constructors that have a leaveOpen parameter + for more information. + + + 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. + + + + indicates whether the Dispose method was invoked by user code. + + + + + Indicates whether the stream can be read. + + + The return value depends on whether the captive stream supports reading. + + + + + Indicates whether the stream supports Seek operations. + + + Always returns false. + + + + + Indicates whether the stream can be written. + + + The return value depends on whether the captive stream supports writing. + + + + + Flush the stream. + + + + + Reading this property always throws a . + + + + + The position of the stream pointer. + + + + Setting this property always throws a . 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. + + + + + Read data from the stream. + + + + + + If you wish to use the ZlibStream to compress data while reading, + you can create a ZlibStream with CompressionMode.Compress, + providing an uncompressed data stream. Then call Read() on that + ZlibStream, and the data read will be compressed. If you wish to + use the ZlibStream to decompress data while reading, you can create + a ZlibStream with CompressionMode.Decompress, providing a + readable compressed data stream. Then call Read() on that + ZlibStream, and the data will be decompressed as it is read. + + + + A ZlibStream can be used for Read() or Write(), but + not both. + + + + + + The buffer into which the read data should be placed. + + + the offset within that data array to put the first byte read. + + the number of bytes to read. + + the number of bytes read + + + + Calling this method always throws a . + + + The offset to seek to.... + IF THIS METHOD ACTUALLY DID ANYTHING. + + + The reference specifying how to apply the offset.... IF + THIS METHOD ACTUALLY DID ANYTHING. + + + nothing. This method always throws. + + + + Calling this method always throws a . + + + The new value for the stream length.... IF + THIS METHOD ACTUALLY DID ANYTHING. + + + + + Write data to the stream. + + + + + + If you wish to use the ZlibStream to compress data while writing, + you can create a ZlibStream with CompressionMode.Compress, + and a writable output stream. Then call Write() on that + ZlibStream, 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 ZlibStream to decompress data while writing, you + can create a ZlibStream with CompressionMode.Decompress, and a + writable output stream. Then call Write() on that stream, + providing previously compressed data. The data sent to the output stream + will be the decompressed form of the data written. + + + + A ZlibStream can be used for Read() or Write(), but not both. + + + The buffer holding data to write to the stream. + the offset within that data array to find the first byte to write. + the number of bytes to write. + + + + Compress a string into a byte array using ZLIB. + + + + Uncompress it with . + + + + + + + + A string to compress. The string will first be encoded + using UTF8, then compressed. + + + The string in compressed form + + + + Compress a byte array into a new byte array using ZLIB. + + + + Uncompress it with . + + + + + + + A buffer to compress. + + + The data in compressed form + + + + Uncompress a ZLIB-compressed byte array into a single string. + + + + + + + A buffer containing ZLIB-compressed data. + + + The uncompressed string + + + + Uncompress a ZLIB-compressed byte array into a byte array. + + + + + + + A buffer containing ZLIB-compressed data. + + + The data in uncompressed form + + + diff --git a/packages/DotNetZip.1.13.3/lib/netstandard2.0/DotNetZip.dll b/packages/DotNetZip.1.13.3/lib/netstandard2.0/DotNetZip.dll new file mode 100644 index 0000000..63b5ccd Binary files /dev/null and b/packages/DotNetZip.1.13.3/lib/netstandard2.0/DotNetZip.dll differ diff --git a/packages/DotNetZip.1.13.3/lib/netstandard2.0/DotNetZip.pdb b/packages/DotNetZip.1.13.3/lib/netstandard2.0/DotNetZip.pdb new file mode 100644 index 0000000..c77f4a5 Binary files /dev/null and b/packages/DotNetZip.1.13.3/lib/netstandard2.0/DotNetZip.pdb differ diff --git a/packages/DotNetZip.1.13.3/lib/netstandard2.0/DotNetZip.xml b/packages/DotNetZip.1.13.3/lib/netstandard2.0/DotNetZip.xml new file mode 100644 index 0000000..549f424 --- /dev/null +++ b/packages/DotNetZip.1.13.3/lib/netstandard2.0/DotNetZip.xml @@ -0,0 +1,18022 @@ + + + + DotNetZip + + + + + Delivers the remaining bits, left-aligned, in a byte. + + + + This is valid only if NumRemainingBits is less than 8; + in other words it is valid only after a call to Flush(). + + + + + + Reset the BitWriter. + + + + 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. + + + + + + Write some number of bits from the given value, into the output. + + + + The nbits value should be a max of 25, for safety. For performance + reasons, this method does not check! + + + + + + Write a full 8-bit byte into the output. + + + + + Write four 8-bit bytes into the output. + + + + + Write all available byte-aligned bytes. + + + + This method writes no new output, but flushes any accumulated + bits. At completion, the accumulator may contain up to 7 + bits. + + + 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. + + + + + + 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. + + + + Knuth's increments seem to work better than Incerpi-Sedgewick here. + Possibly because the number of elems to sort is usually small, typically + <= 20. + + + + BZip2Compressor writes its compressed data out via a BitWriter. This + is necessary because BZip2 does byte shredding. + + + + + The number of uncompressed bytes being held in the buffer. + + + + 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. + + + + + + Accept new bytes into the compressor data buffer + + + + This method does the first-level (cheap) run-length encoding, and + stores the encoded data into the rle block. + + + + + + Process one input byte into the block. + + + + + 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. + + + + 0 if the byte was not written, non-zero if written. + + + + Append one run to the output block. + + + + + 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. + + + true if the block is now full; otherwise false. + + + + Compress the data that has been placed (Run-length-encoded) into the + block. The compressed data goes into the CompressedBytes array. + + + + Side effects: 1. fills the CompressedBytes array. 2. sets the + AvailableBytesOut property. + + + + + This is the most hammered method of this class. + +

+ This is the version using unrolled loops. +

+ + + Method "mainQSort3", file "blocksort.c", BZip2 1.0.2 + + + Array instance identical to sfmap, both are used only + temporarily and independently, so we do not need to allocate + additional memory. + + + + A read-only decorator stream that performs BZip2 decompression on Read. + + + + + Compressor State + + + + + Create a BZip2InputStream, wrapping it around the given input Stream. + + + + The input stream will be closed when the BZip2InputStream is closed. + + + The stream from which to read compressed data + + + + Create a BZip2InputStream with the given stream, and + specifying whether to leave the wrapped stream open when + the BZip2InputStream is closed. + + The stream from which to read compressed data + + Whether to leave the input stream open, when the BZip2InputStream closes. + + + + + This example reads a bzip2-compressed file, decompresses it, + and writes the decompressed data into a newly created file. + + + 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); + } + } + } + } + + + + + + Read data from the stream. + + + + + To decompress a BZip2 data stream, create a BZip2InputStream, + providing a stream that reads compressed data. Then call Read() on + that BZip2InputStream, and the data read will be decompressed + as you read. + + + + A BZip2InputStream can be used only for Read(), not for Write(). + + + + The buffer into which the read data should be placed. + the offset within that data array to put the first byte read. + the number of bytes to read. + the number of bytes actually read + + + + Read a single byte from the stream. + + the byte read from the stream, or -1 if EOF + + + + Indicates whether the stream can be read. + + + The return value depends on whether the captive stream supports reading. + + + + + Indicates whether the stream supports Seek operations. + + + Always returns false. + + + + + Indicates whether the stream can be written. + + + The return value depends on whether the captive stream supports writing. + + + + + Flush the stream. + + + + + Reading this property always throws a . + + + + + The position of the stream pointer. + + + + Setting this property always throws a . Reading will return the + total number of uncompressed bytes read in. + + + + + Calling this method always throws a . + + this is irrelevant, since it will always throw! + this is irrelevant, since it will always throw! + irrelevant! + + + + Calling this method always throws a . + + this is irrelevant, since it will always throw! + + + + Calling this method always throws a . + + this parameter is never used + this parameter is never used + this parameter is never used + + + + Dispose the stream. + + + indicates whether the Dispose method was invoked by user code. + + + + + Close the stream. + + + + + Read n bits from input, right justifying the result. + + + + For example, if you read 1 bit, the result is either 0 + or 1. + + + + The number of bits to read, always between 1 and 32. + + + + Called by createHuffmanDecodingTables() exclusively. + + + Called by recvDecodingTables() exclusively. + + + Freq table collected to save a pass over the data during + decompression. + + + 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. + + + + A write-only decorator stream that compresses data as it is + written using the BZip2 algorithm. + + + + + Constructs a new BZip2OutputStream, that sends its + compressed output to the given output stream. + + + + The destination stream, to which compressed output will be sent. + + + + + This example reads a file, then compresses it with bzip2 file, + and writes the compressed data into a newly created file. + + + 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); + } + } + } + } + + + + + + Constructs a new BZip2OutputStream with specified blocksize. + + the destination stream. + + The blockSize in units of 100000 bytes. + The valid range is 1..9. + + + + + Constructs a new BZip2OutputStream. + + the destination stream. + + whether to leave the captive stream open upon closing this stream. + + + + + Constructs a new BZip2OutputStream with specified blocksize, + and explicitly specifies whether to leave the wrapped stream open. + + + the destination stream. + + The blockSize in units of 100000 bytes. + The valid range is 1..9. + + + whether to leave the captive stream open upon closing this stream. + + + + + Close the stream. + + + + This may or may not close the underlying stream. Check the + constructors that accept a bool value. + + + + + + Flush the stream. + + + + + The blocksize parameter specified at construction time. + + + + + Write data to the stream. + + + + + Use the BZip2OutputStream to compress data while writing: + create a BZip2OutputStream with a writable output stream. + Then call Write() on that BZip2OutputStream, providing + uncompressed data as input. The data sent to the output stream will + be the compressed form of the input data. + + + + A BZip2OutputStream can be used only for Write() not for Read(). + + + + + The buffer holding data to write to the stream. + the offset within that data array to find the first byte to write. + the number of bytes to write. + + + + Indicates whether the stream can be read. + + + The return value is always false. + + + + + Indicates whether the stream supports Seek operations. + + + Always returns false. + + + + + Indicates whether the stream can be written. + + + The return value should always be true, unless and until the + object is disposed and closed. + + + + + Reading this property always throws a . + + + + + The position of the stream pointer. + + + + Setting this property always throws a . Reading will return the + total number of uncompressed bytes written through. + + + + + Calling this method always throws a . + + this is irrelevant, since it will always throw! + this is irrelevant, since it will always throw! + irrelevant! + + + + Calling this method always throws a . + + this is irrelevant, since it will always throw! + + + + Calling this method always throws a . + + this parameter is never used + this parameter is never used + this parameter is never used + never returns anything; always throws + + + + A write-only decorator stream that compresses data as it is + written using the BZip2 algorithm. This stream compresses by + block using multiple threads. + + + This class performs BZIP2 compression through writing. For + more information on the BZIP2 algorithm, see + . + + + + This class is similar to , + 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. + + + + The tradeoff is that this class uses more memory and more CPU than the + vanilla BZip2OutputStream. Also, for small files, the + ParallelBZip2OutputStream can be much slower than the vanilla + BZip2OutputStream, because of the overhead associated to using the + thread pool. + + + + + + + Constructs a new ParallelBZip2OutputStream, that sends its + compressed output to the given output stream. + + + + The destination stream, to which compressed output will be sent. + + + + + This example reads a file, then compresses it with bzip2 file, + and writes the compressed data into a newly created file. + + + 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); + } + } + } + } + + + + + + Constructs a new ParallelBZip2OutputStream with specified blocksize. + + the destination stream. + + The blockSize in units of 100000 bytes. + The valid range is 1..9. + + + + + Constructs a new ParallelBZip2OutputStream. + + the destination stream. + + whether to leave the captive stream open upon closing this stream. + + + + + Constructs a new ParallelBZip2OutputStream with specified blocksize, + and explicitly specifies whether to leave the wrapped stream open. + + + the destination stream. + + The blockSize in units of 100000 bytes. + The valid range is 1..9. + + + whether to leave the captive stream open upon closing this stream. + + + + + The maximum number of concurrent compression worker threads to use. + + + + + 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 + ThreadPool.QueueUserWorkItem(), 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. + + + + 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. + + + + 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. + + + + 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 property. + + + + 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. + + + + 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. + + + + 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. + + + + + + Close the stream. + + + + This may or may not close the underlying stream. Check the + constructors that accept a bool value. + + + + + + Flush the stream. + + + + + The blocksize parameter specified at construction time. + + + + + Write data to the stream. + + + + + Use the ParallelBZip2OutputStream to compress data while + writing: create a ParallelBZip2OutputStream with a writable + output stream. Then call Write() on that + ParallelBZip2OutputStream, providing uncompressed data as + input. The data sent to the output stream will be the compressed + form of the input data. + + + + A ParallelBZip2OutputStream can be used only for + Write() not for Read(). + + + + + The buffer holding data to write to the stream. + the offset within that data array to find the first byte to write. + the number of bytes to write. + + + + Indicates whether the stream can be read. + + + The return value is always false. + + + + + Indicates whether the stream supports Seek operations. + + + Always returns false. + + + + + Indicates whether the stream can be written. + + + The return value depends on whether the captive stream supports writing. + + + + + Reading this property always throws a . + + + + + The position of the stream pointer. + + + + Setting this property always throws a . Reading will return the + total number of uncompressed bytes written through. + + + + + The total number of bytes written out by the stream. + + + This value is meaningful only after a call to Close(). + + + + + Calling this method always throws a . + + this is irrelevant, since it will always throw! + this is irrelevant, since it will always throw! + irrelevant! + + + + Calling this method always throws a . + + this is irrelevant, since it will always throw! + + + + Calling this method always throws a . + + this parameter is never used + this parameter is never used + this parameter is never used + never returns anything; always throws + + + + Returns the "random" number at a specific index. + + the index + the random number + + + + 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. + + + This type is used internally by DotNetZip; it is generally not used + directly by applications wishing to create, read, or manipulate zip + archive files. + + + + + Indicates the total number of bytes applied to the CRC. + + + + + Indicates the current CRC for all blocks slurped in. + + + + + Returns the CRC32 for the specified stream. + + The stream over which to calculate the CRC32 + the CRC32 calculation + + + + Returns the CRC32 for the specified stream, and writes the input into the + output stream. + + The stream over which to calculate the CRC32 + The stream into which to deflate the input + the CRC32 calculation + + + + Get the CRC32 for the given (word,byte) combo. This is a + computation defined by PKzip for PKZIP 2.0 (weak) encryption. + + The word to start with. + The byte to combine it with. + The CRC-ized result. + + + + Update the value for the running CRC32 using the given block of bytes. + This is useful when using the CRC32() class in a Stream. + + block of bytes to slurp + starting point in the block + how many bytes within the block to slurp + + + + Process one byte in the CRC. + + the byte to include into the CRC . + + + + Process a run of N identical bytes into the CRC. + + + + 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. + + + the byte to include into the CRC. + the number of times that byte should be repeated. + + + + Combines the given CRC32 value with the current running total. + + + 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. + + the crc value to be combined with this one + the length of data the CRC value was calculated on + + + + Create an instance of the CRC32 class using the default settings: no + bit reversal, and a polynomial of 0xEDB88320. + + + + + Create an instance of the CRC32 class, specifying whether to reverse + data bits or not. + + + specify true if the instance should reverse data bits. + + + + 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. + + + + + + Create an instance of the CRC32 class, specifying the polynomial and + whether to reverse data bits or not. + + + 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. + + + specify true if the instance should reverse data bits. + + + + + 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 reverseBits 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 + reverseBits parameter. + + + + + + Reset the CRC-32 class - clear the CRC "remainder register." + + + + Use this when employing a single instance of this class to compute + multiple, distinct CRCs on multiple, distinct data blocks. + + + + + + A Stream that calculates a CRC32 (a checksum) on all bytes read, + or on all bytes written. + + + + + 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. + + + + This class is intended primarily for use internally by the + DotNetZip library. + + + + + + The default constructor. + + + + 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. + + + The underlying stream + + + + The constructor allows the caller to specify how to handle the + underlying stream at close. + + + + The stream uses the default CRC32 algorithm, which implies a + polynomial of 0xEDB88320. + + + The underlying stream + true to leave the underlying stream + open upon close of the CrcCalculatorStream; false otherwise. + + + + A constructor allowing the specification of the length of the stream + to read. + + + + The stream uses the default CRC32 algorithm, which implies a + polynomial of 0xEDB88320. + + + Instances returned from this constructor will leave the underlying + stream open upon Close(). + + + The underlying stream + The length of the stream to slurp + + + + 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(). + + + + The stream uses the default CRC32 algorithm, which implies a + polynomial of 0xEDB88320. + + + The underlying stream + The length of the stream to slurp + true to leave the underlying stream + open upon close of the CrcCalculatorStream; false otherwise. + + + + 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. + + + + The stream uses the specified CRC32 instance, which allows the + application to specify how the CRC gets calculated. + + + The underlying stream + The length of the stream to slurp + true to leave the underlying stream + open upon close of the CrcCalculatorStream; false otherwise. + the CRC32 instance to use to calculate the CRC32 + + + + Gets the total number of bytes run through the CRC32 calculator. + + + + This is either the total number of bytes read, or the total number of + bytes written, depending on the direction of this stream. + + + + + Provides the current CRC for all blocks slurped in. + + + + 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. + + + + + + Indicates whether the underlying stream will be left open when the + CrcCalculatorStream is Closed. + + + + Set this at any point before calling . + + + + + + Read from the stream + + the buffer to read + the offset at which to start + the number of bytes to read + the number of bytes actually read + + + + Write to the stream. + + the buffer from which to write + the offset at which to start writing + the number of bytes to write + + + + Indicates whether the stream supports reading. + + + + + Indicates whether the stream supports seeking. + + + + Always returns false. + + + + + + Indicates whether the stream supports writing. + + + + + Flush the stream. + + + + + Returns the length of the underlying stream. + + + + + The getter for this property returns the total bytes read. + If you use the setter, it will throw + . + + + + + Seeking is not supported on this stream. This method always throws + + + N/A + N/A + N/A + + + + This method always throws + + + N/A + + + + Closes the stream. + + + + + A class for compressing and decompressing streams using the Deflate algorithm. + + + + + + The DeflateStream is a Decorator on a . It adds DEFLATE compression or decompression to any + stream. + + + + Using this stream, applications can compress or decompress data via stream + Read and Write operations. Either compresssion or decompression + can occur through either reading or writing. The compression format used is + DEFLATE, which is documented in IETF RFC 1951, "DEFLATE + Compressed Data Format Specification version 1.3.". + + + + This class is similar to , except that + ZlibStream adds the RFC + 1950 - ZLIB framing bytes to a compressed stream when compressing, or + expects the RFC1950 framing bytes when decompressing. The DeflateStream + does not. + + + + + + + + + + Create a DeflateStream using the specified CompressionMode. + + + + When mode is CompressionMode.Compress, the DeflateStream will use + the default compression level. The "captive" stream will be closed when + the DeflateStream is closed. + + + + This example uses a DeflateStream to compress data from a file, and writes + the compressed data to another file. + + 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); + } + } + } + } + + + + 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 + + + The stream which will be read or written. + Indicates whether the DeflateStream will compress or decompress. + + + + Create a DeflateStream using the specified CompressionMode and the specified CompressionLevel. + + + + + + When mode is CompressionMode.Decompress, the level parameter is + ignored. The "captive" stream will be closed when the DeflateStream is + closed. + + + + + + + This example uses a DeflateStream to compress data from a file, and writes + the compressed data to another file. + + + 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); + } + } + } + } + + + + 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 + + + The stream to be read or written while deflating or inflating. + Indicates whether the DeflateStream will compress or decompress. + A tuning knob to trade speed for effectiveness. + + + + Create a DeflateStream using the specified + CompressionMode, and explicitly specify whether the + stream should be left open after Deflation or Inflation. + + + + + + This constructor allows the application to request that the captive stream + remain open after the deflation or inflation occurs. By default, after + Close() 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 parameter to leave the stream open. + + + + The DeflateStream will use the default compression level. + + + + See the other overloads of this constructor for example code. + + + + + The stream which will be read or written. This is called the + "captive" stream in other places in this documentation. + + + + Indicates whether the DeflateStream will compress or decompress. + + + true if the application would like the stream to + remain open after inflation/deflation. + + + + Create a DeflateStream using the specified CompressionMode + and the specified CompressionLevel, and explicitly specify whether + the stream should be left open after Deflation or Inflation. + + + + + + When mode is CompressionMode.Decompress, the level parameter is ignored. + + + + This constructor allows the application to request that the captive stream + remain open after the deflation or inflation occurs. By default, after + Close() 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 + that will be re-read after + compression. Specify true for the parameter + to leave the stream open. + + + + + + + This example shows how to use a DeflateStream to compress data from + a file, and store the compressed data into another file. + + + 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 + } + + + + 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 + + + The stream which will be read or written. + Indicates whether the DeflateStream will compress or decompress. + true if the application would like the stream to remain open after inflation/deflation. + A tuning knob to trade speed for effectiveness. + + + + This property sets the flush behavior on the stream. + + See the ZLIB documentation for the meaning of the flush behavior. + + + + + The size of the working buffer for the compression codec. + + + + + 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. + + + + Set this before the first call to Read() or Write() on the + stream. If you try to set it afterwards, it will throw. + + + + + + The ZLIB strategy to be used during compression. + + + + By tweaking this parameter, you may be able to optimize the compression for + data with particular characteristics. + + + + Returns the total number of bytes input so far. + + + Returns the total number of bytes output so far. + + + + Dispose the stream. + + + + This may or may not result in a Close() call on the captive + stream. See the constructors that have a leaveOpen parameter + for more information. + + + 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. + + + + true if the Dispose method was invoked by user code. + + + + + Indicates whether the stream can be read. + + + The return value depends on whether the captive stream supports reading. + + + + + Indicates whether the stream supports Seek operations. + + + Always returns false. + + + + + Indicates whether the stream can be written. + + + The return value depends on whether the captive stream supports writing. + + + + + Flush the stream. + + + + + Reading this property always throws a . + + + + + The position of the stream pointer. + + + + Setting this property always throws a . 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. + + + + + Read data from the stream. + + + + + If you wish to use the DeflateStream to compress data while + reading, you can create a DeflateStream with + CompressionMode.Compress, providing an uncompressed data stream. + Then call Read() on that DeflateStream, and the data read will be + compressed as you read. If you wish to use the DeflateStream to + decompress data while reading, you can create a DeflateStream with + CompressionMode.Decompress, providing a readable compressed data + stream. Then call Read() on that DeflateStream, and the data read + will be decompressed as you read. + + + + A DeflateStream can be used for Read() or Write(), but not both. + + + + The buffer into which the read data should be placed. + the offset within that data array to put the first byte read. + the number of bytes to read. + the number of bytes actually read + + + + Calling this method always throws a . + + this is irrelevant, since it will always throw! + this is irrelevant, since it will always throw! + irrelevant! + + + + Calling this method always throws a . + + this is irrelevant, since it will always throw! + + + + Write data to the stream. + + + + + If you wish to use the DeflateStream to compress data while + writing, you can create a DeflateStream with + CompressionMode.Compress, and a writable output stream. Then call + Write() on that DeflateStream, 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 DeflateStream to + decompress data while writing, you can create a DeflateStream with + CompressionMode.Decompress, and a writable output stream. Then + call Write() on that stream, providing previously compressed + data. The data sent to the output stream will be the decompressed form of + the data written. + + + + A DeflateStream can be used for Read() or Write(), + but not both. + + + + + The buffer holding data to write to the stream. + the offset within that data array to find the first byte to write. + the number of bytes to write. + + + + Compress a string into a byte array using DEFLATE (RFC 1951). + + + + Uncompress it with . + + + DeflateStream.UncompressString(byte[]) + DeflateStream.CompressBuffer(byte[]) + GZipStream.CompressString(string) + ZlibStream.CompressString(string) + + + A string to compress. The string will first be encoded + using UTF8, then compressed. + + + The string in compressed form + + + + Compress a byte array into a new byte array using DEFLATE. + + + + Uncompress it with . + + + DeflateStream.CompressString(string) + DeflateStream.UncompressBuffer(byte[]) + GZipStream.CompressBuffer(byte[]) + ZlibStream.CompressBuffer(byte[]) + + + A buffer to compress. + + + The data in compressed form + + + + Uncompress a DEFLATE'd byte array into a single string. + + + DeflateStream.CompressString(String) + DeflateStream.UncompressBuffer(byte[]) + GZipStream.UncompressString(byte[]) + ZlibStream.UncompressString(byte[]) + + + A buffer containing DEFLATE-compressed data. + + + The uncompressed string + + + + Uncompress a DEFLATE'd byte array into a byte array. + + + DeflateStream.CompressBuffer(byte[]) + DeflateStream.UncompressString(byte[]) + GZipStream.UncompressBuffer(byte[]) + ZlibStream.UncompressBuffer(byte[]) + + + A buffer containing data that has been compressed with DEFLATE. + + + The data in uncompressed form + + + + A class for compressing and decompressing GZIP streams. + + + + + The GZipStream is a Decorator on a + . It adds GZIP compression or decompression to any + stream. + + + + Like the System.IO.Compression.GZipStream in the .NET Base Class Library, the + Ionic.Zlib.GZipStream can compress while writing, or decompress while + reading, but not vice versa. The compression method used is GZIP, which is + documented in IETF RFC + 1952, "GZIP file format specification version 4.3". + + + A GZipStream can be used to decompress data (through Read()) or + to compress data (through Write()), but not both. + + + + If you wish to use the GZipStream to compress data, you must wrap it + around a write-able stream. As you call Write() on the GZipStream, the + data will be compressed into the GZIP format. If you want to decompress data, + you must wrap the GZipStream around a readable stream that contains an + IETF RFC 1952-compliant stream. The data will be decompressed as you call + Read() on the GZipStream. + + + + 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. + + + + This class is similar to and . + ZlibStream handles RFC1950-compliant streams. + handles RFC1951-compliant streams. This class handles RFC1952-compliant streams. + + + + + + + + + + The comment on the GZIP stream. + + + + + 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 Write() for the first time on the + GZipStream. + + + + When using GZipStream to decompress, you can retrieve this property + after the first call to Read(). If no comment has been set in the + GZIP bytestream, the Comment property will return null + (Nothing in VB). + + + + + + The FileName for the GZIP stream. + + + + + + The GZIP format optionally allows each file to have an associated + filename. When compressing data (through Write()), set this + FileName before calling Write() the first time on the GZipStream. + 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. + + + + When decompressing (through Read()), you can retrieve this value + any time after the first Read(). In the case where there was no filename + encoded into the GZIP bytestream, the property will return null (Nothing + in VB). + + + + + + The last modified time for the GZIP stream. + + + + 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 + Write(). When decompressing, you can retrieve this value any time + after the first call to Read(). + + + + + The CRC on the GZIP stream. + + + This is used for internal error checking. You probably don't need to look at this property. + + + + + Create a GZipStream using the specified CompressionMode. + + + + + When mode is CompressionMode.Compress, the GZipStream will use the + default compression level. + + + + As noted in the class documentation, the CompressionMode (Compress + or Decompress) also establishes the "direction" of the stream. A + GZipStream with CompressionMode.Compress works only through + Write(). A GZipStream with + CompressionMode.Decompress works only through Read(). + + + + + + This example shows how to use a GZipStream to compress data. + + 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); + } + } + } + } + + + 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 + + + + + This example shows how to use a GZipStream to uncompress a file. + + 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); + } + } + } + } + } + } + + + + 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 + + + + The stream which will be read or written. + Indicates whether the GZipStream will compress or decompress. + + + + Create a GZipStream using the specified CompressionMode and + the specified CompressionLevel. + + + + + The CompressionMode (Compress or Decompress) also establishes the + "direction" of the stream. A GZipStream with + CompressionMode.Compress works only through Write(). A + GZipStream with CompressionMode.Decompress works only + through Read(). + + + + + + + This example shows how to use a GZipStream to compress a file into a .gz file. + + + 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); + } + } + } + } + + + + 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 + + + The stream to be read or written while deflating or inflating. + Indicates whether the GZipStream will compress or decompress. + A tuning knob to trade speed for effectiveness. + + + + Create a GZipStream using the specified CompressionMode, and + explicitly specify whether the stream should be left open after Deflation + or Inflation. + + + + + This constructor allows the application to request that the captive stream + remain open after the deflation or inflation occurs. By default, after + Close() 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 parameter to leave + the stream open. + + + + The (Compress or Decompress) also + establishes the "direction" of the stream. A GZipStream with + CompressionMode.Compress works only through Write(). A GZipStream + with CompressionMode.Decompress works only through Read(). + + + + The GZipStream will use the default compression level. If you want + to specify the compression level, see . + + + + See the other overloads of this constructor for example code. + + + + + + The stream which will be read or written. This is called the "captive" + stream in other places in this documentation. + + + Indicates whether the GZipStream will compress or decompress. + + + + true if the application would like the base stream to remain open after + inflation/deflation. + + + + + Create a GZipStream using the specified CompressionMode and the + specified CompressionLevel, and explicitly specify whether the + stream should be left open after Deflation or Inflation. + + + + + + This constructor allows the application to request that the captive stream + remain open after the deflation or inflation occurs. By default, after + Close() 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 parameter to + leave the stream open. + + + + As noted in the class documentation, the CompressionMode (Compress + or Decompress) also establishes the "direction" of the stream. A + GZipStream with CompressionMode.Compress works only through + Write(). A GZipStream with CompressionMode.Decompress works only + through Read(). + + + + + + This example shows how to use a GZipStream to compress data. + + 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); + } + } + } + } + + + 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 + + + The stream which will be read or written. + Indicates whether the GZipStream will compress or decompress. + true if the application would like the stream to remain open after inflation/deflation. + A tuning knob to trade speed for effectiveness. + + + + This property sets the flush behavior on the stream. + + + + + The size of the working buffer for the compression codec. + + + + + 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. + + + + Set this before the first call to Read() or Write() on the + stream. If you try to set it afterwards, it will throw. + + + + + Returns the total number of bytes input so far. + + + Returns the total number of bytes output so far. + + + + Dispose the stream. + + + + This may or may not result in a Close() call on the captive + stream. See the constructors that have a leaveOpen parameter + for more information. + + + 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. + + + + indicates whether the Dispose method was invoked by user code. + + + + + Indicates whether the stream can be read. + + + The return value depends on whether the captive stream supports reading. + + + + + Indicates whether the stream supports Seek operations. + + + Always returns false. + + + + + Indicates whether the stream can be written. + + + The return value depends on whether the captive stream supports writing. + + + + + Flush the stream. + + + + + Reading this property always throws a . + + + + + The position of the stream pointer. + + + + Setting this property always throws a . 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. + + + + + Read and decompress data from the source stream. + + + + With a GZipStream, decompression is done through reading. + + + + + 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); + } + } + } + } + + + The buffer into which the decompressed data should be placed. + the offset within that data array to put the first byte read. + the number of bytes to read. + the number of bytes actually read + + + + Calling this method always throws a . + + irrelevant; it will always throw! + irrelevant; it will always throw! + irrelevant! + + + + Calling this method always throws a . + + irrelevant; this method will always throw! + + + + Write data to the stream. + + + + + If you wish to use the GZipStream to compress data while writing, + you can create a GZipStream with CompressionMode.Compress, and a + writable output stream. Then call Write() on that GZipStream, + providing uncompressed data as input. The data sent to the output stream + will be the compressed form of the data written. + + + + A GZipStream can be used for Read() or Write(), but not + both. Writing implies compression. Reading implies decompression. + + + + The buffer holding data to write to the stream. + the offset within that data array to find the first byte to write. + the number of bytes to write. + + + + Compress a string into a byte array using GZip. + + + + Uncompress it with . + + + + + + + A string to compress. The string will first be encoded + using UTF8, then compressed. + + + The string in compressed form + + + + Compress a byte array into a new byte array using GZip. + + + + Uncompress it with . + + + + + + + A buffer to compress. + + + The data in compressed form + + + + Uncompress a GZip'ed byte array into a single string. + + + + + + + A buffer containing GZIP-compressed data. + + + The uncompressed string + + + + Uncompress a GZip'ed byte array into a byte array. + + + + + + + A buffer containing data that has been compressed with GZip. + + + The data in uncompressed form + + + + A class for compressing streams using the + Deflate algorithm with multiple threads. + + + + + 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." + + + + This class is similar to , 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. + + + + 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. + + + + + + + + Create a ParallelDeflateOutputStream. + + + + + This stream compresses data written into it via the DEFLATE + algorithm (see RFC 1951), and writes out the compressed byte stream. + + + + The instance will use the default compression level, the default + buffer sizes and the default number of threads and buffers per + thread. + + + + This class is similar to , + 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. + + + + + + + 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. + + + 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); + } + } + } + } + + + 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 + + + The stream to which compressed data will be written. + + + + Create a ParallelDeflateOutputStream using the specified CompressionLevel. + + + See the + constructor for example code. + + The stream to which compressed data will be written. + A tuning knob to trade speed for effectiveness. + + + + Create a ParallelDeflateOutputStream and specify whether to leave the captive stream open + when the ParallelDeflateOutputStream is closed. + + + See the + constructor for example code. + + The stream to which compressed data will be written. + + true if the application would like the stream to remain open after inflation/deflation. + + + + + Create a ParallelDeflateOutputStream and specify whether to leave the captive stream open + when the ParallelDeflateOutputStream is closed. + + + See the + constructor for example code. + + The stream to which compressed data will be written. + A tuning knob to trade speed for effectiveness. + + true if the application would like the stream to remain open after inflation/deflation. + + + + + Create a ParallelDeflateOutputStream using the specified + CompressionLevel and CompressionStrategy, and specifying whether to + leave the captive stream open when the ParallelDeflateOutputStream is + closed. + + + See the + constructor for example code. + + The stream to which compressed data will be written. + A tuning knob to trade speed for effectiveness. + + By tweaking this parameter, you may be able to optimize the compression for + data with particular characteristics. + + + true if the application would like the stream to remain open after inflation/deflation. + + + + + The ZLIB strategy to be used during compression. + + + + + + The maximum number of buffer pairs to use. + + + + + 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 + ThreadPool.QueueUserWorkItem() + to compress those buffers in a background threadpool thread. After a + buffer is compressed, it is re-ordered and written to the output + stream. + + + + 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. + + + + 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 (). 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. + + + + 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. + + + + 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. + + + + 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. + + + + 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. + + + + + + The size of the buffers used by the compressor threads. + + + + + The default buffer size is 128k. The application can set this value + at any time, but it is effective only before the first Write(). + + + + 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 . 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 + DeflateStream. 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. + + + + 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. + + + + + + + The CRC32 for the data that was written out, prior to compression. + + + This value is meaningful only after a call to Close(). + + + + + The total number of uncompressed bytes processed by the ParallelDeflateOutputStream. + + + This value is meaningful only after a call to Close(). + + + + + Write data to the stream. + + + + + + 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. + + + + To decompress data, use the class. + + + + The buffer holding data to write to the stream. + the offset within that data array to find the first byte to write. + the number of bytes to write. + + + + Flush the stream. + + + + + Close the stream. + + + 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. + + + + Dispose the object + + + Because ParallelDeflateOutputStream is IDisposable, the + application must call this method when finished using the instance. + + + This method is generally called implicitly upon exit from + a using scope in C# (Using in VB). + + + + + The Dispose method + + indicates whether the Dispose method was invoked by user code. + + + + + Resets the stream for use with another stream. + + + 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. + + + + The new output stream for this era. + + + + + 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); + } + } + } + } + + + + + + Indicates whether the stream supports Seek operations. + + + Always returns false. + + + + + Indicates whether the stream supports Read operations. + + + Always returns false. + + + + + Indicates whether the stream supports Write operations. + + + Returns true if the provided stream is writable. + + + + + Reading this property always throws a NotSupportedException. + + + + + Returns the current position of the output stream. + + + + Because the output gets written by a background thread, + the value may change asynchronously. Setting this + property always throws a NotSupportedException. + + + + + + This method always throws a NotSupportedException. + + + The buffer into which data would be read, IF THIS METHOD + ACTUALLY DID ANYTHING. + + + The offset within that data array at which to insert the + data that is read, IF THIS METHOD ACTUALLY DID + ANYTHING. + + + The number of bytes to write, IF THIS METHOD ACTUALLY DID + ANYTHING. + + nothing. + + + + This method always throws a NotSupportedException. + + + The offset to seek to.... + IF THIS METHOD ACTUALLY DID ANYTHING. + + + The reference specifying how to apply the offset.... IF + THIS METHOD ACTUALLY DID ANYTHING. + + nothing. It always throws. + + + + This method always throws a NotSupportedException. + + + The new value for the stream length.... IF + THIS METHOD ACTUALLY DID ANYTHING. + + + + + Map from a distance to a distance code. + + + No side effects. _dist_code[256] and _dist_code[257] are never used. + + + + + Describes how to flush the current deflate operation. + + + The different FlushType values are useful when using a Deflate in a streaming application. + + + + No flush at all. + + + 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. + + + + + 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, AvailableBytesIn 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. + + + + + Use this during compression to specify that all output should be flushed, as + with FlushType.Sync, 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 + FlushType.Full too often can significantly degrade the compression. + + + + Signals the end of the compression/decompression stream. + + + + The compression level to be used when using a DeflateStream or ZlibStream with CompressionMode.Compress. + + + + + 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. + + + + + Same as None. + + + + + The fastest but least effective compression. + + + + + A synonym for BestSpeed. + + + + + A little slower, but better, than level 1. + + + + + A little slower, but better, than level 2. + + + + + A little slower, but better, than level 3. + + + + + A little slower than level 4, but with better compression. + + + + + The default compression level, with a good balance of speed and compression efficiency. + + + + + A synonym for Default. + + + + + Pretty good compression! + + + + + Better compression than Level7! + + + + + The "best" compression, where best means greatest reduction in size of the input data stream. + This is also the slowest compression. + + + + + A synonym for BestCompression. + + + + + 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. + + + + + The default strategy is probably the best for normal data. + + + + + The Filtered 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 Filtered is to force more Huffman + coding and less string matching; it is a half-step between Default and HuffmanOnly. + + + + + Using HuffmanOnly will force the compressor to do Huffman encoding only, with no + string matching. + + + + + An enum to specify the direction of transcoding - whether to compress or decompress. + + + + + Used to specify that the stream should compress the data. + + + + + Used to specify that the stream should decompress the data. + + + + + A general purpose exception class for exceptions in the Zlib library. + + + + + The ZlibException class captures exception information generated + by the Zlib library. + + + + + This ctor collects a message attached to the exception. + + the message for the exception. + + + + Performs an unsigned bitwise right shift with the specified number + + Number to operate on + Ammount of bits to shift + The resulting number from the shift operation + + + + Reads a number of characters from the current source TextReader and writes + the data to the target array at the specified index. + + + The source TextReader to read from + Contains the array of characteres read from the source TextReader. + The starting index of the target array. + The maximum number of characters to read from the source TextReader. + + + 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. + + + + + Computes an Adler-32 checksum. + + + 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. + + + + + + + Calculates the Adler32 checksum. + + + + This is used within ZLIB. You probably don't need to use this directly. + + + + To compute an Adler32 checksum on a byte array: + + var adler = Adler.Adler32(0, null, 0, 0); + adler = Adler.Adler32(adler, buffer, index, length); + + + + + + Encoder and Decoder for ZLIB and DEFLATE (IETF RFC1950 and RFC1951). + + + + This class compresses and decompresses data according to the Deflate algorithm + and optionally, the ZLIB format, as documented in RFC 1950 - ZLIB and RFC 1951 - DEFLATE. + + + + + The buffer from which data is taken. + + + + + An index into the InputBuffer array, indicating where to start reading. + + + + + The number of bytes available in the InputBuffer, starting at NextIn. + + + 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. + + + + + Total number of bytes read so far, through all calls to Inflate()/Deflate(). + + + + + Buffer to store output data. + + + + + An index into the OutputBuffer array, indicating where to start writing. + + + + + The number of bytes available in the OutputBuffer, starting at NextOut. + + + 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. + + + + + Total number of bytes written to the output so far, through all calls to Inflate()/Deflate(). + + + + + used for diagnostics, when something goes wrong! + + + + + The compression level to use in this codec. Useful only in compression mode. + + + + + The number of Window Bits to use. + + + 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. + + + + + The compression strategy to use. + + + 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. + + + + + The Adler32 checksum on the data transferred through the codec so far. You probably don't need to look at this. + + + + + Create a ZlibCodec. + + + If you use this default constructor, you will later have to explicitly call + InitializeInflate() or InitializeDeflate() before using the ZlibCodec to compress + or decompress. + + + + + Create a ZlibCodec that either compresses or decompresses. + + + Indicates whether the codec should compress (deflate) or decompress (inflate). + + + + + Initialize the inflation state. + + + It is not necessary to call this before using the ZlibCodec to inflate data; + It is implicitly called when you call the constructor. + + Z_OK if everything goes well. + + + + Initialize the inflation state with an explicit flag to + govern the handling of RFC1950 header bytes. + + + + By default, the ZLIB header defined in RFC 1950 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. + + + whether to expect an RFC1950 header byte + pair when reading the stream of data to be inflated. + + Z_OK if everything goes well. + + + + Initialize the ZlibCodec for inflation, with the specified number of window bits. + + The number of window bits to use. If you need to ask what that is, + then you shouldn't be calling this initializer. + Z_OK if all goes well. + + + + Initialize the inflation state with an explicit flag to govern the handling of + RFC1950 header bytes. + + + + 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 RFC + 1950, 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. + + + whether to expect an RFC1950 header byte pair when reading + the stream of data to be inflated. + The number of window bits to use. If you need to ask what that is, + then you shouldn't be calling this initializer. + Z_OK if everything goes well. + + + + Inflate the data in the InputBuffer, placing the result in the OutputBuffer. + + + You must have set InputBuffer and OutputBuffer, NextIn and NextOut, and AvailableBytesIn and + AvailableBytesOut before calling this method. + + + + 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(); + } + + + + The flush to use when inflating. + Z_OK if everything goes well. + + + + Ends an inflation session. + + + 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. + + Z_OK if everything goes well. + + + + I don't know what this does! + + Z_OK if everything goes well. + + + + Initialize the ZlibCodec for deflation operation. + + + The codec will use the MAX window bits and the default level of compression. + + + + 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(); + + + + Z_OK if all goes well. You generally don't need to check the return code. + + + + Initialize the ZlibCodec for deflation operation, using the specified CompressionLevel. + + + The codec will use the maximum window bits (15) and the specified + CompressionLevel. It will emit a ZLIB stream as it compresses. + + The compression level for the codec. + Z_OK if all goes well. + + + + Initialize the ZlibCodec for deflation operation, using the specified CompressionLevel, + and the explicit flag governing whether to emit an RFC1950 header byte pair. + + + 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 RFC + 1950, in the compressed stream. + + The compression level for the codec. + whether to emit an initial RFC1950 byte pair in the compressed stream. + Z_OK if all goes well. + + + + Initialize the ZlibCodec for deflation operation, using the specified CompressionLevel, + and the specified number of window bits. + + + The codec will use the specified number of window bits and the specified CompressionLevel. + + The compression level for the codec. + the number of window bits to use. If you don't know what this means, don't use this method. + Z_OK if all goes well. + + + + 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. + + + The compression level for the codec. + whether to emit an initial RFC1950 byte pair in the compressed stream. + the number of window bits to use. If you don't know what this means, don't use this method. + Z_OK if all goes well. + + + + Deflate one batch of data. + + + You must have set InputBuffer and OutputBuffer before calling this method. + + + + 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); + } + + + 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. + + Z_OK if all goes well. + + + + End a deflation session. + + + Call this after making a series of one or more calls to Deflate(). All buffers are flushed. + + Z_OK if all goes well. + + + + Reset a codec for another deflation session. + + + 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. + + Z_OK if all goes well. + + + + Set the CompressionStrategy and CompressionLevel for a deflation session. + + the level of compression to use. + the strategy to use for compression. + Z_OK if all goes well. + + + + Set the dictionary to be used for either Inflation or Deflation. + + The dictionary bytes to use. + Z_OK if all goes well. + + + + A bunch of constants used in the Zlib interface. + + + + + The maximum number of window bits for the Deflate algorithm. + + + + + The default number of window bits for the Deflate algorithm. + + + + + indicates everything is A-OK + + + + + Indicates that the last operation reached the end of the stream. + + + + + The operation ended in need of a dictionary. + + + + + There was an error with the stream - not enough data, not open and readable, etc. + + + + + There was an error with the data - not enough data, bad data, etc. + + + + + There was an error with the working buffer. + + + + + The size of the working buffer used in the ZlibCodec class. + + + + + The minimum size of the working buffer used in the ZlibCodec class. + + + + + Represents a Zlib stream for compression or decompression. + + + + + The ZlibStream is a Decorator on a . It adds ZLIB compression or decompression to any + stream. + + + Using this stream, applications can compress or decompress data via + stream Read() and Write() operations. Either compresssion or + decompression can occur through either reading or writing. The compression + format used is ZLIB, which is documented in IETF RFC 1950, "ZLIB Compressed + Data Format Specification version 3.3". This implementation of ZLIB always uses + DEFLATE as the compression method. (see IETF RFC 1951, "DEFLATE + Compressed Data Format Specification version 1.3.") + + + 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. + + + + This class is similar to , 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 + . + + + + + + + + Create a ZlibStream using the specified CompressionMode. + + + + + When mode is CompressionMode.Compress, the ZlibStream + will use the default compression level. The "captive" stream will be + closed when the ZlibStream is closed. + + + + + + This example uses a ZlibStream to compress a file, and writes the + compressed data to another file. + + 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); + } + } + } + } + + + 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 + + + + The stream which will be read or written. + Indicates whether the ZlibStream will compress or decompress. + + + + Create a ZlibStream using the specified CompressionMode and + the specified CompressionLevel. + + + + + + When mode is CompressionMode.Decompress, the level parameter is ignored. + The "captive" stream will be closed when the ZlibStream is closed. + + + + + + This example uses a ZlibStream to compress data from a file, and writes the + compressed data to another file. + + + 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); + } + } + } + } + + + + 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 + + + + The stream to be read or written while deflating or inflating. + Indicates whether the ZlibStream will compress or decompress. + A tuning knob to trade speed for effectiveness. + + + + Create a ZlibStream using the specified CompressionMode, and + explicitly specify whether the captive stream should be left open after + Deflation or Inflation. + + + + + + When mode is CompressionMode.Compress, the ZlibStream will use + the default compression level. + + + + This constructor allows the application to request that the captive stream + remain open after the deflation or inflation occurs. By default, after + Close() 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 + that will be re-read after + compression. Specify true for the parameter to leave the stream + open. + + + + See the other overloads of this constructor for example code. + + + + + The stream which will be read or written. This is called the + "captive" stream in other places in this documentation. + Indicates whether the ZlibStream will compress or decompress. + true if the application would like the stream to remain + open after inflation/deflation. + + + + Create a ZlibStream using the specified CompressionMode + and the specified CompressionLevel, and explicitly specify + whether the stream should be left open after Deflation or Inflation. + + + + + + This constructor allows the application to request that the captive + stream remain open after the deflation or inflation occurs. By + default, after Close() 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 that will be + re-read after compression. Specify true for the parameter to leave the stream open. + + + + When mode is CompressionMode.Decompress, the level parameter is + ignored. + + + + + + + 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. + + + 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 + } + + + 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 + + + + The stream which will be read or written. + + Indicates whether the ZlibStream will compress or decompress. + + + true if the application would like the stream to remain open after + inflation/deflation. + + + + A tuning knob to trade speed for effectiveness. This parameter is + effective only when mode is CompressionMode.Compress. + + + + + This property sets the flush behavior on the stream. + Sorry, though, not sure exactly how to describe all the various settings. + + + + + The size of the working buffer for the compression codec. + + + + + 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. + + + + Set this before the first call to Read() or Write() on the + stream. If you try to set it afterwards, it will throw. + + + + + Returns the total number of bytes input so far. + + + Returns the total number of bytes output so far. + + + + Dispose the stream. + + + + This may or may not result in a Close() call on the captive + stream. See the constructors that have a leaveOpen parameter + for more information. + + + 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. + + + + indicates whether the Dispose method was invoked by user code. + + + + + Indicates whether the stream can be read. + + + The return value depends on whether the captive stream supports reading. + + + + + Indicates whether the stream supports Seek operations. + + + Always returns false. + + + + + Indicates whether the stream can be written. + + + The return value depends on whether the captive stream supports writing. + + + + + Flush the stream. + + + + + Reading this property always throws a . + + + + + The position of the stream pointer. + + + + Setting this property always throws a . 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. + + + + + Read data from the stream. + + + + + + If you wish to use the ZlibStream to compress data while reading, + you can create a ZlibStream with CompressionMode.Compress, + providing an uncompressed data stream. Then call Read() on that + ZlibStream, and the data read will be compressed. If you wish to + use the ZlibStream to decompress data while reading, you can create + a ZlibStream with CompressionMode.Decompress, providing a + readable compressed data stream. Then call Read() on that + ZlibStream, and the data will be decompressed as it is read. + + + + A ZlibStream can be used for Read() or Write(), but + not both. + + + + + + The buffer into which the read data should be placed. + + + the offset within that data array to put the first byte read. + + the number of bytes to read. + + the number of bytes read + + + + Calling this method always throws a . + + + The offset to seek to.... + IF THIS METHOD ACTUALLY DID ANYTHING. + + + The reference specifying how to apply the offset.... IF + THIS METHOD ACTUALLY DID ANYTHING. + + + nothing. This method always throws. + + + + Calling this method always throws a . + + + The new value for the stream length.... IF + THIS METHOD ACTUALLY DID ANYTHING. + + + + + Write data to the stream. + + + + + + If you wish to use the ZlibStream to compress data while writing, + you can create a ZlibStream with CompressionMode.Compress, + and a writable output stream. Then call Write() on that + ZlibStream, 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 ZlibStream to decompress data while writing, you + can create a ZlibStream with CompressionMode.Decompress, and a + writable output stream. Then call Write() on that stream, + providing previously compressed data. The data sent to the output stream + will be the decompressed form of the data written. + + + + A ZlibStream can be used for Read() or Write(), but not both. + + + The buffer holding data to write to the stream. + the offset within that data array to find the first byte to write. + the number of bytes to write. + + + + Compress a string into a byte array using ZLIB. + + + + Uncompress it with . + + + + + + + + A string to compress. The string will first be encoded + using UTF8, then compressed. + + + The string in compressed form + + + + Compress a byte array into a new byte array using ZLIB. + + + + Uncompress it with . + + + + + + + A buffer to compress. + + + The data in compressed form + + + + Uncompress a ZLIB-compressed byte array into a single string. + + + + + + + A buffer containing ZLIB-compressed data. + + + The uncompressed string + + + + Uncompress a ZLIB-compressed byte array into a byte array. + + + + + + + A buffer containing ZLIB-compressed data. + + + The data in uncompressed form + + + + 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. + + + + + A wrapper for ZipFile.IsZipFile(string) + + The filename to of the zip file to check. + true if the file contains a valid zip file. + + + + A wrapper for ZipFile.IsZipFile(string, bool) + + + We cannot use "overloaded" Method names in COM interop. + So, here, we use a unique name. + + The filename to of the zip file to check. + true if the file contains a valid zip file. + + + + A wrapper for ZipFile.CheckZip(string) + + The filename to of the zip file to check. + + true if the named zip file checks OK. Otherwise, false. + + + + A COM-friendly wrapper for the static method . + + + The filename to of the zip file to check. + + The password to check. + + true if the named zip file checks OK. Otherwise, false. + + + + A wrapper for ZipFile.FixZipDirectory(string) + + The filename to of the zip file to fix. + + + + A wrapper for ZipFile.LibraryVersion + + + the version number on the DotNetZip assembly, formatted as a string. + + + + + An enum that provides the various encryption algorithms supported by this + library. + + + + + + PkzipWeak implies the use of Zip 2.0 encryption, which is known to be + weak and subvertible. + + + + A note on interoperability: Values of PkzipWeak and None are + specified in PKWARE's zip + specification, 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. + + + + Values of WinZipAes128 and WinZipAes256 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). + + + + 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. + + + + In case you care: According to the WinZip specification, the + actual AES key used is derived from the via an + algorithm that complies with RFC 2898, using an iteration + count of 1000. The algorithm is sometimes referred to as PBKDF2, which stands + for "Password Based Key Derivation Function #2". + + + + 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 this + article. + + + + + + + No encryption at all. + + + + + Traditional or Classic pkzip encryption. + + + + + WinZip AES encryption (128 key bits). + + + + + WinZip AES encryption (256 key bits). + + + + + An encryption algorithm that is not supported by DotNetZip. + + + + + Delegate in which the application writes the ZipEntry content for the named entry. + + + The name of the entry that must be written. + The stream to which the entry data should be written. + + + When you add an entry and specify a WriteDelegate, via , the application + code provides the logic that writes the entry data directly into the zip file. + + + + + 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. + + + 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); + } + } + + + + 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 + + + + + + + Delegate in which the application opens the stream, just-in-time, for the named entry. + + + + The name of the ZipEntry that the application should open the stream for. + + + + When you add an entry via , the application code provides the logic that + opens and closes the stream for the given ZipEntry. + + + + + + + Delegate in which the application closes the stream, just-in-time, for the named entry. + + + + The name of the ZipEntry that the application should close the stream for. + + + The stream to be closed. + + + When you add an entry via , the application code provides the logic that + opens and closes the stream for the given ZipEntry. + + + + + + + Delegate for the callback by which the application tells the + library the CompressionLevel to use for a file. + + + + + Using this callback, the application can, for example, specify that + previously-compressed files (.mp3, .png, .docx, etc) should use a + CompressionLevel of None, or can set the compression level based + on any other factor. + + + + + + + In an EventArgs type, indicates which sort of progress event is being + reported. + + + 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. + + + + + Indicates that a Add() operation has started. + + + + + Indicates that an individual entry in the archive has been added. + + + + + Indicates that a Add() operation has completed. + + + + + Indicates that a Read() operation has started. + + + + + Indicates that an individual entry in the archive is about to be read. + + + + + Indicates that an individual entry in the archive has just been read. + + + + + Indicates that a Read() operation has completed. + + + + + The given event reports the number of bytes read so far + during a Read() operation. + + + + + Indicates that a Save() operation has started. + + + + + Indicates that an individual entry in the archive is about to be written. + + + + + Indicates that an individual entry in the archive has just been saved. + + + + + Indicates that a Save() operation has completed. + + + + + Indicates that the zip archive has been created in a + temporary location during a Save() operation. + + + + + Indicates that the temporary file is about to be renamed to the final archive + name during a Save() operation. + + + + + Indicates that the temporary file is has just been renamed to the final archive + name during a Save() operation. + + + + + Indicates that the self-extracting archive has been compiled + during a Save() operation. + + + + + The given event is reporting the number of source bytes that have run through the compressor so far + during a Save() operation. + + + + + Indicates that an entry is about to be extracted. + + + + + Indicates that an entry has just been extracted. + + + + + Indicates that extraction of an entry would overwrite an existing + filesystem file. You must use + + ExtractExistingFileAction.InvokeExtractProgressEvent in the call + to ZipEntry.Extract() in order to receive this event. + + + + + The given event is reporting the number of bytes written so far for + the current entry during an Extract() operation. + + + + + Indicates that an ExtractAll operation is about to begin. + + + + + Indicates that an ExtractAll operation has completed. + + + + + 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. + + + + + 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. + + + + + The total number of entries to be saved or extracted. + + + + + The name of the last entry saved or extracted. + + + + + In an event handler, set this to cancel the save or extract + operation that is in progress. + + + + + The type of event being reported. + + + + + Returns the archive name associated to this event. + + + + + The number of bytes read or written so far for this entry. + + + + + Total number of bytes that will be read or written for this entry. + This number will be -1 if the value cannot be determined. + + + + + Provides information about the progress of a Read operation. + + + + + Provides information about the progress of a Add operation. + + + + + Provides information about the progress of a save operation. + + + + + Constructor for the SaveProgressEventArgs. + + the name of the zip archive. + whether this is before saving the entry, or after + The total number of entries in the zip archive. + Number of entries that have been saved. + The entry involved in the event. + + + + Number of entries saved so far. + + + + + Provides information about the progress of the extract operation. + + + + + Constructor for the ExtractProgressEventArgs. + + the name of the zip archive. + whether this is before saving the entry, or after + The total number of entries in the zip archive. + Number of entries that have been extracted. + The entry involved in the event. + The location to which entries are extracted. + + + + 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(). + + + + + Returns the extraction target location, a filesystem path. + + + + + Provides information about the an error that occurred while zipping. + + + + + Returns the exception that occurred, if any. + + + + + Returns the name of the file that caused the exception, if any. + + + + + Issued when an ZipEntry.ExtractWithPassword() method is invoked + with an incorrect password. + + + + + Default ctor. + + + + + Come on, you know how exceptions work. Why are you looking at this documentation? + + The message in the exception. + + + + Come on, you know how exceptions work. Why are you looking at this documentation? + + The message in the exception. + The innerException for this exception. + + + + Come on, you know how exceptions work. Why are you looking at this documentation? + + The serialization info for the exception. + The streaming context from which to deserialize. + + + + Indicates that a read was attempted on a stream, and bad or incomplete data was + received. + + + + + Default ctor. + + + + + Come on, you know how exceptions work. Why are you looking at this documentation? + + The message in the exception. + + + + Come on, you know how exceptions work. Why are you looking at this documentation? + + The message in the exception. + The innerException for this exception. + + + + Come on, you know how exceptions work. Why are you looking at this documentation? + + The serialization info for the exception. + The streaming context from which to deserialize. + + + + Issued when an CRC check fails upon extracting an entry from a zip archive. + + + + + Default ctor. + + + + + Come on, you know how exceptions work. Why are you looking at this documentation? + + The message in the exception. + + + + Come on, you know how exceptions work. Why are you looking at this documentation? + + The serialization info for the exception. + The streaming context from which to deserialize. + + + + Issued when errors occur saving a self-extracting archive. + + + + + Default ctor. + + + + + Come on, you know how exceptions work. Why are you looking at this documentation? + + The message in the exception. + + + + Come on, you know how exceptions work. Why are you looking at this documentation? + + The serialization info for the exception. + The streaming context from which to deserialize. + + + + Indicates that an operation was attempted on a ZipFile which was not possible + given the state of the instance. For example, if you call Save() on a ZipFile + which has no filename set, you can get this exception. + + + + + Default ctor. + + + + + Come on, you know how exceptions work. Why are you looking at this documentation? + + The message in the exception. + + + + Come on, you know how exceptions work. Why are you looking at this documentation? + + The message in the exception. + The innerException for this exception. + + + + Come on, you know how exceptions work. Why are you looking at this documentation? + + The serialization info for the exception. + The streaming context from which to deserialize. + + + + Base class for all exceptions defined by and throw by the Zip library. + + + + + Default ctor. + + + + + Come on, you know how exceptions work. Why are you looking at this documentation? + + The message in the exception. + + + + Come on, you know how exceptions work. Why are you looking at this documentation? + + The message in the exception. + The innerException for this exception. + + + + Come on, you know how exceptions work. Why are you looking at this documentation? + + The serialization info for the exception. + The streaming context from which to deserialize. + + + + An enum for the options when extracting an entry would overwrite an existing file. + + + + + This enum describes the actions that the library can take when an + Extract() or ExtractWithPassword() method is called to extract an + entry to a filesystem, and the extraction would overwrite an existing filesystem + file. + + + + + + + Throw an exception when extraction would overwrite an existing file. (For + COM clients, this is a 0 (zero).) + + + + + 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.) + + + + + When extraction would overwrite an existing file, don't overwrite the file, silently. + (For COM clients, this is a 2.) + + + + + When extraction would overwrite an existing file, invoke the ExtractProgress + event, using an event type of . 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 property before making + the decision. If, after your processing in the Extract progress event, you + want to NOT extract the file, set + on the ZipProgressEventArgs.CurrentEntry to DoNotOverwrite. + If you do want to extract the file, set ZipEntry.ExtractExistingFile + to OverwriteSilently. If you want to cancel the Extraction, set + ZipProgressEventArgs.Cancel 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.) + + + + + Collects general purpose utility methods. + + + + private null constructor + + + + 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. + + source path. + transformed path + + + + Sanitize paths in zip files. This means making sure that relative paths in a zip file don't go outside + the top directory. Entries like something/../../../../Temp/evil.txt get sanitized to Temp/evil.txt + when extracting + + A path with forward slashes as directory separator + sanitized path + + + + 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. + + + + + Scans through 64k at a time. + + + + 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. + + + + The stream to search + The 4-byte signature to find + The number of bytes read + + + + Create a pseudo-random filename, suitable for use as a temporary + file, and open it. + + + + This method produces a filename of the form + DotNetZip-xxxxxxxx.tmp, where xxxxxxxx is replaced by randomly + chosen characters, and creates that file. + + + + + + Workitem 7889: handle ERROR_LOCK_VIOLATION during read + + + This could be gracefully handled with an extension attribute, but + This assembly used to be built for .NET 2.0, so could not use + extension methods. + + + + + A decorator stream. It wraps another stream, and performs bookkeeping + to keep track of the stream Position. + + + + In some cases, it is not possible to get the Position of a stream, let's + say, on a write-only output stream like ASP.NET's + Response.OutputStream, 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. + + + Consider the scenario of an application that saves a self-extracting + archive (SFX), that uses a custom SFX stub. + + + Saving to a filesystem file, the application would open the + filesystem file (getting a FileStream), save the custom sfx stub + into it, and then call ZipFile.Save(), specifying the same + FileStream. ZipFile.Save() does the right thing for the zipentry + offsets, by inquiring the Position of the FileStream before writing + any data, and then adding that initial offset into any ZipEntry + offsets in the zip directory. Everything works fine. + + + Now suppose the application is an ASPNET application and it saves + directly to Response.OutputStream. It's not possible for DotNetZip to + inquire the Position, so the offsets for the SFX will be wrong. + + + The workaround is for the application to use this class to wrap + HttpResponse.OutputStream, then write the SFX stub and the ZipFile + into that wrapper stream. Because ZipFile.Save() can inquire the + Position, it will then do the right thing with the offsets. + + + + + + The constructor. + + The underlying stream + + + + Gets the wrapped stream. + + + + + The count of bytes written out to the stream. + + + + + the count of bytes that have been read from the stream. + + + + + Adjust the byte count on the stream. + + + + the number of bytes to subtract from the count. + + + + + 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. + + + + + + The read method. + + The buffer to hold the data read from the stream. + the offset within the buffer to copy the first byte read. + the number of bytes to read. + the number of bytes read, after decryption and decompression. + + + + Write data into the stream. + + The buffer holding data to write to the stream. + the offset within that data array to find the first byte to write. + the number of bytes to write. + + + + Whether the stream can be read. + + + + + Whether it is possible to call Seek() on the stream. + + + + + Whether it is possible to call Write() on the stream. + + + + + Flushes the underlying stream. + + + + + The length of the underlying stream. + + + + + Returns the sum of number of bytes written, plus the initial + offset before writing. + + + + + The Position of the stream. + + + + + Seek in the stream. + + the offset point to seek to + the reference point from which to seek + The new position + + + + Set the length of the underlying stream. Be careful with this! + + + the length to set on the underlying stream. + + + + This is a helper class supporting WinZip AES encryption. + This class is intended for use only by the DotNetZip library. + + + + 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. + + + + + 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. + + + + 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 + + + + + + + The constructor. + + The underlying stream + To either encrypt or decrypt. + The pre-initialized WinZipAesCrypto object. + The maximum number of bytes to read from the stream. + + + + Returns the final HMAC-SHA1-80 for the data that was encrypted. + + + + + Close the stream. + + + + + Returns true if the stream can be read. + + + + + Always returns false. + + + + + Returns true if the CryptoMode is Encrypt. + + + + + Flush the content in the stream. + + + + + Getting this property throws a NotImplementedException. + + + + + Getting or Setting this property throws a NotImplementedException. + + + + + This method throws a NotImplementedException. + + + + + This method throws a NotImplementedException. + + + + + 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. + + + + 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. + + + + + The default constructor for ZipCrypto. + + + + 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. + + + + + + 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 + + + + + Call this method on a cipher text to render the plaintext. You must + first initialize the cipher with a call to InitCipher. + + + + + 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); + + + + The encrypted buffer. + + The number of bytes to encrypt. + Should be less than or equal to CipherText.Length. + + + The plaintext. + + + + This is the converse of DecryptMessage. It encrypts the plaintext + and produces a ciphertext. + + + The plain text buffer. + + + The number of bytes to encrypt. + Should be less than or equal to plainText.Length. + + + The ciphertext. + + + + This initializes the cipher with the given password. + See AppNote.txt for details. + + + + The passphrase for encrypting or decrypting with this cipher. + + + + + 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. + + + + + After the keys are initialized, then you can use the cipher to + encrypt the plaintext. + + + + Essentially we encrypt the password with the keys, then discard the + ciphertext for the password. This initializes the keys for later use. + + + + + + + A Stream for reading and concurrently decrypting data from a zip file, + or for writing and concurrently encrypting data to a zip file. + + + + The constructor. + The underlying stream + To either encrypt or decrypt. + The pre-initialized ZipCrypto object. + + + + 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. + + + + + True if the referenced entry is a directory. + + + + + Provides a human-readable string with information about the ZipEntry. + + + + + Reads one entry from the zip directory structure in the zip file. + + + + 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. + + + + a list of previously seen entry names; used to prevent duplicates. + + + the entry read from the archive. + + + + Returns true if the passed-in value is a valid signature for a ZipDirEntry. + + the candidate 4-byte signature value. + true, if the signature is valid according to the PKWare spec. + + + + Default constructor. + + + Applications should never need to call this directly. It is exposed to + support COM Automation environments. + + + + + The time and date at which the file indicated by the ZipEntry was + last modified. + + + + + 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 System.DateTime.Now for this + value, for the given entry. + + + + This property allows the application to retrieve and possibly set the + LastModified value on an entry, to an arbitrary value. values with a + setting of DateTimeKind.Unspecified are taken to be expressed as + DateTimeKind.Local. + + + + Be aware that because of the way PKWare's + Zip specification describes how times are stored in the zip file, + the full precision of the System.DateTime 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. + + + + The actual last modified time of a file can be stored in multiple ways in + the zip file, and they are not mutually exclusive: + + + + + 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 LastModified property. This value is always + present in the metadata for each zip entry. In some cases the value is + invalid, or zero. + + + + 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 ModifiedTime property. + + + + In the "Unix" format, a 4-byte quantity specifying the number of seconds since + January 1, 1970 UTC. + + + + 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. + + + + + + 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. + + + + When reading ZIP files, the DotNetZip library reads the Windows-formatted + time, if it is stored in the entry, and sets both LastModified and + ModifiedTime 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 .) + + + + The last modified time of the file created upon a call to + ZipEntry.Extract() 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 provides + some good context. + + + + 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. + + + + 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. + + + + 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. + + + + .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. + + + + 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. + + + + 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. + + + + + + + + Ability to set Last Modified DOS time to zero + (for using with EmitTimesInWindowsFormatWhenSaving+EmitTimesInUnixFormatWhenSaving setted to false) + some flasher hardware use as marker of first binary + + + + + Last Modified time for the file represented by the entry. + + + + + + This value corresponds to the "last modified" time in the NTFS file times + as described in the Zip + specification. When getting this property, the value may be + different from . When setting the property, + the property also gets set, but with a lower + precision. + + + + 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, who is ever going to need better + resolution than THAT? And so ZIP files, regardless of the platform on + which the zip file was created, store file times in exactly the same format that DOS used + in 1989. + + + + 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. + + + + 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 + last write, last access, and file creation + 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 formatted in the zip file + 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. + + + + 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. + + + + 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 + ModifiedTime, AccessedTime and CreationTime + properties on the ZipEntry. + + + + 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 + , is guaranteed to be present, though it + sometimes unset. + + + + Ok, getting back to the question about how the LastModified + property relates to this ModifiedTime + property... LastModified is always set, while + ModifiedTime is not. (The other times stored in the NTFS + times extension, CreationTime and AccessedTime also + may not be set on an entry that is read from an existing zip file.) + When reading a zip file, then LastModified 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 DateTime.Now for the + LastModified 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 LastModified and ModifiedTime 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 ModifiedTime + remains unset (likewise AccessedTime and CreationTime), + and LastModified keeps its DOS time. + + + + When creating zip files with this library, by default the extended time + properties (ModifiedTime, AccessedTime, and + CreationTime) 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 DateTime.Now. In + this case LastModified and ModifiedTime will be identical, + to 2 seconds of precision. You can explicitly set the + CreationTime, AccessedTime, and ModifiedTime of an + entry using the property setters. If you want to set all of those + quantities, it's more efficient to use the method. Those + changes are not made permanent in the zip file until you call or one of its cousins. + + + + 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 and + 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. + + + + 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, maybe you + should donate? + + + + + + + + + + + Last Access time for the file represented by the entry. + + + This value may or may not be meaningful. If the ZipEntry was read from an existing + Zip archive, this information may not be available. For an explanation of why, see + . + + + + + + + + The file creation time for the file represented by the entry. + + + + This value may or may not be meaningful. If the ZipEntry 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 . + + + + + + + + Sets the NTFS Creation, Access, and Modified times for the given entry. + + + + + 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. + + + + The values you set here will be retrievable with the , and properties. + + + + When this method is called, if both and are false, then the + EmitTimesInWindowsFormatWhenSaving flag is automatically set. + + + + DateTime values provided here without a DateTimeKind are assumed to be Local Time. + + + + the creation time of the entry. + the last access time of the entry. + the last modified time of the entry. + + + + + + + + + + Specifies whether the Creation, Access, and Modified times for the given + entry will be emitted in "Windows format" when the zip archive is saved. + + + + + 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 true. + + + + 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, all three values are implicitly set to DateTime.Now. Applications + can also explicitly set those times by calling . + + + + PKWARE's + zip specification 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. + + + + 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 Infozip + 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. + + + + The times stored are taken from , , and . + + + + This property is not mutually exclusive from the 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. + + + + Normally you will use the ZipFile.EmitTimesInWindowsFormatWhenSaving + property, to specify the behavior for all entries in a zip, rather than + the property on each individual entry. + + + + + + + + + + + + + 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. + + + + + 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 + false, meaning the Unix-format times are not stored in the zip + archive. + + + + 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, all three values are implicitly set to DateTime.Now. Applications + can also explicitly set those times by calling . + + + + PKWARE's + zip specification 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. + + + + 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 Infozip + 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. + + + + The times stored are taken from , , and . + + + + This property is not mutually exclusive from the 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. + + + + Normally you will use the ZipFile.EmitTimesInUnixFormatWhenSaving + property, to specify the behavior for all entries, rather than the + property on each individual entry. + + + + + + + + + + + + + The type of timestamp attached to the ZipEntry. + + + + 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. + + + + + + + + The file attributes for the entry. + + + + + + The attributes in NTFS include + ReadOnly, Archive, Hidden, System, and Indexed. When adding a + ZipEntry 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 ZipFile, you can set the attributes + explicitly if you like. + + + + When reading a ZipEntry from a ZipFile, the attributes are + set according to the data stored in the ZipFile. If you extract the + entry from the archive to a filesystem file, DotNetZip will set the + attributes on the resulting file accordingly. + + + + The attributes can be set explicitly by the application. For example the + application may wish to set the FileAttributes.ReadOnly 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 Save() method on the ZipFile + instance that contains the ZipEntry. + + + + 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 ZipFile. + + + + 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. + + + + + + + The name of the filesystem file, referred to by the ZipEntry. + + + + + This property specifies the thing-to-be-zipped on disk, and is set only + when the ZipEntry is being created from a filesystem file. If the + ZipFile is instantiated by reading an existing .zip archive, then + the LocalFileName will be null (Nothing in VB). + + + + When it is set, the value of this property may be different than , which is the path used in the archive itself. If you + call Zip.AddFile("foop.txt", AlternativeDirectory), then the path + used for the ZipEntry within the zip archive will be different + than this path. + + + + If the entry is being added from a stream, then this is null (Nothing in VB). + + + + + + + + The name of the file contained in the ZipEntry. + + + + + + This is the name of the entry in the ZipFile itself. When creating + a zip archive, if the ZipEntry has been created from a filesystem + file, via a call to or , or a related overload, the value + of this property is derived from the name of that file. The + FileName property does not include drive letters, and may include a + different directory path, depending on the value of the + directoryPathInArchive parameter used when adding the entry into + the ZipFile. + + + + In some cases there is no related filesystem file - for example when a + ZipEntry is created using 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. + + + + 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. + + + + 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 the Zip + specification, for compatibility with Unix(tm) and ... get + this.... Amiga! + + + + If an application reads a ZipFile via or a related overload, and then explicitly + sets the FileName on an entry contained within the ZipFile, and + then calls , the application will effectively + rename the entry within the zip archive. + + + + If an application sets the value of FileName, then calls + Extract() on the entry, the entry is extracted to a file using the + newly set value as the filename. The FileName value is made + permanent in the zip archive only after a call to one of the + ZipFile.Save() methods on the ZipFile that contains the + ZipEntry. + + + + If an application attempts to set the FileName to a value that + would result in a duplicate entry in the ZipFile, an exception is + thrown. + + + + When a ZipEntry is contained within a ZipFile, applications + cannot rename the entry within the context of a foreach (For + Each in VB) loop, because of the way the ZipFile stores + entries. If you need to enumerate through all the entries and rename one + or more of them, use ZipFile.EntriesSorted as the + collection. See also, ZipFile.GetEnumerator(). + + + + + + + The stream that provides content for the ZipEntry. + + + + + + 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 ZipFile comprised of content obtained from hundreds of + files, via calls to AddFile(). 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 ZipFile.Save() call. Only + one input stream is opened at a time, as each entry is being written out. + + + + Now imagine a different application that creates a ZipFile + with content obtained from hundreds of streams, added through . 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. + + + + To avoid this, call and specify delegates that open and close the stream at + the time of Save. + + + + + Setting the value of this property when the entry was not added from a + stream (for example, when the ZipEntry was added with or , or when the entry was added by + reading an existing zip archive) will throw an exception. + + + + + + + + A flag indicating whether the InputStream was provided Just-in-time. + + + + + + When creating a zip archive, an application can obtain content for one or + more of the ZipEntry instances from streams, using the 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 ZipFile.Save() methods is called and + the data for the various entries are being compressed and written out. + + + + In this case, the application can set the + property, typically within the SaveProgress event (event type: ) for that entry. + + + + The application will later want to call Close() and Dispose() on that + stream. In the SaveProgress event, when the event type is , 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. + + + + + + + + An enum indicating the source of the ZipEntry. + + + + + The version of the zip engine needed to read the ZipEntry. + + + + + This is a readonly property, indicating the version of the Zip + specification 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. + + + + + value + Features + + + + 20 + a basic Zip Entry, potentially using PKZIP encryption. + + + + + 45 + The ZIP64 extension is used on the entry. + + + + + 46 + File is compressed using BZIP2 compression* + + + + 50 + File is encrypted using PkWare's DES, 3DES, (broken) RC2 or RC4 + + + + 51 + File is encrypted using PKWare's AES encryption or corrected RC2 encryption. + + + + 52 + File is encrypted using corrected RC2-64 encryption** + + + + 61 + File is encrypted using non-OAEP key wrapping*** + + + + 63 + File is compressed using LZMA, PPMd+, Blowfish, or Twofish + + + + + + 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. + + + + This value is set upon reading an existing zip file, or after saving a zip + archive. + + + + + + The comment attached to the ZipEntry. + + + + + 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. + + + + By default, the Comment is encoded in IBM437 code page. You can + specify an alternative with and + . + + + + + + + + Indicates whether the entry requires ZIP64 extensions. + + + + + + This property is null (Nothing in VB) until a Save() method on the + containing instance has been called. The property is + non-null (HasValue is true) only after a Save() method has + been called. + + + + After the containing ZipFile 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 Save() is attempted on the zip archive and + the compression is applied. + + + + If none of the three conditions holds, then the Value is false. + + + + A Value of false does not indicate that the entry, as saved in the + zip archive, does not use ZIP64. It merely indicates that ZIP64 is + not required. An entry may use ZIP64 even when not required if + the property on the containing + ZipFile instance is set to , or if + the property on the containing + ZipFile instance is set to + and the output stream was not seekable. + + + + + + + + Indicates whether the entry actually used ZIP64 extensions, as it was most + recently written to the output file or stream. + + + + + + This Nullable property is null (Nothing in VB) until a Save() + method on the containing instance has been + called. HasValue is true only after a Save() method has been + called. + + + + The value of this property for a particular ZipEntry may change + over successive calls to Save() methods on the containing ZipFile, + even if the file that corresponds to the ZipEntry does not. This + may happen if other entries contained in the ZipFile expand, + causing the offset for this particular entry to exceed 0xFFFFFFFF. + + + + + + + The bitfield for the entry as defined in the zip spec. You probably + never need to look at this. + + + + + You probably do not need to concern yourself with the contents of this + property, but in case you do: + + + + + bit + meaning + + + + 0 + set if encryption is used. + + + + 1-2 + + 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. + + + + + 3 + + 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. + + + + + + 4 + reserved for "enhanced deflating". This library doesn't do enhanced deflating. + + + + 5 + set to indicate the zip is compressed patched data. This library doesn't do that. + + + + 6 + + 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. + + + + 7 + not used + + + + 8 + not used + + + + 9 + not used + + + + 10 + not used + + + + 11 + + 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. + + + + + 12 + Reserved by PKWARE for enhanced compression. + + + + 13 + + 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 the Zip + specification describing the Strong Encryption Specification for + details. + + + + + 14 + Reserved by PKWARE. + + + + 15 + Reserved by PKWARE. + + + + + + + + + The compression method employed for this ZipEntry. + + + + + + The + Zip specification allows a variety of compression methods. This + library supports just two: 0x08 = Deflate. 0x00 = Store (no compression), + for reading or writing. + + + + 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. + + + + You may wish to set CompressionMethod to CompressionMethod.None (0) + when zipping already-compressed data like a jpg, png, or mp3 file. + This can save time and cpu cycles. + + + + When setting this property on a ZipEntry that is read from an + existing zip file, calling ZipFile.Save() will cause the new + CompressionMethod to be used on the entry in the newly saved zip file. + + + + Setting this property may have the side effect of modifying the + CompressionLevel property. If you set the CompressionMethod to a + value other than None, and CompressionLevel is previously + set to None, then CompressionLevel will be set to + Default. + + + + + + + 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. + + 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(); + } + + + + 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 + + + + + + Sets the compression level to be used for the entry when saving the zip + archive. This applies only for CompressionMethod = DEFLATE. + + + + + 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. + + + + 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 BestCompression 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. + + + + When setting this property on a ZipEntry that is read from an + existing zip file, calling ZipFile.Save() will cause the new + CompressionLevel to be used on the entry in the newly saved zip file. + + + + Setting this property may have the side effect of modifying the + CompressionMethod property. If you set the CompressionLevel + to a value other than None, CompressionMethod will be set + to Deflate, if it was previously None. + + + + Setting this property has no effect if the CompressionMethod is something + other than Deflate or None. + + + + + + + + The compressed size of the file, in bytes, within the zip archive. + + + + When reading a ZipFile, this value is read in from the existing + zip file. When creating or updating a ZipFile, the compressed + size is computed during compression. Therefore the value on a + ZipEntry is valid after a call to Save() (or one of its + overloads) in that case. + + + + + + + The size of the file, in bytes, before compression, or after extraction. + + + + When reading a ZipFile, this value is read in from the existing + zip file. When creating or updating a ZipFile, the uncompressed + size is computed during compression. Therefore the value on a + ZipEntry is valid after a call to Save() (or one of its + overloads) in that case. + + + + + + + The ratio of compressed size to uncompressed size of the ZipEntry. + + + + + 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. + + + + You could format it for presentation to a user via a format string of + "{3,5:F0}%" to see it as a percentage. + + + + If the size of the original uncompressed file is 0, implying a + denominator of 0, the return value will be zero. + + + + This property is valid after reading in an existing zip file, or after + saving the ZipFile that contains the ZipEntry. You cannot know the + effect of a compression transform until you try it. + + + + + + + The 32-bit CRC (Cyclic Redundancy Check) on the contents of the ZipEntry. + + + + + You probably don't need to concern yourself with this. It is used + internally by DotNetZip to verify files or streams upon extraction. + + The value is a 32-bit + CRC 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 + Save() on the containing ZipFile. When reading an existing zip file, the value + of this property reflects the stored CRC for the entry. + + + + + + True if the entry is a directory (not a file). + This is a readonly property on the entry. + + + + + A derived property that is true if the entry uses encryption. + + + + + This is a readonly property on the entry. When reading a zip file, + the value for the ZipEntry is determined by the data read + from the zip file. After saving a ZipFile, the value of this + property for each ZipEntry indicates whether encryption was + actually used (which will have been true if the was set and the property + was something other than . + + + + + + Set this to specify which encryption algorithm to use for the entry when + saving it to a zip archive. + + + + + + Set this property in order to encrypt the entry when the ZipFile is + saved. When setting this property, you must also set a on the entry. If you set a value other than on this property and do not set a + Password then the entry will not be encrypted. The ZipEntry + data is encrypted as the ZipFile is saved, when you call or one of its cousins on the containing + ZipFile instance. You do not need to specify the Encryption + when extracting entries from an archive. + + + + 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 a + subset 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. + + + + 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 specified + by PKWare, 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. + + + + The class also has a property. In most cases you will use + that property when setting encryption. This property takes + precedence over any Encryption set on the ZipFile 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. + + + + Some comments on updating archives: If you read a ZipFile, 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 + ZipFile. 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 Encryption to PkzipWeak, then at + the time of Save(), the original entry is read and decompressed, + then re-compressed and encrypted. Conversely, if the original entry is + encrypted with PkzipWeak encryption, and the application sets the + Encryption property to WinZipAes128, then at the time of + Save(), 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. + + + + 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 Encryption to None, then call Save(). Then set the + Encryption to the new value (not "None"), then call Save() + once again. + + + + The WinZip AES encryption algorithms are not supported on the .NET Compact + Framework. + + + + + + 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. + + + // 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"); + } + + + + ' 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 + + + + + + Thrown in the setter if EncryptionAlgorithm.Unsupported is specified. + + + ZipEntry.Password + ZipFile.Encryption + + + + The Password to be used when encrypting a ZipEntry upon + ZipFile.Save(), or when decrypting an entry upon Extract(). + + + + + 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. + + + + The password set here is implicitly used to encrypt the entry during the + operation, or to decrypt during the or operation. If you set + the Password on a ZipEntry after calling Save(), there is no + effect. + + + + Consider setting the 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, AES + Encryption uses a standard, strong, tested, encryption + algorithm. DotNetZip can create zip archives that use WinZip-compatible + AES encryption, if you set the 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." + + + + The class also has a + 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. + + + + Some comments on updating archives: If you read a ZipFile, 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 , and then adding a new + entry with a new Password. + + + + For example, suppose you read a ZipFile, and there is an encrypted + entry. Setting the Password property on that ZipEntry and then + calling Save() on the ZipFile does not update the password + on that entry in the archive. Neither is an exception thrown. Instead, + what happens during the Save() 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. + + + + If you read a ZipFile, and there is an un-encrypted entry, you can set the + Password on the entry and then call Save() on the ZipFile, and get + encryption on that entry. + + + + + + + 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. + + + // 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"); + } + + + + + 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 + + + + + + + ZipFile.Password + + + + The action the library should take when extracting a file that already exists. + + + + + This property affects the behavior of the Extract methods (one of the + Extract() or ExtractWithPassword() 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. + + + + This property has no effect when extracting to a stream, or when the file to be + extracted does not already exist. + + + + + + + This example shows how to set the ExtractExistingFile property in + an ExtractProgress event, in response to user input. The + ExtractProgress event is invoked if and only if the + ExtractExistingFile property was previously set to + ExtractExistingFileAction.InvokeExtractProgressEvent. + + 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; + } + } + + + + + + The action to take when an error is encountered while + opening or reading files as they are saved into a zip archive. + + + + + Errors can occur within a call to ZipFile.Save, as the various files contained + in a ZipFile are being saved into the zip archive. During the + Save, DotNetZip will perform a File.Open 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. + + + + Typically you will NOT set this property on individual ZipEntry + instances. Instead, you will set the ZipFile.ZipErrorAction property on + the ZipFile instance, before adding any entries to the + ZipFile. If you do this, errors encountered on behalf of any of + the entries in the ZipFile will be handled the same way. + + + + But, if you use a handler, you will want + to set this property on the ZipEntry within the handler, to + communicate back to DotNetZip what you would like to do with the + particular error. + + + + + + + + + Indicates whether the entry was included in the most recent save. + + + An entry can be excluded or skipped from a save if there is an error + opening or reading the entry. + + + + + + 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. + + + + + See + + + + + + Set to indicate whether to use UTF-8 encoding for filenames and comments. + + + + + + If this flag is set, the comment and filename for the entry will be + encoded with UTF-8, as described in the Zip + specification, if necessary. "Necessary" means, the filename or + entry comment (if any) cannot be reflexively encoded and decoded using the + default code page, IBM437. + + + + Setting this flag to true is equivalent to setting to System.Text.Encoding.UTF8. + + + + This flag has no effect or relation to the text encoding used within the + file itself. + + + + + + + The text encoding to use for the FileName and Comment on this ZipEntry, + when the default encoding is insufficient. + + + + + + Don't use this property. See . + + + + + + + Specifies the alternate text encoding used by this ZipEntry + + + + 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. + + + When creating a zip file, the usage of the alternate encoding is + governed by the property. + Typically you would set both properties to tell DotNetZip to employ an + encoding that is not IBM437 in the zipfile you are creating. + + + 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. + + + 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. + + + + This example shows how to create a zipfile encoded with a + language-specific encoding: + + 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"); + } + + + + + + + Describes if and when this instance should apply + AlternateEncoding to encode the FileName and Comment, when + saving. + + + + + + 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. + + + + + 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. + + + + 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. + + + + 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. + + + + 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. + + + + This property merely tells a reading application what is stored in the + metadata for an entry, without guaranteeing its validity or its + meaning. + + + + 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 + Save() on the ZipFile. + + + + 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, you + need to read and parse the registry. + + + + + using (var zip = new ZipFile()) + { + var e = zip.UpdateFile("Descriptions.mme", ""); + e.IsText = true; + zip.Save(zipPath); + } + + + + Using zip As New ZipFile + Dim e2 as ZipEntry = zip.AddFile("Descriptions.mme", "") + e.IsText= True + zip.Save(zipPath) + End Using + + + + + Provides a string representation of the instance. + a string representation of the instance. + + + + Extract the entry to the filesystem, starting at the current + working directory. + + + + 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 ExtractWithPassword() methods. + + + + + + + + + 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. + + + + The action taken when extraction an entry would overwrite an + existing file is determined by the property. + + + + Within the call to Extract(), 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 property on + the entry. See the remarks the property for + some details about the last modified time. + + + + + + + Extract the entry to a file in the filesystem, using the specified + behavior when extraction would overwrite an existing file. + + + + + See the remarks on the property, for some + details about how the last modified time of the file is set after + extraction. + + + + + The action to take if extraction would overwrite an existing file. + + + + + Extracts the entry to the specified stream. + + + + + The caller can specify any write-able stream, for example a , a , or ASP.NET's + Response.OutputStream. The content will be decrypted and + decompressed as necessary. If the entry is encrypted and no password + is provided, this method will throw. + + + 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(). + + + + + the stream to which the entry should be extracted. + + + + + + Extract the entry to the filesystem, starting at the specified base + directory. + + + the pathname of the base directory + + + + + + This example extracts only the entries in a zip file that are .txt files, + into a directory called "textfiles". + + using (ZipFile zip = ZipFile.Read("PackedDocuments.zip")) + { + foreach (string s1 in zip.EntryFilenames) + { + if (s1.EndsWith(".txt")) + { + zip[s1].Extract("textfiles"); + } + } + } + + + 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 + + + + + + + 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 property, or call + . + + + + See the remarks on the property, for some + details about how the last modified time of the created file is set. + + + + + + Extract the entry to the filesystem, starting at the specified base + directory, and using the specified behavior when extraction would + overwrite an existing file. + + + + + See the remarks on the property, for some + details about how the last modified time of the created file is set. + + + + + + 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); + } + } + + + + 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 + + + + the pathname of the base directory + + The action to take if extraction would overwrite an existing file. + + + + + Extract the entry to the filesystem, using the current working directory + and the specified password. + + + + This method has a bunch of overloads! One of them is sure to be + the right one for you... + + + + + + + + + Existing entries in the filesystem will not be overwritten. If you + would like to force the overwrite of existing files, see the property, or call + . + + + + See the remarks on the property for some + details about how the "last modified" time of the created file is + set. + + + + + In this example, entries that use encryption are extracted using a + particular password. + + using (var zip = ZipFile.Read(FilePath)) + { + foreach (ZipEntry e in zip) + { + if (e.UsesEncryption) + e.ExtractWithPassword("Secret!"); + else + e.Extract(); + } + } + + + 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 + + + The Password to use for decrypting the entry. + + + + Extract the entry to the filesystem, starting at the specified base + directory, and using the specified password. + + + + + + + + Existing entries in the filesystem will not be overwritten. If you + would like to force the overwrite of existing files, see the property, or call + . + + + + See the remarks on the property, for some + details about how the last modified time of the created file is set. + + + + The pathname of the base directory. + The Password to use for decrypting the entry. + + + + 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. + + + + + See the remarks on the property, for some + details about how the last modified time of the created file is set. + + + + The Password to use for decrypting the entry. + + + The action to take if extraction would overwrite an existing file. + + + + + Extract the entry to the filesystem, starting at the specified base + directory, and using the specified behavior when extraction would + overwrite an existing file. + + + + See the remarks on the property, for some + details about how the last modified time of the created file is set. + + + the pathname of the base directory + + The action to take if extraction would + overwrite an existing file. + + The Password to use for decrypting the entry. + + + + Extracts the entry to the specified stream, using the specified + Password. For example, the caller could extract to Console.Out, or + to a MemoryStream. + + + + + The caller can specify any write-able stream, for example a , a , or ASP.NET's + Response.OutputStream. The content will be decrypted and + decompressed as necessary. If the entry is encrypted and no password + is provided, this method will throw. + + + 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(). + + + + + + the stream to which the entry should be extracted. + + + The password to use for decrypting the entry. + + + + + Opens a readable stream corresponding to the zip entry in the + archive. The stream decompresses and decrypts as necessary, as it + is read. + + + + + + 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 . + + + + The return value is of type . Use it as you would any + stream for reading. When an application calls on that stream, it will + receive data from the zip entry that is decrypted and decompressed + as necessary. + + + + CrcCalculatorStream adds one additional feature: it keeps a + CRC32 checksum on the bytes of the stream as it is read. The CRC + value is available in the property on the + CrcCalculatorStream. When the read is complete, your + application + should check this CRC against the + property on the ZipEntry 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. + + + + If the entry is protected with a password, then you need to provide + a password prior to calling , either by + setting the property on the entry, or the + property on the ZipFile + itself. Or, you can use , the + overload of OpenReader that accepts a password parameter. + + + + If you want to extract entry data into a write-able stream that is + already opened, like a , do not + use this method. Instead, use . + + + + 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(). + + + + The OpenReader() method works only when the ZipEntry is + obtained from an instance of ZipFile. This method will throw + an exception if the ZipEntry is obtained from a . + + + + + 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 ZipEntry, to verify the extraction. + + 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)); + } + } + + + 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 + + + + The Stream for reading. + + + + Opens a readable stream for an encrypted zip entry in the archive. + The stream decompresses and decrypts as necessary, as it is read. + + + + + See the documentation on the method for + full details. This overload allows the application to specify a + password for the ZipEntry to be read. + + + + The password to use for decrypting the entry. + The Stream for reading. + + + + Pass in either basedir or s, but not both. + In other words, you can extract to a stream or to a directory (filesystem), but not both! + The Password param is required for encrypted entries. + + + + + Extract to a stream + In other words, you can extract to a stream or to a directory (filesystem), but not both! + The Password param is required for encrypted entries. + + + + + Validates that the args are consistent; returning whether the caller can return + because it's done, or not (caller should continue) + + + + + Validates that the args are consistent; returning whether the caller can return + because it's done, or not (caller should continue) + + + + + Reads one ZipEntry from the given stream. The content for + the entry does not get decompressed or decrypted. This method + basically reads metadata, and seeks. + + the ZipContainer this entry belongs to. + + true of this is the first entry being read from the stream. + + the ZipEntry read from the stream. + + + + 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. + + + + + 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. + + + + + generate and return a byte array that encodes the filename + for the entry. + + + + 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. + + + + + + Stores the position of the entry source stream, or, if the position is + already stored, seeks to that position. + + + + + 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. + + + + The first time through, this method sets the _sourceStreamOriginalPosition + field. Subsequent calls to this method seek to that position. + + + + + + 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. + + + + + 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) + + + + + Prepare the given stream for output - wrap it in a CountingStream, and + then in a CRC stream, and an encryptor and deflator as appropriate. + + + + 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. + + + + + + An enum that specifies the type of timestamp available on the ZipEntry. + + + + + + The last modified time of a file can be stored in multiple ways in + a zip file, and they are not mutually exclusive: + + + + + 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 LastModified property. This value is always + present in the metadata for each zip entry. In some cases the value is + invalid, or zero. + + + + 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 ModifiedTime property. + + + + In the "Unix" format, a 4-byte quantity specifying the number of seconds since + January 1, 1970 UTC. + + + + 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. + + + + + + This bit field describes which of the formats were found in a ZipEntry that was read. + + + + + + + Default value. + + + + + A DOS timestamp with 2-second precision. + + + + + A Windows timestamp with 100-ns precision. + + + + + A Unix timestamp with 1-second precision. + + + + + A Unix timestamp with 1-second precision, stored in InfoZip v1 format. This + format is outdated and is supported for reading archives only. + + + + + The method of compression to use for a particular ZipEntry. + + + + PKWare's + ZIP Specification describes a number of distinct + cmopression methods that can be used within a zip + file. DotNetZip supports a subset of them. + + + + + No compression at all. For COM environments, the value is 0 (zero). + + + + + DEFLATE compression, as described in IETF RFC + 1951. This is the "normal" compression used in zip + files. For COM environments, the value is 8. + + + + + BZip2 compression, a compression algorithm developed by Julian Seward. + For COM environments, the value is 12. + + + + + An enum that specifies the source of the ZipEntry. + + + + + Default value. Invalid on a bonafide ZipEntry. + + + + + The entry was instantiated by calling AddFile() or another method that + added an entry from the filesystem. + + + + + The entry was instantiated via or + . + + + + + The ZipEntry was instantiated by reading a zipfile. + + + + + The content for the ZipEntry will be or was provided by the WriteDelegate. + + + + + The content for the ZipEntry will be obtained from the stream dispensed by the OpenDelegate. + The entry was instantiated via . + + + + + The content for the ZipEntry will be or was obtained from a ZipOutputStream. + + + + + 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. + + + + + 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. + + + + 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. + + + + 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. + + + + + + Throw an exception when an error occurs while zipping. This is the default + behavior. (For COM clients, this is a 0 (zero).) + + + + + 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.) + + + + + 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.) + + + + + When an error occurs, invoke the zipError event. The event type used is + . 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 on the + ZipProgressEventArgs.CurrentEntry to Skip. If you want the + exception to be thrown, set ZipErrorAction on the CurrentEntry + to Throw. If you want to cancel the zip, set + ZipProgressEventArgs.Cancel 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.) + + + + + The ZipFile type represents a zip archive file. + + + + + This is the main type in the DotNetZip class library. This class reads and + writes zip files, as defined in the specification + for zip files described by PKWare. The compression for this + implementation is provided by a managed-code version of Zlib, included with + DotNetZip in the classes in the Ionic.Zlib namespace. + + + + 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 + Stream type to write the zip file, you may want to consider the class. + + + + Both the ZipOutputStream class and the ZipFile 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. + + + + The ZipFile class is generally easier to use than + ZipOutputStream and should be considered a higher-level interface. For + example, when creating a zip file via calls to the PutNextEntry() and + Write() methods on the ZipOutputStream class, the caller is + responsible for opening the file, reading the bytes from the file, writing + those bytes into the ZipOutputStream, setting the attributes on the + ZipEntry, 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 ZipFile.AddFile(). + For this reason, the ZipOutputStream 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 Stream + metaphor. + + + + Aside from the differences in programming model, there are other + differences in capability between the two classes. + + + + + ZipFile can be used to read and extract zip files, in addition to + creating zip files. ZipOutputStream cannot read zip files. If you want + to use a stream to read zip files, check out the class. + + + + ZipOutputStream does not support the creation of segmented or spanned + zip files. + + + + ZipOutputStream cannot produce a self-extracting archive. + + + + + Be aware that the ZipFile class implements the interface. In order for ZipFile to + produce a valid zip file, you use use it within a using clause (Using + in VB), or call the Dispose() method explicitly. See the examples + for how to employ a using clause. + + + + + + + Adds an item, either a file or a directory, to a zip file archive. + + + + + 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 ZipFile. + + + + The name of the item may be a relative path or a fully-qualified + path. Remember, the items contained in ZipFile instance get written + to the disk only when you call or a similar + save method. + + + + The directory name used for the file within the archive is the same + as the directory name (potentially a relative path) specified in the + . + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to the + ZipEntry added. + + + + + + + + + This method has two overloads. + + the name of the file or directory to add. + + The ZipEntry added. + + + + 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. + + + + + If adding a directory, the add is recursive on all files and + subdirectories contained within it. + + + The name of the item may be a relative path or a fully-qualified path. + The item added by this call to the ZipFile is not read from the + disk nor written to the zip file archive until the application calls + Save() on the ZipFile. + + + + 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. + + + + Encryption will be used on the file data if the Password has + been set on the ZipFile object, prior to calling this method. + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to the + ZipEntry added. + + + + + + Thrown if the file or directory passed in does not exist. + + + the name of the file or directory to add. + + + + 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 null (Nothing in VB) will use the + path on the fileOrDirectoryName. Passing the empty string ("") will + insert the item at the root path within the archive. + + + + + + + + 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. + + + 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); + } + + + + 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 + + + The ZipEntry added. + + + + Adds a File to a Zip file archive. + + + + + 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 ZipFile, does DotNetZip read the file from the filesystem and + then write the content to the zip file archive. + + + + This method will throw an exception if an entry with the same name already + exists in the ZipFile. + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to the + ZipEntry added. + + + + + + + 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. + + + 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); + } + + + + 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 + + + + This method has two overloads. + + + + + + + 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. + + The ZipEntry corresponding to the File added. + + + + Adds a File to a Zip file archive, potentially overriding the path to be + used within the zip archive. + + + + + The file added by this call to the ZipFile is not written to the + zip file archive until the application calls Save() on the ZipFile. + + + + This method will throw an exception if an entry with the same name already + exists in the ZipFile. + + + + This version of the method allows the caller to explicitly specify the + directory path to be used in the archive. + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to the + ZipEntry added. + + + + + + + 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. + + + 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); + } + + + + 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 + + + + + + + + + The name of the file to add. The name of the file may be a relative path + or a fully-qualified path. + + + + Specifies a directory path to use to override any path in the fileName. + This path may, or may not, correspond to a real directory in the current + filesystem. If the files within the zip are later extracted, this is the + path used for the extracted file. Passing null (Nothing in + VB) will use the path on the fileName, if any. Passing the empty string + ("") will insert the item at the root path within the archive. + + + The ZipEntry corresponding to the file added. + + + + This method removes a collection of entries from the ZipFile. + + + + 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. + + + + + + + + This method removes a collection of entries from the ZipFile, by name. + + + + A collection of strings that refer to names of entries to be removed + from the ZipFile. For example, you can pass in an array or a + List of Strings that provide the names of entries to be removed. + + + + + + + + This method adds a set of files to the ZipFile. + + + + + Use this method to add a set of files to the zip archive, in one call. + For example, a list of files received from + System.IO.Directory.GetFiles() can be added to a zip archive in one + call. + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to each + ZipEntry added. + + + + + 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. + + + + This example shows how to create a zip file, and add a few files into it. + + 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); + } + + + + 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 + + + + + + + + Adds or updates a set of files in the ZipFile. + + + + + Any files that already exist in the archive are updated. Any files that + don't yet exist in the archive are added. + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to each + ZipEntry added. + + + + + 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. + + + + + + Adds a set of files to the ZipFile, using the + specified directory path in the archive. + + + + + 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. + + + + For ZipFile properties including , , , , , , and , their respective values at the + time of this call will be applied to each ZipEntry added. + + + + + 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. + + + + 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 null (Nothing in + VB) will use the path on each of the fileNames, if any. Passing + the empty string ("") will insert the item at the root path within the + archive. + + + + + + + Adds a set of files to the ZipFile, using the specified directory + path in the archive, and preserving the full directory structure in the + filenames. + + + + + + Think of the as a "root" or + base directory used in the archive for the files that get added. when + is true, the hierarchy of files + found in the filesystem will be placed, with the hierarchy intact, + starting at that root in the archive. When preserveDirHierarchy + is false, the path hierarchy of files is flattned, and the flattened + set of files gets placed in the root within the archive as specified in + directoryPathInArchive. + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to each + ZipEntry added. + + + + + + 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. + + + + Specifies a directory path to use as a prefix for each entry 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 null (Nothing in + VB) will use the path on each of the fileNames, if any. Passing + the empty string ("") will insert the item at the root path within the + archive. + + + + whether the entries in the zip archive will reflect the directory + hierarchy that is present in the various filenames. For example, if + includes two paths, + \Animalia\Chordata\Mammalia\Info.txt and + \Plantae\Magnoliophyta\Dicotyledon\Info.txt, then calling this method + with = false will + result in an exception because of a duplicate entry name, while + calling this method with = + true will result in the full direcory paths being included in + the entries added to the ZipFile. + + + + + + Adds or updates a set of files to the ZipFile, using the specified + directory path in the archive. + + + + + + Any files that already exist in the archive are updated. Any files that + don't yet exist in the archive are added. + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to each + ZipEntry added. + + + + + 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. + + + + 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 null (Nothing in + VB) will use the path on each of the fileNames, if any. Passing + the empty string ("") will insert the item at the root path within the + archive. + + + + + + + Adds or Updates a File in a Zip file archive. + + + + + 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 UpdateFile method might more accurately be + called "AddOrUpdateFile". + + + + Upon success, there is no way for the application to learn whether the file + was added versus updated. + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to the + ZipEntry added. + + + + + + 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. + + + 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(); + } + + + + 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 + + + + + + + + + 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. + + + + The ZipEntry corresponding to the File that was added or updated. + + + + + Adds or Updates a File in a Zip file archive. + + + + + 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. + + + + 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. + + + + Upon success, there is no way for the application to learn if the file was + added versus updated. + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to the + ZipEntry added. + + + + + + + + + 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. + + + + Specifies a directory path to use to override any path in the + fileName. This path may, or may not, correspond to a real + directory in the current filesystem. If the files within the zip are + later extracted, this is the path used for the extracted file. Passing + null (Nothing in VB) will use the path on the + fileName, if any. Passing the empty string ("") will insert the + item at the root path within the archive. + + + + The ZipEntry corresponding to the File that was added or updated. + + + + + Add or update a directory in a zip archive. + + + + If the specified directory does not exist in the archive, then this method + is equivalent to calling AddDirectory(). 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. + + + + + + + + The path to the directory to be added to the zip archive, or updated in + the zip archive. + + + + The ZipEntry corresponding to the Directory that was added or updated. + + + + + Add or update a directory in the zip archive at the specified root + directory in the archive. + + + + If the specified directory does not exist in the archive, then this method + is equivalent to calling AddDirectory(). 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. + + + + + + + + The path to the directory to be added to the zip archive, or updated + in the zip archive. + + + + 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 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 + directoryName, if any. Passing the empty string ("") will insert + the item at the root path within the archive. + + + + The ZipEntry corresponding to the Directory that was added or updated. + + + + + Add or update a file or directory in the zip archive. + + + + + 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 ZipFile. Calling this method + is equivalent to calling RemoveEntry() if an entry by the same name + already exists, followed calling by AddItem(). + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to the + ZipEntry added. + + + + + + + + + the path to the file or directory to be added or updated. + + + + + Add or update a file or directory. + + + + + 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 ZipFile. Calling this method + is equivalent to calling RemoveEntry(), if an entry by that name + exists, and then calling AddItem(). + + + + 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 + DirectoryPathInArchive. Extracting the entry from the archive will + result in a file stored in that directory path. + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to the + ZipEntry added. + + + + + + + + + The path for the File or Directory to be added or updated. + + + Specifies a directory path to use to override any path in the + itemName. 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 + itemName, if any. Passing the empty string ("") will insert the + item at the root path within the archive. + + + + + Adds a named entry into the zip archive, taking content for the entry + from a string. + + + + 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. + + + + The content of the file, should it be extracted from the zip. + + + + The name, including any path, to use for the entry within the archive. + + + The ZipEntry added. + + + + This example shows how to add an entry to the zipfile, using a string as + content for that entry. + + + 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"); + } + + + + 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 + + + + + + Adds a named entry into the zip archive, taking content for the entry + from a string, and using the specified text encoding. + + + + + + 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, 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. + + + + Most Encoding classes support a constructor that accepts a boolean, + indicating whether to emit a BOM or not. For example see . + + + + + + The name, including any path, to use within the archive for the entry. + + + + The content of the file, should it be extracted from the zip. + + + + 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 . + + + The ZipEntry added. + + + + + Create an entry in the ZipFile using the given Stream + as input. The entry will have the given filename. + + + + + + The application should provide an open, readable stream; in this case it + will be read during the call to or one of + its overloads. + + + + 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. + + + + In cases where a large number of streams will be added to the + ZipFile, the application may wish to avoid maintaining all of the + streams open simultaneously. To handle this situation, the application + should use the + overload. + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to the + ZipEntry added. + + + + + + + This example adds a single entry to a ZipFile via a Stream. + + + + 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 + } + } + + + + 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 + + + + + + + The name, including any path, which is shown in the zip file for the added + entry. + + + The input stream from which to grab content for the file + + The ZipEntry added. + + + + Add a ZipEntry for which content is written directly by the application. + + + + + 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. + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to the + ZipEntry added. + + + + About progress events: When using the WriteDelegate, DotNetZip does + not issue any SaveProgress events with EventType = + Saving_EntryBytesRead. (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 + Saving_Started, + + Saving_BeforeWriteEntry, and + Saving_AfterWriteEntry. + + + + 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. + + + + 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. + + + + As you can imagine, this can cause performance problems for large + streams, and it can lead to correctness problems when you use a + WriteDelegate. 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. + + + + 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 the Workitem + tracking this issue. + + + + + the name of the entry to add + the delegate which will write the entry content + the ZipEntry added + + + + 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. + + + 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); + } + + + + + + 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 + AddFile() 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 WriteDelegate to do it, in this way. + + + 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); + } + } + + + + + + 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 AddFile() method. The key scenario for + which the WriteDelegate 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 WriteDelegate would be appropriate for those cases as + well. + + + 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 + + + + + + Add an entry, for which the application will provide a stream + containing the entry data, on a just-in-time basis. + + + + + 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. The application provides an + opener delegate that will be called by the DotNetZip library to + obtain a readable stream that can be read to get the bytes for + the given entry. Typically, this delegate opens a stream. + Optionally, the application can provide a closer delegate as + well, which will be called by DotNetZip when all bytes have been + read from the entry. + + + + These delegates are called from within the scope of the call to + ZipFile.Save(). + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to the + ZipEntry added. + + + + + + + This example uses anonymous methods in C# to open and close the + source stream for the content for a zip entry. + + + 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); + } + + + + + + + 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. + + + + 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 + + + + + the name of the entry to add + + the delegate that will be invoked by ZipFile.Save() to get the + readable stream for the given entry. ZipFile.Save() will call + read on this stream to obtain the data for the entry. This data + will then be compressed and written to the newly created zip + file. + + + the delegate that will be invoked to close the stream. This may + be null (Nothing in VB), in which case no call is makde to close + the stream. + + the ZipEntry added + + + + + Updates the given entry in the ZipFile, using the given + string as content for the ZipEntry. + + + + + + Calling this method is equivalent to removing the ZipEntry for + the given file name and directory path, if it exists, and then calling + . See the documentation for + that method for further explanation. The string content is encoded + using the default encoding for the machine. This encoding is distinct + from the encoding used for the filename itself. See + . + + + + + + The name, including any path, to use within the archive for the entry. + + + + The content of the file, should it be extracted from the zip. + + + The ZipEntry added. + + + + + Updates the given entry in the ZipFile, using the given string as + content for the ZipEntry. + + + + Calling this method is equivalent to removing the ZipEntry for the + given file name and directory path, if it exists, and then calling . See the + documentation for that method for further explanation. + + + + The name, including any path, to use within the archive for the entry. + + + + The content of the file, should it be extracted from the zip. + + + + The text encoding to use when encoding the string. Be aware: This is + distinct from the text encoding used to encode the filename. See . + + + The ZipEntry added. + + + + + Updates the given entry in the ZipFile, using the given delegate + as the source for content for the ZipEntry. + + + + Calling this method is equivalent to removing the ZipEntry for the + given file name and directory path, if it exists, and then calling . See the + documentation for that method for further explanation. + + + + The name, including any path, to use within the archive for the entry. + + + the delegate which will write the entry content. + + The ZipEntry added. + + + + + Updates the given entry in the ZipFile, using the given delegates + to open and close the stream that provides the content for the ZipEntry. + + + + Calling this method is equivalent to removing the ZipEntry for the + given file name and directory path, if it exists, and then calling . See the + documentation for that method for further explanation. + + + + The name, including any path, to use within the archive for the entry. + + + + the delegate that will be invoked to open the stream + + + the delegate that will be invoked to close the stream + + + The ZipEntry added or updated. + + + + + Updates the given entry in the ZipFile, using the given stream as + input, and the given filename and given directory Path. + + + + + Calling the method is equivalent to calling RemoveEntry() if an + entry by the same name already exists, and then calling AddEntry() + with the given fileName and stream. + + + + The stream must be open and readable during the call to + ZipFile.Save. You can dispense the stream on a just-in-time basis + using the property. Check the + documentation of that property for more information. + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to the + ZipEntry added. + + + + + + + + + The name, including any path, to use within the archive for the entry. + + + The input stream from which to read file data. + The ZipEntry added. + + + + 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. + + + The data to use for the entry. + + + The name, including any path, to use within the archive for the entry. + + + The ZipEntry added. + + + + Updates the given entry in the ZipFile, using the given byte + array as content for the entry. + + + + Calling this method is equivalent to removing the ZipEntry + for the given filename and directory path, if it exists, and then + calling . See the + documentation for that method for further explanation. + + + + The name, including any path, to use within the archive for the entry. + + + The content to use for the ZipEntry. + + The ZipEntry added. + + + + + Adds the contents of a filesystem directory to a Zip file archive. + + + + + + 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. + + + + 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. + + + + 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. + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to each + ZipEntry added. + + + + + + + + + + This method has 2 overloads. + + The name of the directory to add. + The ZipEntry added. + + + + Adds the contents of a filesystem directory to a Zip file archive, + overriding the path to be used for entries in the archive. + + + + + 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. + + + + 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. + + + + For ZipFile properties including , , , , , + , and , their + respective values at the time of this call will be applied to each + ZipEntry added. + + + + + + + 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. + + + + public void ZipUp(string targetZip, string directory) + { + using (var zip = new ZipFile()) + { + zip.AddDirectory(directory, System.IO.Path.GetFileName(directory)); + zip.Save(targetZip); + } + } + + + + + + + + The name of the directory to add. + + + 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 null + (Nothing in VB) or the empty string ("") will insert the items at + the root path within the archive. + + + The ZipEntry added. + + + + Creates a directory in the zip archive. + + + + + + Use this when you want to create a directory in the archive but there is + no corresponding filesystem representation for that directory. + + + + 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. + + + + + + The name of the directory to create in the archive. + + The ZipEntry added. + + + + Checks a zip file to see if its directory is consistent. + + + + + + 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. + + + This method may take a long time to run for large zip files. + + + This method is not supported in the Reduced version of DotNetZip. + + + + Developers using COM can use the ComHelper.CheckZip(String) + method. + + + + + The filename to of the zip file to check. + + true if the named zip file checks OK. Otherwise, false. + + + + + + + Checks a zip file to see if its directory is consistent, + and optionally fixes the directory if necessary. + + + + + + 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 Name_Fixed.zip. + + + + 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 + fixIfNecessary is true. + + + + This method is not supported in the Reduced version of DotNetZip. + + + + + The filename to of the zip file to check. + + If true, the method will fix the zip file if + necessary. + + + a TextWriter in which messages generated while checking will be written. + + + true if the named zip is OK; false if the file needs to be fixed. + + + + + + + Rewrite the directory within a zipfile. + + + + + + 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. + + + This can take a long time for large zip files. + + This won't work if the zip file uses a non-standard + code page - neither IBM437 nor UTF-8. + + + This method is not supported in the Reduced or Compact Framework + versions of DotNetZip. + + + + Developers using COM can use the ComHelper.FixZipDirectory(String) + method. + + + + + The filename to of the zip file to fix. + + + + + + + Verify the password on a zip file. + + + + + 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. + + + There is no way to check a password without doing the + decryption. So this code decrypts and extracts the given + zipfile into + + + + The filename to of the zip file to fix. + + The password to check. + + a bool indicating whether the password matches. + + + + Provides a human-readable string with information about the ZipFile. + + + + + 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. + + + This information is mostly useful for diagnostic purposes. + + + + + + Indicates whether to perform a full scan of the zip file when reading it. + + + + + + You almost never want to use this property. + + + + When reading a zip file, if this flag is true (True 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. + + + + This flag is effective only when calling . Normally you would read a ZipFile with the + static ZipFile.Read + method. But you can't set the FullScan property on the + ZipFile instance when you use a static factory method like + ZipFile.Read. + + + + + + + This example shows how to read a zip file using the full scan approach, + and then save it, thereby producing a corrected zip file. + + + using (var zip = new ZipFile()) + { + zip.FullScan = true; + zip.Initialize(zipFileName); + zip.Save(newName); + } + + + + Using zip As New ZipFile + zip.FullScan = True + zip.Initialize(zipFileName) + zip.Save(newName) + End Using + + + + + + + Whether to sort the ZipEntries before saving the file. + + + + The default is false. If you have a large number of zip entries, the sort + alone can consume significant time. + + + + + using (var zip = new ZipFile()) + { + zip.AddFiles(filesToAdd); + zip.SortEntriesBeforeSaving = true; + zip.Save(name); + } + + + + Using zip As New ZipFile + zip.AddFiles(filesToAdd) + zip.SortEntriesBeforeSaving = True + zip.Save(name) + End Using + + + + + + + Indicates whether NTFS Reparse Points, like junctions, should be + traversed during calls to AddDirectory(). + + + + 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. + + + + + using (var zip = new ZipFile()) + { + zip.AddDirectoryWillTraverseReparsePoints = false; + zip.AddDirectory(dirToZip,"fodder"); + zip.Save(zipFileToCreate); + } + + + + + + Size of the IO buffer used while saving. + + + + + + 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? + + + + Now that we have that 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. + + + + Changing the buffer size affects a few things: first, for larger buffer + sizes, the memory used by the ZipFile, 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. + + + + 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. + + + + + + This example shows how you might set a large buffer size for efficiency when + dealing with zip entries that are larger than 1gb. + + 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); + } + + + + + + Size of the work buffer to use for the ZLIB codec during compression. + + + + + 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 ZipFile.Save() + overloads. + + + 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. + + + + + + Indicates whether extracted files should keep their paths as + stored in the zip archive. + + + + + This property affects Extraction. It is not used when creating zip + archives. + + + + With this property set to false, 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 true, extracting entries from the zip file results in files + with no path: the folders are "flattened." + + + + An example: suppose the zip file contains entries /directory1/file1.txt and + /directory2/file2.txt. With FlattenFoldersOnExtract 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. + + + + + + + The compression strategy to use for all entries. + + + + 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 Ionic.Zlib.CompressionStrategy. + + + + + The name of the ZipFile, on disk. + + + + + + When the ZipFile instance was created by reading an archive using + one of the ZipFile.Read methods, this property represents the name + of the zip file that was read. When the ZipFile instance was + created by using the no-argument constructor, this value is null + (Nothing in VB). + + + + If you use the no-argument constructor, and you then explicitly set this + property, when you call , this name will + specify the name of the zip file created. Doing so is equivalent to + calling . When instantiating a + ZipFile by reading from a stream or byte array, the Name + property remains null. When saving to a stream, the Name + property is implicitly set to null. + + + + + + Sets the compression level to be used for entries subsequently added to + the zip archive. + + + + + Varying the compression level used on entries can affect the + size-vs-speed tradeoff when compression and decompressing data streams + or files. + + + + As with some other properties on the ZipFile class, like , , and , setting this property on a ZipFile + instance will cause the specified CompressionLevel to be used on all + items that are subsequently added to the + ZipFile instance. If you set this property after you have added + items to the ZipFile, but before you have called Save(), + those items will not use the specified compression level. + + + + 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 BestCompression 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. + + + + + + The compression method for the zipfile. + + + + By default, the compression method is CompressionMethod.Deflate. + + + + + + + A comment attached to the zip archive. + + + + + + This property is read/write. It allows the application to specify a + comment for the ZipFile, or read the comment for the + ZipFile. After setting this property, changes are only made + permanent when you call a Save() method. + + + + According to PKWARE's + zip specification, the comment is not encrypted, even if there is a + password set on the zip file. + + + + 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 is + Never, it uses the default encoding (IBM437). (b) if is Always, it always uses the + alternate encoding (). (c) if is AsNecessary, 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 ZipFile.Save(). + + + + When creating a zip archive using this library, it is possible to change + the value of between each + entry you add, and between adding entries and the call to + Save(). 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 + alone, or specify it only + once, before adding any entries to the ZipFile instance. + + + + + + + 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. + + + + + 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 + true, meaning the Windows-format times are stored in the zip + archive. + + + + 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, all three values are implicitly set to + DateTime.Now. Applications can also explicitly set those times by + calling . + + + + PKWARE's + zip specification 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. + + + + 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 Infozip + 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. + + + + The times stored are taken from , , and . + + + + The value set here applies to all entries subsequently added to the + ZipFile. + + + + This property is not mutually exclusive of the 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 LastModified 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. + + + + 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. + + + + + This example shows how to save a zip file that contains file timestamps + in a format normally used by Unix. + + 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); + } + + + + 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 + + + + + + + + + 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. + + + + + 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 + false, meaning the Unix-format times are not stored in the zip + archive. + + + + 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, all three values are implicitly set to DateTime.Now. + Applications can also explicitly set those times by calling . + + + + PKWARE's + zip specification 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. + + + + 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 Infozip + 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. + + + + The times stored are taken from , , and . + + + + This property is not mutually exclusive of the 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 LastModified 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. + + + + 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. + + + + + + + + + Indicates whether verbose output is sent to the during AddXxx() and + ReadXxx() operations. + + + + This is a synthetic property. It returns true if the is non-null. + + + + + Returns true if an entry by the given name exists in the ZipFile. + + + the name of the entry to find + true if an entry with the given name exists; otherwise false. + + + + + Indicates whether to perform case-sensitive matching on the filename when + retrieving entries in the zipfile via the string-based indexer. + + + + The default value is false, 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 true 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. + + + + + Indicates whether to ignore duplicate files (report only the first entry) + when loading a zipfile. + + + + The default value is false, which will try to make all files + available (duplicates will have a "copy" suffix appended to their name). + Setting this to true prior to using Initialize to read a + zipfile will prevent this and instead just ignore the duplicates. + + + + + Indicates whether to encode entry filenames and entry comments using Unicode + (UTF-8). + + + + + The + PKWare zip specification 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. + + + + 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. + + + + 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. + + + + 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. + + + + 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. + + + + 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. + + + + If you do not set this flag, it will remain false. If this flag is false, + your ZipFile 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". + + + + 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 ZipFile, 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. + + + + 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. + + + + Rather than specify the encoding in a binary fashion using this flag, an + application can specify an arbitrary encoding via the 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. + + + + + + + Specify whether to use ZIP64 extensions when saving a zip archive. + + + + + + When creating a zip file, the default value for the property is . is + safest, in the sense that you will not get an Exception if a pre-ZIP64 + limit is exceeded. + + + + You may set the property at any time before calling Save(). + + + + When reading a zip file via the Zipfile.Read() 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. + + + + An interesting question is, if you have set this property to + AsNecessary, and then successfully saved, does the resulting + archive use ZIP64 extensions or not? To learn this, check the property, after calling Save(). + + + + Have you thought about + donating? + + + + + + + + Indicates whether the archive requires ZIP64 extensions. + + + + + + This property is null (or Nothing in VB) if the archive has + not been saved, and there are fewer than 65334 ZipEntry items + contained in the archive. + + + + The Value 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 Save() is attempted + on the zip archive. The Value of this + property may be set only AFTER one of the Save() methods has been called. + + + + If none of the four conditions holds, and the archive has been saved, then + the Value is false. + + + + A Value 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 property is set to , or if the property is set to and the output stream was not + seekable. Use the property to determine if + the most recent Save() method resulted in an archive that utilized + the ZIP64 extensions. + + + + + + + + + Indicates whether the most recent Save() operation used ZIP64 extensions. + + + + + 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 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 ZipFile. + + + + The value is null (or Nothing in VB) if the archive has not + been saved. + + + + Non-null values (HasValue is true) indicate whether ZIP64 + extensions were used during the most recent Save() 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 UseZip64WhenSaving property was set + to , or because the + UseZip64WhenSaving property was set to and the output stream was not seekable. + The value of this property does not indicate the reason the ZIP64 + extensions were used. + + + + + + + + + Indicates whether the most recent Read() operation read a zip file that uses + ZIP64 extensions. + + + + This property will return null (Nothing in VB) if you've added an entry after reading + the zip file. + + + + + The text encoding to use when writing new entries to the ZipFile, + 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 ZipFile. + + + + + In its + zip specification, 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. + + + + 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 and for each ZipEntry 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 + Comment encoded in IBM437 and a FileName encoded with the + specified "provisional" codepage. + + + + Be aware that a zip file created after you've explicitly set the 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. + + + + When creating a zip archive using this library, it is possible to change + the value of between each + entry you add, and between adding entries and the call to + Save(). Don't do this. It will likely result in a zipfile that is + not readable. For best interoperability, either leave alone, or specify it only once, + before adding any entries to the ZipFile instance. There is one + exception to this recommendation, described later. + + + + 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. + + + + 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. + + + + Example: Suppose you create a zipfile that contains entries with + filenames that have Danish characters. If you use 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". + + + + 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 Zipfile is READ. This means you must use a ZipFile.Read() + 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. + + + + 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 + ProvisionalAlternateEncoding to your desired region-specific code + page, once before adding any entries, and then reset + ProvisionalAlternateEncoding to IBM437 before setting the property and calling Save(). + + + + + This example shows how to read a zip file using the Big-5 Chinese code page + (950), and extract each entry in the zip file. For this code to work as + desired, the Zipfile must have been created using the big5 code page + (CP950). This is typical, for example, when using WinRar on a machine with + CP950 set as the default code page. In that case, the names of entries + within the Zip archive will be stored in that code page, and reading the zip + archive must be done using that code page. If the application did not use + the correct code page in ZipFile.Read(), then names of entries within the + zip archive would not be correctly retrieved. + + 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"); + } + + + + 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 + + + + DefaultEncoding + + + + A Text Encoding to use when encoding the filenames and comments for + all the ZipEntry items, during a ZipFile.Save() operation. + + + + Whether the encoding specified here is used during the save depends + on . + + + + + + 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. + + + + + Gets or sets the TextWriter to which status messages are delivered + for the instance. + + + + If the TextWriter is set to a non-null value, then verbose output is sent + to the TextWriter during Add, Read, Save and + Extract operations. Typically, console applications might use + Console.Out and graphical or headless applications might use a + System.IO.StringWriter. The output of this is suitable for viewing + by humans. + + + + + In this example, a console application instantiates a ZipFile, then + sets the StatusMessageTextWriter to Console.Out. At that + point, all verbose status messages for that ZipFile are sent to the + console. + + + + using (ZipFile zip= ZipFile.Read(FilePath)) + { + zip.StatusMessageTextWriter= System.Console.Out; + // messages are sent to the console during extraction + zip.ExtractAll(); + } + + + + 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 + + + + In this example, a Windows Forms application instantiates a + ZipFile, then sets the StatusMessageTextWriter to a + StringWriter. At that point, all verbose status messages for that + ZipFile are sent to the StringWriter. + + + + var sw = new System.IO.StringWriter(); + using (ZipFile zip= ZipFile.Read(FilePath)) + { + zip.StatusMessageTextWriter= sw; + zip.ExtractAll(); + } + Console.WriteLine("{0}", sw.ToString()); + + + + 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 + + + + + + + Gets or sets the name for the folder to store the temporary file + this library writes when saving a zip archive. + + + + + This library will create a temporary file when saving a Zip archive to a + file. This file is written when calling one of the Save() methods + that does not save to a stream, or one of the SaveSelfExtractor() + methods. + + + + By default, the library will create the temporary file in the directory + specified for the file itself, via the property or via + the method. + + + + 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 ZipFile + is saved, specfy ".". To revert to the default behavior, set this + property to null (Nothing in VB). + + + + 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 Save() + is called. + + + + 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 Save() + specifying the Response.OutputStream as the output stream, there is + no temporary file created. + + + + + Thrown when setting the property if the directory does not exist. + + + + + + Sets the password to be used on the ZipFile instance. + + + + + + When writing a zip archive, this password is applied to the entries, not + to the zip archive itself. It applies to any ZipEntry subsequently + added to the ZipFile, using one of the AddFile, + AddDirectory, AddEntry, or AddItem methods, etc. + When reading a zip archive, this property applies to any entry + subsequently extracted from the ZipFile using one of the Extract + methods on the ZipFile class. + + + + 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. + + + + 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. + + + + If you set the password on the ZipFile, 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 null + (Nothing in VB), and add another entry, the first entry is + encrypted and the second is not. If you call AddFile(), then set + the Password property, then call ZipFile.Save, the file + added will not be password-protected, and no warning will be generated. + + + + When setting the Password, you may also want to explicitly set the 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 , then PKZip 2.0 ("Weak") encryption is used. + This encryption is relatively weak but is very interoperable. If you set + the password to a null value (Nothing in VB), Encryption is + reset to None. + + + + 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 + ZipFile, then call one of the Extract() overloads on the . In this case, the entry is extracted using the + Password that is specified on the ZipFile instance. If you + have not set the Password property, then the password is + null, and the entry is extracted with no password. + + + + If you set the Password property on the ZipFile, then call + Extract() an entry that has not been encrypted with a password, the + password is not used for that entry, and the ZipEntry is extracted + as normal. In other words, the password is used only if necessary. + + + + The class also has a Password property. It takes precedence + over this property on the ZipFile. 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. + + + + + + + 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. + + + // 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"); + } + + + + + 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 + + + + + + ZipFile.Encryption + ZipEntry.Password + + + + The action the library should take when extracting a file that already + exists. + + + + + This property affects the behavior of the Extract methods (one of the + Extract() or ExtractWithPassword() 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. + + + + This property has no effect when extracting to a stream, or when the file + to be extracted does not already exist. + + + + + + + The action the library should take when an error is encountered while + opening or reading files as they are saved into a zip archive. + + + + + 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. + + + + 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. + + + + This property tells DotNetZip what you would like to do in the case of + these errors. The primary options are: ZipErrorAction.Throw to + throw an exception (this is the default behavior if you don't set this + property); ZipErrorAction.Skip to Skip the file for which there + was an error and continue saving; ZipErrorAction.Retry to Retry + the entry that caused the problem; or + ZipErrorAction.InvokeErrorEvent to invoke an event handler. + + + + This property is implicitly set to ZipErrorAction.InvokeErrorEvent + if you add a handler to the event. If you set + this property to something other than + ZipErrorAction.InvokeErrorEvent, then the ZipError + 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. + + + + As with some other properties on the ZipFile class, like , , and , setting this property on a ZipFile + instance will cause the specified ZipErrorAction to be used on all + items that are subsequently added to the + ZipFile instance. If you set this property after you have added + items to the ZipFile, but before you have called Save(), + those items will not use the specified error handling action. + + + + 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. + + + + If you set this property to ZipErrorAction.Skip and you'd like to + learn which files may have been skipped after a Save(), you can + set the on the ZipFile before + calling Save(). A message will be emitted into that writer for + each skipped file, if any. + + + + + + This example shows how to tell DotNetZip to skip any files for which an + error is generated during the Save(). + + 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 + + + + + + + + + + The Encryption to use for entries added to the ZipFile. + + + + + 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 + ZipFile instance. Applications do not need to set the + Encryption property when reading or extracting a zip archive. + + + + If you set this to something other than EncryptionAlgorithm.None, you + will also need to set the . + + + + As with some other properties on the ZipFile class, like and , setting this + property on a ZipFile instance will cause the specified + EncryptionAlgorithm to be used on all items + that are subsequently added to the ZipFile instance. In other + words, if you set this property after you have added items to the + ZipFile, but before you have called Save(), 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 property, before calling + AddFile, AddItem, or AddDirectory (etc.) on the + ZipFile instance. + + + + If you read a ZipFile, you can modify the Encryption on an + encrypted entry, only by setting the Encryption property on the + ZipEntry itself. Setting the Encryption property on the + ZipFile, once it has been created via a call to + ZipFile.Read(), does not affect entries that were previously read. + + + + For example, suppose you read a ZipFile, and there is an encrypted + entry. Setting the Encryption property on that ZipFile and + then calling Save() on the ZipFile does not update the + Encryption used for the entries in the archive. Neither is an + exception thrown. Instead, what happens during the Save() 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. + + + + Suppose an application reads a ZipFile, and there is an encrypted + entry. Setting the Encryption property on that ZipFile and + then adding new entries (via AddFile(), AddEntry(), etc) + and then calling Save() on the ZipFile does not update the + Encryption on any of the entries that had previously been in the + ZipFile. The Encryption property applies only to the + newly-added entries. + + + + + + + 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. + + + + // 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"); + } + + + + ' 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 + + + + + ZipFile.Password + ZipEntry.Encryption + + + + A callback that allows the application to specify the compression level + to use for entries subsequently added to the zip archive. + + + + + + With this callback, the DotNetZip library allows the application to + determine whether compression will be used, at the time of the + Save. This may be useful if the application wants to favor + speed over size, and wants to defer the decision until the time of + Save. + + + + Typically applications set the property on + the ZipFile or on each ZipEntry to determine the level of + compression used. This is done at the time the entry is added to the + ZipFile. Setting the property to + Ionic.Zlib.CompressionLevel.None means no compression will be used. + + + + This callback allows the application to defer the decision on the + CompressionLevel to use, until the time of the call to + ZipFile.Save(). The callback is invoked once per ZipEntry, + at the time the data for the entry is being written out as part of a + Save() 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 None for all .mp3 entries. + + + + 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 CompressionLevel is set to the return value. If this + callback has not been set, then the previously set value for + CompressionLevel is used. + + + + + + + The maximum size of an output segment, when saving a split Zip file. + + + + Make sure you do not read from this field if you've set the value using + + + + Set this to a non-zero value before calling or 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. + + + + 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 + basename.z01, the second will be named basename.z02, and + so on. The final file is named basename.zip. 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. + + + + The value of this property determines the maximum size of a split + segment when writing a split archive. For example, suppose you have a + ZipFile that would save to a single file of 200k. If you set the + MaxOutputSegmentSize to 65536 before calling Save(), 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 + ZipFile. + + + + 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. + + + + 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. + + + + 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. + + + + This property has no effect when reading a split archive. You can read + a split archive in the normal way with DotNetZip. + + + + 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. + + + + If you read a split archive, with and + then subsequently call ZipFile.Save(), unless you set this + property before calling Save(), you will get a normal, + single-file archive. + + + + + + + + The maximum size of an output segment, when saving a split Zip file. + + + + If you set this value, make sure you do not accidently use in your code + + + + Set this to a non-zero value before calling or 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. + + + + 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 + basename.z01, the second will be named basename.z02, and + so on. The final file is named basename.zip. 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. + + + + The value of this property determines the maximum size of a split + segment when writing a split archive. For example, suppose you have a + ZipFile that would save to a single file of 200k. If you set the + MaxOutputSegmentSize to 65536 before calling Save(), 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 + ZipFile. + + + + 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. + + + + 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. + + + + 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. + + + + This property has no effect when reading a split archive. You can read + a split archive in the normal way with DotNetZip. + + + + 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. + + + + If you read a split archive, with and + then subsequently call ZipFile.Save(), unless you set this + property before calling Save(), you will get a normal, + single-file archive. + + + + + + + + Returns the number of segments used in the most recent Save() operation. + + + + This is normally zero, unless you have set the property. If you have set , 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. + + + 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. + + + + + + + The size threshold for an entry, above which a parallel deflate is used. + + + + + + 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. + + + + 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. + + + + 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. + + + + 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%. + + + + 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 . You may have to + perform some tests to determine the best approach for your situation. + + + + + + + + + + The maximum number of buffer pairs to use when performing + parallel compression. + + + + + 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 + ThreadPool.QueueUserWorkItem() to compress those + buffers in a background threadpool thread. After a buffer + is compressed, it is re-ordered and written to the output + stream. + + + + 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. + + + + 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 (). 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. + + + + 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. + + + + 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. + + + + 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. + + + + The application can set this value at any time + before calling ZipFile.Save(). + + + + + + + + Provides a string representation of the instance. + a string representation of the instance. + + + + Returns the version number on the DotNetZip assembly. + + + + + 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. + + + This static property is primarily useful for diagnostic purposes. + + + + + + Creates a new ZipFile instance, using the specified filename. + + + + + 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. + + + + 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 + ZipFile via AddDirectory(), AddFile(), AddItem() + and then write the zip archive to the disk by calling Save(). The + zip file is not actually opened and written to the disk until the + application calls ZipFile.Save(). At that point the new zip file + with the given name is created. + + + + If you won't know the name of the Zipfile until the time you call + ZipFile.Save(), or if you plan to save to a stream (which has no + name), then you should use the no-argument constructor. + + + + 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 method, + passing the name of the zip file, because using ZipFile.Read() in + your code communicates very clearly what you are doing. In either case, + the file is then read into the ZipFile 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. + + + + 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. + + + + Instances of the ZipFile 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 ZipFile instance, or you + can synchronize multi-thread access to a single instance. + + + + By the way, since DotNetZip is so easy to use, don't you think you should + donate $5 or $10? + + + + + + Thrown if name refers to an existing file that is not a valid zip file. + + + + This example shows how to create a zipfile, and add a few files into it. + + 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); + } + + + + 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 + + + + The filename to use for the new zip archive. + + + + + Creates a new ZipFile instance, using the specified name for the + filename, and the specified Encoding. + + + + + See the documentation on the ZipFile + constructor that accepts a single string argument for basic + information on all the ZipFile constructors. + + + + 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 property on the ZipFile + instance after construction. + + + + Instances of the ZipFile 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 ZipFile instance, or you + can synchronize multi-thread access to a single instance. + + + + + + Thrown if name refers to an existing file that is not a valid zip file. + + + The filename to use for the new zip archive. + The Encoding is used as the default alternate + encoding for entries with filenames or comments that cannot be encoded + with the IBM437 code page. + + + + Create a zip file, without specifying a target filename or stream to save to. + + + + + See the documentation on the ZipFile + constructor that accepts a single string argument for basic + information on all the ZipFile constructors. + + + + After instantiating with this constructor and adding entries to the + archive, the application should call or + to save to a file or a + stream, respectively. The application can also set the + property and then call the no-argument method. (This + is the preferred approach for applications that use the library through + COM interop.) If you call the no-argument method + without having set the Name of the ZipFile, either through + the parameterized constructor or through the explicit property , the + Save() will throw, because there is no place to save the file. + + + Instances of the ZipFile class are not multi-thread safe. You may + have multiple threads that each use a distinct ZipFile instance, or + you can synchronize multi-thread access to a single instance. + + + + + This example creates a Zip archive called Backup.zip, containing all the files + in the directory DirectoryToZip. Files within subdirectories are not zipped up. + + 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"); + } + + + + 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 + + + + + + Create a zip file, specifying a text Encoding, but without specifying a + target filename or stream to save to. + + + + + See the documentation on the ZipFile + constructor that accepts a single string argument for basic + information on all the ZipFile constructors. + + + + + + The Encoding is used as the default alternate encoding for entries with + filenames or comments that cannot be encoded with the IBM437 code page. + + + + + Creates a new ZipFile instance, using the specified name for the + filename, and the specified status message writer. + + + + + See the documentation on the ZipFile + constructor that accepts a single string argument for basic + information on all the ZipFile constructors. + + + + 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 + TextWriter, for example, a StringWriter, and then display + the messages in a TextBox, or generate an audit log of ZipFile operations. + + + + To encrypt the data for the files added to the ZipFile instance, + set the Password property after creating the ZipFile instance. + + + + Instances of the ZipFile 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 ZipFile instance, or you + can synchronize multi-thread access to a single instance. + + + + + + Thrown if name refers to an existing file that is not a valid zip file. + + + + + 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(); + } + + + + 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 + + + + The filename to use for the new zip archive. + A TextWriter to use for writing + verbose status messages. + + + + Creates a new ZipFile instance, using the specified name for the + filename, the specified status message writer, and the specified Encoding. + + + + + This constructor works like the ZipFile + constructor that accepts a single string argument. See that + reference for detail on what this constructor does. + + + + This version of the constructor allows the caller to pass in a + TextWriter, and an Encoding. The TextWriter 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 + System.Console.Out to get messages on the Console. A graphical or + headless application may wish to capture the messages in a different + TextWriter, for example, a StringWriter, and then display + the messages in a TextBox, or generate an audit log of + ZipFile operations. + + + + 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 a equivalent to setting the property on the ZipFile + instance after construction. + + + + To encrypt the data for the files added to the ZipFile instance, + set the Password property after creating the ZipFile + instance. + + + + Instances of the ZipFile 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 ZipFile instance, or you + can synchronize multi-thread access to a single instance. + + + + + + Thrown if fileName refers to an existing file that is not a valid zip file. + + + The filename to use for the new zip archive. + A TextWriter to use for writing verbose + status messages. + + The Encoding is used as the default alternate encoding for entries with + filenames or comments that cannot be encoded with the IBM437 code page. + + + + + Initialize a ZipFile instance by reading in a zip file. + + + + + + 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 default (no argument) + constructor, then calling Initialize() to read the contents + of an on-disk zip archive into the ZipFile instance. + + + + .NET applications are encouraged to use the ZipFile.Read() methods + for better clarity. + + + + the name of the existing zip file to read in. + + + + This is an integer indexer into the Zip archive. + + + + + This property is read-only. + + + + Internally, the ZipEntry instances that belong to the + ZipFile are stored in a Dictionary. When you use this + indexer the first time, it creates a read-only + List<ZipEntry> from the Dictionary.Values Collection. + If at any time you modify the set of entries in the ZipFile, + 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. + + + + This means you cannot rename any ZipEntry from + inside an enumeration of the zip file. + + + + The index value. + + + + + + The ZipEntry within the Zip archive at the specified index. If the + entry does not exist in the archive, this indexer throws. + + + + + + This is a name-based indexer into the Zip archive. + + + + + This property is read-only. + + + + The property on the ZipFile + 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. + + + + Regardless of case-sensitivity, it is not always the case that + this[value].FileName == value. In other words, the FileName + property of the ZipEntry retrieved with this indexer, may or may + not be equal to the index value. + + + + 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, zip["dir1\\entry1.txt"].FileName == + "dir1/entry.txt". + + + + 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. + + + + + + This example extracts only the entries in a zip file that are .txt files. + + using (ZipFile zip = ZipFile.Read("PackedDocuments.zip")) + { + foreach (string s1 in zip.EntryFilenames) + { + if (s1.EndsWith(".txt")) + zip[s1].Extract("textfiles"); + } + } + + + 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 + + + + + + Thrown if the caller attempts to assign a non-null value to the indexer. + + + + 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 + property to change this behavior. The + pathname can use forward-slashes or backward slashes. + + + + The ZipEntry within the Zip archive, given by the specified + filename. If the named entry does not exist in the archive, this indexer + returns null (Nothing in VB). + + + + + + The list of filenames for the entries contained within the zip archive. + + + + 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. + + + + + + This example shows one way to test if a filename is already contained + within a zip archive. + + 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(); + } + + + 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 + + + + + The list of strings for the filenames contained within the Zip archive. + + + + + + Returns the readonly collection of entries in the Zip archive. + + + + + + If there are no entries in the current ZipFile, 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. + + + This is the implied enumerator on the ZipFile class. If you use a + ZipFile instance in a context that expects an enumerator, you will + get this collection. + + + + + + + Returns a readonly collection of entries in the Zip archive, sorted by FileName. + + + + If there are no entries in the current ZipFile, 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. + + + + + This example fills a Windows Forms ListView with the entries in a zip file. + + + 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); + } + } + + + + + + + + Returns the number of entries in the Zip archive. + + + + + Removes the given ZipEntry from the zip archive. + + + + + After calling RemoveEntry, the application must call Save to + make the changes permanent. + + + + + Thrown if the specified ZipEntry does not exist in the ZipFile. + + + + 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. + + 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"); + } + + + + 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 + + + + + The ZipEntry to remove from the zip. + + + + + + + + Removes the ZipEntry with the given filename from the zip archive. + + + + + After calling RemoveEntry, the application must call Save to + make the changes permanent. + + + + + + Thrown if the ZipFile is not updatable. + + + + Thrown if a ZipEntry with the specified filename does not exist in + the ZipFile. + + + + + This example shows one way to remove an entry with a given filename from + an existing zip archive. + + + 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(); + } + } + + + 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 + + + + + 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 + CaseSensitiveRetrieval property to change this behavior. The + pathname can use forward-slashes or backward slashes. + + + + + + Closes the read and write streams associated + to the ZipFile, if necessary. + + + + The Dispose() method is generally employed implicitly, via a using(..) {..} + statement. (Using...End Using 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. + + + + This example extracts an entry selected by name, from the Zip file to the + Console. + + 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. + + + + 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 + + + + + + Disposes any managed resources, if the flag is set, then marks the + instance disposed. This method is typically not called explicitly from + application code. + + + + Applications should call the no-arg Dispose method. + + + + indicates whether the method should dispose streams or not. + + + + + Default size of the buffer used for IO. + + + + + 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. + + + + + Depending on the particular event, different properties on the parameter are set. The following + table summarizes the available EventTypes and the conditions under + which this event handler is invoked with a + SaveProgressEventArgs with the given EventType. + + + + + value of EntryType + Meaning and conditions + + + + ZipProgressEventType.Saving_Started + Fired when ZipFile.Save() begins. + + + + + ZipProgressEventType.Saving_BeforeSaveEntry + + Fired within ZipFile.Save(), just before writing data for each + particular entry. + + + + + ZipProgressEventType.Saving_AfterSaveEntry + + Fired within ZipFile.Save(), just after having finished writing data + for each particular entry. + + + + + ZipProgressEventType.Saving_Completed + Fired when ZipFile.Save() has completed. + + + + + ZipProgressEventType.Saving_AfterSaveTempArchive + + 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. + + + + + ZipProgressEventType.Saving_BeforeRenameTempArchive + + 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. + + + + + ZipProgressEventType.Saving_AfterRenameTempArchive + + 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. + + + + + ZipProgressEventType.Saving_AfterCompileSelfExtractor + + Fired after a self-extracting archive has finished compiling. This + EventType is used only within SaveSelfExtractor(). + + + + + ZipProgressEventType.Saving_BytesRead + + 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. + + + + + + + + + This example uses an anonymous method to handle the + SaveProgress event, by updating a progress bar. + + + 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); + } + + + + + This example uses a named method as the + SaveProgress event handler, to update the user, in a + console-based application. + + + 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); + } + } + + + + + 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 + + + + + + This is a more complete example of using the SaveProgress + events in a Windows Forms application, with a + Thread object. + + + 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(); + } + + + + + + + + + + + An event handler invoked before, during, and after the reading of a zip archive. + + + + + Depending on the particular event being signaled, different properties on the + parameter are set. The following table + summarizes the available EventTypes and the conditions under which this + event handler is invoked with a ReadProgressEventArgs with the given EventType. + + + + + value of EntryType + Meaning and conditions + + + + ZipProgressEventType.Reading_Started + Fired just as ZipFile.Read() begins. Meaningful properties: ArchiveName. + + + + + ZipProgressEventType.Reading_Completed + Fired when ZipFile.Read() has completed. Meaningful properties: ArchiveName. + + + + + ZipProgressEventType.Reading_ArchiveBytesRead + Fired while reading, updates the number of bytes read for the entire archive. + Meaningful properties: ArchiveName, CurrentEntry, BytesTransferred, TotalBytesToTransfer. + + + + + ZipProgressEventType.Reading_BeforeReadEntry + Indicates an entry is about to be read from the archive. + Meaningful properties: ArchiveName, EntriesTotal. + + + + + ZipProgressEventType.Reading_AfterReadEntry + Indicates an entry has just been read from the archive. + Meaningful properties: ArchiveName, EntriesTotal, CurrentEntry. + + + + + + + + + + + + + An event handler invoked before, during, and after extraction of + entries in the zip archive. + + + + + Depending on the particular event, different properties on the parameter are set. The following + table summarizes the available EventTypes and the conditions under + which this event handler is invoked with a + ExtractProgressEventArgs with the given EventType. + + + + + value of EntryType + Meaning and conditions + + + + ZipProgressEventType.Extracting_BeforeExtractAll + + Set when ExtractAll() begins. The ArchiveName, Overwrite, and + ExtractLocation properties are meaningful. + + + + ZipProgressEventType.Extracting_AfterExtractAll + + Set when ExtractAll() has completed. The ArchiveName, Overwrite, + and ExtractLocation properties are meaningful. + + + + + ZipProgressEventType.Extracting_BeforeExtractEntry + + Set when an Extract() on an entry in the ZipFile has begun. + Properties that are meaningful: ArchiveName, EntriesTotal, + CurrentEntry, Overwrite, ExtractLocation, EntriesExtracted. + + + + + ZipProgressEventType.Extracting_AfterExtractEntry + + Set when an Extract() on an entry in the ZipFile has completed. + Properties that are meaningful: ArchiveName, EntriesTotal, + CurrentEntry, Overwrite, ExtractLocation, EntriesExtracted. + + + + + ZipProgressEventType.Extracting_EntryBytesWritten + + 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. + + + + + ZipProgressEventType.Extracting_ExtractEntryWouldOverwrite + + 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 ExtractExistingFileAction on the ZipFile or + ZipEntry is set to InvokeExtractProgressEvent. + + + + + + + + + + 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); + } + } + } + + + + 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 + + + + + + + + + + An event handler invoked before, during, and after Adding entries to a zip archive. + + + + Adding a large number of entries to a zip file can take a long + time. For example, when calling 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. + + + + + + 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); + } + } + + + + + + 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 + + + + + + + + + + + + An event that is raised when an error occurs during open or read of files + while saving a zip archive. + + + + + 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 Save(). + + + + Setting a handler implicitly sets to + ZipErrorAction.InvokeErrorEvent. + + + + The handler you add applies to all items that are + subsequently added to the ZipFile instance. If you set this + property after you have added items to the ZipFile, but before you + have called Save(), errors that occur while saving those items + will not cause the error handler to be invoked. + + + + 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. + + + + In the error handler method, you need to set the property on the + ZipErrorEventArgs.CurrentEntry. This communicates back to + DotNetZip what you would like to do with this particular error. Within + an error handler, if you set the ZipEntry.ZipErrorAction property + on the ZipEntry to ZipErrorAction.InvokeErrorEvent 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 ZipEntry.ZipErrorAction property on the + ZipEntry to ZipErrorAction.Throw.) If you set the + ZipErrorEventArgs.Cancel to true, the entire Save() will be + canceled. + + + + In the case that you use ZipErrorAction.Skip, 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. + + + + + + + This example shows how to use an event handler to handle + errors during save of the zip file. + + + 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); + } + } + + + + 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 + + + + + + + + + Extracts all of the items in the zip archive, to the specified path in the + filesystem. The path can be relative or fully-qualified. + + + + + This method will extract all entries in the ZipFile to the + specified path. + + + + 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 ZipFile 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 + overload that allows you to + specify an ExtractExistingFileAction parameter. + + + + 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 ZipEntry.Extract methods. + + + + This method will send verbose output messages to the , if it is set on the ZipFile + instance. + + + + You may wish to take advantage of the ExtractProgress event. + + + + 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 ZipEntry, then the extracted file will also get + these times. + + + + 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. + + + + To compensate, when extracting an archive with ExtractAll, + 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. + + + + This compensation is performed only within the context of an + ExtractAll. If you call ZipEntry.Extract on a directory + entry, the timestamps on directory in the filesystem will reflect the + times stored in the zip. If you then call ZipEntry.Extract on + a file entry, which is extracted into the directory, the timestamps on + the directory will be updated to the current time. + + + + + This example extracts all the entries in a zip archive file, to the + specified target directory. The extraction will overwrite any + existing files silently. + + + String TargetDirectory= "unpack"; + using(ZipFile zip= ZipFile.Read(ZipFileToExtract)) + { + zip.ExtractExistingFile= ExtractExistingFileAction.OverwriteSilently; + zip.ExtractAll(TargetDirectory); + } + + + + Dim TargetDirectory As String = "unpack" + Using zip As ZipFile = ZipFile.Read(ZipFileToExtract) + zip.ExtractExistingFile= ExtractExistingFileAction.OverwriteSilently + zip.ExtractAll(TargetDirectory) + End Using + + + + + + + + The path to which the contents of the zipfile will be extracted. + The path can be relative or fully-qualified. + + + + + + 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. + + + + + + This method will extract all entries in the ZipFile to the specified + path. For an extraction that would overwrite an existing file, the behavior + is dictated by , which overrides any + setting you may have made on individual ZipEntry instances. + + + + 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 or one of the similar methods. + + + + Calling this method is equivalent to setting the property and then calling . + + + + This method will send verbose output messages to the + , if it is set on the ZipFile instance. + + + + + This example extracts all the entries in a zip archive file, to the + specified target directory. It does not overwrite any existing files. + + String TargetDirectory= "c:\\unpack"; + using(ZipFile zip= ZipFile.Read(ZipFileToExtract)) + { + zip.ExtractAll(TargetDirectory, ExtractExistingFileAction.DontOverwrite); + } + + + + Dim TargetDirectory As String = "c:\unpack" + Using zip As ZipFile = ZipFile.Read(ZipFileToExtract) + zip.ExtractAll(TargetDirectory, ExtractExistingFileAction.DontOverwrite) + End Using + + + + + The path to which the contents of the zipfile will be extracted. + The path can be relative or fully-qualified. + + + + The action to take if extraction would overwrite an existing file. + + + + + + Reads a zip file archive and returns the instance. + + + + + The stream is read using the default System.Text.Encoding, which is the + IBM437 codepage. + + + + + Thrown if the ZipFile cannot be read. The implementation of this method + relies on System.IO.File.OpenRead, 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. + + + + The name of the zip archive to open. This can be a fully-qualified or relative + pathname. + + + . + + The instance read from the zip archive. + + + + + Reads a zip file archive from the named filesystem file using the + specified options. + + + + + This version of the Read() method allows the caller to pass + in a TextWriter an Encoding, via an instance of the + ReadOptions class. The ZipFile is read in using the + specified encoding for entries where UTF-8 encoding is not + explicitly specified. + + + + + + + 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. + + + + 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. + + + + 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); + } + } + + + + + 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 + + + + + + + + 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 StringWriter. + + + + 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 + + + + 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 + + + + + Thrown if the zipfile cannot be read. The implementation of + this method relies on System.IO.File.OpenRead, 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. + + + + The name of the zip archive to open. + This can be a fully-qualified or relative pathname. + + + + The set of options to use when reading the zip file. + + + The ZipFile instance read from the zip archive. + + + + + + + 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. + + + + The name of the zip archive to open. + This can be a fully-qualified or relative pathname. + + + + An event handler for Read operations. + + + + The System.IO.TextWriter to use for writing verbose status messages + during operations on 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 + TextWriter, such as a System.IO.StringWriter. + + + + The System.Text.Encoding 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. + + + The instance read from the zip archive. + + + + + Reads a zip archive from a stream. + + + + + + When reading from a file, it's probably easier to just use + ZipFile.Read(String, ReadOptions). 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. + + + + Using this overload, the stream is read using the default + System.Text.Encoding, which is the IBM437 + codepage. If you want to specify the encoding to use when + reading the zipfile content, see + ZipFile.Read(Stream, ReadOptions). This + + + + 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 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. + + + + + + + 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. + + + + using (ZipFile zip = ZipFile.Read(InputStream)) + { + zip.Extract("NameOfEntryInArchive.doc", OutputStream); + } + + + + Using zip as ZipFile = ZipFile.Read(InputStream) + zip.Extract("NameOfEntryInArchive.doc", OutputStream) + End Using + + + + the stream containing the zip data. + + The ZipFile instance read from the stream + + + + + Reads a zip file archive from the given stream using the + specified options. + + + + + + When reading from a file, it's probably easier to just use + ZipFile.Read(String, ReadOptions). 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. + + + + 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 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. + + + + the stream containing the zip data. + + + The set of options to use when reading the zip file. + + + + Thrown if the zip archive cannot be read. + + + The ZipFile instance read from the stream. + + + + + + + Reads a zip archive from a stream, using the specified text Encoding, the + specified TextWriter for status messages, + and the specified ReadProgress event handler. + + + + + 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 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. + + + + the stream containing the zip data. + + + The System.IO.TextWriter to which verbose status messages are written + during operations on the ZipFile. 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 null, no verbose messages + are written. + + + + 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 + property for more information. + + + + An event handler for Read operations. + + + an instance of ZipFile + + + + Checks the given file to see if it appears to be a valid zip file. + + + + + Calling this method is equivalent to calling with the testExtract parameter set to false. + + + + The file to check. + true if the file appears to be a zip file. + + + + Checks a file to see if it is a valid zip file. + + + + + This method opens the specified zip file, reads in the zip archive, + verifying the ZIP metadata as it reads. + + + + 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. + + + + If 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. + + + + If 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. + + + + + The zip file to check. + true if the caller wants to extract each entry. + true if the file contains a valid zip file. + + + + Checks a stream to see if it contains a valid zip archive. + + + + + 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 . + + + + 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. + + + + If testExtract 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. + + + + If 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 + ZipFile that has entries which are protected with a password, you will need + to do that manually. + + + + + + The stream to check. + true if the caller wants to extract each entry. + true if the stream contains a valid zip archive. + + + + Delete file with retry on UnauthorizedAccessException. + + + + + 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. + + + + the name of the file to be deleted + + + + Saves the Zip archive to a file, specified by the Name property of the + ZipFile. + + + + + The ZipFile instance is written to storage, typically a zip file + in a filesystem, only when the caller calls Save. 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. + + + + The property is specified either explicitly, + or implicitly using one of the parameterized ZipFile constructors. For + COM Automation clients, the Name property must be set explicitly, + because COM Automation clients cannot call parameterized constructors. + + + + When using a filesystem file for the Zip output, it is possible to call + Save multiple times on the ZipFile instance. With each + call the zip content is re-written to the same output file. + + + + Data for entries that have been added to the ZipFile instance is + written to the output when the Save method is called. This means + that the input streams for those entries must be available at the time + the application calls Save. If, for example, the application + adds entries with AddEntry using a dynamically-allocated + MemoryStream, the memory stream must not have been disposed + before the call to Save. See the 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. + + + + + + + + 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. + + + + Thrown if or 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. + + + + + + Save the file to a new zipfile, with the given name. + + + + + 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. + + + + An application can also save a zip archive in several places by calling this + method multiple times in succession, with different filenames. + + + + The ZipFile instance is written to storage, typically a zip file in a + filesystem, only when the caller calls Save. 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. + + + + + + Thrown if you specify a directory for the filename. + + + + The name of the zip archive to save to. Existing files will + be overwritten with great prejudice. + + + + This example shows how to create and Save a zip file. + + using (ZipFile zip = new ZipFile()) + { + zip.AddDirectory(@"c:\reports\January"); + zip.Save("January.zip"); + } + + + + Using zip As New ZipFile() + zip.AddDirectory("c:\reports\January") + zip.Save("January.zip") + End Using + + + + + + This example shows how to update a zip file. + + using (ZipFile zip = ZipFile.Read("ExistingArchive.zip")) + { + zip.AddFile("NewData.csv"); + zip.Save("UpdatedArchive.zip"); + } + + + + Using zip As ZipFile = ZipFile.Read("ExistingArchive.zip") + zip.AddFile("NewData.csv") + zip.Save("UpdatedArchive.zip") + End Using + + + + + + + Save the zip archive to the specified stream. + + + + + The ZipFile 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 Save. + + + + 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 + Save(Response.OutputStream) to write a zipfile directly to the + output stream, without creating a zip file on the disk on the ASP.NET + server. + + + + Be careful when saving a file to a non-seekable stream, including + Response.OutputStream. 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. + + + + + + + This example saves the zipfile content into a MemoryStream, and + then gets the array of bytes from that MemoryStream. + + + 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(); + } + + + + + + 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: + + + + using (var fs = new FileStream(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!! + } + } + + + + Better like this: + + + + using (var zip = Ionic.Zip.ZipFile.Read(filename)) + { + zip.AddEntry("Name1.txt", "this is the content"); + zip.Save(); // YES! + } + + + + + + The System.IO.Stream to write to. It must be + writable. If you created the ZipFile instance by calling + ZipFile.Read(), this stream must not be the same stream + you passed to ZipFile.Read(). + + + + + Adds to the ZipFile a set of files from the current working directory on + disk, that conform to the specified criteria. + + + + + This method selects files from the the current working directory matching + the specified criteria, and adds them to the ZipFile. + + + + 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." + + + + 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. + + + + 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. + + + + 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). + + + + The value for a size criterion is expressed in integer quantities of bytes, + kilobytes (use k or kb after the number), megabytes (m or mb), or gigabytes + (g or gb). + + + + The value for a name is a pattern to match against the filename, potentially + including wildcards. The pattern follows CMD.exe glob rules: * implies one + or more of any character, 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. + + + + 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 = '* *.*'" . + + + + The value for a type criterion is either F (implying a file) or D (implying + a directory). + + + + Some examples: + + + + + criteria + Files retrieved + + + + name != *.xls + any file with an extension that is not .xls + + + + + name = *.mp3 + any file with a .mp3 extension. + + + + + *.mp3 + (same as above) any file with a .mp3 extension. + + + + + attributes = A + all files whose attributes include the Archive bit. + + + + + attributes != H + all files whose attributes do not include the Hidden bit. + + + + + mtime > 2009-01-01 + all files with a last modified time after January 1st, 2009. + + + + + size > 2gb + all files whose uncompressed size is greater than 2gb. + + + + + type = D + all directories in the filesystem. + + + + + + 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. + + + + 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. + + + + 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. + + + + 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". + + + + 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. + + + + 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. + + + + + This example zips up all *.csv files in the current working directory. + + 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); + } + + + Using zip As ZipFile = New ZipFile() + zip.AddSelectedFiles("*.csv") + zip.Save(PathToZipArchive) + End Using + + + + The criteria for file selection + + + + Adds to the ZipFile a set of files from the disk that conform to the + specified criteria, optionally recursing into subdirectories. + + + + + This method selects files from the the current working directory matching + the specified criteria, and adds them to the ZipFile. If + recurseDirectories 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. + + + + 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 + directoryInArchive. + + + + For details on the syntax for the selectionCriteria parameter, see . + + + + + + + This example zips up all *.xml files in the current working directory, or any + subdirectory, that are larger than 1mb. + + + using (ZipFile zip = new ZipFile()) + { + // Use a compound expression in the selectionCriteria string. + zip.AddSelectedFiles("name = *.xml and size > 1024kb", true); + zip.Save(PathToZipArchive); + } + + + 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 + + + + The criteria for file selection + + + If true, the file selection will recurse into subdirectories. + + + + + Adds to the ZipFile a set of files from a specified directory in the + filesystem, that conform to the specified criteria. + + + + + 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. + + + + 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. + + + + For details on the syntax for the selectionCriteria parameter, see . + + + + + + + This example zips up all *.xml files larger than 1mb in the directory + given by "d:\rawdata". + + + 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); + } + + + + 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 + + + + The criteria for file selection + + + The name of the directory on the disk from which to select files. + + + + + Adds to the ZipFile a set of files from the specified directory on disk, + that conform to the specified criteria. + + + + + + This method selects files from the the specified disk directory matching + the specified selection criteria, and adds them to the ZipFile. If + recurseDirectories is true, files are also selected from + subdirectories. + + + + 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 + directoryInArchive. + + + + For details on the syntax for the selectionCriteria parameter, see . + + + + + + This example zips up all *.csv files in the "files" directory, or any + subdirectory, that have been saved since 2009 February 14th. + + + 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); + } + + + 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 + + + + + This example zips up all files in the current working + directory, and all its child directories, except those in + the excludethis subdirectory. + + Using Zip As ZipFile = New ZipFile(zipfile) + Zip.AddSelectedFfiles("name != 'excludethis\*.*'", datapath, True) + Zip.Save() + End Using + + + + The criteria for file selection + + + The filesystem path from which to select files. + + + + If true, the file selection will recurse into subdirectories. + + + + + 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. + + + + + 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 . + + + + + + + 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". + + + 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); + } + + + Using zip As ZipFile = New ZipFile + zip.AddSelectedFiles("name = *.psd and mtime > 2009-02-14", "photos", "content") + zip.Save(PathToZipArchive) + End Using + + + + + The criteria for selection of files to add to the ZipFile. + + + + The path to the directory in the filesystem from which to select files. + + + + Specifies a directory path to use to in place of the + directoryOnDisk. 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 directoryOnDisk, plus any subdirectory. Passing + the empty string ("") will insert the item at the root path within the + archive. + + + + + 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. + + + + 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 recurseDirectories + 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 directoryOnDisk. For details on the + syntax for the selectionCriteria parameter, see . + + + + + This example zips up all files that are NOT *.pst files, in the current + working directory and any subdirectories. + + + using (ZipFile zip = new ZipFile()) + { + zip.AddSelectedFiles("name != *.pst", SourceDirectory, "backup", true); + zip.Save(PathToZipArchive); + } + + + Using zip As ZipFile = New ZipFile + zip.AddSelectedFiles("name != *.pst", SourceDirectory, "backup", true) + zip.Save(PathToZipArchive) + End Using + + + + + The criteria for selection of files to add to the ZipFile. + + + + The path to the directory in the filesystem from which to select files. + + + + Specifies a directory path to use to in place of the + directoryOnDisk. 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 directoryOnDisk, plus any subdirectory. Passing + the empty string ("") will insert the item at the root path within the + archive. + + + + If true, the method also scans subdirectories for files matching the + criteria. + + + + + Updates the ZipFile with a selection of files from the disk that conform + to the specified criteria. + + + + This method selects files from the specified disk directory that match the + specified selection criteria, and Updates the ZipFile with those + files, using the specified directory path in the archive. If + recurseDirectories 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 + directoryOnDisk. For details on the syntax for the + selectionCriteria parameter, see . + + + + The criteria for selection of files to add to the ZipFile. + + + + The path to the directory in the filesystem from which to select files. + + + + Specifies a directory path to use to in place of the + directoryOnDisk. 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 directoryOnDisk, plus any + subdirectory. Passing the empty string ("") will insert the item at + the root path within the archive. + + + + If true, the method also scans subdirectories for files matching the criteria. + + + + + + + Retrieve entries from the zipfile by specified criteria. + + + + + 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. + + + + For details on the syntax for the selectionCriteria parameter, see . + + + + 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. + + + + + Thrown if selectionCriteria has an invalid syntax. + + + + This example selects all the PhotoShop files from within an archive, and extracts them + to the current working directory. + + using (ZipFile zip1 = ZipFile.Read(ZipFileName)) + { + var PhotoShopFiles = zip1.SelectEntries("*.psd"); + foreach (ZipEntry psd in PhotoShopFiles) + { + psd.Extract(); + } + } + + + 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 + + + the string that specifies which entries to select + a collection of ZipEntry objects that conform to the inclusion spec + + + + Retrieve entries from the zipfile by specified criteria. + + + + + 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. + + + + For details on the syntax for the selectionCriteria parameter, see . + + + + 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. + + + + + Thrown if selectionCriteria has an invalid syntax. + + + + + 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(); + } + } + + + 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 + + + the string that specifies which entries to select + + + the directory in the archive from which to select entries. If null, then + all directories in the archive are used. + + + a collection of ZipEntry objects that conform to the inclusion spec + + + + Remove entries from the zipfile by specified criteria. + + + + + 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. + + + + For details on the syntax for the selectionCriteria parameter, see . + + + + 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. + + + + + Thrown if selectionCriteria has an invalid syntax. + + + + This example removes all entries in a zip file that were modified prior to January 1st, 2008. + + 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(); + } + + + 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 + + + the string that specifies which entries to select + the number of entries removed + + + + Remove entries from the zipfile by specified criteria, and within the specified + path in the archive. + + + + + 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. + + + + For details on the syntax for the selectionCriteria parameter, see . + + + + 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. + + + + + Thrown if selectionCriteria has an invalid syntax. + + + + + 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(); + } + + + 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 + + + + the string that specifies which entries to select + + the directory in the archive from which to select entries. If null, then + all directories in the archive are used. + + the number of entries removed + + + + Selects and Extracts a set of Entries from the ZipFile. + + + + + The entries are extracted into the current working directory. + + + + If any of the files to be extracted already exist, then the action taken is as + specified in the property on the + corresponding ZipEntry instance. By default, the action taken in this case is to + throw an exception. + + + + For information on the syntax of the selectionCriteria string, + see . + + + + + This example shows how extract all XML files modified after 15 January 2009. + + using (ZipFile zip = ZipFile.Read(zipArchiveName)) + { + zip.ExtractSelectedEntries("name = *.xml and mtime > 2009-01-15"); + } + + + the selection criteria for entries to extract. + + + + + + Selects and Extracts a set of Entries from the ZipFile. + + + + + 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 + parameter. + + + + For information on the syntax of the string describing the entry selection criteria, + see . + + + + + This example shows how extract all XML files modified after 15 January 2009, + overwriting any existing files. + + using (ZipFile zip = ZipFile.Read(zipArchiveName)) + { + zip.ExtractSelectedEntries("name = *.xml and mtime > 2009-01-15", + ExtractExistingFileAction.OverwriteSilently); + } + + + + the selection criteria for entries to extract. + + + The action to take if extraction would overwrite an existing file. + + + + + Selects and Extracts a set of Entries from the ZipFile. + + + + + The entries are selected from the specified directory within the archive, and then + extracted into the current working directory. + + + + If any of the files to be extracted already exist, then the action taken is as + specified in the property on the + corresponding ZipEntry instance. By default, the action taken in this case is to + throw an exception. + + + + For information on the syntax of the string describing the entry selection criteria, + see . + + + + + This example shows how extract all XML files modified after 15 January 2009, + and writes them to the "unpack" directory. + + using (ZipFile zip = ZipFile.Read(zipArchiveName)) + { + zip.ExtractSelectedEntries("name = *.xml and mtime > 2009-01-15","unpack"); + } + + + + the selection criteria for entries to extract. + + + the directory in the archive from which to select entries. If null, then + all directories in the archive are used. + + + + + + + Selects and Extracts a set of Entries from the ZipFile. + + + + + The entries are extracted into the specified directory. If any of the files to be + extracted already exist, an exception will be thrown. + + + For information on the syntax of the string describing the entry selection criteria, + see . + + + + the selection criteria for entries to extract. + + + the directory in the archive from which to select entries. If null, then + all directories in the archive are used. + + + + the directory on the disk into which to extract. It will be created + if it does not exist. + + + + + Selects and Extracts a set of Entries from the ZipFile. + + + + + 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 + parameter. + + + + For information on the syntax of the string describing the entry selection criteria, + see . + + + + + 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. + + using (ZipFile zip = ZipFile.Read(zipArchiveName)) + { + zip.ExtractSelectedEntries("name = *.xml or size > 100000", + null, + "unpack", + ExtractExistingFileAction.DontOverwrite); + } + + + + the selection criteria for entries to extract. + + + The directory on the disk into which to extract. It will be created if it does not exist. + + + + The directory in the archive from which to select entries. If null, then + all directories in the archive are used. + + + + The action to take if extraction would overwrite an existing file. + + + + + + + + Static constructor for ZipFile + + + Code Pages 437 and 1252 for English are same + Code Page 1252 Windows Latin 1 (ANSI) - + Code Page 437 MS-DOS Latin US - + + + + + The default text encoding used in zip archives. It is numeric 437, also + known as IBM437. + + + + + + Generic IEnumerator support, for use of a ZipFile in an enumeration. + + + + You probably do not want to call GetEnumerator explicitly. Instead + it is implicitly called when you use a loop in C#, or a + For Each loop in VB.NET. + + + + 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. + + 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(); + } + } + + + + 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 + + + + A generic enumerator suitable for use within a foreach loop. + + + + An IEnumerator, for use of a ZipFile in a foreach construct. + + + + 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 For Each + statement. In Javascript, this is done with new Enumerator(zipfile). + + + + The IEnumerator over the entries in the ZipFile. + + + + + Options for using ZIP64 extensions when saving zip archives. + + + + + + Designed many years ago, the original zip + specification from PKWARE 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. + + + + Set this property to 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. + + + + Set this property to 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 Never. If you set this property to , 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. + + + + Set this property to 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 Response.OutputStream, or + Console.Out. 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 is the same + as using : it will always produce a zip + archive that uses ZIP64 extensions. + + + + + + + The default behavior, which is "Never". + (For COM clients, this is a 0 (zero).) + + + + + Do not use ZIP64 extensions when writing zip archives. + (For COM clients, this is a 0 (zero).) + + + + + 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.) + + + + + Always use ZIP64 extensions when writing zip archives, even when unnecessary. + (For COM clients, this is a 2.) + + + + + 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. + + + + + The default behavior. This is the same as "Never". + (For COM clients, this is a 0 (zero).) + + + + + Never use the associated option. + (For COM clients, this is a 0 (zero).) + + + + + Use the associated behavior "as necessary." + (For COM clients, this is a 1.) + + + + + Use the associated behavior Always, whether necessary or not. + (For COM clients, this is a 2.) + + + + + A class for collecting the various options that can be used when + Reading zip files for extraction or update. + + + + + 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. + + + + Pass an instance of the ReadOptions class into the + ZipFile.Read() method. + + + . + . + + + + + 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 Read(), the progress event is invoked as + necessary. + + + + + The System.IO.TextWriter to use for writing verbose status messages + during operations on 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 + TextWriter, such as a System.IO.StringWriter. + + + + + The System.Text.Encoding 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. + + + + + + + + Provides a stream metaphor for reading zip files. + + + + + This class provides an alternative programming model for reading zip files to + the one enabled by the class. Use this when reading zip + files, as an alternative to the class, when you would + like to use a Stream class to read the file. + + + + Some application designs require a readable stream for input. This stream can + be used to read a zip file, and extract entries. + + + + Both the ZipInputStream class and the ZipFile 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 GetNextEntry() and Read() methods on the + ZipInputStream 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 ZipEntry.Extract(). For this reason, the + ZipInputStream is generally recommended for when your application wants + to extract the data, without storing that data into a file. + + + + Aside from the obvious differences in programming model, there are some + differences in capability between the ZipFile class and the + ZipInputStream class. + + + + + ZipFile can be used to create or update zip files, or read and + extract zip files. ZipInputStream can be used only to read and + extract zip files. If you want to use a stream to create zip files, check + out the . + + + + ZipInputStream cannot read segmented or spanned + zip files. + + + + ZipInputStream will not read Zip file comments. + + + + When reading larger files, ZipInputStream will always underperform + ZipFile. This is because the ZipInputStream does a full scan on the + zip file, while the ZipFile class reads the central directory of the + zip file. + + + + + + + + + Create a ZipInputStream, wrapping it around an existing stream. + + + + + + While the class is generally easier + to use, this class provides an alternative to those + applications that want to read from a zipfile directly, + using a . + + + + Both the ZipInputStream class and the ZipFile 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 GetNextEntry() and Read() methods on the + ZipInputStream 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 ZipEntry.Extract(). For this reason, the + ZipInputStream is generally recommended for when your application wants + to extract the data, without storing that data into a file. + + + + Aside from the obvious differences in programming model, there are some + differences in capability between the ZipFile class and the + ZipInputStream class. + + + + + ZipFile can be used to create or update zip files, or read and extract + zip files. ZipInputStream can be used only to read and extract zip + files. If you want to use a stream to create zip files, check out the . + + + + ZipInputStream cannot read segmented or spanned + zip files. + + + + ZipInputStream will not read Zip file comments. + + + + When reading larger files, ZipInputStream will always underperform + ZipFile. This is because the ZipInputStream does a full scan on the + zip file, while the ZipFile class reads the central directory of the + zip file. + + + + + + + + The stream to read. It must be readable. This stream will be closed at + the time the ZipInputStream is closed. + + + + + This example shows how to read a zip file, and extract entries, using the + ZipInputStream class. + + + 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); + } + } + } + } + } + } + + + + 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 + + + + + + Create a ZipInputStream, given the name of an existing zip file. + + + + + + This constructor opens a FileStream for the given zipfile, and + wraps a ZipInputStream around that. See the documentation for the + constructor for full details. + + + + While the class is generally easier + to use, this class provides an alternative to those + applications that want to read from a zipfile directly, + using a . + + + + + + The name of the filesystem file to read. + + + + + This example shows how to read a zip file, and extract entries, using the + ZipInputStream class. + + + 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); + } + } + } + } + } + + + + 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 + + + + + + Create a ZipInputStream, explicitly specifying whether to + keep the underlying stream open. + + + + See the documentation for the ZipInputStream(Stream) + constructor for a discussion of the class, and an example of how to use the class. + + + + The stream to read from. It must be readable. + + + + true if the application would like the stream + to remain open after the ZipInputStream has been closed. + + + + Provides a string representation of the instance. + + + This can be useful for debugging purposes. + + + a string representation of the instance. + + + + 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. + + + + + In its + zip specification, 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. + + + + 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 ZipEntry in the zip + file. + + + + 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 Comment encoded in IBM437 and a FileName encoded with + the specified "provisional" codepage. + + + + 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. + + + + + + + Size of the work buffer to use for the ZLIB codec during decompression. + + + + 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. + + + + + Sets the password to be used on the ZipInputStream instance. + + + + + + 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 Read() for each entry. + + + + When reading an entry that is not encrypted, the value of this property is + ignored. + + + + + + + This example uses the ZipInputStream to read and extract entries from a + zip file, using a potentially different password for each entry. + + + 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); + } + } + } + } + } + + + + + + + Read the data from the stream into the buffer. + + + + + The data for the zipentry will be decrypted and uncompressed, as + necessary, before being copied into the buffer. + + + + You must set the property before calling + Read() the first time for an encrypted entry. To determine if an + entry is encrypted and requires a password, check the ZipEntry.Encryption property. + + + + The buffer to hold the data read from the stream. + the offset within the buffer to copy the first byte read. + the number of bytes to read. + the number of bytes read, after decryption and decompression. + + + + Read the next entry from the zip file. + + + + + Call this method just before calling , + to position the pointer in the zip file to the next entry that can be + read. Subsequent calls to Read(), will decrypt and decompress the + data in the zip file, until Read() returns 0. + + + + Each time you call GetNextEntry(), the pointer in the wrapped + stream is moved to the next entry in the zip file. If you call , and thus re-position the pointer within + the file, you will need to call GetNextEntry() again, to insure + that the file pointer is positioned at the beginning of a zip entry. + + + + This method returns the ZipEntry. Using a stream approach, you will + read the raw bytes for an entry in a zip file via calls to Read(). + Alternatively, you can extract an entry into a file, or a stream, by + calling , or one of its siblings. + + + + + + The ZipEntry read. Returns null (or Nothing in VB) if there are no more + entries in the zip file. + + + + + + Dispose the stream. + + + + + This method disposes the ZipInputStream. It may also close the + underlying stream, depending on which constructor was used. + + + + Typically the application will call Dispose() implicitly, via + a using statement in C#, or a Using statement in VB. + + + + 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. + + + + + true if the Dispose method was invoked by user code. + + + + + Always returns true. + + + + + Returns the value of CanSeek for the underlying (wrapped) stream. + + + + + Always returns false. + + + + + Returns the length of the underlying stream. + + + + + Gets or sets the position of the underlying stream. + + + Setting the position is equivalent to calling Seek(value, SeekOrigin.Begin). + + + + + This is a no-op. + + + + + This method always throws a NotSupportedException. + + ignored + ignored + ignored + + + + This method seeks in the underlying stream. + + + + + Call this method if you want to seek around within the zip file for random access. + + + + Applications can intermix calls to Seek() with calls to . After a call to Seek(), + GetNextEntry() will get the next ZipEntry 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. + + + + + the offset point to seek to + the reference point from which to seek + The new position + + + + This method always throws a NotSupportedException. + + ignored + + + + Provides a stream metaphor for generating zip files. + + + + + This class writes zip files, as defined in the specification + for zip files described by PKWare. The compression for this + implementation is provided by a managed-code version of Zlib, included with + DotNetZip in the classes in the Ionic.Zlib namespace. + + + + This class provides an alternative programming model to the one enabled by the + class. Use this when creating zip files, as an + alternative to the class, when you would like to use a + Stream type to write the zip file. + + + + Both the ZipOutputStream class and the ZipFile 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. + + + + The ZipFile class is generally easier to use than + ZipOutputStream and should be considered a higher-level interface. For + example, when creating a zip file via calls to the PutNextEntry() and + Write() methods on the ZipOutputStream class, the caller is + responsible for opening the file, reading the bytes from the file, writing + those bytes into the ZipOutputStream, setting the attributes on the + ZipEntry, 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 ZipFile.AddFile(). + For this reason, the ZipOutputStream 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 Stream + metaphor. + + + + Aside from the differences in programming model, there are other + differences in capability between the two classes. + + + + + ZipFile can be used to read and extract zip files, in addition to + creating zip files. ZipOutputStream cannot read zip files. If you want + to use a stream to read zip files, check out the class. + + + + ZipOutputStream does not support the creation of segmented or spanned + zip files. + + + + ZipOutputStream cannot produce a self-extracting archive. + + + + + Be aware that the ZipOutputStream class implements the interface. In order for + ZipOutputStream to produce a valid zip file, you use use it within + a using clause (Using in VB), or call the Dispose() method + explicitly. See the examples for how to employ a using clause. + + + + 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 property to zero, if you are compressing + large files through ZipOutputStream. This will cause parallel + compression to be used, always. + + + + + + Create a ZipOutputStream, wrapping an existing stream. + + + + + The class is generally easier to use when creating + zip files. The ZipOutputStream offers a different metaphor for creating a + zip file, based on the class. + + + + + + The stream to wrap. It must be writable. This stream will be closed at + the time the ZipOutputStream is closed. + + + + + This example shows how to create a zip file, using the + ZipOutputStream class. + + + 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); + } + } + } + } + } + } + + + + 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 + + + + + + Create a ZipOutputStream that writes to a filesystem file. + + + + The class is generally easier to use when creating + zip files. The ZipOutputStream offers a different metaphor for creating a + zip file, based on the class. + + + + The name of the zip file to create. + + + + + This example shows how to create a zip file, using the + ZipOutputStream class. + + + 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); + } + } + } + } + } + + + + 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 + + + + + + Create a ZipOutputStream. + + + + See the documentation for the ZipOutputStream(Stream) + constructor for an example. + + + + The stream to wrap. It must be writable. + + + + true if the application would like the stream + to remain open after the ZipOutputStream has been closed. + + + + Provides a string representation of the instance. + + + This can be useful for debugging purposes. + + + a string representation of the instance. + + + + Sets the password to be used on the ZipOutputStream instance. + + + + + + When writing a zip archive, this password is applied to the entries, not + to the zip archive itself. It applies to any ZipEntry subsequently + written to the ZipOutputStream. + + + + 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 + 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. + + + + If you set this property, and then add a set of entries to the archive via + calls to PutNextEntry, 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 null (Nothing in VB), and add another entry, the + first entry is encrypted and the second is not. + + + + When setting the Password, you may also want to explicitly set the 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 , then PKZip 2.0 ("Weak") encryption is used. + This encryption is relatively weak but is very interoperable. If + you set the password to a null value (Nothing in VB), + Encryption is reset to None. + + + + Special case: if you wrap a ZipOutputStream around a non-seekable stream, + and use encryption, and emit an entry of zero bytes, the Close() or + PutNextEntry() following the entry will throw an exception. + + + + + + + The Encryption to use for entries added to the ZipOutputStream. + + + + + The specified Encryption is applied to the entries subsequently + written to the ZipOutputStream instance. + + + + If you set this to something other than + EncryptionAlgorithm.None, you will also need to set the + to a non-null, non-empty value in + order to actually get encryption on the entry. + + + + + ZipOutputStream.Password + ZipEntry.Encryption + + + + Size of the work buffer to use for the ZLIB codec during compression. + + + + 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. + + + + + The compression strategy to use for all entries. + + + + 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 . + + + + + The type of timestamp attached to the ZipEntry. + + + + Set this in order to specify the kind of timestamp that should be emitted + into the zip file for each entry. + + + + + Sets the compression level to be used for entries subsequently added to + the zip archive. + + + + + Varying the compression level used on entries can affect the + size-vs-speed tradeoff when compression and decompressing data streams + or files. + + + + As with some other properties on the ZipOutputStream class, like , and , + setting this property on a ZipOutputStream + instance will cause the specified CompressionLevel to be used on all + items that are subsequently added to the + ZipOutputStream instance. + + + + 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 BestCompression 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. + + + + + + The compression method used on each entry added to the ZipOutputStream. + + + + + A comment attached to the zip archive. + + + + + + The application sets this property to specify a comment to be embedded + into the generated zip archive. + + + + According to PKWARE's + zip specification, the comment is not encrypted, even if there is a + password set on the zip file. + + + + 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 is + Never, it uses the default encoding (IBM437). (b) if is Always, it always uses the + alternate encoding (). (c) if is AsNecessary, 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 ZipFile.Save(). + + + + + + + Specify whether to use ZIP64 extensions when saving a zip archive. + + + + + The default value for the property is . is + safest, in the sense that you will not get an Exception if a + pre-ZIP64 limit is exceeded. + + + + You must set this property before calling Write(). + + + + + + + Indicates whether ZIP64 extensions were used when saving the zip archive. + + + + The value is defined only after the ZipOutputStream has been closed. + + + + + Whether the ZipOutputStream should use case-insensitive comparisons when + checking for uniqueness of zip entries. + + + + + 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 with a name that duplicates one + already used within the archive, the library will throw an Exception. + + + This property allows the application to specify whether the + ZipOutputStream instance considers ordinal case when checking for + uniqueness of zip entries. + + + + + + Indicates whether to encode entry filenames and entry comments using + Unicode (UTF-8). + + + + + The + PKWare zip specification 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. + + + + 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. + + + + 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. + + + + 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. + + + + 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. + + + + 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. + + + + If you do not set this flag, it will remain false. If this flag is false, + the ZipOutputStream 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". + + + + 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 ZipOutputStream, 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. + + + + 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. + + + + Rather than specify the encoding in a binary fashion using this flag, an + application can specify an arbitrary encoding via the 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. + + + + + + + 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. + + + + + In its + zip specification, 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. + + + + 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 and for each ZipEntry 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 + Comment encoded in IBM437 and a FileName encoded with the + specified "provisional" codepage. + + + + Be aware that a zip file created after you've explicitly set the + 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. + + + + When creating a zip archive using this library, it is possible to change + the value of ProvisionalAlternateEncoding between each entry you + add, and between adding entries and the call to Close(). Don't do + this. It will likely result in a zipfile that is not readable. For best + interoperability, either leave ProvisionalAlternateEncoding + alone, or specify it only once, before adding any entries to the + ZipOutputStream instance. There is one exception to this + recommendation, described later. + + + + 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. + + + + 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 ProvisionalAlternateEncoding to your desired + region-specific code page, once before adding any entries, and then set + the property and reset + ProvisionalAlternateEncoding to IBM437 before calling Close(). + + + + + + A Text Encoding to use when encoding the filenames and comments for + all the ZipEntry items, during a ZipFile.Save() operation. + + + + Whether the encoding specified here is used during the save depends + on . + + + + + + 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. + + + + + The default text encoding used in zip archives. It is numeric 437, also + known as IBM437. + + + + + + The size threshold for an entry, above which a parallel deflate is used. + + + + + + DotNetZip will use multiple threads to compress any ZipEntry, when + the CompressionMethod 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". + + + + 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. + + + + 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. + + + + 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%. + + + + 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 . You may have to perform + some tests to determine the best approach for your situation. + + + + The default value for this property is -1, which means parallel + compression will not be performed unless you set it to zero. + + + + + + + The maximum number of buffer pairs to use when performing + parallel compression. + + + + + 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 + ThreadPool.QueueUserWorkItem() to compress those + buffers in a background threadpool thread. After a buffer + is compressed, it is re-ordered and written to the output + stream. + + + + 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. + + + + 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 (). 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. + + + + 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. + + + + 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. + + + + 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. + + + + The application can set this value at any time, but it is + effective only if set before calling + ZipOutputStream.Write() for the first time. + + + + + + + + + Returns true if an entry by the given name has already been written + to the ZipOutputStream. + + + + The name of the entry to scan for. + + + + true if an entry by the given name has already been written. + + + + + Write the data from the buffer to the stream. + + + + 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 + and the properties. + + + The buffer holding data to write to the stream. + the offset within that data array to find the first byte to write. + the number of bytes to write. + + + + Specify the name of the next entry that will be written to the zip file. + + + + + Call this method just before calling , to + specify the name of the entry that the next set of bytes written to + the ZipOutputStream belongs to. All subsequent calls to Write, + until the next call to PutNextEntry, + will be inserted into the named entry in the zip file. + + + + If the used in PutNextEntry() ends in + a slash, then the entry added is marked as a directory. Because directory + entries do not contain data, a call to Write(), before an + intervening additional call to PutNextEntry(), will throw an + exception. + + + + If you don't call Write() between two calls to + PutNextEntry(), the first entry is inserted into the zip file as a + file of zero size. This may be what you want. + + + + Because PutNextEntry() closes out the prior entry, if any, this + method may throw if there is a problem with the prior entry. + + + + This method returns the ZipEntry. You can modify public properties + on the ZipEntry, such as , , and so on, until the first call to + ZipOutputStream.Write(), or until the next call to + PutNextEntry(). If you modify the ZipEntry after + having called Write(), you may get a runtime exception, or you may + silently get an invalid zip archive. + + + + + + + This example shows how to create a zip file, using the + ZipOutputStream class. + + + 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); + } + } + } + + + + + The name of the entry to be added, including any path to be used + within the zip file. + + + + The ZipEntry created. + + + + + + Dispose the stream + + + + + 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. + + + + Typically the application will call Dispose() implicitly, via a using + statement in C#, or a Using statement in VB. + + + + + set this to true, always. + + + + Always returns false. + + + + + Always returns false. + + + + + Always returns true. + + + + + Always returns a NotSupportedException. + + + + + Setting this property always returns a NotSupportedException. Getting it + returns the value of the Position on the underlying stream. + + + + + This is a no-op. + + + + + This method always throws a NotSupportedException. + + ignored + ignored + ignored + nothing + + + + This method always throws a NotSupportedException. + + ignored + ignored + nothing + + + + This method always throws a NotSupportedException. + + ignored + + + + 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. + + + + 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. + + + Caller must Close/Dispose the stream object returned by + this method. + + + + + + Name of the filesystem file corresponding to the current segment. + + + + 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. + + + + + + Read from the stream + + the buffer to read + the offset at which to start + the number of bytes to read + the number of bytes actually read + + + + Write to the stream. + + the buffer from which to write + the offset at which to start writing + the number of bytes to write + + + + Enumerates the options for a logical conjunction. This enum is intended for use + internally by the FileSelector class. + + + + + 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. + + + + + + The FileSelector class is used internally by the ZipFile class for selecting + files for inclusion into the ZipFile, when the method, or one of + its overloads, is called. It's also used for the methods. Typically, an + application that creates or manipulates Zip archives will not directly + interact with the FileSelector class. + + + + 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. + + + + Consult the documentation for + for more information on specifying the selection criteria. + + + + + + + Constructor that allows the caller to specify file selection criteria. + + + + + This constructor allows the caller to specify a set of criteria for + selection of files. + + + + See for a description of + the syntax of the selectionCriteria string. + + + + By default the FileSelector will traverse NTFS Reparse Points. To + change this, use FileSelector(String, bool). + + + + The criteria for file selection. + + + + Constructor that allows the caller to specify file selection criteria. + + + + + This constructor allows the caller to specify a set of criteria for + selection of files. + + + + See for a description of + the syntax of the selectionCriteria string. + + + + The criteria for file selection. + + whether to traverse NTFS reparse points (junctions). + + + + + The string specifying which files to include when retrieving. + + + + + 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." + + + + 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. + + + + 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. + + + + 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). + + + + The value for a size criterion is expressed in integer quantities of + bytes, kilobytes (use k or kb after the number), megabytes (m or mb), + or gigabytes (g or gb). + + + + The value for a name is a pattern to match against the filename, + potentially including wildcards. The pattern follows CMD.exe glob + rules: * implies one or more of any character, 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. + + + + 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 = '* *.*'" . + + + + The value for a type criterion is either F (implying a file) or D + (implying a directory). + + + + Some examples: + + + + + criteria + Files retrieved + + + + name != *.xls + any file with an extension that is not .xls + + + + + name = *.mp3 + any file with a .mp3 extension. + + + + + *.mp3 + (same as above) any file with a .mp3 extension. + + + + + attributes = A + all files whose attributes include the Archive bit. + + + + + attributes != H + all files whose attributes do not include the Hidden bit. + + + + + mtime > 2009-01-01 + all files with a last modified time after January 1st, 2009. + + + + + ctime > 2009/01/01-03:00:00 + all files with a created time after 3am (local time), + on January 1st, 2009. + + + + + size > 2gb + all files whose uncompressed size is greater than 2gb. + + + + + type = D + all directories in the filesystem. + + + + + + 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. + + + + 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. + + + + 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. + + + + 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. + + + + 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. + + + + + + Thrown in the setter if the value has an invalid syntax. + + + + + Indicates whether searches will traverse NTFS reparse points, like Junctions. + + + + + Returns a string representation of the FileSelector object. + + The string representation of the boolean logic statement of the file + selection criteria for this instance. + + + + Returns the names of the files in the specified directory + that fit the selection criteria specified in the FileSelector. + + + + This is equivalent to calling + with recurseDirectories = false. + + + + The name of the directory over which to apply the FileSelector + criteria. + + + + A collection of strings containing fully-qualified pathnames of files + that match the criteria specified in the FileSelector instance. + + + + + Returns the names of the files in the specified directory that fit the + selection criteria specified in the FileSelector, optionally recursing + through subdirectories. + + + + 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. + + + + The name of the directory over which to apply the FileSelector + criteria. + + + + Whether to recurse through subdirectories when applying the file + selection criteria. + + + + A collection of strings containing fully-qualified pathnames of files + that match the criteria specified in the FileSelector instance. + + + + + Retrieve the ZipEntry items in the ZipFile that conform to the specified criteria. + + + + + This method applies the criteria set in the FileSelector instance (as described in + the ) to the specified ZipFile. Using this + method, for example, you can retrieve all entries from the given ZipFile that + have filenames ending in .txt. + + + + Normally, applications would not call this method directly. This method is used + by the ZipFile class. + + + + Using the appropriate SelectionCriteria, you can retrieve entries based on size, + time, and attributes. See for a + description of the syntax of the SelectionCriteria string. + + + + + The ZipFile from which to retrieve entries. + + a collection of ZipEntry objects that conform to the criteria. + + + + Retrieve the ZipEntry items in the ZipFile that conform to the specified criteria. + + + + + This method applies the criteria set in the FileSelector instance (as described in + the ) to the specified ZipFile. Using this + method, for example, you can retrieve all entries from the given ZipFile that + have filenames ending in .txt. + + + + Normally, applications would not call this method directly. This method is used + by the ZipFile class. + + + + This overload allows the selection of ZipEntry instances from the ZipFile to be restricted + to entries contained within a particular directory in the ZipFile. + + + + Using the appropriate SelectionCriteria, you can retrieve entries based on size, + time, and attributes. See for a + description of the syntax of the SelectionCriteria string. + + + + + The ZipFile from which to retrieve entries. + + + the directory in the archive from which to select entries. If null, then + all directories in the archive are used. + + + a collection of ZipEntry objects that conform to the criteria. + + + + Summary description for EnumUtil. + + + + + Returns the value of the DescriptionAttribute if the specified Enum + value has one. If not, returns the ToString() representation of the + Enum value. + + The Enum to get the description for + + + + + 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. + + The System.Type of the enumeration. + + A string containing the name or value to convert. + + + + + + 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. + + The System.Type of the enumeration. + + A string containing the name or value to convert. + + + Whether the operation is case-sensitive or not. + + + +