<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Class Socket - Class Socket</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 Socket<span class="faldoc_belong"><a href="./module_feather_socket.html">[in Socket]</a></p></h1>
<p class="faldoc_brief">TCP/IP networking base class. </p>
<p class="faldoc_funcdecl">
<b>class</b> Socket
</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="#lastError">lastError</a></td><td>Numeric value of system level error that has occoured on the socket.</td></tr>
<tr><td><a href="#timedout">timedout</a></td><td>True if the last operation has timed out.</td></tr>
<tr><td><a href="#dispose">dispose()</a></td><td>Closes a socket and frees system resources associated with it. </td></tr>
<tr><td><a href="#getHost">getHost()</a></td><td>Gets the host associated with this socket. </td></tr>
<tr><td><a href="#getPort">getPort()</a></td><td>Gets the port associated with this socket. </td></tr>
<tr><td><a href="#getService">getService()</a></td><td>Returns the service name (port description) associated with this socket </td></tr>
<tr><td><a href="#getTimeout">getTimeout()</a></td><td>Returns the default timeout for this socket. </td></tr>
<tr><td><a href="#readAvailable">readAvailable()</a></td><td>Checks if there is available data to be read on this socket. </td></tr>
<tr><td><a href="#setTimeout">setTimeout()</a></td><td>Sets the default timeout for lengthy operations. </td></tr>
<tr><td><a href="#writeAvailable">writeAvailable()</a></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> Socket
</p>
<table class="faldoc_function">
</table>
<br/>
<p class="item_brief">TCP/IP networking base class. </p>
<p class="faldoc_text">The Socket class is the base class for both UDP and TCP socket. It provides common methods and properties, and so it should not be directly instantiated. </p>
<h2 class="faldoc_title">Properties</h2>
<h3 class="faldoc_funcname"><a name="lastError">lastError</a></h3>
<p class="item_brief">Numeric value of system level error that has occoured on the socket.</p>
<h3 class="faldoc_funcname"><a name="timedout">timedout</a></h3>
<p class="item_brief">True if the last operation has timed out.</p>
<h2 class="faldoc_title">Methods</h2>
<h3 class="faldoc_funcname"><a name="dispose">dispose()</a></h3>
<p class="item_brief">Closes a socket and frees system resources associated with it. </p>
<p class="faldoc_funcdecl">Socket.dispose( )</p>
<p class="faldoc_text"><p class="faldoc_text">Sockets are automatically disposed by garbage collector, but the calling program may find useful to free them immediately i.e. in tight loops while accepting and serving sockets. </p>
</p>
<h3 class="faldoc_funcname"><a name="getHost">getHost()</a></h3>
<p class="item_brief">Gets the host associated with this socket. </p>
<p class="faldoc_funcdecl">Socket.getHost( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The host address. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">For TCP sockets, this method will always return the address of the remote host, while in UDP sockets it will be the local address where the socket has been bound. </p>
</p>
<h3 class="faldoc_funcname"><a name="getPort">getPort()</a></h3>
<p class="item_brief">Gets the port associated with this socket. </p>
<p class="faldoc_funcdecl">Socket.getPort( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The port address. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">For TCP sockets, returns a numeric representation of the port to which the socket is connected. For UDP sockets, returns the local port from which the messages sent through this socket are generated, if an explicit bound request has been issued. </p>
</p>
<h3 class="faldoc_funcname"><a name="getService">getService()</a></h3>
<p class="item_brief">Returns the service name (port description) associated with this socket </p>
<p class="faldoc_funcdecl">Socket.getService( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A string containing the service name. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">For TCP sockets, returns the name of the service to which the socket is connected. For UDP sockets, returns the local service from which the messages sent through this socket are generated, if an explicit bound request has been issued. Returned values are a system-specific 1:1 mapping of numeric ports to service names. If the port has not an associated service name, the port number is returned as a string value (I.e. port 80 is returned as the string "80"). </p>
</p>
<h3 class="faldoc_funcname"><a name="getTimeout">getTimeout()</a></h3>
<p class="item_brief">Returns the default timeout for this socket. </p>
<p class="faldoc_funcdecl">Socket.getTimeout( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A numeric value (seconds or seconds fractions). </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="readAvailable">readAvailable()</a></h3>
<p class="item_brief">Checks if there is available data to be read on this socket. </p>
<p class="faldoc_funcdecl">Socket.readAvailable( [timeout] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_optparam">timeout</td><td class="faldoc_optparamdesc">Wait for a specified time in seconds or fractions. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">True if the next read operation would not block. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><b><i>InterruptedError</i></b></td><td class="faldoc_raisedesc">In case of asynchronous interruption. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This method can be used to wait for incoming data on the socket. If there are some data available for immediate read, the function returns immediately true, otherwise it returns false. </p>
<p class="faldoc_text"> If <b>timeout</b> is not given, the function will return immediately, peeking for current read availability status. If it is given, the function will wait for a specified amount of seconds, or for some data to become available for read, whichever comes first. </p>
<p class="faldoc_text">If the timeout value is negative, the function will wait forever, until some data is available. </p>
<p class="faldoc_text">This wait will block the VM and all the coroutines. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> On Unix, this function respects the VirtualMachine interruption protocol, and can be asynchronously interrupted from other threads. This functionality is not implemented on MS-Windows systems yet, and will be provided in version 0.8.12. </p>
</p>
<h3 class="faldoc_funcname"><a name="setTimeout">setTimeout()</a></h3>
<p class="item_brief">Sets the default timeout for lengthy operations. </p>
<p class="faldoc_funcdecl">Socket.setTimeout( timeout )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">timeout</td><td class="faldoc_paramdesc">Timeout in seconds and fractions. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function sets a default timeout for the read/write operations, or for other lengthy operations as connect. If -1 is set (the default at socket creation), blocking operation will wait forever, until some data is ready. In this case, readAvailable and writeAvailable methods can be used to peek for incoming data. </p>
<p class="faldoc_text">If 0 is set, read/write operations will never block, returning immediately if data is not available. If a value greater than zero is set, blocking functions will wait the specified amount of seconds for their action to complete. </p>
<p class="faldoc_text"> Whenever an operation times out, the <a href="./class_Socket.html#timedout">Socket.timedout</a> member property is set to 1. This allows to distinguish between faulty operations and timed out ones. </p>
<p class="faldoc_text"><a href="./class_Socket.html#readAvailable">Socket.readAvailable</a> and <a href="./class_Socket.html#writeAvailable">Socket.writeAvailable</a> methods do not use this setting. </p>
</p>
<h3 class="faldoc_funcname"><a name="writeAvailable">writeAvailable()</a></h3>
<p class="item_brief">Waits for the socket to be ready to write data. </p>
<p class="faldoc_funcdecl">Socket.writeAvailable( [timeout] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_optparam">timeout</td><td class="faldoc_optparamdesc">Optional wait in seconds. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">True if the socket is writeable or becomes writeable during the wait. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><b><i>InterruptedError</i></b></td><td class="faldoc_raisedesc">in case of asynchronous interruption. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This method checks for the socket to be ready for immediate writing. A socket may not be ready for writing if the OS system stack is full, which usually means that the other side has not been able to forward the received messages to the listening application. </p>
<p class="faldoc_text">The method will return true in case the socket is available for write, false otherwise. </p>
<p class="faldoc_text"> An optional <b>timeout</b> may be specified; in this case, the function will return true if the socket is immediately available or if it becomse available before the wait expires, false otherwise. The wait blocks the VM, preventing other coroutines to be processed as well. </p>
<p class="faldoc_text"> This function does not take into consideration overall timeout set by <a href="./class_Socket.html#setTimeout">Socket.setTimeout</a>. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> On Unix, this function respects the VirtualMachine interruption protocol, and can be asynchronously interrupted from other threads. This functionality is not implemented on MS-Windows systems yet, and will be provided in version 0.8.12. </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>
