Socket.ConnectAsync Socket.ConnectAsync Socket.ConnectAsync Socket.ConnectAsync Method

定义

开始一个对远程主机连接的异步请求。Begins an asynchronous request for a connection to a remote host.

重载

ConnectAsync(SocketAsyncEventArgs) ConnectAsync(SocketAsyncEventArgs) ConnectAsync(SocketAsyncEventArgs) ConnectAsync(SocketAsyncEventArgs)

开始一个对远程主机连接的异步请求。Begins an asynchronous request for a connection to a remote host.

ConnectAsync(SocketType, ProtocolType, SocketAsyncEventArgs) ConnectAsync(SocketType, ProtocolType, SocketAsyncEventArgs) ConnectAsync(SocketType, ProtocolType, SocketAsyncEventArgs)

开始一个对远程主机连接的异步请求。Begins an asynchronous request for a connection to a remote host.

ConnectAsync(SocketAsyncEventArgs) ConnectAsync(SocketAsyncEventArgs) ConnectAsync(SocketAsyncEventArgs) ConnectAsync(SocketAsyncEventArgs)

开始一个对远程主机连接的异步请求。Begins an asynchronous request for a connection to a remote host.

public:
 bool ConnectAsync(System::Net::Sockets::SocketAsyncEventArgs ^ e);
public bool ConnectAsync (System.Net.Sockets.SocketAsyncEventArgs e);
member this.ConnectAsync : System.Net.Sockets.SocketAsyncEventArgs -> bool
Public Function ConnectAsync (e As SocketAsyncEventArgs) As Boolean

参数

e
SocketAsyncEventArgs SocketAsyncEventArgs SocketAsyncEventArgs SocketAsyncEventArgs

要用于此异步套接字操作的 SocketAsyncEventArgs 对象。The SocketAsyncEventArgs object to use for this asynchronous socket operation.

返回

如果 I/O 操作挂起,则为 truetrue if the I/O operation is pending. 操作完成时,将引发 e 参数的 Completed 事件。The Completed event on the e parameter will be raised upon completion of the operation.

如果 I/O 操作同步完成,则为 falsefalse if the I/O operation completed synchronously. 在这种情况下,将不会引发 e 参数的 Completed 事件,并且可能在方法调用返回后立即检查作为参数传递的 e 对象以检索操作的结果。In this case, The Completed event on the e parameter will not be raised and the e object passed as a parameter may be examined immediately after the method call returns to retrieve the result of the operation.

异常

自变量无效。An argument is not valid. 如果指定了多个缓冲区,即 BufferList 属性不为 null,将会发生此异常。This exception occurs if multiple buffers are specified, the BufferList property is not null.

e 参数不能为 null,并且 RemoteEndPoint 不能为空。The e parameter cannot be null and the RemoteEndPoint cannot be null.

Socket 正在侦听或已经在使用 e 参数中指定的 SocketAsyncEventArgs 对象执行套接字操作。The Socket is listening or a socket operation was already in progress using the SocketAsyncEventArgs object specified in the e parameter.

尝试访问套接字时出错。An error occurred when attempting to access the socket.

此方法需要 Windows XP 或更高版本。Windows XP or later is required for this method. 如果本地终结点和 RemoteEndPoint 不是相同的地址族,也会发生此异常。This exception also occurs if the local endpoint and the RemoteEndPoint are not the same address family.

调用堆栈中的较高调用方无权执行所请求的操作。A caller higher in the call stack does not have permission for the requested operation.

注解

如果使用面向连接的协议ConnectAsync方法启动与远程主机的连接的异步请求。If you are using a connection-oriented protocol, the ConnectAsync method starts an asynchronous request for a connection to the remote host. 如果您使用的是无连接协议,ConnectAsync建立默认远程主机。If you are using a connectionless protocol, ConnectAsync establishes a default remote host.

若要在完成时得到通知,必须创建实现事件处理程序的回调方法<SocketAsyncEventArgs > 委托并将附加到回调SocketAsyncEventArgs.Completed事件。To be notified of completion, you must create a callback method that implements the EventHandler<SocketAsyncEventArgs> delegate and attach the callback to the SocketAsyncEventArgs.Completed event.

调用方必须设置SocketAsyncEventArgs.RemoteEndPoint属性设置为IPEndPoint要连接到的远程主机。The caller must set the SocketAsyncEventArgs.RemoteEndPoint property to the IPEndPoint of the remote host to connect to.

调用方可能会设置SocketAsyncEventArgs.UserToken属性设置为在调用之前所需的任何用户状态对象ConnectAsync方法,以便可在回调方法中检索信息。The caller may set the SocketAsyncEventArgs.UserToken property to any user state object desired before calling the ConnectAsync method, so that the information will be retrievable in the callback method. 如果回调需要比单个对象的详细信息,可以创建一个小类来保存作为成员的其他所需的状态信息。If the callback needs more information than a single object, a small class can be created to hold the other required state information as members.

如果使用如 UDP 是无连接协议,不需要调用ConnectAsync之前发送和接收数据。If you are using a connectionless protocol such as UDP, you do not have to call ConnectAsync before sending and receiving data. 可以使用SendToAsyncReceiveFromAsync与远程主机通信。You can use SendToAsync and ReceiveFromAsync to communicate with a remote host. 如果调用ConnectAsync,将丢弃来自指定的默认值以外的地址的任何数据报。If you do call ConnectAsync, any datagrams that arrive from an address other than the specified default will be discarded. 如果你想要更改默认远程主机,则调用ConnectAsync方法再次使用所需终结点。If you want to change the default remote host, call the ConnectAsync method again with the desired endpoint.

如果你想要设置默认远程主机与广播地址,必须先调用SetSocketOption设置为广播和trueIf you wish to set the default remote host to a broadcast address, you must first call SetSocketOption and set Broadcast to true. 如果不执行此操作,ConnectAsync方法将引发SocketExceptionIf this is not done, the ConnectAsync method will throw a SocketException.

下列属性和事件上的System.Net.Sockets.SocketAsyncEventArgs对象所需:The following properties and events on the System.Net.Sockets.SocketAsyncEventArgs object are required:

(可选) 一个缓冲区可能会提供它以原子方式发送后在套接字上ConnectAsync方法成功。Optionally, a buffer may be provided which will atomically be sent on the socket after the ConnectAsync method succeeds. 在这种情况下,SocketAsyncEventArgs.Buffer属性应设置为包含数据的缓冲区,以发送和SocketAsyncEventArgs.Count属性应设置为的数据的字节数,以从缓冲区发送。In this case, the SocketAsyncEventArgs.Buffer property needs to be set to the buffer containing the data to send and the SocketAsyncEventArgs.Count property needs to be set to the number of bytes of data to send from the buffer. 一旦建立的连接,该缓冲区中的数据会被发送。Once a connection is established, this buffer of data is sent.

如果您使用的是面向连接的协议,并且不会调用Bind之前调用ConnectAsync,基础服务提供程序将分配的最合适的本地网络地址和端口号。If you are using a connection-oriented protocol and do not call Bind before calling ConnectAsync, the underlying service provider will assign the most appropriate local network address and port number.

如果您使用的是无连接协议,直到您调用,服务提供程序将不分配本地网络 IP 地址和端口号SendAsyncReceiveAsync方法。If you are using a connectionless protocol, the service provider will not assign a local network IP address and port number until you call the SendAsync or ReceiveAsync methods.

ConnectAsync方法会抛出NotSupportedException如果的地址族SocketSocketAsyncEventArgs.RemoteEndPoint不是同一地址系列。The ConnectAsync method throws NotSupportedException if the address family of the Socket and the SocketAsyncEventArgs.RemoteEndPoint are not the same address family.

备注

如果你收到SocketException调用此方法时,使用SocketException.ErrorCode属性来获取特定错误代码。If you receive a SocketException when calling this method, use the SocketException.ErrorCode property to obtain the specific error code. 获取此代码后,请参阅Windows 套接字版本 2 API 错误代码有关错误的详细说明的文档。After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation for a detailed description of the error.

另请参阅

ConnectAsync(SocketType, ProtocolType, SocketAsyncEventArgs) ConnectAsync(SocketType, ProtocolType, SocketAsyncEventArgs) ConnectAsync(SocketType, ProtocolType, SocketAsyncEventArgs)

开始一个对远程主机连接的异步请求。Begins an asynchronous request for a connection to a remote host.

public:
 static bool ConnectAsync(System::Net::Sockets::SocketType socketType, System::Net::Sockets::ProtocolType protocolType, System::Net::Sockets::SocketAsyncEventArgs ^ e);
public static bool ConnectAsync (System.Net.Sockets.SocketType socketType, System.Net.Sockets.ProtocolType protocolType, System.Net.Sockets.SocketAsyncEventArgs e);
static member ConnectAsync : System.Net.Sockets.SocketType * System.Net.Sockets.ProtocolType * System.Net.Sockets.SocketAsyncEventArgs -> bool

参数

socketType
SocketType SocketType SocketType SocketType

SocketType 值之一。One of the SocketType values.

protocolType
ProtocolType ProtocolType ProtocolType ProtocolType

ProtocolType 值之一。One of the ProtocolType values.

e
SocketAsyncEventArgs SocketAsyncEventArgs SocketAsyncEventArgs SocketAsyncEventArgs

要用于此异步套接字操作的 SocketAsyncEventArgs 对象。The SocketAsyncEventArgs object to use for this asynchronous socket operation.

返回

如果 I/O 操作挂起,则为 truetrue if the I/O operation is pending. 操作完成时,将引发 e 参数的 Completed 事件。The Completed event on the e parameter will be raised upon completion of the operation.

如果 I/O 操作同步完成,则为 falsefalse if the I/O operation completed synchronously. 在这种情况下,将不会引发 e 参数的 Completed 事件,并且可能在方法调用返回后立即检查作为参数传递的 e 对象以检索操作的结果。In this case, The Completed event on the e parameter will not be raised and the e object passed as a parameter may be examined immediately after the method call returns to retrieve the result of the operation.

异常

自变量无效。An argument is not valid. 如果指定了多个缓冲区,即 BufferList 属性不为 null,将会发生此异常。This exception occurs if multiple buffers are specified, the BufferList property is not null.

e 参数不能为 null,并且 RemoteEndPoint 不能为空。The e parameter cannot be null and the RemoteEndPoint cannot be null.

Socket 正在侦听或已经在使用 e 参数中指定的 SocketAsyncEventArgs 对象执行套接字操作。The Socket is listening or a socket operation was already in progress using the SocketAsyncEventArgs object specified in the e parameter.

尝试访问套接字时出错。An error occurred when attempting to access the socket.

此方法需要 Windows XP 或更高版本。Windows XP or later is required for this method. 如果本地终结点和 RemoteEndPoint 不是相同的地址族,也会发生此异常。This exception also occurs if the local endpoint and the RemoteEndPoint are not the same address family.

调用堆栈中的较高调用方无权执行所请求的操作。A caller higher in the call stack does not have permission for the requested operation.

注解

如果使用的是面向连接的协议,M:System.Net.Sockets.Socket.ConnectAsync(System.Net.Sockets.SocketType,System.Net.Sockets.ProtocolType,System.Net.Sockets.SocketAsyncEventArgs) 方法启动的异步请求连接到远程主机。If you are using a connection-oriented protocol, the M:System.Net.Sockets.Socket.ConnectAsync(System.Net.Sockets.SocketType,System.Net.Sockets.ProtocolType,System.Net.Sockets.SocketAsyncEventArgs) method starts an asynchronous request for a connection to the remote host. 如果使用的是无连接协议ConnectAsync建立默认远程主机由指定socketTypeprotocolType参数。If you are using a connectionless protocol, ConnectAsync establishes a default remote host specified by the socketType and protocolType parameters.

若要在完成时得到通知,必须创建实现事件处理程序的回调方法<SocketAsyncEventArgs > 委托并将附加到回调SocketAsyncEventArgs.Completed事件。To be notified of completion, you must create a callback method that implements the EventHandler<SocketAsyncEventArgs> delegate and attach the callback to the SocketAsyncEventArgs.Completed event.

调用方必须设置SocketAsyncEventArgs.RemoteEndPoint属性设置为IPEndPoint要连接到的远程主机。The caller must set the SocketAsyncEventArgs.RemoteEndPoint property to the IPEndPoint of the remote host to connect to.

调用方可能会设置SocketAsyncEventArgs.UserToken属性设置为在调用之前所需的任何用户状态对象ConnectAsync方法,以便可在回调方法中检索信息。The caller may set the SocketAsyncEventArgs.UserToken property to any user state object desired before calling the ConnectAsync method, so that the information will be retrievable in the callback method. 如果回调需要比单个对象的详细信息,可以创建一个小类来保存作为成员的其他所需的状态信息。If the callback needs more information than a single object, a small class can be created to hold the other required state information as members.

如果使用如 UDP 是无连接协议,不需要调用ConnectAsync之前发送和接收数据。If you are using a connectionless protocol such as UDP, you do not have to call ConnectAsync before sending and receiving data. 可以使用SendToAsyncReceiveFromAsync与远程主机通信。You can use SendToAsync and ReceiveFromAsync to communicate with a remote host. 如果调用ConnectAsync,将丢弃来自指定的默认值以外的地址的任何数据报。If you do call ConnectAsync, any datagrams that arrive from an address other than the specified default will be discarded. 如果你想要更改默认远程主机,则调用ConnectAsync方法再次使用所需终结点。If you want to change the default remote host, call the ConnectAsync method again with the desired endpoint.

如果你想要设置默认远程主机与广播地址,必须先调用SetSocketOption设置为广播和trueIf you wish to set the default remote host to a broadcast address, you must first call SetSocketOption and set Broadcast to true. 如果不执行此操作,ConnectAsync方法将引发SocketExceptionIf this is not done, the ConnectAsync method will throw a SocketException.

下列属性和事件上的System.Net.Sockets.SocketAsyncEventArgs对象所需:The following properties and events on the System.Net.Sockets.SocketAsyncEventArgs object are required:

(可选) 一个缓冲区可能会提供它以原子方式发送后在套接字上ConnectAsync方法成功。Optionally, a buffer may be provided which will atomically be sent on the socket after the ConnectAsync method succeeds. 在这种情况下,SocketAsyncEventArgs.Buffer属性应设置为包含数据的缓冲区,以发送和SocketAsyncEventArgs.Count属性应设置为的数据的字节数,以从缓冲区发送。In this case, the SocketAsyncEventArgs.Buffer property needs to be set to the buffer containing the data to send and the SocketAsyncEventArgs.Count property needs to be set to the number of bytes of data to send from the buffer. 一旦建立的连接,该缓冲区中的数据会被发送。Once a connection is established, this buffer of data is sent.

如果您使用的是面向连接的协议,并且不会调用Bind之前调用ConnectAsync,基础服务提供程序将分配的最合适的本地网络地址和端口号。If you are using a connection-oriented protocol and do not call Bind before calling ConnectAsync, the underlying service provider will assign the most appropriate local network address and port number.

如果您使用的是无连接协议,直到您调用,服务提供程序将不分配本地网络 IP 地址和端口号SendAsyncReceiveAsync方法。If you are using a connectionless protocol, the service provider will not assign a local network IP address and port number until you call the SendAsync or ReceiveAsync methods.

ConnectAsync方法会抛出NotSupportedException如果的地址族SocketSocketAsyncEventArgs.RemoteEndPoint不是同一地址系列。The ConnectAsync method throws NotSupportedException if the address family of the Socket and the SocketAsyncEventArgs.RemoteEndPoint are not the same address family.

备注

如果你收到SocketException调用此方法时,使用SocketException.ErrorCode属性来获取特定错误代码。If you receive a SocketException when calling this method, use the SocketException.ErrorCode property to obtain the specific error code. 获取此代码后,请参阅Windows 套接字版本 2 API 错误代码有关错误的详细说明的文档。After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation for a detailed description of the error.

适用于