<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Class UDPSocket - Class UDPSocket</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 UDPSocket<span class="faldoc_belong"><a href="./module_feather_socket.html">[in Socket]</a></p></h1>
<p class="faldoc_brief">UDP (datagram) manager. </p>
<p class="faldoc_funcdecl">
<b>class</b> UDPSocket( addrOrService, [service] ) \
<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="#remote">remote</a></td><td>Contains the origin address of the last datagram received with the method.</td></tr>
<tr><td><a href="#remoteService">remoteService</a></td><td>Contains the origin port of the last datagram received with the method.</td></tr>
<tr><td><a href="#broadcast">broadcast()</a></td><td>Activates broadcasting and multicasting abilities on this UDP socket. </td></tr>
<tr><td><a href="#recv">recv()</a></td><td>Reads incoming data. </td></tr>
<tr><td><a href="#sendTo">sendTo()</a></td><td>Sends a datagram to a given address. </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> UDPSocket( addrOrService, [service] ) \
<b>from</b> <a href="./class_Socket.html">Socket</a>
</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">addrOrService</td><td class="faldoc_paramdesc">Address at which this server will be listening. </td></tr>
<tr><td class="faldoc_optparam">service</td><td class="faldoc_optparamdesc">If an address is given, service or port number (as a string) where to listen. </td></tr>
</table>
<br/>
<p class="item_brief">UDP (datagram) manager. </p>
<p class="faldoc_text">The UDPSocket class provides support for UDP transmissions (datagrams). </p>
<p class="faldoc_text">The constructor reserves the needed system resources and return an UDPSocket object that can be used to send and receive datagrams. </p>
<h2 class="faldoc_title">Properties</h2>
<h3 class="faldoc_funcname"><a name="remote">remote</a></h3>
<p class="item_brief">Contains the origin address of the last datagram received with the method.</p>
<h3 class="faldoc_funcname"><a name="remoteService">remoteService</a></h3>
<p class="item_brief">Contains the origin port of the last datagram received with the method.</p>
<h2 class="faldoc_title">Methods</h2>
<h3 class="faldoc_funcname"><a name="broadcast">broadcast()</a></h3>
<p class="item_brief">Activates broadcasting and multicasting abilities on this UDP socket. </p>
<p class="faldoc_funcdecl">UDPSocket.broadcast( )</p>
<table class="faldoc_function">
<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 system error. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This is provided as a method separated from the socket constructor as, on some systems, this call requires administrator privileges to be successful. </p>
</p>
<h3 class="faldoc_funcname"><a name="recv">recv()</a></h3>
<p class="item_brief">Reads incoming data. </p>
<p class="faldoc_funcdecl">UDPSocket.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">the 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"> This method works as the <a href="./class_TCPSocket.html#recv">TCPSocket.recv</a> method, with the only difference that the incoming datagram is always completely read, provided that the specified size is enough to store the data. </p>
<p class="faldoc_text"> Also, the <a href="./class_UDPSocket.html#remote">UDPSocket.remote</a> and <a href="./class_UDPSocket.html#remoteService">UDPSocket.remoteService</a> properties of the receiving object are filled with the address and port of the host sending the packet. </p>
<p class="faldoc_text">In case of system error, a NetError is raised. </p>
</p>
<h3 class="faldoc_funcname"><a name="sendTo">sendTo()</a></h3>
<p class="item_brief">Sends a datagram to a given address. </p>
<p class="faldoc_funcdecl">UDPSocket.sendTo( host, service, buffer, [size], [start] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">host</td><td class="faldoc_paramdesc">Remote host where to send the datagram. </td></tr><tr><td class="faldoc_param">service</td><td class="faldoc_paramdesc">Remote service or port number where to send the datagram. </td></tr><tr><td class="faldoc_param">buffer</td><td class="faldoc_paramdesc">The buffer to be sent. </td></tr>
<tr><td class="faldoc_optparam">size</td><td class="faldoc_optparamdesc">Amount of bytes from the buffer to be sent. </td></tr><tr><td class="faldoc_optparam">start</td><td class="faldoc_optparamdesc">Begin position in the buffer. </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"> This method works as the TCPSocket.send method, with the main difference that the outgoing datagram can be directed towards a specified <b>host</b>, and that a whole datagram is always completely filled before being sent, provided that the specified size does not exceed datagram size limits. </p>
<p class="faldoc_text"> The <b>host</b> parameter may be an host name to be resolved or an address; if the <a href="./class_UDPSocket.html#broadcast">UDPSocket.broadcast</a> method has been successfully called, it may be also a multicast or broadcast address. </p>
<p class="faldoc_text"> The <b>service</b> parameter is a string containing either a service name (i.e. "http") or a numeric port number (i.e. "80", as a string). </p>
<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_note"><span class="faldoc_notetype">Note:</span> If the <b>buffer</b> is a MemBuf item, <b>size</b> and <b>start</b> parameters are ignored, and the buffer <b>MemBuf.position</b> and <b>MemBuf.limit</b> are used to determine how much data can be received. After a successful receive, the value of <b>MemBuf.position</b> is moved forward accordingly. </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. 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). </p>
<p class="faldoc_text">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_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>sendTo</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>
