NetworkStream.BeginRead(Byte[], Int32, Int32, AsyncCallback, Object) Method
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Begins an asynchronous read from the NetworkStream.
public:
override IAsyncResult ^ BeginRead(cli::array <System::Byte> ^ buffer, int offset, int size, AsyncCallback ^ callback, System::Object ^ state);public:
override IAsyncResult ^ BeginRead(cli::array <System::Byte> ^ buffer, int offset, int count, AsyncCallback ^ callback, System::Object ^ state);public override IAsyncResult BeginRead (byte[] buffer, int offset, int size, AsyncCallback? callback, object? state);public override IAsyncResult BeginRead (byte[] buffer, int offset, int count, AsyncCallback? callback, object? state);public override IAsyncResult BeginRead (byte[] buffer, int offset, int size, AsyncCallback callback, object state);override this.BeginRead : byte[] * int * int * AsyncCallback * obj -> IAsyncResultoverride this.BeginRead : byte[] * int * int * AsyncCallback * obj -> IAsyncResultPublic Overrides Function BeginRead (buffer As Byte(), offset As Integer, size As Integer, callback As AsyncCallback, state As Object) As IAsyncResultPublic Overrides Function BeginRead (buffer As Byte(), offset As Integer, count As Integer, callback As AsyncCallback, state As Object) As IAsyncResultParameters
- buffer
- Byte[]
An array of type Byte that is the location in memory to store data read from the NetworkStream.
- offset
- Int32
The location in buffer to begin storing the data.
- sizecount
- Int32
The number of bytes to read from the NetworkStream.
- callback
- AsyncCallback
The AsyncCallback delegate that is executed when BeginRead(Byte[], Int32, Int32, AsyncCallback, Object) completes.
- state
- Object
An object that contains any additional user-defined data.
Returns
An IAsyncResult that represents the asynchronous call.
Exceptions
The buffer parameter is null.
The offset parameter is less than 0.
-or-
The offset parameter is greater than the length of the buffer paramater.
-or-
The size is less than 0.
-or-
The size is greater than the length of buffer minus the value of the offset parameter.
The underlying Socket is closed.
-or-
There was a failure while reading from the network.
-or-
An error occurred when accessing the socket.
The NetworkStream is closed.
Remarks
Important
This is a compatibility API, we don't recommend to use the APM (Begin / End) methods for new development. Instead, use the Task-based equivalents.
You can pass a callback that implements AsyncCallback to BeginRead in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to BeginRead. In this case, the CompletedSynchronously property on the returned IAsyncResult will be set to true to indicate that the method completed synchronously. Use the AsyncState property of the IAsyncResult to obtain the state object passed to the BeginRead method.
The BeginRead operation must be completed by calling the EndRead method. Typically, the method is invoked by the provided AsyncCallback delegate. EndRead will block the calling thread until the operation is completed.
The operation reads as much data as is available, up to the number of bytes specified by the size parameter.
Note
If you receive an IOException, check the InnerException property to determine if it was caused by a SocketException. If so, use the ErrorCode property to obtain the specific error code.
Read and write operations can be performed simultaneously on an instance of the NetworkStream class without the need for synchronization. As long as there is one unique thread for the write operations and one unique thread for the read operations, there will be no cross-interference between read and write threads and no synchronization is required.
