.tlshandshake Method

Function:	For the currently selected socket (selection is made through sock.num), initiates the TLS handshake process to upgrade the socket to an encrypted connection.
Syntax:	sock.tlshandshake(byref server_name as string) as enum
Returns:	0 — PL_TLS_SUCCESS — Initialization was completed successfully 1 — PL_TLS_REJECTED — Initialization attempt was rejected 2 — PL_TLS_ERROR_IN_USE — TLS is already in use on another socket
See Also:	Transport Layer Security (TLS), Establishing a Secure Connection

Part	Description
server_name	The fully qualified domain name of the designated server.

Details

This method's sole parameter, server_name, requires a fully qualified domain name (i.e., everything after "https://" up to the first forward slash). If you do not want to verify the server name against the certificate, pass an empty string — this is useful when connecting directly to an IP address.

Attempting to call sock.tlshandshake on a socket other than the one on which sock.tlsinit was executed will return PL_TLS_ERROR_IN_USE.

Additionally, calling sock.tlshandshake will result in PL_TLS_REJECTED in the following scenarios:

The selected protocol is not TCP (sock.protocol <> PL_SOCK_PROTOCOL_TCP)
The TCP connection is not an outgoing connection (sock.state <> PL_SST_EST_AOPENED)
sock.tlsinit has not been executed on any socket (sock.tlscurrentnum = 255)

Even if sock.tlshandshake returns PL_TLS_SUCCESS, the creation of the secure connection may still fail due to a number of reasons. The final and definitive indicator of the successful establishment of the TLS link is the transition of sock.state into PL_SST_EST_TLS.