<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Class TCPSocket - Class TCPSocket</title>
<link href="faldoc.css" rel="stylesheet" type="text/css"/>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
</head>
<body class="faldoc_body">
<div class="navitop">
<div class="tabs">
<ul>
<li><a href="./index.html"><span>Main</span></a></li>
<li><a href="./modules.html"><span>Modules</span></a></li>
<li><a href="./pages.html"><span>Related pages</span></a></li>
<li><a href="./groups.html"><span>Groups</span></a></li>
<li><a href="./classes.html"><span>Classes</span></a></li>
<li><a href="./objects.html"><span>Objects</span></a></li>
<li><a href="./functions.html"><span>All functions</span></a></li>
<li><a href="./enum.html"><span>Enumerations</span></a></li>
</ul>
</div>
</div>
<hr/>
<h1 class="faldoc_title">Class TCPSocket<span class="faldoc_belong"><a href="./module_feather_socket.html">[in Socket]</a></p></h1>
<p class="faldoc_brief">Provides full TCP connectivity. </p>
<p class="faldoc_funcdecl">
<b>class</b> TCPSocket \
<b>from</b> <a href="./class_Socket.html">Socket</a>
</p>
<p class="faldoc_brief"><a href="#more">more...</a></p>
<h2 class="faldoc_title">Summary</h2>
<table class="faldoc_list">
<tr><td><a href="#close">close()</a></td><td>Closes the socket. </td></tr>
<tr><td><a href="#closeRead">closeRead()</a></td><td>Closes a socket read side. </td></tr>
<tr><td><a href="#closeWrite">closeWrite()</a></td><td>Closes a socket write side. </td></tr>
<tr><td><a href="#connect">connect()</a></td><td>Connects this socket to a remote host. </td></tr>
<tr><td><a href="#isConnected">isConnected()</a></td><td>Check if this TCPSocket is currently connected with a remote host. </td></tr>
<tr><td><a href="#recv">recv()</a></td><td>Reads incoming data. </td></tr>
<tr><td><a href="#send">send()</a></td><td>Send data on the network connection. </td></tr>
</table>
<h3 class="faldoc_title">Inherited properties</h3>
<table class="faldoc_list">
<tr><td><a href="./class_Socket.html#lastError">lastError</a> from Socket </td><td>Numeric value of system level error that has occoured on the socket.</td></tr>
<tr><td><a href="./class_Socket.html#timedout">timedout</a> from Socket </td><td>True if the last operation has timed out.</td></tr>
</table>
<h3 class="faldoc_title">Inherited methods</h3>
<table class="faldoc_list">
<tr><td><a href="./class_Socket.html#dispose">dispose</a> from Socket </td><td>Closes a socket and frees system resources associated with it. </td></tr>
<tr><td><a href="./class_Socket.html#getHost">getHost</a> from Socket </td><td>Gets the host associated with this socket. </td></tr>
<tr><td><a href="./class_Socket.html#getPort">getPort</a> from Socket </td><td>Gets the port associated with this socket. </td></tr>
<tr><td><a href="./class_Socket.html#getService">getService</a> from Socket </td><td>Returns the service name (port description) associated with this socket </td></tr>
<tr><td><a href="./class_Socket.html#getTimeout">getTimeout</a> from Socket </td><td>Returns the default timeout for this socket. </td></tr>
<tr><td><a href="./class_Socket.html#readAvailable">readAvailable</a> from Socket </td><td>Checks if there is available data to be read on this socket. </td></tr>
<tr><td><a href="./class_Socket.html#setTimeout">setTimeout</a> from Socket </td><td>Sets the default timeout for lengthy operations. </td></tr>
<tr><td><a href="./class_Socket.html#writeAvailable">writeAvailable</a> from Socket </td><td>Waits for the socket to be ready to write data. </td></tr>
</table>
<a name="more"><h2 class="faldoc_title">Detailed description</h2></a>
<p class="faldoc_funcdecl">
<b>class</b> TCPSocket \
<b>from</b> <a href="./class_Socket.html">Socket</a>
</p>
<table class="faldoc_function">
</table>
<br/>
<p class="item_brief">Provides full TCP connectivity. </p>
<p class="faldoc_text"> This class is derived from the <a href="./class_Socket.html">Socket</a> class, but it also provides methods that can be used to open connection towards remote hosts. </p>
<p class="faldoc_text">The constructor reserves system resources for the socket. If the needed system resources are not available, a NetError is Raised. </p>
<h2 class="faldoc_title">Methods</h2>
<h3 class="faldoc_funcname"><a name="close">close()</a></h3>
<p class="item_brief">Closes the socket. </p>
<p class="faldoc_funcdecl">TCPSocket.close( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">False if timed out, true if succesful </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_NetError.html">NetError</a></td><td class="faldoc_raisedesc">in case of underlying connection error during the closing phase. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Closes the socket, discarding incoming messages and notifying the remote side about the event. The close message must be acknowledged by the remote host, so the function may actually fail, block and/or timeout - see setTimeout() . </p>
<p class="faldoc_text"> In case of error, a NetError is raised, while in case of timeout <b>false</b> is returned. On successful completion <b>true</b> is returned. </p>
</p>
<h3 class="faldoc_funcname"><a name="closeRead">closeRead()</a></h3>
<p class="item_brief">Closes a socket read side. </p>
<p class="faldoc_funcdecl">TCPSocket.closeRead( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">False if timed out, true if succesful </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_NetError.html">NetError</a></td><td class="faldoc_raisedesc">in case of underlying connection error during the closing phase. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Closes the socket read side, discarding incominig messages and notifying the remote side about the event. The close message must be acknowledged by the remote host, so the function may actually fail, block and/or timeout. </p>
<p class="faldoc_text">After the call, the socket can still be used to write (i.e. to finish writing pending data). This informs the remote side we're not going to read anymore, and so if the application on the remote host tries to write, it will receive an error. </p>
<p class="faldoc_text"> In case of error, a NetError is raised, while in case of timeout <b>false</b> is returned. On successful completion, true is returned. </p>
</p>
<h3 class="faldoc_funcname"><a name="closeWrite">closeWrite()</a></h3>
<p class="item_brief">Closes a socket write side. </p>
<p class="faldoc_funcdecl">TCPSocket.closeWrite( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">False if timed out, true if succesful </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_NetError.html">NetError</a></td><td class="faldoc_raisedesc">in case of underlying connection error during the closing phase. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Closes the socket write side, discarding incoming messages and notifying the remote side about the event. The close message must be acknowledged by the remote host, so the function may actually fail, block and/or timeout. </p>
<p class="faldoc_text">After the call, the socket can still be used to read (i.e. to finish reading informations incoming from the remote host). This informs the remote side we're not going to write anymore, and so if the application on the remote host tries to read, it will receive an error. </p>
<p class="faldoc_text"> In case of error, a NetError is raised, while in case of timeout <b>false</b> is returned. On successful completion, true is returned. </p>
</p>
<h3 class="faldoc_funcname"><a name="connect">connect()</a></h3>
<p class="item_brief">Connects this socket to a remote host. </p>
<p class="faldoc_funcdecl">TCPSocket.connect( host, service )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">host</td><td class="faldoc_paramdesc">Remote host to be connected to. </td></tr><tr><td class="faldoc_param">service</td><td class="faldoc_paramdesc">Port or service name to be connected to. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">False if timed out, true if succesful </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_NetError.html">NetError</a></td><td class="faldoc_raisedesc">in case of underlying connection error during the closing phase. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Connects with a remote listening TCP host. The operation may fail for a system error, in which case a NetError is raised. </p>
<p class="faldoc_text"> The connection attempt may timeout if it takes more than the time specified in <a href="./class_Socket.html#setTimeout">Socket.setTimeout</a> method. In that case, the <a href="./class_TCPSocket.html#isConnected">TCPSocket.isConnected</a> method may check if the connection has been established at a later moment. So, it is possible to set the socket timeout to 0, and then check periodically for connection success without never blocking the VM. </p>
<p class="faldoc_text">The host name may be a name to be resolved by the system resoluter or it may be an already resolved dot-quad IP, or it may be an IPV6 address. </p>
</p>
<h3 class="faldoc_funcname"><a name="isConnected">isConnected()</a></h3>
<p class="item_brief">Check if this TCPSocket is currently connected with a remote host. </p>
<p class="faldoc_funcdecl">TCPSocket.isConnected( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">True if the socket is currently connected, false otherwise. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This method checks if this TCPSocket is currently connected with a remote host. </p>
</p>
<h3 class="faldoc_funcname"><a name="recv">recv()</a></h3>
<p class="item_brief">Reads incoming data. </p>
<p class="faldoc_funcdecl">TCPSocket.recv( buffer, [size] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">buffer</td><td class="faldoc_paramdesc">A pre-allocated buffer to fill. </td></tr>
<tr><td class="faldoc_optparam">size</td><td class="faldoc_optparamdesc">Maximum size in bytes to be read. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">Amount of bytes actually read. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_NetError.html">NetError</a></td><td class="faldoc_raisedesc">on network error. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> The <b>buffer</b> parameter is a buffer to be filled: a <b>MemBuf</b> or a an empty string (for example, a string created with <b><i>strBuffer</i></b>). </p>
<p class="faldoc_text"> If the <b>size</b> parameter is provided, it is used to define how many bytes can be read and stored in the buffer. </p>
<p class="faldoc_text"> If the <b>buffer</b> parameter is a string, it is automatically resized to fit the incoming data. On a successful read, it's size will be trimmed to the amount of read data, but the internal buffer will be retained; successive reads will reuse the already available data buffer. For example: </p>
<pre class="faldoc_code">
str = ""
while mySocket.recv( str, 1024 ) > 0
> "Read: ", str.len()
... do something with str ...
end
</pre>
<p class="faldoc_text">This allocates 1024 bytes in str, which is trimmed each time to the amount of data really received, but is never re-allocated during this loop. However, this is more efficient as you spare a parameter in each call, but it makes less evident how much data you want to receive: </p>
<pre class="faldoc_code">
str = strBuffer( 1024 )
while mySocket.recv( str ) > 0
> "Read: ", str.len()
... do something with str ...
end
</pre>
<p class="faldoc_text"> If the <b>buffer</b> parameter is a MemBuf, the read data will be placed at <b><i>MemBuf.position</i></b>. After a succesful read, up to <b><i>MemBuf.limit</i></b> bytes are filled, and <b><i>MemBuf.position</i></b> is advanced. To start processing the data in the buffer, use <b><i>MamBuf.flip</i></b>(). </p>
<p class="faldoc_text">In case of system error, a NetError is raised. </p>
</p>
<h3 class="faldoc_funcname"><a name="send">send()</a></h3>
<p class="item_brief">Send data on the network connection. </p>
<p class="faldoc_funcdecl">TCPSocket.send( buffer, [size], [start] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">buffer</td><td class="faldoc_paramdesc">The buffer containing the data to be sent. </td></tr>
<tr><td class="faldoc_optparam">size</td><td class="faldoc_optparamdesc">Amount of bytes to be sent. </td></tr><tr><td class="faldoc_optparam">start</td><td class="faldoc_optparamdesc">Begin position in the buffer (in bytes). </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">Number of bytes actually sent through the network layer. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_NetError.html">NetError</a></td><td class="faldoc_raisedesc">on network error, </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> The <b>buffer</b> may be a byte-only string or a byte-wide MemBuf; it is possible to send also multibyte strings (i.e. strings containing international characters) or multi-byte memory buffers, but in that case the sent data may get corrupted as a transmission may deliver only part of a character or of a number stored in a memory buffer. </p>
<p class="faldoc_text"> When using a <b>MemBuf</b> item type, the function will try to send the data between <b><i>MemBuf.position</i></b> and <b><i>MemBuf.limit</i></b>. After a correct write, the position is moved forward accordingly to the amount of bytes sent. </p>
<p class="faldoc_text"> If a <b>size</b> parameter is not specified, the method will try to send the whole content of the buffer, otherwise it will send at maximum size bytes. </p>
<p class="faldoc_text"> If a <b>start</b> parameter is specified, then the data sent will be taken starting from that position in the buffer (counting in bytes from the start). This is useful when sending big buffers in several steps, so that it is not necessary to create substrings for each send, sparing both CPU and memory. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> The <b>start</b> and <b>count</b> parameters are ignored when using a memory buffer. </p>
<p class="faldoc_text"> The returned value may be 0 in case of timeout, otherwise it will be a number between 1 and the requested size. Programs should never assume that a successful <b>send</b> has sent all the data. </p>
<p class="faldoc_text"> In case of error, a <a href="./class_NetError.html">NetError</a> is raised. </p>
</p>
<hr/>
<div class="navibottom">
<center>
<a href="./index.html">Main</a> - <a href="./modules.html">Modules</a> - <a href="./pages.html">Related pages</a> - <a href="./groups.html">Groups</a> - <a href="./classes.html">Classes</a> - <a href="./objects.html">Objects</a> - <a href="./functions.html">All functions</a> - <a href="./enum.html">Enumerations</a>
</center>
</div>
</div>
<div class="faldoc_signature">Made with <a href="http://www.falconpl.org">faldoc 2.2.0</div>
</body>
</html>
