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 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=tohostname>
socket.dns.<b>tohostname()</b>
socket.dns.<b>tohostname(</b>address<b>)</b>
</p>
<p class=description>
@ -91,7 +91,7 @@ followed by an error message.
<!-- toip +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=toip>
socket.dns.<b>toip()</b>
socket.dns.<b>toip(</b>address<b>)</b>
</p>
<p class=description>

View File

@ -98,36 +98,36 @@ Note: MIME headers are independent of order. Therefore, there is no problem
in representing them in a Lua table.
</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 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=get>
socket.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>
http.<b>get(</b>url<b>)</b><br>
</p>
<p class=description>
Performs the HTTP method <tt>GET</tt>.
Performs the HTTP method <tt>GET</tt>.
</p>
<p class=parameters>
The function can be
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.
<tt>Url</tt> identifies the entity to retrieve.
</p>
<p class=return>
The function returns the response message body, the mime headers, the
status code and an error message (if any). In case of failure, the
function returns all information it managed to gather.
If successful, the function returns the response message body, the mime
headers, and the status code. In case of failure, the
function returns <tt><b>nil</b></tt> followed by an error message.
</p>
<p class=note>
@ -136,35 +136,30 @@ Note: The function is trivially implemented with the use of the
</p>
<pre class=example>
-- load the http module
http = require("http")
-- connect to server "www.tecgraf.puc-rio.br" and retrieves this manual
-- 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
-- "~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,
-- h returns authentication information
-- and c returns with value 401 (Authentication Required)
-- tries to connect to server "wrong.host" to retrieve "/"
-- and fails because the host does not exist.
b, h, c, e = socket.http.get("http://wrong.host/")
-- b, h, c are nil, and e returns with value "host not found"
r, e = http.get("http://wrong.host/")
-- r is nil, and e returns with value "host not found"
</pre>
<!-- http.post ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=post>
socket.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>
http.<b>post(</b>url, body<b>)</b><br>
</p>
<p class=description>
@ -181,50 +176,64 @@ Note: This function is also trivially implemented with the use of the
<!-- http.request ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=request>
socket.http.<b>request{</b><br>
&nbsp;&nbsp;method = <i>string</i>,<br>
http.<b>request{</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>string</i>,<br>
&nbsp;&nbsp;[sink = <i>LTN12 sink</i>],]<br>
&nbsp;&nbsp;[method = <i>string</i>,]<br>
&nbsp;&nbsp;[headers = <i>header-table</i>,]<br>
&nbsp;&nbsp;[source = <i>LTN12 source</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>
</p>
<p class=description>
Performs the generic HTTP request using.
Performs the generic HTTP request, controled by a request table.
</p>
<p class=parameters>
The request uses <tt>method</tt> on <tt>url</tt>
sending the request <tt>headers</tt> and request <tt>body</tt> in the
request message. If authentication information is provided, the function
The most important parameters are the <tt>url</tt> and the LTN12
<tt>sink</tt> that will receive the downloaded content.
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>)
to retrieve the document. <tt>User</tt> and <tt>password</tt> provided
explicitly override those given by the <tt>url</tt>. The <tt>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.
to retrieve the document. If <tt>sink</tt> is <tt><b>nil</b></tt>, the
function discards the downloaded data. The optional parameters are the
following:
</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>
The function returns a table with all components of the response message
it managed to retrieve. The response table has the following form:
In case of failure, the function returns <tt><b>nil</b></tt> followed by an
error message. If successful, the function returns a table
with all components of the response message. The response table has the following form:
</p>
<blockquote><tt>
response = {<br>
&nbsp;&nbsp;body = <i>string</i>,<br>
respt = {<br>
&nbsp;&nbsp;headers = <i>header-table</i>,<br>
&nbsp;&nbsp;status = <i>string</i>,<br>
&nbsp;&nbsp;code = <i>number</i>,<br>
&nbsp;&nbsp;error = <i>string</i><br>
}
</tt></blockquote>
<p class=return>
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
operation was successful, check the returned status <tt>code</tt>. For
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>
<pre class=example>
-- load the http module
http = require("http")
-- Requests information about a document, without downloading it.
-- Useful, for example, if you want to display a download gauge and need
-- to know the size of the document in advance
response = socket.http.request {
respt = http.request {
method = "HEAD",
url = "http://www.tecgraf.puc-rio.br/~diego"
}
-- Would return the following headers:
-- response.headers = {
-- respt.headers = {
-- date = "Tue, 18 Sep 2001 20:42:21 GMT",
-- server = "Apache/1.3.12 (Unix) (Red Hat/Linux)",
-- ["last-modified"] = "Wed, 05 Sep 2001 06:11:20 GMT",
@ -276,10 +288,14 @@ authentication is required.
</p>
<pre class=example>
-- load required modules
http = require("http")
mime = require("mime")
-- Connect to server "www.tecgraf.puc-rio.br" and tries to retrieve
-- "~diego/auth/index.html", using the provided name and password to
-- authenticate the request
response = socket.http.request{
respt = http.request{
url = "http://www.tecgraf.puc-rio.br/~diego/auth/index.html",
user = "diego",
password = "password"
@ -287,83 +303,12 @@ response = socket.http.request{
-- Alternatively, one could fill the appropriate header and authenticate
-- the request directly.
headers = {
authentication = "Basic " .. socket.code.base64("diego:password")
}
response = socket.http.request {
respt = http.request {
url = "http://www.tecgraf.puc-rio.br/~diego/auth/index.html",
headers = headers
headers = { authentication = "Basic " .. (mime.b64("diego:password")) }
}
</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 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=footer>

View File

@ -47,7 +47,7 @@ applications that deal with the Internet.
<p>
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
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
and Unix platforms.
</p>
@ -61,7 +61,7 @@ LuaSocket.
</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>
</p>
@ -70,7 +70,7 @@ Author: <A href="http://www.cs.princeton.edu/~diego">Diego Nehab</a>
<h2 id=download>Download</h2>
<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
Windows&nbsp;XP, Linux, and Mac OS X.
</p>
@ -81,8 +81,8 @@ The library can be downloaded in source code from the following links:
<blockquote>
<p>
<a href="luasocket-2.0-alpha.tar.gz">luasocket-2.0-alpha.tar.gz</a> <br>
<a href="luasocket-2.0-alpha.zip">luasocket-2.0-alpha.zip</a>
<a href="luasocket-2.0-beta.tar.gz">luasocket-2.0-beta.tar.gz</a> <br>
<a href="luasocket-2.0-beta.zip">luasocket-2.0-beta.zip</a>
</p>
</blockquote>
@ -112,11 +112,11 @@ option, and should be able to run the automatic test procedures.
<h2 id=thanks>Special thanks</h2>
<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.
Special thanks go to
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
extensible design seen in the C core of LuaSocket 2.0.
</p>
@ -127,7 +127,7 @@ extensible design seen in the C core of LuaSocket 2.0.
<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
and greatly improved. There have also been some API changes
that made the interface simpler and more consistent. Here are some of
@ -140,58 +140,85 @@ the changes that made it into version 2.0:
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
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
functions. They are now only available as methods of the appropriate
objects;
<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
in case of error. The best way to check for errors is to check for the
presence of an error message;
All functions return <b><tt>nil</tt></b> followed by error message
in case of error;
<li> UDP connected sockets can break association with peer by calling
<li> Better error messages and parameter checking;
<li> Should be interrupt safe;
<li> UDP connected sockets can break association with peer by calling
<tt>setpeername</tt> with address '<tt>*</tt>';
<li> TCP has been changed to become more uniform. First create an object,
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
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
library and are supported. They used to be available only when
LUASOCKET_DEBUG was defined, but it turns out they might be useful for
applications;
<li> Socket options interface has been improved and TCP objects also
support socket options.
<li> <tt>socket.try</tt> and <tt>socket.protect</tt> provide a simple
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>
<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 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h3 id=incompatible>Incompatibilities with previous versions</h3>
<ul>
<li> The introduction of namespaces affects all programs that use LuaSocket,
specially code that relies on global functions. These are no longer
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>,
<tt>socket.smtp</tt> etc);
etc) are independent now and should be "<tt>require</tt>ed";
<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>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> <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>
<!-- old ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

View File

@ -37,9 +37,9 @@
<p>
Communication in LuaSocket is performed via I/O objects. These can
represent different network domains. Currently, support is
provided for TCP and UDP, but there is work in progress to implement SSL,
Local Domain, Pipes, File Descriptors etc. I/O objects provide a standard
represent different network domains. Currently, support is provided for TCP
and UDP, but nothing prevents other developers from implementing SSL, Local
Domain, Pipes, File Descriptors etc. I/O objects provide a standard
interface to I/O across different domains and operating systems.
LuaSocket&nbsp;2.0 has been rewritten from scratch to simplify the future
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
from LuaSocket 2.0. I/O operations are only available as methods of the
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
initialization.
</p>
@ -103,18 +103,23 @@ initialization.
<h3>Initializing the library</h3>
<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
functionality is defined inside a table (or rather a namespace) stored with
the global name <tt>socket</tt>. To have this table created and its
contents made available to a Lua script, the interpreter running the script
must be linked to the LuaSocket library, and to whatever libraries the
host OS requires for network access (Windows requires ws2_32.lib, for
instance). LuaSocket is initialized in the
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.
functionality is defined inside a tables (or rather a namespaces). No global
variables are ever created.
Namespaces are obtained with the <tt>require</tt> Lua function, which loads
and initializes any required libraries and return the namespace.
For example, the core functionality or LuaSocket is usually available
from the "<tt>socket</tt>" namespace.
</p>
<pre class="example">
socket = require("socket")
print(socket.VERSION)
-- LuaSocket 2.0
</pre>
<!-- tcp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h3 id=tcp>TCP</h3>
@ -185,29 +190,25 @@ program.
</p>
<pre class=example>
-- create a new TCP object
server, err = socket.tcp()
assert(server, err)
-- bind it to the local host, at any port
ret, err = server:bind("*", 0)
assert(ret, err)
-- load namespace
local socket = require("socket")
-- create a TCP socket and bind it to the local host, at any port
local server = socket.try(socket.bind("*", 0))
-- 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("Please telnet to localhost on port " .. port)
print("After connecting, you have 10s to enter a line to be echoed")
-- loop forever waiting for clients
while 1 do
-- 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
client:settimeout(10)
-- receive the line
line, err = client:receive()
local line, err = client:receive()
-- if there was no error, send it back to the client
if not err then
client:send(line .. "\n")
end
if not err then client:send(line .. "\n") end
-- done with client, close the object
client:close()
end
@ -286,21 +287,19 @@ error message.
</p>
<pre class=example>
host = "localhost" -- change here to the host you want to contact
port = port or 13
-- change here to the host an port you want to contact
host = "localhost"
port = 13
-- load namespace
local socket = require("socket")
-- convert host name to ip address
ip, err = socket.dns.toip(host)
assert(ip, err)
local ip = socket.try(socket.dns.toip(host))
-- create a new UDP object
udp = socket.udp()
local udp = socket.udp()
-- contact daytime host
nsent, err = udp:sendto("anything", ip, port)
assert(not err, err)
-- retrieve the answer
dgram, err = udp:receive()
assert(dgram, err)
-- display to user
print(dgram)
socket.try(udp:sendto("anything", ip, port))
-- retrieve the answer and print results
io.write(socket.try((udp:receive())))
</pre>
</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/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">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>.
</p>