<doc>
	<legacy_id>1570</legacy_id>
	<name>open socket</name>
	<type>command</type>

	<syntax>
		<example>open [datagram] socket [to] <i>host</i>[:<i>port</i>[|<i>ID</i>]] [with message <i>callbackMessage</i>]</example>
		<example>open secure socket [to] <i>host</i>[:<i>port</i>[|<i>ID</i>]] [with message <i>callbackMessage</i>] [without verification] [using certificate <i>certificate</i> and key <i>key</i>]</example>
		<example>open secure socket [to] <i>host</i>[:<i>port</i>[|<i>ID</i>]] [with message <i>callbackMessage</i>] [with verification [for host <i>verificationHostName</i>]] [using certificate <i>certificate</i> and key <i>key</i>]</example>
	</syntax>

	<synonyms>
	</synonyms>

	<summary>Establishes a <glossary tag="TCP">TCP</glossary> communications <glossary tag="socket">socket</glossary> between your system and another system.</summary>

	<examples>
<example>open socket to "127.0.0.0:8080"</example>
<example>open socket to "ftp.example.org:21|sendFiles"</example>
<example>open secure socket to "runrev.com:443" with message "wasConnected" without verification</example>
<example>open secure socket to "runrev.com:443" with message "wasConnected" with verification for host "livecode.com"</example>
<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</example>
	</examples>

	<history>
		<introduced version="1.0">Added.</introduced>
		<deprecated version=""></deprecated>
		<removed version=""></removed>
		<changed version="4.5">updated non blocking</changed>
<changed version="2.5">2.5</changed>
		<experimental version=""></experimental>
		<nonexperimental version=""></nonexperimental>
	</history>

	<objects>
	</objects>

	<platforms>
		<mac/>
		<windows/>
		<linux/>
	</platforms>

	<classes>
		<desktop/>
		<server/>
		<web/>
	</classes>

	<security>
		<network/>
	</security>


	<classification>
	</classification>

	<references>
		<command tag="accept">accept Command</command>
		<command tag="post">post Command</command>
		<command tag="wait">wait Command</command>
		<message tag="socketTimeout">socketTimeout Message</message>
	</references>

	<description>
	<overview>Use the <b>open socket</b> <glossary tag="command">command</glossary> to open a connection to another system on the Internet (or another IP network) to get and send data.</overview>

		<parameters>
  <parameter>
    <name>host</name>
    <description>The IP address or domain name of the host you want to connect to.</description>
  </parameter>
  <parameter>
    <name>port</name>
    <description>The port number you want to connect to. If you don't specify a port, port 80 is used. (On most systems, port 80 is used for HTTP connections.).</description>
  </parameter>
  <parameter>
    <name>ID</name>
    <description>An optional connection name for the socket, and can be any string. Specify an ID if you want to create more than one socket to the same host and port number, so that you can distinguish between them.</description>
  </parameter>
  <parameter>
    <name>callbackMessage</name>
    <description>The name of a message to be sent when the connection is made.</description>
  </parameter>
  <parameter>
    <name>verificationHostName</name>
    <description>The IP address or domain name of the host you want to verify the socket against.</description>
  </parameter>		</parameters>

	<value></value>
	<comments>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.<p></p><p>Use the open datagram socket form if you want to send a connectionless UDP datagram instead of opening a socket.</p><p></p><p>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.)</p><p></p><p>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.</p><p></p><p><font face="Lucida Grande" size="11">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.</font></p><p></p><p>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.)</p><p></p><p><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.</p><p></note><p><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.)</p><p></important><p>For technical information about the numbers used to designate standard ports, see the list of port numbers at &lt;http://www.iana.org/assignments/port-numbers&gt;, in particular the section titled "Well Known Port Numbers".</p><p></p><p><important> The open secure socket command is part of the SSL &amp; Encryption library. To ensure that the command works in a standalone application, you must include this custom library when you create your standalone. In the Inclusions section on the General screen of the Standalone Application Settings window, make sure "SSL &amp; Encryption" is selected in the list of script libraries.</p><p></important><p><change></p><p>(6.7) Added the "with verification for host" variant.<p></change><p>(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.</p><p></p><p>For applications using hostNameToAddress directly, its syntax has been augmented:</p><p></p><p>hostnameToAddress(hostname, [ callback ])</p><p></p><p>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.</p></comments>
	</description>
</doc>