You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy Stream docs to CryptoStream overrides (#2869)
* Copy Stream docs to CryptoStream overrides
All content came from System.IO.Stream, with references to members updated
to be CryptoStream members instead of Stream members -- with the exception
of Stream.CopyTo, which CryptoStream does not override.
* Apply suggestions from code review
Co-Authored-By: Ron Petrusha <[email protected]>
<paramname="buffer">The buffer to read the data into.</param>
182
+
<paramname="offset">The byte offset in <paramrefname="buffer" /> at which to begin writing data read from the stream.</param>
183
+
<paramname="count">The maximum number of bytes to read.</param>
184
+
<paramname="callback">An optional asynchronous callback, to be called when the read is complete.</param>
185
+
<paramname="state">A user-provided object that distinguishes this particular asynchronous read request from other requests.</param>
186
+
<summary>Begins an asynchronous read operation. (Consider using <seecref="Overload:System.Security.Cryptography.CryptoStream.ReadAsync" /> instead.)</summary>
187
+
<returns>An <seecref="T:System.IAsyncResult" /> that represents the asynchronous read, which could still be pending.</returns>
188
+
<remarks>
189
+
<formattype="text/markdown"><![CDATA[
190
+
191
+
## Remarks
192
+
In the .NET Framework 4 and earlier versions, you have to use methods such as <xref:System.IO.Stream.BeginRead%2A> and <xref:System.IO.Stream.EndRead%2A> to implement asynchronous I/O operations. These methods are still available in .NET to support legacy code; however, the new async methods, such as <xref:System.Security.Cryptography.CryptoStream.ReadAsync%2A>, <xref:System.Security.Cryptography.CryptoStream.WriteAsync%2A>, <xref:System.IO.Stream.CopyToAsync%2A>, and <xref:System.Security.Cryptography.CryptoStream.FlushAsync%2A>, help you implement asynchronous I/O operations more easily.
193
+
194
+
Pass the `IAsyncResult` return value to the <xref:System.Security.Cryptography.CryptoStream.EndRead%2A> method of the stream to determine how many bytes were read and to release operating system resources used for reading. <xref:System.Security.Cryptography.CryptoStream.EndRead%2A> must be called once for every call to <xref:System.Security.Cryptography.CryptoStream.BeginRead%2A>. You can do this either by using the same code that called `BeginRead` or in a callback passed to `BeginRead`.
195
+
196
+
The current position in the stream is updated when the asynchronous read or write is issued, not when the I/O operation completes.
197
+
198
+
Multiple simultaneous asynchronous requests render the request completion order uncertain.
199
+
200
+
Use the <xref:System.Security.Cryptography.CryptoStream.CanRead%2A> property to determine whether the current instance supports reading.
201
+
202
+
If a stream is closed or you pass an invalid argument, exceptions are thrown immediately from `BeginRead`. 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 `EndRead`.
203
+
204
+
]]></format>
205
+
</remarks>
206
+
<exceptioncref="T:System.IO.IOException">Attempted an asynchronous read past the end of the stream, or a disk error occurred.</exception>
207
+
<exceptioncref="T:System.ArgumentException">One or more of the arguments is invalid.</exception>
208
+
<exceptioncref="T:System.ObjectDisposedException">Methods were called after the stream was closed.</exception>
209
+
<exceptioncref="T:System.NotSupportedException">The current <seelangword="Stream" /> implementation does not support the read operation.</exception>
<paramname="buffer">The buffer to write data from.</param>
243
+
<paramname="offset">The byte offset in <paramrefname="buffer" /> from which to begin writing.</param>
244
+
<paramname="count">The maximum number of bytes to write.</param>
245
+
<paramname="callback">An optional asynchronous callback, to be called when the write is complete.</param>
246
+
<paramname="state">A user-provided object that distinguishes this particular asynchronous write request from other requests.</param>
247
+
<summary>Begins an asynchronous write operation. (Consider using <seecref="Overload:System.Security.Cryptography.CryptoStream.WriteAsync" /> instead.)</summary>
248
+
<returns>An <seelangword="IAsyncResult" /> that represents the asynchronous write, which could still be pending.</returns>
249
+
<remarks>
250
+
<formattype="text/markdown"><![CDATA[
251
+
252
+
## Remarks
253
+
In the .NET Framework 4 and earlier versions, you have to use methods such as <xref:System.Security.Cryptography.CryptoStream.BeginWrite%2A> and <xref:System.Security.Cryptography.CryptoStream.EndWrite%2A> to implement asynchronous I/O operations. These methods are still available in .NET to support legacy code; however, the new async methods, such as <xref:System.Security.Cryptography.CryptoStream.ReadAsync%2A>, <xref:System.Security.Cryptography.CryptoStream.WriteAsync%2A>, <xref:System.IO.Stream.CopyToAsync%2A>, and <xref:System.Security.Cryptography.CryptoStream.FlushAsync%2A>, help you implement asynchronous I/O operations more easily.
254
+
255
+
Pass the `IAsyncResult` returned by the current method to <xref:System.Security.Cryptography.CryptoStream.EndWrite%2A> to ensure that the write completes and frees resources appropriately. <xref:System.Security.Cryptography.CryptoStream.EndWrite%2A> must be called once for every call to <xref:System.Security.Cryptography.CryptoStream.BeginWrite%2A>. You can do this either by using the same code that called `BeginWrite` or in a callback passed to `BeginWrite`. If an error occurs during an asynchronous write, an exception will not be thrown until `EndWrite` is called with the `IAsyncResult` returned by this method.
256
+
257
+
If a stream is writable, writing at the end of the stream expands the stream.
258
+
259
+
The current position in the stream is updated when you issue the asynchronous read or write, not when the I/O operation completes. Multiple simultaneous asynchronous requests render the request completion order uncertain.
260
+
261
+
Use the <xref:System.Security.Cryptography.CryptoStream.CanWrite%2A> property to determine whether the current instance supports writing.
262
+
263
+
If a stream is closed or you pass an invalid argument, exceptions are thrown immediately from `BeginWrite`. 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 `EndWrite`.
264
+
265
+
]]></format>
266
+
</remarks>
267
+
<exceptioncref="T:System.IO.IOException">Attempted an asynchronous write past the end of the stream, or a disk error occurred.</exception>
268
+
<exceptioncref="T:System.ArgumentException">One or more of the arguments is invalid.</exception>
269
+
<exceptioncref="T:System.ObjectDisposedException">Methods were called after the stream was closed.</exception>
270
+
<exceptioncref="T:System.NotSupportedException">The current <seelangword="Stream" /> implementation does not support the write operation.</exception>
229
271
</Docs>
230
272
</Member>
231
273
<MemberMemberName="CanRead">
@@ -495,9 +537,20 @@
495
537
</ReturnValue>
496
538
<Parameters />
497
539
<Docs>
498
-
<summary>To be added.</summary>
499
-
<returns>To be added.</returns>
500
-
<remarks>To be added.</remarks>
540
+
<summary>Asynchronously releases the unmanaged resources used by the <seecref="T:System.Security.Cryptography.CryptoStream" />.</summary>
541
+
<returns>A task that represents the asynchronous dispose operation.</returns>
542
+
<remarks>
543
+
<formattype="text/markdown"><] app or [!INCLUDE[desktop_appname](~/includes/desktop-appname-md.md)] 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 `async` and `await` keywords in Visual Basic and C#.
547
+
548
+
This method disposes the stream by writing any changes to the backing store and closing the stream to release resources.
549
+
550
+
Calling `DisposeAsync` allows the resources used by the <xref:System.Security.Cryptography.CryptoStream> to be reallocated for other purposes. For more information, see [Cleaning Up Unmanaged Resources](~/docs/standard/garbage-collection/unmanaged.md).
<paramname="asyncResult">The reference to the pending asynchronous request to finish.</param>
583
+
<summary>Waits for the pending asynchronous read to complete. (Consider using <seecref="Overload:System.Security.Cryptography.CryptoStream.ReadAsync" /> instead.)</summary>
584
+
<returns>The number of bytes read from the stream, between zero (0) and the number of bytes you requested. Streams return zero (0) only at the end of the stream, otherwise, they should block until at least one byte is available.</returns>
585
+
<remarks>
586
+
<formattype="text/markdown"><![CDATA[
587
+
588
+
## Remarks
589
+
In the .NET Framework 4 and earlier versions, you have to use methods such as <xref:System.Security.Cryptography.CryptoStream.BeginRead%2A> and <xref:System.Security.Cryptography.CryptoStream.EndRead%2A> to implement asynchronous I/O operations. These methods are still available in .NET to support legacy code; however, the new async methods, such as <xref:System.Security.Cryptography.CryptoStream.ReadAsync%2A>, <xref:System.Security.Cryptography.CryptoStream.WriteAsync%2A>, <xref:System.IO.Stream.CopyToAsync%2A>, and <xref:System.Security.Cryptography.CryptoStream.FlushAsync%2A>, help you implement asynchronous I/O operations more easily.
590
+
591
+
Call `EndRead` to determine how many bytes were read from the stream.
592
+
593
+
`EndRead` can be called once on every <xref:System.IAsyncResult> from <xref:System.Security.Cryptography.CryptoStream.BeginRead%2A>.
594
+
595
+
This method blocks until the I/O operation has completed.
596
+
597
+
]]></format>
598
+
</remarks>
599
+
<exceptioncref="T:System.ArgumentNullException">
600
+
<paramrefname="asyncResult" /> is <seelangword="null" />.</exception>
601
+
<exceptioncref="T:System.ArgumentException">A handle to the pending read operation is not available.
602
+
603
+
-or-
604
+
605
+
The pending operation does not support reading.</exception>
<paramrefname="asyncResult" /> did not originate from a <seecref="M:System.Security.Cryptography.CryptoStream.BeginRead(System.Byte[],System.Int32,System.Int32,System.AsyncCallback,System.Object)" /> method on the current stream.</exception>
608
+
<exceptioncref="T:System.IO.IOException">The stream is closed or an internal error has occurred.</exception>
<paramname="asyncResult">A reference to the outstanding asynchronous I/O request.</param>
638
+
<summary>Ends an asynchronous write operation. (Consider using <seecref="Overload:System.Security.Cryptography.CryptoStream.WriteAsync" /> instead.)</summary>
639
+
<remarks>
640
+
<formattype="text/markdown"><![CDATA[
641
+
642
+
## Remarks
643
+
In the .NET Framework 4 and earlier versions, you have to use methods such as <xref:System.Security.Cryptography.CryptoStream.BeginWrite%2A> and <xref:System.Security.Cryptography.CryptoStream.EndWrite%2A> to implement asynchronous I/O operations. These methods are still available in .NET to support legacy code; however, the new async methods, such as <xref:System.Security.Cryptography.CryptoStream.ReadAsync%2A>, <xref:System.Security.Cryptography.CryptoStream.WriteAsync%2A>, <xref:System.IO.Stream.CopyToAsync%2A>, and <xref:System.Security.Cryptography.CryptoStream.FlushAsync%2A>, help you implement asynchronous I/O operations more easily.
644
+
645
+
`EndWrite` must be called exactly once on every <xref:System.IAsyncResult> from <xref:System.Security.Cryptography.CryptoStream.BeginWrite%2A>.
646
+
647
+
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 `EndWrite`. Exceptions thrown by the thread pool thread will not be visible when calling `EndWrite`.
648
+
649
+
]]></format>
650
+
</remarks>
651
+
<exceptioncref="T:System.ArgumentNullException">
652
+
<paramrefname="asyncResult" /> is <seelangword="null" />.</exception>
653
+
<exceptioncref="T:System.ArgumentException">A handle to the pending write operation is not available.
654
+
655
+
-or-
656
+
657
+
The pending operation does not support writing.</exception>
<paramrefname="asyncResult" /> did not originate from a <seecref="M:System.IO.Stream.BeginWrite(System.Byte[],System.Int32,System.Int32,System.AsyncCallback,System.Object)" /> method on the current stream.</exception>
660
+
<exceptioncref="T:System.IO.IOException">The stream is closed or an internal error has occurred.</exception>
564
661
</Docs>
565
662
</Member>
566
663
<MemberMemberName="Finalize">
@@ -1001,9 +1098,20 @@
1001
1098
</ReturnValue>
1002
1099
<Parameters />
1003
1100
<Docs>
1004
-
<summary>To be added.</summary>
1005
-
<returns>To be added.</returns>
1006
-
<remarks>To be added.</remarks>
1101
+
<summary>Reads a byte from the stream and advances the position within the stream by one byte, or returns -1 if at the end of the stream.</summary>
1102
+
<returns>The unsigned byte cast to an <seelangword="Int32" />, or -1 if at the end of the stream.</returns>
1103
+
<remarks>
1104
+
<formattype="text/markdown"><![CDATA[
1105
+
1106
+
## Remarks
1107
+
Use the <xref:System.Security.Cryptography.CryptoStream.CanRead%2A> property to determine whether the current instance supports reading.
1108
+
1109
+
Attempts to manipulate the stream after the stream has been closed could throw an <xref:System.ObjectDisposedException>.
1110
+
1111
+
]]></format>
1112
+
</remarks>
1113
+
<exceptioncref="T:System.NotSupportedException">The stream does not support reading.</exception>
1114
+
<exceptioncref="T:System.ObjectDisposedException">Methods were called after the stream was closed.</exception>
0 commit comments