StreamSocket.ConnectAsync 方法

定义

命名空间:

Windows.Networking.Sockets

重载

名称	说明
ConnectAsync(EndpointPair)	对 StreamSocket 对象启动异步操作，以连接到指定为 EndpointPair 对象的远程网络目标。
ConnectAsync(EndpointPair, SocketProtectionLevel)	对 StreamSocket 对象启动异步操作，以连接到指定为 EndpointPair 对象的远程网络目标，以及 SocketProtectionLevel 枚举。 此方法不可从 JavaScript 调用。
ConnectAsync(HostName, String)	对 StreamSocket 对象启动异步操作，以连接到远程主机名和远程服务名称指定的远程网络目标。
ConnectAsync(HostName, String, SocketProtectionLevel)	对 StreamSocket 对象启动异步操作，以连接到远程主机名、远程服务名称和 SocketProtectionLevel指定的远程目标。
ConnectAsync(HostName, String, SocketProtectionLevel, NetworkAdapter)	对指定的本地网络适配器上的 StreamSocket 对象启动异步操作，以连接到远程主机名、远程服务名称和 SocketProtectionLevel指定的远程目标。

ConnectAsync(EndpointPair)

对 StreamSocket 对象启动异步操作，以连接到指定为 EndpointPair 对象的远程网络目标。

public:
 virtual IAsyncAction ^ ConnectAsync(EndpointPair ^ endpointPair) = ConnectAsync;

/// [Windows.Foundation.Metadata.Overload("ConnectWithEndpointPairAsync")]
IAsyncAction ConnectAsync(EndpointPair const& endpointPair);

[Windows.Foundation.Metadata.Overload("ConnectWithEndpointPairAsync")]
public IAsyncAction ConnectAsync(EndpointPair endpointPair);

function connectAsync(endpointPair)

Public Function ConnectAsync (endpointPair As EndpointPair) As IAsyncAction

参数

endpointPair

EndpointPair

EndpointPair 对象，该对象指定本地主机名或 IP 地址、本地服务名称或 TCP 端口、远程主机名或远程 IP 地址，以及远程网络目标的远程服务名称或远程 TCP 端口。

返回

IAsyncAction

StreamSocket 对象的异步连接操作。

属性

OverloadAttribute

Windows 要求

要求	说明
应用功能	internetClientServer privateNetworkClientServer

注解

如果在 endpointPair 参数中传递的 EndpointPair 对象包含 LocalHostName 属性的 null，则系统将提供要使用的本地 IP 地址。 如果在 endpointPair 参数中传递的 EndpointPair 对象包含 LocalServiceName 属性的空字符串，则系统将提供要使用的本地 TCP 端口。

在 UWP 应用中，StreamSocket 类支持在代理完成连接时连接到远程终结点。 对代理的这种支持对应用是自动且透明的。 指定本地主机地址时不支持通过代理进行连接，因此在 endpointPair 参数中传递的 LocalHostName 属性必须为 null。 有关详细信息，请参阅 StreamSocket 类参考中有关代理 支持说明。

另请参阅

• ConnectAsync(HostName, String)
• ConnectAsync(EndpointPair, SocketProtectionLevel)
• ConnectAsync(HostName, String, SocketProtectionLevel)
• ConnectAsync(HostName, String, SocketProtectionLevel, NetworkAdapter)
• EndpointPair
• 如何在套接字操作 设置超时
• 如何在套接字操作 设置超时

ConnectAsync(EndpointPair, SocketProtectionLevel)

对 StreamSocket 对象启动异步操作，以连接到指定为 EndpointPair 对象的远程网络目标，以及 SocketProtectionLevel 枚举。 此方法不可从 JavaScript 调用。

public:
 virtual IAsyncAction ^ ConnectAsync(EndpointPair ^ endpointPair, SocketProtectionLevel protectionLevel) = ConnectAsync;

/// [Windows.Foundation.Metadata.Overload("ConnectWithEndpointPairAndProtectionLevelAsync")]
IAsyncAction ConnectAsync(EndpointPair const& endpointPair, SocketProtectionLevel const& protectionLevel);

[Windows.Foundation.Metadata.Overload("ConnectWithEndpointPairAndProtectionLevelAsync")]
public IAsyncAction ConnectAsync(EndpointPair endpointPair, SocketProtectionLevel protectionLevel);

function connectAsync(endpointPair, protectionLevel)

Public Function ConnectAsync (endpointPair As EndpointPair, protectionLevel As SocketProtectionLevel) As IAsyncAction

参数

endpointPair

EndpointPair

EndpointPair 对象，该对象指定本地主机名或 IP 地址、本地服务名称或 TCP 端口、远程主机名或远程 IP 地址，以及远程网络目标的远程服务名称或远程 TCP 端口。

protectionLevel

SocketProtectionLevel

表示 StreamSocket 对象的完整性和加密的保护级别。

返回

IAsyncAction

StreamSocket 对象的异步连接操作。

属性

OverloadAttribute

Windows 要求

要求	说明
应用功能	internetClientServer privateNetworkClientServer

注解

如果在 endpointPair 参数中传递的 EndpointPair 对象包含 LocalHostName 属性的 null，则系统将提供要使用的本地 IP 地址。 如果在 endpointPair 参数中传递的 EndpointPair 对象包含 LocalServiceName 属性的空字符串，则系统将提供要使用的本地 TCP 端口。

如果在 endpointPair 参数中传递的 EndpointPair 对象包含 LocalServiceName 属性的 null，则会发生错误。

[ConnectAsync（EndpointPair， SocketProtectionLevel） 方法未在 JavaScript 中公开。 无法从 JavaScript 调用此方法，因为它的参数数与 ConnectAsync（HostName， String） 方法相同。

使用 JavaScript 编写的应用无法使用 SSL 直接使用 EndpointPair 连接 StreamSocket。 若要使用 SSL 连接 EndpointPair，JavaScript 应用可以改用以下代码。

var clientSocket = new Windows.Networking.Sockets.StreamSocket();
var remoteName = new Windows.Networking.HostName("www.contoso.com");
var myEndpointPair = EndpointPair();

// Set properties needed on the EndpointPair
// We only set remote properties and the localServiceName,
// But the localHostName could also be set

myEndpointPair.localServiceName = "12345";
myEndpointPair.remoteHostName = remoteName;
myEndpointPair.remoteServiceName = "http";

// First connect the socket without SSL
clientSocket.connectAsync(myEendpointPair>).then(function () {
    // Now upgrade the connection to SSL
    clientSocket.upgradeToSslAsync(SocketProtectionLevel.Ssl).then(function () {
        // now connected using SSL
    }
}   

当 protectionLevel 参数设置为需要 SSL 或 TLS 的值时，如果远程终结点不支持 SSL 或 TLS，套接字连接操作可能不会超时。 如果初始连接操作成功，但远程终结点在 SSL 握手期间不会终止连接，则可能会发生这种情况。 为了防范这种情况，应用应在请求 SSL/TLS 时对连接操作设置超时，并在超时过期时中止该操作。 有关在套接字操作上使用 JavaScript 设置超时的详细信息，请参阅 如何在套接字操作 设置超时。 有关在套接字操作上使用 VB、C# 或C++设置超时的详细信息，请参阅 如何在套接字操作 设置超时。

在 UWP 应用中，StreamSocket 类支持在代理完成连接时连接到远程终结点。 对代理的这种支持对应用是自动且透明的。 指定本地主机地址时不支持通过代理进行连接，因此在 endpointPair 参数中传递的 LocalHostName 属性必须为 null。 有关详细信息，请参阅 StreamSocket 类参考中有关代理 支持说明。

另请参阅

• ConnectAsync(EndpointPair)
• ConnectAsync(HostName, String)
• ConnectAsync(HostName, String, SocketProtectionLevel)
• ConnectAsync(HostName, String, SocketProtectionLevel, NetworkAdapter)
• EndpointPair
• SocketProtectionLevel
• 如何在套接字操作 设置超时
• 如何在套接字操作 设置超时

ConnectAsync(HostName, String)

对 StreamSocket 对象启动异步操作，以连接到远程主机名和远程服务名称指定的远程网络目标。

public:
 virtual IAsyncAction ^ ConnectAsync(HostName ^ remoteHostName, Platform::String ^ remoteServiceName) = ConnectAsync;

/// [Windows.Foundation.Metadata.DefaultOverload]
/// [Windows.Foundation.Metadata.Overload("ConnectAsync")]
/// [Windows.Foundation.Metadata.RemoteAsync]
IAsyncAction ConnectAsync(HostName const& remoteHostName, winrt::hstring const& remoteServiceName);

[Windows.Foundation.Metadata.DefaultOverload]
[Windows.Foundation.Metadata.Overload("ConnectAsync")]
[Windows.Foundation.Metadata.RemoteAsync]
public IAsyncAction ConnectAsync(HostName remoteHostName, string remoteServiceName);

function connectAsync(remoteHostName, remoteServiceName)

Public Function ConnectAsync (remoteHostName As HostName, remoteServiceName As String) As IAsyncAction

参数

remoteHostName

HostName

远程网络目标的主机名或 IP 地址。 对于蓝牙 RFCOMM，这是一个 MAC 地址。

remoteServiceName

String

Platform::String

winrt::hstring

远程网络目标的服务名称或 TCP 端口号。 对于蓝牙 RFCOMM，这是蓝牙地址。

返回

IAsyncAction

StreamSocket 对象的异步连接操作。

属性

DefaultOverloadAttribute OverloadAttribute RemoteAsyncAttribute

Windows 要求

要求	说明
应用功能	internetClientServer privateNetworkClientServer

注解

必须提供 remoteHostName 和 remoteServiceName 参数。 如果 remoteHostName 为 null 或 remoteServiceName 为 null 或空字符串 ，则会发生错误。

在 UWP 应用中，StreamSocket 类支持在代理完成连接时连接到远程终结点。 对代理的这种支持对应用是自动且透明的。 有关详细信息，请参阅 StreamSocket 类参考中有关代理 支持说明。

另请参阅

• ConnectAsync(EndpointPair)
• ConnectAsync(EndpointPair, SocketProtectionLevel)
• ConnectAsync(HostName, String, SocketProtectionLevel)
• ConnectAsync(HostName, String, SocketProtectionLevel, NetworkAdapter)
• HostName
• 如何在套接字操作 设置超时
• 如何在套接字操作 设置超时

ConnectAsync(HostName, String, SocketProtectionLevel)

对 StreamSocket 对象启动异步操作，以连接到远程主机名、远程服务名称和 SocketProtectionLevel指定的远程目标。

public:
 virtual IAsyncAction ^ ConnectAsync(HostName ^ remoteHostName, Platform::String ^ remoteServiceName, SocketProtectionLevel protectionLevel) = ConnectAsync;

/// [Windows.Foundation.Metadata.Overload("ConnectWithProtectionLevelAsync")]
/// [Windows.Foundation.Metadata.RemoteAsync]
IAsyncAction ConnectAsync(HostName const& remoteHostName, winrt::hstring const& remoteServiceName, SocketProtectionLevel const& protectionLevel);

[Windows.Foundation.Metadata.Overload("ConnectWithProtectionLevelAsync")]
[Windows.Foundation.Metadata.RemoteAsync]
public IAsyncAction ConnectAsync(HostName remoteHostName, string remoteServiceName, SocketProtectionLevel protectionLevel);

function connectAsync(remoteHostName, remoteServiceName, protectionLevel)

Public Function ConnectAsync (remoteHostName As HostName, remoteServiceName As String, protectionLevel As SocketProtectionLevel) As IAsyncAction

参数

remoteHostName

HostName

远程网络目标的主机名或 IP 地址。 对于蓝牙 RFCOMM，这是一个 MAC 地址。

remoteServiceName

String

Platform::String

winrt::hstring

远程网络目标的服务名称或 TCP 端口号。 对于蓝牙 RFCOMM，这是蓝牙地址。

protectionLevel

SocketProtectionLevel

表示 StreamSocket 对象的完整性和加密的保护级别。

返回

IAsyncAction

StreamSocket 对象的异步连接操作。

属性

OverloadAttribute RemoteAsyncAttribute

Windows 要求

要求	说明
应用功能	internetClientServer privateNetworkClientServer

注解

必须提供 remoteHostName 和 remoteServiceName 参数。 如果 remoteHostName 为 null 或 remoteServiceName 为 null 或空字符串 ，则会发生错误。

当 protectionLevel 参数设置为需要 SSL 或 TLS 的值时，如果远程网络目标不支持 SSL 或 TLS，套接字连接操作可能不会超时。 如果初始连接操作成功，但远程主机不会在 SSL 握手期间终止连接，则可能会发生这种情况。 为了防范这种情况，应用应在请求 SSL/TLS 时对连接操作设置超时，并在超时过期时中止该操作。 有关在套接字操作上使用 JavaScript 设置超时的详细信息，请参阅 如何在套接字操作 设置超时。 有关在套接字操作上使用 VB、C# 或C++设置超时的详细信息，请参阅 如何在套接字操作 设置超时。

在 UWP 应用中，StreamSocket 类支持在代理完成连接时连接到远程终结点。 对代理的这种支持对应用是自动且透明的。 有关详细信息，请参阅 StreamSocket 类参考中有关代理 支持说明。

另请参阅

• ConnectAsync(EndpointPair)
• ConnectAsync(HostName, String)
• ConnectAsync(EndpointPair, SocketProtectionLevel)
• ConnectAsync(HostName, String, SocketProtectionLevel, NetworkAdapter)
• HostName
• SocketProtectionLevel
• 如何在套接字操作 设置超时
• 如何在套接字操作 设置超时

ConnectAsync(HostName, String, SocketProtectionLevel, NetworkAdapter)

对指定的本地网络适配器上的 StreamSocket 对象启动异步操作，以连接到远程主机名、远程服务名称和 SocketProtectionLevel指定的远程目标。

public:
 virtual IAsyncAction ^ ConnectAsync(HostName ^ remoteHostName, Platform::String ^ remoteServiceName, SocketProtectionLevel protectionLevel, NetworkAdapter ^ adapter) = ConnectAsync;

/// [Windows.Foundation.Metadata.Overload("ConnectWithProtectionLevelAndAdapterAsync")]
/// [Windows.Foundation.Metadata.RemoteAsync]
IAsyncAction ConnectAsync(HostName const& remoteHostName, winrt::hstring const& remoteServiceName, SocketProtectionLevel const& protectionLevel, NetworkAdapter const& adapter);

[Windows.Foundation.Metadata.Overload("ConnectWithProtectionLevelAndAdapterAsync")]
[Windows.Foundation.Metadata.RemoteAsync]
public IAsyncAction ConnectAsync(HostName remoteHostName, string remoteServiceName, SocketProtectionLevel protectionLevel, NetworkAdapter adapter);

function connectAsync(remoteHostName, remoteServiceName, protectionLevel, adapter)

Public Function ConnectAsync (remoteHostName As HostName, remoteServiceName As String, protectionLevel As SocketProtectionLevel, adapter As NetworkAdapter) As IAsyncAction

参数

remoteHostName

HostName

远程网络目标的主机名或 IP 地址。 对于蓝牙 RFCOMM，这是一个 MAC 地址。

remoteServiceName

String

Platform::String

winrt::hstring

远程网络目标的服务名称或 TCP 端口号。 对于蓝牙 RFCOMM，这是蓝牙地址。

protectionLevel

SocketProtectionLevel

表示 StreamSocket 对象的完整性和加密的保护级别。

adapter

NetworkAdapter

用于 StreamSocket 对象的连接操作的本地网络适配器。

返回

IAsyncAction

StreamSocket 对象的异步连接操作。

属性

OverloadAttribute RemoteAsyncAttribute

注解

[ConnectAsync（Hostname， String， SocketProtectionLevel， NetworkAdapter） 方法绑定到本地计算机上的 适配器 参数中指定的网络接口，以及远程主机名和服务名称，remoteHostName 中指定的远程主机名和服务名称，以及 remoteServiceName 参数，以及 protectionLevel 参数中指定的保护级别。

必须提供 remoteHostName 和 remoteServiceName 参数。 如果 remoteHostName为 null，或者 remoteServiceNamenull 或空字符串，则会发生错误。 如果 适配器 参数 null，则会发生错误。

[ConnectAsync（Hostname， String， SocketProtectionLevel， NetworkAdapter） 方法使用的名称解析机制仅限于域名系统 （DNS） 命名空间的指定接口。

使用指定的网络适配器是尽最大努力的。 在弱主机或转发模式下配置的适配器的系统可能使用指定的适配器以外的适配器。

当 protectionLevel 参数设置为需要 SSL 或 TLS 的值时，如果远程网络目标不支持 SSL 或 TLS，套接字连接操作可能不会超时。 如果初始连接操作成功，但远程主机不会在 SSL 握手期间终止连接，则可能会发生这种情况。 为了防范这种情况，应用应在请求 SSL/TLS 时对连接操作设置超时，并在超时过期时中止该操作。 有关在套接字操作上使用 JavaScript 设置超时的详细信息，请参阅 如何在套接字操作 设置超时。 有关在套接字操作上使用 VB、C# 或C++设置超时的详细信息，请参阅 如何在套接字操作 设置超时。

应用可以通过检查 HostName 实例（例如使用 NetworkInformation.GetHostNames 方法）并从 Hostname.IPInformation 属性检索 IPInformation 对象，从而检索 有效的 NetworkAdapter。 IPInformation.NetworkAdapter 属性可用于检索关联的 NetworkAdapter。

在 UWP 应用中，StreamSocket 类支持在代理完成连接时连接到远程终结点。 对代理的这种支持对应用是自动且透明的。 但是，当选择特定的网络适配器时，不支持通过代理进行连接。 因此，在使用 [ConnectAsync（HostName、String、 SocketProtectionLevel、 NetworkAdapter） 方法时，将禁用代理支持。 有关详细信息，请参阅 StreamSocket 类参考中有关代理 支持说明。

另请参阅

• ConnectAsync(EndpointPair)
• ConnectAsync(HostName, String)
• ConnectAsync(EndpointPair, SocketProtectionLevel)
• ConnectAsync(HostName, String, SocketProtectionLevel)
• IPInformation
• NetworkAdapter
• 如何在套接字操作 设置超时
• 如何在套接字操作 设置超时