Socket.BeginReceive Method

Reference

Definition

Namespace:: System.Net.Sockets

Assembly:: System.Net.Sockets.dll

Assembly:: System.dll

Assembly:: netstandard.dll

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 to asynchronously receive data from a connected Socket.

Overloads

BeginReceive(Byte[], Int32, Int32, SocketFlags, AsyncCallback, Object)	Begins to asynchronously receive data from a connected Socket.
BeginReceive(Byte[], Int32, Int32, SocketFlags, SocketError, 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, AsyncCallback, Object)

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(cli::array <System::Byte> ^ buffer, int offset, int size, System::Net::Sockets::SocketFlags socket_flags, AsyncCallback ^ callback, System::Object ^ state);

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

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

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

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

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

Public Function BeginReceive (buffer As Byte(), offset As Integer, size As Integer, socket_flags 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.

socketFlagssocket_flags: 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.

Examples

The following code example begins to asynchronously receive data from a connected Socket.

public ref class StateObject
{
public:
   literal int BUFFER_SIZE = 1024;
   Socket^ workSocket;
   array<Byte>^ buffer;
   StringBuilder^ sb;
   StateObject() : workSocket( nullptr )
   {
      buffer = gcnew array<Byte>(BUFFER_SIZE);
      sb = gcnew StringBuilder;
   }
};

public class StateObject{
     public Socket workSocket = null;
     public const int BUFFER_SIZE = 1024;
     public byte[] buffer = new byte[BUFFER_SIZE];
     public StringBuilder sb = new StringBuilder();
}

Public Class StateObject
   Public workSocket As Socket = Nothing
   Public const BUFFER_SIZE As Integer = 1024
   Public buffer(BUFFER_SIZE) As byte
   Public sb As New StringBuilder()
End Class

static void Listen_Callback( IAsyncResult^ ar )
{
   allDone->Set();
   Socket^ s = safe_cast<Socket^>(ar->AsyncState);
   Socket^ s2 = s->EndAccept( ar );
   StateObject^ so2 = gcnew StateObject;
   so2->workSocket = s2;
   s2->BeginReceive( so2->buffer, 0, StateObject::BUFFER_SIZE, SocketFlags::None,
      gcnew AsyncCallback( &Async_Send_Receive::Read_Callback ), so2 );
}

public static void Listen_Callback(IAsyncResult ar){
     allDone.Set();
     Socket s = (Socket) ar.AsyncState;
     Socket s2 = s.EndAccept(ar);
     StateObject so2 = new StateObject();
     so2.workSocket = s2;
     s2.BeginReceive(so2.buffer, 0, StateObject.BUFFER_SIZE,0,
                           new AsyncCallback(Async_Send_Receive.Read_Callback), so2);	
}

Public Shared Sub Listen_Callback(ar As IAsyncResult)
   allDone.Set()
   Dim s As Socket = CType(ar.AsyncState, Socket)
   Dim s2 As Socket = s.EndAccept(ar)
   Dim so2 As New StateObject()
   so2.workSocket = s2
   s2.BeginReceive(so2.buffer, 0, StateObject.BUFFER_SIZE, 0, New AsyncCallback(AddressOf Async_Send_Receive.Read_Callback), so2)
End Sub

static void Read_Callback( IAsyncResult^ ar )
{
   StateObject^ so = safe_cast<StateObject^>(ar->AsyncState);
   Socket^ s = so->workSocket;

   int read = s->EndReceive( ar );

   if ( read > 0 )
   {
      so->sb->Append( Encoding::ASCII->GetString( so->buffer, 0, read ) );
      s->BeginReceive( so->buffer, 0, StateObject::BUFFER_SIZE, SocketFlags::None,
         gcnew AsyncCallback( &Async_Send_Receive::Read_Callback ), so );
   }
   else
   {
      if ( so->sb->Length > 1 )
      {
         //All of the data has been read, so displays it to the console
         String^ strContent = so->sb->ToString();
         Console::WriteLine( String::Format( "Read {0} byte from socket" +
            " data = {1} ", strContent->Length, strContent ) );
      }
      s->Close();
   }
}

public static void Read_Callback(IAsyncResult ar){
    StateObject so = (StateObject) ar.AsyncState;
    Socket s = so.workSocket;

    int read = s.EndReceive(ar);

    if (read > 0) {
            so.sb.Append(Encoding.ASCII.GetString(so.buffer, 0, read));
            s.BeginReceive(so.buffer, 0, StateObject.BUFFER_SIZE, 0,
                                     new AsyncCallback(Async_Send_Receive.Read_Callback), so);
    }
    else{
         if (so.sb.Length > 1) {
              //All of the data has been read, so displays it to the console
              string strContent;
              strContent = so.sb.ToString();
              Console.WriteLine(String.Format("Read {0} byte from socket" +
                               "data = {1} ", strContent.Length, strContent));
         }
         s.Close();
    }
}

Public Shared Sub Read_Callback(ar As IAsyncResult)
   Dim so As StateObject = CType(ar.AsyncState, StateObject)
   Dim s As Socket = so.workSocket
   
   Dim read As Integer = s.EndReceive(ar)
   
   If read > 0 Then
      so.sb.Append(Encoding.ASCII.GetString(so.buffer, 0, read))
      s.BeginReceive(so.buffer, 0, StateObject.BUFFER_SIZE, 0, New AsyncCallback(AddressOf Async_Send_Receive.Read_Callback), so)
   Else
      If so.sb.Length > 1 Then
         'All the data has been read, so displays it to the console
         Dim strContent As String
         strContent = so.sb.ToString()
         Console.WriteLine([String].Format("Read {0} byte from socket" + "data = {1} ", strContent.Length, strContent))
      End If
      s.Close()
   End If
End Sub

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.

Applies to

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

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(cli::array <System::Byte> ^ buffer, int offset, int size, System::Net::Sockets::SocketFlags flags, [Runtime::InteropServices::Out] System::Net::Sockets::SocketError % error, 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);

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

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

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

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

Public Function BeginReceive (buffer As Byte(), offset As Integer, size As Integer, flags As SocketFlags, ByRef error 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.

socketFlagsflags: SocketFlags

A bitwise combination of the SocketFlags values.

errorCodeerror: 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.

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

Applies to

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

Important

This API is not CLS-compliant.

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);

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

[System.CLSCompliant(false)]
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

[<System.CLSCompliant(false)>]
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.

Attributes: CLSCompliantAttribute

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.

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

Applies to

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

Important

This API is not CLS-compliant.

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);

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);

[System.CLSCompliant(false)]
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

[<System.CLSCompliant(false)>]
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.

Attributes: CLSCompliantAttribute

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.

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

Applies to

Socket.BeginReceive Method

Definition

Overloads

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

Parameters

Returns

Exceptions

Examples

Remarks

See also

Applies to

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

Parameters

Returns

Exceptions

Remarks

See also

Applies to

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

Parameters

Returns

Exceptions

Remarks

See also

Applies to

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

Parameters

Returns

Exceptions

Remarks

See also

Applies to

Additional resources