StreamSocket.ConnectAsync(EndpointPair, SocketProtectionLevel) method

Applies to Windows and Windows Phone

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.

Syntax


public IAsyncAction ConnectAsync(
  EndpointPair endpointPair, 
  SocketProtectionLevel protectionLevel
)

Parameters

endpointPair

Type: 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

Type: SocketProtectionLevel

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

Return value

Type: IAsyncAction

An asynchronous connect operation on a StreamSocket object.

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.

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 (HTML). For more information on setting a timeout using VB, C#, or C++ on socket operations, see How to set timeouts on socket operations (XAML).

In a Windows Store 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 Store app, the StreamSocket class does not provide automatic support for proxies.

Requirements

Minimum supported client

Windows 8

Minimum supported server

Windows Server 2012

Minimum supported phone

Windows Phone 8

Namespace

Windows.Networking.Sockets
Windows::Networking::Sockets [C++]

Metadata

Windows.winmd

DLL

Windows.Networking.dll

Capabilities

internetClientServer
privateNetworkClientServer
ID_CAP_NETWORKING [Windows Phone]

See also

Other resources
How to set timeouts on socket operations (HTML)
How to set timeouts on socket operations (XAML)
Reference
ConnectAsync(EndpointPair)
ConnectAsync(HostName, String)
ConnectAsync(HostName, String, SocketProtectionLevel)
ConnectAsync(HostName, String, SocketProtectionLevel, NetworkAdapter)
EndpointPair
SocketProtectionLevel
StreamSocket

 

 

Show:
© 2014 Microsoft