Name: open socket

Type: command

Syntax: open [datagram] socket [from [<localHostName>][:<localPort>]] [to] <socketID> [with message <callbackMessage>]

Syntax: open secure socket [from [<localHostName>][:<localPort>]] [to] <socketID> [with message <callbackMessage>] [without verification] [using certificate <certificate> and key <key>]

Syntax: open secure socket [from [<localHostName>][:<localPort>]] [to] <socketID> [with message <callbackMessage>] [with verification [for host <verificationHostName>]] [using certificate <certificate> and key <key>]

Summary:
Establishes either a <TCP> or <UDP> communications <socket> between your system and
another system.

Associations: ssl & encryption

Introduced: 1.0

OS: mac, windows, linux, ios, android

Platforms: desktop, server, mobile

Security: network

Example:
open socket to "127.0.0.0:8080"

Example:
open socket to "ftp.example.org:21|sendFiles"

Example:
open secure socket to "livecode.com:443" with message "wasConnected" without verification

Example:
open secure socket to "livecode.com:443" with message "wasConnected" with verification for host "livecode.com"

Example:
open datagram socket from ":8080" to "10.2.1.1:8080"

Example:
on mouseUp
   open socket "www.google.com:80"
   write "test" \
         to socket "www.google.com:80" \
         with message "socketFinishedWriting"
end mouseUp

on socketFinishedWriting pSocketID
   put "Data written to socket" && pSocketID
   close socket "www.google.com:80"
end socketFinishedWriting

Parameters:
localHostName:
The name or IP address of the local host to use when opening the socket.
If no local host name is specified, then the <defaultNetworkInterface>
property will be used. If the <defaultNetworkInterface> has not been
set, then the system's default local host will be used.

localPort:
The local port to use when opening the socket. If no local port is
specified, then the OS will select a free local port.

socketID:
The identifier (set when you opened the socket) of the socket you want
to close. The socket identifier starts with the IP address of the host
the socket is connected to, and may optionally include a port number
(separated from the IP address by a colon). If there is more than one
socket connected to that host and port, you can specify which socket by
appending the connection name or number that was assigned when the
socket was opened, separated from the port number by a vertical bar (|).

callbackMessage:
The name of a message to be sent when the connection is made.

certificate:


key:


verificationHostName:
The IP address or domain name of the host you want to verify the socket
against. 

The result:
If the socket fails to open due to an error, a socketError message is
sent to the object that attempted to open the socket. (If the error is
due to a problem finding the specified host, the error message is
returned in the result, and no socketError message is sent.).

Description:
Use the <open socket> <command> to open a connection to another system
on the Internet (or another IP network) to get and send data.

When a connection is made, the open socket command creates a new socket
that can be used to communicate with the other system. The handler
continues executing while the connection is being established. If you
use the write to socket command while the connection is opening, the
data is buffered and is sent to the host as soon as the connection is
made. 

Use the open datagram socket form if you want to send a connectionless
<UDP> <datagram> instead of opening a socket.

If you specify a callbackMessage, the message is sent to the object
whose script contains the open socket command, as soon as the connection
is made. The first parameter pf this message is the host and port number
of the socket. Use a callbackMessage to trigger actions (such as reading
from the socket) that must wait until the connection has been
established. (To pause the handler that contains the open socket command
until the callbackMessage is received, use the wait for messages form of
the wait command.)

<UDP>/<datagram> sockets are not supported by SSL.  When connecting to a
remote peer, the client verifies the servers certificate during the
handshake process and verifies it against a list of certificates. You
can specify a list of root CA to verify against using the
sslcertificates property (see sslurlloader sample). The sslcertficates
property takes a return delimited list of files or folders. In addition
you can place system wide certfificates in System/Library/OpenSSL/certs.

The most common CAs such as verisign can be found in the file root.pem.
If a verificationhostname is specified, the socket will be verified
against that verificationhostname rather than the host. An example of
this is when you want to create a secure connection with a host while
tunnelling through a proxy. Specifying the final host allows LiveCode to
verify the socket against that host, rather than the proxy server. If
'without verification' is specified then server credentials are not
authenticated, and any connection is accepted.

>*Note:*  When the accept command creates a socket, it assigns a number
> as the connection name. If you are using both the open socket command
> and the accept command to connect to the same port on the same host,
> make sure to use a non-numeric connection name that won't conflict
> with the numbers assigned by the accept command. This ensures that you
> can always refer to two different sockets by distinct socket
> identifiers. 

>*Important:*  Sockets are always opened in binary mode. This means that
> LiveCode does not automatically convert between the other system's
> end-of-line convention and the line feed character (ASCII 10) that
> LiveCode uses internally to mark the end of a line. If you are reading
> or writing data one line at a time, be sure you know whether the other
> system uses line feed, return (ASCII 13), or both to mark the end of
> each line; if necessary, you will need to convert end-of-line markers
> yourself, after receiving or before sending the data. (The usual
> end-of-line marker on Mac OS and OS X systems is a return character;
> on Unix, a line feed; on Windows, a CRLF.)

For technical information about the numbers used to designate standard
ports, see the list of port numbers at
http://www.iana.org/assignments/port-numbers, in particular the section 
titled "Well Known Port Numbers".

>*Important:*  The <open socket> <command> is part of the 
> <SSL & Encryption library>. To ensure that the <command> works in a 
> standalone application, you must include this 
> <LiveCode custom library|custom library> when you create your 
> <standalone application|standalone>. In the Inclusions pane of the 
> <Standalone Application Settings> window, make sure the
> "SSL & Encryption" 
> library checkbox is checked.

>*Important:* 
On Android, when using remote sockets, internet permissions must be
enabled. Do this by selecting the "Internet" checkbox of the
"Application Permissions" section of the Android screen.

(4.5) The open socket command no longer blocks on DNS resolution.
Instead, if resolution is required the command will return immediately
and the DNS lookup will happen in the background. If resolution fails,
then a socketError message is sent in the same was as if connection
fails. 

For applications using hostNameToAddress directly, its syntax has been
augmented: 

    hostnameToAddress(hostname, [ callback ])

If the callback parameter is specified then the call will return
immediately and upon completion of the lookup, the callback will be
invoked with the resolved address as a parameter.

Changes:
(6.7) Added the "with verification for host" variant.

(9.0) Added the ability to specify the local host and port.

References: accept (command), post (command), wait (command),
TCP (glossary), UDP (glossary), command (glossary), socket (glossary),
Standalone Application Settings (glossary), command (glossary),
LiveCode custom library (glossary), SSL & Encryption library (library),
socketTimeout (message), defaultNetworkInterface (property), datagram (glossary)

