Almost done with manual...

This commit is contained in:
Diego Nehab 2004-06-15 23:00:56 +00:00
parent cb03a0e954
commit 843a431ef9
5 changed files with 165 additions and 194 deletions

View File

@ -70,7 +70,7 @@ The function returns a string with the host name.
<!-- tohostname +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- tohostname +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=tohostname> <p class=name id=tohostname>
socket.dns.<b>tohostname()</b> socket.dns.<b>tohostname(</b>address<b>)</b>
</p> </p>
<p class=description> <p class=description>
@ -91,7 +91,7 @@ followed by an error message.
<!-- toip +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- toip +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=toip> <p class=name id=toip>
socket.dns.<b>toip()</b> socket.dns.<b>toip(</b>address<b>)</b>
</p> </p>
<p class=description> <p class=description>

View File

@ -98,17 +98,22 @@ Note: MIME headers are independent of order. Therefore, there is no problem
in representing them in a Lua table. in representing them in a Lua table.
</p> </p>
<p>
The following constants can be set to control the default behaviour of
the HTTP module:
</p>
<ul>
<li> <tt>PORT</tt>: default port used for connections;
<li> <tt>PROXY</tt>: default proxy used for connections;
<li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations;
<li> <tt>USERAGENT</tt>: default user agent reported to server.
</ul>
<!-- http.get +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- http.get +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=get> <p class=name id=get>
socket.http.<b>get(</b>url<b>)</b><br> http.<b>get(</b>url<b>)</b><br>
socket.http.<b>get{</b><br>
&nbsp;&nbsp;url = <i>string</i>,<br>
&nbsp;&nbsp;headers = <i>header-table</i>,<br>
&nbsp;&nbsp;user = <i>string</i>,<br>
&nbsp;&nbsp;password = <i>string</i>,<br>
&nbsp;&nbsp;stay = <i>bool</i>,<br>
<b>}</b>
</p> </p>
<p class=description> <p class=description>
@ -116,18 +121,13 @@ Performs the HTTP method <tt>GET</tt>.
</p> </p>
<p class=parameters> <p class=parameters>
The function can be <tt>Url</tt> identifies the entity to retrieve.
called either directly with a <tt>url</tt> or with a <em>request table</em>.
The use of a request table allows complete control over the components of
the request. Values passed explicitly as fields of the request table
override those given by the <tt>url</tt>. For a description of the fields,
see the <a href=#request><tt>request</tt></a> function.
</p> </p>
<p class=return> <p class=return>
The function returns the response message body, the mime headers, the If successful, the function returns the response message body, the mime
status code and an error message (if any). In case of failure, the headers, and the status code. In case of failure, the
function returns all information it managed to gather. function returns <tt><b>nil</b></tt> followed by an error message.
</p> </p>
<p class=note> <p class=note>
@ -136,35 +136,30 @@ Note: The function is trivially implemented with the use of the
</p> </p>
<pre class=example> <pre class=example>
-- load the http module
http = require("http")
-- connect to server "www.tecgraf.puc-rio.br" and retrieves this manual -- connect to server "www.tecgraf.puc-rio.br" and retrieves this manual
-- file from "/luasocket/http.html" -- file from "/luasocket/http.html"
b, h, c, e = socket.http.get("http://www.tecgraf.puc-rio.br/luasocket/http.html") b, h, c = http.get("http://www.tecgraf.puc-rio.br/luasocket/http.html")
-- connect to server "www.tecgraf.puc-rio.br" and tries to retrieve -- connect to server "www.tecgraf.puc-rio.br" and tries to retrieve
-- "~diego/auth/index.html". Fails because authentication is needed. -- "~diego/auth/index.html". Fails because authentication is needed.
b, h, c, e = socket.http.get("http://www.tecgraf.puc-rio.br/~diego/auth/index.html") b, h, c = http.get("http://www.tecgraf.puc-rio.br/~diego/auth/index.html")
-- b returns some useless page telling about the denied access, -- b returns some useless page telling about the denied access,
-- h returns authentication information -- h returns authentication information
-- and c returns with value 401 (Authentication Required) -- and c returns with value 401 (Authentication Required)
-- tries to connect to server "wrong.host" to retrieve "/" -- tries to connect to server "wrong.host" to retrieve "/"
-- and fails because the host does not exist. -- and fails because the host does not exist.
b, h, c, e = socket.http.get("http://wrong.host/") r, e = http.get("http://wrong.host/")
-- b, h, c are nil, and e returns with value "host not found" -- r is nil, and e returns with value "host not found"
</pre> </pre>
<!-- http.post ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- http.post ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=post> <p class=name id=post>
socket.http.<b>post(</b>url, body<b>)</b><br> http.<b>post(</b>url, body<b>)</b><br>
socket.http.<b>post{</b><br>
&nbsp;&nbsp; url = <i>string</i>,<br>
&nbsp;&nbsp; headers = <i>header-table</i>,<br>
&nbsp;&nbsp; body = <i>string</i>,<br>
&nbsp;&nbsp; user = <i>string</i>,<br>
&nbsp;&nbsp; password = <i>string</i>,<br>
&nbsp;&nbsp; stay = <i>bool</i>,<br>
<b>}</b>
</p> </p>
<p class=description> <p class=description>
@ -181,50 +176,64 @@ Note: This function is also trivially implemented with the use of the
<!-- http.request ++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- http.request ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=request> <p class=name id=request>
socket.http.<b>request{</b><br> http.<b>request{</b><br>
&nbsp;&nbsp;method = <i>string</i>,<br>
&nbsp;&nbsp;url = <i>string</i>,<br> &nbsp;&nbsp;url = <i>string</i>,<br>
&nbsp;&nbsp;headers = <i>header-table</i>,<br> &nbsp;&nbsp;[sink = <i>LTN12 sink</i>],]<br>
&nbsp;&nbsp;body = <i>string</i>,<br> &nbsp;&nbsp;[method = <i>string</i>,]<br>
&nbsp;&nbsp;user = <i>string</i>,<br> &nbsp;&nbsp;[headers = <i>header-table</i>,]<br>
&nbsp;&nbsp;password = <i>string</i>,<br> &nbsp;&nbsp;[source = <i>LTN12 source</i>],<br>
&nbsp;&nbsp;stay = <i>string</i>,<br> &nbsp;&nbsp;[step = <i>LTN12 pump step</i>,]<br>
&nbsp;&nbsp;[proxy = <i>string</i>,]<br>
&nbsp;&nbsp;[redirect = <i>boolean</i>]<br>
<b>}</b> <b>}</b>
</p> </p>
<p class=description> <p class=description>
Performs the generic HTTP request using. Performs the generic HTTP request, controled by a request table.
</p> </p>
<p class=parameters> <p class=parameters>
The request uses <tt>method</tt> on <tt>url</tt> The most important parameters are the <tt>url</tt> and the LTN12
sending the request <tt>headers</tt> and request <tt>body</tt> in the <tt>sink</tt> that will receive the downloaded content.
request message. If authentication information is provided, the function Any part of the <tt>url</tt> can be overriden by including
the appropriate field in the request table.
If authentication information is provided, the function
uses the Basic Authentication Scheme (see <a href="#authentication">note</a>) uses the Basic Authentication Scheme (see <a href="#authentication">note</a>)
to retrieve the document. <tt>User</tt> and <tt>password</tt> provided to retrieve the document. If <tt>sink</tt> is <tt><b>nil</b></tt>, the
explicitly override those given by the <tt>url</tt>. The <tt>stay</tt> function discards the downloaded data. The optional parameters are the
parameter, when set to anything but <b><tt>nil</tt></b>, prevents the function following:
from automatically following 301 or 302 server redirect messages.
</p> </p>
<ul>
<li><tt>method</tt>: The HTTP request method. Defaults to "GET";
<li><tt>headers</tt>: Any additional HTTP headers to send with the request;
<li><tt>source</tt>: LTN12 source to provide the request body. If there
is a body, you need to provide an appropriate "<tt>content-length</tt>"
request header field, or the function will attempt to send the body as
"<tt>chunked</tt>" (something few servers support). Defaults to the empty source;
<li><tt>step</tt>: LTN12 pump step function used to move data.
Defaults to the LTN12 <tt>pump.step</tt> function.
<li><tt>proxy</tt>: The URL of a proxy server to use. Defaults to no proxy;
<li><tt>redirect</tt>: Set to <tt><b>false</b></tt> to prevent the
function from automatically following 301 or 302 server redirect messages.
</ul>
<p class=return> <p class=return>
The function returns a table with all components of the response message In case of failure, the function returns <tt><b>nil</b></tt> followed by an
it managed to retrieve. The response table has the following form: error message. If successful, the function returns a table
with all components of the response message. The response table has the following form:
</p> </p>
<blockquote><tt> <blockquote><tt>
response = {<br> respt = {<br>
&nbsp;&nbsp;body = <i>string</i>,<br>
&nbsp;&nbsp;headers = <i>header-table</i>,<br> &nbsp;&nbsp;headers = <i>header-table</i>,<br>
&nbsp;&nbsp;status = <i>string</i>,<br> &nbsp;&nbsp;status = <i>string</i>,<br>
&nbsp;&nbsp;code = <i>number</i>,<br> &nbsp;&nbsp;code = <i>number</i>,<br>
&nbsp;&nbsp;error = <i>string</i><br>
} }
</tt></blockquote> </tt></blockquote>
<p class=return> <p class=return>
Even when there was failure (URL not found, for example), the Even when there was failure (URL not found, for example), the
function may succeed retrieving a message body (a web page informing the function usually succeeds retrieving a message body (a web page informing the
URL was not found or some other useless page). To make sure the URL was not found or some other useless page). To make sure the
operation was successful, check the returned status <tt>code</tt>. For operation was successful, check the returned status <tt>code</tt>. For
a list of the possible values and their meanings, refer to <a a list of the possible values and their meanings, refer to <a
@ -233,15 +242,18 @@ href="http://www.cs.princeton.edu/~diego/rfc/rfc2616.txt">RFC
</p> </p>
<pre class=example> <pre class=example>
-- load the http module
http = require("http")
-- Requests information about a document, without downloading it. -- Requests information about a document, without downloading it.
-- Useful, for example, if you want to display a download gauge and need -- Useful, for example, if you want to display a download gauge and need
-- to know the size of the document in advance -- to know the size of the document in advance
response = socket.http.request { respt = http.request {
method = "HEAD", method = "HEAD",
url = "http://www.tecgraf.puc-rio.br/~diego" url = "http://www.tecgraf.puc-rio.br/~diego"
} }
-- Would return the following headers: -- Would return the following headers:
-- response.headers = { -- respt.headers = {
-- date = "Tue, 18 Sep 2001 20:42:21 GMT", -- date = "Tue, 18 Sep 2001 20:42:21 GMT",
-- server = "Apache/1.3.12 (Unix) (Red Hat/Linux)", -- server = "Apache/1.3.12 (Unix) (Red Hat/Linux)",
-- ["last-modified"] = "Wed, 05 Sep 2001 06:11:20 GMT", -- ["last-modified"] = "Wed, 05 Sep 2001 06:11:20 GMT",
@ -276,10 +288,14 @@ authentication is required.
</p> </p>
<pre class=example> <pre class=example>
-- load required modules
http = require("http")
mime = require("mime")
-- Connect to server "www.tecgraf.puc-rio.br" and tries to retrieve -- Connect to server "www.tecgraf.puc-rio.br" and tries to retrieve
-- "~diego/auth/index.html", using the provided name and password to -- "~diego/auth/index.html", using the provided name and password to
-- authenticate the request -- authenticate the request
response = socket.http.request{ respt = http.request{
url = "http://www.tecgraf.puc-rio.br/~diego/auth/index.html", url = "http://www.tecgraf.puc-rio.br/~diego/auth/index.html",
user = "diego", user = "diego",
password = "password" password = "password"
@ -287,83 +303,12 @@ response = socket.http.request{
-- Alternatively, one could fill the appropriate header and authenticate -- Alternatively, one could fill the appropriate header and authenticate
-- the request directly. -- the request directly.
headers = { respt = http.request {
authentication = "Basic " .. socket.code.base64("diego:password")
}
response = socket.http.request {
url = "http://www.tecgraf.puc-rio.br/~diego/auth/index.html", url = "http://www.tecgraf.puc-rio.br/~diego/auth/index.html",
headers = headers headers = { authentication = "Basic " .. (mime.b64("diego:password")) }
} }
</pre> </pre>
<!-- request_cb +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=request_cb>
socket.http.<b>request_cb(</b>request, response<b>)</b>
</p>
<p class=description>
Performs the generic HTTP request.
</p>
<p class=parameters>
The function receives two tables as parameters. The <tt>request</tt> table
provides information about the request:
</p>
<blockquote><tt>
request = {<br>
&nbsp;&nbsp;method = <i>string</i>,<br>
&nbsp;&nbsp;url = <i>string</i>,<br>
&nbsp;&nbsp;headers = <i>header-table</i>,<br>
&nbsp;&nbsp;body_cb = <i>send-callback</i>,<br>
&nbsp;&nbsp;user = <i>string</i>,<br>
&nbsp;&nbsp;password = <i>string</i>,<br>
&nbsp;&nbsp;stay = <i>string</i>,<br>
}</tt>
</blockquote>
<p class=parameters>
The function uses the HTTP method specified in
<tt>request.method</tt> on the URL <tt>request.url</tt>,
sending <tt>request.headers</tt> along with the request. The request
message body is sent via the send callback <tt>request.body_cb</tt>.
If authentication information is provided, the function uses the Basic
Authentication Scheme (see <a href="#authentication">note</a>) to
retrieve the document. <tt>Request.user</tt> and
<tt>request.password</tt> override those given by the
<tt>request.url</tt>. The <tt>request.stay</tt> parameter, when set to
anything but <b><tt>nil</tt></b>, prevents the function from automatically
following 301 or 302 server redirect messages.
</p>
<p class=parameters>
The <tt>response</tt> table specifies information about the desired
response:
</p>
<blockquote><tt>
response = {<br>
&nbsp;&nbsp;body_cb = <i>receive-callback</i><br>
}</tt>
</blockquote>
<p class=return>
The function returns the same response table as that returned by the
<tt>socket.http.request</tt> function, except the response message body is
returned to the receive callback given by the
<tt>response.body_cb</tt> field.
</p>
<p class=note>
Note: For more information on callbacks, please refer to
<a href="stream.html#stream">Streaming with callbacks</a>.
</p>
<p class=note>
Note: Method names are case <em>sensitive</em>
</p>
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=footer> <div class=footer>

View File

@ -47,7 +47,7 @@ applications that deal with the Internet.
<p> <p>
Network support has been implemented so that it is both efficient and Network support has been implemented so that it is both efficient and
simple to use. LuaSocket can be used by any Lua application once it has simple to use. LuaSocket can be used by any Lua application once it has
been properly linked with and initialized by the interpreter running the been properly initialized by the interpreter running the
Lua application. The code has been tested and runs well on several Windows Lua application. The code has been tested and runs well on several Windows
and Unix platforms. and Unix platforms.
</p> </p>
@ -61,7 +61,7 @@ LuaSocket.
</p> </p>
<p> <p>
Copyright &copy; 1999-2003 Tecgraf/PUC-Rio. All rights reserved. <br> Copyright &copy; 1999-2004 Tecgraf/PUC-Rio. All rights reserved. <br>
Author: <A href="http://www.cs.princeton.edu/~diego">Diego Nehab</a> Author: <A href="http://www.cs.princeton.edu/~diego">Diego Nehab</a>
</p> </p>
@ -70,7 +70,7 @@ Author: <A href="http://www.cs.princeton.edu/~diego">Diego Nehab</a>
<h2 id=download>Download</h2> <h2 id=download>Download</h2>
<p> <p>
LuaSocket version 2.0 alpha is now available for download! It is LuaSocket version 2.0 beta is now available for download! It is
compatible with Lua&nbsp;5.0 and has been tested on compatible with Lua&nbsp;5.0 and has been tested on
Windows&nbsp;XP, Linux, and Mac OS X. Windows&nbsp;XP, Linux, and Mac OS X.
</p> </p>
@ -81,8 +81,8 @@ The library can be downloaded in source code from the following links:
<blockquote> <blockquote>
<p> <p>
<a href="luasocket-2.0-alpha.tar.gz">luasocket-2.0-alpha.tar.gz</a> <br> <a href="luasocket-2.0-beta.tar.gz">luasocket-2.0-beta.tar.gz</a> <br>
<a href="luasocket-2.0-alpha.zip">luasocket-2.0-alpha.zip</a> <a href="luasocket-2.0-beta.zip">luasocket-2.0-beta.zip</a>
</p> </p>
</blockquote> </blockquote>
@ -112,11 +112,11 @@ option, and should be able to run the automatic test procedures.
<h2 id=thanks>Special thanks</h2> <h2 id=thanks>Special thanks</h2>
<p> <p>
Throughout LuaSocket its history, many people gave sugestions that helped Throughout LuaSocket's history, many people gave sugestions that helped
improve it. For that, I thank the Lua comunity. improve it. For that, I thank the Lua comunity.
Special thanks go to Special thanks go to
David Burgess, who has pushed the library to a new level of quality and David Burgess, who has pushed the library to a new level of quality and
from whom I have learned a lot stuff that doesn't show up in RFCs. from whom I have learned a lot of stuff that doesn't show up in RFCs.
Special thanks also to Carlos Cassino, who played a big part in the Special thanks also to Carlos Cassino, who played a big part in the
extensible design seen in the C core of LuaSocket 2.0. extensible design seen in the C core of LuaSocket 2.0.
</p> </p>
@ -127,7 +127,7 @@ extensible design seen in the C core of LuaSocket 2.0.
<p> <p>
Most of the changes for 2.0 happened in the C layer, which Everything is new! Many changes for 2.0 happened in the C layer, which
has been almost completely rewritten. The code has been ported to Lua 5.0 has been almost completely rewritten. The code has been ported to Lua 5.0
and greatly improved. There have also been some API changes and greatly improved. There have also been some API changes
that made the interface simpler and more consistent. Here are some of that made the interface simpler and more consistent. Here are some of
@ -140,15 +140,19 @@ the changes that made it into version 2.0:
pipes (on Unix) and named pipes (on windows) as a bonus; pipes (on Unix) and named pipes (on windows) as a bonus;
<li> Following the Lua 5.0 trend, all functions provided by the library are <li> Following the Lua 5.0 trend, all functions provided by the library are
in the namespace <tt>socket</tt>. Functions such as in namespaces. These should be obtained with calls to the
<tt>require</tt> function. Functions such as
send/receive/timeout/close etc do not exist anymore as stand-alone send/receive/timeout/close etc do not exist anymore as stand-alone
functions. They are now only available as methods of the appropriate functions. They are now only available as methods of the appropriate
objects; objects;
<li> All functions return a non-nil value as first return value if successful. <li> All functions return a non-nil value as first return value if successful.
All functions return whatever could be retrieved followed by error message All functions return <b><tt>nil</tt></b> followed by error message
in case of error. The best way to check for errors is to check for the in case of error;
presence of an error message;
<li> Better error messages and parameter checking;
<li> Should be interrupt safe;
<li> UDP connected sockets can break association with peer by calling <li> UDP connected sockets can break association with peer by calling
<tt>setpeername</tt> with address '<tt>*</tt>'; <tt>setpeername</tt> with address '<tt>*</tt>';
@ -157,41 +161,64 @@ the changes that made it into version 2.0:
then connect or bind if needed, and finally use I/O functions. The then connect or bind if needed, and finally use I/O functions. The
<tt>socket.connect</tt> and <tt>socket.bind</tt> functions are still <tt>socket.connect</tt> and <tt>socket.bind</tt> functions are still
provided for simplicity, but they just call <tt>socket.tcp</tt> followed provided for simplicity, but they just call <tt>socket.tcp</tt> followed
by the <tt>connect</tt> or <tt>bind</tt> methods; by the <tt>connect</tt> or <tt>bind/listen</tt> methods;
<li> Better error messages and parameter checking; <li> Greatly reduced the number of times select is called during data
transfers, by calling only on failure;
<li> TCP can set timeout value before connecting and also bind to local
address before connecting;
<li> <tt>socket.select</tt> returns associative sets and checks if
sockets had buffered data;
<li> <tt>socket.sleep</tt> and <tt>socket.time</tt> are now part of the <li> <tt>socket.sleep</tt> and <tt>socket.time</tt> are now part of the
library and are supported. They used to be available only when library and are supported. They used to be available only when
LUASOCKET_DEBUG was defined, but it turns out they might be useful for LUASOCKET_DEBUG was defined, but it turns out they might be useful for
applications; applications;
<li> Socket options interface has been improved and TCP objects also <li> <tt>socket.try</tt> and <tt>socket.protect</tt> provide a simple
support socket options. interface to exceptions that proved very in the implementation of
high-level modules;
<li> Socket options interface has been improved. TCP objects also
support socket options and many other options were added.
</ul> </ul>
<p>
Lots of changes in the Lua modules, too. The new MIME and LTN12 modules
make all other modules much more powerful. The main new functionality is
the support for multipart messages in the SMTP module.
</p>
<ul>
<li>
</ul>
<!-- incompatible +++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- incompatible +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h3 id=incompatible>Incompatibilities with previous versions</h3> <h3 id=incompatible>Incompatibilities with previous versions</h3>
<ul> <ul>
<li> The introduction of namespaces affects all programs that use LuaSocket, <li> The introduction of namespaces affects all programs that use LuaSocket,
specially code that relies on global functions. These are no longer specially code that relies on global functions. These are no longer
available. Note that even the support modules (<tt>http</tt>, <tt>smtp</tt> available. Note that even the support modules (<tt>http</tt>, <tt>smtp</tt>
etc) have been moved to the namespace (i.e. <tt>socket.http</tt>, etc) are independent now and should be "<tt>require</tt>ed";
<tt>socket.smtp</tt> etc);
<li> WARNING: The new <tt>send</tt>, <li> FTP, SMTP and HTTP are completely new; I am sure you will
agree the new stuff is better;
<li> WARNING: The new <tt>send</tt>, <tt><b>receive</b></tt>,
<tt>sendto</tt>, <tt>setpeername</tt> and <tt>setsockname</tt>, <tt>sendto</tt>, <tt>setpeername</tt> and <tt>setsockname</tt>,
<tt>ftp.put</tt>, <tt>ftp.put_cb</tt> return convention WILL break old code; return convention WILL break old code;
<li> Interface to options has changed; <li> Interface to options has changed;
<li> <tt>socket.select</tt> refuses tables that have anything that is not
an object from the group <tt>select{able}</tt>. This includes even the
'<tt>n</tt>' field. Silently ignoring objects was a source of bugs for Lua
programs.
</ul> </ul>
<!-- old ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- old ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

View File

@ -37,9 +37,9 @@
<p> <p>
Communication in LuaSocket is performed via I/O objects. These can Communication in LuaSocket is performed via I/O objects. These can
represent different network domains. Currently, support is represent different network domains. Currently, support is provided for TCP
provided for TCP and UDP, but there is work in progress to implement SSL, and UDP, but nothing prevents other developers from implementing SSL, Local
Local Domain, Pipes, File Descriptors etc. I/O objects provide a standard Domain, Pipes, File Descriptors etc. I/O objects provide a standard
interface to I/O across different domains and operating systems. interface to I/O across different domains and operating systems.
LuaSocket&nbsp;2.0 has been rewritten from scratch to simplify the future LuaSocket&nbsp;2.0 has been rewritten from scratch to simplify the future
addition of new domains. addition of new domains.
@ -93,7 +93,7 @@ Previous versions of LuaSocket provided global functions for operating on
I/O objects. To give the library a Lua 5.0 feel, these have been eliminated I/O objects. To give the library a Lua 5.0 feel, these have been eliminated
from LuaSocket 2.0. I/O operations are only available as methods of the from LuaSocket 2.0. I/O operations are only available as methods of the
corresponding I/O objects. Naturally, different I/O objects accept corresponding I/O objects. Naturally, different I/O objects accept
different operations. The core functionality for TCP and UDP objects is different operations. The TCP and UDP objects are
introduced in the following sections, following a few words about introduced in the following sections, following a few words about
initialization. initialization.
</p> </p>
@ -103,18 +103,23 @@ initialization.
<h3>Initializing the library</h3> <h3>Initializing the library</h3>
<p> <p>
The core LuaSocket functionality is implemented in C, and usually available as
a dynamic library which the interpreter can load when required.
Beginning with version 2.0 and following the Lua 5.0 trend, all LuaSocket Beginning with version 2.0 and following the Lua 5.0 trend, all LuaSocket
functionality is defined inside a table (or rather a namespace) stored with functionality is defined inside a tables (or rather a namespaces). No global
the global name <tt>socket</tt>. To have this table created and its variables are ever created.
contents made available to a Lua script, the interpreter running the script Namespaces are obtained with the <tt>require</tt> Lua function, which loads
must be linked to the LuaSocket library, and to whatever libraries the and initializes any required libraries and return the namespace.
host OS requires for network access (Windows requires ws2_32.lib, for For example, the core functionality or LuaSocket is usually available
instance). LuaSocket is initialized in the from the "<tt>socket</tt>" namespace.
Lua state given as the argument to the function
<tt>luaopen_socket</tt>, the only C function exported by the library.
After initialization, scripts are free to use all of the LuaSocket API.
</p> </p>
<pre class="example">
socket = require("socket")
print(socket.VERSION)
-- LuaSocket 2.0
</pre>
<!-- tcp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- tcp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h3 id=tcp>TCP</h3> <h3 id=tcp>TCP</h3>
@ -185,29 +190,25 @@ program.
</p> </p>
<pre class=example> <pre class=example>
-- create a new TCP object -- load namespace
server, err = socket.tcp() local socket = require("socket")
assert(server, err) -- create a TCP socket and bind it to the local host, at any port
-- bind it to the local host, at any port local server = socket.try(socket.bind("*", 0))
ret, err = server:bind("*", 0)
assert(ret, err)
-- find out which port the OS chose for us -- find out which port the OS chose for us
ip, port = server:getsockname() local ip, port = server:getsockname()
-- print a message informing what's up -- print a message informing what's up
print("Please telnet to localhost on port " .. port) print("Please telnet to localhost on port " .. port)
print("After connecting, you have 10s to enter a line to be echoed") print("After connecting, you have 10s to enter a line to be echoed")
-- loop forever waiting for clients -- loop forever waiting for clients
while 1 do while 1 do
-- wait for a conection from any client -- wait for a conection from any client
client, err = server:accept() local client = server:accept()
-- make sure we don't block waiting for this client's line -- make sure we don't block waiting for this client's line
client:settimeout(10) client:settimeout(10)
-- receive the line -- receive the line
line, err = client:receive() local line, err = client:receive()
-- if there was no error, send it back to the client -- if there was no error, send it back to the client
if not err then if not err then client:send(line .. "\n") end
client:send(line .. "\n")
end
-- done with client, close the object -- done with client, close the object
client:close() client:close()
end end
@ -286,21 +287,19 @@ error message.
</p> </p>
<pre class=example> <pre class=example>
host = "localhost" -- change here to the host you want to contact -- change here to the host an port you want to contact
port = port or 13 host = "localhost"
port = 13
-- load namespace
local socket = require("socket")
-- convert host name to ip address -- convert host name to ip address
ip, err = socket.dns.toip(host) local ip = socket.try(socket.dns.toip(host))
assert(ip, err)
-- create a new UDP object -- create a new UDP object
udp = socket.udp() local udp = socket.udp()
-- contact daytime host -- contact daytime host
nsent, err = udp:sendto("anything", ip, port) socket.try(udp:sendto("anything", ip, port))
assert(not err, err) -- retrieve the answer and print results
-- retrieve the answer io.write(socket.try((udp:receive())))
dgram, err = udp:receive()
assert(dgram, err)
-- display to user
print(dgram)
</pre> </pre>
</blockquote> </blockquote>

View File

@ -44,7 +44,7 @@ MIME is described mainly in
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2045.txt">RFC 2045</a>, <a href="http://www.cs.princeton.edu/~diego/rfc/rfc2045.txt">RFC 2045</a>,
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2046.txt">2046</a>, <a href="http://www.cs.princeton.edu/~diego/rfc/rfc2046.txt">2046</a>,
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2047.txt">2047</a>, <a href="http://www.cs.princeton.edu/~diego/rfc/rfc2047.txt">2047</a>,
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2047.txt">2048</a> and <a href="http://www.cs.princeton.edu/~diego/rfc/rfc2047.txt">2048</a>, and
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2048.txt">2049</a>. <a href="http://www.cs.princeton.edu/~diego/rfc/rfc2048.txt">2049</a>.
</p> </p>