Socket.BeginReceive Method (System.Net.Sockets)

Parameters

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

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 );
      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)
      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.
           
           
            If you receive a
            
             SocketException
            
            , use the
            
             SocketException.ErrorCode
            
            property to obtain the specific error code.
           
           
            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.
           
           
            
             state
            
            is an instantiation of a user-defined class.
           
           
            This member outputs trace information when you enable network tracing in your application. For more information, see
            
             Network Tracing in .NET Framework
            
            .
           
           
            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.
           
           
            
             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
            
           
           
            Applies to
           
           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
           
           
            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
           
           
            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.
           
           
            If you receive a
            
             SocketException
            
            , use the
            
             SocketException.ErrorCode
            
            property to obtain the specific error code.
           
           
            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.
           
           
            
             state
            
            is an instantiation of a user-defined class.
           
           
            This member outputs trace information when you enable network tracing in your application. For more information, see
            
             Network Tracing in .NET Framework
            
            .
           
           
            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.
           
           
            
             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
            
           
           
            Applies to
           
           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
           
           
            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
           
           
            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.
           
           
            If you receive a
            
             SocketException
            
            , use the
            
             SocketException.ErrorCode
            
            property to obtain the specific error code.
           
           
            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.
           
           
            
             state
            
            is an instantiation of a user-defined class.
           
           
            This member outputs trace information when you enable network tracing in your application. For more information, see
            
             Network Tracing in .NET Framework
            
            .
           
           
            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.
           
           
            
             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
            
           
           
            Applies to
           
           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
           
           
            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
           
           
            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.
           
           
            If you receive a
            
             SocketException
            
            , use the
            
             SocketException.ErrorCode
            
            property to obtain the specific error code.
           
           
            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.
           
           
            
             state
            
            is an instantiation of a user-defined class.
           
           
            This member outputs trace information when you enable network tracing in your application. For more information, see
            
             Network Tracing in .NET Framework
            
            .
           
           
            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.
           
           
            
             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
            
           
           
            Applies to