Socket.BeginConnect Method

Definition

Namespace:

System.Net.Sockets

Assembly:

System.Net.Sockets.dll

Begins an asynchronous request for a remote host connection.

Overloads

BeginConnect(EndPoint, AsyncCallback, Object)	Begins an asynchronous request for a remote host connection.
BeginConnect(IPAddress, Int32, AsyncCallback, Object)	Begins an asynchronous request for a remote host connection. The host is specified by an IPAddress and a port number.
BeginConnect(IPAddress[], Int32, AsyncCallback, Object)	Begins an asynchronous request for a remote host connection. The host is specified by an IPAddress array and a port number.
BeginConnect(String, Int32, AsyncCallback, Object)	Begins an asynchronous request for a remote host connection. The host is specified by a host name and a port number.

BeginConnect(EndPoint, AsyncCallback, Object)

Source:

Socket.cs

Begins an asynchronous request for a remote host connection.

public:
 IAsyncResult ^ BeginConnect(System::Net::EndPoint ^ remoteEP, AsyncCallback ^ callback, System::Object ^ state);

public IAsyncResult BeginConnect (System.Net.EndPoint remoteEP, AsyncCallback? callback, object? state);

member this.BeginConnect : System.Net.EndPoint * AsyncCallback * obj -> IAsyncResult

Public Function BeginConnect (remoteEP As EndPoint, callback As AsyncCallback, state As Object) As IAsyncResult

Parameters

remoteEP

EndPoint

An EndPoint that represents the remote host.

callback

AsyncCallback

The AsyncCallback delegate.

state

Object

An object that contains state information for this request.

Returns

IAsyncResult

An IAsyncResult that references the asynchronous connection.

Exceptions

ArgumentNullException

remoteEP is null.

SocketException

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

ObjectDisposedException

The Socket has been closed.

SecurityException

A caller higher in the call stack does not have permission for the requested operation.

InvalidOperationException

The Socket has been placed in a listening state by calling Listen(Int32), or an asynchronous operation is already in progress.

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.

Connection-oriented protocols can use the BeginAccept method to start accepting incoming connection attempts. The resulting accept operation is represented by the returned IAsyncResult even though it may complete synchronously. Before calling the BeginAccept method, you must call the Listen method to listen for and queue incoming connection requests.

You can pass a callback that implements AsyncCallback to BeginAccept in order to get notified about the completion of the accept operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to BeginAccept. 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 BeginAccept method.

The BeginAccept operation must be completed by calling the EndAccept method. Typically, the method is invoked by the provided AsyncCallback delegate. EndAccept will block the calling thread until the operation is completed.

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

Note

You can use the RemoteEndPoint property of the returned Socket to identify the remote host's network address and port number.

Note

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

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

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

BeginConnect(IPAddress, Int32, AsyncCallback, Object)

Source:

Socket.cs

Begins an asynchronous request for a remote host connection. The host is specified by an IPAddress and a port number.

public:
 IAsyncResult ^ BeginConnect(System::Net::IPAddress ^ address, int port, AsyncCallback ^ requestCallback, System::Object ^ state);

public IAsyncResult BeginConnect (System.Net.IPAddress address, int port, AsyncCallback? requestCallback, object? state);

member this.BeginConnect : System.Net.IPAddress * int * AsyncCallback * obj -> IAsyncResult

Public Function BeginConnect (address As IPAddress, port As Integer, requestCallback As AsyncCallback, state As Object) As IAsyncResult

Parameters

address

IPAddress

The IPAddress of the remote host.

port

Int32

The port number of the remote host.

requestCallback

AsyncCallback

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

state

Object

A user-defined object that contains information about the connect operation. This object is passed to the requestCallback delegate when the operation is complete.

Returns

IAsyncResult

An IAsyncResult that references the asynchronous connection.

Exceptions

ArgumentNullException

address is null.

SocketException

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

ObjectDisposedException

The Socket has been closed.

NotSupportedException

The Socket is not in the socket family.

ArgumentOutOfRangeException

The port number is not valid.

ArgumentException

The length of address is zero.

InvalidOperationException

The Socket has been placed in a listening state by calling Listen(Int32), or an asynchronous operation is already in progress.

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.

If you are using a connection-oriented protocol, the BeginConnect method starts an asynchronous request for a connection to the endpoit specified by the remoteEP parameter. If you are using a connectionless protocol, BeginConnect establishes a default remote host.

You can pass a callback that implements AsyncCallback to BeginConnect in order to get notified about the completion of the connect operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to BeginConnect. 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 BeginConnect method.

The BeginConnect operation must be completed by calling the EndConnect method. Typically, the method is invoked by the provided AsyncCallback delegate. EndConnect will block the calling thread until the operation is completed.

If you are using a connectionless protocol such as UDP, you do not have to call BeginConnect before sending and receiving data. You can use BeginSendTo and BeginReceiveFrom to communicate with a remote host. If you do call BeginConnect, any datagrams that arrive from an address other than the specified default will be discarded. If you wish to set your default remote host to a broadcast address, you must first call SetSocketOption and set Broadcast to true. If you cannot, BeginConnect will throw a SocketException.

If you are using a connection-oriented protocol and do not call Bind before calling BeginConnect, the underlying service provider will assign the most appropriate local network address and port number. If you are using a connectionless protocol, the service provider will not assign a local network address and port number until you call the BeginSend or ReceiveFrom method. If you want to change the default remote host, call the BeginConnect method again with the desired endpoint.

To cancel a pending call to the BeginConnect method, close the Socket. When the Close method is called while an asynchronous operation is in progress, the callback provided to the BeginConnect method is called. A subsequent call to the EndConnect 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

If this socket has previously been disconnected, then BeginConnect must be called on a thread that will not exit until the operation is complete. This is a limitation of the underlying provider.

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

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

BeginConnect(IPAddress[], Int32, AsyncCallback, Object)

Source:

Socket.cs

Begins an asynchronous request for a remote host connection. The host is specified by an IPAddress array and a port number.

public:
 IAsyncResult ^ BeginConnect(cli::array <System::Net::IPAddress ^> ^ addresses, int port, AsyncCallback ^ requestCallback, System::Object ^ state);

public IAsyncResult BeginConnect (System.Net.IPAddress[] addresses, int port, AsyncCallback? requestCallback, object? state);

member this.BeginConnect : System.Net.IPAddress[] * int * AsyncCallback * obj -> IAsyncResult

Public Function BeginConnect (addresses As IPAddress(), port As Integer, requestCallback As AsyncCallback, state As Object) As IAsyncResult

Parameters

addresses

IPAddress[]

At least one IPAddress, designating the remote host.

port

Int32

The port number of the remote host.

requestCallback

AsyncCallback

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

state

Object

A user-defined object that contains information about the connect operation. This object is passed to the requestCallback delegate when the operation is complete.

Returns

IAsyncResult

An IAsyncResult that references the asynchronous connections.

Exceptions

ArgumentNullException

addresses is null.

SocketException

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

ObjectDisposedException

The Socket has been closed.

NotSupportedException

This method is valid for sockets that use InterNetwork or InterNetworkV6.

ArgumentOutOfRangeException

The port number is not valid.

ArgumentException

The length of address is zero.

InvalidOperationException

The Socket has been placed in a listening state by calling Listen(Int32), or an asynchronous operation is already in progress.

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.

If you are using a connection-oriented protocol, the BeginConnect method starts an asynchronous request for a connection to the endpoit specified by the remoteEP parameter. If you are using a connectionless protocol, BeginConnect establishes a default remote host.

You can pass a callback that implements AsyncCallback to BeginConnect in order to get notified about the completion of the connect operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to BeginConnect. 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 BeginConnect method.

The BeginConnect operation must be completed by calling the EndConnect method. Typically, the method is invoked by the provided AsyncCallback delegate. EndConnect will block the calling thread until the operation is completed.

If you are using a connectionless protocol such as UDP, you do not have to call BeginConnect before sending and receiving data. You can use BeginSendTo and BeginReceiveFrom to communicate with a remote host. If you do call BeginConnect, any datagrams that arrive from an address other than the specified default will be discarded. If you wish to set your default remote host to a broadcast address, you must first call SetSocketOption and set Broadcast to true. If you cannot, BeginConnect will throw a SocketException.

If you are using a connection-oriented protocol and do not call Bind before calling BeginConnect, the underlying service provider will assign the most appropriate local network address and port number. If you are using a connectionless protocol, the service provider will not assign a local network address and port number until you call the BeginSend or ReceiveFrom method. If you want to change the default remote host, call the BeginConnect method again with the desired endpoint.

To cancel a pending call to the BeginConnect method, close the Socket. When the Close method is called while an asynchronous operation is in progress, the callback provided to the BeginConnect method is called. A subsequent call to the EndConnect 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

If this socket has previously been disconnected, then BeginConnect must be called on a thread that will not exit until the operation is complete. This is a limitation of the underlying provider.

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

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

BeginConnect(String, Int32, AsyncCallback, Object)

Source:

Socket.cs

Begins an asynchronous request for a remote host connection. The host is specified by a host name and a port number.

public:
 IAsyncResult ^ BeginConnect(System::String ^ host, int port, AsyncCallback ^ requestCallback, System::Object ^ state);

public IAsyncResult BeginConnect (string host, int port, AsyncCallback? requestCallback, object? state);

member this.BeginConnect : string * int * AsyncCallback * obj -> IAsyncResult

Public Function BeginConnect (host As String, port As Integer, requestCallback As AsyncCallback, state As Object) As IAsyncResult

Parameters

host

String

The name of the remote host.

port

Int32

The port number of the remote host.

requestCallback

AsyncCallback

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

state

Object

A user-defined object that contains information about the connect operation. This object is passed to the requestCallback delegate when the operation is complete.

Returns

IAsyncResult

An IAsyncResult that references the asynchronous connection.

Exceptions

ArgumentNullException

host is null.

ObjectDisposedException

The Socket has been closed.

NotSupportedException

This method is valid for sockets in the InterNetwork or InterNetworkV6 families.

ArgumentOutOfRangeException

The port number is not valid.

InvalidOperationException

The Socket has been placed in a listening state by calling Listen(Int32), or an asynchronous operation is already in progress.

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.

If you are using a connection-oriented protocol, the BeginConnect method starts an asynchronous request for a connection to the endpoit specified by the remoteEP parameter. If you are using a connectionless protocol, BeginConnect establishes a default remote host.

You can pass a callback that implements AsyncCallback to BeginConnect in order to get notified about the completion of the connect operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to BeginConnect. 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 BeginConnect method.

The BeginConnect operation must be completed by calling the EndConnect method. Typically, the method is invoked by the provided AsyncCallback delegate. EndConnect will block the calling thread until the operation is completed.

If you are using a connectionless protocol such as UDP, you do not have to call BeginConnect before sending and receiving data. You can use BeginSendTo and BeginReceiveFrom to communicate with a remote host. If you do call BeginConnect, any datagrams that arrive from an address other than the specified default will be discarded. If you wish to set your default remote host to a broadcast address, you must first call SetSocketOption and set Broadcast to true. If you cannot, BeginConnect will throw a SocketException.

If you are using a connection-oriented protocol and do not call Bind before calling BeginConnect, the underlying service provider will assign the most appropriate local network address and port number. If you are using a connectionless protocol, the service provider will not assign a local network address and port number until you call the BeginSend or ReceiveFrom method. If you want to change the default remote host, call the BeginConnect method again with the desired endpoint.

To cancel a pending call to the BeginConnect method, close the Socket. When the Close method is called while an asynchronous operation is in progress, the callback provided to the BeginConnect method is called. A subsequent call to the EndConnect 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

If this socket has previously been disconnected, then BeginConnect must be called on a thread that will not exit until the operation is complete. This is a limitation of the underlying provider.

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

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