# %connect_starttls() function

The %connect_starttls function provides the ability to elevate an
 unsecured connection to a secured connection.

The %connect_starttls function is supported on D3 Windows and D3
 Linux.

## Syntax

```
code = %connect_starttls(fd, &SSL);
```

## Parameter(s)

| fd | File descriptor of the local socket returned by a previous call to the FlashBASIC C function %socket(). |
| --- | --- |
| SSL | Return value for the SSL handle. |

## Description

The Client connecting to a Server uses the %connect function for
 establishing an unsecured connection to a server. Then, the Server uses the
 %connect_starttls function to elevate the unsecured connection to
 a secured connection.

 The Client initially calls the %connect function to establish an
 unsecured connection, then calls the %connect_starttls function to
 elevate the unsecured connection to a secured connection. This function negotiates with
 the Server by sending and receiving messages on the socket to determine if the Server
 supports STARTTLS. If the Server supports STARTTLS and the Client chooses to use
 STARTTLS, the Client negotiates with the Server to use STARTTLS.

 The %connect_starttls function provides similar functionality to the
 %connect_ssl function, except the embedded call to the
 %connect function has been removed. When calling the
 %connect_starttls function, the connection must have been
 previously established by using the %connect function.

## Example(s)

**Example 1**

 **UNIX**: Client code for connecting to mail server using the
 %connect and %connect_starttls functions:

```

cfunction socket.builtin
include dm,bp,includes sysid.inc
include dm,bp,unix.h socket.h
include dm,bp,unix.h errno.h
*
CRLF = CHAR(13):CHAR(10)
HELO = 'gmail.com'
*
SOCKFD = %socket(AF$INET, SOCK$STREAM, 0)
IF SOCKFD = -1 THEN
CRT "Getting soxket failed"
STOP
END
*
HOST = "smtp.gmail.com"
PORT = 587
SSL = 0
*
RESULT = %connect(SOCKFD,AF$INET,HOST,PORT)
IF RESULT < 0 THEN
CRT "Connection to ":HOST:" failed"
%close(SOCKFD)
STOP
END
GOSUB DO.READ
*

 SMTP PROTOCOL:
 MSG = &#39;EHLO &#39;:HELO:CRLF
 GOSUB DO.WRITE
 GOSUB DO.READ
 *
 MSG = &#39;HELO &#39;:HELO:CRLF
 GOSUB DO.WRITE
 GOSUB DO.READ
 *
 MSG = &#39;STARTTLS&#39;:CRLF
 GOSUB DO.WRITE
 GOSUB DO.READ
 *
 RESULT = %connect_starttls(SOCKFD,&SSL)
 IF RESULT < 0 THEN
 CRT "SSL connection to ":HOST:" failed"
 %close(SOCKFD)
 STOP
 END
 *
 %close(SOCKFD)
 *
 CRT "SSL connection to :"HOST:" successful"
 STOP
 DO.READ:*
 BUFFER = SPACE(4096)
 LEN.BUFFER = LEN(BUFFER)
 RESULT = %READ(SOCKFD, BUFFER, LEN.BUFFER)
 IF RESULT < 0 THEN
 CRT "%READ FAILED RESULT : ":RESULT
 %close(SOCKFD)
 STOP
 END
 BYTES.READ = RESULT
 CRT BUFFER[1, BYTES.READ]
 RETURN
 DO.WRITE:*
 LEN.MSG = LEN(MSG)
 RESULT = %WRITE(SOCKFD, MSG, LEN.MSG)

IF RESULT < 0 THEN
CRT "%WRITE FAILED RESULT : ":RESULT
%close(SOCKFD)
STOP
END
RETURN
```

 **Example 2**

 **Windows**: Client code for connecting to mail server using the
 %connect and %connect_starttls functions:

```

cfunction socket.builtin
include dm,bp,includes sysid.inc
*
PLATFORM = SYSTEM(38)
WINDOWS.BASED = (PLATFORM<SYS$IMP> = SYS$NT)
AF$INET = 2 + 0; * internetwork: UDP, TCP, etc
SOCK$STREAM = 1 + 0; * stream socket
*
CRLF = CHAR(13):CHAR(10)
HELO = &#39;gmail.com&#39;
*
SOCKFD = %socket(AF$INET, SOCK$STREAM, 0)
IF SOCKFD = -1 THEN
CRT "Getting soxket failed"
STOP
END
*
HOST = "smtp.gmail.com"
PORT = 587
SSL = 0
*
RESULT = %connect(SOCKFD,AF$INET,(CHAR *)HOST,PORT)
IF RESULT < 0 THEN
CRT "Connection to ":HOST:" failed"
%CLOSESOCKET( SOCKFD )
STOP
END
GOSUB DO.READ
*

 SMTP PROTOCOL:
 MSG = &#39;EHLO &#39;:HELO:CRLF
 GOSUB DO.WRITE
 GOSUB DO.READ
 *
 MSG = &#39;HELO &#39;:HELO:CRLF
 GOSUB DO.WRITE
 GOSUB DO.READ
 *
 MSG = &#39;STARTTLS&#39;:CRLF
 GOSUB DO.WRITE
 GOSUB DO.READ
 *
 RESULT = %connect_starttls(SOCKFD,&SSL)
 IF RESULT < 0 THEN
 CRT "SSL connection to ":HOST:" failed"
 %CLOSESOCKET( SOCKFD )
 STOP
 END
 *
 %CLOSESOCKET( SOCKFD )
 *
 CRT "SSL connection to :"HOST:" successful"
 STOP
 DO.READ:*
 SOCKFD = SOCKFD + 0
 BUFFER = SPACE(4096)
 LEN.BUFFER = LEN(BUFFER)
 RESULT = %RECV( SOCKFD, (CHAR *)BUFFER, LEN.BUFFER, 0)
 IF RESULT < 0 THEN
 CRT "%READ FAILED RESULT : ":RESULT
 %CLOSESOCKET( SOCKFD )
 STOP
 END
 BYTES.READ = RESULT
 CRT BUFFER[1, BYTES.READ]
 RETURN
 DO.WRITE:*
 SOCKFD = SOCKFD + 0
 LEN.MSG = LEN(MSG)
 RESULT = %SEND( SOCKFD, (CHAR *)MSG, LEN.MSG, 0)
 IF RESULT < 0 THEN
 CRT "%WRITE FAILED RESULT : ":RESULT
 %CLOSESOCKET( SOCKFD )
 STOP
 END
 RETURN
```

## See also

- [%connect() function](https://d3codex.com/pickbasic-flashbasic/percent-connect-function/)
- [%connect_ssl() function](https://d3codex.com/pickbasic-flashbasic/percent-connect-ssl-function/)
- [%accept_ssl() function](https://d3codex.com/pickbasic-flashbasic/percent-accept-ssl-function/)
- [%close_ssl() function](https://d3codex.com/pickbasic-flashbasic/percent-close-ssl-function/)
- [%read_ssl() function](https://d3codex.com/pickbasic-flashbasic/percent-read-ssl-function/)
- [%write_ssl() function](https://d3codex.com/pickbasic-flashbasic/percent-write-ssl-function/)

---
Source: https://d3codex.com/pickbasic-flashbasic/percent-connect-starttls-function/ - part of the D3Codex reference.