dany/luasocket
1
0
Fork 0
mirror of https://github.com/lunarmodules/luasocket.git synced 2024-12-25 12:08:21 +01:00
Code Issues Packages Projects Releases Wiki Activity

LuaSocket 2.0 User's Manual.

Browse Source
This commit is contained in:
Diego Nehab 2003-08-31 01:00:15 +00:00
parent 6789b83ff5
commit 982781f146
14 changed files with 3223 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

202
doc/code.html Normal file
View File

@ -0,0 +1,202 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>LuaSocket: Network support for the Lua language</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 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> &middot;
<a href="home.html#download">download</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>
</p>
</center>
<hr>
</div>
<!-- code +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h2 id=code>Code</h2>
<p>
The <tt>code.lua</tt> module offers routines to convert back and forth
some common types of content encoding, including Base 64 and URL
escaping. Base 64 is described in
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2045.txt">RFC
2045</a>,
URL escaping is described in
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2396.txt">RFC
2396</a>.
</p>
<!-- base64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="base64">
socket.code.<b>base64(</b>content, single<b>)</b>
</p>
<p class=description>
Applies the Base 64 content coding to a string.
</p>
<p class=parameters>
<tt>Content</tt> is the string to be encoded.
If <tt>single</tt> is set to anything
but <tt>nil</tt>, the output is returned as a single
line, otherwise the function splits the content into 76 character long
lines after encoding.
</p>
<p class=result>
The function returns the encoded string.
</p>
<pre class=example>
code = socket.code.base64("diego:password")
-- code = "ZGllZ286cGFzc3dvcmQ="
</pre>
<!-- unbase64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="unbase64">
socket.code.<b>unbase64(</b>content<b>)</b>
</p>
<p class=description>
Removes the Base 64 content coding from a string.
</p>
<p class=parameters>
<tt>Content</tt> is the string to be decoded.
</p>
<p class=result>
The function returns the decoded string.
</p>
<!-- escape +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="escape">
socket.code.<b>escape(</b>content<b>)</b>
</p>
<p class=description>
Applies the URL escaping content coding to a string
Each byte is encoded as a percent character followed
by the two byte hexadecimal representation of its integer
value.
</p>
<p class=parameters>
<tt>Content</tt> is the string to be encoded.
</p>
<p class=result>
The function returns the encoded string.
</p>
<pre class=example>
code = socket.code.escape("/#?;")
-- code = "%2f%23%3f%3b"
</pre>
<!-- unescape +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="unescape">
socket.code.<b>unescape(</b>content<b>)</b>
</p>
<p class=description>
Removes the URL escaping content coding from a string.
</p>
<p class=parameters>
<tt>Content</tt> is the string to be decoded.
</p>
<p class=return>
The function returns the decoded string.
</p>
<!-- hexa +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="hexa">
socket.code.<b>hexa(</b>content<b>)</b>
</p>
<p class=description>
Applies the hexadecimal content coding to a string.
Each byte is encoded as the byte hexadecimal
representation of its integer value. <p>
</p>
<p class=parameters>
<tt>Content</tt> is the string to be encoded.
</p>
<p class=return>
The function returns the encoded string.
</p>
<pre class=example>
code = socket.code.hexa("\16\32\255")
-- code = "1020ff"
</pre>
<!-- unhexa +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="unhexa">
socket.code.<b>unhexa(</b>content<b>)</b>
</p>
<p class=description>
Removes the hexadecimal content coding from a string.
</p>
<p class=parameters>
<tt>Content</tt> is the string to be decoded.
</p>
<p class=return>
The function returns the decoded string.
</p>
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=footer>
<hr>
<center>
<p class=bar>
<a href="home.html">home</a> &middot;
<a href="home.html#down">download</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>
</p>
<p>
<small>
Last modified by Diego Nehab on <br>
Sat Aug 9 01:00:41 PDT 2003
</small>
</p>
</center>
</div>
</body>
</html>

120
doc/dns.html Normal file
View File

@ -0,0 +1,120 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>LuaSocket: Network support for the Lua language</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 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> &middot;
<a href="home.html#download">download</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>
</p>
</center>
<hr>
</div>
<!-- dns ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h2 id=dns>DNS</h2>
<p>
The following functions can be used to convert between host names and IP
addresses. Both functions return <em>all</em> information returned by the
resolver in a table of the form:
</p>
<blockquote><tt>
resolved = {<br>
&nbsp;&nbsp;name = <i>canonic-name</i>,<br>
&nbsp;&nbsp;alias = <i>alias-list</i>,<br>
&nbsp;&nbsp;ip = <i>ip-address-list</i><br>
}
</tt> </blockquote>
<p>
Note that the <tt>alias</tt> list can be empty.
</p>
<!-- tohostname +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=tohostname>
socket.dns.<b>tohostname()</b>
</p>
<p class=description>
Converts from IP address to host name.
</p>
<p class=parameters>
<tt>Address</tt> can be an IP address or host name.
</p>
<p class=return>
The function a string with the canonic host name of the given
<tt>address</tt>, followed by a table with all information returned by
the resolver. In case of error, the function returns <tt>nil</tt>
followed by an error message.
</p>
<!-- toip +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=toip>
socket.dns.<b>toip()</b>
</p>
<p class=description>
Converts from host name to IP address.
</p>
<p class=parameters>
<tt>Address</tt> can be an IP address or host name.
</p>
<p class=return>
Returns a string with the first IP address found for <tt>address</tt>,
followed by a table with all information returned by the resolver.
In case of error, the function returns <tt>nil</tt> followed by an error
message.
</p>
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=footer>
<hr>
<center>
<p class=bar>
<a href="home.html">home</a> &middot;
<a href="home.html#down">download</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>
</p>
<p>
<small>
Last modified by Diego Nehab on <br>
Sat Aug 9 01:00:41 PDT 2003
</small>
</p>
</center>
</div>
</body>
</html>

243
doc/ftp.html Normal file
View File

@ -0,0 +1,243 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> <html>
<head>
<title>LuaSocket: Network support for the Lua language</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 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> &middot;
<a href="home.html#download">download</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>
</p>
</center>
<hr>
</div>
<!-- ftp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h2 id=ftp>FTP</h2>
<p>
FTP (File Transfer Protocol) is a protocol used to transfer files
between hosts. The module <tt>ftp.lua</tt> offers simple FTP support,
allowing applications to download and upload files, and list directory
contents. The implementation conforms to
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc0959.txt">RFC 959</a>.
</p>
<p>
URLs MUST conform to
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc1738.txt">RFC
1738</a>, that is, an URL is a string in the form:
</p>
<blockquote>
<tt>
[ftp://][&lt;user&gt;[:&lt;password&gt;]@]&lt;host&gt;[:&lt;port&gt;][/&lt;path&gt;][<i>type</i>=a|i|d]</tt>
</blockquote>
<!-- ftp.get ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=get>
socket.ftp.<b>get(</b>url<b>)</b><br>
socket.ftp.<b>get{</b><br>
&nbsp;&nbsp;url = <i>string</i>,<br>
&nbsp;&nbsp;type = <i>string</i>,<br>
&nbsp;&nbsp;user = <i>string</i>,<br>
&nbsp;&nbsp;password = <i>string</i><br>
<b>}</b>
</p>
<p class=description>
Downloads an URL from a FTP server.
</p>
<p class=parameters>
The function can be called either directly with a <tt>url</tt>
or with a <em>request table</em>.
Fields passed explicitly in the request table override those
present in the <tt>url</tt>.
</p>
<p class=parameters>
The parameter <tt>type</tt> accepts values '<tt>a</tt>' (ASCII, the
default), '<tt>i</tt>' (binary) or '<tt>d</tt>' (directory listing) and
determines the transfer type. If <tt>&lt;path&gt;</tt> ends with a
'<tt>/</tt>' or <tt>type</tt> is '<tt>d</tt>', a directory listing of
<tt>&lt;path&gt;</tt> is returned. If no <tt>user</tt> is provided in the
<tt>url</tt> or explicitly, the function tries to log in as user
'<tt>anonymous</tt>'.
</p>
<p class=return>
If successful, the function returns
the file content as a string. In case of error, the function returns
<tt>nil</tt> and an error message describing the error.
</p>
<pre class=example>
-- Log as user "anonymous" on server "ftp.tecgraf.puc-rio.br",
-- go to directory "pub/lua" and get file "lua.tar.gz" as binary.
f, e = socket.ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua/lua.tar.gz;type=i")
-- Log as user "anonymous" on server "ftp.tecgraf.puc-rio.br",
-- go to director "pub" and retrieve directory listing of directory "lua"
f, e = socket.ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua;type=d")
-- Log as user "diego", password "nehab", on server "ftp.tecgraf.puc-rio.br",
-- go to directory "tec/luasocket/bin" and retrieve file "luasocket.exe"
-- (actually, fails because of wrong password, of course)
f, e = socket.ftp.get{
url = "ftp://ftp.tecgraf.puc-rio.br/tec/luasocket/bin/luasocket.exe",
user = "diego",
password = "nehab",
type = "i"
}
-- f returns nil, and e returns an appropriate error message
</pre>
<!-- get_cb +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=get_cb>
socket.ftp.<b>get_cb{</b><br>
&nbsp;&nbsp;url = <i>string</i>,<br>
&nbsp;&nbsp;type = <i>string</i>,<br>
&nbsp;&nbsp;content_cb = <i>receive-callback</i>,<br>
&nbsp;&nbsp;user = <i>string</i>,<br>
&nbsp;&nbsp;password = <i>string</i><br>
<b>}</b>
</p>
<p class=description>
Same as <a href="#get"><tt>get</tt></a>, but the library returns
the content of the downloaded file to the receive callback
<tt>content_cb</tt>.
</p>
<p class=note>
Note: for more information on callbacks, refer to
<a href="stream.html#stream">Streaming with callbacks</a>.
</p>
<!-- put ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=put>
socket.ftp.<b>put(</b>url, content<b>)</b><br>
socket.ftp.<b>put{</b><br>
&nbsp;&nbsp;url = <i>string</i>,<br>
&nbsp;&nbsp;content = <i>string</i>,<br>
&nbsp;&nbsp;type = <i>string</i>,<br>
&nbsp;&nbsp;user = <i>string</i>,<br>
&nbsp;&nbsp;password = <i>string</i><br>
<b>}</b>
</p>
<p class=description>
Upload a file to a FTP server.
</p>
<p class=parameters>
The function can be called directly with a
<tt>url</tt> and <tt>content</tt> parameters, or with a
<em>request table</em>.
Values passed explicitly in the request table override those present in
the <tt>url</tt>. The parameter <tt>type</tt> accept values
'<tt>a</tt>' (ASCII, the default) or '<tt>i</tt>' (binary) and
determines the transfer type. If no <tt>user</tt> is provided, the
function tries to log in as '<tt>anonymous</tt>'.
</p>
<p class=return>
If successful, the function returns 1. In case of error, the
function returns <tt>nil</tt> followed by a string describing the error.
</p>
<pre class=example>
-- Log as user "anonymous" on server "ftp.free.org" and store file
-- "hello" with contents "hello world!", using binary mode for the transfer
r, e = socket.ftp.put("ftp://ftp.free.org/hello;type=i", "hello world!\n")
-- Does exactly the same, but logging in as diego
r, e = socket.ftp.put{
url = "ftp://ftp.free.org/hello",
type = "i",
user = "diego",
password = "nehab",
content = "hello world\n"
}
</pre>
</blockquote>
<!-- put_cb +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=put_cb>
socket.ftp.<b>put_cb{</b><br>
&nbsp;&nbsp;url = <i>string</i>,<br>
&nbsp;&nbsp;type = <i>string</i>,<br>
&nbsp;&nbsp;content_cb = <i>send-callback</i>,<br>
&nbsp;&nbsp;user = <i>string</i>,<br>
&nbsp;&nbsp;password = <i>string</i><br>
<b>}</b>
</p>
<p class=description>
Same as <a href="#put"><tt>put</tt></a>, but the
library obtains the contents of the file to be uploaded using the send
callback <tt>content_cb</tt>.
</p>
<p class=note>
Note: for more information on callbacks, refer to
<a href="stream.html#stream">Streaming with callbacks</a>.
</p>
<pre class=example>
-- Log as user "anonymous" on server "ftp.free.org" and store file
-- "hello" with contents of the same file in the current directory,
-- using binary mode for the transfer
r, e = socket.ftp.put_cb{
url = "ftp://ftp.free.org/hello",
type = "i",
content_cb = socket.callback.send_file(io.open("hello", "r"))
}
</pre>
</blockquote>
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=footer>
<hr>
<center>
<p class=bar>
<a href="home.html">home</a> &middot;
<a href="home.html#download">download</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>
</p>
<p>
<small>
Last modified by Diego Nehab on <br>
Sat Aug 9 01:00:41 PDT 2003
</small>
</p>
</center>
</div>
</body>
</html>

388
doc/http.html Normal file
View File

@ -0,0 +1,388 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>LuaSocket: Network support for the Lua language</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 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> &middot;
<a href="home.html#download">download</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>
</p>
</center>
<hr>
</div>
<!-- http +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h2 id=http>HTTP</h2>
<p>
HTTP (Hyper Text Transfer Protocol) is the protocol used to exchange
information between web-browsers and servers. The <tt>http.lua</tt>
module offers support for the client side of the HTTP protocol (i.e.,
the facilities that would be used by a web-browser implementation). The
implementation conforms to the HTTP/1.1 standard,
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2616.txt">RFC
2616</a>.
</p>
<p>
The module exports functions that provide HTTP functionality in different
levels of abstraction, from a simple <a
href="#get"><tt>get</tt></a>, to the generic, stream oriented
<a href="#request_cb"> <tt>request_cb</tt></a>.
</p>
<p>
URLs must conform to
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc1738.txt">RFC
1738</a>,
that is, an URL is a string in the form:
</p>
<blockquote>
<pre>
[http://][&lt;user&gt;[:&lt;password&gt;]@]&lt;host&gt;[:&lt;port&gt;][/&lt;path&gt;]
</pre>
</blockquote>
<p>
MIME headers are represented as a Lua table in the form:
</p>
<blockquote>
<table summary="MIME headers in Lua table">
<tr><td><tt>
headers = {<br>
&nbsp;&nbsp;field-1-name = <i>field-1-value</i>,<br>
&nbsp;&nbsp;field-2-name = <i>field-2-value</i>,<br>
&nbsp;&nbsp;field-3-name = <i>field-3-value</i>,
</tt></td></tr>
<tr><td align=center><tt>
&nbsp;&nbsp;...
</tt></td></tr>
<tr><td><tt>
&nbsp;&nbsp;field-n-name = <i>field-n-value</i><br>
}
</tt></td></tr>
</table>
</blockquote>
<p>
Field names are case insensitive (as specified by the standard) and all
functions work with lowercase field names.
Field values are left unmodified.
</p>
<p class=note>
Note: MIME headers are independent of order. Therefore, there is no problem
in representing them in a Lua table.
</p>
<!-- 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>
</p>
<p class=description>
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.
</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.
</p>
<p class=note>
Note: The function is trivially implemented with the use of the
<a href="#request"><tt>request</tt></a> function.
</p>
<pre class=example>
-- 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")
-- 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 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"
</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>
</p>
<p class=description>
Same as <a href="#get"><tt>get</tt></a>, except
that the <tt>POST</tt> method is used and the request
message <tt>body</tt> is sent along with the request.
</p>
<p class=note>
Note: This function is also trivially implemented with the use of the
<a href="#request"><tt>request</tt></a> function.
</p>
<!-- http.request ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=request>
socket.http.<b>request{</b><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 = <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>
<b>}</b>
</p>
<p class=description>
Performs the generic HTTP request using.
</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
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 <tt>nil</tt>, prevents the function
from automatically following 301 or 302 server redirect messages.
</p>
<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:
</p>
<blockquote><tt>
response = {<br>
&nbsp;&nbsp;body = <i>string</i>,<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
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
href="http://www.cs.princeton.edu/~diego/rfc/rfc2616.txt">RFC
2616</a>.
</p>
<pre class=example>
-- 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 {
method = "HEAD",
url = "http://www.tecgraf.puc-rio.br/~diego"
}
-- Would return the following headers:
-- response.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",
-- ["content-length"] = 15652,
-- ["connection"] = "close",
-- ["content-Type"] = "text/html"
-- }
</pre>
</blockquote>
<p class=note id=authentication>
Note: Some URLs are protected by their
servers from anonymous download. For those URLs, the server must receive
some sort of authentication along with the request or it will deny
download and return status "401&nbsp;Authentication Required".
</p>
<p class=note>
The HTTP/1.1 standard defines two authentication methods: the Basic
Authentication Scheme and the Digest Authentication Scheme, both
explained in detail in
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2068.txt">RFC 2068</a>.
</p>
<p class=note>The Basic Authentication Scheme sends
<tt>&lt;user&gt;</tt> and
<tt>&lt;password&gt;</tt> unencrypted to the server and is therefore
considered unsafe. Unfortunately, by the time of this implementation,
the wide majority of servers and browsers support the Basic Scheme only.
Therefore, this is the method used by the toolkit whenever
authentication is required.
</p>
<pre class=example>
-- 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{
url = "http://www.tecgraf.puc-rio.br/~diego/auth/index.html",
user = "diego",
password = "password"
}
-- Alternatively, one could fill the appropriate header and authenticate
-- the request directly.
headers = {
authentication = "Basic " .. socket.code.base64("diego:password")
}
response = socket.http.request {
url = "http://www.tecgraf.puc-rio.br/~diego/auth/index.html",
headers = headers
}
</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 <tt>nil</tt>, 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>
<hr>
<center>
<p class=bar>
<a href="home.html">home</a> &middot;
<a href="home.html#download">download</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>
</p>
<p>
<small>
Last modified by Diego Nehab on <br>
Sat Aug 9 01:00:41 PDT 2003
</small>
</p>
</center>
</div>
</body>
</html>

212
doc/index.html Normal file
View File

@ -0,0 +1,212 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>LuaSocket: Network support for the Lua language </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 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> &middot;
<a href="home.html#download">download</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>
</p>
</center>
<hr>
</div>
<!-- whatis +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h2 id=whatis>What is LuaSocket?</h2>
<p>
LuaSocket is a <a href="http://www.lua.org">Lua</a> extension library
that is composed by two parts: a C layer that provides support for the TCP
and UDP transport layers, and a set of Lua modules that add support for
the SMTP (sending e-mails), HTTP (WWW access) and FTP (uploading and
downloading files) protocols.
</p>
<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
Lua application. The code has been tested and runs well on several Windows
and Unix platforms.
</p>
<p>
The library is available under the same
<a href="http://www.lua.org/copyright.html">
terms and conditions</a> as the Lua language, the MIT license. The idea is
that if you can use Lua in a project, you should also be able to use
LuaSocket.
</p>
<p>
Copyright &copy; 1999-2003 Tecgraf/PUC-Rio. All rights reserved. <br>
Author: <A href="http://www.cs.princeton.edu/~diego">Diego Nehab</a>
</p>
<!-- download +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h2 id=down>Download</h2>
<p>
LuaSocket version 2.0 alpha 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>
<p>
The library can be downloaded in source code from the following links:
</p>
<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>
</p>
</blockquote>
<p>
Besides the full C and Lua source code for the library, the distribution
contains several examples, this user's manual and the test procedures.
</p>
<p>
I am also providing a Windows binary for those that want to give
LuaSocket a quick try:
</p>
<blockquote>
<p>
<a href="luasocket-2.0.exe">luasocket-2.0.exe</a>
</p>
</blockquote>
<p>
This binary has been compiled with the <tt>LUASOCKET_DEBUG</tt>
option, and should be able to run the automatic test procedures.
</p>
<!-- whatsnew +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h2 id=new>What's New</h2>
<p>
Most of the 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
the changes that made it into version 2.0:
</p>
<ul>
<li> Major C code rewrite. Code is modular and extensible. Hopefully, next
versions will include code for local domain sockets, file descriptors,
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
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;
<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;
<li> Better error messages and parameter checking;
<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.
</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);
<li> WARNING: The new <tt>send</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;
<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 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h2 id=old>Old Versions</h2>
<p>
All previous versions of the LuaSocket library can be downloaded
<a href="http://www.tecgraf.puc-rio.br/luasocket/old">here</a>. Although
these versions are no longer supported, they are still available for
those that have compatibility issues.
</p>
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=footer>
<hr>
<center>
<p class=bar>
<a href="home.html#down">download</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>
</p>
<p>
<small>
Last modified by Diego Nehab on <br>
Sun Aug 10 01:36:26 PDT 2003
</small>
</p>
</center>
</div>
</body>
</html>

328
doc/introduction.html Normal file
View File

@ -0,0 +1,328 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>LuaSocket: Network support for the Lua language</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 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> &middot;
<a href="home.html#download">download</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>
</p>
</center>
<hr>
</div>
<!-- introduction +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h2>Introduction</h2>
<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
interface to I/O across different domains and operating systems.
LuaSocket&nbsp;2.0 has been rewritten from scratch to simplify the future
addition new domains.
</p>
<p>
The LuaSocket API was designed with two goals in mind. First, users
experienced with the C API to sockets should feel comfortable using LuaSocket.
Second, the simplicity and the feel of the Lua language should be
preserved. To achieve these goals, the LuaSocket API keeps the function names and semantics the C API whenever possible, but their usage in Lua has been greatly simplified.
</p>
<p>
One of the simplifications is the timeout control
mechanism. As in C, all I/O operations are blocking by default. For
example, the <a href=tcp.html#send><tt>send</tt></a>,
<a href=tcp.html#receive><tt>receive</tt></a> and
<a href=tcp.html#accept><tt>accept</tt></a> methods
of the TCP domain will block the caller application until
the operation is completed (if ever!). However, with a call to the
<a href=tcp.html#settimeout><tt>settimeout</tt></a>
method, an application can specify upper limits on
the time it can be blocked by LuaSocket (the "<tt>total</tt>" timeout), on
the time LuaSocket can internally be blocked by any OS call (the
"<tt>block</tt>" timeout) or a combination of the two. Each LuaSocket
call might perform several OS calls, so that the two timeout values are
<em>not</em> equivalent.
</p>
<p>
Another important difference is the receive pattern capability.
Applications can read data from stream domains (such as TCP)
line by line, block by block, or until the connection is closed.
All I/O reads are buffered and the performance differences between
different receive patterns are negligible.
</p>
<p>
Finally, the host name resolution is transparent, meaning that most
functions and methods accept both IP addresses and host names. In case a
host name is given, the library queries the system's resolver and
tries the main returned IP address. Note that direct use of IP addresses
is more efficient, of course. The
<a href=dns.html#toip><tt>toip</tt></a>
and <a href=dns.html#tohostname><tt>tohostname</tt></a>
functions from the DNS module are provided to convert between host names and IP addresses.
</p>
<p>
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
introduced in the following sections, following a few words about
initialization.
</p>
<!-- initializing +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h3>Initializing the library</h3>
<p>
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, the scripts are free to use all LuaSocket API.
</p>
<!-- tcp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h3 id=tcp>TCP</h3>
<p>
TCP (Transfer Control Protocol) is reliable stream protocol. In other
words, applications communicating through TCP can send and receive data as
an error free stream of bytes. Data is split in one end and
reassembled transparently on the other end. There are no boundaries in
the data transfers. The library allows users to read data from the
sockets in several different granularity: patterns are available for
lines, arbitrary sized blocks or "read up to connection closed", all with
good performance.
</p>
<p>
The library distinguishes three types of TCP sockets: master, client and server sockets.
</p>
<p>
Master sockets are newly created TCP sockets returned by the function
<a href=tcp.html#tcp><tt>socket.tcp</tt></a>. A master socket is
transformed into a server socket
after it is associated with a <em>local</em> address by a call to the
<a href=tcp.html#bind><tt>bind</tt></a> method. Conversely, it
can be changed into a client socket with the method
<a href=tcp.html#connect><tt>connect</tt></a>,
that associates it with a <em>remote</em> address.
</p>
<p>
On server sockets, applications can use the
<a href=tcp.html#accept><tt>accept</tt></a> method
to wait for a client connection. Once a connection is established, a
client socket object is returned representing this connection. The
other methods available for server socket objects are
<a href=tcp.html#getsockname><tt>getsockname</tt></a>,
<a href=tcp.html#setoption><tt>setoption</tt></a>,
<a href=tcp.html#settimeout><tt>settimeout</tt></a> and
<a href=tcp.html#close><tt>close</tt></a>.
</p>
<p>
Client sockets are used to exchange data between two applications over
the Internet. Applications can call the methods
<a href=tcp.html#send><tt>send</tt></a> and
<a href=tcp.html#receive><tt>receive</tt></a>
to send and receive data. The other methods
available for client socket objects are
<a href=tcp.html#getsockname><tt>getsockname</tt></a>,
<a href=tcp.html#getpeername><tt>getpeername</tt></a>,
<a href=tcp.html#setoption><tt>setoption</tt></a>,
<a href=tcp.html#settimeout><tt>settimeout</tt></a> and
<a href=tcp.html#close><tt>close</tt></a>.
</p>
<p>
Example:
</p>
<blockquote>
<p>
A simple echo server, using LuaSocket. The program binds to an ephemeral
port (one that is chosen by the operating system) on the local host and
awaits client connections on that port. When a connection is established,
the program reads a line from the remote end and sends it back, closing
the connection immediately after. You can test it using the telnet
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)
-- find out which port the OS chose for us
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()
-- make sure we don't block waiting for this client's line
client:settimeout(10)
-- receive the line
line, err = client:receive()
-- if there was no error, send it back to the client
if not err then
client:send(line .. "\n")
end
-- done with client, close the object
client:close()
end
</pre>
</blockquote>
<!-- udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h3 id=udp>UDP</h3>
<p>
UDP (User Datagram Protocol) is a non-reliable datagram protocol. In
other words, applications communicating through UDP send and receive
data as independent blocks, which are not guaranteed to reach the other
end. Even when they do reach the other end, they are not guaranteed to be
error free. Data transfers are atomic, one datagram at a time. Reading
only part of a datagram discards the rest, so that the following read
operation will act on the next datagram. The advantages are in
simplicity (no connection setup) and performance (no error checking or
error correction).
</p>
<p>
An UDP socket object is created by the
<a href=udp.html#udp><tt>socket.udp</tt></a> function. UDP
sockets do not need to be connected before use. The method
<a href=udp.html#sendto><tt>sendto</tt></a>
can be used immediately after creation to
send a datagram to IP address and port. Host names are not allowed
because performing name resolution for each packet would be forbiddingly
slow. Methods
<a href=udp.html#receive><tt>receive</tt></a> and
<a href=udp.html#receivefrom><tt>receivefrom</tt></a>
can be used to retrieve datagrams, the latter returning the IP and port of
the sender as extra return values (thus being slightly less
efficient).
</p>
<p>
When communication is performed repeatedly with a single peer, an
application should call the
<a href=udp.html#setpeername><tt>setpeername</tt></a> method to specify a
permanent partner. Methods
<a href=udp.html#sendto><tt>sendto</tt></a> and
<a href=udp.html#receivefrom><tt>receivefrom</tt></a>
can no longer be used, but the method
<a href=udp.html#send><tt>send</tt></a> can be used to send data
directly to the peer, and the method
<a href=udp.html#receive><tt>receive</tt></a>
will only return datagrams originating
from that peer. There is about 30% performance gain due to this practice.
</p>
<p>
To associate an UDP socket with a local address, an application calls the
<a href=udp.html#setsockname><tt>setsockname</tt></a>
method <em>before</em> sending any datagrams. Otherwise, the socket is
automatically bound to an ephemeral address before the first data
transmission and once bound the local address cannot be changed.
The other methods available for UDP sockets are
<a href=udp.html#getpeername><tt>getpeername</tt></a>,
<a href=udp.html#getsockname><tt>getsockname</tt></a>,
<a href=udp.html#settimeout><tt>settimeout</tt></a>,
<a href=udp.html#setoption><tt>setoption</tt></a> and
<a href=udp.html#close><tt>close</tt></a>.
</p>
<p>
Example:
</p>
<blockquote>
<p>
A simple daytime client, using LuaSocket. The program connects to a remote
server and tries to retrieve the daytime, printing the answer it got or an
error message.
</p>
<pre class=example>
host = "localhost" -- change here to the host you want to contact
port = port or 13
-- convert host name to ip address
ip, err = socket.toip(host)
assert(ip, err)
-- create a new UDP object
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)
</pre>
</blockquote>
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=footer>
<hr>
<center>
<p class=bar>
<a href="home.html">home</a> &middot;
<a href="home.html#down">download</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>
</p>
<p>
<small>
Last modified by Diego Nehab on <br>
Sat Aug 9 01:00:41 PDT 2003
</small>
</p>
</center>
</div>
</body>
</html>

BIN
doc/luasocket.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 12 KiB

40
doc/reference.css Normal file
View File

@ -0,0 +1,40 @@
body {
margin-left: 1em;
margin-right: 1em;
}
body > * { margin-left: 1em; }
div.header, div.footer { margin-left: 0em; }
hr, h1, h2, h3, h4 { margin-left: 0em; }
p.name { margin-left: 0em; }
h2:first-letter, h2:first-letter, h3:first-letter { color: #00007f; }
blockquote { margin-left: 3em; }
a[href] { color: #00007f; }
p.name {
font-size: large;
font-family: monospace;
padding-top: 1em;
}
pre.example {
background: #ccc;
font-size: small;
padding: 1em;
}
hr {
background: #00007f;
border: 0px;
height: 1px;
}
ul { list-style-type: disc; }
table.index { border: 1px #00007f; }
table.index td { text-align: left; vertical-align: top; }
table.index ul { padding-top: 0em; margin-top: 0em; }

209
doc/reference.html Normal file
View File

@ -0,0 +1,209 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>LuaSocket: Network support for the Lua language </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 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> &middot;
<a href="home.html#download">download</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>
</p>
</center>
<hr>
</div>
<!-- reference +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h2>Reference</h2>
<!-- tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<table summary="TCP Index" class=index width=100%>
<colgroup> <col width="50%"> <col width="50%"> </colgroup>
<tr>
<td><ul>
<li><a href="tcp.html">TCP (socket.tcp)</a>
<ul>
<li><a href="tcp.html#accept">accept</a>
<li><a href="tcp.html#bind">bind</a>
<li><a href="tcp.html#close">close</a>
<li><a href="tcp.html#connect">connect</a>
<li><a href="tcp.html#getpeername">getpeername</a>
</ul>
</ul></td>
<td valign=top><ul>
<li><a href="tcp.html#getsockname">getsockname</a>
<li><a href="tcp.html#receive">receive</a>
<li><a href="tcp.html#send">send</a>
<li><a href="tcp.html#setoption">setoption</a>
<li><a href="tcp.html#settimeout">settimeout</a>
</ul></td>
</tr>
</table>
<hr>
<!-- udp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<table summary="UDP Index" class=index width=100%>
<colgroup> <col width="50%"> <col width="50%"> </colgroup>
<tr>
<td><ul>
<li><a href="udp.html">UDP (socket.udp)</a>
<ul>
<li><a href="udp.html#close">close</a>
<li><a href="udp.html#getpeername">getpeername</a>
<li><a href="udp.html#getsockname">getsockname</a>
<li><a href="udp.html#receive">receive</a>
<li><a href="udp.html#receivefrom">receivefrom</a>
</ul>
</ul></td>
<td><ul>
<li><a href="udp.html#send">send</a>
<li><a href="udp.html#sendto">sendto</a>
<li><a href="udp.html#setpeername">setpeername</a>
<li><a href="udp.html#setsockname">setsockname</a>
<li><a href="udp.html#setoption">setoption</a>
<li><a href="udp.html#settimeout">settimeout</a>
</ul></td>
</tr>
</table>
<hr>
<!-- http & ftp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<table summary="HTTP and FTP Index" class=index width=100% rules=cols>
<colgroup> <col width="50%"> <col width="50%"> </colgroup>
<tr>
<td valign=top><ul>
<li><a href="http.html">HTTP (socket.http)</a>
<ul>
<li><a href="http.html#get">get</a>
<li><a href="http.html#post">post</a>
<li><a href="http.html#request">request</a>
<li><a href="http.html#request_cb">request_cb</a>
</ul>
</ul></td>
<td valign=top><ul>
<li><a href="ftp.html">FTP (socket.ftp)</a>
<ul>
<li><a href="ftp.html#get">get</a>
<li><a href="ftp.html#get_cb">get_cb</a>
<li><a href="ftp.html#put">put</a>
<li><a href="ftp.html#put_cb">put_cb</a>
</ul>
</ul></td>
</tr>
</table>
<hr>
<!-- http & ftp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<table summary="Streaming Index" class=index width=100%>
<colgroup> <col width="50%"> <col width="50%"> </colgroup>
<tr><td valign=top><ul>
<li><a href="stream.html">Streaming with Callbacks</a>
<ul>
<li><a href="stream.html#receive_cb">receive_cb</a>
<li><a href="stream.html#send_cb">send_cb</a>
</ul>
</ul></td></tr>
</table>
<hr>
<!-- smtp & dns ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<table summary="SMTP and DNS Index" class=index width=100% rules=cols>
<colgroup> <col width="50%"> <col width="50%"> </colgroup>
<tr>
<td><ul>
<li><a href="smtp.html">SMTP (socket.smtp)</a>
<ul>
<li> <a href="mod.html#mail">mail</a>
</ul>
</ul></td>
<td><ul>
<li><a href="dns.html">DNS services (socket.dns)</a>
<ul>
<li><a href="dns.html#toip">toip</a>
<li><a href="dns.html#tohostname">tohostname</a>
</ul>
</ul></td>
</tr>
</table>
<hr>
<!-- url & code ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<table summary="URL and Code Index" class=index width=100% rules=cols>
<colgroup> <col width="50%"> <col width="50%"> </colgroup>
<tr>
<td valign=top><ul>
<li><a href="url.html">URL (socket.url) </a>
<ul>
<li> <a href="url.html#absolute">absolute</a>
<li> <a href="url.html#build">build</a>
<li> <a href="url.html#build_path">build_path</a>
<li> <a href="url.html#parse">parse</a>
<li> <a href="url.html#parse_path">parse_path</a>
</ul>
</ul></td>
<td valign=top><ul>
<li> <a href="code.html">Code (socket.code) </a>
<ul>
<li> <a href="code.html#base64">base64</a>
<li> <a href="code.html#unbase64">unbase64</a>
<li> <a href="code.html#escape">escape</a>
<li> <a href="code.html#unescape">unescape</a>
<li> <a href="code.html#hexa">hexa</a>
<li> <a href="code.html#unhexa">unhexa</a>
</ul>
</ul></td>
</tr>
</table>
<!-- footer ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=footer>
<hr>
<center>
<p class=bar>
<a href="home.html">home</a> &middot;
<a href="home.html#down">download</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>
</p>
<p>
<small>
Last modified by Diego Nehab on <br>
Thu Sep 27 16:18:27 EST 2001
</small>
</p>
</center>
</div>
</body>
</html>

228
doc/smtp.html Normal file
View File

@ -0,0 +1,228 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>LuaSocket: Network support for the Lua language</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 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> &middot;
<a href="home.html#download">download</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>
</p>
</center>
<hr>
</div>
<!-- smtp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h2 id=smtp>SMTP</h2>
<p>
The module <tt>smtp.lua</tt> provides functionality to send e-mail
messages. The implementation conforms to the Simple Mail Transfer Protocol,
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2821.txt">RFC 2821</a>.
The other RFC of interest in this implementation is
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2822.txt">RFC 2822</a>,
which governs the Internet Message Format.
</p>
<p>
MIME headers are represented as a Lua table in the form:
</p>
<blockquote>
<table summary="MIME headers in Lua table">
<tr><td><tt>
headers = {<br>
&nbsp;&nbsp;field-1-name = <i>field-1-value</i>,<br>
&nbsp;&nbsp;field-2-name = <i>field-2-value</i>,<br>
&nbsp;&nbsp;field-3-name = <i>field-3-value</i>,
</tt></td></tr>
<tr><td align=center><tt>
&nbsp;&nbsp;...
</tt></td></tr>
<tr><td><tt>
&nbsp;&nbsp;field-n-name = <i>field-n-value</i><br>
}
</tt></td></tr>
</table>
</blockquote>
<p>
Field names are case insensitive (as specified by the standard) and all
functions work with lowercase field names.
Field values are left unmodified.
</p>
<p class=note>
Note: MIME headers are independent of order. Therefore, there is no problem
in representing them in a Lua table.
</p>
<!-- mail +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=mail>
socket.smtp.<b>mail{</b><br>
&nbsp;&nbsp;from = <i>string</i>,<br>
&nbsp;&nbsp;rcpt = <i>string</i> or <i>string-table</i>,<br>
&nbsp;&nbsp;body = <i>string</i>,<br>
&nbsp;&nbsp;headers = <i>headers-table</i>,<br>
&nbsp;&nbsp;server = <i>string</i><br>
<b>}</b>
</p>
<p class=description>
Sends a message to a recipient list.
</p>
<p class=parameters>
<tt>Rcpt</tt> is a Lua table with one entry for each recipient, or a string
in case there is just one recipient.
The sender is given by the e-mail address <tt>from</tt>.
The message is composed by the optional MIME Headers <tt>headers</tt>
and text <tt>body</tt>. The message is sent using the server
<tt>server</tt>.
</p>
<p class=return>
If successful, the function returns 1. Otherwise, the function returns
<tt>nil</tt> followed by an error message.
</p>
<p class=note>
Big note: There is a good deal of misconception with the use of the
destination address field headers, i.e., the '<tt>To</tt>', '<tt>Cc</tt>',
and, more importantly, the '<tt>Bcc</tt>' headers. Do <em>not</em> add a
'<tt>Bcc</tt>' header to your messages because it will probably do the
exact opposite of what you expect.
</p>
<p class=note>
Only recipients specified in the recipient list will receive a copy of the
message. Each recipient of an SMTP mail message receives a copy of the
message body along with the headers, and nothing more. The headers are
considered as part of the message. The list of recipients is <em>not</em>
part of the message.
</p>
<p class=note>
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2822.txt">RFC 2822</a>
has two <em>important and short</em> sections, "3.6.3. Destination address
fields" and "5. Security considerations", explaining the proper
use of these headers. Here is a summary of what it says:
</p>
<ul>
<li> <tt>To</tt>: contains the address(es) of the primary recipient(s)
of the message;
<li> <tt>Cc</tt>: (where the "Cc" means "Carbon Copy" in the sense of
making a copy on a typewriter using carbon paper) contains the
addresses of others who are to receive the message, though the
content of the message may not be directed at them;
<li> <tt>Bcc</tt>: (where the "Bcc" means "Blind Carbon
Copy") contains addresses of recipients of the message whose addresses are not to be revealed to other recipients of the message.
</ul>
<p class=note>
The LuaSocket <tt>mail</tt> function does not interpret the headers you
pass to, but it gives you full control over what is sent and to whom
it is sent:
</p>
<ul>
<li> If someone is to receive the message, the e-mail address <em>has</em>
to be in the recipient list. This is the only parameter that controls who
gets a copy of the message;
<li> If there are multiple recipients, none of them will automatically
know that someone else got that message. That is, the default behavior is
similar to the <tt>Bcc</tt> field of popular e-mail clients;
<li> It is up to you to add the <tt>To</tt> header with the list of primary
recipients so that other recipients can see it;
<li> It is also up to you to add the <tt>Cc</tt> header with the
list of additional recipients so that everyone else sees it;
<li> Adding a header <tt>Bcc</tt> is nonsense, unless it is
empty. Otherwise, everyone receiving the message will see it and that is
exactly what you <em>don't</em> want to happen!
</ul>
<p class=note>
I hope this clarifies the issue. Otherwise, please refer to
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2821.txt">RFC 2821</a>
and
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2822.txt">RFC 2822</a>.
</p>
<pre class=example>
-- Connects to server "localhost" and sends a message to users
-- "fulano@tecgraf.puc-rio.br", "beltrano@tecgraf.puc-rio.br",
-- and "sicrano@tecgraf.puc-rio.br".
-- Note that "fulano" is the primary recipient, "beltrano" receives a
-- carbon copy and neither of them knows that "sicrano" received a blind
-- carbon copy of the message.
headers = {
to = "fulano@tecgraf.puc-rio.br",
cc = "beltrano@tecgraf.puc-rio.br",
subject = "LuaSocket test message"
}
from = "luasocket@tecgraf.puc-rio.br"
rcpt = {
"fulano@tecgraf.puc-rio.br",
"beltrano@tecgraf.puc-rio.br",
"sicrano@tecgraf.puc-rio.br"
}
body = "This is a test message. Please ignore."
server = "localhost"
r, e = socket.smtp.mail{
from = from,
rcpt = rcpt,
headers = headers,
body = body,
server = server
}
</pre>
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=footer>
<hr>
<center>
<p class=bar>
<a href="home.html">home</a> &middot;
<a href="home.html#down">download</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>
</p>
<p>
<small>
Last modified by Diego Nehab on <br>
Sat Aug 9 01:00:41 PDT 2003
</small>
</p>
</center>
</div>
</body>
</html>

173
doc/stream.html Normal file
View File

@ -0,0 +1,173 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>LuaSocket: Network support for the Lua language</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 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> &middot;
<a href="home.html#download">download</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>
</p>
</center>
<hr>
</div>
<!-- stream ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h2 id=stream>Streaming with Callbacks</h2>
<p>
HTTP and FTP transfers sometimes involve large amounts of information.
Sometimes an application needs to generate outgoing data in real time,
or needs to process incoming information as it is being received. To
address these problems, LuaSocket allows HTTP message bodies and FTP
file contents to be received or sent through the callback mechanism
outlined below.
</p>
<p>
Instead of returning the entire contents of a FTP file or HTTP message
body as strings to the Lua application, the library allows the user to
provide a <em>receive callback</em> that will be called with successive
chunks of data, as the data becomes available. Conversely, the <em>send
callbacks</em> should be used when data needed by LuaSocket
is generated incrementally by the application.
</p>
<!-- tohostname +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=receive_cb>
<b>receive_cb(</b>chunk, err<b>)</b>
</p>
<p class=description>
The callback provided by the user will be repeatedly called by the
library whenever new data is available. Each time it is called, the
callback receives successive chunks of downloaded data.
</p>
<p class=parameters>
<tt>Chunk</tt> contains the current chunk of data.
When the transmission is over, the function is called with an
empty string (i.e.&nbsp;<tt>""</tt>) as the <tt>chunk</tt>. If an error occurs, the
function receives <tt>nil</tt> as <tt>chunk</tt> and an error message as
<tt>err</tt>.
</p>
<p class=return>
The callback can abort transmission by returning
<tt>nil</tt> as its first return value. In that case, it can also return
an error message. Any non-<tt>nil</tt> return value proceeds with the
transmission.
</p>
<pre class=example>
-- The implementation of socket.callback.receive_concat
function Public.receive_concat(concat)
concat = concat or socket.concat.create()
local callback = function(chunk, err)
-- if not finished, add chunk
if chunk and chunk ~= "" then
concat:addstring(chunk)
return 1
end
end
return callback, concat
end
</pre>
<!-- send_cb ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name>
<b>send_cb()</b>
</p>
<p class=description>
The callback provided by the user will be repeatedly called whenever the
library needs more data to be sent.
</p>
<p class=return>
Each time the callback is called, it
should return the next part of the information the library is expecting,
followed by the total number of bytes to be sent.
The callback can abort
the process at any time by returning <tt>nil</tt> followed by an
optional error message.
</p>
<p class=note>
Note: The need for the second return value comes from the fact that, with
the HTTP protocol for instance, the library needs to know in advance the
total number of bytes that will be sent.
</p>
<pre class=example>
-- The implementation of socket.callback.send_file
function Public.send_file(file)
local callback
-- if successfull, return the callback that reads from the file
if file then
-- get total size
local size = file:seek("end")
-- go back to start of file
file:seek("set")
callback = function()
-- send next block of data
local chunk = file:read(Public.BLOCKSIZE)
if not chunk then file:close() end
return chunk, size
end
-- else, return a callback that just aborts the transfer
else
callback = function()
-- just abort
return nil, "unable to open file"
end
end
return callback, file
end
</pre>
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=footer>
<hr>
<center>
<p class=bar>
<a href="home.html">home</a> &middot;
<a href="home.html#down">download</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>
</p>
<p>
<small>
Last modified by Diego Nehab on <br>
Sat Aug 9 01:00:41 PDT 2003
</small>
</p>
</center>
</div>
</body>
</html>

415
doc/tcp.html Normal file
View File

@ -0,0 +1,415 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>LuaSocket: Network support for the Lua language</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 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> &middot;
<a href="home.html#download">download</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>
</p>
</center>
<hr>
</div>
<!-- tcp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h2 id=tcp>TCP</h2>
<!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=socket.tcp>
socket.<b>tcp()</b>
</p>
<p class=description>
Creates and returns a TCP master object. A master object can
be transformed into a server object with the method
<a href=#bind><tt>bind</tt></a> or into a client object with the method
<a href=#connect><tt>connect</tt></a>. The only other method
supported by a master object is the <a href=#close><tt>close</tt></a>
method.</p>
<p class=return>
In case of success, a new master object is returned. In case of error,
<tt>nil</tt> is returned, followed by an error message.
</p>
<!-- accept +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=accept>
server:<b>accept()</b>
</p>
<p class=description>
Waits for a remote connection on the server
object and returns a client object representing that connection.
</p>
<p class=return>
If a connection is successfully initiated, a client object is returned.
If a timeout condition is met, the method returns <tt>nil</tt> followed
by the error string '<tt>timeout</tt>'.
</p>
<p class=note>
Note: calling <a href=misc.html#socket.select><tt>socket.select</tt></a>
with a server object in
the <tt>receive</tt> parameter before a call to <tt>accept</tt> does
<em>not</em> guarantee <tt>accept</tt> will return immediately. Use the <a
href=#settimeout><tt>settimeout</tt></a> method or <tt>accept</tt>
might block until <em>another</em> client shows up.
</p>
<!-- bind +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=bind>
master:<b>bind(</b>address, port [, backlog]<b>)</b>
</p>
<p class=description>
Binds a master object to <tt>address</tt> and <tt>port</tt> on the
local host, transforming it into a server object. Server
objects support the
<a href=#accept><tt>accept</tt></a>,
<a href=#getsockname><tt>getsockname</tt></a>,
<a href=#setoption><tt>setoption</tt></a>,
<a href=#settimeout><tt>settimeout</tt></a>,
and <a href=#close><tt>close</tt></a> methods.
</p>
<p class=parameters>
<tt>Address</tt> can be an IP address or a host name.
<tt>Port</tt> must be an integer number in the range [0..64K].
If <tt>address</tt>
is '<tt>*</tt>', the system binds to all local interfaces
using the <tt>INADDR_ANY</tt> constant. If <tt>port</tt> is 0, the system automatically
chooses an ephemeral port. The optional parameter <tt>backlog</tt>, which
defaults to 1, specifies the number of client connections that can
be queued waiting for service. If the queue is full and another client
attempts connection, the connection is refused.
</p>
<p class=return>
In case of success, the method returns 1. In case of error, the
method returns <tt>nil</tt> followed by an error message.
</p>
<p class=note>
Note: The function <tt>socket.bind</tt> is available and is a short
for <a href=#socket.tcp><tt>socket.tcp</tt></a> followed by the <tt>bind</tt> method.
</p>
<!-- close ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=close>
master:<b>close()</b><br>
client:<b>close()</b><br>
server:<b>close()</b>
</p>
<p class=description>
Closes a TCP 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>
<!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=connect>
master:<b>connect(</b>address, port<b>)</b>
</p>
<p class=description>
Attempts to connect a master object to a remote host, transforming it into a
client object. Client objects support methods
<a href=#send><tt>send</tt></a>,
<a href=#receive><tt>receive</tt></a>,
<a href=#getsockname><tt>getsockname</tt></a>,
<a href=#getpeername><tt>getpeername</tt></a>,
<a href=#settimeout><tt>settimeout</tt></a>,
and <a href=#close><tt>close</tt></a>.
</p>
<p class=parameters>
<tt>Address</tt> can be an IP address or a host name.
<tt>Port</tt> must be an integer number in the range [1..64K].
</p>
<p class=return>
In case of error, the method returns <tt>nil</tt> followed by a string
describing the error. In case of success, the method returns 1.
</p>
<p class=note>
Note: The function <tt>socket.connect</tt> is available and is a short
for <a href=#socket.tcp><tt>socket.tcp</tt></a> followed by the <tt>connect</tt> method.
</p>
<!-- getpeername ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=getpeername>
client:<b>getpeername()</b>
</p>
<p class=description>
Returns information about the remote side of a connected client object.
</p>
<p class=return>
Returns a string with the IP address of the peer, followed by the
port number that peer is using for the connection.
In case of error, the method returns <tt>nil</tt>.
</p>
<p class=note>
Note: It makes no sense to call this method on server objects.
</p>
<!-- getpeername ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=getsockname>
client:<b>getsockname()</b><br>
server:<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 <tt>nil</tt>.
</p>
<p class=note>
Note: Naturally, for a server object, the address and port returned are
those passed to the <a href=#bind>bind</a> method. If the port value
passed to bind was 0, the OS assigned ephemeral port is returned. For
client objects, both the address and port are ephemeral and these are the
values returned.
</p>
<!-- receive ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=receive>
client:<b>receive(</b>[pattern<sub>1</sub>, pattern<sub>2</sub>,
... pattern<sub>N</sub>]<b>)</b>
</p>
<p class=description>
Reads data from a client object, according to the specified <em>read
patterns</em>. Patterns follow the Lua file I/O format, and the difference in performance between all patterns is negligible.
</p>
<p class=parameters>
The parameters <tt>pattern</tt><sub>1</sub>, <tt>pattern</tt><sub>2</sub>, ...
<tt>pattern</tt><sub>N</sub> can be any of the following:
</p>
<ul>
<li> '<tt>*a</tt>': reads from the socket until the connection is
closed. No end-of-line translation is performed;
<li> '<tt>*l</tt>': reads a line of text from the socket. The line is
terminated by a LF character (ASCII&nbsp;10), optionally preceded by a
CR character (ASCII&nbsp;13). The CR and LF characters are not included in
the returned line. This is the default pattern;
<li> <tt>number</tt>: causes the method to read <tt>number</tt> raw
bytes from the socket.
</ul>
<p class=return>
The method returns one value for each pattern, followed by a single
error code that can be <tt>nil</tt> in case of success, the string
'<tt>closed</tt>' in case the connection was closed before the
transmission was completed or the string '<tt>timeout</tt>' in case
there was a timeout during the operation.
</p>
<p class=note>
Note: In case of error, the method always return everything it managed
to download before the error condition was met.
</p>
<!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=send>
client:<b>send(</b>string<sub>1</sub> [,
string<sub>2</sub>, ... string<sub>N</sub>]<b>)</b>
</p>
<p class=description>
Sends data through client object.
</p>
<p class=parameters>
All parameters should be strings. For small strings, it is always better to
concatenate them in Lua (with the '<tt>..</tt>' operator) and pass the
result to LuaSocket instead of passing several independent strings.
</p>
<p class=return>
The method returns the number of bytes accepted by the transport layer,
followed by an error code. The error code is <tt>nil</tt> if the operation
completed with no errors, the string '<tt>closed</tt>' in case
the connection was closed before the transmission was completed or the
string '<tt>timeout</tt>' in case there was a timeout during the
operation.
</p>
<p class=note>
Note: The return values for the <tt>send</tt> method have been changed in
LuaSocket 2.0! In previous versions, the method returned only the
error message. Since returning <tt>nil</tt> in case of success goes
against all other LuaSocket methods and functions, the
<tt>send</tt> method been changed for the sake of uniformity.
</p>
<!-- setoption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=setoption>
client:<b>setoption(</b>option [, value]<b>)</b><br>
server:<b>setoption(</b>option [, value]<b>)</b>
</p>
<p class=description>
Sets options for the TCP object. Options are only needed by low-level or
time-critical applications. You should only modify a 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:
<ul>
<li> '<tt>tcp-nodelay</tt>': Setting this option to <tt>true</tt> disables the
Nagle's algorithm for the connection;
<li> '<tt>linger</tt>': Controls the action taken when unsent data are
queued on socket and a close is performed. The value is a table with a
boolean entry '<tt>on</tt>' and a numeric entry for the time interval
'<tt>timeout</tt>' in seconds.
If the '<tt>on</tt>' field is set to <tt>true</tt>,
the system will block the process on the close attempt until it is able to
transmit the data or until '<tt>timeout</tt>' has passed. If '<tt>on</tt>'
is <tt>false</tt> and a close is issued, the system will process the close
in a manner that allows the process to continue as quickly as possible. I
do not advise you to set this to anything other than zero.
<li> '<tt>keepalive</tt>': Setting this option to <tt>true</tt> enables
the periodic transmission of messages on a connected socket. Should the
connected party fail to respond to these messages, the connection is
considered broken and processes using the socket are notified.
</ul>
<p class=return>
The method returns 1 in case of success, or <tt>nil</tt> otherwise.
</p>
<p class=note>
Note: The descriptions above come from the man pages.
</p>
<!-- settimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=settimeout>
client:<b>settimeout(</b>value [, mode]<b>)</b><br>
server:<b>settimeout(</b>value [, mode]<b>)</b>
</p>
<p class=description>
Changes the timeout values for the object. By default,
all I/O operations are blocking. That is, any call to the methods
<a href=#send><tt>send</tt></a>,
<a href=#receive><tt>receive</tt></a>, and
<a href=#accept><tt>accept</tt></a>
will block indefinitely, until the operation completes. The
<tt>settimeout</tt> method defines a limit on the amount of time the
I/O methods 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. There are two timeout modes and
both can be used together for fine tuning:
</p>
<ul>
<li> '<tt>b</tt>': <em>block</em> timeout. Specifies the upper limit on
the amount of time LuaSocket can be blocked by the operating system
while waiting for completion of any single I/O operation. This is the
default mode;</li>
<li> '<tt>t</tt>': <em>total</em> timeout. Specifies the upper limit on
the amount of time LuaSocket can block a Lua script before returning from
a call.</li>
</ul>
<p class=parameters>
The <tt>nil</tt> timeout <tt>value</tt> allows operations to block
indefinitely. Negative timeout values have the same effect.
</p>
<p class=note>
Note: although timeout values have millisecond precision in LuaSocket,
large blocks can cause I/O functions not to respect timeout values due
to the time the library takes to transfer blocks to and from the OS
and to and from the Lua interpreter.
</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> &middot;
<a href="home.html#down">download</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>
</p>
<p>
<small>
Last modified by Diego Nehab on <br>
Sat Aug 9 01:00:41 PDT 2003
</small>
</p>
</center>
</div>
</body>
</html>

400
doc/udp.html Normal file
View File

@ -0,0 +1,400 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>LuaSocket: Network support for the Lua language</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 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> &middot;
<a href="home.html#download">download</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>
</p>
</center>
<hr>
</div>
<!-- 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, <tt>nil</tt> 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 <tt>nil</tt>.
</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.
</p>
<p class="return">
In case of success, the method return the
received datagram. In case of timeout, the method returns
<tt>nil</tt> 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.
Beware that the maximum datagram size for UDP is 576 bytes.
</p>
<p class="return">
If successful, the method returns 1. In case of
error, the method returns <tt>nil</tt> followed by the
'<tt>refused</tt>' 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. Beware that the maximum datagram size for UDP is
576 bytes. <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 <tt>nil</tt> followed by the
'<tt>refused</tt>' 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
<tt>nil</tt> 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 <tt>nil</tt> 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 a 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
<tt>nil</tt> 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 <tt>nil</tt> 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> &middot;
<a href="home.html#download">download</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>
</p>
<p>
<small>
Last modified by Diego Nehab on <br>
Sat Aug 9 01:00:41 PDT 2003
</small>
</p>
</center>
</div>
</body>
</html>

265
doc/url.html Normal file
View File

@ -0,0 +1,265 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>LuaSocket: Network support for the Lua language</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 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> &middot;
<a href="home.html#download">download</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>
</p>
</center>
<hr>
</div>
<!-- url ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h2 id=url>URL</h2>
<p>
The module <tt>url.lua</tt> provides functions to parse, protect,
and build URLs, as well as functions to compose absolute URLs
from base and relative URLs, according to
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2396.txt">RFC
2396</a>.
</p>
<p>
An URL is defined by the following grammar:
</p>
<blockquote>
<tt>
&lt;url&gt; ::= [&lt;scheme&gt;:][//&lt;authority&gt;][/&lt;path&gt;][;&lt;params&gt;][?&lt;query&gt;][#&lt;fragment&gt;]<br>
&lt;authority&gt; ::= [&lt;userinfo&gt;@]&lt;host&gt;[:&lt;port&gt;]<br>
&lt;userinfo&gt; ::= &lt;user&gt;[:&lt;password&gt;]<br>
&lt;path&gt; ::= {&lt;segment&gt;/}&lt;segment&gt;<br>
</tt>
</blockquote>
<!-- absolute +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=absolute>
socket.url.<b>absolute(</b>base, relative<b>)</b>
</p>
<p class=description>
Builds an absolute URL from a base URL and a relative URL.
</p>
<p class=parameters>
<tt>Base</tt> is a string with the base URL and <tt>relative</tt> is a
string with the relative URL.
</p>
<p class=return>
The function returns a string with the absolute URL.
</p>
<p class=note>
Note: The rules that
govern the composition are fairly complex, and are described in detail in
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2396.txt">RFC 2396</a>.
The example bellow should give an idea of what are the rules.
</p>
<pre class=example>
http://a/b/c/d;p?q
+
g:h = g:h
g = http://a/b/c/g
./g = http://a/b/c/g
g/ = http://a/b/c/g/
/g = http://a/g
//g = http://g
?y = http://a/b/c/?y
g?y = http://a/b/c/g?y
#s = http://a/b/c/d;p?q#s
g#s = http://a/b/c/g#s
g?y#s = http://a/b/c/g?y#s
;x = http://a/b/c/;x
g;x = http://a/b/c/g;x
g;x?y#s = http://a/b/c/g;x?y#s
. = http://a/b/c/
./ = http://a/b/c/
.. = http://a/b/
../ = http://a/b/
../g = http://a/b/g
../.. = http://a/
../../ = http://a/
../../g = http://a/g
</pre>
<!-- build ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=build>
socket.url.<b>build(</b>parsed_url<b>)</b>
</p>
<p class=description>
Rebuilds an URL from its parts.
</p>
<p class=parameters>
<tt>Parsed_url</tt> is a table with same components returned by
<a href="#parse"><tt>parse</tt></a>.
Lower level components, if specified,
take precedence over hight level components of the URL grammar.
</p>
<p class=return>
The function returns a string with the built URL.
</p>
<!-- build_path +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=build_path>
socket.url.<b>build_path(</b>segments, unsafe<b>)</b>
</p>
<p class=description>
Builds a <tt>&lt;path&gt;</tt> component from a list of
<tt>&lt;segment&gt;</tt> parts.
Before composition, any reserved characters found in a segment are escaped into
their protected form, so that the resulting path is a valid URL path
component.
</p>
<p class=parameters>
<tt>Segments</tt> is a list of strings with the <tt>&lt;segment&gt;</tt>
parts. If <tt>unsafe</tt> is anything but <tt>nil</tt>, reserved
characters are left untouched.
</p>
<p class=return>
The function returns a string with the
built <tt>&lt;path&gt;</tt> component.
</p>
<!-- parse ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=parse>
socket.url.<b>parse(</b>url, default<b>)</b>
</p>
<p class=description>
Parses an URL given as a string into a Lua table with its components.
</p>
<p class=parameters>
<tt>Url</tt> is the URL to be parsed. If the <tt>default</tt> table is
present, it is used to store the parsed fields. Only fields present in the
URL are overwritten. Therefore, this table can be used to pass default
values for each field.
</p>
<p class=return>
The function returns a table with all the URL components:
</p>
<blockquote><tt>
parsed_url = {<br>
&nbsp;&nbsp;url = <i>string</i>,<br>
&nbsp;&nbsp;scheme = <i>string</i>,<br>
&nbsp;&nbsp;authority = <i>string</i>,<br>
&nbsp;&nbsp;path = <i>string</i>,<br>
&nbsp;&nbsp;params = <i>string</i>,<br>
&nbsp;&nbsp;query = <i>string</i>,<br>
&nbsp;&nbsp;fragment = <i>string</i>,<br>
&nbsp;&nbsp;userinfo = <i>string</i>,<br>
&nbsp;&nbsp;host = <i>string</i>,<br>
&nbsp;&nbsp;port = <i>string</i>,<br>
&nbsp;&nbsp;user = <i>string</i>,<br>
&nbsp;&nbsp;password = <i>string</i><br>
}
</tt></blockquote>
<pre class=example>
parsed_url = socket.url.parse("http://www.puc-rio.br/~diego/index.lua?a=2#there")
-- parsed_url = {
-- scheme = "http",
-- authority = "www.puc-rio.br",
-- path = "/~diego/index.lua"
-- query = "a=2",
-- fragment = "there",
-- host = "www.puc-rio.br",
-- }
parsed_url = socket.url.parse("ftp://root:passwd@unsafe.org/pub/virus.exe;type=i")
-- parsed_url = {
-- scheme = "ftp",
-- authority = "root:passwd@unsafe.org",
-- path = "/pub/virus.exe",
-- params = "type=i",
-- userinfo = "root:passwd",
-- host = "unsafe.org",
-- user = "root",
-- password = "passwd",
-- }
</pre>
<!-- parse_path +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=parse_path>
socket.url.<b>parse_path(</b>path<b>)</b>
</p>
<p class=description>
Breaks a <tt>&lt;path&gt;</tt> URL component into all its
<tt>&lt;segment&gt;</tt> parts.
</p>
<p class=description>
<tt>Path</tt> is a string with the path to be parsed.
</p>
<p class=return>
Since some characters are reserved in URLs, they must be escaped
whenever present in a <tt>&lt;path&gt;</tt> component. Therefore, before
returning a list with all the parsed segments, the function unescapes all
of them.
</p>
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=footer>
<hr>
<center>
<p class=bar>
<a href="home.html">home</a> &middot;
<a href="home.html#down">download</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>
</p>
<p>
<small>
Last modified by Diego Nehab on <br>
Sat Aug 9 01:00:41 PDT 2003
</small>
</p>
</center>
</div>
</body>
</html>