From ed9873326d1e52348e52e0032d5894f4ff7306de Mon Sep 17 00:00:00 2001 From: carlossanlop Date: Thu, 25 Feb 2021 15:48:27 -0800 Subject: [PATCH 01/18] DeflateStream --- .../Compression/DeflateZLib/DeflateStream.cs | 267 +++++++++++++++++- 1 file changed, 265 insertions(+), 2 deletions(-) diff --git a/src/libraries/System.IO.Compression/src/System/IO/Compression/DeflateZLib/DeflateStream.cs b/src/libraries/System.IO.Compression/src/System/IO/Compression/DeflateZLib/DeflateStream.cs index c8cd4071f5bc00..0e07b82410c90c 100644 --- a/src/libraries/System.IO.Compression/src/System/IO/Compression/DeflateZLib/DeflateStream.cs +++ b/src/libraries/System.IO.Compression/src/System/IO/Compression/DeflateZLib/DeflateStream.cs @@ -10,6 +10,16 @@ namespace System.IO.Compression { + /// Provides methods and properties for compressing and decompressing streams by using the Deflate algorithm. + /// This class represents the Deflate algorithm, which is an industry-standard algorithm for lossless file compression and decompression. Starting with the .NET Framework 4.5, the class uses the zlib library. As a result, it provides a better compression algorithm and, in most cases, a smaller compressed file than it provides in earlier versions of the .NET Framework. + /// This class does not inherently provide functionality for adding files to or extracting files from zip archives. To work with zip archives, use the and the classes. + /// The class uses the same compression algorithm as the gzip data format used by the class. + /// The compression functionality in and is exposed as a stream. Data is read on a byte-by-byte basis, so it is not possible to perform multiple passes to determine the best method for compressing entire files or large blocks of data. The and classes are best used on uncompressed sources of data. If the source data is already compressed, using these classes may actually increase the size of the stream. + /// The following example shows how to use the class to compress and decompress a directory of files. + /// public partial class DeflateStream : Stream { private const int DefaultBufferSize = 8192; @@ -27,20 +37,80 @@ internal DeflateStream(Stream stream, CompressionMode mode, long uncompressedSiz { } + /// Initializes a new instance of the class by using the specified stream and compression mode. + /// The stream to compress or decompress. + /// One of the enumeration values that indicates whether to compress or decompress the stream. + /// By default, owns the underlying stream, so closing the stream also closes the underlying stream. Note that the state of the underlying stream can affect the usability of the stream. Also, no explicit checks are performed, so no additional exceptions are thrown when the new instance is created. + /// If an instance of the class is created with the parameter equal to `Compress`, header information is inserted immediately. If no further action occurs, the stream appears as a valid, empty, compressed file. + /// Using the class to compress a file larger than 4 GB raises an exception. + /// By default, the compression level is set to when the compression mode is . + /// The following example shows how to use the class to compress and decompress a file. + /// + /// is . + /// is not a valid value. + /// -or- + /// is and is . + /// -or- + /// is and is . public DeflateStream(Stream stream, CompressionMode mode) : this(stream, mode, leaveOpen: false) { } + /// Initializes a new instance of the class by using the specified stream and compression mode, and optionally leaves the stream open. + /// The stream to compress or decompress. + /// One of the enumeration values that indicates whether to compress or decompress the stream. + /// to leave the stream open after disposing the object; otherwise, . + /// By default, owns the underlying stream, so closing the stream also closes the underlying stream. Note that the state of the underlying stream can affect the usability of the stream. Also, no explicit checks are performed, so no additional exceptions are thrown when the new instance is created. + /// If an instance of the class is created with the parameter equal to `Compress`, header information is inserted immediately. If no further action occurs, the stream appears as a valid, empty, compressed file. + /// Using the class to compress a file larger than 4 GB raises an exception. + /// By default, the compression level is set to when the compression mode is . + /// The following code example shows how to use the class to compress and decompress a file. + /// + /// is . + /// is not a valid value. + /// -or- + /// is and is . + /// -or- + /// is and is . public DeflateStream(Stream stream, CompressionMode mode, bool leaveOpen) : this(stream, mode, leaveOpen, ZLibNative.Deflate_DefaultWindowBits) { } - // Implies mode = Compress + /// Initializes a new instance of the class by using the specified stream and compression level. + /// The stream to compress. + /// One of the enumeration values that indicates whether to emphasize speed or compression efficiency when compressing the stream. + /// You use this constructor when you want to specify whether compression efficiency or speed is more important for an instance of the class. + /// This constructor overload uses the compression mode . To set the compression mode to another value, use the or overload. + /// The following example shows how to set the compression level when creating a object. + /// + /// is . + /// The stream does not support write operations such as compression. (The property on the stream object is .) public DeflateStream(Stream stream, CompressionLevel compressionLevel) : this(stream, compressionLevel, leaveOpen: false) { } - // Implies mode = Compress + /// Initializes a new instance of the class by using the specified stream and compression level, and optionally leaves the stream open. + /// The stream to compress. + /// One of the enumeration values that indicates whether to emphasize speed or compression efficiency when compressing the stream. + /// to leave the stream object open after disposing the object; otherwise, . + /// You use this constructor when you want to specify whether compression efficiency or speed is more important for an instance of the class, and whether to leave the stream object open after disposing the object. + /// This constructor overload uses the compression mode . To set the compression mode to another value, use the or overload. + /// The following example shows how to set the compression level when creating a object and how to leave the stream open. + /// + /// is . + /// The stream does not support write operations such as compression. (The property on the stream object is .) public DeflateStream(Stream stream, CompressionLevel compressionLevel, bool leaveOpen) : this(stream, compressionLevel, leaveOpen, ZLibNative.Deflate_DefaultWindowBits) { } @@ -118,8 +188,13 @@ private void EnsureBufferInitialized() } } + /// Gets a reference to the underlying stream. + /// A stream object that represents the underlying stream. + /// The underlying stream is closed. public Stream BaseStream => _stream; + /// Gets a value indicating whether the stream supports reading while decompressing a file. + /// if the value is , and the underlying stream is opened and supports reading; otherwise, . public override bool CanRead { get @@ -133,6 +208,8 @@ public override bool CanRead } } + /// Gets a value indicating whether the stream supports writing. + /// if the value is , and the underlying stream supports writing and is not closed; otherwise, . public override bool CanWrite { get @@ -146,19 +223,30 @@ public override bool CanWrite } } + /// Gets a value indicating whether the stream supports seeking. + /// in all cases. public override bool CanSeek => false; + /// This property is not supported and always throws a . + /// A long value. + /// This property is not supported on this stream. public override long Length { get { throw new NotSupportedException(SR.NotSupported); } } + /// This property is not supported and always throws a . + /// A long value. + /// This property is not supported on this stream. public override long Position { get { throw new NotSupportedException(SR.NotSupported); } set { throw new NotSupportedException(SR.NotSupported); } } + /// The current implementation of this method has no functionality. + /// Flushes the internal buffer if the compression mode is set to . + /// The stream is closed. public override void Flush() { EnsureNotDisposed(); @@ -166,6 +254,10 @@ public override void Flush() FlushBuffers(); } + /// Asynchronously clears all buffers for this Deflate stream, causes any buffered data to be written to the underlying device, and monitors cancellation requests. + /// The token to monitor for cancellation requests. The default value is . + /// A task that represents the asynchronous flush operation. + /// If the operation is canceled before it completes, the returned task contains the value for the property. public override Task FlushAsync(CancellationToken cancellationToken) { EnsureNoActiveAsyncOperation(); @@ -211,16 +303,27 @@ async Task Core(CancellationToken cancellationToken) } } + /// This operation is not supported and always throws a . + /// The location in the stream. + /// One of the values. + /// A long value. + /// This property is not supported on this stream. public override long Seek(long offset, SeekOrigin origin) { throw new NotSupportedException(SR.NotSupported); } + /// This operation is not supported and always throws a . + /// The length of the stream. + /// This property is not supported on this stream. public override void SetLength(long value) { throw new NotSupportedException(SR.NotSupported); } + /// Reads a byte from the Deflate stream and advances the position within the stream by one byte, or returns -1 if at the end of the Deflate stream. + /// The unsigned byte cast to an , or -1 if at the end of the stream. + /// Use the property to determine whether the current instance supports reading. public override int ReadByte() { EnsureDecompressionMode(); @@ -233,12 +336,38 @@ public override int ReadByte() return _inflater.Inflate(out b) ? b : base.ReadByte(); } + /// Reads a number of decompressed bytes into the specified byte array. + /// The array to store decompressed bytes. + /// The byte offset in at which the read bytes will be placed. + /// The maximum number of decompressed bytes to read. + /// The number of bytes that were read into the byte array. + /// + /// The following example shows how to compress and decompress bytes by using the and methods. + /// + /// is . + /// The value was when the object was created. + /// -or- + /// The underlying stream does not support reading. + /// or is less than zero. + /// -or- + /// length minus the index starting point is less than . + /// The data is in an invalid format. + /// The stream is closed. public override int Read(byte[] buffer, int offset, int count) { ValidateBufferArguments(buffer, offset, count); return ReadCore(new Span(buffer, offset, count)); } + /// Reads a sequence of bytes from the current Deflate stream into a byte span and advances the position within the Deflate stream by the number of bytes read. + /// A region of memory. When this method returns, the contents of this region are replaced by the bytes read from the current source. + /// The total number of bytes read into the buffer. This can be less than the number of bytes allocated in the buffer if that many bytes are not currently available, or zero (0) if the end of the stream has been reached. + /// Use the property to determine whether the current instance supports reading. Use the method to read asynchronously from the current stream. + /// This method read a maximum of `buffer.Length` bytes from the current stream and store them in . The current position within the Deflate stream is advanced by the number of bytes read; however, if an exception occurs, the current position within the Deflate stream remains unchanged. This method will block until at least one byte of data can be read, in the event that no data is available. `Read` returns 0 only when there is no more data in the stream and no more is expected (such as a closed socket or end of file). The method is free to return fewer bytes than requested even if the end of the stream has not been reached. + /// Use for reading primitive data types. public override int Read(Span buffer) { if (GetType() != typeof(DeflateStream)) @@ -336,9 +465,43 @@ private static void ThrowCannotWriteToDeflateStreamException() throw new InvalidOperationException(SR.CannotWriteToDeflateStream); } + /// Begins an asynchronous read operation. (Consider using the method instead.) + /// The byte array to read the data into. + /// The byte array to read the data into. + /// The byte offset in at which to begin reading data from the stream. + /// The maximum number of bytes to read. + /// An optional asynchronous callback, to be called when the read operation is complete. + /// An optional asynchronous callback, to be called when the read operation is complete. + /// A user-provided object that distinguishes this particular asynchronous read request from other requests. + /// A user-provided object that distinguishes this particular asynchronous read request from other requests. + /// An object that represents the asynchronous read operation, which could still be pending. + /// Starting with the .NET Framework 4.5, you can perform asynchronous read operations by using the method. The method is still available in the .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). + /// Pass the return value to the method of the stream to determine how many bytes were read and to release operating system resources used for reading. You can do this either by using the same code that called or in a callback passed to . + /// The current position in the stream is updated when the asynchronous read or write operation is issued, not when the I/O operation completes. + /// Multiple simultaneous asynchronous requests render the request completion order uncertain. + /// Use the property to determine whether the current object supports reading. + /// If a stream is closed or you pass an invalid argument, exceptions are thrown immediately from . Errors that occur during an asynchronous read request, such as a disk failure during the I/O request, occur on the thread pool thread and throw exceptions when calling . + /// The method tried to read asynchronously past the end of the stream, or a disk error occurred. + /// One or more of the arguments is invalid. + /// Methods were called after the stream was closed. + /// The current implementation does not support the read operation. + /// This call cannot be completed. public override IAsyncResult BeginRead(byte[] buffer, int offset, int count, AsyncCallback? asyncCallback, object? asyncState) => TaskToApm.Begin(ReadAsync(buffer, offset, count, CancellationToken.None), asyncCallback, asyncState); + /// Waits for the pending asynchronous read to complete. (Consider using the method instead.) + /// The reference to the pending asynchronous request to finish. + /// The reference to the pending asynchronous request to finish. + /// The number of bytes read from the stream, between 0 (zero) and the number of bytes you requested. returns 0 only at the end of the stream; otherwise, it blocks until at least one byte is available. + /// Starting with the .NET Framework 4.5, you can perform asynchronous read operations by using the method. The method is still available in the .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). + /// Call this method to determine how many bytes were read from the stream. This method can be called once to return the amount of bytes read between calls to and . + /// This method blocks until the I/O operation has completed. + /// is . + /// did not originate from a method on the current stream. + /// An exception was thrown during a call to . + /// The end call is invalid because asynchronous read operations for this stream are not yet complete. + /// -or- + /// The stream is . public override int EndRead(IAsyncResult asyncResult) { EnsureDecompressionMode(); @@ -346,12 +509,28 @@ public override int EndRead(IAsyncResult asyncResult) return TaskToApm.End(asyncResult); } + /// Asynchronously reads a sequence of bytes from the current Deflate stream, writes them to a byte array, advances the position within the Deflate stream by the number of bytes read, and monitors cancellation requests. + /// The buffer to write the data into. + /// The byte offset in at which to begin writing data from the Deflate stream. + /// The maximum number of bytes to read. + /// The token to monitor for cancellation requests. The default value is . + /// A task that represents the asynchronous read operation, which wraps the total number of bytes read into the . The result value can be less than the number of bytes requested if the number of bytes currently available is less than the requested number, or it can be 0 (zero) if the end of the Deflate stream has been reached. + /// The `ReadAsync` method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the and keywords in Visual Basic and C#. + /// Use the property to determine whether the current instance supports reading. + /// If the operation is canceled before it completes, the returned task contains the value for the property. public override Task ReadAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken) { ValidateBufferArguments(buffer, offset, count); return ReadAsyncMemory(new Memory(buffer, offset, count), cancellationToken).AsTask(); } + /// Asynchronously reads a sequence of bytes from the current Deflate stream, writes them to a byte memory range, advances the position within the Deflate stream by the number of bytes read, and monitors cancellation requests. + /// The region of memory to write the data into. + /// The token to monitor for cancellation requests. The default value is . + /// A task that represents the asynchronous read operation, which wraps the total number of bytes read into the buffer. The result value can be less than the number of bytes allocated in the buffer if that many bytes are not currently available, or it can be 0 (zero) if the end of the Deflate stream has been reached. + /// The `ReadAsync` method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the and keywords in Visual Basic and C#. + /// Use the property to determine whether the current instance supports reading. + /// If the operation is canceled before it completes, the returned task contains the value for the property. public override ValueTask ReadAsync(Memory buffer, CancellationToken cancellationToken = default(CancellationToken)) { if (GetType() != typeof(DeflateStream)) @@ -436,12 +615,26 @@ async ValueTask Core(Memory buffer, CancellationToken cancellationTok } } + /// Writes compressed bytes to the underlying stream from the specified byte array. + /// The buffer that contains the data to compress. + /// The byte offset in from which the bytes will be read. + /// The maximum number of bytes to write. + /// + /// The following example shows how to compress and decompress bytes by using the and methods. + /// public override void Write(byte[] buffer, int offset, int count) { ValidateBufferArguments(buffer, offset, count); WriteCore(new ReadOnlySpan(buffer, offset, count)); } + /// Writes a sequence of bytes to the current Deflate stream and advances the current position within this Deflate stream by the number of bytes written. + /// A region of memory. This method copies the contents of this region to the current Deflate stream. + /// Use the property to determine whether the current instance supports writing. Use the method to write asynchronously to the current stream. + /// If the write operation is successful, the position within the Deflate stream advances by the number of bytes written. If an exception occurs, the position within the Deflate stream remains unchanged. public override void Write(ReadOnlySpan buffer) { if (GetType() != typeof(DeflateStream)) @@ -616,6 +809,10 @@ private async ValueTask PurgeBuffersAsync() } } + /// Releases the unmanaged resources used by the and optionally releases the managed resources. + /// to release both managed and unmanaged resources; to release only unmanaged resources. + /// This method is called by the public method and the method. invokes the protected method with the parameter set to . invokes with set to . + /// When the parameter is , this method releases all resources held by any managed objects that this references. This method invokes the method of each referenced object. protected override void Dispose(bool disposing) { try @@ -662,6 +859,11 @@ protected override void Dispose(bool disposing) } } + /// Asynchronously releases the unmanaged resources used by the . + /// A task that represents the asynchronous dispose operation. + /// The `DisposeAsync` method enables you to perform a resource-intensive dispose operation without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the and keywords in Visual Basic and C#. + /// This method disposes the Deflate stream by writing any changes to the backing store and closing the stream to release resources. + /// Calling `DisposeAsync` allows the resources used by the to be reallocated for other purposes. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). public override ValueTask DisposeAsync() { return GetType() == typeof(DeflateStream) ? @@ -714,9 +916,42 @@ async ValueTask Core() } } + /// Begins an asynchronous write operation. (Consider using the method instead.) + /// The buffer to write data from. + /// The buffer to write data from. + /// The byte offset in to begin writing from. + /// The maximum number of bytes to write. + /// An optional asynchronous callback, to be called when the write operation is complete. + /// An optional asynchronous callback, to be called when the write operation is complete. + /// A user-provided object that distinguishes this particular asynchronous write request from other requests. + /// A user-provided object that distinguishes this particular asynchronous write request from other requests. + /// An object that represents the asynchronous write operation, which could still be pending. + /// Starting with the .NET Framework 4.5, you can perform asynchronous write operations by using the method. The method is still available in the .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). + /// Pass the object returned by the current method to to ensure that the write completes and frees resources appropriately. You can do this either by using the same code that called or in a callback passed to . If an error occurs during an asynchronous write operation, an exception will not be thrown until is called with the returned by this method. + /// If a stream is writable, writing at the end of the stream expands the stream. + /// The current position in the stream is updated when you issue the asynchronous read or write operation, not when the I/O operation completes. Multiple simultaneous asynchronous requests render the request completion order uncertain. + /// Use the property to determine whether the current object supports writing. + /// If a stream is closed or you pass an invalid argument, exceptions are thrown immediately from . Errors that occur during an asynchronous write request, such as a disk failure during the I/O request, occur on the thread pool thread and throw exceptions when calling . + /// The method tried to write asynchronously past the end of the stream, or a disk error occurred. + /// One or more of the arguments is invalid. + /// Methods were called after the stream was closed. + /// The current implementation does not support the write operation. + /// The write operation cannot be performed because the stream is closed. public override IAsyncResult BeginWrite(byte[] buffer, int offset, int count, AsyncCallback? asyncCallback, object? asyncState) => TaskToApm.Begin(WriteAsync(buffer, offset, count, CancellationToken.None), asyncCallback, asyncState); + /// Ends an asynchronous write operation. (Consider using the method instead.) + /// A reference to the outstanding asynchronous I/O request. + /// A reference to the outstanding asynchronous I/O request. + /// Starting with the .NET Framework 4.5, you can perform asynchronous write operations by using the method. The method is still available in the .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). + /// must be called only once for every call to the method. + /// This method blocks until the I/O operation has completed. Errors that occur during an asynchronous write request, such as a disk failure during the I/O request, occur on the thread pool thread and become visible upon a call to . Exceptions thrown by the thread pool thread will not be visible when calling . + /// is . + /// did not originate from a method on the current stream. + /// An exception was thrown during a call to . + /// The stream is . + /// -or- + /// The end write call is invalid. public override void EndWrite(IAsyncResult asyncResult) { EnsureCompressionMode(); @@ -724,12 +959,28 @@ public override void EndWrite(IAsyncResult asyncResult) TaskToApm.End(asyncResult); } + /// Asynchronously writes compressed bytes to the underlying Deflate stream from the specified byte array. + /// The buffer that contains the data to compress. + /// The zero-based byte offset in from which to begin copying bytes to the Deflate stream. + /// The maximum number of bytes to write. + /// The token to monitor for cancellation requests. The default value is . + /// A task that represents the asynchronous write operation. + /// The `WriteAsync` method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the and keywords in Visual Basic and C#. + /// Use the property to determine whether the current instance supports writing. + /// If the operation is canceled before it completes, the returned task contains the value for the property. public override Task WriteAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken) { ValidateBufferArguments(buffer, offset, count); return WriteAsyncMemory(new ReadOnlyMemory(buffer, offset, count), cancellationToken).AsTask(); } + /// Asynchronously writes compressed bytes to the underlying Deflate stream from the specified read-only memory region. + /// The region of memory to write data from. + /// The token to monitor for cancellation requests. The default value is . + /// A task that represents the asynchronous write operation. + /// The `WriteAsync` method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the and keywords in Visual Basic and C#. + /// Use the property to determine whether the current instance supports writing. + /// If the operation is canceled before it completes, the returned task contains the value for the property. public override ValueTask WriteAsync(ReadOnlyMemory buffer, CancellationToken cancellationToken) { if (GetType() != typeof(DeflateStream)) @@ -792,6 +1043,10 @@ private async ValueTask WriteDeflaterOutputAsync(CancellationToken cancellationT } } + /// Reads the bytes from the current Deflate stream and writes them to another stream, using a specified buffer size. + /// The stream to which the contents of the current Deflate stream will be copied. + /// The size of the buffer. This value must be greater than zero. The default size is 81920. + /// Copying begins at the current position in the current Deflate stream and does not reset the position of the destination stream after the copy operation is complete. public override void CopyTo(Stream destination, int bufferSize) { ValidateCopyToArguments(destination, bufferSize); @@ -802,6 +1057,14 @@ public override void CopyTo(Stream destination, int bufferSize) new CopyToStream(this, destination, bufferSize).CopyFromSourceToDestination(); } + /// Asynchronously reads the bytes from the current Deflate stream and writes them to another stream, using a specified buffer size. + /// The stream to which the contents of the current Deflate stream will be copied. + /// The size, in bytes, of the buffer. This value must be greater than zero. The default size is 81920. + /// The token to monitor for cancellation requests. The default value is . + /// A task that represents the asynchronous copy operation. + /// The `CopyToAsync` method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the and keywords in Visual Basic and C#. + /// If the operation is canceled before it completes, the returned task contains the value for the property. + /// Copying begins at the current position in the current Deflate stream. public override Task CopyToAsync(Stream destination, int bufferSize, CancellationToken cancellationToken) { ValidateCopyToArguments(destination, bufferSize); From 986d1ea6dac0e01c8d7184cc2545e8b769286381 Mon Sep 17 00:00:00 2001 From: carlossanlop Date: Thu, 25 Feb 2021 15:48:36 -0800 Subject: [PATCH 02/18] CompressionLevel --- .../System/IO/Compression/CompressionLevel.cs | 33 ++++++++++--------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/src/libraries/System.IO.Compression/src/System/IO/Compression/CompressionLevel.cs b/src/libraries/System.IO.Compression/src/System/IO/Compression/CompressionLevel.cs index 558708dedd9afc..99f184d35f241b 100644 --- a/src/libraries/System.IO.Compression/src/System/IO/Compression/CompressionLevel.cs +++ b/src/libraries/System.IO.Compression/src/System/IO/Compression/CompressionLevel.cs @@ -3,27 +3,30 @@ namespace System.IO.Compression { - /// - /// Specifies values that indicate whether a compression operation emphasizes speed or compression size. - /// - - // This is an abstract concept and NOT the ZLib compression level. - // There may or may not be any correspondence with the a possible implementation-specific level-parameter of the deflater. + /// Specifies values that indicate whether a compression operation emphasizes speed or compression size. + /// Compression operations usually involve a tradeoff between the speed and the effectiveness of compression. You use the enumeration to indicate which factor is more important in your development scenario: the time to complete the compression operation or the size of the compressed file. These values do not correspond to specific compression levels; the object that implements compression determines how to handle them. + /// The following methods of the , , , , and classes include a parameter named `compressionLevel` that lets you specify the compression level: + /// - + /// - + /// - + /// - + /// - + /// - + /// - + /// The following example shows how to set the compression level when creating a zip archive by using the class. + /// public enum CompressionLevel { - /// - /// The compression operation should balance compression speed and output size. - /// + /// The compression operation should be optimally compressed, even if the operation takes a longer time to complete. Optimal = 0, - /// - /// The compression operation should complete as quickly as possible, even if the resulting file is not optimally compressed. - /// + /// The compression operation should complete as quickly as possible, even if the resulting file is not optimally compressed. Fastest = 1, - /// - /// No compression should be performed on the file. - /// + /// No compression should be performed on the file. NoCompression = 2, /// From d4bae09fc24d44652c523253fb39a5ac2f35409a Mon Sep 17 00:00:00 2001 From: carlossanlop Date: Thu, 25 Feb 2021 15:48:43 -0800 Subject: [PATCH 03/18] CompressionMode --- .../src/System/IO/Compression/CompressionMode.cs | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/src/libraries/System.IO.Compression/src/System/IO/Compression/CompressionMode.cs b/src/libraries/System.IO.Compression/src/System/IO/Compression/CompressionMode.cs index f14efbbc41c28f..078e69ba29c0bc 100644 --- a/src/libraries/System.IO.Compression/src/System/IO/Compression/CompressionMode.cs +++ b/src/libraries/System.IO.Compression/src/System/IO/Compression/CompressionMode.cs @@ -3,9 +3,18 @@ namespace System.IO.Compression { + /// Specifies whether to compress or decompress the underlying stream. + /// This enumeration is used with the and classes. + /// The following code example uses the enumeration with the class to compress and decompress a file. + /// public enum CompressionMode { + /// Decompresses the underlying stream. Decompress = 0, + /// Compresses the underlying stream. Compress = 1 } } From f0628ad7b55242e5f4e2f7135f26e31d4377d793 Mon Sep 17 00:00:00 2001 From: carlossanlop Date: Thu, 25 Feb 2021 15:48:51 -0800 Subject: [PATCH 04/18] GZipStream --- .../src/System/IO/Compression/GZipStream.cs | 259 +++++++++++++++++- 1 file changed, 257 insertions(+), 2 deletions(-) diff --git a/src/libraries/System.IO.Compression/src/System/IO/Compression/GZipStream.cs b/src/libraries/System.IO.Compression/src/System/IO/Compression/GZipStream.cs index 8e674d13b97a82..225f3c3b34d85b 100644 --- a/src/libraries/System.IO.Compression/src/System/IO/Compression/GZipStream.cs +++ b/src/libraries/System.IO.Compression/src/System/IO/Compression/GZipStream.cs @@ -7,47 +7,125 @@ namespace System.IO.Compression { + /// Provides methods and properties used to compress and decompress streams by using the GZip data format specification. + /// This class represents the gzip data format, which uses an industry-standard algorithm for lossless file compression and decompression. The format includes a cyclic redundancy check value for detecting data corruption. The gzip data format uses the same algorithm as the class, but can be extended to use other compression formats. The format can be readily implemented in a manner not covered by patents. + /// Starting with the .NET Framework 4.5, the class uses the zlib library for compression. As a result, it provides a better compression algorithm and, in most cases, a smaller compressed file than it provides in earlier versions of the .NET Framework. + /// Compressed objects written to a file with an extension of .gz can be decompressed using many common compression tools; however, this class does not inherently provide functionality for adding files to or extracting files from zip archives. + /// The compression functionality in and is exposed as a stream. Data is read on a byte-by-byte basis, so it is not possible to perform multiple passes to determine the best method for compressing entire files or large blocks of data. The and classes are best used on uncompressed sources of data. If the source data is already compressed, using these classes may actually increase the size of the stream. + /// The following example shows how to use the class to compress and decompress a directory of files. + /// public class GZipStream : Stream { private DeflateStream _deflateStream; + /// Initializes a new instance of the class by using the specified stream and compression mode. + /// The stream the compressed or decompressed data is written to. + /// One of the enumeration values that indicates whether to compress or decompress the stream. + /// By default, owns the underlying stream, so closing the parameter also closes the underlying stream. Note that the state of the underlying stream can affect the usability of the stream. Also, no explicit checks are performed, so no additional exceptions are thrown when the new instance is created. + /// If an instance of the class is created with the parameter equal to `Compress` and no further action occurs, the stream will appear as a valid, empty compressed file. + /// By default, the compression level is set to when the compression mode is . + /// The following example initializes a new instance of the class with set to . This example is part of a larger example provided for the class. + /// + /// is . + /// is not a valid enumeration value. + /// -or- + /// is and is . + /// -or- + /// is and is . public GZipStream(Stream stream, CompressionMode mode) : this(stream, mode, leaveOpen: false) { } + /// Initializes a new instance of the class by using the specified stream and compression mode, and optionally leaves the stream open. + /// The stream to compress. + /// One of the enumeration values that indicates whether to compress or decompress the stream. + /// to leave the stream open after disposing the object; otherwise, . + /// By default, owns the underlying stream, so closing the parameter also closes the underlying stream. Note that the state of the underlying stream can affect the usability of the stream. Also, no explicit checks are performed, so no additional exceptions are thrown when the new instance is created. + /// If an instance of the class is created with the parameter equal to `Compress` and no further action occurs, the stream will appear as a valid, empty compressed file. + /// By default, the compression level is set to when the compression mode is . + /// is . + /// is not a valid value. + /// -or- + /// is and is . + /// -or- + /// is and is . public GZipStream(Stream stream, CompressionMode mode, bool leaveOpen) { _deflateStream = new DeflateStream(stream, mode, leaveOpen, ZLibNative.GZip_DefaultWindowBits); } - // Implies mode = Compress + /// Initializes a new instance of the class by using the specified stream and compression level. + /// The stream to compress. + /// One of the enumeration values that indicates whether to emphasize speed or compression efficiency when compressing the stream. + /// You use this constructor when you want to specify whether compression efficiency or speed is more important for an instance of the class. + /// This constructor overload uses the compression mode . To set the compression mode to another value, use the or overload. + /// The following example shows how to set the compression level when creating a object. + /// + /// is . + /// The stream does not support write operations such as compression. (The property on the stream object is .) public GZipStream(Stream stream, CompressionLevel compressionLevel) : this(stream, compressionLevel, leaveOpen: false) { } - // Implies mode = Compress + /// Initializes a new instance of the class by using the specified stream and compression level, and optionally leaves the stream open. + /// The stream to write the compressed data to. + /// One of the enumeration values that indicates whether to emphasize speed or compression efficiency when compressing the stream. + /// to leave the stream object open after disposing the object; otherwise, . + /// You use this constructor when you want to specify whether compression efficiency or speed is more important for an instance of the class, and whether to leave the stream object open after disposing the object. + /// This constructor overload uses the compression mode . To set the compression mode to another value, use the or overload. + /// The following example shows how to set the compression level when creating a object and how to leave the stream open. + /// + /// is . + /// The stream does not support write operations such as compression. (The property on the stream object is .) public GZipStream(Stream stream, CompressionLevel compressionLevel, bool leaveOpen) { _deflateStream = new DeflateStream(stream, compressionLevel, leaveOpen, ZLibNative.GZip_DefaultWindowBits); } + /// Gets a value indicating whether the stream supports reading while decompressing a file. + /// if the value is and the underlying stream supports reading and is not closed; otherwise, . public override bool CanRead => _deflateStream?.CanRead ?? false; + /// Gets a value indicating whether the stream supports writing. + /// if the value is , and the underlying stream supports writing and is not closed; otherwise, . public override bool CanWrite => _deflateStream?.CanWrite ?? false; + /// Gets a value indicating whether the stream supports seeking. + /// in all cases. public override bool CanSeek => _deflateStream?.CanSeek ?? false; + /// This property is not supported and always throws a . + /// A long value. + /// This property is not supported on this stream. public override long Length { get { throw new NotSupportedException(SR.NotSupported); } } + /// This property is not supported and always throws a . + /// A long value. + /// This property is not supported on this stream. public override long Position { get { throw new NotSupportedException(SR.NotSupported); } set { throw new NotSupportedException(SR.NotSupported); } } + /// Flushes the internal buffers. + /// This method flushes only if the current compression mode is and the underlying stream still has some input left to write. + /// The underlying stream is closed. public override void Flush() { CheckDeflateStream(); @@ -55,34 +133,112 @@ public override void Flush() return; } + /// This property is not supported and always throws a . + /// The location in the stream. + /// One of the values. + /// A long value. + /// This property is not supported on this stream. public override long Seek(long offset, SeekOrigin origin) { throw new NotSupportedException(SR.NotSupported); } + /// This property is not supported and always throws a . + /// The length of the stream. + /// This property is not supported on this stream. public override void SetLength(long value) { throw new NotSupportedException(SR.NotSupported); } + /// Reads a byte from the GZip stream and advances the position within the stream by one byte, or returns -1 if at the end of the GZip stream. + /// The unsigned byte cast to an , or -1 if at the end of the stream. + /// Use the property to determine whether the current instance supports reading. public override int ReadByte() { CheckDeflateStream(); return _deflateStream.ReadByte(); } + /// Begins an asynchronous read operation. (Consider using the method instead.) + /// The byte array to read the data into. + /// The byte array to read the data into. + /// The byte offset in at which to begin reading data from the stream. + /// The maximum number of bytes to read. + /// An optional asynchronous callback, to be called when the read operation is complete. + /// An optional asynchronous callback, to be called when the read operation is complete. + /// A user-provided object that distinguishes this particular asynchronous read request from other requests. + /// A user-provided object that distinguishes this particular asynchronous read request from other requests. + /// An object that represents the asynchronous read operation, which could still be pending. + /// Starting with the .NET Framework 4.5, you can perform asynchronous read operations by using the method. The method is still available in .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). + /// Pass the return value to the method of the stream to determine how many bytes were read and to release operating system resources used for reading. You can do this either by using the same code that called or in a callback passed to . + /// The current position in the stream is updated when the asynchronous read or write is issued, not when the I/O operation completes. + /// Multiple simultaneous asynchronous requests render the request completion order uncertain. + /// Use the property to determine whether the current object supports reading. + /// If a stream is closed or you pass an invalid argument, exceptions are thrown immediately from . Errors that occur during an asynchronous read request, such as a disk failure during the I/O request, occur on the thread pool thread and throw exceptions when calling . + /// The following code example shows how to use the class to compress and decompress a file. + /// + /// The method tried to read asynchronously past the end of the stream, or a disk error occurred. + /// One or more of the arguments is invalid. + /// Methods were called after the stream was closed. + /// The current implementation does not support the read operation. + /// A read operation cannot be performed because the stream is closed. public override IAsyncResult BeginRead(byte[] buffer, int offset, int count, AsyncCallback? asyncCallback, object? asyncState) => TaskToApm.Begin(ReadAsync(buffer, offset, count, CancellationToken.None), asyncCallback, asyncState); + /// Waits for the pending asynchronous read to complete. (Consider using the method instead.) + /// The reference to the pending asynchronous request to finish. + /// The reference to the pending asynchronous request to finish. + /// The number of bytes read from the stream, between 0 (zero) and the number of bytes you requested. returns 0 only at the end of the stream; otherwise, it blocks until at least one byte is available. + /// Starting with the .NET Framework 4.5, you can perform asynchronous read operations by using the method. The method is still available in .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). + /// Call this method to determine how many bytes were read from the stream. This method can be called once to return the amount of bytes read between calls to and . + /// This method blocks until the I/O operation has completed. + /// The following code example shows how to use the class to compress and decompress a file. + /// + /// is . + /// did not originate from a method on the current stream. + /// The end operation cannot be performed because the stream is closed. public override int EndRead(IAsyncResult asyncResult) => _deflateStream.EndRead(asyncResult); + /// Reads a number of decompressed bytes into the specified byte array. + /// The array used to store decompressed bytes. + /// The byte offset in at which the read bytes will be placed. + /// The maximum number of decompressed bytes to read. + /// The number of bytes that were decompressed into the byte array. If the end of the stream has been reached, zero or the number of bytes read is returned. + /// If data is found in an invalid format, an is thrown as one of the last operations. A cyclic redundancy check (CRC) is performed as one of the last operations of this method. + /// The following example shows how to compress and decompress bytes by using the and methods. + /// + /// is . + /// The value was when the object was created. + /// -or- + /// The underlying stream does not support reading. + /// or is less than zero. + /// -or- + /// length minus the index starting point is less than . + /// The data is in an invalid format. + /// The stream is closed. public override int Read(byte[] buffer, int offset, int count) { CheckDeflateStream(); return _deflateStream.Read(buffer, offset, count); } + /// Reads a sequence of bytes from the current GZip stream into a byte span and advances the position within the GZip stream by the number of bytes read. + /// A region of memory. When this method returns, the contents of this region are replaced by the bytes read from the current source. + /// The total number of bytes read into the buffer. This can be less than the number of bytes allocated in the buffer if that many bytes are not currently available, or zero (0) if the end of the stream has been reached. + /// Use the property to determine whether the current instance supports reading. Use the method to read asynchronously from the current stream. + /// This method read a maximum of `buffer.Length` bytes from the current stream and store them in . The current position within the GZip stream is advanced by the number of bytes read; however, if an exception occurs, the current position within the GZip stream remains unchanged. This method will block until at least one byte of data can be read, in the event that no data is available. `Read` returns 0 only when there is no more data in the stream and no more is expected (such as a closed socket or end of file). The method is free to return fewer bytes than requested even if the end of the stream has not been reached. + /// Use for reading primitive data types. public override int Read(Span buffer) { if (GetType() != typeof(GZipStream)) @@ -99,18 +255,57 @@ public override int Read(Span buffer) } } + /// Begins an asynchronous write operation. (Consider using the method instead.) + /// The buffer containing data to write to the current stream. + /// The buffer containing data to write to the current stream. + /// The byte offset in at which to begin writing. + /// The maximum number of bytes to write. + /// An optional asynchronous callback to be called when the write operation is complete. + /// An optional asynchronous callback to be called when the write operation is complete. + /// A user-provided object that distinguishes this particular asynchronous write request from other requests. + /// A user-provided object that distinguishes this particular asynchronous write request from other requests. + /// An object that represents the asynchronous write operation, which could still be pending. + /// Starting with the .NET Framework 4.5, you can perform asynchronous write operations by using the method. The method is still available in .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). + /// The method starts an asynchronous write operation to a stream object. + /// You must create a callback method that implements the delegate and pass its name to the method. + /// The underlying stream is . + /// -or- + /// The underlying stream is closed. public override IAsyncResult BeginWrite(byte[] buffer, int offset, int count, AsyncCallback? asyncCallback, object? asyncState) => TaskToApm.Begin(WriteAsync(buffer, offset, count, CancellationToken.None), asyncCallback, asyncState); + /// Handles the end of an asynchronous write operation. (Consider using the method instead.) + /// The object that represents the asynchronous call. + /// The object that represents the asynchronous call. + /// Starting with the .NET Framework 4.5, you can perform asynchronous write operations by using the method. The method is still available in .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). + /// The method completes the asynchronous write operation started in the method. + /// The underlying stream is . + /// -or- + /// The underlying stream is closed. public override void EndWrite(IAsyncResult asyncResult) => _deflateStream.EndWrite(asyncResult); + /// Writes compressed bytes to the underlying GZip stream from the specified byte array. + /// The buffer that contains the data to compress. + /// The byte offset in from which the bytes will be read. + /// The maximum number of bytes to write. + /// The write operation might not occur immediately but is buffered until the buffer size is reached or until the or method is called. + /// The following example shows how to compress and decompress bytes by using the and methods. + /// + /// The write operation cannot be performed because the stream is closed. public override void Write(byte[] buffer, int offset, int count) { CheckDeflateStream(); _deflateStream.Write(buffer, offset, count); } + /// Writes a sequence of bytes to the current GZip stream from a read-only byte span and advances the current position within this GZip stream by the number of bytes written. + /// A region of memory. This method copies the contents of this region to the current GZip stream. + /// Use the property to determine whether the current instance supports writing. Use the method to write asynchronously to the current stream. + /// If the write operation is successful, the position within the GZip stream advances by the number of bytes written. If an exception occurs, the position within the GZip stream remains unchanged. public override void Write(ReadOnlySpan buffer) { if (GetType() != typeof(GZipStream)) @@ -127,12 +322,20 @@ public override void Write(ReadOnlySpan buffer) } } + /// Reads the bytes from the current GZip stream and writes them to another stream, using a specified buffer size. + /// The stream to which the contents of the current GZip stream will be copied. + /// The size of the buffer. This value must be greater than zero. The default size is 81920. + /// Copying begins at the current position in the current GZip stream, and does not reset the position of the destination stream after the copy operation is complete. public override void CopyTo(Stream destination, int bufferSize) { CheckDeflateStream(); _deflateStream.CopyTo(destination, bufferSize); } + /// Releases the unmanaged resources used by the and optionally releases the managed resources. + /// to release both managed and unmanaged resources; to release only unmanaged resources. + /// This method is called by the public method and the method. invokes the protected method with the parameter set to . invokes with set to . + /// When the parameter is , this method releases all resources held by any managed objects that this references. This method invokes the method of each referenced object. protected override void Dispose(bool disposing) { try @@ -149,6 +352,11 @@ protected override void Dispose(bool disposing) } } + /// Asynchronously releases the unmanaged resources used by the . + /// A task that represents the asynchronous dispose operation. + /// The `DisposeAsync` method enables you to perform a resource-intensive dispose operation without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the and keywords in Visual Basic and C#. + /// This method disposes the GZip stream by writing any changes to the backing store and closing the stream to release resources. + /// Calling `DisposeAsync` allows the resources used by the to be reallocated for other purposes. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). public override ValueTask DisposeAsync() { if (GetType() != typeof(GZipStream)) @@ -166,14 +374,33 @@ public override ValueTask DisposeAsync() return default; } + /// Gets a reference to the underlying stream. + /// A stream object that represents the underlying stream. + /// The underlying stream is closed. public Stream BaseStream => _deflateStream?.BaseStream!; + /// Asynchronously reads a sequence of bytes from the current GZip stream into a byte array, advances the position within the GZip stream by the number of bytes read, and monitors cancellation requests. + /// The buffer to write the data into. + /// The byte offset in at which to begin writing data from the GZip stream. + /// The maximum number of bytes to read. + /// The token to monitor for cancellation requests. The default value is . + /// A task that represents the asynchronous read operation, which wraps the total number of bytes read into the . The result value can be less than the number of bytes requested if the number of bytes currently available is less than the requested number, or it can be 0 (zero) if the end of the GZip stream has been reached. + /// The `ReadAsync` method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the and keywords in Visual Basic and C#. + /// Use the property to determine whether the current instance supports reading. + /// If the operation is canceled before it completes, the returned task contains the value for the property. public override Task ReadAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken) { CheckDeflateStream(); return _deflateStream.ReadAsync(buffer, offset, count, cancellationToken); } + /// Asynchronously reads a sequence of bytes from the current GZip stream into a byte memory region, advances the position within the GZip stream by the number of bytes read, and monitors cancellation requests. + /// The region of memory to write the data into. + /// The token to monitor for cancellation requests. The default value is . + /// A task that represents the asynchronous read operation, which wraps the total number of bytes read into the buffer. The result value can be less than the number of bytes allocated in the buffer if that many bytes are not currently available, or it can be 0 (zero) if the end of the GZip stream has been reached. + /// The `ReadAsync` method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the and keywords in Visual Basic and C#. + /// Use the property to determine whether the current instance supports reading. + /// If the operation is canceled before it completes, the returned task contains the value for the property. public override ValueTask ReadAsync(Memory buffer, CancellationToken cancellationToken = default(CancellationToken)) { if (GetType() != typeof(GZipStream)) @@ -190,12 +417,28 @@ public override Task ReadAsync(byte[] buffer, int offset, int count, Cancel } } + /// Asynchronously writes compressed bytes to the underlying GZip stream from the specified byte array. + /// The buffer that contains the data to compress. + /// The zero-based byte offset in from which to begin copying bytes to the GZip stream. + /// The maximum number of bytes to write. + /// The token to monitor for cancellation requests. The default value is . + /// A task that represents the asynchronous write operation. + /// The `WriteAsync` method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the and keywords in Visual Basic and C#. + /// Use the property to determine whether the current instance supports writing. + /// If the operation is canceled before it completes, the returned task contains the value for the property. public override Task WriteAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken) { CheckDeflateStream(); return _deflateStream.WriteAsync(buffer, offset, count, cancellationToken); } + /// Asynchronously writes compressed bytes to the underlying GZip stream from the specified read-only byte memory region. + /// The region of memory to write data from. + /// The token to monitor for cancellation requests. The default value is . + /// A task that represents the asynchronous write operation. + /// The `WriteAsync` method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the and keywords in Visual Basic and C#. + /// Use the property to determine whether the current instance supports writing. + /// If the operation is canceled before it completes, the returned task contains the value for the property. public override ValueTask WriteAsync(ReadOnlyMemory buffer, CancellationToken cancellationToken = default(CancellationToken)) { if (GetType() != typeof(GZipStream)) @@ -212,12 +455,24 @@ public override Task WriteAsync(byte[] buffer, int offset, int count, Cancellati } } + /// Asynchronously clears all buffers for this GZip stream, causes any buffered data to be written to the underlying device, and monitors cancellation requests. + /// The token to monitor for cancellation requests. The default value is . + /// A task that represents the asynchronous flush operation. + /// If the operation is canceled before it completes, the returned task contains the value for the property. public override Task FlushAsync(CancellationToken cancellationToken) { CheckDeflateStream(); return _deflateStream.FlushAsync(cancellationToken); } + /// Asynchronously reads the bytes from the current GZip stream and writes them to another stream, using a specified buffer size. + /// The stream to which the contents of the current GZip stream will be copied. + /// The size, in bytes, of the buffer. This value must be greater than zero. The default size is 81920. + /// The token to monitor for cancellation requests. The default value is . + /// A task that represents the asynchronous copy operation. + /// The method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the and keywords in Visual Basic and C#. + /// If the operation is canceled before it completes, the returned task contains the value for the property. + /// Copying begins at the current position in the current GZip stream. public override Task CopyToAsync(Stream destination, int bufferSize, CancellationToken cancellationToken) { CheckDeflateStream(); From 46f53e7d70beef9438e6ca8f7ec248c610afba37 Mon Sep 17 00:00:00 2001 From: carlossanlop Date: Thu, 25 Feb 2021 15:48:58 -0800 Subject: [PATCH 05/18] ZipArchive --- .../src/System/IO/Compression/ZipArchive.cs | 279 ++++++++++-------- 1 file changed, 151 insertions(+), 128 deletions(-) diff --git a/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchive.cs b/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchive.cs index 5fbd00c47006c3..7819856d725c79 100644 --- a/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchive.cs +++ b/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchive.cs @@ -11,6 +11,35 @@ namespace System.IO.Compression { + /// Represents a package of compressed files in the zip archive format. + /// The methods for manipulating zip archives and their file entries are spread across three classes: , , and . + /// |To|Use| + /// |--------|---------| + /// |Create a zip archive from a directory|| + /// |Extract the contents of a zip archive to a directory|| + /// |Add new files to an existing zip archive|| + /// |Retrieve a file from a zip archive|| + /// |Retrieve all the files from a zip archive|| + /// |Open a stream to a single file contained in a zip archive|| + /// |Delete a file from a zip archive|| + /// When you create a new entry, the file is compressed and added to the zip package. The method enables you to specify a directory hierarchy when adding the entry. You include the relative path of the new entry within the zip package. For example, creating a new entry with a relative path of `AddedFolder\NewFile.txt` creates a compressed text file in a directory named AddedFolder. + /// If you reference the `System.IO.Compression.FileSystem` assembly in your project, you can access four extension methods (from the class) for the class: , , , and (available in .NET Core 2.0 and later versions). These extension methods enable you to compress and decompress the contents of the entry to a file. The `System.IO.Compression.FileSystem` assembly is not available for Windows 8.x Store apps. In Windows 8.x Store apps, you can compress and decompress files by using the or class, or you can use the Windows Runtime types Compressor](https://go.microsoft.com/fwlink/p/?LinkID=246357) and [Decompressor. + /// The first example shows how to create a new entry and write to it by using a stream. + /// + /// The following example shows how to open a zip archive and iterate through the collection of entries. + /// + /// The third example shows how to use extension methods to create a new entry in a zip archive from an existing file and extract the archive contents. You must reference the `System.IO.Compression.FileSystem` assembly to execute the code. + /// + /// public class ZipArchive : IDisposable { private readonly Stream _archiveStream; @@ -30,92 +59,68 @@ public class ZipArchive : IDisposable private byte[]? _archiveComment; private Encoding? _entryNameEncoding; -#if DEBUG_FORCE_ZIP64 - public bool _forceZip64; -#endif - - /// - /// Initializes a new instance of ZipArchive on the given stream for reading. - /// - /// The stream is already closed or does not support reading. - /// The stream is null. - /// The contents of the stream could not be interpreted as a Zip archive. - /// The stream containing the archive to be read. + /// Initializes a new instance of the class from the specified stream. + /// The stream that contains the archive to be read. + /// The stream is already closed or does not support reading. + /// is . + /// The contents of the stream are not in the zip archive format. public ZipArchive(Stream stream) : this(stream, ZipArchiveMode.Read, leaveOpen: false, entryNameEncoding: null) { } - /// - /// Initializes a new instance of ZipArchive on the given stream in the specified mode. - /// - /// The stream is already closed. -or- mode is incompatible with the capabilities of the stream. - /// The stream is null. - /// mode specified an invalid value. - /// The contents of the stream could not be interpreted as a Zip file. -or- mode is Update and an entry is missing from the archive or is corrupt and cannot be read. -or- mode is Update and an entry is too large to fit into memory. + /// Initializes a new instance of the class from the specified stream and with the specified mode. /// The input or output stream. - /// See the description of the ZipArchiveMode enum. Read requires the stream to support reading, Create requires the stream to support writing, and Update requires the stream to support reading, writing, and seeking. + /// One of the enumeration values that indicates whether the zip archive is used to read, create, or update entries. + /// If the parameter is set to , the stream must support reading. If the parameter is set to , the stream must support writing. If the parameter is set to , the stream must support reading, writing, and seeking. + /// The stream is already closed, or the capabilities of the stream do not match the mode. + /// is . + /// is an invalid value. + /// The contents of the stream could not be interpreted as a zip archive. + /// -or- + /// is and an entry is missing from the archive or is corrupt and cannot be read. + /// -or- + /// is and an entry is too large to fit into memory. public ZipArchive(Stream stream, ZipArchiveMode mode) : this(stream, mode, leaveOpen: false, entryNameEncoding: null) { } - /// - /// Initializes a new instance of ZipArchive on the given stream in the specified mode, specifying whether to leave the stream open. - /// - /// The stream is already closed. -or- mode is incompatible with the capabilities of the stream. - /// The stream is null. - /// mode specified an invalid value. - /// The contents of the stream could not be interpreted as a Zip file. -or- mode is Update and an entry is missing from the archive or is corrupt and cannot be read. -or- mode is Update and an entry is too large to fit into memory. + /// Initializes a new instance of the class on the specified stream for the specified mode, and optionally leaves the stream open. /// The input or output stream. - /// See the description of the ZipArchiveMode enum. Read requires the stream to support reading, Create requires the stream to support writing, and Update requires the stream to support reading, writing, and seeking. - /// true to leave the stream open upon disposing the ZipArchive, otherwise false. + /// One of the enumeration values that indicates whether the zip archive is used to read, create, or update entries. + /// to leave the stream open after the object is disposed; otherwise, . + /// If the parameter is set to , the stream must support reading. If the parameter is set to , the stream must support writing. If the parameter is set to , the stream must support reading, writing, and seeking. + /// The stream is already closed, or the capabilities of the stream do not match the mode. + /// is . + /// is an invalid value. + /// The contents of the stream could not be interpreted as a zip archive. + /// -or- + /// is and an entry is missing from the archive or is corrupt and cannot be read. + /// -or- + /// is and an entry is too large to fit into memory. public ZipArchive(Stream stream, ZipArchiveMode mode, bool leaveOpen) : this(stream, mode, leaveOpen, entryNameEncoding: null) { } - /// - /// Initializes a new instance of ZipArchive on the given stream in the specified mode, specifying whether to leave the stream open. - /// - /// The stream is already closed. -or- mode is incompatible with the capabilities of the stream. - /// The stream is null. - /// mode specified an invalid value. - /// The contents of the stream could not be interpreted as a Zip file. -or- mode is Update and an entry is missing from the archive or is corrupt and cannot be read. -or- mode is Update and an entry is too large to fit into memory. + /// Initializes a new instance of the class on the specified stream for the specified mode, uses the specified encoding for entry names, and optionally leaves the stream open. /// The input or output stream. - /// See the description of the ZipArchiveMode enum. Read requires the stream to support reading, Create requires the stream to support writing, and Update requires the stream to support reading, writing, and seeking. - /// true to leave the stream open upon disposing the ZipArchive, otherwise false. - /// The encoding to use when reading or writing entry names in this ZipArchive. - /// /// NOTE: Specifying this parameter to values other than null is discouraged. - /// However, this may be necessary for interoperability with ZIP archive tools and libraries that do not correctly support - /// UTF-8 encoding for entry names.
- /// This value is used as follows: - /// Reading (opening) ZIP archive files: - /// If entryNameEncoding is not specified (== null): - /// - /// For entries where the language encoding flag (EFS) in the general purpose bit flag of the local file header is not set, - /// use the current system default code page (Encoding.Default) in order to decode the entry name. - /// For entries where the language encoding flag (EFS) in the general purpose bit flag of the local file header is set, - /// use UTF-8 (Encoding.UTF8) in order to decode the entry name. - /// - /// If entryNameEncoding is specified (!= null): - /// - /// For entries where the language encoding flag (EFS) in the general purpose bit flag of the local file header is not set, - /// use the specified entryNameEncoding in order to decode the entry name. - /// For entries where the language encoding flag (EFS) in the general purpose bit flag of the local file header is set, - /// use UTF-8 (Encoding.UTF8) in order to decode the entry name. - /// - /// Writing (saving) ZIP archive files: - /// If entryNameEncoding is not specified (== null): - /// - /// For entry names that contain characters outside the ASCII range, - /// the language encoding flag (EFS) will be set in the general purpose bit flag of the local file header, - /// and UTF-8 (Encoding.UTF8) will be used in order to encode the entry name into bytes. - /// For entry names that do not contain characters outside the ASCII range, - /// the language encoding flag (EFS) will not be set in the general purpose bit flag of the local file header, - /// and the current system default code page (Encoding.Default) will be used to encode the entry names into bytes. - /// - /// If entryNameEncoding is specified (!= null): - /// - /// The specified entryNameEncoding will always be used to encode the entry names into bytes. - /// The language encoding flag (EFS) in the general purpose bit flag of the local file header will be set if and only - /// if the specified entryNameEncoding is a UTF-8 encoding. - /// - /// Note that Unicode encodings other than UTF-8 may not be currently used for the entryNameEncoding, - /// otherwise an is thrown. - /// - /// If a Unicode encoding other than UTF-8 is specified for the entryNameEncoding. + /// One of the enumeration values that indicates whether the zip archive is used to read, create, or update entries. + /// to leave the stream open after the object is disposed; otherwise, . + /// The encoding to use when reading or writing entry names in this archive. Specify a value for this parameter only when an encoding is required for interoperability with zip archive tools and libraries that do not support UTF-8 encoding for entry names. + /// If the parameter is set to , the stream must support reading. If the parameter is set to , the stream must support writing. If the parameter is set to , the stream must support reading, writing, and seeking. + /// When you open a zip archive file for reading and is set to , entry names are decoded according to the following rules: + /// - When the language encoding flag (in the general-purpose bit flag of the local file header) is not set, the current system default code page is used to decode the entry name. + /// - When the language encoding flag is set, UTF-8 is used to decode the entry name. + /// When you open a zip archive file for reading and is set to a value other than , entry names are decoded according to the following rules: + /// - When the language encoding flag is not set, the specified is used to decode the entry name. + /// - When the language encoding flag is set, UTF-8 is used to decode the entry name. + /// When you write to archive files and is set to , entry names are encoded according to the following rules: + /// - For entry names that contain characters outside the ASCII range, the language encoding flag is set, and entry names are encoded by using UTF-8. + /// - For entry names that contain only ASCII characters, the language encoding flag is not set, and entry names are encoded by using the current system default code page. + /// When you write to archive files and is set to a value other than , the specified is used to encode the entry names into bytes. The language encoding flag (in the general-purpose bit flag of the local file header) is set only when the specified encoding is a UTF-8 encoding. + /// The stream is already closed, or the capabilities of the stream do not match the mode. + /// -or- + /// An encoding other than UTF-8 is specified for the . + /// is . + /// is an invalid value. + /// The contents of the stream could not be interpreted as a zip archive. + /// -or- + /// is and an entry is missing from the archive or is corrupt and cannot be read. + /// -or- + /// is and an entry is too large to fit into memory. public ZipArchive(Stream stream, ZipArchiveMode mode, bool leaveOpen, Encoding? entryNameEncoding) { if (stream == null) @@ -211,12 +216,17 @@ public ZipArchive(Stream stream, ZipArchiveMode mode, bool leaveOpen, Encoding? } } - /// - /// The collection of entries that are currently in the ZipArchive. This may not accurately represent the actual entries that are present in the underlying file or stream. - /// - /// The ZipArchive does not support reading. - /// The ZipArchive has already been closed. - /// The Zip archive is corrupt and the entries cannot be retrieved. + /// Gets the collection of entries that are currently in the zip archive. + /// The collection of entries that are currently in the zip archive. + /// Use the property to retrieve the entire collection of entries. Use the method to retrieve a single entry by name. + /// The following example shows how to open a zip archive and iterate through the collection of entries. + /// + /// The zip archive does not support reading. + /// The zip archive has been disposed. + /// The zip archive is corrupt, and its entries cannot be retrieved. public ReadOnlyCollection Entries { get @@ -231,9 +241,9 @@ public ReadOnlyCollection Entries } } - /// - /// The ZipArchiveMode that the ZipArchive was initialized with. - /// + /// Gets a value that describes the type of action the zip archive can perform on entries. + /// One of the enumeration values that describes the type of action (read, create, or update) the zip archive can perform on entries. + /// You specify a value for the property when you create an instance of the class. Use the or constructor to provide a value for the property. public ZipArchiveMode Mode { get @@ -242,45 +252,53 @@ public ZipArchiveMode Mode } } - /// - /// Creates an empty entry in the Zip archive with the specified entry name. - /// There are no restrictions on the names of entries. - /// The last write time of the entry is set to the current time. - /// If an entry with the specified name already exists in the archive, a second entry will be created that has an identical name. - /// Since no CompressionLevel is specified, the default provided by the implementation of the underlying compression - /// algorithm will be used; the ZipArchive will not impose its own default. - /// (Currently, the underlying compression algorithm is provided by the System.IO.Compression.DeflateStream class.) - /// - /// entryName is a zero-length string. - /// entryName is null. - /// The ZipArchive does not support writing. - /// The ZipArchive has already been closed. - /// A path relative to the root of the archive, indicating the name of the entry to be created. - /// A wrapper for the newly created file entry in the archive. + /// Creates an empty entry that has the specified path and entry name in the zip archive. + /// A path, relative to the root of the archive, that specifies the name of the entry to be created. + /// An empty entry in the zip archive. + /// The string should reflect the relative path of the entry you want to create within the zip archive. There is no restriction on the string you provide. However, if it is not formatted as a relative path, the entry is created, but you may get an exception when you extract the contents of the zip archive. If an entry with the specified path and name already exists in the archive, a second entry is created with the same path and name. + /// The value of the property for the new entry is set to the current time. The entry is compressed using the default compression level of the underlying compression algorithm. If you want to specify a different compression level, use the method. + /// The following example shows how to create an entry and write to it by using a stream. + /// + /// is . + /// is . + /// The zip archive does not support writing. + /// The zip archive has been disposed. public ZipArchiveEntry CreateEntry(string entryName) { return DoCreateEntry(entryName, null); } - /// - /// Creates an empty entry in the Zip archive with the specified entry name. There are no restrictions on the names of entries. The last write time of the entry is set to the current time. If an entry with the specified name already exists in the archive, a second entry will be created that has an identical name. - /// - /// entryName is a zero-length string. - /// entryName is null. - /// The ZipArchive does not support writing. - /// The ZipArchive has already been closed. - /// A path relative to the root of the archive, indicating the name of the entry to be created. - /// The level of the compression (speed/memory vs. compressed size trade-off). - /// A wrapper for the newly created file entry in the archive. + /// Creates an empty entry that has the specified entry name and compression level in the zip archive. + /// A path, relative to the root of the archive, that specifies the name of the entry to be created. + /// One of the enumeration values that indicates whether to emphasize speed or compression effectiveness when creating the entry. + /// An empty entry in the zip archive. + /// The string should reflect the relative path of the entry you want to create within the zip archive. There is no restriction on the string you provide. However, if it is not formatted as a relative path, the entry is created, but you may get an exception when you extract the contents of the zip archive. If an entry with the specified name already exists in the archive, a second entry is created with the same name. + /// The value of the property for the new entry is set to the current time. Set the parameter to if you want the file to be compressed as much as possible. Set the parameter to only if you are concerned that the compression operation will not complete quickly enough for your scenario. + /// The following example shows how to create an entry with the optimal compression level. It also writes to the new entry by using a stream. + /// + /// is . + /// is . + /// The zip archive does not support writing. + /// The zip archive has been disposed. public ZipArchiveEntry CreateEntry(string entryName, CompressionLevel compressionLevel) { return DoCreateEntry(entryName, compressionLevel); } - /// - /// Releases the unmanaged resources used by ZipArchive and optionally finishes writing the archive and releases the managed resources. - /// - /// true to finish writing the archive and release unmanaged and managed resources, false to release only unmanaged resources. + /// Called by the and methods to release the unmanaged resources used by the current instance of the class, and optionally finishes writing the archive and releases the managed resources. + /// to finish writing the archive and release unmanaged and managed resources; to release only unmanaged resources. + /// If is set to , all underlying streams are closed and no longer available for subsequent write operations, unless you construct the object by using the constructor overload and set its `leaveOpen` parameter to . + /// This method is called only by the public and methods; do not call this method directly. + /// When you implement the dispose pattern, the Boolean parameter of the method should be used as follows: + /// - The method of the current object should call with the Boolean parameter set to to release both managed and unmanaged resources. + /// - The method of the current object should call with the Boolean parameter set to to release only unmanaged resources. + /// For more information, see [Implementing a Dispose method](/dotnet/standard/garbage-collection/implementing-dispose). protected virtual void Dispose(bool disposing) { if (disposing && !_isDisposed) @@ -307,25 +325,30 @@ protected virtual void Dispose(bool disposing) } } - /// - /// Finishes writing the archive and releases all resources used by the ZipArchive object, unless the object was constructed with leaveOpen as true. Any streams from opened entries in the ZipArchive still open will throw exceptions on subsequent writes, as the underlying streams will have been closed. - /// + /// Releases the resources used by the current instance of the class. + /// This method finishes writing the archive and releases all resources used by the object. Unless you construct the object by using the constructor overload and set its `leaveOpen` parameter to , all underlying streams are closed and no longer available for subsequent write operations. + /// When you are finished using this instance of , call to release all resources used by this instance. You should eliminate further references to this instance so that the garbage collector can reclaim the memory of the instance instead of keeping it alive for finalization. + /// calls the method, which contains the code to release managed and unmanaged resources. For more information, see [Implementing a Dispose method](/dotnet/standard/garbage-collection/implementing-dispose). public void Dispose() { Dispose(true); GC.SuppressFinalize(this); } - /// - /// Retrieves a wrapper for the file entry in the archive with the specified name. Names are compared using ordinal comparison. If there are multiple entries in the archive with the specified name, the first one found will be returned. - /// - /// entryName is a zero-length string. - /// entryName is null. - /// The ZipArchive does not support reading. - /// The ZipArchive has already been closed. - /// The Zip archive is corrupt and the entries cannot be retrieved. - /// A path relative to the root of the archive, identifying the desired entry. - /// A wrapper for the file entry in the archive. If no entry in the archive exists with the specified name, null will be returned. + /// Retrieves a wrapper for the specified entry in the zip archive. + /// A path, relative to the root of the archive, that identifies the entry to retrieve. + /// A wrapper for the specified entry in the archive; if the entry does not exist in the archive. + /// If multiple entries that have the specified name exist in the archive, the first one is returned. The name of the entry is compared to using ordinal comparison. + /// The following example shows how to use the method to retrieve an entry. + /// + /// is . + /// is . + /// The zip archive does not support reading. + /// The zip archive has been disposed. + /// The zip archive is corrupt, and its entries cannot be retrieved. public ZipArchiveEntry? GetEntry(string entryName) { if (entryName == null) From 35c4164f8bb58723a75b8060e9fa778ee90b6f16 Mon Sep 17 00:00:00 2001 From: carlossanlop Date: Thu, 25 Feb 2021 15:49:04 -0800 Subject: [PATCH 06/18] ZipArchiveEntry --- .../System/IO/Compression/ZipArchiveEntry.cs | 147 ++++++++++++------ 1 file changed, 102 insertions(+), 45 deletions(-) diff --git a/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveEntry.cs b/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveEntry.cs index 100a61b270bb4a..dd7044586a3393 100644 --- a/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveEntry.cs +++ b/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveEntry.cs @@ -8,7 +8,29 @@ namespace System.IO.Compression { - // The disposable fields that this class owns get disposed when the ZipArchive it belongs to gets disposed + /// Represents a compressed file within a zip archive. + /// A zip archive contains an entry for each compressed file. The class enables you to examine the properties of an entry, and open or delete the entry. When you open an entry, you can modify the compressed file by writing to the stream for that compressed file. + /// The methods for manipulating zip archives and their file entries are spread across three classes: , and . + /// |To...|Use...| + /// |---------|----------| + /// |Create a zip archive from a directory|| + /// |Extract the contents of a zip archive to a directory|| + /// |Add new files to an existing zip archive|| + /// |Retrieve an file in a zip archive|| + /// |Retrieve all of the files in a zip archive|| + /// |To open a stream to an individual file contained in a zip archive|| + /// |Delete a file from a zip archive|| + /// If you reference the `System.IO.Compression.FileSystem` assembly in your project, you can access two extension methods for the class. Those methods are and , and they enable you to decompress the contents of the entry to a file. The `System.IO.Compression.FileSystem` assembly is not available in Windows 8. In Windows 8.x Store apps, you can decompress the contents of an archive by using or , or you can use the Windows Runtime types Compressor](https://go.microsoft.com/fwlink/p/?LinkId=246357) and [Decompressor to compress and decompress files. + /// The first example shows how to create a new entry in a zip archive and write to it. + /// + /// The second example shows how to use the extension method. You must reference the `System.IO.Compression.FileSystem` assembly in your project for the code to execute. + /// public partial class ZipArchiveEntry { // The maximum index of our buffers, from the maximum index of a byte array @@ -139,18 +161,24 @@ internal ZipArchiveEntry(ZipArchive archive, string entryName) } } - /// - /// The ZipArchive that this entry belongs to. If this entry has been deleted, this will return null. - /// + /// Gets the zip archive that the entry belongs to. + /// The zip archive that the entry belongs to, or if the entry has been deleted. public ZipArchive Archive => _archive; + /// The 32-bit Cyclic Redundant Check. + /// An unsigned integer (4 bytes) representing the CRC-32 field. [CLSCompliant(false)] public uint Crc32 => _crc32; - /// - /// The compressed size of the entry. If the archive that the entry belongs to is in Create mode, attempts to get this property will always throw an exception. If the archive that the entry belongs to is in update mode, this property will only be valid if the entry has not been opened. - /// - /// This property is not available because the entry has been written to or modified. + /// Gets the compressed size of the entry in the zip archive. + /// The compressed size of the entry in the zip archive. + /// This property cannot be retrieved when the mode is set to , or the mode is set to and the entry has been opened. + /// The following example shows how to retrieve entries in a zip archive, and evaluate the properties of the entries. It uses the property to display the name of the entry, and the and properties to calculate how much the file was compressed. + /// + /// The value of the property is not available because the entry has been modified. public long CompressedLength { get @@ -161,6 +189,9 @@ public long CompressedLength } } + /// OS and application specific file attributes. + /// The external attributes written by the application when this entry was written. It is both host OS and application dependent. + /// The mapping of the external attributes is host-system dependent. For MS-DOS, the low order byte is the MS-DOS directory attribute byte. For Unix, the high Order byte is frequently used to store the file permissions. If input came from standard input, this field is set to zero. public int ExternalAttributes { get @@ -174,9 +205,15 @@ public int ExternalAttributes } } - /// - /// The relative path of the entry as stored in the Zip archive. Note that Zip archives allow any string to be the path of the entry, including invalid and absolute paths. - /// + /// Gets the relative path of the entry in the zip archive. + /// The relative path of the entry in the zip archive. + /// The property contains the relative path, including the subdirectory hierarchy, of an entry in a zip archive. (In contrast, the property contains only the name of the entry and does not include the subdirectory hierarchy.) For example, if you create two entries in a zip archive by using the method and provide `NewEntry.txt` as the name for the first entry and `AddedFolder\\NewEntry.txt` for the second entry, both entries will have `NewEntry.txt` in the property. The first entry will also have `NewEntry.txt` in the property, but the second entry will have `AddedFolder\\NewEntry.txt` in the property. + /// You can specify any string as the path of an entry, including strings that specify invalid and absolute paths. Therefore, the property might contain a value that is not correctly formatted. An invalid or absolute path might result in an exception when you extract the contents of the zip archive. + /// The following example shows how to iterate through the contents of a .zip file, and extract files that contain the .txt extension. + /// public string FullName { get @@ -205,16 +242,20 @@ private set } } - /// - /// The last write time of the entry as stored in the Zip archive. When setting this property, the DateTime will be converted to the - /// Zip timestamp format, which supports a resolution of two seconds. If the data in the last write time field is not a valid Zip timestamp, - /// an indicator value of 1980 January 1 at midnight will be returned. - /// - /// An attempt to set this property was made, but the ZipArchive that this entry belongs to was - /// opened in read-only mode. - /// An attempt was made to set this property to a value that cannot be represented in the - /// Zip timestamp format. The earliest date/time that can be represented is 1980 January 1 0:00:00 (midnight), and the last date/time - /// that can be represented is 2107 December 31 23:59:58 (one second before midnight). + /// Gets or sets the last time the entry in the zip archive was changed. + /// The last time the entry in the zip archive was changed. + /// When you create a new entry from an existing file by calling the method, the property for the entry is automatically set to the last time the file was modified. When you create a new entry programmatically by calling the method, the property for the entry is automatically set to the time of execution. If you modify the entry, you must explicitly set the property if you want the value to reflect the time of the latest change. + /// When you set this property, the value is converted to a timestamp format that is specific to zip archives. This format supports a resolution of two seconds. The earliest permitted value is 1980 January 1 0:00:00 (midnight). The latest permitted value is 2107 December 31 23:59:58 (one second before midnight). If the value for the last write time is not valid, the property returns a default value of 1980 January 1 0:00:00 (midnight). + /// The following example shows how to open an entry in a zip archive, modify it, and set the property to the current time. + /// + /// The attempt to set this property failed, because the zip archive for the entry is in mode. + /// The archive mode is set to . + /// -or- + /// The archive mode is set to and the entry has been opened. + /// An attempt was made to set this property to a value that is either earlier than 1980 January 1 0:00:00 (midnight) or later than 2107 December 31 23:59:58 (one second before midnight). public DateTimeOffset LastWriteTime { get @@ -235,10 +276,15 @@ public DateTimeOffset LastWriteTime } } - /// - /// The uncompressed size of the entry. This property is not valid in Create mode, and it is only valid in Update mode if the entry has not been opened. - /// - /// This property is not available because the entry has been written to or modified. + /// Gets the uncompressed size of the entry in the zip archive. + /// The uncompressed size of the entry in the zip archive. + /// This property cannot be retrieved when the mode is set to , or the mode is set to and the entry has been opened. + /// The following example shows how to retrieve entries from a zip archive, and evaluate the properties of the entries. It uses the property to display the name of the entry, and the and properties to calculate how much the file was compressed. + /// + /// The value of the property is not available because the entry has been modified. public long Length { get @@ -249,17 +295,20 @@ public long Length } } - /// - /// The filename of the entry. This is equivalent to the substring of Fullname that follows the final directory separator character. - /// + /// Gets the file name of the entry in the zip archive. + /// The file name of the entry in the zip archive. + /// The property contains the portion of the property that follows the final directory separator character (\\), and does not include the subdirectory hierarchy. For example, if you create two entries in a zip archive by using the method and provide `NewEntry.txt` as the name for the first entry and `AddedFolder\\NewEntry.txt` for the second entry, both entries will have `NewEntry.txt` in the property. The first entry will also have `NewEntry.txt` in the property, but the second entry will have `AddedFolder\\NewEntry.txt` in the property. + /// The following example shows how to retrieve entries from a zip archive and evaluate the properties of the entries. It uses the property to display the name of the entry, and the and properties to calculate how much the file was compressed. + /// public string Name => ParseFileName(FullName, _versionMadeByPlatform); - /// - /// Deletes the entry from the archive. - /// - /// The entry is already open for reading or writing. - /// The ZipArchive that this entry belongs to was opened in a mode other than ZipArchiveMode.Update. - /// The ZipArchive that this entry belongs to has been disposed. + /// Deletes the entry from the zip archive. + /// The entry is already open for reading or writing. + /// The zip archive for this entry was opened in a mode other than . + /// The zip archive for this entry has been disposed. public void Delete() { if (_archive == null) @@ -278,13 +327,23 @@ public void Delete() UnloadStreams(); } - /// - /// Opens the entry. If the archive that the entry belongs to was opened in Read mode, the returned stream will be readable, and it may or may not be seekable. If Create mode, the returned stream will be writable and not seekable. If Update mode, the returned stream will be readable, writable, seekable, and support SetLength. - /// - /// A Stream that represents the contents of the entry. - /// The entry is already currently open for writing. -or- The entry has been deleted from the archive. -or- The archive that this entry belongs to was opened in ZipArchiveMode.Create, and this entry has already been written to once. - /// The entry is missing from the archive or is corrupt and cannot be read. -or- The entry has been compressed using a compression method that is not supported. - /// The ZipArchive that this entry belongs to has been disposed. + /// Opens the entry from the zip archive. + /// The stream that represents the contents of the entry. + /// You use this method to access the stream for an entry in a zip archive. After retrieving the stream, you can read from or write to the stream. When you write to the stream, the modifications you make to the entry will appear in the zip archive. + /// The following example shows how to create a new entry, open it with the method, and write to the stream. + /// + /// The entry is already currently open for writing. + /// -or- + /// The entry has been deleted from the archive. + /// -or- + /// The archive for this entry was opened with the mode, and this entry has already been written to. + /// The entry is either missing from the archive or is corrupt and cannot be read. + /// -or- + /// The entry has been compressed by using a compression method that is not supported. + /// The zip archive for this entry has been disposed. public Stream Open() { ThrowIfInvalidArchive(); @@ -302,10 +361,8 @@ public Stream Open() } } - /// - /// Returns the FullName of the entry. - /// - /// FullName of the entry + /// Retrieves the relative path of the entry in the zip archive. + /// The relative path of the entry, which is the value stored in the property. public override string ToString() { return FullName; From c3e5092f2b492df1157bc2cdba6f8342c4dd683a Mon Sep 17 00:00:00 2001 From: carlossanlop Date: Thu, 25 Feb 2021 15:49:12 -0800 Subject: [PATCH 07/18] ZipArchiveEntry.Windows --- .../IO/Compression/ZipArchiveEntry.Windows.cs | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveEntry.Windows.cs b/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveEntry.Windows.cs index 730ade4b35081c..bfb1d9ea8c598c 100644 --- a/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveEntry.Windows.cs +++ b/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveEntry.Windows.cs @@ -3,6 +3,29 @@ namespace System.IO.Compression { + /// Represents a compressed file within a zip archive. + /// A zip archive contains an entry for each compressed file. The class enables you to examine the properties of an entry, and open or delete the entry. When you open an entry, you can modify the compressed file by writing to the stream for that compressed file. + /// The methods for manipulating zip archives and their file entries are spread across three classes: , and . + /// |To...|Use...| + /// |---------|----------| + /// |Create a zip archive from a directory|| + /// |Extract the contents of a zip archive to a directory|| + /// |Add new files to an existing zip archive|| + /// |Retrieve an file in a zip archive|| + /// |Retrieve all of the files in a zip archive|| + /// |To open a stream to an individual file contained in a zip archive|| + /// |Delete a file from a zip archive|| + /// If you reference the `System.IO.Compression.FileSystem` assembly in your project, you can access two extension methods for the class. Those methods are and , and they enable you to decompress the contents of the entry to a file. The `System.IO.Compression.FileSystem` assembly is not available in Windows 8. In Windows 8.x Store apps, you can decompress the contents of an archive by using or , or you can use the Windows Runtime types Compressor](https://go.microsoft.com/fwlink/p/?LinkId=246357) and [Decompressor to compress and decompress files. + /// The first example shows how to create a new entry in a zip archive and write to it. + /// + /// The second example shows how to use the extension method. You must reference the `System.IO.Compression.FileSystem` assembly in your project for the code to execute. + /// public partial class ZipArchiveEntry { internal const ZipVersionMadeByPlatform CurrentZipPlatform = ZipVersionMadeByPlatform.Windows; From e7bc9f2e71445af55c4a48ad4c2dc9ba94e9c255 Mon Sep 17 00:00:00 2001 From: carlossanlop Date: Thu, 25 Feb 2021 15:49:18 -0800 Subject: [PATCH 08/18] ZipArchiveMode --- .../System/IO/Compression/ZipArchiveMode.cs | 35 +++++++++---------- 1 file changed, 16 insertions(+), 19 deletions(-) diff --git a/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveMode.cs b/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveMode.cs index 9119fc1a9aba90..bcc9734f5bc23b 100644 --- a/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveMode.cs +++ b/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveMode.cs @@ -3,29 +3,26 @@ namespace System.IO.Compression { + /// Specifies values for interacting with zip archive entries. + /// When you set the mode to Read, the underlying file or stream must support reading, but does not have to support seeking. If the underlying file or stream supports seeking, the files are read from the archive as they are requested. If the underlying file or stream does not support seeking, the entire archive is held in memory. + /// When you set the mode to Create, the underlying file or stream must support writing, but does not have to support seeking. Each entry in the archive can be opened only once for writing. If you create a single entry, the data is written to the underlying stream or file as soon as it is available. If you create multiple entries, such as by calling the method, the data is written to the underlying stream or file after all the entries are created. + /// When you set the mode to Update, the underlying file or stream must support reading, writing, and seeking. The content of the entire archive is held in memory, and no data is written to the underlying file or stream until the archive is disposed. + /// The following methods include a parameter named `mode` that lets you specify the archive mode: + /// - + /// - + /// - + /// The following example shows how to specify a `ZipArchiveMode` value when creating a object. + /// public enum ZipArchiveMode { - /// - /// Only reading entries from the archive is permitted. - /// If the underlying file or stream is seekable, then files will be read from the archive on-demand as they are requested. - /// If the underlying file or stream is not seekable, the entire archive will be held in memory. - /// Requires that the underlying file or stream is readable. - /// + /// Only reading archive entries is permitted. Read, - /// - /// Only supports the creation of new archives. - /// Only writing to newly created entries in the archive is permitted. - /// Each entry in the archive can only be opened for writing once. - /// If only one entry is written to at a time, data will be written to the underlying stream or file as soon as it is available. - /// The underlying stream must be writable, but need not be seekable. - /// + /// Only creating new archive entries is permitted. Create, - /// - /// Reading and writing from entries in the archive is permitted. - /// Requires that the contents of the entire archive be held in memory. - /// The underlying file or stream must be readable, writable and seekable. - /// No data will be written to the underlying file or stream until the archive is disposed. - /// + /// Both read and write operations are permitted for archive entries. Update } } From d113f4b6945ea1701c78b84611dd8ebc5f8a307e Mon Sep 17 00:00:00 2001 From: carlossanlop Date: Thu, 25 Feb 2021 16:26:24 -0800 Subject: [PATCH 09/18] Remove duplicate or inexistent parameters. Use langword for APIs that cannot be referenced. Add O: prefix to method overloads. --- .../Compression/DeflateZLib/DeflateStream.cs | 60 ++++++++----------- 1 file changed, 26 insertions(+), 34 deletions(-) diff --git a/src/libraries/System.IO.Compression/src/System/IO/Compression/DeflateZLib/DeflateStream.cs b/src/libraries/System.IO.Compression/src/System/IO/Compression/DeflateZLib/DeflateStream.cs index 0e07b82410c90c..41c63d6c95b7d1 100644 --- a/src/libraries/System.IO.Compression/src/System/IO/Compression/DeflateZLib/DeflateStream.cs +++ b/src/libraries/System.IO.Compression/src/System/IO/Compression/DeflateZLib/DeflateStream.cs @@ -86,7 +86,7 @@ public DeflateStream(Stream stream, CompressionMode mode, bool leaveOpen) : this /// The stream to compress. /// One of the enumeration values that indicates whether to emphasize speed or compression efficiency when compressing the stream. /// You use this constructor when you want to specify whether compression efficiency or speed is more important for an instance of the class. - /// This constructor overload uses the compression mode . To set the compression mode to another value, use the or overload. + /// This constructor overload uses the compression mode . To set the compression mode to another value, use the or overload. /// The following example shows how to set the compression level when creating a object. /// One of the enumeration values that indicates whether to emphasize speed or compression efficiency when compressing the stream. /// to leave the stream object open after disposing the object; otherwise, . /// You use this constructor when you want to specify whether compression efficiency or speed is more important for an instance of the class, and whether to leave the stream object open after disposing the object. - /// This constructor overload uses the compression mode . To set the compression mode to another value, use the or overload. + /// This constructor overload uses the compression mode . To set the compression mode to another value, use the or overload. /// The following example shows how to set the compression level when creating a object and how to leave the stream open. /// Reads a number of decompressed bytes into the specified byte array. - /// The array to store decompressed bytes. - /// The byte offset in at which the read bytes will be placed. + /// The array to store decompressed bytes. + /// The byte offset in at which the read bytes will be placed. /// The maximum number of decompressed bytes to read. /// The number of bytes that were read into the byte array. /// - /// The following example shows how to compress and decompress bytes by using the and methods. + /// The following example shows how to compress and decompress bytes by using the and methods. /// - /// is . + /// is . /// The value was when the object was created. /// -or- /// The underlying stream does not support reading. /// or is less than zero. /// -or- - /// length minus the index starting point is less than . + /// length minus the index starting point is less than . /// The data is in an invalid format. /// The stream is closed. public override int Read(byte[] buffer, int offset, int count) @@ -365,7 +365,7 @@ public override int Read(byte[] buffer, int offset, int count) /// Reads a sequence of bytes from the current Deflate stream into a byte span and advances the position within the Deflate stream by the number of bytes read. /// A region of memory. When this method returns, the contents of this region are replaced by the bytes read from the current source. /// The total number of bytes read into the buffer. This can be less than the number of bytes allocated in the buffer if that many bytes are not currently available, or zero (0) if the end of the stream has been reached. - /// Use the property to determine whether the current instance supports reading. Use the method to read asynchronously from the current stream. + /// Use the property to determine whether the current instance supports reading. Use the method to read asynchronously from the current stream. /// This method read a maximum of `buffer.Length` bytes from the current stream and store them in . The current position within the Deflate stream is advanced by the number of bytes read; however, if an exception occurs, the current position within the Deflate stream remains unchanged. This method will block until at least one byte of data can be read, in the event that no data is available. `Read` returns 0 only when there is no more data in the stream and no more is expected (such as a closed socket or end of file). The method is free to return fewer bytes than requested even if the end of the stream has not been reached. /// Use for reading primitive data types. public override int Read(Span buffer) @@ -467,15 +467,12 @@ private static void ThrowCannotWriteToDeflateStreamException() /// Begins an asynchronous read operation. (Consider using the method instead.) /// The byte array to read the data into. - /// The byte array to read the data into. - /// The byte offset in at which to begin reading data from the stream. + /// The byte offset in at which to begin reading data from the stream. /// The maximum number of bytes to read. /// An optional asynchronous callback, to be called when the read operation is complete. - /// An optional asynchronous callback, to be called when the read operation is complete. /// A user-provided object that distinguishes this particular asynchronous read request from other requests. - /// A user-provided object that distinguishes this particular asynchronous read request from other requests. /// An object that represents the asynchronous read operation, which could still be pending. - /// Starting with the .NET Framework 4.5, you can perform asynchronous read operations by using the method. The method is still available in the .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). + /// Starting with the .NET Framework 4.5, you can perform asynchronous read operations by using the method. The method is still available in the .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). /// Pass the return value to the method of the stream to determine how many bytes were read and to release operating system resources used for reading. You can do this either by using the same code that called or in a callback passed to . /// The current position in the stream is updated when the asynchronous read or write operation is issued, not when the I/O operation completes. /// Multiple simultaneous asynchronous requests render the request completion order uncertain. @@ -491,14 +488,13 @@ public override IAsyncResult BeginRead(byte[] buffer, int offset, int count, Asy /// Waits for the pending asynchronous read to complete. (Consider using the method instead.) /// The reference to the pending asynchronous request to finish. - /// The reference to the pending asynchronous request to finish. /// The number of bytes read from the stream, between 0 (zero) and the number of bytes you requested. returns 0 only at the end of the stream; otherwise, it blocks until at least one byte is available. - /// Starting with the .NET Framework 4.5, you can perform asynchronous read operations by using the method. The method is still available in the .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). + /// Starting with the .NET Framework 4.5, you can perform asynchronous read operations by using the method. The method is still available in the .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). /// Call this method to determine how many bytes were read from the stream. This method can be called once to return the amount of bytes read between calls to and . /// This method blocks until the I/O operation has completed. /// is . /// did not originate from a method on the current stream. - /// An exception was thrown during a call to . + /// An exception was thrown during a call to . /// The end call is invalid because asynchronous read operations for this stream are not yet complete. /// -or- /// The stream is . @@ -510,11 +506,11 @@ public override int EndRead(IAsyncResult asyncResult) } /// Asynchronously reads a sequence of bytes from the current Deflate stream, writes them to a byte array, advances the position within the Deflate stream by the number of bytes read, and monitors cancellation requests. - /// The buffer to write the data into. - /// The byte offset in at which to begin writing data from the Deflate stream. + /// The buffer to write the data into. + /// The byte offset in at which to begin writing data from the Deflate stream. /// The maximum number of bytes to read. /// The token to monitor for cancellation requests. The default value is . - /// A task that represents the asynchronous read operation, which wraps the total number of bytes read into the . The result value can be less than the number of bytes requested if the number of bytes currently available is less than the requested number, or it can be 0 (zero) if the end of the Deflate stream has been reached. + /// A task that represents the asynchronous read operation, which wraps the total number of bytes read into the . The result value can be less than the number of bytes requested if the number of bytes currently available is less than the requested number, or it can be 0 (zero) if the end of the Deflate stream has been reached. /// The `ReadAsync` method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the and keywords in Visual Basic and C#. /// Use the property to determine whether the current instance supports reading. /// If the operation is canceled before it completes, the returned task contains the value for the property. @@ -616,11 +612,11 @@ async ValueTask Core(Memory buffer, CancellationToken cancellationTok } /// Writes compressed bytes to the underlying stream from the specified byte array. - /// The buffer that contains the data to compress. - /// The byte offset in from which the bytes will be read. + /// The buffer that contains the data to compress. + /// The byte offset in from which the bytes will be read. /// The maximum number of bytes to write. /// - /// The following example shows how to compress and decompress bytes by using the and methods. + /// The following example shows how to compress and decompress bytes by using the and methods. /// Writes a sequence of bytes to the current Deflate stream and advances the current position within this Deflate stream by the number of bytes written. /// A region of memory. This method copies the contents of this region to the current Deflate stream. - /// Use the property to determine whether the current instance supports writing. Use the method to write asynchronously to the current stream. + /// Use the property to determine whether the current instance supports writing. Use the method to write asynchronously to the current stream. /// If the write operation is successful, the position within the Deflate stream advances by the number of bytes written. If an exception occurs, the position within the Deflate stream remains unchanged. public override void Write(ReadOnlySpan buffer) { @@ -811,8 +807,8 @@ private async ValueTask PurgeBuffersAsync() /// Releases the unmanaged resources used by the and optionally releases the managed resources. /// to release both managed and unmanaged resources; to release only unmanaged resources. - /// This method is called by the public method and the method. invokes the protected method with the parameter set to . invokes with set to . - /// When the parameter is , this method releases all resources held by any managed objects that this references. This method invokes the method of each referenced object. + /// This method is called by the public method and the method. invokes the protected method with the parameter set to . invokes with set to . + /// When the parameter is , this method releases all resources held by any managed objects that this references. This method invokes the method of each referenced object. protected override void Dispose(bool disposing) { try @@ -917,16 +913,13 @@ async ValueTask Core() } /// Begins an asynchronous write operation. (Consider using the method instead.) - /// The buffer to write data from. /// The buffer to write data from. /// The byte offset in to begin writing from. /// The maximum number of bytes to write. /// An optional asynchronous callback, to be called when the write operation is complete. - /// An optional asynchronous callback, to be called when the write operation is complete. /// A user-provided object that distinguishes this particular asynchronous write request from other requests. - /// A user-provided object that distinguishes this particular asynchronous write request from other requests. /// An object that represents the asynchronous write operation, which could still be pending. - /// Starting with the .NET Framework 4.5, you can perform asynchronous write operations by using the method. The method is still available in the .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). + /// Starting with the .NET Framework 4.5, you can perform asynchronous write operations by using the method. The method is still available in the .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). /// Pass the object returned by the current method to to ensure that the write completes and frees resources appropriately. You can do this either by using the same code that called or in a callback passed to . If an error occurs during an asynchronous write operation, an exception will not be thrown until is called with the returned by this method. /// If a stream is writable, writing at the end of the stream expands the stream. /// The current position in the stream is updated when you issue the asynchronous read or write operation, not when the I/O operation completes. Multiple simultaneous asynchronous requests render the request completion order uncertain. @@ -942,13 +935,12 @@ public override IAsyncResult BeginWrite(byte[] buffer, int offset, int count, As /// Ends an asynchronous write operation. (Consider using the method instead.) /// A reference to the outstanding asynchronous I/O request. - /// A reference to the outstanding asynchronous I/O request. - /// Starting with the .NET Framework 4.5, you can perform asynchronous write operations by using the method. The method is still available in the .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). + /// Starting with the .NET Framework 4.5, you can perform asynchronous write operations by using the method. The method is still available in the .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). /// must be called only once for every call to the method. /// This method blocks until the I/O operation has completed. Errors that occur during an asynchronous write request, such as a disk failure during the I/O request, occur on the thread pool thread and become visible upon a call to . Exceptions thrown by the thread pool thread will not be visible when calling . /// is . /// did not originate from a method on the current stream. - /// An exception was thrown during a call to . + /// An exception was thrown during a call to . /// The stream is . /// -or- /// The end write call is invalid. @@ -960,8 +952,8 @@ public override void EndWrite(IAsyncResult asyncResult) } /// Asynchronously writes compressed bytes to the underlying Deflate stream from the specified byte array. - /// The buffer that contains the data to compress. - /// The zero-based byte offset in from which to begin copying bytes to the Deflate stream. + /// The buffer that contains the data to compress. + /// The zero-based byte offset in from which to begin copying bytes to the Deflate stream. /// The maximum number of bytes to write. /// The token to monitor for cancellation requests. The default value is . /// A task that represents the asynchronous write operation. From c5cc992975028dfa698742606f72be3f4643aeab Mon Sep 17 00:00:00 2001 From: carlossanlop Date: Thu, 25 Feb 2021 16:29:31 -0800 Subject: [PATCH 10/18] Use langwords for APIs that cannot be referenced. --- .../System/IO/Compression/CompressionLevel.cs | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/src/libraries/System.IO.Compression/src/System/IO/Compression/CompressionLevel.cs b/src/libraries/System.IO.Compression/src/System/IO/Compression/CompressionLevel.cs index 99f184d35f241b..ec2f9dd55489a5 100644 --- a/src/libraries/System.IO.Compression/src/System/IO/Compression/CompressionLevel.cs +++ b/src/libraries/System.IO.Compression/src/System/IO/Compression/CompressionLevel.cs @@ -5,15 +5,15 @@ namespace System.IO.Compression { /// Specifies values that indicate whether a compression operation emphasizes speed or compression size. /// Compression operations usually involve a tradeoff between the speed and the effectiveness of compression. You use the enumeration to indicate which factor is more important in your development scenario: the time to complete the compression operation or the size of the compressed file. These values do not correspond to specific compression levels; the object that implements compression determines how to handle them. - /// The following methods of the , , , , and classes include a parameter named `compressionLevel` that lets you specify the compression level: - /// - - /// - - /// - - /// - - /// - - /// - - /// - - /// The following example shows how to set the compression level when creating a zip archive by using the class. + /// The following methods of the , , , , and classes include a parameter named `compressionLevel` that lets you specify the compression level: + /// - + /// - + /// - + /// - + /// - + /// - + /// - + /// The following example shows how to set the compression level when creating a zip archive by using the class. /// Date: Thu, 25 Feb 2021 16:40:27 -0800 Subject: [PATCH 11/18] DeflateStream unresolved hyperlinks in xml. --- .../System/IO/Compression/DeflateZLib/DeflateStream.cs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/libraries/System.IO.Compression/src/System/IO/Compression/DeflateZLib/DeflateStream.cs b/src/libraries/System.IO.Compression/src/System/IO/Compression/DeflateZLib/DeflateStream.cs index 41c63d6c95b7d1..60b82f22b95380 100644 --- a/src/libraries/System.IO.Compression/src/System/IO/Compression/DeflateZLib/DeflateStream.cs +++ b/src/libraries/System.IO.Compression/src/System/IO/Compression/DeflateZLib/DeflateStream.cs @@ -472,7 +472,7 @@ private static void ThrowCannotWriteToDeflateStreamException() /// An optional asynchronous callback, to be called when the read operation is complete. /// A user-provided object that distinguishes this particular asynchronous read request from other requests. /// An object that represents the asynchronous read operation, which could still be pending. - /// Starting with the .NET Framework 4.5, you can perform asynchronous read operations by using the method. The method is still available in the .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). + /// Starting with the .NET Framework 4.5, you can perform asynchronous read operations by using the method. The method is still available in the .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see Asynchronous File I/O. /// Pass the return value to the method of the stream to determine how many bytes were read and to release operating system resources used for reading. You can do this either by using the same code that called or in a callback passed to . /// The current position in the stream is updated when the asynchronous read or write operation is issued, not when the I/O operation completes. /// Multiple simultaneous asynchronous requests render the request completion order uncertain. @@ -489,7 +489,7 @@ public override IAsyncResult BeginRead(byte[] buffer, int offset, int count, Asy /// Waits for the pending asynchronous read to complete. (Consider using the method instead.) /// The reference to the pending asynchronous request to finish. /// The number of bytes read from the stream, between 0 (zero) and the number of bytes you requested. returns 0 only at the end of the stream; otherwise, it blocks until at least one byte is available. - /// Starting with the .NET Framework 4.5, you can perform asynchronous read operations by using the method. The method is still available in the .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). + /// Starting with the .NET Framework 4.5, you can perform asynchronous read operations by using the method. The method is still available in the .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see Asynchronous File I/O. /// Call this method to determine how many bytes were read from the stream. This method can be called once to return the amount of bytes read between calls to and . /// This method blocks until the I/O operation has completed. /// is . @@ -919,7 +919,7 @@ async ValueTask Core() /// An optional asynchronous callback, to be called when the write operation is complete. /// A user-provided object that distinguishes this particular asynchronous write request from other requests. /// An object that represents the asynchronous write operation, which could still be pending. - /// Starting with the .NET Framework 4.5, you can perform asynchronous write operations by using the method. The method is still available in the .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). + /// Starting with the .NET Framework 4.5, you can perform asynchronous write operations by using the method. The method is still available in the .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see Asynchronous File I/O. /// Pass the object returned by the current method to to ensure that the write completes and frees resources appropriately. You can do this either by using the same code that called or in a callback passed to . If an error occurs during an asynchronous write operation, an exception will not be thrown until is called with the returned by this method. /// If a stream is writable, writing at the end of the stream expands the stream. /// The current position in the stream is updated when you issue the asynchronous read or write operation, not when the I/O operation completes. Multiple simultaneous asynchronous requests render the request completion order uncertain. @@ -935,7 +935,7 @@ public override IAsyncResult BeginWrite(byte[] buffer, int offset, int count, As /// Ends an asynchronous write operation. (Consider using the method instead.) /// A reference to the outstanding asynchronous I/O request. - /// Starting with the .NET Framework 4.5, you can perform asynchronous write operations by using the method. The method is still available in the .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). + /// Starting with the .NET Framework 4.5, you can perform asynchronous write operations by using the method. The method is still available in the .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see Asynchronous File I/O. /// must be called only once for every call to the method. /// This method blocks until the I/O operation has completed. Errors that occur during an asynchronous write request, such as a disk failure during the I/O request, occur on the thread pool thread and become visible upon a call to . Exceptions thrown by the thread pool thread will not be visible when calling . /// is . From 9ded70b4c2ab263dd9211752fc526b6815ad401d Mon Sep 17 00:00:00 2001 From: carlossanlop Date: Thu, 25 Feb 2021 16:41:45 -0800 Subject: [PATCH 12/18] GZipStream #ctor to actual method, array param to buffer, unresolved hyperlinks in xml, overload crefs, --- .../src/System/IO/Compression/GZipStream.cs | 58 ++++++++----------- 1 file changed, 25 insertions(+), 33 deletions(-) diff --git a/src/libraries/System.IO.Compression/src/System/IO/Compression/GZipStream.cs b/src/libraries/System.IO.Compression/src/System/IO/Compression/GZipStream.cs index 225f3c3b34d85b..c1e753ce9a2a3c 100644 --- a/src/libraries/System.IO.Compression/src/System/IO/Compression/GZipStream.cs +++ b/src/libraries/System.IO.Compression/src/System/IO/Compression/GZipStream.cs @@ -64,7 +64,7 @@ public GZipStream(Stream stream, CompressionMode mode, bool leaveOpen) /// The stream to compress. /// One of the enumeration values that indicates whether to emphasize speed or compression efficiency when compressing the stream. /// You use this constructor when you want to specify whether compression efficiency or speed is more important for an instance of the class. - /// This constructor overload uses the compression mode . To set the compression mode to another value, use the or overload. + /// This constructor overload uses the compression mode . To set the compression mode to another value, use the or overload. /// The following example shows how to set the compression level when creating a object. /// One of the enumeration values that indicates whether to emphasize speed or compression efficiency when compressing the stream. /// to leave the stream object open after disposing the object; otherwise, . /// You use this constructor when you want to specify whether compression efficiency or speed is more important for an instance of the class, and whether to leave the stream object open after disposing the object. - /// This constructor overload uses the compression mode . To set the compression mode to another value, use the or overload. + /// This constructor overload uses the compression mode . To set the compression mode to another value, use the or overload. /// The following example shows how to set the compression level when creating a object and how to leave the stream open. /// Begins an asynchronous read operation. (Consider using the method instead.) - /// The byte array to read the data into. /// The byte array to read the data into. - /// The byte offset in at which to begin reading data from the stream. + /// The byte offset in at which to begin reading data from the stream. /// The maximum number of bytes to read. /// An optional asynchronous callback, to be called when the read operation is complete. - /// An optional asynchronous callback, to be called when the read operation is complete. /// A user-provided object that distinguishes this particular asynchronous read request from other requests. - /// A user-provided object that distinguishes this particular asynchronous read request from other requests. /// An object that represents the asynchronous read operation, which could still be pending. - /// Starting with the .NET Framework 4.5, you can perform asynchronous read operations by using the method. The method is still available in .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). + /// Starting with the .NET Framework 4.5, you can perform asynchronous read operations by using the method. The method is still available in .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see Asynchronous File I/O. /// Pass the return value to the method of the stream to determine how many bytes were read and to release operating system resources used for reading. You can do this either by using the same code that called or in a callback passed to . /// The current position in the stream is updated when the asynchronous read or write is issued, not when the I/O operation completes. /// Multiple simultaneous asynchronous requests render the request completion order uncertain. @@ -191,9 +188,8 @@ public override IAsyncResult BeginRead(byte[] buffer, int offset, int count, Asy /// Waits for the pending asynchronous read to complete. (Consider using the method instead.) /// The reference to the pending asynchronous request to finish. - /// The reference to the pending asynchronous request to finish. /// The number of bytes read from the stream, between 0 (zero) and the number of bytes you requested. returns 0 only at the end of the stream; otherwise, it blocks until at least one byte is available. - /// Starting with the .NET Framework 4.5, you can perform asynchronous read operations by using the method. The method is still available in .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). + /// Starting with the .NET Framework 4.5, you can perform asynchronous read operations by using the method. The method is still available in .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see Asynchronous File I/O. /// Call this method to determine how many bytes were read from the stream. This method can be called once to return the amount of bytes read between calls to and . /// This method blocks until the I/O operation has completed. /// The following code example shows how to use the class to compress and decompress a file. @@ -208,23 +204,23 @@ public override int EndRead(IAsyncResult asyncResult) => _deflateStream.EndRead(asyncResult); /// Reads a number of decompressed bytes into the specified byte array. - /// The array used to store decompressed bytes. - /// The byte offset in at which the read bytes will be placed. + /// The array used to store decompressed bytes. + /// The byte offset in at which the read bytes will be placed. /// The maximum number of decompressed bytes to read. /// The number of bytes that were decompressed into the byte array. If the end of the stream has been reached, zero or the number of bytes read is returned. /// If data is found in an invalid format, an is thrown as one of the last operations. A cyclic redundancy check (CRC) is performed as one of the last operations of this method. - /// The following example shows how to compress and decompress bytes by using the and methods. + /// The following example shows how to compress and decompress bytes by using the and methods. /// - /// is . + /// is . /// The value was when the object was created. /// -or- /// The underlying stream does not support reading. /// or is less than zero. /// -or- - /// length minus the index starting point is less than . + /// length minus the index starting point is less than . /// The data is in an invalid format. /// The stream is closed. public override int Read(byte[] buffer, int offset, int count) @@ -236,7 +232,7 @@ public override int Read(byte[] buffer, int offset, int count) /// Reads a sequence of bytes from the current GZip stream into a byte span and advances the position within the GZip stream by the number of bytes read. /// A region of memory. When this method returns, the contents of this region are replaced by the bytes read from the current source. /// The total number of bytes read into the buffer. This can be less than the number of bytes allocated in the buffer if that many bytes are not currently available, or zero (0) if the end of the stream has been reached. - /// Use the property to determine whether the current instance supports reading. Use the method to read asynchronously from the current stream. + /// Use the property to determine whether the current instance supports reading. Use the method to read asynchronously from the current stream. /// This method read a maximum of `buffer.Length` bytes from the current stream and store them in . The current position within the GZip stream is advanced by the number of bytes read; however, if an exception occurs, the current position within the GZip stream remains unchanged. This method will block until at least one byte of data can be read, in the event that no data is available. `Read` returns 0 only when there is no more data in the stream and no more is expected (such as a closed socket or end of file). The method is free to return fewer bytes than requested even if the end of the stream has not been reached. /// Use for reading primitive data types. public override int Read(Span buffer) @@ -256,16 +252,13 @@ public override int Read(Span buffer) } /// Begins an asynchronous write operation. (Consider using the method instead.) - /// The buffer containing data to write to the current stream. /// The buffer containing data to write to the current stream. - /// The byte offset in at which to begin writing. + /// The byte offset in at which to begin writing. /// The maximum number of bytes to write. /// An optional asynchronous callback to be called when the write operation is complete. - /// An optional asynchronous callback to be called when the write operation is complete. /// A user-provided object that distinguishes this particular asynchronous write request from other requests. - /// A user-provided object that distinguishes this particular asynchronous write request from other requests. /// An object that represents the asynchronous write operation, which could still be pending. - /// Starting with the .NET Framework 4.5, you can perform asynchronous write operations by using the method. The method is still available in .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). + /// Starting with the .NET Framework 4.5, you can perform asynchronous write operations by using the method. The method is still available in .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see Asynchronous File I/O. /// The method starts an asynchronous write operation to a stream object. /// You must create a callback method that implements the delegate and pass its name to the method. /// The underlying stream is . @@ -276,8 +269,7 @@ public override IAsyncResult BeginWrite(byte[] buffer, int offset, int count, As /// Handles the end of an asynchronous write operation. (Consider using the method instead.) /// The object that represents the asynchronous call. - /// The object that represents the asynchronous call. - /// Starting with the .NET Framework 4.5, you can perform asynchronous write operations by using the method. The method is still available in .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see [Asynchronous File I/O](/dotnet/standard/io/asynchronous-file-i-o). + /// Starting with the .NET Framework 4.5, you can perform asynchronous write operations by using the method. The method is still available in .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see Asynchronous File I/O. /// The method completes the asynchronous write operation started in the method. /// The underlying stream is . /// -or- @@ -286,11 +278,11 @@ public override void EndWrite(IAsyncResult asyncResult) => _deflateStream.EndWrite(asyncResult); /// Writes compressed bytes to the underlying GZip stream from the specified byte array. - /// The buffer that contains the data to compress. - /// The byte offset in from which the bytes will be read. + /// The buffer that contains the data to compress. + /// The byte offset in from which the bytes will be read. /// The maximum number of bytes to write. /// The write operation might not occur immediately but is buffered until the buffer size is reached or until the or method is called. - /// The following example shows how to compress and decompress bytes by using the and methods. + /// The following example shows how to compress and decompress bytes by using the and methods. /// Writes a sequence of bytes to the current GZip stream from a read-only byte span and advances the current position within this GZip stream by the number of bytes written. /// A region of memory. This method copies the contents of this region to the current GZip stream. - /// Use the property to determine whether the current instance supports writing. Use the method to write asynchronously to the current stream. + /// Use the property to determine whether the current instance supports writing. Use the method to write asynchronously to the current stream. /// If the write operation is successful, the position within the GZip stream advances by the number of bytes written. If an exception occurs, the position within the GZip stream remains unchanged. public override void Write(ReadOnlySpan buffer) { @@ -334,8 +326,8 @@ public override void CopyTo(Stream destination, int bufferSize) /// Releases the unmanaged resources used by the and optionally releases the managed resources. /// to release both managed and unmanaged resources; to release only unmanaged resources. - /// This method is called by the public method and the method. invokes the protected method with the parameter set to . invokes with set to . - /// When the parameter is , this method releases all resources held by any managed objects that this references. This method invokes the method of each referenced object. + /// This method is called by the public method and the method. invokes the protected method with the parameter set to . invokes with set to . + /// When the parameter is , this method releases all resources held by any managed objects that this references. This method invokes the method of each referenced object. protected override void Dispose(bool disposing) { try @@ -380,11 +372,11 @@ public override ValueTask DisposeAsync() public Stream BaseStream => _deflateStream?.BaseStream!; /// Asynchronously reads a sequence of bytes from the current GZip stream into a byte array, advances the position within the GZip stream by the number of bytes read, and monitors cancellation requests. - /// The buffer to write the data into. - /// The byte offset in at which to begin writing data from the GZip stream. + /// The buffer to write the data into. + /// The byte offset in at which to begin writing data from the GZip stream. /// The maximum number of bytes to read. /// The token to monitor for cancellation requests. The default value is . - /// A task that represents the asynchronous read operation, which wraps the total number of bytes read into the . The result value can be less than the number of bytes requested if the number of bytes currently available is less than the requested number, or it can be 0 (zero) if the end of the GZip stream has been reached. + /// A task that represents the asynchronous read operation, which wraps the total number of bytes read into the . The result value can be less than the number of bytes requested if the number of bytes currently available is less than the requested number, or it can be 0 (zero) if the end of the GZip stream has been reached. /// The `ReadAsync` method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in a Windows 8.x Store app or desktop app where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the and keywords in Visual Basic and C#. /// Use the property to determine whether the current instance supports reading. /// If the operation is canceled before it completes, the returned task contains the value for the property. @@ -418,8 +410,8 @@ public override Task ReadAsync(byte[] buffer, int offset, int count, Cancel } /// Asynchronously writes compressed bytes to the underlying GZip stream from the specified byte array. - /// The buffer that contains the data to compress. - /// The zero-based byte offset in from which to begin copying bytes to the GZip stream. + /// The buffer that contains the data to compress. + /// The zero-based byte offset in from which to begin copying bytes to the GZip stream. /// The maximum number of bytes to write. /// The token to monitor for cancellation requests. The default value is . /// A task that represents the asynchronous write operation. From 396c83aa4c19b2510dda2518cc2076f5be61ae32 Mon Sep 17 00:00:00 2001 From: carlossanlop Date: Thu, 25 Feb 2021 16:44:16 -0800 Subject: [PATCH 13/18] ZipArchive: langword, #ctor, hyperlinks, overloads --- .../src/System/IO/Compression/ZipArchive.cs | 36 +++++++++---------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchive.cs b/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchive.cs index 7819856d725c79..1a457f895cea74 100644 --- a/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchive.cs +++ b/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchive.cs @@ -12,18 +12,18 @@ namespace System.IO.Compression { /// Represents a package of compressed files in the zip archive format. - /// The methods for manipulating zip archives and their file entries are spread across three classes: , , and . + /// The methods for manipulating zip archives and their file entries are spread across three classes: , , and . /// |To|Use| /// |--------|---------| - /// |Create a zip archive from a directory|| - /// |Extract the contents of a zip archive to a directory|| - /// |Add new files to an existing zip archive|| + /// |Create a zip archive from a directory|| + /// |Extract the contents of a zip archive to a directory|| + /// |Add new files to an existing zip archive|| /// |Retrieve a file from a zip archive|| /// |Retrieve all the files from a zip archive|| /// |Open a stream to a single file contained in a zip archive|| /// |Delete a file from a zip archive|| - /// When you create a new entry, the file is compressed and added to the zip package. The method enables you to specify a directory hierarchy when adding the entry. You include the relative path of the new entry within the zip package. For example, creating a new entry with a relative path of `AddedFolder\NewFile.txt` creates a compressed text file in a directory named AddedFolder. - /// If you reference the `System.IO.Compression.FileSystem` assembly in your project, you can access four extension methods (from the class) for the class: , , , and (available in .NET Core 2.0 and later versions). These extension methods enable you to compress and decompress the contents of the entry to a file. The `System.IO.Compression.FileSystem` assembly is not available for Windows 8.x Store apps. In Windows 8.x Store apps, you can compress and decompress files by using the or class, or you can use the Windows Runtime types Compressor](https://go.microsoft.com/fwlink/p/?LinkID=246357) and [Decompressor. + /// When you create a new entry, the file is compressed and added to the zip package. The method enables you to specify a directory hierarchy when adding the entry. You include the relative path of the new entry within the zip package. For example, creating a new entry with a relative path of `AddedFolder\NewFile.txt` creates a compressed text file in a directory named AddedFolder. + /// If you reference the `System.IO.Compression.FileSystem` assembly in your project, you can access four extension methods (from the class) for the class: , , , and (available in .NET Core 2.0 and later versions). These extension methods enable you to compress and decompress the contents of the entry to a file. The `System.IO.Compression.FileSystem` assembly is not available for Windows 8.x Store apps. In Windows 8.x Store apps, you can compress and decompress files by using the or class, or you can use the Windows Runtime types Compressor](https://go.microsoft.com/fwlink/p/?LinkID=246357) and [Decompressor. /// The first example shows how to create a new entry and write to it by using a stream. /// - /// + /// public class ZipArchive : IDisposable { private readonly Stream _archiveStream; @@ -243,7 +243,7 @@ public ReadOnlyCollection Entries /// Gets a value that describes the type of action the zip archive can perform on entries. /// One of the enumeration values that describes the type of action (read, create, or update) the zip archive can perform on entries. - /// You specify a value for the property when you create an instance of the class. Use the or constructor to provide a value for the property. + /// You specify a value for the property when you create an instance of the class. Use the or constructor to provide a value for the property. public ZipArchiveMode Mode { get @@ -256,7 +256,7 @@ public ZipArchiveMode Mode /// A path, relative to the root of the archive, that specifies the name of the entry to be created. /// An empty entry in the zip archive. /// The string should reflect the relative path of the entry you want to create within the zip archive. There is no restriction on the string you provide. However, if it is not formatted as a relative path, the entry is created, but you may get an exception when you extract the contents of the zip archive. If an entry with the specified path and name already exists in the archive, a second entry is created with the same path and name. - /// The value of the property for the new entry is set to the current time. The entry is compressed using the default compression level of the underlying compression algorithm. If you want to specify a different compression level, use the method. + /// The value of the property for the new entry is set to the current time. The entry is compressed using the default compression level of the underlying compression algorithm. If you want to specify a different compression level, use the method. /// The following example shows how to create an entry and write to it by using a stream. /// Called by the and methods to release the unmanaged resources used by the current instance of the class, and optionally finishes writing the archive and releases the managed resources. + /// Called by the and methods to release the unmanaged resources used by the current instance of the class, and optionally finishes writing the archive and releases the managed resources. /// to finish writing the archive and release unmanaged and managed resources; to release only unmanaged resources. - /// If is set to , all underlying streams are closed and no longer available for subsequent write operations, unless you construct the object by using the constructor overload and set its `leaveOpen` parameter to . - /// This method is called only by the public and methods; do not call this method directly. - /// When you implement the dispose pattern, the Boolean parameter of the method should be used as follows: - /// - The method of the current object should call with the Boolean parameter set to to release both managed and unmanaged resources. - /// - The method of the current object should call with the Boolean parameter set to to release only unmanaged resources. + /// If is set to , all underlying streams are closed and no longer available for subsequent write operations, unless you construct the object by using the constructor overload and set its `leaveOpen` parameter to . + /// This method is called only by the public and methods; do not call this method directly. + /// When you implement the dispose pattern, the Boolean parameter of the method should be used as follows: + /// - The method of the current object should call with the Boolean parameter set to to release both managed and unmanaged resources. + /// - The method of the current object should call with the Boolean parameter set to to release only unmanaged resources. /// For more information, see [Implementing a Dispose method](/dotnet/standard/garbage-collection/implementing-dispose). protected virtual void Dispose(bool disposing) { @@ -326,9 +326,9 @@ protected virtual void Dispose(bool disposing) } /// Releases the resources used by the current instance of the class. - /// This method finishes writing the archive and releases all resources used by the object. Unless you construct the object by using the constructor overload and set its `leaveOpen` parameter to , all underlying streams are closed and no longer available for subsequent write operations. - /// When you are finished using this instance of , call to release all resources used by this instance. You should eliminate further references to this instance so that the garbage collector can reclaim the memory of the instance instead of keeping it alive for finalization. - /// calls the method, which contains the code to release managed and unmanaged resources. For more information, see [Implementing a Dispose method](/dotnet/standard/garbage-collection/implementing-dispose). + /// This method finishes writing the archive and releases all resources used by the object. Unless you construct the object by using the constructor overload and set its `leaveOpen` parameter to , all underlying streams are closed and no longer available for subsequent write operations. + /// When you are finished using this instance of , call to release all resources used by this instance. You should eliminate further references to this instance so that the garbage collector can reclaim the memory of the instance instead of keeping it alive for finalization. + /// calls the method, which contains the code to release managed and unmanaged resources. For more information, see [Implementing a Dispose method](/dotnet/standard/garbage-collection/implementing-dispose). public void Dispose() { Dispose(true); From 99bf1b6af992d590b30aba1cd30184dd210c44ca Mon Sep 17 00:00:00 2001 From: carlossanlop Date: Thu, 25 Feb 2021 16:48:39 -0800 Subject: [PATCH 14/18] ZipArchiveEntry: langwords, overloads --- .../System/IO/Compression/ZipArchiveEntry.cs | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveEntry.cs b/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveEntry.cs index dd7044586a3393..55747546c28cbc 100644 --- a/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveEntry.cs +++ b/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveEntry.cs @@ -10,23 +10,23 @@ namespace System.IO.Compression { /// Represents a compressed file within a zip archive. /// A zip archive contains an entry for each compressed file. The class enables you to examine the properties of an entry, and open or delete the entry. When you open an entry, you can modify the compressed file by writing to the stream for that compressed file. - /// The methods for manipulating zip archives and their file entries are spread across three classes: , and . + /// The methods for manipulating zip archives and their file entries are spread across three classes: , and . /// |To...|Use...| /// |---------|----------| - /// |Create a zip archive from a directory|| - /// |Extract the contents of a zip archive to a directory|| - /// |Add new files to an existing zip archive|| + /// |Create a zip archive from a directory|| + /// |Extract the contents of a zip archive to a directory|| + /// |Add new files to an existing zip archive|| /// |Retrieve an file in a zip archive|| /// |Retrieve all of the files in a zip archive|| /// |To open a stream to an individual file contained in a zip archive|| /// |Delete a file from a zip archive|| - /// If you reference the `System.IO.Compression.FileSystem` assembly in your project, you can access two extension methods for the class. Those methods are and , and they enable you to decompress the contents of the entry to a file. The `System.IO.Compression.FileSystem` assembly is not available in Windows 8. In Windows 8.x Store apps, you can decompress the contents of an archive by using or , or you can use the Windows Runtime types Compressor](https://go.microsoft.com/fwlink/p/?LinkId=246357) and [Decompressor to compress and decompress files. + /// If you reference the `System.IO.Compression.FileSystem` assembly in your project, you can access two extension methods for the class. Those methods are and , and they enable you to decompress the contents of the entry to a file. The `System.IO.Compression.FileSystem` assembly is not available in Windows 8. In Windows 8.x Store apps, you can decompress the contents of an archive by using or , or you can use the Windows Runtime types Compressor](https://go.microsoft.com/fwlink/p/?LinkId=246357) and [Decompressor to compress and decompress files. /// The first example shows how to create a new entry in a zip archive and write to it. /// - /// The second example shows how to use the extension method. You must reference the `System.IO.Compression.FileSystem` assembly in your project for the code to execute. + /// The second example shows how to use the extension method. You must reference the `System.IO.Compression.FileSystem` assembly in your project for the code to execute. /// Gets the relative path of the entry in the zip archive. /// The relative path of the entry in the zip archive. - /// The property contains the relative path, including the subdirectory hierarchy, of an entry in a zip archive. (In contrast, the property contains only the name of the entry and does not include the subdirectory hierarchy.) For example, if you create two entries in a zip archive by using the method and provide `NewEntry.txt` as the name for the first entry and `AddedFolder\\NewEntry.txt` for the second entry, both entries will have `NewEntry.txt` in the property. The first entry will also have `NewEntry.txt` in the property, but the second entry will have `AddedFolder\\NewEntry.txt` in the property. + /// The property contains the relative path, including the subdirectory hierarchy, of an entry in a zip archive. (In contrast, the property contains only the name of the entry and does not include the subdirectory hierarchy.) For example, if you create two entries in a zip archive by using the method and provide `NewEntry.txt` as the name for the first entry and `AddedFolder\\NewEntry.txt` for the second entry, both entries will have `NewEntry.txt` in the property. The first entry will also have `NewEntry.txt` in the property, but the second entry will have `AddedFolder\\NewEntry.txt` in the property. /// You can specify any string as the path of an entry, including strings that specify invalid and absolute paths. Therefore, the property might contain a value that is not correctly formatted. An invalid or absolute path might result in an exception when you extract the contents of the zip archive. /// The following example shows how to iterate through the contents of a .zip file, and extract files that contain the .txt extension. /// Gets or sets the last time the entry in the zip archive was changed. /// The last time the entry in the zip archive was changed. - /// When you create a new entry from an existing file by calling the method, the property for the entry is automatically set to the last time the file was modified. When you create a new entry programmatically by calling the method, the property for the entry is automatically set to the time of execution. If you modify the entry, you must explicitly set the property if you want the value to reflect the time of the latest change. + /// When you create a new entry from an existing file by calling the method, the property for the entry is automatically set to the last time the file was modified. When you create a new entry programmatically by calling the method, the property for the entry is automatically set to the time of execution. If you modify the entry, you must explicitly set the property if you want the value to reflect the time of the latest change. /// When you set this property, the value is converted to a timestamp format that is specific to zip archives. This format supports a resolution of two seconds. The earliest permitted value is 1980 January 1 0:00:00 (midnight). The latest permitted value is 2107 December 31 23:59:58 (one second before midnight). If the value for the last write time is not valid, the property returns a default value of 1980 January 1 0:00:00 (midnight). /// The following example shows how to open an entry in a zip archive, modify it, and set the property to the current time. /// Gets the file name of the entry in the zip archive. /// The file name of the entry in the zip archive. - /// The property contains the portion of the property that follows the final directory separator character (\\), and does not include the subdirectory hierarchy. For example, if you create two entries in a zip archive by using the method and provide `NewEntry.txt` as the name for the first entry and `AddedFolder\\NewEntry.txt` for the second entry, both entries will have `NewEntry.txt` in the property. The first entry will also have `NewEntry.txt` in the property, but the second entry will have `AddedFolder\\NewEntry.txt` in the property. + /// The property contains the portion of the property that follows the final directory separator character (\\), and does not include the subdirectory hierarchy. For example, if you create two entries in a zip archive by using the method and provide `NewEntry.txt` as the name for the first entry and `AddedFolder\\NewEntry.txt` for the second entry, both entries will have `NewEntry.txt` in the property. The first entry will also have `NewEntry.txt` in the property, but the second entry will have `AddedFolder\\NewEntry.txt` in the property. /// The following example shows how to retrieve entries from a zip archive and evaluate the properties of the entries. It uses the property to display the name of the entry, and the and properties to calculate how much the file was compressed. /// Date: Thu, 25 Feb 2021 16:48:57 -0800 Subject: [PATCH 15/18] ZipArchiveEntry.Windows: langword, hyperlinks, overloads --- .../System/IO/Compression/ZipArchiveEntry.Windows.cs | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveEntry.Windows.cs b/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveEntry.Windows.cs index bfb1d9ea8c598c..9c6e654145c08b 100644 --- a/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveEntry.Windows.cs +++ b/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveEntry.Windows.cs @@ -5,23 +5,23 @@ namespace System.IO.Compression { /// Represents a compressed file within a zip archive. /// A zip archive contains an entry for each compressed file. The class enables you to examine the properties of an entry, and open or delete the entry. When you open an entry, you can modify the compressed file by writing to the stream for that compressed file. - /// The methods for manipulating zip archives and their file entries are spread across three classes: , and . + /// The methods for manipulating zip archives and their file entries are spread across three classes: , and . /// |To...|Use...| /// |---------|----------| - /// |Create a zip archive from a directory|| - /// |Extract the contents of a zip archive to a directory|| - /// |Add new files to an existing zip archive|| + /// |Create a zip archive from a directory|| + /// |Extract the contents of a zip archive to a directory|| + /// |Add new files to an existing zip archive|| /// |Retrieve an file in a zip archive|| /// |Retrieve all of the files in a zip archive|| /// |To open a stream to an individual file contained in a zip archive|| /// |Delete a file from a zip archive|| - /// If you reference the `System.IO.Compression.FileSystem` assembly in your project, you can access two extension methods for the class. Those methods are and , and they enable you to decompress the contents of the entry to a file. The `System.IO.Compression.FileSystem` assembly is not available in Windows 8. In Windows 8.x Store apps, you can decompress the contents of an archive by using or , or you can use the Windows Runtime types Compressor](https://go.microsoft.com/fwlink/p/?LinkId=246357) and [Decompressor to compress and decompress files. + /// If you reference the `System.IO.Compression.FileSystem` assembly in your project, you can access two extension methods for the class. Those methods are and , and they enable you to decompress the contents of the entry to a file. The `System.IO.Compression.FileSystem` assembly is not available in Windows 8. In Windows 8.x Store apps, you can decompress the contents of an archive by using or , or you can use the Windows Runtime types Compressor](https://go.microsoft.com/fwlink/p/?LinkId=246357) and [Decompressor to compress and decompress files. /// The first example shows how to create a new entry in a zip archive and write to it. /// - /// The second example shows how to use the extension method. You must reference the `System.IO.Compression.FileSystem` assembly in your project for the code to execute. + /// The second example shows how to use the extension method. You must reference the `System.IO.Compression.FileSystem` assembly in your project for the code to execute. /// Date: Thu, 25 Feb 2021 16:50:01 -0800 Subject: [PATCH 16/18] ZipArchiveMode: langword, #ctor --- .../src/System/IO/Compression/ZipArchiveMode.cs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveMode.cs b/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveMode.cs index bcc9734f5bc23b..3652e8fea07961 100644 --- a/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveMode.cs +++ b/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveMode.cs @@ -5,12 +5,12 @@ namespace System.IO.Compression { /// Specifies values for interacting with zip archive entries. /// When you set the mode to Read, the underlying file or stream must support reading, but does not have to support seeking. If the underlying file or stream supports seeking, the files are read from the archive as they are requested. If the underlying file or stream does not support seeking, the entire archive is held in memory. - /// When you set the mode to Create, the underlying file or stream must support writing, but does not have to support seeking. Each entry in the archive can be opened only once for writing. If you create a single entry, the data is written to the underlying stream or file as soon as it is available. If you create multiple entries, such as by calling the method, the data is written to the underlying stream or file after all the entries are created. + /// When you set the mode to Create, the underlying file or stream must support writing, but does not have to support seeking. Each entry in the archive can be opened only once for writing. If you create a single entry, the data is written to the underlying stream or file as soon as it is available. If you create multiple entries, such as by calling the method, the data is written to the underlying stream or file after all the entries are created. /// When you set the mode to Update, the underlying file or stream must support reading, writing, and seeking. The content of the entire archive is held in memory, and no data is written to the underlying file or stream until the archive is disposed. /// The following methods include a parameter named `mode` that lets you specify the archive mode: - /// - - /// - - /// - + /// - + /// - + /// - /// The following example shows how to specify a `ZipArchiveMode` value when creating a object. /// Date: Thu, 25 Feb 2021 18:31:10 -0800 Subject: [PATCH 17/18] Lengthy remarks --- .../System/IO/Compression/CompressionLevel.cs | 17 +---- .../Compression/DeflateZLib/DeflateStream.cs | 64 ++++++------------- .../src/System/IO/Compression/GZipStream.cs | 26 ++------ .../src/System/IO/Compression/ZipArchive.cs | 44 ++----------- .../IO/Compression/ZipArchiveEntry.Windows.cs | 25 +------- .../System/IO/Compression/ZipArchiveEntry.cs | 54 ++++------------ .../System/IO/Compression/ZipArchiveMode.cs | 15 +---- 7 files changed, 51 insertions(+), 194 deletions(-) diff --git a/src/libraries/System.IO.Compression/src/System/IO/Compression/CompressionLevel.cs b/src/libraries/System.IO.Compression/src/System/IO/Compression/CompressionLevel.cs index ec2f9dd55489a5..6551d02395832c 100644 --- a/src/libraries/System.IO.Compression/src/System/IO/Compression/CompressionLevel.cs +++ b/src/libraries/System.IO.Compression/src/System/IO/Compression/CompressionLevel.cs @@ -4,20 +4,9 @@ namespace System.IO.Compression { /// Specifies values that indicate whether a compression operation emphasizes speed or compression size. - /// Compression operations usually involve a tradeoff between the speed and the effectiveness of compression. You use the enumeration to indicate which factor is more important in your development scenario: the time to complete the compression operation or the size of the compressed file. These values do not correspond to specific compression levels; the object that implements compression determines how to handle them. - /// The following methods of the , , , , and classes include a parameter named `compressionLevel` that lets you specify the compression level: - /// - - /// - - /// - - /// - - /// - - /// - - /// - - /// The following example shows how to set the compression level when creating a zip archive by using the class. - /// + /// public enum CompressionLevel { /// The compression operation should be optimally compressed, even if the operation takes a longer time to complete. diff --git a/src/libraries/System.IO.Compression/src/System/IO/Compression/DeflateZLib/DeflateStream.cs b/src/libraries/System.IO.Compression/src/System/IO/Compression/DeflateZLib/DeflateStream.cs index 60b82f22b95380..bfa50da0e538d2 100644 --- a/src/libraries/System.IO.Compression/src/System/IO/Compression/DeflateZLib/DeflateStream.cs +++ b/src/libraries/System.IO.Compression/src/System/IO/Compression/DeflateZLib/DeflateStream.cs @@ -11,15 +11,9 @@ namespace System.IO.Compression { /// Provides methods and properties for compressing and decompressing streams by using the Deflate algorithm. - /// This class represents the Deflate algorithm, which is an industry-standard algorithm for lossless file compression and decompression. Starting with the .NET Framework 4.5, the class uses the zlib library. As a result, it provides a better compression algorithm and, in most cases, a smaller compressed file than it provides in earlier versions of the .NET Framework. - /// This class does not inherently provide functionality for adding files to or extracting files from zip archives. To work with zip archives, use the and the classes. - /// The class uses the same compression algorithm as the gzip data format used by the class. - /// The compression functionality in and is exposed as a stream. Data is read on a byte-by-byte basis, so it is not possible to perform multiple passes to determine the best method for compressing entire files or large blocks of data. The and classes are best used on uncompressed sources of data. If the source data is already compressed, using these classes may actually increase the size of the stream. - /// The following example shows how to use the class to compress and decompress a directory of files. - /// + /// public partial class DeflateStream : Stream { private const int DefaultBufferSize = 8192; @@ -40,15 +34,9 @@ internal DeflateStream(Stream stream, CompressionMode mode, long uncompressedSiz /// Initializes a new instance of the class by using the specified stream and compression mode. /// The stream to compress or decompress. /// One of the enumeration values that indicates whether to compress or decompress the stream. - /// By default, owns the underlying stream, so closing the stream also closes the underlying stream. Note that the state of the underlying stream can affect the usability of the stream. Also, no explicit checks are performed, so no additional exceptions are thrown when the new instance is created. - /// If an instance of the class is created with the parameter equal to `Compress`, header information is inserted immediately. If no further action occurs, the stream appears as a valid, empty, compressed file. - /// Using the class to compress a file larger than 4 GB raises an exception. - /// By default, the compression level is set to when the compression mode is . - /// The following example shows how to use the class to compress and decompress a file. - /// + /// /// is . /// is not a valid value. /// -or- @@ -63,15 +51,9 @@ public DeflateStream(Stream stream, CompressionMode mode) : this(stream, mode, l /// The stream to compress or decompress. /// One of the enumeration values that indicates whether to compress or decompress the stream. /// to leave the stream open after disposing the object; otherwise, . - /// By default, owns the underlying stream, so closing the stream also closes the underlying stream. Note that the state of the underlying stream can affect the usability of the stream. Also, no explicit checks are performed, so no additional exceptions are thrown when the new instance is created. - /// If an instance of the class is created with the parameter equal to `Compress`, header information is inserted immediately. If no further action occurs, the stream appears as a valid, empty, compressed file. - /// Using the class to compress a file larger than 4 GB raises an exception. - /// By default, the compression level is set to when the compression mode is . - /// The following code example shows how to use the class to compress and decompress a file. - /// + /// /// is . /// is not a valid value. /// -or- @@ -102,13 +84,9 @@ public DeflateStream(Stream stream, CompressionLevel compressionLevel) : this(st /// The stream to compress. /// One of the enumeration values that indicates whether to emphasize speed or compression efficiency when compressing the stream. /// to leave the stream object open after disposing the object; otherwise, . - /// You use this constructor when you want to specify whether compression efficiency or speed is more important for an instance of the class, and whether to leave the stream object open after disposing the object. - /// This constructor overload uses the compression mode . To set the compression mode to another value, use the or overload. - /// The following example shows how to set the compression level when creating a object and how to leave the stream open. - /// + /// /// is . /// The stream does not support write operations such as compression. (The property on the stream object is .) public DeflateStream(Stream stream, CompressionLevel compressionLevel, bool leaveOpen) : this(stream, compressionLevel, leaveOpen, ZLibNative.Deflate_DefaultWindowBits) @@ -472,12 +450,9 @@ private static void ThrowCannotWriteToDeflateStreamException() /// An optional asynchronous callback, to be called when the read operation is complete. /// A user-provided object that distinguishes this particular asynchronous read request from other requests. /// An object that represents the asynchronous read operation, which could still be pending. - /// Starting with the .NET Framework 4.5, you can perform asynchronous read operations by using the method. The method is still available in the .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see Asynchronous File I/O. - /// Pass the return value to the method of the stream to determine how many bytes were read and to release operating system resources used for reading. You can do this either by using the same code that called or in a callback passed to . - /// The current position in the stream is updated when the asynchronous read or write operation is issued, not when the I/O operation completes. - /// Multiple simultaneous asynchronous requests render the request completion order uncertain. - /// Use the property to determine whether the current object supports reading. - /// If a stream is closed or you pass an invalid argument, exceptions are thrown immediately from . Errors that occur during an asynchronous read request, such as a disk failure during the I/O request, occur on the thread pool thread and throw exceptions when calling . + /// /// The method tried to read asynchronously past the end of the stream, or a disk error occurred. /// One or more of the arguments is invalid. /// Methods were called after the stream was closed. @@ -919,12 +894,9 @@ async ValueTask Core() /// An optional asynchronous callback, to be called when the write operation is complete. /// A user-provided object that distinguishes this particular asynchronous write request from other requests. /// An object that represents the asynchronous write operation, which could still be pending. - /// Starting with the .NET Framework 4.5, you can perform asynchronous write operations by using the method. The method is still available in the .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see Asynchronous File I/O. - /// Pass the object returned by the current method to to ensure that the write completes and frees resources appropriately. You can do this either by using the same code that called or in a callback passed to . If an error occurs during an asynchronous write operation, an exception will not be thrown until is called with the returned by this method. - /// If a stream is writable, writing at the end of the stream expands the stream. - /// The current position in the stream is updated when you issue the asynchronous read or write operation, not when the I/O operation completes. Multiple simultaneous asynchronous requests render the request completion order uncertain. - /// Use the property to determine whether the current object supports writing. - /// If a stream is closed or you pass an invalid argument, exceptions are thrown immediately from . Errors that occur during an asynchronous write request, such as a disk failure during the I/O request, occur on the thread pool thread and throw exceptions when calling . + /// /// The method tried to write asynchronously past the end of the stream, or a disk error occurred. /// One or more of the arguments is invalid. /// Methods were called after the stream was closed. diff --git a/src/libraries/System.IO.Compression/src/System/IO/Compression/GZipStream.cs b/src/libraries/System.IO.Compression/src/System/IO/Compression/GZipStream.cs index c1e753ce9a2a3c..222b1996fe750b 100644 --- a/src/libraries/System.IO.Compression/src/System/IO/Compression/GZipStream.cs +++ b/src/libraries/System.IO.Compression/src/System/IO/Compression/GZipStream.cs @@ -8,15 +8,9 @@ namespace System.IO.Compression { /// Provides methods and properties used to compress and decompress streams by using the GZip data format specification. - /// This class represents the gzip data format, which uses an industry-standard algorithm for lossless file compression and decompression. The format includes a cyclic redundancy check value for detecting data corruption. The gzip data format uses the same algorithm as the class, but can be extended to use other compression formats. The format can be readily implemented in a manner not covered by patents. - /// Starting with the .NET Framework 4.5, the class uses the zlib library for compression. As a result, it provides a better compression algorithm and, in most cases, a smaller compressed file than it provides in earlier versions of the .NET Framework. - /// Compressed objects written to a file with an extension of .gz can be decompressed using many common compression tools; however, this class does not inherently provide functionality for adding files to or extracting files from zip archives. - /// The compression functionality in and is exposed as a stream. Data is read on a byte-by-byte basis, so it is not possible to perform multiple passes to determine the best method for compressing entire files or large blocks of data. The and classes are best used on uncompressed sources of data. If the source data is already compressed, using these classes may actually increase the size of the stream. - /// The following example shows how to use the class to compress and decompress a directory of files. - /// + /// public class GZipStream : Stream { private DeflateStream _deflateStream; @@ -167,17 +161,9 @@ public override int ReadByte() /// An optional asynchronous callback, to be called when the read operation is complete. /// A user-provided object that distinguishes this particular asynchronous read request from other requests. /// An object that represents the asynchronous read operation, which could still be pending. - /// Starting with the .NET Framework 4.5, you can perform asynchronous read operations by using the method. The method is still available in .NET Framework 4.5 to support legacy code; however, you can implement asynchronous I/O operations more easily by using the new async methods. For more information, see Asynchronous File I/O. - /// Pass the return value to the method of the stream to determine how many bytes were read and to release operating system resources used for reading. You can do this either by using the same code that called or in a callback passed to . - /// The current position in the stream is updated when the asynchronous read or write is issued, not when the I/O operation completes. - /// Multiple simultaneous asynchronous requests render the request completion order uncertain. - /// Use the property to determine whether the current object supports reading. - /// If a stream is closed or you pass an invalid argument, exceptions are thrown immediately from . Errors that occur during an asynchronous read request, such as a disk failure during the I/O request, occur on the thread pool thread and throw exceptions when calling . - /// The following code example shows how to use the class to compress and decompress a file. - /// + /// /// The method tried to read asynchronously past the end of the stream, or a disk error occurred. /// One or more of the arguments is invalid. /// Methods were called after the stream was closed. diff --git a/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchive.cs b/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchive.cs index 1a457f895cea74..cad8a8c8293e1c 100644 --- a/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchive.cs +++ b/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchive.cs @@ -12,33 +12,9 @@ namespace System.IO.Compression { /// Represents a package of compressed files in the zip archive format. - /// The methods for manipulating zip archives and their file entries are spread across three classes: , , and . - /// |To|Use| - /// |--------|---------| - /// |Create a zip archive from a directory|| - /// |Extract the contents of a zip archive to a directory|| - /// |Add new files to an existing zip archive|| - /// |Retrieve a file from a zip archive|| - /// |Retrieve all the files from a zip archive|| - /// |Open a stream to a single file contained in a zip archive|| - /// |Delete a file from a zip archive|| - /// When you create a new entry, the file is compressed and added to the zip package. The method enables you to specify a directory hierarchy when adding the entry. You include the relative path of the new entry within the zip package. For example, creating a new entry with a relative path of `AddedFolder\NewFile.txt` creates a compressed text file in a directory named AddedFolder. - /// If you reference the `System.IO.Compression.FileSystem` assembly in your project, you can access four extension methods (from the class) for the class: , , , and (available in .NET Core 2.0 and later versions). These extension methods enable you to compress and decompress the contents of the entry to a file. The `System.IO.Compression.FileSystem` assembly is not available for Windows 8.x Store apps. In Windows 8.x Store apps, you can compress and decompress files by using the or class, or you can use the Windows Runtime types Compressor](https://go.microsoft.com/fwlink/p/?LinkID=246357) and [Decompressor. - /// The first example shows how to create a new entry and write to it by using a stream. - /// - /// The following example shows how to open a zip archive and iterate through the collection of entries. - /// - /// The third example shows how to use extension methods to create a new entry in a zip archive from an existing file and extract the archive contents. You must reference the `System.IO.Compression.FileSystem` assembly to execute the code. - /// + /// /// public class ZipArchive : IDisposable { @@ -100,17 +76,9 @@ public ZipArchive(Stream stream, ZipArchiveMode mode, bool leaveOpen) : this(str /// One of the enumeration values that indicates whether the zip archive is used to read, create, or update entries. /// to leave the stream open after the object is disposed; otherwise, . /// The encoding to use when reading or writing entry names in this archive. Specify a value for this parameter only when an encoding is required for interoperability with zip archive tools and libraries that do not support UTF-8 encoding for entry names. - /// If the parameter is set to , the stream must support reading. If the parameter is set to , the stream must support writing. If the parameter is set to , the stream must support reading, writing, and seeking. - /// When you open a zip archive file for reading and is set to , entry names are decoded according to the following rules: - /// - When the language encoding flag (in the general-purpose bit flag of the local file header) is not set, the current system default code page is used to decode the entry name. - /// - When the language encoding flag is set, UTF-8 is used to decode the entry name. - /// When you open a zip archive file for reading and is set to a value other than , entry names are decoded according to the following rules: - /// - When the language encoding flag is not set, the specified is used to decode the entry name. - /// - When the language encoding flag is set, UTF-8 is used to decode the entry name. - /// When you write to archive files and is set to , entry names are encoded according to the following rules: - /// - For entry names that contain characters outside the ASCII range, the language encoding flag is set, and entry names are encoded by using UTF-8. - /// - For entry names that contain only ASCII characters, the language encoding flag is not set, and entry names are encoded by using the current system default code page. - /// When you write to archive files and is set to a value other than , the specified is used to encode the entry names into bytes. The language encoding flag (in the general-purpose bit flag of the local file header) is set only when the specified encoding is a UTF-8 encoding. + /// /// The stream is already closed, or the capabilities of the stream do not match the mode. /// -or- /// An encoding other than UTF-8 is specified for the . diff --git a/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveEntry.Windows.cs b/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveEntry.Windows.cs index 9c6e654145c08b..51d14bd6d1671b 100644 --- a/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveEntry.Windows.cs +++ b/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveEntry.Windows.cs @@ -4,28 +4,9 @@ namespace System.IO.Compression { /// Represents a compressed file within a zip archive. - /// A zip archive contains an entry for each compressed file. The class enables you to examine the properties of an entry, and open or delete the entry. When you open an entry, you can modify the compressed file by writing to the stream for that compressed file. - /// The methods for manipulating zip archives and their file entries are spread across three classes: , and . - /// |To...|Use...| - /// |---------|----------| - /// |Create a zip archive from a directory|| - /// |Extract the contents of a zip archive to a directory|| - /// |Add new files to an existing zip archive|| - /// |Retrieve an file in a zip archive|| - /// |Retrieve all of the files in a zip archive|| - /// |To open a stream to an individual file contained in a zip archive|| - /// |Delete a file from a zip archive|| - /// If you reference the `System.IO.Compression.FileSystem` assembly in your project, you can access two extension methods for the class. Those methods are and , and they enable you to decompress the contents of the entry to a file. The `System.IO.Compression.FileSystem` assembly is not available in Windows 8. In Windows 8.x Store apps, you can decompress the contents of an archive by using or , or you can use the Windows Runtime types Compressor](https://go.microsoft.com/fwlink/p/?LinkId=246357) and [Decompressor to compress and decompress files. - /// The first example shows how to create a new entry in a zip archive and write to it. - /// - /// The second example shows how to use the extension method. You must reference the `System.IO.Compression.FileSystem` assembly in your project for the code to execute. - /// + /// public partial class ZipArchiveEntry { internal const ZipVersionMadeByPlatform CurrentZipPlatform = ZipVersionMadeByPlatform.Windows; diff --git a/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveEntry.cs b/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveEntry.cs index 55747546c28cbc..9286ef9e95e7e8 100644 --- a/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveEntry.cs +++ b/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveEntry.cs @@ -9,28 +9,9 @@ namespace System.IO.Compression { /// Represents a compressed file within a zip archive. - /// A zip archive contains an entry for each compressed file. The class enables you to examine the properties of an entry, and open or delete the entry. When you open an entry, you can modify the compressed file by writing to the stream for that compressed file. - /// The methods for manipulating zip archives and their file entries are spread across three classes: , and . - /// |To...|Use...| - /// |---------|----------| - /// |Create a zip archive from a directory|| - /// |Extract the contents of a zip archive to a directory|| - /// |Add new files to an existing zip archive|| - /// |Retrieve an file in a zip archive|| - /// |Retrieve all of the files in a zip archive|| - /// |To open a stream to an individual file contained in a zip archive|| - /// |Delete a file from a zip archive|| - /// If you reference the `System.IO.Compression.FileSystem` assembly in your project, you can access two extension methods for the class. Those methods are and , and they enable you to decompress the contents of the entry to a file. The `System.IO.Compression.FileSystem` assembly is not available in Windows 8. In Windows 8.x Store apps, you can decompress the contents of an archive by using or , or you can use the Windows Runtime types Compressor](https://go.microsoft.com/fwlink/p/?LinkId=246357) and [Decompressor to compress and decompress files. - /// The first example shows how to create a new entry in a zip archive and write to it. - /// - /// The second example shows how to use the extension method. You must reference the `System.IO.Compression.FileSystem` assembly in your project for the code to execute. - /// + /// public partial class ZipArchiveEntry { // The maximum index of our buffers, from the maximum index of a byte array @@ -207,13 +188,9 @@ public int ExternalAttributes /// Gets the relative path of the entry in the zip archive. /// The relative path of the entry in the zip archive. - /// The property contains the relative path, including the subdirectory hierarchy, of an entry in a zip archive. (In contrast, the property contains only the name of the entry and does not include the subdirectory hierarchy.) For example, if you create two entries in a zip archive by using the method and provide `NewEntry.txt` as the name for the first entry and `AddedFolder\\NewEntry.txt` for the second entry, both entries will have `NewEntry.txt` in the property. The first entry will also have `NewEntry.txt` in the property, but the second entry will have `AddedFolder\\NewEntry.txt` in the property. - /// You can specify any string as the path of an entry, including strings that specify invalid and absolute paths. Therefore, the property might contain a value that is not correctly formatted. An invalid or absolute path might result in an exception when you extract the contents of the zip archive. - /// The following example shows how to iterate through the contents of a .zip file, and extract files that contain the .txt extension. - /// + /// public string FullName { get @@ -244,13 +221,9 @@ private set /// Gets or sets the last time the entry in the zip archive was changed. /// The last time the entry in the zip archive was changed. - /// When you create a new entry from an existing file by calling the method, the property for the entry is automatically set to the last time the file was modified. When you create a new entry programmatically by calling the method, the property for the entry is automatically set to the time of execution. If you modify the entry, you must explicitly set the property if you want the value to reflect the time of the latest change. - /// When you set this property, the value is converted to a timestamp format that is specific to zip archives. This format supports a resolution of two seconds. The earliest permitted value is 1980 January 1 0:00:00 (midnight). The latest permitted value is 2107 December 31 23:59:58 (one second before midnight). If the value for the last write time is not valid, the property returns a default value of 1980 January 1 0:00:00 (midnight). - /// The following example shows how to open an entry in a zip archive, modify it, and set the property to the current time. - /// + /// /// The attempt to set this property failed, because the zip archive for the entry is in mode. /// The archive mode is set to . /// -or- @@ -297,12 +270,9 @@ public long Length /// Gets the file name of the entry in the zip archive. /// The file name of the entry in the zip archive. - /// The property contains the portion of the property that follows the final directory separator character (\\), and does not include the subdirectory hierarchy. For example, if you create two entries in a zip archive by using the method and provide `NewEntry.txt` as the name for the first entry and `AddedFolder\\NewEntry.txt` for the second entry, both entries will have `NewEntry.txt` in the property. The first entry will also have `NewEntry.txt` in the property, but the second entry will have `AddedFolder\\NewEntry.txt` in the property. - /// The following example shows how to retrieve entries from a zip archive and evaluate the properties of the entries. It uses the property to display the name of the entry, and the and properties to calculate how much the file was compressed. - /// + /// public string Name => ParseFileName(FullName, _versionMadeByPlatform); /// Deletes the entry from the zip archive. diff --git a/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveMode.cs b/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveMode.cs index 3652e8fea07961..e1aa3d02ce8fee 100644 --- a/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveMode.cs +++ b/src/libraries/System.IO.Compression/src/System/IO/Compression/ZipArchiveMode.cs @@ -4,18 +4,9 @@ namespace System.IO.Compression { /// Specifies values for interacting with zip archive entries. - /// When you set the mode to Read, the underlying file or stream must support reading, but does not have to support seeking. If the underlying file or stream supports seeking, the files are read from the archive as they are requested. If the underlying file or stream does not support seeking, the entire archive is held in memory. - /// When you set the mode to Create, the underlying file or stream must support writing, but does not have to support seeking. Each entry in the archive can be opened only once for writing. If you create a single entry, the data is written to the underlying stream or file as soon as it is available. If you create multiple entries, such as by calling the method, the data is written to the underlying stream or file after all the entries are created. - /// When you set the mode to Update, the underlying file or stream must support reading, writing, and seeking. The content of the entire archive is held in memory, and no data is written to the underlying file or stream until the archive is disposed. - /// The following methods include a parameter named `mode` that lets you specify the archive mode: - /// - - /// - - /// - - /// The following example shows how to specify a `ZipArchiveMode` value when creating a object. - /// + /// public enum ZipArchiveMode { /// Only reading archive entries is permitted. From 21861858a2d1b1541d6b07fd649aac8fd284e562 Mon Sep 17 00:00:00 2001 From: carlossanlop Date: Thu, 25 Feb 2021 18:34:05 -0800 Subject: [PATCH 18/18] GenerateDocumentationFile in csproj --- .../System.IO.Compression/src/System.IO.Compression.csproj | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/libraries/System.IO.Compression/src/System.IO.Compression.csproj b/src/libraries/System.IO.Compression/src/System.IO.Compression.csproj index e2a7adee12f579..5608b4737fe762 100644 --- a/src/libraries/System.IO.Compression/src/System.IO.Compression.csproj +++ b/src/libraries/System.IO.Compression/src/System.IO.Compression.csproj @@ -1,8 +1,9 @@ - + true $(NetCoreAppCurrent)-windows;$(NetCoreAppCurrent)-Unix;$(NetCoreAppCurrent)-Browser enable + true