<doc>
  <legacy_id>1880</legacy_id>
  <name>read from socket</name>
  <type>command</type>
  <syntax>
    <example>read from socket <i>socketID</i> [until <i>string</i> | for <i>amount</i> [<i>chunkType</i>]] [with message <i>callbackMessage</i>]</example>
  </syntax>
  <library></library>
  <objects>
  </objects>
  <synonyms>
  </synonyms>
  <classification>
    <category>Networks &amp; Communication</category>
  </classification>
  <references>
    <command tag="accept">accept Command</command>
    <command tag="post">post Command</command>
    <message tag="socketTimeout">socketTimeout Message</message>
  </references>
  <history>
    <introduced version="1.0">Added.</introduced>
  </history>
  <platforms>
    <mac/>
    <windows/>
    <linux/>
  </platforms>
  <classes>
    <desktop/>
    <server/>
    <web/>
  </classes>
  <security>
  </security>
  <summary>Accepts data from a <glossary tag="socket">socket</glossary> and places the data in the <keyword tag="it">it</keyword> <glossary tag="variable">variable</glossary>.</summary>
  <examples>
    <example>read from socket "www.example.net:80" <i>-- reads next character</i></example>
    <example>read from socket "www.example.net:80" for 50 <i>-- reads next 50 chars</i></example>
    <example>read from socket "127.0.0.0:20|foo" until linefeed</example>
    <example>read from socket mySocket for 30 uInt2s with message "gotData"</example>
  </examples>
  <description>
    <p>Use the <b>read from socket</b> <glossary tag="command">command</glossary> to get data from another system via a <glossary tag="TCP">TCP</glossary> <glossary tag="socket">socket</glossary>.</p><p/><p><b>Parameters:</b></p><p>The <i>socketID</i> is the identifier (set when you opened the <glossary tag="socket">socket</glossary>) of the <glossary tag="socket">socket</glossary> you want to get data from.</p><p/><p>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 (|).</p><p/><p>The <i>string</i> is any expression that evaluates to a <keyword tag="string">string</keyword>. When LiveCode encounters the <i>string</i> in the <glossary tag="socket">socket</glossary> data, it stops reading. If the <i>string</i> is not encountered, the <b>read from socket</b> <glossary tag="command">command</glossary> continues reading as long as there is data to be read.</p><p/><p>The <i>amount</i> is a positive <keyword tag="integer">integer</keyword> and specifies how much data to read.</p><p/><p>The <i>chunkType</i> is one of chars, characters, words, items, lines, int1, uInt1, int2, uint2, int4, or uint4. The <b>read from socket</b> <glossary tag="command">command</glossary> reads <i>amount</i> of the specified <i>chunkType</i>. If you don't specify a <i>chunkType</i>, <i>amount</i> <keyword tag="characters">characters</keyword> are read.</p><p/><p>The <i>callbackMessage</i> is the name of a <keyword tag="message box">message</keyword> to be sent when the read is successfully completed.</p><p/><p><b>Comments:</b></p><p>The socket to read from must be opened first with the <b>open socket</b> <glossary tag="command">command</glossary>. If the <glossary tag="socket">socket</glossary> is not open, the <function tag="result">result</function> <control_st tag="function">function</control_st> is set to "Socket is not open.".</p><p/><p>The until <i>string</i> form reads data until the specified string is encountered. The for <i>amount</i> form reads data until the specified number of chunks have arrived. If you don't specify a <i>string</i> or <i>amount</i>, the <b>read from socket</b> <glossary tag="command">command</glossary> reads the next <keyword tag="character">character</keyword> of data from the <glossary tag="socket">socket</glossary>.</p><p/><p>If you specify a <i>callbackMessage</i>, the <keyword tag="message box">message</keyword> is sent to the <glossary tag="object">object</glossary> whose <property tag="script">script</property> contains the <b>read from socket</b> <glossary tag="command">command</glossary>, as soon as the read is finished. This message has two <glossary tag="parameter">parameters</glossary>: the <i>socketID</i> and the data received from the <glossary tag="socket">socket</glossary>.</p><p/><p>If you don't specify a <i>callbackMessage</i>, the <glossary tag="handler">handler</glossary> pauses until the read has been completed, or until the time set in the <property tag="socketTimeoutInterval">socketTimeoutInterval</property> <glossary tag="property">property</glossary> has passed. The data is placed in the <keyword tag="it">it</keyword> variable after reading. If you specified a <glossary tag="binary data">binary data</glossary> <i>chunkType</i> (int1, uInt1, int2, uint2, int4, or uint4), the data consists of a comma-separated list of numbers, one for the numerical value of each chunk that was read. Otherwise, the data is placed in the <keyword tag="it">it</keyword> <glossary tag="variable">variable</glossary> as it appears in the incoming data stream.</p>
  </description>
</doc>