Share via


StreamSocket.UpgradeToSslAsync(SocketProtectionLevel, HostName) Method

Definition

Starts an asynchronous operation to upgrade a connected socket to use SSL on a StreamSocket object.

public:
 virtual IAsyncAction ^ UpgradeToSslAsync(SocketProtectionLevel protectionLevel, HostName ^ validationHostName) = UpgradeToSslAsync;
/// [Windows.Foundation.Metadata.RemoteAsync]
IAsyncAction UpgradeToSslAsync(SocketProtectionLevel const& protectionLevel, HostName const& validationHostName);
[Windows.Foundation.Metadata.RemoteAsync]
public IAsyncAction UpgradeToSslAsync(SocketProtectionLevel protectionLevel, HostName validationHostName);
function upgradeToSslAsync(protectionLevel, validationHostName)
Public Function UpgradeToSslAsync (protectionLevel As SocketProtectionLevel, validationHostName As HostName) As IAsyncAction

Parameters

protectionLevel
SocketProtectionLevel

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

validationHostName
HostName

The hostname of the remote network destination that is used for validation when upgrading to SSL.

Returns

An asynchronous operation to upgrade to use SSL on a StreamSocket object.

Attributes

Windows requirements

App capabilities
ID_CAP_NETWORKING [Windows Phone]

Remarks

The UpgradeToSslAsync method can only be used to upgrade an already established connection made with a SocketProtectionLevel of PlainSocket.

The typical order of operations to establish an SSL connection is as follows:

  • Create the StreamSocket.
  • Get socket control data on a StreamSocketControl object using the Control property and set any properties before calling one of the ConnectAsync methods.
  • Call one of the ConnectAsync methods to establish a connection with the remote endpoint. If an SSL/TLS connection is required immediately, this can be specified using some of the ConnectAsync methods. If an SSL/TLS connection is desired after sending and receiving some initial data, then the UpgradeToSslAsync method can be called later to upgrade the connection to use SSL.
  • Get the OutputStream property to write data to the remote host.
  • Get the InputStream property to read data from the remote host.
  • Read and write data as needed.
  • Call the Close method to abort any pending operations and release all unmanaged resources associated with the StreamSocket object. The UpgradeToSslAsync method requires that the remote server to which the connection was established is able to upgrade a TCP connection to an SSL connection.

The UpgradeToSslAsync method can only be used for client connections. This method can't be used to upgrade a connection accepted by the StreamSocketListener to an SSL connection. The UpgradeToSslAsync method only implements the client parts of the SSL protocol negotiation, not the server parts that would be needed to listen for and accept SSL connections.

Applies to

See also