# Metadata
Platforms: desktop, server, mobile OS: mac, windows, linux, ios, android Introduced: 1.0 Security: network
# Syntax
open [datagram] socket [from [localHostName][:localPort]] [to] socketID [with message callbackMessage]
# Params
- 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.
# Examples
open socket to "127.0.0.0:8080"
open socket to "ftp.example.org:21|sendFiles"
open secure socket to "livecode.com:443" with message "wasConnected" without verification
open secure socket to "livecode.com:443" with message "wasConnected" with verification for host "livecode.com"
open datagram socket from ":8080" to "10.2.1.1:8080"
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
# 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 when you create your > standalone application. 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.
# Tags
# See
- **property:** defaultNetworkInterface - **message:** socketTimeout - **command:** accept, post, wait - **glossary:** TCP, UDP, command, socket, Standalone Application Settings, command, LiveCode custom library, datagram - **library:** SSL & Encryption library