Mercurial > luasocket
diff doc/udp.html @ 0:4b915342e2a8
LuaSocket 2.0.2 + CMake build description.
| author | Eric Wing <ewing . public |-at-| gmail . com> |
|---|---|
| date | Tue, 26 Aug 2008 18:40:01 -0700 |
| parents | |
| children |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/udp.html Tue Aug 26 18:40:01 2008 -0700 @@ -0,0 +1,416 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> + +<head> +<meta name="description" content="LuaSocket: The UDP support"> +<meta name="keywords" content="Lua, LuaSocket, Socket, UDP, Library, Network, Support"> +<title>LuaSocket: UDP support</title> +<link rel="stylesheet" href="reference.css" type="text/css"> +</head> + +<body> + +<!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<div class=header> +<hr> +<center> +<table summary="LuaSocket logo"> +<tr><td align=center><a href="http://www.lua.org"> +<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> +</a></td></tr> +<tr><td align=center valign=top>Network support for the Lua language +</td></tr> +</table> +<p class=bar> +<a href="home.html">home</a> · +<a href="home.html#download">download</a> · +<a href="installation.html">installation</a> · +<a href="introduction.html">introduction</a> · +<a href="reference.html">reference</a> +</p> +</center> +<hr> +</div> + + +<!-- udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<h2 id=udp>UDP</h2> + +<!-- socket.udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class="name" id="socket.udp"> +socket.<b>udp()</b> +</p> + +<p class="description"> +Creates and returns an unconnected UDP object. Unconnected objects support the +<a href="#sendto"><tt>sendto</tt></a>, +<a href="#receive"><tt>receive</tt></a>, +<a href="#receivefrom"><tt>receivefrom</tt></a>, +<a href="#getsockname"><tt>getsockname</tt></a>, +<a href="#setoption"><tt>setoption</tt></a>, +<a href="#settimeout"><tt>settimeout</tt></a>, +<a href="#setpeername"><tt>setpeername</tt></a>, +<a href="#setsockname"><tt>setsockname</tt></a>, and +<a href="#close"><tt>close</tt></a>. +The <a href="#setpeername"><tt>setpeername</tt></a> +is used to connect the object. +</p> + +<p class="return"> +In case of success, a new unconnected UDP object +returned. In case of error, <b><tt>nil</tt></b> is returned, followed by +an error message. +</p> + +<!-- close +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class="name" id="close"> +connected:<b>close()</b><br> +unconnected:<b>close()</b> +</p> + +<p class="description"> +Closes a UDP object. The internal socket +used by the object is closed and the local address to which the +object was bound is made available to other applications. No +further operations (except for further calls to the <tt>close</tt> +method) are allowed on a closed socket. +</p> + +<p class="note"> +Note: It is important to close all used sockets +once they are not needed, since, in many systems, each socket uses +a file descriptor, which are limited system resources. +Garbage-collected objects are automatically closed before +destruction, though. +</p> + +<!-- getpeername +++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class="name" id="getpeername"> +connected:<b>getpeername()</b> +</p> + +<p class="description"> +Retrieves information about the peer +associated with a connected UDP object. +</p> + +<p class="return"> +Returns the IP address and port number of the peer. +</p> + +<p class="note"> +Note: It makes no sense to call this method on unconnected objects. +</p> + +<!-- getsockname +++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class="name" id="getsockname"> +connected:<b>getsockname()</b><br> +unconnected:<b>getsockname()</b> +</p> + +<p class="description"> +Returns the local address information associated to the object. +</p> + +<p class="return"> +The method returns a string with local IP +address and a number with the port. In case of error, the method +returns <b><tt>nil</tt></b>. +</p> + +<p class="note"> +Note: UDP sockets are not bound to any address +until the <a href="#setsockname"><tt>setsockname</tt></a> or the +<a href="#sendto"><tt>sendto</tt></a> method is called for the +first time (in which case it is bound to an ephemeral port and the +wild-card address). +</p> + +<!-- receive +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class="name" id="receive"> +connected:<b>receive(</b>[size]<b>)</b><br> +unconnected:<b>receive(</b>[size]<b>)</b> +</p> + +<p class="description"> +Receives a datagram from the UDP object. If +the UDP object is connected, only datagrams coming from the peer +are accepted. Otherwise, the returned datagram can come from any +host. +</p> + +<p class="parameters"> +The optional <tt>size</tt> parameter +specifies the maximum size of the datagram to be retrieved. If +there are more than <tt>size</tt> bytes available in the datagram, +the excess bytes are discarded. If there are less then +<tt>size</tt> bytes available in the current datagram, the +available bytes are returned. If <tt>size</tt> is omitted, the +maximum datagram size is used (which is currently limited by the +implementation to 8192 bytes). +</p> + +<p class="return"> +In case of success, the method returns the +received datagram. In case of timeout, the method returns +<b><tt>nil</tt></b> followed by the string '<tt>timeout</tt>'. +</p> + +<!-- receivefrom +++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class="name" id="receivefrom"> +unconnected:<b>receivefrom(</b>[size]<b>)</b> +</p> + +<p class="description"> +Works exactly as the <a href="#receive"><tt>receive</tt></a> +method, except it returns the IP +address and port as extra return values (and is therefore slightly less +efficient). +</p> + +<!-- send ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class="name" id="send"> +connected:<b>send(</b>datagram<b>)</b> +</p> + +<p class="description"> +Sends a datagram to the UDP peer of a connected object. +</p> + +<p class="parameters"> +<tt>Datagram</tt> is a string with the datagram contents. +The maximum datagram size for UDP is 64K minus IP layer overhead. +However datagrams larger than the link layer packet size will be +fragmented, which may deteriorate performance and/or reliability. +</p> + +<p class="return"> +If successful, the method returns 1. In case of +error, the method returns <b><tt>nil</tt></b> followed by an error message. +</p> + +<p class="note"> +Note: In UDP, the <tt>send</tt> method never blocks +and the only way it can fail is if the underlying transport layer +refuses to send a message to the specified address (i.e. no +interface accepts the address). +</p> + +<!-- sendto ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class="name" id="sendto"> +unconnected:<b>sendto(</b>datagram, ip, port<b>)</b> +</p> + +<p class="description"> +Sends a datagram to the specified IP address and port number. +</p> + +<p class="parameters"> +<tt>Datagram</tt> is a string with the +datagram contents. +The maximum datagram size for UDP is 64K minus IP layer overhead. +However datagrams larger than the link layer packet size will be +fragmented, which may deteriorate performance and/or reliability. +<tt>Ip</tt> is the IP address of the recipient. +Host names are <em>not</em> allowed for performance reasons. + +<tt>Port</tt> is the port number at the recipient. +</p> + +<p class="return"> +If successful, the method returns 1. In case of +error, the method returns <b><tt>nil</tt></b> followed by an error message. +</p> + +<p class="note"> +Note: In UDP, the <tt>send</tt> method never blocks +and the only way it can fail is if the underlying transport layer +refuses to send a message to the specified address (i.e. no +interface accepts the address). +</p> + +<!-- setpeername +++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class="name" id="setpeername"> +connected:<b>setpeername(</b>'*'<b>)</b><br> +unconnected:<b>setpeername(</b>address, port<b>)</b> +</p> + +<p class="description"> +Changes the peer of a UDP object. This +method turns an unconnected UDP object into a connected UDP +object or vice versa. +</p> + +<p class="description"> +For connected objects, outgoing datagrams +will be sent to the specified peer, and datagrams received from +other peers will be discarded by the OS. Connected UDP objects must +use the <a href="#send"><tt>send</tt></a> and +<a href="#receive"><tt>receive</tt></a> methods instead of +<a href="#sendto"><tt>sendto</tt></a> and +<a href="#receivefrom"><tt>receivefrom</tt></a>. +</p> + +<p class="parameters"> +<tt>Address</tt> can be an IP address or a +host name. <tt>Port</tt> is the port number. If <tt>address</tt> is +'<tt>*</tt>' and the object is connected, the peer association is +removed and the object becomes an unconnected object again. In that +case, the <tt>port</tt> argument is ignored. +</p> + +<p class="return"> +In case of error the method returns +<b><tt>nil</tt></b> followed by an error message. In case of success, the +method returns 1. +</p> + +<p class="note"> +Note: Since the address of the peer does not have +to be passed to and from the OS, the use of connected UDP objects +is recommended when the same peer is used for several transmissions +and can result in up to 30% performance gains. +</p> + +<!-- setsockname +++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class="name" id="setsockname"> +unconnected:<b>setsockname(</b>address, port<b>)</b> +</p> + +<p class="description"> +Binds the UDP object to a local address. +</p> + +<p class="parameters"> +<tt>Address</tt> can be an IP address or a +host name. If <tt>address</tt> is '<tt>*</tt>' the system binds to +all local interfaces using the constant <tt>INADDR_ANY</tt>. If +<tt>port</tt> is 0, the system chooses an ephemeral port. +</p> + +<p class="return"> +If successful, the method returns 1. In case of +error, the method returns <b><tt>nil</tt></b> followed by an error +message. +</p> + +<p class="note"> +Note: This method can only be called before any +datagram is sent through the UDP object, and only once. Otherwise, +the system automatically binds the object to all local interfaces +and chooses an ephemeral port as soon as the first datagram is +sent. After the local address is set, either automatically by the +system or explicitly by <tt>setsockname</tt>, it cannot be +changed. +</p> + +<!-- setoption +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class="name" id="setoption"> +connected:<b>setoption(</b>option [, value]<b>)</b><br> +unconnected:<b>setoption(</b>option [, value]<b>)</b> +</p> + +<p class="description"> +Sets options for the UDP object. Options are +only needed by low-level or time-critical applications. You should +only modify an option if you are sure you need it.</p> +<p class="parameters"><tt>Option</tt> is a string with the option +name, and <tt>value</tt> depends on the option being set: +</p> + +<ul> +<li>'<tt>dontroute</tt>': Setting this option to <tt>true</tt> +indicates that outgoing messages should bypass the standard routing +facilities;</li> +<li>'<tt>broadcast</tt>': Setting this option to <tt>true</tt> +requests permission to send broadcast datagrams on the +socket.</li> +</ul> + +<p class="return"> +The method returns 1 in case of success, or +<b><tt>nil</tt></b> followed by an error message otherwise. +</p> + +<p class="note"> +Note: The descriptions above come from the man +pages. +</p> + +<!-- settimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<p class="name" id="settimeout"> +connected:<b>settimeout(</b>value<b>)</b><br> +unconnected:<b>settimeout(</b>value<b>)</b> +</p> + +<p class="description"> +Changes the timeout values for the object. By default, the +<a href="#receive"><tt>receive</tt></a> and +<a href="#receivefrom"><tt>receivefrom</tt></a> +operations are blocking. That is, any call to the methods will block +indefinitely, until data arrives. The <tt>settimeout</tt> function defines +a limit on the amount of time the functions can block. When a timeout is +set and the specified amount of time has elapsed, the affected methods +give up and fail with an error code. +</p> + +<p class="parameters"> +The amount of time to wait is specified as +the <tt>value</tt> parameter, in seconds. The <b><tt>nil</tt></b> timeout +<tt>value</tt> allows operations to block indefinitely. Negative +timeout values have the same effect. +</p> + +<p class="note"> +Note: In UDP, the <a href="#send"><tt>send</tt></a> +and <a href="#sentdo"><tt>sendto</tt></a> methods never block (the +datagram is just passed to the OS and the call returns +immediately). Therefore, the <tt>settimeout</tt> method has no +effect on them. +</p> + +<p class="note"> +Note: The old <tt>timeout</tt> method is +deprecated. The name has been changed for sake of uniformity, since +all other method names already contained verbs making their +imperative nature obvious. +</p> + +<!-- footer ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> + +<div class=footer> +<hr> +<center> +<p class=bar> +<a href="home.html">home</a> · +<a href="home.html#download">download</a> · +<a href="installation.html">installation</a> · +<a href="introduction.html">introduction</a> · +<a href="reference.html">reference</a> +</p> +<p> +<small> +Last modified by Diego Nehab on <br> +Thu Apr 20 00:26:01 EDT 2006 +</small> +</p> +</center> +</div> + +</body> +</html>