Socket.BeginReceive Method

Definition

Namespace:

System.Net.Sockets

Assembly:

System.Net.Sockets.dll

Begins to asynchronously receive data from a connected Socket.

Overloads

BeginReceive(Byte[], Int32, Int32, SocketFlags, SocketError, AsyncCallback, Object)	Begins to asynchronously receive data from a connected Socket.
BeginReceive(Byte[], Int32, Int32, SocketFlags, AsyncCallback, Object)	Begins to asynchronously receive data from a connected Socket.
BeginReceive(IList<ArraySegment<Byte>>, SocketFlags, AsyncCallback, Object)	Begins to asynchronously receive data from a connected Socket.
BeginReceive(IList<ArraySegment<Byte>>, SocketFlags, SocketError, AsyncCallback, Object)	Begins to asynchronously receive data from a connected Socket.

BeginReceive(Byte[], Int32, Int32, SocketFlags, SocketError, AsyncCallback, Object)

Source:

Socket.cs

Begins to asynchronously receive data from a connected Socket.

public:
 IAsyncResult ^ BeginReceive(cli::array <System::Byte> ^ buffer, int offset, int size, System::Net::Sockets::SocketFlags socketFlags, [Runtime::InteropServices::Out] System::Net::Sockets::SocketError % errorCode, AsyncCallback ^ callback, System::Object ^ state);

public IAsyncResult? BeginReceive (byte[] buffer, int offset, int size, System.Net.Sockets.SocketFlags socketFlags, out System.Net.Sockets.SocketError errorCode, AsyncCallback? callback, object? state);

member this.BeginReceive : byte[] * int * int * System.Net.Sockets.SocketFlags * SocketError * AsyncCallback * obj -> IAsyncResult

Public Function BeginReceive (buffer As Byte(), offset As Integer, size As Integer, socketFlags As SocketFlags, ByRef errorCode As SocketError, callback As AsyncCallback, state As Object) As IAsyncResult

Parameters

buffer

Byte[]

An array of type Byte that is the storage location for the received data.

offset

Int32

The location in buffer to store the received data.

size

Int32

The number of bytes to receive.

socketFlags

SocketFlags

A bitwise combination of the SocketFlags values.

errorCode

SocketError

A SocketError object that stores the socket error.

callback

AsyncCallback

An AsyncCallback delegate that references the method to invoke when the operation is complete.

state

Object

A user-defined object that contains information about the receive operation. This object is passed to the EndReceive(IAsyncResult) delegate when the operation is complete.

Returns

IAsyncResult

An IAsyncResult that references the asynchronous read.

Exceptions

ArgumentNullException

buffer is null.

SocketException

.NET Framework and .NET 5 and earlier only: An error occurred when attempting to access the socket.

ObjectDisposedException

Socket has been closed.

ArgumentOutOfRangeException

offset is less than 0.

-or-

offset is greater than the length of buffer.

-or-

size is less than 0.

-or-

size is greater than the length of buffer minus the value of the offset parameter.

Remarks

Important

This is a compatibility API. We don't recommend using the APM (Begin* and End*) methods for new development. Instead, use the Task-based equivalents.

You can pass a callback that implements AsyncCallback to BeginReceive 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 BeginReceive. 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 BeginReceive method.

The asynchronous BeginReceive operation must be completed by calling the EndReceive method. Typically, the method is invoked by the AsyncCallback delegate. EndReceive will block the calling thread until the operation is completed.

Close the Socket to cancel a pending BeginReceive. When the Close method is called while an asynchronous operation is in progress, the callback provided to the BeginReceive method is called. A subsequent call to the EndReceive method will throw an ObjectDisposedException (before .NET 7) or a SocketException (on .NET 7+) to indicate that the operation has been cancelled.

Note

If you receive a SocketException, use the SocketException.ErrorCode property to obtain the specific error code.

Note

All I/O initiated by a given thread is canceled when that thread exits. A pending asynchronous operation can fail if the thread exits before the operation completes.

Note

state is an instantiation of a user-defined class.

Note

This member outputs trace information when you enable network tracing in your application. For more information, see Network Tracing in .NET Framework.

Note

The execution context (the security context, the impersonated user, and the calling context) is cached for the asynchronous Socket methods. After the first use of a particular context (a specific asynchronous Socket method, a specific Socket instance, and a specific callback), subsequent uses of that context will see a performance improvement.

See also

• EndAccept(IAsyncResult)
• AsyncCallback
• Connect(EndPoint)
• BeginReceiveFrom(Byte[], Int32, Int32, SocketFlags, EndPoint, AsyncCallback, Object)
• Marshaling a Delegate as a Callback Method
• Asynchronous Client Socket Example
• Asynchronous Server Socket Example

BeginReceive(Byte[], Int32, Int32, SocketFlags, AsyncCallback, Object)

Source:

Socket.cs

Begins to asynchronously receive data from a connected Socket.

public:
 IAsyncResult ^ BeginReceive(cli::array <System::Byte> ^ buffer, int offset, int size, System::Net::Sockets::SocketFlags socketFlags, AsyncCallback ^ callback, System::Object ^ state);

public IAsyncResult BeginReceive (byte[] buffer, int offset, int size, System.Net.Sockets.SocketFlags socketFlags, AsyncCallback? callback, object? state);

member this.BeginReceive : byte[] * int * int * System.Net.Sockets.SocketFlags * AsyncCallback * obj -> IAsyncResult

Public Function BeginReceive (buffer As Byte(), offset As Integer, size As Integer, socketFlags As SocketFlags, callback As AsyncCallback, state As Object) As IAsyncResult

Parameters

buffer

Byte[]

An array of type Byte that is the storage location for the received data.

offset

Int32

The zero-based position in the buffer parameter at which to store the received data.

size

Int32

The number of bytes to receive.

socketFlags

SocketFlags

A bitwise combination of the SocketFlags values.

callback

AsyncCallback

An AsyncCallback delegate that references the method to invoke when the operation is complete.

state

Object

A user-defined object that contains information about the receive operation. This object is passed to the EndReceive(IAsyncResult) delegate when the operation is complete.

Returns

IAsyncResult

An IAsyncResult that references the asynchronous read.

Exceptions

ArgumentNullException

buffer is null.

SocketException

.NET Framework and .NET 5 and earlier only: An error occurred when attempting to access the socket.

ObjectDisposedException

Socket has been closed.

ArgumentOutOfRangeException

offset is less than 0.

-or-

offset is greater than the length of buffer.

-or-

size is less than 0.

-or-

size is greater than the length of buffer minus the value of the offset parameter.

Remarks

Important

This is a compatibility API. We don't recommend using the APM (Begin* and End*) methods for new development. Instead, use the Task-based equivalents.

You can pass a callback that implements AsyncCallback to BeginReceive 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 BeginReceive. 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 BeginReceive method.

The asynchronous BeginReceive operation must be completed by calling the EndReceive method. Typically, the method is invoked by the AsyncCallback delegate. EndReceive will block the calling thread until the operation is completed.

Close the Socket to cancel a pending BeginReceive. When the Close method is called while an asynchronous operation is in progress, the callback provided to the BeginReceive method is called. A subsequent call to the EndReceive method will throw an ObjectDisposedException (before .NET 7) or a SocketException (on .NET 7+) to indicate that the operation has been cancelled.

Note

If you receive a SocketException, use the SocketException.ErrorCode property to obtain the specific error code.

Note

All I/O initiated by a given thread is canceled when that thread exits. A pending asynchronous operation can fail if the thread exits before the operation completes.

Note

state is an instantiation of a user-defined class.

Note

This member outputs trace information when you enable network tracing in your application. For more information, see Network Tracing in .NET Framework.

Note

The execution context (the security context, the impersonated user, and the calling context) is cached for the asynchronous Socket methods. After the first use of a particular context (a specific asynchronous Socket method, a specific Socket instance, and a specific callback), subsequent uses of that context will see a performance improvement.

See also

• EndAccept(IAsyncResult)
• AsyncCallback
• Connect(EndPoint)
• BeginReceiveFrom(Byte[], Int32, Int32, SocketFlags, EndPoint, AsyncCallback, Object)
• Marshaling a Delegate as a Callback Method
• Asynchronous Client Socket Example
• Asynchronous Server Socket Example

BeginReceive(IList<ArraySegment<Byte>>, SocketFlags, AsyncCallback, Object)

Source:

Socket.cs

Begins to asynchronously receive data from a connected Socket.

public:
 IAsyncResult ^ BeginReceive(System::Collections::Generic::IList<ArraySegment<System::Byte>> ^ buffers, System::Net::Sockets::SocketFlags socketFlags, AsyncCallback ^ callback, System::Object ^ state);

public IAsyncResult BeginReceive (System.Collections.Generic.IList<ArraySegment<byte>> buffers, System.Net.Sockets.SocketFlags socketFlags, AsyncCallback? callback, object? state);

member this.BeginReceive : System.Collections.Generic.IList<ArraySegment<byte>> * System.Net.Sockets.SocketFlags * AsyncCallback * obj -> IAsyncResult

Public Function BeginReceive (buffers As IList(Of ArraySegment(Of Byte)), socketFlags As SocketFlags, callback As AsyncCallback, state As Object) As IAsyncResult

Parameters

buffers

IList<ArraySegment<Byte>>

An array of type Byte that is the storage location for the received data.

socketFlags

SocketFlags

A bitwise combination of the SocketFlags values.

callback

AsyncCallback

An AsyncCallback delegate that references the method to invoke when the operation is complete.

state

Object

A user-defined object that contains information about the receive operation. This object is passed to the EndReceive(IAsyncResult) delegate when the operation is complete.

Returns

IAsyncResult

An IAsyncResult that references the asynchronous read.

Exceptions

ArgumentNullException

buffer is null.

SocketException

.NET Framework and .NET 5 and earlier only: An error occurred when attempting to access the socket.

ObjectDisposedException

Socket has been closed.

Remarks

Important

This is a compatibility API. We don't recommend using the APM (Begin* and End*) methods for new development. Instead, use the Task-based equivalents.

You can pass a callback that implements AsyncCallback to BeginReceive 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 BeginReceive. 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 BeginReceive method.

The asynchronous BeginReceive operation must be completed by calling the EndReceive method. Typically, the method is invoked by the AsyncCallback delegate. EndReceive will block the calling thread until the operation is completed.

Close the Socket to cancel a pending BeginReceive. When the Close method is called while an asynchronous operation is in progress, the callback provided to the BeginReceive method is called. A subsequent call to the EndReceive method will throw an ObjectDisposedException (before .NET 7) or a SocketException (on .NET 7+) to indicate that the operation has been cancelled.

Note

If you receive a SocketException, use the SocketException.ErrorCode property to obtain the specific error code.

Note

All I/O initiated by a given thread is canceled when that thread exits. A pending asynchronous operation can fail if the thread exits before the operation completes.

Note

state is an instantiation of a user-defined class.

Note

This member outputs trace information when you enable network tracing in your application. For more information, see Network Tracing in .NET Framework.

Note

The execution context (the security context, the impersonated user, and the calling context) is cached for the asynchronous Socket methods. After the first use of a particular context (a specific asynchronous Socket method, a specific Socket instance, and a specific callback), subsequent uses of that context will see a performance improvement.

See also

• EndAccept(IAsyncResult)
• AsyncCallback
• Connect(EndPoint)
• BeginReceiveFrom(Byte[], Int32, Int32, SocketFlags, EndPoint, AsyncCallback, Object)
• Marshaling a Delegate as a Callback Method
• Asynchronous Client Socket Example
• Asynchronous Server Socket Example

BeginReceive(IList<ArraySegment<Byte>>, SocketFlags, SocketError, AsyncCallback, Object)

Source:

Socket.cs

Begins to asynchronously receive data from a connected Socket.

public:
 IAsyncResult ^ BeginReceive(System::Collections::Generic::IList<ArraySegment<System::Byte>> ^ buffers, System::Net::Sockets::SocketFlags socketFlags, [Runtime::InteropServices::Out] System::Net::Sockets::SocketError % errorCode, AsyncCallback ^ callback, System::Object ^ state);

public IAsyncResult? BeginReceive (System.Collections.Generic.IList<ArraySegment<byte>> buffers, System.Net.Sockets.SocketFlags socketFlags, out System.Net.Sockets.SocketError errorCode, AsyncCallback? callback, object? state);

member this.BeginReceive : System.Collections.Generic.IList<ArraySegment<byte>> * System.Net.Sockets.SocketFlags * SocketError * AsyncCallback * obj -> IAsyncResult

Public Function BeginReceive (buffers As IList(Of ArraySegment(Of Byte)), socketFlags As SocketFlags, ByRef errorCode As SocketError, callback As AsyncCallback, state As Object) As IAsyncResult

Parameters

buffers

IList<ArraySegment<Byte>>

An array of type Byte that is the storage location for the received data.

socketFlags

SocketFlags

A bitwise combination of the SocketFlags values.

errorCode

SocketError

A SocketError object that stores the socket error.

callback

AsyncCallback

An AsyncCallback delegate that references the method to invoke when the operation is complete.

state

Object

A user-defined object that contains information about the receive operation. This object is passed to the EndReceive(IAsyncResult) delegate when the operation is complete.

Returns

IAsyncResult

An IAsyncResult that references the asynchronous read.

Exceptions

ArgumentNullException

buffer is null.

SocketException

.NET Framework and .NET 5 and earlier only: An error occurred when attempting to access the socket.

ObjectDisposedException

Socket has been closed.

Remarks

Important

This is a compatibility API. We don't recommend using the APM (Begin* and End*) methods for new development. Instead, use the Task-based equivalents.

You can pass a callback that implements AsyncCallback to BeginReceive 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 BeginReceive. 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 BeginReceive method.

The asynchronous BeginReceive operation must be completed by calling the EndReceive method. Typically, the method is invoked by the AsyncCallback delegate. EndReceive will block the calling thread until the operation is completed.

Close the Socket to cancel a pending BeginReceive. When the Close method is called while an asynchronous operation is in progress, the callback provided to the BeginReceive method is called. A subsequent call to the EndReceive method will throw an ObjectDisposedException (before .NET 7) or a SocketException (on .NET 7+) to indicate that the operation has been cancelled.

Note

If you receive a SocketException, use the SocketException.ErrorCode property to obtain the specific error code.

Note

All I/O initiated by a given thread is canceled when that thread exits. A pending asynchronous operation can fail if the thread exits before the operation completes.

Note

state is an instantiation of a user-defined class.

Note

This member outputs trace information when you enable network tracing in your application. For more information, see Network Tracing in .NET Framework.

Note

The execution context (the security context, the impersonated user, and the calling context) is cached for the asynchronous Socket methods. After the first use of a particular context (a specific asynchronous Socket method, a specific Socket instance, and a specific callback), subsequent uses of that context will see a performance improvement.

See also

• EndAccept(IAsyncResult)
• AsyncCallback
• Connect(EndPoint)
• BeginReceiveFrom(Byte[], Int32, Int32, SocketFlags, EndPoint, AsyncCallback, Object)
• Marshaling a Delegate as a Callback Method
• Asynchronous Client Socket Example
• Asynchronous Server Socket Example