SocketAsyncEventArgs Class
Represents an asynchronous socket operation.
Namespace: System.Net.Sockets
Assembly: System.Net (in System.Net.dll)
The SocketAsyncEventArgs type exposes the following members.
| Name | Description | |
|---|---|---|
![]() ![]() | Buffer | Gets the data buffer to use with an asynchronous socket method. |
![]() ![]() | BufferList | Gets or sets an array of data buffers to use with an asynchronous socket method. |
![]() ![]() | BytesTransferred | Gets the number of bytes transferred in the socket operation. |
![]() ![]() | ConnectByNameError | Gets the exception in the case of a connection failure when a DnsEndPoint was used. |
![]() ![]() | ConnectSocket | The created and connected Socket object after successful completion of the ConnectAsync method. |
![]() ![]() | Count | Gets the maximum amount of data, in bytes, to send or receive in an asynchronous operation. |
![]() ![]() | LastOperation | Gets the type of socket operation most recently performed with this object. |
![]() ![]() | Offset | Gets the offset, in bytes, into the data buffer referenced by the Buffer property. |
![]() ![]() | RemoteEndPoint | Gets or sets the remote IP or DNS endpoint for an asynchronous operation. |
![]() | SocketClientAccessPolicyProtocol | Gets or sets the method to download the policy file that an instance of the Socket class will use. |
![]() ![]() | SocketError | Gets or sets the result of the asynchronous socket operation. |
![]() ![]() | UserToken | Gets or sets a user or application object associated with this asynchronous socket operation. |
| Name | Description | |
|---|---|---|
![]() ![]() | Dispose | Releases the unmanaged resources used by the SocketAsyncEventArgs instance and optionally disposes of the managed resources. |
![]() ![]() | Equals(Object) | Determines whether the specified Object is equal to the current Object. (Inherited from Object.) |
![]() ![]() | Finalize | Frees resources used by the SocketAsyncEventArgs class. (Overrides Object::Finalize().) |
![]() ![]() | GetHashCode | Serves as a hash function for a particular type. (Inherited from Object.) |
![]() ![]() | GetType | Gets the Type of the current instance. (Inherited from Object.) |
![]() ![]() | MemberwiseClone | Creates a shallow copy of the current Object. (Inherited from Object.) |
![]() ![]() | OnCompleted | Represents a method that is called when an asynchronous operation completes. |
![]() ![]() | SetBuffer(Int32, Int32) | Sets the data buffer to use with an asynchronous socket method. |
![]() ![]() | SetBuffer(array<Byte>, Int32, Int32) | Sets the data buffer to use with an asynchronous socket method. |
![]() ![]() | ToString | Returns a string that represents the current object. (Inherited from Object.) |
The SocketAsyncEventArgs class provides an asynchronous pattern used by socket applications. The main feature of this pattern is the avoidance of the repeated allocation and synchronization of objects during asynchronous socket I/O.
In the System.Net.Sockets::Socket class, asynchronous socket operations are described by reusable SocketAsyncEventArgs objects allocated and maintained by the application. Socket applications know best the amount of overlapped socket operations that must be sustained. The application can create as many of the SocketAsyncEventArgs objects that it needs. For example, if an application needs to have 15 socket send or receive operations outstanding at all times to support outgoing client connection rates, it can allocate 15 reusable SocketAsyncEventArgs objects for that purpose.
The pattern for performing an asynchronous socket operation with this class consists of the following steps:
Allocate a new SocketAsyncEventArgs object, or get a free one from an application pool.
Set properties on the SocketAsyncEventArgs object required for the operation about to be performed (the completion callback delegate method, the data buffer, the offset into the buffer, and the maximum amount of data to transfer for the ReceiveAsync and SendAsync methods, for example).
Call the appropriate socket method (ConnectAsync, ReceiveAsync, or SendAsync) to initiate the asynchronous operation.
If the asynchronous socket method returns true, the I/O operation is pending. The SocketAsyncEventArgs::Completed event on the System.Net.Sockets::SocketAsyncEventArgs object passed to the socket method will be raised upon completion of the operation. When the event is raised in the event handler, query the SocketAsyncEventArgs properties for the completion status and socket operation result (the amount of received data in the buffer for ReceiveAsync method call, for example).
If the asynchronous socket method returns false, the operation completed synchronously. The SocketAsyncEventArgs properties may be queried for the completion status and socket operation result.
Reuse the SocketAsyncEventArgs object for another operation, put it back in the pool, or discard it.
The lifetime of the new SocketAsyncEventArgs object used in an asynchronous socket operation is determined by references in the application code and asynchronous I/O references. It is not necessary for the application to retain a reference to a SocketAsyncEventArgs object after it is submitted as a parameter to one of the asynchronous socket methods. It will remain referenced until the completion callback returns. However it is advantageous for the application to retain the reference to the SocketAsyncEventArgs object so that it can be reused for a future asynchronous socket operation.
The following example creates two instances of the SocketAsyncEventArgs class, one for use with the ConnectAsync method and one for use with the ReceiveAsync method. The SocketAsyncEventArgs instance for use on the connect operation still needs the RemoteEndPoint property set to a DnsEndPoint instance for the host before the ConnectAsync method is called.
public class Example { static ManualResetEvent clientDone = new ManualResetEvent(false); public static void Demo(System.Windows.Controls.TextBlock outputBlock) { SocketAsyncEventArgs socketEventArg = new SocketAsyncEventArgs(); DnsEndPoint hostEntry = new DnsEndPoint("http://www.contoso.com", 80); // Create a socket and connect to the server Socket sock = new Socket(AddressFamily.InterNetwork, SocketType.Stream, ProtocolType.Tcp); socketEventArg.Completed += new EventHandler<SocketAsyncEventArgs>(SocketEventArg_Completed); socketEventArg.RemoteEndPoint = hostEntry; socketEventArg.UserToken = sock; sock.ConnectAsync(socketEventArg); clientDone.WaitOne(); } // A single callback is used for all socket operations. // This method forwards execution on to the correct handler // based on the type of completed operation static void SocketEventArg_Completed(object sender, SocketAsyncEventArgs e) { switch (e.LastOperation) { case SocketAsyncOperation.Connect: ProcessConnect(e); break; case SocketAsyncOperation.Receive: ProcessReceive(e); break; case SocketAsyncOperation.Send: ProcessSend(e); break; default: throw new Exception("Invalid operation completed"); } } // Called when a ConnectAsync operation completes private static void ProcessConnect(SocketAsyncEventArgs e) { if (e.SocketError == SocketError.Success) { // Successfully connected to the server // Send 'Hello World' to the server byte[] buffer = Encoding.UTF8.GetBytes("Hello World"); e.SetBuffer(buffer, 0, buffer.Length); Socket sock = e.UserToken as Socket; bool willRaiseEvent = sock.SendAsync(e); if (!willRaiseEvent) { ProcessSend(e); } } else { throw new SocketException((int)e.SocketError); } } // Called when a ReceiveAsync operation completes // </summary> private static void ProcessReceive(SocketAsyncEventArgs e) { if (e.SocketError == SocketError.Success) { // Received data from server // Data has now been sent and received from the server. // Disconnect from the server Socket sock = e.UserToken as Socket; sock.Shutdown(SocketShutdown.Send); sock.Close(); clientDone.Set(); } else { throw new SocketException((int)e.SocketError); } } // Called when a SendAsync operation completes private static void ProcessSend(SocketAsyncEventArgs e) { if (e.SocketError == SocketError.Success) { // Sent "Hello World" to the server successfully //Read data sent from the server Socket sock = e.UserToken as Socket; bool willRaiseEvent = sock.ReceiveAsync(e); if (!willRaiseEvent) { ProcessReceive(e); } } else { throw new SocketException((int)e.SocketError); } } }
For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.
