StreamSocket.ConnectAsync Method

Reference

Definition

Namespace:: Windows.Networking.Sockets

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Overloads

ConnectAsync(EndpointPair)	Starts an asynchronous operation on a StreamSocket object to connect to a remote network destination specified as an EndpointPair object.
ConnectAsync(EndpointPair, SocketProtectionLevel)	Starts an asynchronous operation on a StreamSocket object to connect to a remote network destination specified as an EndpointPair object and a SocketProtectionLevel enumeration. This method is not callable from JavaScript.
ConnectAsync(HostName, String)	Starts an asynchronous operation on a StreamSocket object to connect to a remote network destination specified by a remote hostname and a remote service name.
ConnectAsync(HostName, String, SocketProtectionLevel)	Starts an asynchronous operation on a StreamSocket object to connect to a remote destination specified by a remote hostname, a remote service name, and a SocketProtectionLevel.
ConnectAsync(HostName, String, SocketProtectionLevel, NetworkAdapter)	Starts an asynchronous operation on a StreamSocket object on a specified local network adapter to connect to a remote destination specified by a remote hostname, a remote service name, and a SocketProtectionLevel.

ConnectAsync(EndpointPair)

Edit

Starts an asynchronous operation on a StreamSocket object to connect to a remote network destination specified as an EndpointPair object.

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

Parameters

endpointPair: EndpointPair

An EndpointPair object that specifies the local hostname or IP address, the local service name or TCP port, the remote hostname or remote IP address, and the remote service name or remote TCP port for the remote network destination.

Returns

IAsyncAction

An asynchronous connect operation on a StreamSocket object.

Attributes: OverloadAttribute

Windows requirements

App capabilities

ID_CAP_NETWORKING [Windows Phone] internetClientServer privateNetworkClientServer

Remarks

If the EndpointPair object passed in the endpointPair parameter contains null for the LocalHostName property, then the system will supply the local IP address that will be used. If the EndpointPair object passed in the endpointPair parameter contains an empty string for the LocalServiceName property, then the system will supply the local TCP port that will be used.

In a UWP app, the StreamSocket class supports connecting to a remote endpoint when proxies are required to complete the connection. This support for proxies is automatic and transparent to the app. Connecting through proxies is not supported when a local host address is specified, so the LocalHostName property passed in the endpointPair parameter must be null. For more detailed information, see the remarks on Support for proxies in the StreamSocket class reference.

In a Windows Phone 8.x app, the StreamSocket class does not provide automatic support for proxies.

Applies to

ConnectAsync(EndpointPair, SocketProtectionLevel)

Edit

Starts an asynchronous operation on a StreamSocket object to connect to a remote network destination specified as an EndpointPair object and a SocketProtectionLevel enumeration. This method is not callable from 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

Parameters

endpointPair: EndpointPair

An EndpointPair object that specifies local hostname or IP address, local service name or TCP port, the remote hostname or remote IP address, and the remote service name or remote TCP port for the remote network destination.

protectionLevel: SocketProtectionLevel

The protection level that represents the integrity and encryption for a StreamSocket object.

Returns

IAsyncAction

An asynchronous connect operation on a StreamSocket object.

Attributes: OverloadAttribute

Windows requirements

App capabilities

ID_CAP_NETWORKING [Windows Phone] internetClientServer privateNetworkClientServer

Remarks

If the EndpointPair object passed in the endpointPair parameter contains null for the LocalServiceName property, then an error will occur.

The [ConnectAsync(EndpointPair, SocketProtectionLevel) method is not exposed in JavaScript. This method can't be called from JavaScript since it has the same number of arguments as the ConnectAsync(HostName, String) method.

Apps written in JavaScript can't connect a StreamSocket using an EndpointPair using SSL directly. In order to connect an EndpointPair using SSL, JavaScript apps can use the following code instead.

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
    }
}

When the protectionLevel parameter is set to a value that requires SSL or TLS, the socket connect operation may not timeout if the remote endpoint does not support SSL or TLS. This can occur if initial connect operation succeeds but the remote endpoint does not terminate the connection during the SSL handshake. To protect against this situation, an app should set a timeout on the connect operation when requesting SSL/TLS and abort the operation if the timeout expires. For more information on setting a timeout using JavaScript on socket operations, see How to set timeouts on socket operations . For more information on setting a timeout using VB, C#, or C++ on socket operations, see How to set timeouts on socket operations .

In a Windows Phone 8.x app, the StreamSocket class does not provide automatic support for proxies.

Applies to

ConnectAsync(HostName, String)

Edit

Starts an asynchronous operation on a StreamSocket object to connect to a remote network destination specified by a remote hostname and a remote service name.

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

Parameters

remoteHostName: HostName

The hostname or IP address of the remote network destination. For Bluetooth RFCOMM, this is a MAC address.

remoteServiceName: String
Platform::String

winrt::hstring

The service name or TCP port number of the remote network destination. For Bluetooth RFCOMM, this is the Bluetooth address.

Returns

IAsyncAction

An asynchronous connect operation on a StreamSocket object.

Attributes: DefaultOverloadAttribute OverloadAttribute RemoteAsyncAttribute

Windows requirements

App capabilities

ID_CAP_NETWORKING [Windows Phone] internetClientServer privateNetworkClientServer

Remarks

The remoteHostName and remoteServiceName parameters must be provided. If the remoteHostName is null or the remoteServiceName is null or an empty string, an error will occur.

In a Windows Phone 8.x app, the StreamSocket class does not provide automatic support for proxies.

Applies to

ConnectAsync(HostName, String, SocketProtectionLevel)

Edit

Starts an asynchronous operation on a StreamSocket object to connect to a remote destination specified by a remote hostname, a remote service name, and a 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

Parameters

remoteHostName: HostName

The hostname or IP address of the remote network destination. For Bluetooth RFCOMM, this is a MAC address.

remoteServiceName: String
Platform::String

winrt::hstring

The service name or TCP port number of the remote network destination. For Bluetooth RFCOMM, this is the Bluetooth address.

protectionLevel: SocketProtectionLevel

The protection level that represents the integrity and encryption for the StreamSocket object.

Returns

IAsyncAction

An asynchronous connect operation on a StreamSocket object.

Attributes: OverloadAttribute RemoteAsyncAttribute

Windows requirements

App capabilities

ID_CAP_NETWORKING [Windows Phone] internetClientServer privateNetworkClientServer

Remarks

The remoteHostName and remoteServiceName parameters must be provided. If the remoteHostName is null or the remoteServiceName is null or an empty string, an error will occur.

When the protectionLevel parameter is set to a value that requires SSL or TLS, the socket connect operation may not timeout if the remote network destination does not support SSL or TLS. This can occur if initial connect operation succeeds but the remote host does not terminate the connection during the SSL handshake. To protect against this situation, an app should set a timeout on the connect operation when requesting SSL/TLS and abort the operation if the timeout expires. For more information on setting a timeout using JavaScript on socket operations, see How to set timeouts on socket operations . For more information on setting a timeout using VB, C#, or C++ on socket operations, see How to set timeouts on socket operations .

In a Windows Phone 8.x app, the StreamSocket class does not provide automatic support for proxies.

Applies to

ConnectAsync(HostName, String, SocketProtectionLevel, NetworkAdapter)

Edit

Starts an asynchronous operation on a StreamSocket object on a specified local network adapter to connect to a remote destination specified by a remote hostname, a remote service name, and a 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

Parameters

remoteHostName: HostName

The hostname or IP address of the remote network destination. For Bluetooth RFCOMM, this is a MAC address.

remoteServiceName: String
Platform::String

winrt::hstring

The service name or TCP port number of the remote network destination. For Bluetooth RFCOMM, this is the Bluetooth address.

protectionLevel: SocketProtectionLevel

The protection level that represents the integrity and encryption for the StreamSocket object.

adapter: NetworkAdapter

The local network adapter to use for the connect operation on the StreamSocket object.

Returns

IAsyncAction

An asynchronous connect operation on a StreamSocket object.

Attributes: OverloadAttribute RemoteAsyncAttribute

Remarks

The [ConnectAsync(Hostname, String, SocketProtectionLevel, NetworkAdapter) method binds to a network interface specified in the adapter parameter on the local computer and the remote hostname and service name specified in the remoteHostName and remoteServiceName parameters with the protection level specified in the protectionLevel parameter.

The remoteHostName and remoteServiceName parameters must be provided. If the remoteHostName is null or the remoteServiceName is null or an empty string, an error will occur. If the adapter parameter is null, an error will occur.

The name resolution mechanism used by the [ConnectAsync(Hostname, String, SocketProtectionLevel, NetworkAdapter) method is limited to the specified interface for the domain name system (DNS) namespace.

Using the specified network adapter is on a best-effort basis. Systems with adapters configured in weak-host or forwarding modes may use an adapter other than the specified adapter.

An app can retrieve a valid NetworkAdapter by inspecting a HostName instance (using the NetworkInformation.GetHostNames method, for example) and retrieving the IPInformation object from the Hostname.IPInformation property. The IPInformation.NetworkAdapter property can be used to retrieve the associated NetworkAdapter.

In a UWP app, the StreamSocket class supports connecting to a remote endpoint when proxies are required to complete the connection. This support for proxies is automatic and transparent to the app. However, connecting through proxies is not supported when a specific network adapter is selected. So proxy support is disabled when the [ConnectAsync(HostName, String, SocketProtectionLevel, NetworkAdapter) method is used. For more detailed information, see the remarks on Support for proxies in the StreamSocket class reference.

In a Windows Phone 8.x app, the StreamSocket class does not provide automatic support for proxies.

Applies to

Share via

StreamSocket.ConnectAsync Method

Definition

Overloads

ConnectAsync(EndpointPair)

Parameters

Returns

Windows requirements

Remarks

See also

Applies to

ConnectAsync(EndpointPair, SocketProtectionLevel)

Parameters

Returns

Windows requirements

Remarks

See also

Applies to

ConnectAsync(HostName, String)

Parameters

Returns

Windows requirements

Remarks

See also

Applies to

ConnectAsync(HostName, String, SocketProtectionLevel)

Parameters

Returns

Windows requirements

Remarks

See also

Applies to

ConnectAsync(HostName, String, SocketProtectionLevel, NetworkAdapter)

Parameters

Returns

Remarks

See also

Applies to

Feedback

Additional resources