mirror of
https://github.com/lunarmodules/luasocket.git
synced 2024-12-25 12:08:21 +01:00
Merge remote-tracking branch 'upstream/master' into test-builds
This commit is contained in:
commit
2de8ddfbb8
14
.github/workflows/luacheck.yml
vendored
14
.github/workflows/luacheck.yml
vendored
@ -7,13 +7,7 @@ jobs:
|
||||
luacheck:
|
||||
runs-on: ubuntu-20.04
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v3
|
||||
- name: Setup ‘lua’
|
||||
uses: leafo/gh-actions-lua@v9
|
||||
- name: Setup ‘luarocks’
|
||||
uses: leafo/gh-actions-luarocks@v4
|
||||
- name: Setup ‘luacheck’
|
||||
run: luarocks install luacheck
|
||||
- name: Run ‘luacheck’ linter
|
||||
run: luacheck .
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v3
|
||||
- name: Luacheck
|
||||
uses: lunarmodules/luacheck@v0
|
||||
|
3
LICENSE
3
LICENSE
@ -1,5 +1,4 @@
|
||||
LuaSocket 3.0 license
|
||||
Copyright © 2004-2013 Diego Nehab
|
||||
Copyright (C) 2004-2022 Diego Nehab
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a
|
||||
copy of this software and associated documentation files (the "Software"),
|
||||
|
8
README
8
README
@ -1,11 +1,11 @@
|
||||
This is the LuaSocket 3.0-rc1. It has been tested on Windows 7, Mac OS X,
|
||||
and Linux.
|
||||
and Linux.
|
||||
|
||||
Please use the project page at GitHub
|
||||
Please use the project page at GitHub
|
||||
|
||||
https://github.com/diegonehab/luasocket
|
||||
https://github.com/lunarmodules/luasocket
|
||||
|
||||
to file bug reports or propose changes.
|
||||
to file bug reports or propose changes.
|
||||
|
||||
Have fun,
|
||||
Diego Nehab.
|
||||
|
@ -1,4 +1,4 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
||||
"http://www.w3.org/TR/html4/strict.dtd">
|
||||
<html>
|
||||
|
||||
@ -13,22 +13,22 @@
|
||||
|
||||
<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<div class=header>
|
||||
<div class="header">
|
||||
<hr>
|
||||
<center>
|
||||
<table summary="LuaSocket logo">
|
||||
<tr><td align=center><a href="http://www.lua.org">
|
||||
<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png">
|
||||
<tr><td align="center"><a href="http://www.lua.org">
|
||||
<img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
|
||||
</a></td></tr>
|
||||
<tr><td align=center valign=top>Network support for the Lua language
|
||||
<tr><td align="center" valign="top">Network support for the Lua language
|
||||
</td></tr>
|
||||
</table>
|
||||
<p class=bar>
|
||||
<p class="bar">
|
||||
<a href="index.html">home</a> ·
|
||||
<a href="index.html#download">download</a> ·
|
||||
<a href="installation.html">installation</a> ·
|
||||
<a href="introduction.html">introduction</a> ·
|
||||
<a href="reference.html">reference</a>
|
||||
<a href="reference.html">reference</a>
|
||||
</p>
|
||||
</center>
|
||||
<hr>
|
||||
@ -36,14 +36,14 @@
|
||||
|
||||
<!-- dns ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<h2 id=dns>DNS</h2>
|
||||
<h2 id="dns">DNS</h2>
|
||||
|
||||
<p>
|
||||
IPv4 name resolution functions
|
||||
<a href=#toip><tt>dns.toip</tt></a>
|
||||
IPv4 name resolution functions
|
||||
<a href="#toip"><tt>dns.toip</tt></a>
|
||||
and
|
||||
<a href=#tohostname><tt>dns.tohostname</tt></a>
|
||||
return <em>all</em> information obtained from
|
||||
<a href="#tohostname"><tt>dns.tohostname</tt></a>
|
||||
return <em>all</em> information obtained from
|
||||
the resolver in a table of the form:
|
||||
</p>
|
||||
|
||||
@ -60,10 +60,10 @@ Note that the <tt>alias</tt> list can be empty.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The more general name resolution function
|
||||
<a href=#getaddrinfo><tt>dns.getaddrinfo</tt></a>, which
|
||||
The more general name resolution function
|
||||
<a href="#getaddrinfo"><tt>dns.getaddrinfo</tt></a>, which
|
||||
supports both IPv6 and IPv4,
|
||||
returns <em>all</em> information obtained from
|
||||
returns <em>all</em> information obtained from
|
||||
the resolver in a table of the form:
|
||||
</p>
|
||||
|
||||
@ -88,82 +88,82 @@ addresses, and <tt>"inet6"</tt> for IPv6 addresses.
|
||||
|
||||
<!-- getaddrinfo ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id=getaddrinfo>
|
||||
<p class="name" id="getaddrinfo">
|
||||
socket.dns.<b>getaddrinfo(</b>address<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
Converts from host name to address.
|
||||
<p class="description">
|
||||
Converts from host name to address.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<tt>Address</tt> can be an IPv4 or IPv6 address or host name.
|
||||
<p class="parameters">
|
||||
<tt>Address</tt> can be an IPv4 or IPv6 address or host name.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
<p class="return">
|
||||
The function returns a table with all information returned by
|
||||
the resolver. In case of error, the function returns <b><tt>nil</tt></b>
|
||||
followed by an error message.
|
||||
followed by an error message.
|
||||
</p>
|
||||
|
||||
<!-- gethostname ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id=gethostname>
|
||||
<p class="name" id="gethostname">
|
||||
socket.dns.<b>gethostname()</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
Returns the standard host name for the machine as a string.
|
||||
<p class="description">
|
||||
Returns the standard host name for the machine as a string.
|
||||
</p>
|
||||
|
||||
<!-- tohostname +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id=tohostname>
|
||||
<p class="name" id="tohostname">
|
||||
socket.dns.<b>tohostname(</b>address<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Converts from IPv4 address to host name.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<tt>Address</tt> can be an IP address or host name.
|
||||
<p class="parameters">
|
||||
<tt>Address</tt> can be an IP address or host name.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
<p class="return">
|
||||
The function returns 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 <b><tt>nil</tt></b>
|
||||
followed by an error message.
|
||||
followed by an error message.
|
||||
</p>
|
||||
|
||||
<!-- toip +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id=toip>
|
||||
<p class="name" id="toip">
|
||||
socket.dns.<b>toip(</b>address<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Converts from host name to IPv4 address.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<tt>Address</tt> can be an IP address or host name.
|
||||
<p class="parameters">
|
||||
<tt>Address</tt> can be an IP address or host name.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
<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 <b><tt>nil</tt></b> followed by an error
|
||||
message.
|
||||
message.
|
||||
</p>
|
||||
|
||||
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<div class=footer>
|
||||
<div class="footer">
|
||||
<hr>
|
||||
<center>
|
||||
<p class=bar>
|
||||
<p class="bar">
|
||||
<a href="index.html">home</a> ·
|
||||
<a href="index.html#down">download</a> ·
|
||||
<a href="installation.html">installation</a> ·
|
@ -1,5 +1,5 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
||||
"http://www.w3.org/TR/html4/strict.dtd">
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
||||
"http://www.w3.org/TR/html4/strict.dtd">
|
||||
<html>
|
||||
|
||||
<head>
|
||||
@ -13,22 +13,22 @@
|
||||
|
||||
<!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<div class=header>
|
||||
<div class="header">
|
||||
<hr>
|
||||
<center>
|
||||
<table summary="LuaSocket logo">
|
||||
<tr><td align=center><a href="http://www.lua.org">
|
||||
<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png">
|
||||
<tr><td align="center"><a href="http://www.lua.org">
|
||||
<img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
|
||||
</a></td></tr>
|
||||
<tr><td align=center valign=top>Network support for the Lua language
|
||||
<tr><td align="center" valign="top">Network support for the Lua language
|
||||
</td></tr>
|
||||
</table>
|
||||
<p class=bar>
|
||||
<p class="bar">
|
||||
<a href="index.html">home</a> ·
|
||||
<a href="index.html#download">download</a> ·
|
||||
<a href="installation.html">installation</a> ·
|
||||
<a href="introduction.html">introduction</a> ·
|
||||
<a href="reference.html">reference</a>
|
||||
<a href="reference.html">reference</a>
|
||||
</p>
|
||||
</center>
|
||||
<hr>
|
||||
@ -36,7 +36,7 @@
|
||||
|
||||
<!-- ftp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<h2 id=ftp>FTP</h2>
|
||||
<h2 id="ftp">FTP</h2>
|
||||
|
||||
<p>
|
||||
FTP (File Transfer Protocol) is a protocol used to transfer files
|
||||
@ -50,28 +50,28 @@ High level functions are provided supporting the most common operations.
|
||||
These high level functions are implemented on top of a lower level
|
||||
interface. Using the low-level interface, users can easily create their
|
||||
own functions to access <em>any</em> operation supported by the FTP
|
||||
protocol. For that, check the implementation.
|
||||
protocol. For that, check the implementation.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
To really benefit from this module, a good understanding of
|
||||
To really benefit from this module, a good understanding of
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">
|
||||
LTN012, Filters sources and sinks</a> is necessary.
|
||||
LTN012, Filters sources and sinks</a> is necessary.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<p>
|
||||
To obtain the <tt>ftp</tt> namespace, run:
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
<pre class="example">
|
||||
-- loads the FTP module and any libraries it requires
|
||||
local ftp = require("socket.ftp")
|
||||
</pre>
|
||||
|
||||
<p>
|
||||
URLs MUST conform to
|
||||
<a href="http://www.ietf.org/rfc/rfc1738.txt">RFC 1738</a>,
|
||||
that is, an URL is a string in the form:
|
||||
<a href="http://www.ietf.org/rfc/rfc1738.txt">RFC 1738</a>,
|
||||
that is, an URL is a string in the form:
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
@ -81,19 +81,19 @@ that is, an URL is a string in the form:
|
||||
|
||||
<p>
|
||||
The following constants in the namespace can be set to control the default behavior of
|
||||
the FTP module:
|
||||
the FTP module:
|
||||
</p>
|
||||
|
||||
<ul>
|
||||
<li> <tt>PASSWORD</tt>: default anonymous password.
|
||||
<li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations;
|
||||
<li> <tt>USER</tt>: default anonymous user;
|
||||
<li> <tt>PASSWORD</tt>: default anonymous password.</li>
|
||||
<li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations;</li>
|
||||
<li> <tt>USER</tt>: default anonymous user;</li>
|
||||
</ul>
|
||||
|
||||
|
||||
<!-- ftp.get ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id=get>
|
||||
<p class="name" id="get">
|
||||
ftp.<b>get(</b>url<b>)</b><br>
|
||||
ftp.<b>get{</b><br>
|
||||
host = <i>string</i>,<br>
|
||||
@ -109,19 +109,19 @@ ftp.<b>get{</b><br>
|
||||
<b>}</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
The <tt>get</tt> function has two forms. The simple form has fixed
|
||||
functionality: it downloads the contents of a URL and returns it as a
|
||||
string. The generic form allows a <em>lot</em> more control, as explained
|
||||
below.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<p class="parameters">
|
||||
If the argument of the <tt>get</tt> function is a table, the function
|
||||
expects at least the fields <tt>host</tt>, <tt>sink</tt>, and one of
|
||||
expects at least the fields <tt>host</tt>, <tt>sink</tt>, and one of
|
||||
<tt>argument</tt> or <tt>path</tt> (<tt>argument</tt> takes
|
||||
precedence). <tt>Host</tt> is the server to connect to. <tt>Sink</tt> is
|
||||
the <em>simple</em>
|
||||
the <em>simple</em>
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
||||
sink that will receive the downloaded data. <tt>Argument</tt> or
|
||||
<tt>path</tt> give the target path to the resource in the server. The
|
||||
@ -129,28 +129,28 @@ optional arguments are the following:
|
||||
</p>
|
||||
<ul>
|
||||
<li><tt>user</tt>, <tt>password</tt>: User name and password used for
|
||||
authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>";
|
||||
authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>";</li>
|
||||
<li><tt>command</tt>: The FTP command used to obtain data. Defaults to
|
||||
"<tt>retr</tt>", but see example below;
|
||||
<li><tt>port</tt>: The port to used for the control connection. Defaults to 21;
|
||||
"<tt>retr</tt>", but see example below;</li>
|
||||
<li><tt>port</tt>: The port to used for the control connection. Defaults to 21;</li>
|
||||
<li><tt>type</tt>: The transfer mode. Can take values "<tt>i</tt>" or
|
||||
"<tt>a</tt>". Defaults to whatever is the server default;
|
||||
<li><tt>step</tt>:
|
||||
"<tt>a</tt>". Defaults to whatever is the server default;</li>
|
||||
<li><tt>step</tt>:
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
||||
pump step function used to pass data from the
|
||||
server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function;
|
||||
server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function;</li>
|
||||
<li><tt>create</tt>: An optional function to be used instead of
|
||||
<a href=tcp.html#socket.tcp><tt>socket.tcp</tt></a> when the communications socket is created.
|
||||
<a href="tcp.html#socket.tcp"><tt>socket.tcp</tt></a> when the communications socket is created.</li>
|
||||
</ul>
|
||||
|
||||
<p class=return>
|
||||
<p class="return">
|
||||
If successful, the simple version returns the URL contents as a
|
||||
string, and the generic function returns 1. In case of error, both
|
||||
functions return <b><tt>nil</tt></b> and an error message describing the
|
||||
error.
|
||||
error.
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
<pre class="example">
|
||||
-- load the ftp support
|
||||
local ftp = require("socket.ftp")
|
||||
|
||||
@ -159,7 +159,7 @@ local ftp = require("socket.ftp")
|
||||
f, e = ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua/lua.tar.gz;type=i")
|
||||
</pre>
|
||||
|
||||
<pre class=example>
|
||||
<pre class="example">
|
||||
-- load needed modules
|
||||
local ftp = require("socket.ftp")
|
||||
local ltn12 = require("ltn12")
|
||||
@ -178,7 +178,7 @@ end
|
||||
|
||||
<!-- put ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id=put>
|
||||
<p class="name" id="put">
|
||||
ftp.<b>put(</b>url, content<b>)</b><br>
|
||||
ftp.<b>put{</b><br>
|
||||
host = <i>string</i>,<br>
|
||||
@ -194,57 +194,57 @@ ftp.<b>put{</b><br>
|
||||
<b>}</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
The <tt>put</tt> function has two forms. The simple form has fixed
|
||||
functionality: it uploads a string of content into a URL. The generic form
|
||||
allows a <em>lot</em> more control, as explained below.
|
||||
allows a <em>lot</em> more control, as explained below.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<p class="parameters">
|
||||
If the argument of the <tt>put</tt> function is a table, the function
|
||||
expects at least the fields <tt>host</tt>, <tt>source</tt>, and one of
|
||||
expects at least the fields <tt>host</tt>, <tt>source</tt>, and one of
|
||||
<tt>argument</tt> or <tt>path</tt> (<tt>argument</tt> takes
|
||||
precedence). <tt>Host</tt> is the server to connect to. <tt>Source</tt> is
|
||||
the <em>simple</em>
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
||||
source that will provide the contents to be uploaded.
|
||||
the <em>simple</em>
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
||||
source that will provide the contents to be uploaded.
|
||||
<tt>Argument</tt> or
|
||||
<tt>path</tt> give the target path to the resource in the server. The
|
||||
optional arguments are the following:
|
||||
</p>
|
||||
<ul>
|
||||
<li><tt>user</tt>, <tt>password</tt>: User name and password used for
|
||||
authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>";
|
||||
authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>";</li>
|
||||
<li><tt>command</tt>: The FTP command used to send data. Defaults to
|
||||
"<tt>stor</tt>", but see example below;
|
||||
<li><tt>port</tt>: The port to used for the control connection. Defaults to 21;
|
||||
"<tt>stor</tt>", but see example below;</li>
|
||||
<li><tt>port</tt>: The port to used for the control connection. Defaults to 21;</li>
|
||||
<li><tt>type</tt>: The transfer mode. Can take values "<tt>i</tt>" or
|
||||
"<tt>a</tt>". Defaults to whatever is the server default;
|
||||
<li><tt>step</tt>:
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
||||
"<tt>a</tt>". Defaults to whatever is the server default;</li>
|
||||
<li><tt>step</tt>:
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
||||
pump step function used to pass data from the
|
||||
server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function;
|
||||
server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function;</li>
|
||||
<li><tt>create</tt>: An optional function to be used instead of
|
||||
<a href=tcp.html#socket.tcp><tt>socket.tcp</tt></a> when the communications socket is created.
|
||||
<a href="tcp.html#socket.tcp"><tt>socket.tcp</tt></a> when the communications socket is created.</li>
|
||||
</ul>
|
||||
|
||||
<p class=return>
|
||||
<p class="return">
|
||||
Both functions return 1 if successful, or <b><tt>nil</tt></b> and an error
|
||||
message describing the reason for failure.
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
<pre class="example">
|
||||
-- load the ftp support
|
||||
local ftp = require("socket.ftp")
|
||||
|
||||
-- Log as user "fulano" on server "ftp.example.com",
|
||||
-- using password "silva", and store a file "README" with contents
|
||||
-- using password "silva", and store a file "README" with contents
|
||||
-- "wrong password, of course"
|
||||
f, e = ftp.put("ftp://fulano:silva@ftp.example.com/README",
|
||||
f, e = ftp.put("ftp://fulano:silva@ftp.example.com/README",
|
||||
"wrong password, of course")
|
||||
</pre>
|
||||
|
||||
<pre class=example>
|
||||
<pre class="example">
|
||||
-- load the ftp support
|
||||
local ftp = require("socket.ftp")
|
||||
local ltn12 = require("ltn12")
|
||||
@ -253,7 +253,7 @@ local ltn12 = require("ltn12")
|
||||
-- using password "silva", and append to the remote file "LOG", sending the
|
||||
-- contents of the local file "LOCAL-LOG"
|
||||
f, e = ftp.put{
|
||||
host = "ftp.example.com",
|
||||
host = "ftp.example.com",
|
||||
user = "fulano",
|
||||
password = "silva",
|
||||
command = "appe",
|
||||
@ -265,15 +265,15 @@ f, e = ftp.put{
|
||||
|
||||
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<div class=footer>
|
||||
<div class="footer">
|
||||
<hr>
|
||||
<center>
|
||||
<p class=bar>
|
||||
<p class="bar">
|
||||
<a href="index.html">home</a> ·
|
||||
<a href="index.html#download">download</a> ·
|
||||
<a href="installation.html">installation</a> ·
|
||||
<a href="introduction.html">introduction</a> ·
|
||||
<a href="reference.html">reference</a>
|
||||
<a href="reference.html">reference</a>
|
||||
</p>
|
||||
<p>
|
||||
<small>
|
@ -1,10 +1,10 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
||||
"http://www.w3.org/TR/html4/strict.dtd">
|
||||
<html>
|
||||
|
||||
<head>
|
||||
<meta name="description" content="LuaSocket: HTTP support">
|
||||
<meta name="keywords" content="Lua, HTTP, Library, WWW, Browser, Network, Support">
|
||||
<meta name="keywords" content="Lua, HTTP, Library, WWW, Browser, Network, Support">
|
||||
<title>LuaSocket: HTTP support</title>
|
||||
<link rel="stylesheet" href="reference.css" type="text/css">
|
||||
</head>
|
||||
@ -13,22 +13,22 @@
|
||||
|
||||
<!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<div class=header>
|
||||
<div class="header">
|
||||
<hr>
|
||||
<center>
|
||||
<table summary="LuaSocket logo">
|
||||
<tr><td align=center><a href="http://www.lua.org">
|
||||
<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png">
|
||||
<tr><td align="center"><a href="http://www.lua.org">
|
||||
<img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
|
||||
</a></td></tr>
|
||||
<tr><td align=center valign=top>Network support for the Lua language
|
||||
<tr><td align="center" valign="top">Network support for the Lua language
|
||||
</td></tr>
|
||||
</table>
|
||||
<p class=bar>
|
||||
<p class="bar">
|
||||
<a href="index.html">home</a> ·
|
||||
<a href="index.html#download">download</a> ·
|
||||
<a href="introduction.html">introduction</a> ·
|
||||
<a href="introduction.html">introduction</a> ·
|
||||
<a href="reference.html">reference</a>
|
||||
<a href="reference.html">reference</a>
|
||||
</p>
|
||||
</center>
|
||||
<hr>
|
||||
@ -36,12 +36,12 @@
|
||||
|
||||
<!-- http +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<h2 id="http">HTTP</h2>
|
||||
<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</tt>
|
||||
namespace offers full support for the client side of the HTTP
|
||||
namespace offers full 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,
|
||||
@ -50,16 +50,16 @@ implementation conforms to the HTTP/1.1 standard,
|
||||
|
||||
<p>
|
||||
The module exports functions that provide HTTP functionality in different
|
||||
levels of abstraction. From the simple
|
||||
levels of abstraction. From the simple
|
||||
string oriented requests, through generic
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> based, down to even lower-level if you bother to look through the source code.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<p>
|
||||
To obtain the <tt>http</tt> namespace, run:
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
<pre class="example">
|
||||
-- loads the HTTP module and any libraries it requires
|
||||
local http = require("socket.http")
|
||||
</pre>
|
||||
@ -67,12 +67,12 @@ local http = require("socket.http")
|
||||
<p>
|
||||
URLs must conform to
|
||||
<a href="http://www.ietf.org/rfc/rfc1738.txt">RFC 1738</a>,
|
||||
that is, an URL is a string in the form:
|
||||
that is, an URL is a string in the form:
|
||||
</p>
|
||||
|
||||
<blockquote>
|
||||
<pre>
|
||||
[http://][<user>[:<password>]@]<host>[:<port>][/<path>]
|
||||
[http://][<user>[:<password>]@]<host>[:<port>][/<path>]
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
@ -97,34 +97,34 @@ headers = {<br>
|
||||
<p>
|
||||
Field names are case insensitive (as specified by the standard) and all
|
||||
functions work with lowercase field names (but see
|
||||
<a href=socket.html#headers.canonic><tt>socket.headers.canonic</tt></a>).
|
||||
<a href="socket.html#headers.canonic"><tt>socket.headers.canonic</tt></a>).
|
||||
Field values are left unmodified.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
Note: MIME headers are independent of order. Therefore, there is no problem
|
||||
in representing them in a Lua table.
|
||||
in representing them in a Lua table.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The following constants can be set to control the default behavior of
|
||||
the HTTP module:
|
||||
the HTTP module:
|
||||
</p>
|
||||
|
||||
<ul>
|
||||
<li> <tt>PROXY</tt>: default proxy used for connections;
|
||||
<li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations;
|
||||
<li> <tt>USERAGENT</tt>: default user agent reported to server.
|
||||
<li> <tt>PROXY</tt>: default proxy used for connections;</li>
|
||||
<li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations;</li>
|
||||
<li> <tt>USERAGENT</tt>: default user agent reported to server.</li>
|
||||
</ul>
|
||||
|
||||
<p class=note id="post">
|
||||
<p class="note">
|
||||
Note: These constants are global. Changing them will also
|
||||
change the behavior other code that might be using LuaSocket.
|
||||
</p>
|
||||
|
||||
<!-- http.request ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="request">
|
||||
<p class="name" id="request">
|
||||
http.<b>request(</b>url [, body]<b>)</b><br>
|
||||
http.<b>request{</b><br>
|
||||
url = <i>string</i>,<br>
|
||||
@ -140,26 +140,26 @@ http.<b>request{</b><br>
|
||||
<b>}</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
The request function has two forms. The simple form downloads
|
||||
a URL using the <tt>GET</tt> or <tt>POST</tt> method and is based
|
||||
on strings. The generic form performs any HTTP method and is
|
||||
<a href=http://lua-users.org/wiki/FiltersSourcesAndSinks>LTN12</a> based.
|
||||
<p class="description">
|
||||
The request function has two forms. The simple form downloads
|
||||
a URL using the <tt>GET</tt> or <tt>POST</tt> method and is based
|
||||
on strings. The generic form performs any HTTP method and is
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> based.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<p class="parameters">
|
||||
If the first argument of the <tt>request</tt> function is a string, it
|
||||
should be an <tt>url</tt>. In that case, if a <tt>body</tt>
|
||||
is provided as a string, the function will perform a <tt>POST</tt> method
|
||||
in the <tt>url</tt>. Otherwise, it performs a <tt>GET</tt> in the
|
||||
<tt>url</tt>
|
||||
<tt>url</tt>
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
If the first argument is instead a table, the most important fields are
|
||||
<p class="parameters">
|
||||
If the first argument is instead a table, the most important fields are
|
||||
the <tt>url</tt> and the <em>simple</em>
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
||||
<tt>sink</tt> that will receive the downloaded content.
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
||||
<tt>sink</tt> that will receive the downloaded content.
|
||||
Any part of the <tt>url</tt> can be overridden by including
|
||||
the appropriate field in the request table.
|
||||
If authentication information is provided, the function
|
||||
@ -169,49 +169,51 @@ function discards the downloaded data. The optional parameters are the
|
||||
following:
|
||||
</p>
|
||||
<ul>
|
||||
<li><tt>method</tt>: The HTTP request method. Defaults to "GET";
|
||||
<li><tt>headers</tt>: Any additional HTTP headers to send with the request;
|
||||
<li><tt>source</tt>: <em>simple</em>
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
||||
<li><tt>method</tt>: The HTTP request method. Defaults to "GET";</li>
|
||||
<li><tt>headers</tt>: Any additional HTTP headers to send with the request;</li>
|
||||
<li><tt>source</tt>: <em>simple</em>
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
||||
source to provide the request body. If there
|
||||
is a body, you need to provide an appropriate "<tt>content-length</tt>"
|
||||
request header field, or the function will attempt to send the body as
|
||||
"<tt>chunked</tt>" (something few servers support). Defaults to the empty source;
|
||||
<li><tt>step</tt>:
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
||||
pump step function used to move data.
|
||||
Defaults to the LTN12 <tt>pump.step</tt> function.
|
||||
<li><tt>proxy</tt>: The URL of a proxy server to use. Defaults to no proxy;
|
||||
<li><tt>redirect</tt>: Set to <tt><b>false</b></tt> to prevent the
|
||||
function from automatically following 301 or 302 server redirect messages;
|
||||
"<tt>chunked</tt>" (something few servers support). Defaults to the empty source;</li>
|
||||
<li><tt>step</tt>:
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
||||
pump step function used to move data.
|
||||
Defaults to the LTN12 <tt>pump.step</tt> function.</li>
|
||||
<li><tt>proxy</tt>: The URL of a proxy server to use. Defaults to no proxy;</li>
|
||||
<li><tt>redirect</tt>: Set to <tt><b>false</b></tt> to prevent the
|
||||
function from automatically following 301 or 302 server redirect messages;</li>
|
||||
<li><tt>create</tt>: An optional function to be used instead of
|
||||
<a href=tcp.html#socket.tcp><tt>socket.tcp</tt></a> when the communications socket is created.
|
||||
<li><tt>maxredirects</tt>: An optional number specifying the maximum number of redirects to follow. Defaults to <tt>5</tt> if not specified. A boolean <tt>false</tt> value means no maximum (unlimited).
|
||||
<a href="tcp.html#socket.tcp"><tt>socket.tcp</tt></a> when the communications socket is created.</li>
|
||||
<li><tt>maxredirects</tt>: An optional number specifying the maximum number of
|
||||
redirects to follow. Defaults to <tt>5</tt> if not specified. A boolean
|
||||
<tt>false</tt> value means no maximum (unlimited).</li>
|
||||
</ul>
|
||||
|
||||
<p class=return>
|
||||
<p class="return">
|
||||
In case of failure, the function returns <tt><b>nil</b></tt> followed by an
|
||||
error message. If successful, the simple form returns the response
|
||||
error message. If successful, the simple form returns the response
|
||||
body as a string, followed by the response status code, the response
|
||||
headers and the response status line. The generic function returns the same
|
||||
information, except the first return value is just the number 1 (the body
|
||||
goes to the <tt>sink</tt>).
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
Even when the server fails to provide the contents of the requested URL (URL not found, for example),
|
||||
<p class="return">
|
||||
Even when the server fails to provide the contents of the requested URL (URL not found, for example),
|
||||
it usually returns 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.ietf.org/rfc/rfc2616.txt">RFC 2616</a>.
|
||||
href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</a>.
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Here are a few examples with the simple interface:
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
<pre class="example">
|
||||
-- load the http module
|
||||
local io = require("io")
|
||||
local http = require("socket.http")
|
||||
@ -219,15 +221,15 @@ local ltn12 = require("ltn12")
|
||||
|
||||
-- connect to server "www.cs.princeton.edu" and retrieves this manual
|
||||
-- file from "~diego/professional/luasocket/http.html" and print it to stdout
|
||||
http.request{
|
||||
url = "http://www.cs.princeton.edu/~diego/professional/luasocket/http.html",
|
||||
http.request{
|
||||
url = "http://www.cs.princeton.edu/~diego/professional/luasocket/http.html",
|
||||
sink = ltn12.sink.file(io.stdout)
|
||||
}
|
||||
|
||||
-- connect to server "www.example.com" and tries to retrieve
|
||||
-- "/private/index.html". Fails because authentication is needed.
|
||||
b, c, h = http.request("http://www.example.com/private/index.html")
|
||||
-- b returns some useless page telling about the denied access,
|
||||
-- b returns some useless page telling about the denied access,
|
||||
-- h returns authentication information
|
||||
-- and c returns with value 401 (Authentication Required)
|
||||
|
||||
@ -237,11 +239,11 @@ r, e = http.request("http://wrong.host/")
|
||||
-- r is nil, and e returns with value "host not found"
|
||||
</pre>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
And here is an example using the generic interface:
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
<pre class="example">
|
||||
-- load the http module
|
||||
http = require("socket.http")
|
||||
|
||||
@ -263,7 +265,7 @@ r, c, h = http.request {
|
||||
-- }
|
||||
</pre>
|
||||
|
||||
<p class=note id="post">
|
||||
<p class="note" id="post">
|
||||
Note: When sending a POST request, simple interface adds a
|
||||
"<tt>Content-type: application/x-www-form-urlencoded</tt>"
|
||||
header to the request. This is the type used by
|
||||
@ -271,21 +273,21 @@ HTML forms. If you need another type, use the generic
|
||||
interface.
|
||||
</p>
|
||||
|
||||
<p class=note id="authentication">
|
||||
<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 Authentication Required".
|
||||
download and return status "401 Authentication Required".
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<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.ietf.org/rfc/rfc2068.txt">RFC 2068</a>.
|
||||
</p>
|
||||
|
||||
<p class=note>The Basic Authentication Scheme sends
|
||||
<p class="note">The Basic Authentication Scheme sends
|
||||
<tt><user></tt> and
|
||||
<tt><password></tt> unencrypted to the server and is therefore
|
||||
considered unsafe. Unfortunately, by the time of this implementation,
|
||||
@ -294,7 +296,7 @@ Therefore, this is the method used by the toolkit whenever
|
||||
authentication is required.
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
<pre class="example">
|
||||
-- load required modules
|
||||
http = require("socket.http")
|
||||
mime = require("mime")
|
||||
@ -314,15 +316,15 @@ r, c = http.request {
|
||||
|
||||
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<div class=footer>
|
||||
<div class="footer">
|
||||
<hr>
|
||||
<center>
|
||||
<p class=bar>
|
||||
<p class="bar">
|
||||
<a href="index.html">home</a> ·
|
||||
<a href="index.html#download">download</a> ·
|
||||
<a href="installation.html">installation</a> ·
|
||||
<a href="introduction.html">introduction</a> ·
|
||||
<a href="reference.html">reference</a>
|
||||
<a href="reference.html">reference</a>
|
||||
</p>
|
||||
<p>
|
||||
<small>
|
@ -1,4 +1,4 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
||||
"http://www.w3.org/TR/html4/strict.dtd">
|
||||
<html>
|
||||
|
||||
@ -13,22 +13,22 @@
|
||||
|
||||
<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<div class=header>
|
||||
<div class="header">
|
||||
<hr>
|
||||
<center>
|
||||
<table summary="LuaSocket logo">
|
||||
<tr><td align=center><a href="http://www.lua.org">
|
||||
<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png">
|
||||
<tr><td align="center"><a href="http://www.lua.org">
|
||||
<img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
|
||||
</a></td></tr>
|
||||
<tr><td align=center valign=top>Network support for the Lua language
|
||||
<tr><td align="center" valign="top">Network support for the Lua language
|
||||
</td></tr>
|
||||
</table>
|
||||
<p class=bar>
|
||||
<p class="bar">
|
||||
<a href="index.html">home</a> ·
|
||||
<a href="index.html#download">download</a> ·
|
||||
<a href="installation.html">installation</a> ·
|
||||
<a href="introduction.html">introduction</a> ·
|
||||
<a href="reference.html">reference</a>
|
||||
<a href="reference.html">reference</a>
|
||||
</p>
|
||||
</center>
|
||||
<hr>
|
||||
@ -36,13 +36,13 @@
|
||||
|
||||
<!-- whatis +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<h2 id=whatis>What is LuaSocket?</h2>
|
||||
<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 core that provides support for the TCP
|
||||
and UDP transport layers, and a set of Lua modules that add support for
|
||||
functionality commonly needed by applications that deal with the Internet.
|
||||
functionality commonly needed by applications that deal with the Internet.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
@ -52,63 +52,63 @@ properly initialized by the interpreter in use. The code has been tested
|
||||
and runs well on several Windows and UNIX platforms. </p>
|
||||
|
||||
<p>
|
||||
Among the support modules, the most commonly used implement the
|
||||
<a href=smtp.html>SMTP</a>
|
||||
(sending e-mails),
|
||||
<a href=http.html>HTTP</a>
|
||||
(WWW access) and
|
||||
<a href=ftp.html>FTP</a>
|
||||
Among the support modules, the most commonly used implement the
|
||||
<a href="smtp.html">SMTP</a>
|
||||
(sending e-mails),
|
||||
<a href="http.html">HTTP</a>
|
||||
(WWW access) and
|
||||
<a href="ftp.html">FTP</a>
|
||||
(uploading and downloading files) client
|
||||
protocols. These provide a very natural and generic interface to the
|
||||
functionality defined by each protocol.
|
||||
In addition, you will find that the
|
||||
<a href=mime.html>MIME</a> (common encodings),
|
||||
<a href=url.html>URL</a>
|
||||
(anything you could possible want to do with one) and
|
||||
<a href=ltn12.html>LTN12</a>
|
||||
(filters, sinks, sources and pumps) modules can be very handy.
|
||||
functionality defined by each protocol.
|
||||
In addition, you will find that the
|
||||
<a href="mime.html">MIME</a> (common encodings),
|
||||
<a href="url.html">URL</a>
|
||||
(anything you could possible want to do with one) and
|
||||
<a href="ltn12.html">LTN12</a>
|
||||
(filters, sinks, sources and pumps) modules can be very handy.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The library is available under the same
|
||||
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
|
||||
that if you can use Lua in a project, you should also be able to use
|
||||
LuaSocket.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Copyright © 1999-2013 Diego Nehab. All rights reserved. <br>
|
||||
Author: <A href="http://www.impa.br/~diego">Diego Nehab</a>
|
||||
Author: <a href="http://www.impa.br/~diego">Diego Nehab</a>
|
||||
</p>
|
||||
|
||||
<!-- download +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<h2 id=download>Download</h2>
|
||||
<h2 id="download">Download</h2>
|
||||
|
||||
<p>
|
||||
LuaSocket version 3.0-rc1 is now available for download!
|
||||
It is compatible with Lua 5.1 and 5.2, and has
|
||||
LuaSocket version 3.0-rc1 is now available for download!
|
||||
It is compatible with Lua 5.1 and 5.2, and has
|
||||
been tested on Windows XP, Linux, and Mac OS X. Chances
|
||||
are it works well on most UNIX distributions and Windows flavors.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The current version of the library can be found at
|
||||
the <a href="https://github.com/diegonehab/luasocket">LuaSocket
|
||||
project page</a> on GitHub. Besides the full C and Lua source code
|
||||
for the library, the distribution contains several examples,
|
||||
the <a href="https://github.com/lunarmodules/luasocket">LuaSocket
|
||||
project page</a> on GitHub. Besides the full C and Lua source code
|
||||
for the library, the distribution contains several examples,
|
||||
this user's manual and basic test procedures.
|
||||
</p>
|
||||
|
||||
<p> Take a look at the <a
|
||||
href=installation.html>installation</a> section of the
|
||||
href="installation.html">installation</a> section of the
|
||||
manual to find out how to properly install the library.
|
||||
</p>
|
||||
|
||||
<!-- thanks +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<h2 id=thanks>Special thanks</h2>
|
||||
<h2 id="thanks">Special thanks</h2>
|
||||
|
||||
<p>
|
||||
This marks the first release of LuaSocket that
|
||||
@ -118,85 +118,85 @@ convinced me it was time for a release including IPv6 and
|
||||
Lua 5.2 support. It was more work than we anticipated.
|
||||
Special thanks to Sam Roberts, Florian Zeitz, and Paul
|
||||
Aurich, Liam Devine, Alexey Melnichuk, and everybody else
|
||||
that has helped bring this library back to life.
|
||||
that has helped bring this library back to life.
|
||||
</p>
|
||||
|
||||
<!-- whatsnew +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<h2 id=new>What's New</h2>
|
||||
<h2 id="new">What's New</h2>
|
||||
|
||||
<p>
|
||||
Main changes for LuaSocket 3.0-rc1 are IPv6 support
|
||||
and Lua 5.2 compatibility.
|
||||
and Lua 5.2 compatibility.
|
||||
</p>
|
||||
|
||||
<ul>
|
||||
<li> Added: Compatible with Lua 5.2
|
||||
<li> Added: Compatible with Lua 5.2</li>
|
||||
<ul>
|
||||
<li> Note that unless you define <tt>LUA_COMPAT_MODULE</tt>,
|
||||
package tables will <em>not</em> be exported as globals!
|
||||
package tables will <em>not</em> be exported as globals!</li>
|
||||
</ul>
|
||||
<li> Added: IPv6 support;
|
||||
<li> Added: IPv6 support;</li>
|
||||
<ul>
|
||||
<li> <tt>Socket.connect</tt> and <tt>socket.bind</tt> support IPv6 addresses;
|
||||
<li> <tt>Socket.connect</tt> and <tt>socket.bind</tt> support IPv6 addresses;</li>
|
||||
<li> <tt>Getpeername</tt> and <tt>getsockname</tt> support
|
||||
IPv6 addresses, and return the socket family as a third value;
|
||||
<li> URL module updated to support IPv6 host names;
|
||||
<li> New <tt>socket.tcp6</tt> and <tt>socket.udp6</tt> functions;
|
||||
<li> New <tt>socket.dns.getaddrinfo</tt> and
|
||||
<tt>socket.dns.getnameinfo</tt> functions;
|
||||
IPv6 addresses, and return the socket family as a third value;</li>
|
||||
<li> URL module updated to support IPv6 host names;</li>
|
||||
<li> New <tt>socket.tcp6</tt> and <tt>socket.udp6</tt> functions;</li>
|
||||
<li> New <tt>socket.dns.getaddrinfo</tt> and
|
||||
<tt>socket.dns.getnameinfo</tt> functions;</li>
|
||||
</ul>
|
||||
<li> Added: <tt>getoption</tt> method;
|
||||
<li> Fixed: <tt>url.unescape</tt> was returning additional values;
|
||||
<li> Fixed: <tt>mime.qp</tt>, <tt>mime.unqp</tt>,
|
||||
<li> Added: <tt>getoption</tt> method;</li>
|
||||
<li> Fixed: <tt>url.unescape</tt> was returning additional values;</li>
|
||||
<li> Fixed: <tt>mime.qp</tt>, <tt>mime.unqp</tt>,
|
||||
<tt>mime.b64</tt>, and <tt>mime.unb64</tt> could
|
||||
mistaking their own stack slots for functions arguments;
|
||||
<li> Fixed: Receiving zero-length datagram is now possible;
|
||||
<li> Improved: Hidden all internal library symbols;
|
||||
<li> Improved: Better error messages;
|
||||
<li> Improved: Better documentation of socket options.
|
||||
mistaking their own stack slots for functions arguments;</li>
|
||||
<li> Fixed: Receiving zero-length datagram is now possible;</li>
|
||||
<li> Improved: Hidden all internal library symbols;</li>
|
||||
<li> Improved: Better error messages;</li>
|
||||
<li> Improved: Better documentation of socket options.</li>
|
||||
<li> Fixed: manual sample of HTTP authentication now uses correct
|
||||
"authorization" header (Alexandre Ittner);
|
||||
<li> Fixed: failure on bind() was destroying the socket (Sam Roberts);
|
||||
"authorization" header (Alexandre Ittner);</li>
|
||||
<li> Fixed: failure on bind() was destroying the socket (Sam Roberts);</li>
|
||||
<li> Fixed: receive() returns immediatelly if prefix can satisfy
|
||||
bytes requested (M Joonas Pihlaja);
|
||||
bytes requested (M Joonas Pihlaja);</li>
|
||||
<li> Fixed: multicast didn't work on Windows, or anywhere
|
||||
else for that matter (Herbert Leuwer, Adrian Sietsma);
|
||||
else for that matter (Herbert Leuwer, Adrian Sietsma);</li>
|
||||
<li> Fixed: select() now reports an error when called with more
|
||||
sockets than FD_SETSIZE (Lorenzo Leonini);
|
||||
sockets than FD_SETSIZE (Lorenzo Leonini);</li>
|
||||
<li> Fixed: manual links to home.html changed to index.html
|
||||
(Robert Hahn);
|
||||
(Robert Hahn);</li>
|
||||
<li> Fixed: mime.unb64() would return an empty string on results that started
|
||||
with a null character (Robert Raschke);
|
||||
<li> Fixed: HTTP now automatically redirects on 303 and 307 (Jonathan Gray);
|
||||
with a null character (Robert Raschke);</li>
|
||||
<li> Fixed: HTTP now automatically redirects on 303 and 307 (Jonathan Gray);</li>
|
||||
<li> Fixed: calling sleep() with negative numbers could
|
||||
block forever, wasting CPU. Now it returns immediately (MPB);
|
||||
block forever, wasting CPU. Now it returns immediately (MPB);</li>
|
||||
<li> Improved: FTP commands are now sent in upper case to
|
||||
help buggy servers (Anders Eurenius);
|
||||
help buggy servers (Anders Eurenius);</li>
|
||||
<li> Improved: known headers now sent in canonic
|
||||
capitalization to help buggy servers (Joseph Stewart);
|
||||
<li> Improved: Clarified tcp:receive() in the manual (MPB);
|
||||
<li> Improved: Decent makefiles (LHF).
|
||||
<li> Fixed: RFC links in documentation now point to IETF (Cosmin Apreutesei).
|
||||
capitalization to help buggy servers (Joseph Stewart);</li>
|
||||
<li> Improved: Clarified tcp:receive() in the manual (MPB);</li>
|
||||
<li> Improved: Decent makefiles (LHF).</li>
|
||||
<li> Fixed: RFC links in documentation now point to IETF (Cosmin Apreutesei).</li>
|
||||
</ul>
|
||||
|
||||
<!-- old ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<h2 id=old>Old Versions</h2>
|
||||
<h2 id="old">Old Versions</h2>
|
||||
|
||||
<p>
|
||||
All previous versions of the LuaSocket library can be downloaded <a
|
||||
href="http://www.impa.br/~diego/software/luasocket/old">
|
||||
here</a>. Although these versions are no longer supported, they are
|
||||
still available for those that have compatibility issues.
|
||||
still available for those that have compatibility issues.
|
||||
</p>
|
||||
|
||||
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<div class=footer>
|
||||
<div class="footer">
|
||||
<hr>
|
||||
<center>
|
||||
<p class=bar>
|
||||
<p class="bar">
|
||||
<a href="index.html#download">download</a> ·
|
||||
<a href="installation.html">installation</a> ·
|
||||
<a href="introduction.html">introduction</a> ·
|
@ -1,4 +1,4 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
||||
"http://www.w3.org/TR/html4/strict.dtd">
|
||||
<html>
|
||||
|
||||
@ -14,22 +14,22 @@ Pump, Support, Library">
|
||||
|
||||
<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<div class=header>
|
||||
<div class="header">
|
||||
<hr>
|
||||
<center>
|
||||
<table summary="LuaSocket logo">
|
||||
<tr><td align=center><a href="http://www.lua.org">
|
||||
<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png">
|
||||
<tr><td align="center"><a href="http://www.lua.org">
|
||||
<img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
|
||||
</a></td></tr>
|
||||
<tr><td align=center valign=top>Network support for the Lua language
|
||||
<tr><td align="center" valign="top">Network support for the Lua language
|
||||
</td></tr>
|
||||
</table>
|
||||
<p class=bar>
|
||||
<p class="bar">
|
||||
<a href="index.html">home</a> ·
|
||||
<a href="index.html#download">download</a> ·
|
||||
<a href="installation.html">installation</a> ·
|
||||
<a href="introduction.html">introduction</a> ·
|
||||
<a href="reference.html">reference</a>
|
||||
<a href="reference.html">reference</a>
|
||||
</p>
|
||||
</center>
|
||||
<hr>
|
||||
@ -37,7 +37,7 @@ Pump, Support, Library">
|
||||
|
||||
<!-- ltn12 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<h2 id=ltn12>LTN12</h2>
|
||||
<h2 id="ltn12">LTN12</h2>
|
||||
|
||||
<p> The <tt>ltn12</tt> namespace implements the ideas described in
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">
|
||||
@ -46,11 +46,11 @@ functions. Please refer to the LTN for a deeper explanation of the
|
||||
functionality provided by this module.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<p>
|
||||
To obtain the <tt>ltn12</tt> namespace, run:
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
<pre class="example">
|
||||
-- loads the LTN21 module
|
||||
local ltn12 = require("ltn12")
|
||||
</pre>
|
||||
@ -61,32 +61,32 @@ local ltn12 = require("ltn12")
|
||||
|
||||
<!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="filter.chain">
|
||||
ltn12.filter.<b>chain(</b>filter<sub>1</sub>, filter<sub>2</sub>
|
||||
<p class="name" id="filter.chain">
|
||||
ltn12.filter.<b>chain(</b>filter<sub>1</sub>, filter<sub>2</sub>
|
||||
[, ... filter<sub>N</sub>]<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Returns a filter that passes all data it receives through each of a
|
||||
series of given filters.
|
||||
series of given filters.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<p class="parameters">
|
||||
<tt>Filter<sub>1</sub></tt> to <tt>filter<sub>N</sub></tt> are simple
|
||||
filters.
|
||||
filters.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
<p class="return">
|
||||
The function returns the chained filter.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
The nesting of filters can be arbitrary. For instance, the useless filter
|
||||
below doesn't do anything but return the data that was passed to it,
|
||||
unaltered.
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
<pre class="example">
|
||||
-- load required modules
|
||||
local ltn12 = require("ltn12")
|
||||
local mime = require("mime")
|
||||
@ -102,26 +102,26 @@ id = ltn12.filter.chain(
|
||||
|
||||
<!-- cycle ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="filter.cycle">
|
||||
<p class="name" id="filter.cycle">
|
||||
ltn12.filter.<b>cycle(</b>low [, ctx, extra]<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Returns a high-level filter that cycles though a low-level filter by
|
||||
passing it each chunk and updating a context between calls.
|
||||
passing it each chunk and updating a context between calls.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<tt>Low</tt> is the low-level filter to be cycled,
|
||||
<p class="parameters">
|
||||
<tt>Low</tt> is the low-level filter to be cycled,
|
||||
<tt>ctx</tt> is the initial context and <tt>extra</tt> is any extra
|
||||
argument the low-level filter might take.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
The function returns the high-level filter.
|
||||
<p class="return">
|
||||
The function returns the high-level filter.
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
<pre class="example">
|
||||
-- load the ltn12 module
|
||||
local ltn12 = require("ltn12")
|
||||
|
||||
@ -137,15 +137,15 @@ end
|
||||
|
||||
<!-- all ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="pump.all">
|
||||
<p class="name" id="pump.all">
|
||||
ltn12.pump.<b>all(</b>source, sink<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
Pumps <em>all</em> data from a <tt>source</tt> to a <tt>sink</tt>.
|
||||
<p class="description">
|
||||
Pumps <em>all</em> data from a <tt>source</tt> to a <tt>sink</tt>.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
<p class="return">
|
||||
If successful, the function returns a value that evaluates to
|
||||
<b><tt>true</tt></b>. In case
|
||||
of error, the function returns a <b><tt>false</tt></b> value, followed by an error message.
|
||||
@ -153,15 +153,15 @@ of error, the function returns a <b><tt>false</tt></b> value, followed by an err
|
||||
|
||||
<!-- step +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="pump.step">
|
||||
<p class="name" id="pump.step">
|
||||
ltn12.pump.<b>step(</b>source, sink<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
Pumps <em>one</em> chunk of data from a <tt>source</tt> to a <tt>sink</tt>.
|
||||
<p class="description">
|
||||
Pumps <em>one</em> chunk of data from a <tt>source</tt> to a <tt>sink</tt>.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
<p class="return">
|
||||
If successful, the function returns a value that evaluates to
|
||||
<b><tt>true</tt></b>. In case
|
||||
of error, the function returns a <b><tt>false</tt></b> value, followed by an error message.
|
||||
@ -173,52 +173,52 @@ of error, the function returns a <b><tt>false</tt></b> value, followed by an err
|
||||
|
||||
<!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="sink.chain">
|
||||
<p class="name" id="sink.chain">
|
||||
ltn12.sink.<b>chain(</b>filter, sink<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
Creates and returns a new sink that passes data through a <tt>filter</tt> before sending it to a given <tt>sink</tt>.
|
||||
<p class="description">
|
||||
Creates and returns a new sink that passes data through a <tt>filter</tt> before sending it to a given <tt>sink</tt>.
|
||||
</p>
|
||||
|
||||
<!-- error ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="sink.error">
|
||||
<p class="name" id="sink.error">
|
||||
ltn12.sink.<b>error(</b>message<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Creates and returns a sink that aborts transmission with the error
|
||||
<tt>message</tt>.
|
||||
</p>
|
||||
|
||||
<!-- file +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="sink.file">
|
||||
<p class="name" id="sink.file">
|
||||
ltn12.sink.<b>file(</b>handle, message<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
Creates a sink that sends data to a file.
|
||||
<p class="description">
|
||||
Creates a sink that sends data to a file.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<tt>Handle</tt> is a file handle. If <tt>handle</tt> is <tt><b>nil</b></tt>,
|
||||
<tt>message</tt> should give the reason for failure.
|
||||
<p class="parameters">
|
||||
<tt>Handle</tt> is a file handle. If <tt>handle</tt> is <tt><b>nil</b></tt>,
|
||||
<tt>message</tt> should give the reason for failure.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
<p class="return">
|
||||
The function returns a sink that sends all data to the given <tt>handle</tt>
|
||||
and closes the file when done, or a sink that aborts the transmission with
|
||||
the error <tt>message</tt>
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
In the following example, notice how the prototype is designed to
|
||||
<p class="note">
|
||||
In the following example, notice how the prototype is designed to
|
||||
fit nicely with the <tt>io.open</tt> function.
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
<pre class="example">
|
||||
-- load the ltn12 module
|
||||
local ltn12 = require("ltn12")
|
||||
|
||||
@ -231,45 +231,45 @@ ltn12.pump.all(
|
||||
|
||||
<!-- null +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="sink.null">
|
||||
<p class="name" id="sink.null">
|
||||
ltn12.sink.<b>null()</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
Returns a sink that ignores all data it receives.
|
||||
<p class="description">
|
||||
Returns a sink that ignores all data it receives.
|
||||
</p>
|
||||
|
||||
<!-- simplify +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="sink.simplify">
|
||||
<p class="name" id="sink.simplify">
|
||||
ltn12.sink.<b>simplify(</b>sink<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
Creates and returns a simple sink given a fancy <tt>sink</tt>.
|
||||
<p class="description">
|
||||
Creates and returns a simple sink given a fancy <tt>sink</tt>.
|
||||
</p>
|
||||
|
||||
<!-- table ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="sink.table">
|
||||
<p class="name" id="sink.table">
|
||||
ltn12.sink.<b>table(</b>[table]<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Creates a sink that stores all chunks in a table. The chunks can later be
|
||||
efficiently concatenated into a single string.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<p class="parameters">
|
||||
<tt>Table</tt> is used to hold the chunks. If
|
||||
<tt><b>nil</b></tt>, the function creates its own table.
|
||||
<tt><b>nil</b></tt>, the function creates its own table.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
The function returns the sink and the table used to store the chunks.
|
||||
<p class="return">
|
||||
The function returns the sink and the table used to store the chunks.
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
<pre class="example">
|
||||
-- load needed modules
|
||||
local http = require("socket.http")
|
||||
local ltn12 = require("ltn12")
|
||||
@ -291,89 +291,89 @@ end
|
||||
|
||||
<!-- cat ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="source.cat">
|
||||
<p class="name" id="source.cat">
|
||||
ltn12.source.<b>cat(</b>source<sub>1</sub> [, source<sub>2</sub>, ...,
|
||||
source<sub>N</sub>]<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Creates a new source that produces the concatenation of the data produced
|
||||
by a number of sources.
|
||||
by a number of sources.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<p class="parameters">
|
||||
<tt>Source<sub>1</sub></tt> to <tt>source<sub>N</sub></tt> are the original
|
||||
sources.
|
||||
sources.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
<p class="return">
|
||||
The function returns the new source.
|
||||
</p>
|
||||
|
||||
<!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="source.chain">
|
||||
<p class="name" id="source.chain">
|
||||
ltn12.source.<b>chain(</b>source, filter<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
Creates a new <tt>source</tt> that passes data through a <tt>filter</tt>
|
||||
before returning it.
|
||||
<p class="description">
|
||||
Creates a new <tt>source</tt> that passes data through a <tt>filter</tt>
|
||||
before returning it.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
<p class="return">
|
||||
The function returns the new source.
|
||||
</p>
|
||||
|
||||
<!-- empty ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="source.empty">
|
||||
<p class="name" id="source.empty">
|
||||
ltn12.source.<b>empty()</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
Creates and returns an empty source.
|
||||
<p class="description">
|
||||
Creates and returns an empty source.
|
||||
</p>
|
||||
|
||||
<!-- error ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="source.error">
|
||||
<p class="name" id="source.error">
|
||||
ltn12.source.<b>error(</b>message<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Creates and returns a source that aborts transmission with the error
|
||||
<tt>message</tt>.
|
||||
</p>
|
||||
|
||||
<!-- file +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="source.file">
|
||||
<p class="name" id="source.file">
|
||||
ltn12.source.<b>file(</b>handle, message<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
Creates a source that produces the contents of a file.
|
||||
<p class="description">
|
||||
Creates a source that produces the contents of a file.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<tt>Handle</tt> is a file handle. If <tt>handle</tt> is <tt><b>nil</b></tt>,
|
||||
<tt>message</tt> should give the reason for failure.
|
||||
<p class="parameters">
|
||||
<tt>Handle</tt> is a file handle. If <tt>handle</tt> is <tt><b>nil</b></tt>,
|
||||
<tt>message</tt> should give the reason for failure.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
The function returns a source that reads chunks of data from
|
||||
<p class="return">
|
||||
The function returns a source that reads chunks of data from
|
||||
given <tt>handle</tt> and returns it to the user,
|
||||
closing the file when done, or a source that aborts the transmission with
|
||||
the error <tt>message</tt>
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
In the following example, notice how the prototype is designed to
|
||||
<p class="note">
|
||||
In the following example, notice how the prototype is designed to
|
||||
fit nicely with the <tt>io.open</tt> function.
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
<pre class="example">
|
||||
-- load the ltn12 module
|
||||
local ltn12 = require("ltn12")
|
||||
|
||||
@ -386,41 +386,41 @@ ltn12.pump.all(
|
||||
|
||||
<!-- simplify +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="source.simplify">
|
||||
<p class="name" id="source.simplify">
|
||||
ltn12.source.<b>simplify(</b>source<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
Creates and returns a simple source given a fancy <tt>source</tt>.
|
||||
<p class="description">
|
||||
Creates and returns a simple source given a fancy <tt>source</tt>.
|
||||
</p>
|
||||
|
||||
<!-- string +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="source.string">
|
||||
<p class="name" id="source.string">
|
||||
ltn12.source.<b>string(</b>string<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Creates and returns a source that produces the contents of a
|
||||
<tt>string</tt>, chunk by chunk.
|
||||
<tt>string</tt>, chunk by chunk.
|
||||
</p>
|
||||
|
||||
<!-- table +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="source.table">
|
||||
<p class="name" id="source.table">
|
||||
ltn12.source.<b>table(</b>table<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Creates and returns a source that produces the numerically-indexed values of a <tt>table</tt> successively beginning at 1. The source returns nil (end-of-stream) whenever a nil value is produced by the current index, which proceeds forward regardless.
|
||||
</p>
|
||||
|
||||
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<div class=footer>
|
||||
<div class="footer">
|
||||
<hr>
|
||||
<center>
|
||||
<p class=bar>
|
||||
<p class="bar">
|
||||
<a href="index.html">home</a> ·
|
||||
<a href="index.html#down">download</a> ·
|
||||
<a href="installation.html">installation</a> ·
|
Before Width: | Height: | Size: 12 KiB After Width: | Height: | Size: 12 KiB |
@ -1,10 +1,10 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
||||
"http://www.w3.org/TR/html4/strict.dtd">
|
||||
<html>
|
||||
|
||||
<head>
|
||||
<meta name="description" content="LuaSocket: MIME support">
|
||||
<meta name="keywords" content="Lua, LuaSocket, MIME, Library, Support">
|
||||
<meta name="keywords" content="Lua, LuaSocket, MIME, Library, Support">
|
||||
<title>LuaSocket: MIME module</title>
|
||||
<link rel="stylesheet" href="reference.css" type="text/css">
|
||||
</head>
|
||||
@ -13,22 +13,22 @@
|
||||
|
||||
<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<div class=header>
|
||||
<div class="header">
|
||||
<hr>
|
||||
<center>
|
||||
<table summary="LuaSocket logo">
|
||||
<tr><td align=center><a href="http://www.lua.org">
|
||||
<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png">
|
||||
<tr><td align="center"><a href="http://www.lua.org">
|
||||
<img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
|
||||
</a></td></tr>
|
||||
<tr><td align=center valign=top>Network support for the Lua language
|
||||
<tr><td align="center" valign="top">Network support for the Lua language
|
||||
</td></tr>
|
||||
</table>
|
||||
<p class=bar>
|
||||
<p class="bar">
|
||||
<a href="index.html">home</a> ·
|
||||
<a href="index.html#download">download</a> ·
|
||||
<a href="installation.html">installation</a> ·
|
||||
<a href="introduction.html">introduction</a> ·
|
||||
<a href="reference.html">reference</a>
|
||||
<a href="reference.html">reference</a>
|
||||
</p>
|
||||
</center>
|
||||
<hr>
|
||||
@ -36,14 +36,14 @@
|
||||
|
||||
<!-- mime +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<h2 id=mime>MIME</h2>
|
||||
<h2 id="mime">MIME</h2>
|
||||
|
||||
<p>
|
||||
The <tt>mime</tt> namespace offers filters that apply and remove common
|
||||
content transfer encodings, such as Base64 and Quoted-Printable.
|
||||
It also provides functions to break text into lines and change
|
||||
the end-of-line convention.
|
||||
MIME is described mainly in
|
||||
MIME is described mainly in
|
||||
<a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045</a>,
|
||||
<a href="http://www.ietf.org/rfc/rfc2046.txt">2046</a>,
|
||||
<a href="http://www.ietf.org/rfc/rfc2047.txt">2047</a>,
|
||||
@ -52,17 +52,17 @@ MIME is described mainly in
|
||||
</p>
|
||||
|
||||
<p>
|
||||
All functionality provided by the MIME module
|
||||
follows the ideas presented in
|
||||
All functionality provided by the MIME module
|
||||
follows the ideas presented in
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">
|
||||
LTN012, Filters sources and sinks</a>.
|
||||
LTN012, Filters sources and sinks</a>.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<p>
|
||||
To obtain the <tt>mime</tt> namespace, run:
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
<pre class="example">
|
||||
-- loads the MIME module and everything it requires
|
||||
local mime = require("mime")
|
||||
</pre>
|
||||
@ -70,60 +70,60 @@ local mime = require("mime")
|
||||
|
||||
<!-- High-level +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<h3 id=high>High-level filters</h3>
|
||||
<h3 id="high">High-level filters</h3>
|
||||
|
||||
|
||||
<!-- decode +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="decode">
|
||||
<p class="name" id="decode">
|
||||
mime.<b>decode(</b>"base64"<b>)</b><br>
|
||||
mime.<b>decode(</b>"quoted-printable"<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Returns a filter that decodes data from a given transfer content
|
||||
encoding.
|
||||
</p>
|
||||
|
||||
<!-- encode +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="encode">
|
||||
<p class="name" id="encode">
|
||||
mime.<b>encode(</b>"base64"<b>)</b><br>
|
||||
mime.<b>encode(</b>"quoted-printable" [, mode]<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Returns a filter that encodes data according to a given transfer content
|
||||
encoding.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<p class="parameters">
|
||||
In the Quoted-Printable case, the user can specify whether the data is
|
||||
textual or binary, by passing the <tt>mode</tt> strings "<tt>text</tt>" or
|
||||
"<tt>binary</tt>". <tt>Mode</tt> defaults to "<tt>text</tt>".
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
Although both transfer content encodings specify a limit for the line
|
||||
length, the encoding filters do <em>not</em> break text into lines (for
|
||||
added flexibility).
|
||||
added flexibility).
|
||||
Below is a filter that converts binary data to the Base64 transfer content
|
||||
encoding and breaks it into lines of the correct size.
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
<pre class="example">
|
||||
base64 = ltn12.filter.chain(
|
||||
mime.encode("base64"),
|
||||
mime.wrap("base64")
|
||||
)
|
||||
</pre>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
Note: Text data <em>has</em> to be converted to canonic form
|
||||
<em>before</em> being encoded.
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
<pre class="example">
|
||||
base64 = ltn12.filter.chain(
|
||||
mime.normalize(),
|
||||
mime.encode("base64"),
|
||||
@ -133,77 +133,77 @@ base64 = ltn12.filter.chain(
|
||||
|
||||
<!-- normalize ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="normalize">
|
||||
<p class="name" id="normalize">
|
||||
mime.<b>normalize(</b>[marker]<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
Converts most common end-of-line markers to a specific given marker.
|
||||
<p class="description">
|
||||
Converts most common end-of-line markers to a specific given marker.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<tt>Marker</tt> is the new marker. It defaults to CRLF, the canonic
|
||||
<p class="parameters">
|
||||
<tt>Marker</tt> is the new marker. It defaults to CRLF, the canonic
|
||||
end-of-line marker defined by the MIME standard.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
The function returns a filter that performs the conversion.
|
||||
<p class="return">
|
||||
The function returns a filter that performs the conversion.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
Note: There is no perfect solution to this problem. Different end-of-line
|
||||
markers are an evil that will probably plague developers forever.
|
||||
markers are an evil that will probably plague developers forever.
|
||||
This function, however, will work perfectly for text created with any of
|
||||
the most common end-of-line markers, i.e. the Mac OS (CR), the Unix (LF),
|
||||
the most common end-of-line markers, i.e. the Mac OS (CR), the Unix (LF),
|
||||
or the DOS (CRLF) conventions. Even if the data has mixed end-of-line
|
||||
markers, the function will still work well, although it doesn't
|
||||
markers, the function will still work well, although it doesn't
|
||||
guarantee that the number of empty lines will be correct.
|
||||
</p>
|
||||
|
||||
<!-- stuff +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="stuff">
|
||||
<p class="name" id="stuff">
|
||||
mime.<b>stuff()</b><br>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Creates and returns a filter that performs stuffing of SMTP messages.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
Note: The <a href=smtp.html#send><tt>smtp.send</tt></a> function
|
||||
<p class="note">
|
||||
Note: The <a href="smtp.html#send"><tt>smtp.send</tt></a> function
|
||||
uses this filter automatically. You don't need to chain it with your
|
||||
source, or apply it to your message body.
|
||||
source, or apply it to your message body.
|
||||
</p>
|
||||
|
||||
<!-- wrap +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="wrap">
|
||||
<p class="name" id="wrap">
|
||||
mime.<b>wrap(</b>"text" [, length]<b>)</b><br>
|
||||
mime.<b>wrap(</b>"base64"<b>)</b><br>
|
||||
mime.<b>wrap(</b>"quoted-printable"<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
Returns a filter that breaks data into lines.
|
||||
<p class="description">
|
||||
Returns a filter that breaks data into lines.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
The "<tt>text</tt>" line-wrap filter simply breaks text into lines by
|
||||
inserting CRLF end-of-line markers at appropriate positions.
|
||||
<tt>Length</tt> defaults 76.
|
||||
<p class="parameters">
|
||||
The "<tt>text</tt>" line-wrap filter simply breaks text into lines by
|
||||
inserting CRLF end-of-line markers at appropriate positions.
|
||||
<tt>Length</tt> defaults 76.
|
||||
The "<tt>base64</tt>" line-wrap filter works just like the default
|
||||
"<tt>text</tt>" line-wrap filter with default length.
|
||||
"<tt>text</tt>" line-wrap filter with default length.
|
||||
The function can also wrap "<tt>quoted-printable</tt>" lines, taking care
|
||||
not to break lines in the middle of an escaped character. In that case, the
|
||||
line length is fixed at 76.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
For example, to create an encoding filter for the Quoted-Printable transfer content encoding of text data, do the following:
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
<pre class="example">
|
||||
qp = ltn12.filter.chain(
|
||||
mime.normalize(),
|
||||
mime.encode("quoted-printable"),
|
||||
@ -211,155 +211,155 @@ qp = ltn12.filter.chain(
|
||||
)
|
||||
</pre>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
Note: To break into lines with a different end-of-line convention, apply
|
||||
a normalization filter after the line break filter.
|
||||
a normalization filter after the line break filter.
|
||||
</p>
|
||||
|
||||
<!-- Low-level ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<h3 id=low>Low-level filters</h3>
|
||||
<h3 id="low">Low-level filters</h3>
|
||||
|
||||
<!-- b64 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="b64">
|
||||
<p class="name" id="b64">
|
||||
A, B = mime.<b>b64(</b>C [, D]<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
Low-level filter to perform Base64 encoding.
|
||||
<p class="description">
|
||||
Low-level filter to perform Base64 encoding.
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<tt>A</tt> is the encoded version of the largest prefix of
|
||||
<tt>C..D</tt>
|
||||
that can be encoded unambiguously. <tt>B</tt> has the remaining bytes of
|
||||
<tt>C..D</tt>, <em>before</em> encoding.
|
||||
If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is padded with
|
||||
the encoding of the remaining bytes of <tt>C</tt>.
|
||||
<p class="description">
|
||||
<tt>A</tt> is the encoded version of the largest prefix of
|
||||
<tt>C..D</tt>
|
||||
that can be encoded unambiguously. <tt>B</tt> has the remaining bytes of
|
||||
<tt>C..D</tt>, <em>before</em> encoding.
|
||||
If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is padded with
|
||||
the encoding of the remaining bytes of <tt>C</tt>.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
Note: The simplest use of this function is to encode a string into it's
|
||||
Base64 transfer content encoding. Notice the extra parenthesis around the
|
||||
call to <tt>mime.b64</tt>, to discard the second return value.
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
<pre class="example">
|
||||
print((mime.b64("diego:password")))
|
||||
--> ZGllZ286cGFzc3dvcmQ=
|
||||
</pre>
|
||||
|
||||
<!-- dot +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
<p class=name id="dot">
|
||||
<p class="name" id="dot">
|
||||
A, n = mime.<b>dot(</b>m [, B]<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Low-level filter to perform SMTP stuffing and enable transmission of
|
||||
messages containing the sequence "CRLF.CRLF".
|
||||
messages containing the sequence "CRLF.CRLF".
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<p class="parameters">
|
||||
<tt>A</tt> is the stuffed version of <tt>B</tt>. '<tt>n</tt>' gives the
|
||||
number of characters from the sequence CRLF seen in the end of <tt>B</tt>.
|
||||
'<tt>m</tt>' should tell the same, but for the previous chunk.
|
||||
</p>
|
||||
|
||||
<p class=note>Note: The message body is defined to begin with
|
||||
<p class="note">Note: The message body is defined to begin with
|
||||
an implicit CRLF. Therefore, to stuff a message correctly, the
|
||||
first <tt>m</tt> should have the value 2.
|
||||
first <tt>m</tt> should have the value 2.
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
<pre class="example">
|
||||
print((string.gsub(mime.dot(2, ".\r\nStuffing the message.\r\n.\r\n."), "\r\n", "\\n")))
|
||||
--> ..\nStuffing the message.\n..\n..
|
||||
</pre>
|
||||
|
||||
<p class=note>
|
||||
Note: The <a href=smtp.html#send><tt>smtp.send</tt></a> function
|
||||
uses this filter automatically. You don't need to
|
||||
apply it again.
|
||||
<p class="note">
|
||||
Note: The <a href="smtp.html#send"><tt>smtp.send</tt></a> function
|
||||
uses this filter automatically. You don't need to
|
||||
apply it again.
|
||||
</p>
|
||||
|
||||
<!-- eol ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="eol">
|
||||
<p class="name" id="eol">
|
||||
A, B = mime.<b>eol(</b>C [, D, marker]<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
Low-level filter to perform end-of-line marker translation.
|
||||
<p class="description">
|
||||
Low-level filter to perform end-of-line marker translation.
|
||||
For each chunk, the function needs to know if the last character of the
|
||||
previous chunk could be part of an end-of-line marker or not. This is the
|
||||
context the function receives besides the chunk. An updated version of
|
||||
the context is returned after each new chunk.
|
||||
the context is returned after each new chunk.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<p class="parameters">
|
||||
<tt>A</tt> is the translated version of <tt>D</tt>. <tt>C</tt> is the
|
||||
ASCII value of the last character of the previous chunk, if it was a
|
||||
candidate for line break, or 0 otherwise.
|
||||
candidate for line break, or 0 otherwise.
|
||||
<tt>B</tt> is the same as <tt>C</tt>, but for the current
|
||||
chunk. <tt>Marker</tt> gives the new end-of-line marker and defaults to CRLF.
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
<pre class="example">
|
||||
-- translates the end-of-line marker to UNIX
|
||||
unix = mime.eol(0, dos, "\n")
|
||||
unix = mime.eol(0, dos, "\n")
|
||||
</pre>
|
||||
|
||||
<!-- qp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="qp">
|
||||
<p class="name" id="qp">
|
||||
A, B = mime.<b>qp(</b>C [, D, marker]<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
Low-level filter to perform Quoted-Printable encoding.
|
||||
<p class="description">
|
||||
Low-level filter to perform Quoted-Printable encoding.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<tt>A</tt> is the encoded version of the largest prefix of
|
||||
<tt>C..D</tt>
|
||||
that can be encoded unambiguously. <tt>B</tt> has the remaining bytes of
|
||||
<tt>C..D</tt>, <em>before</em> encoding.
|
||||
If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is padded with
|
||||
the encoding of the remaining bytes of <tt>C</tt>.
|
||||
Throughout encoding, occurrences of CRLF are replaced by the
|
||||
<p class="parameters">
|
||||
<tt>A</tt> is the encoded version of the largest prefix of
|
||||
<tt>C..D</tt>
|
||||
that can be encoded unambiguously. <tt>B</tt> has the remaining bytes of
|
||||
<tt>C..D</tt>, <em>before</em> encoding.
|
||||
If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is padded with
|
||||
the encoding of the remaining bytes of <tt>C</tt>.
|
||||
Throughout encoding, occurrences of CRLF are replaced by the
|
||||
<tt>marker</tt>, which itself defaults to CRLF.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
Note: The simplest use of this function is to encode a string into it's
|
||||
Quoted-Printable transfer content encoding.
|
||||
Quoted-Printable transfer content encoding.
|
||||
Notice the extra parenthesis around the call to <tt>mime.qp</tt>, to discard the second return value.
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
print((mime.qp("maçã")))
|
||||
<pre class="example">
|
||||
print((mime.qp("ma<EFBFBD><EFBFBD>")))
|
||||
--> ma=E7=E3=
|
||||
</pre>
|
||||
|
||||
<!-- qpwrp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="qpwrp">
|
||||
<p class="name" id="qpwrp">
|
||||
A, m = mime.<b>qpwrp(</b>n [, B, length]<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
Low-level filter to break Quoted-Printable text into lines.
|
||||
<p class="description">
|
||||
Low-level filter to break Quoted-Printable text into lines.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<tt>A</tt> is a copy of <tt>B</tt>, broken into lines of at most
|
||||
<tt>length</tt> bytes (defaults to 76).
|
||||
'<tt>n</tt>' should tell how many bytes are left for the first
|
||||
line of <tt>B</tt> and '<tt>m</tt>' returns the number of bytes
|
||||
left in the last line of <tt>A</tt>.
|
||||
<p class="parameters">
|
||||
<tt>A</tt> is a copy of <tt>B</tt>, broken into lines of at most
|
||||
<tt>length</tt> bytes (defaults to 76).
|
||||
'<tt>n</tt>' should tell how many bytes are left for the first
|
||||
line of <tt>B</tt> and '<tt>m</tt>' returns the number of bytes
|
||||
left in the last line of <tt>A</tt>.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
Note: Besides breaking text into lines, this function makes sure the line
|
||||
breaks don't fall in the middle of an escaped character combination. Also,
|
||||
this function only breaks lines that are bigger than <tt>length</tt> bytes.
|
||||
@ -367,86 +367,86 @@ this function only breaks lines that are bigger than <tt>length</tt> bytes.
|
||||
|
||||
<!-- unb64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="unb64">
|
||||
<p class="name" id="unb64">
|
||||
A, B = mime.<b>unb64(</b>C [, D]<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
Low-level filter to perform Base64 decoding.
|
||||
<p class="description">
|
||||
Low-level filter to perform Base64 decoding.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<tt>A</tt> is the decoded version of the largest prefix of
|
||||
<tt>C..D</tt>
|
||||
that can be decoded unambiguously. <tt>B</tt> has the remaining bytes of
|
||||
<tt>C..D</tt>, <em>before</em> decoding.
|
||||
<p class="parameters">
|
||||
<tt>A</tt> is the decoded version of the largest prefix of
|
||||
<tt>C..D</tt>
|
||||
that can be decoded unambiguously. <tt>B</tt> has the remaining bytes of
|
||||
<tt>C..D</tt>, <em>before</em> decoding.
|
||||
If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is the empty string
|
||||
and <tt>B</tt> returns whatever couldn't be decoded.
|
||||
and <tt>B</tt> returns whatever couldn't be decoded.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
Note: The simplest use of this function is to decode a string from it's
|
||||
Base64 transfer content encoding.
|
||||
Base64 transfer content encoding.
|
||||
Notice the extra parenthesis around the call to <tt>mime.unqp</tt>, to discard the second return value.
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
<pre class="example">
|
||||
print((mime.unb64("ZGllZ286cGFzc3dvcmQ=")))
|
||||
--> diego:password
|
||||
</pre>
|
||||
|
||||
<!-- unqp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="unqp">
|
||||
<p class="name" id="unqp">
|
||||
A, B = mime.<b>unqp(</b>C [, D]<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Low-level filter to remove the Quoted-Printable transfer content encoding
|
||||
from data.
|
||||
from data.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<tt>A</tt> is the decoded version of the largest prefix of
|
||||
<tt>C..D</tt>
|
||||
that can be decoded unambiguously. <tt>B</tt> has the remaining bytes of
|
||||
<tt>C..D</tt>, <em>before</em> decoding.
|
||||
If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is augmented with
|
||||
the encoding of the remaining bytes of <tt>C</tt>.
|
||||
<p class="parameters">
|
||||
<tt>A</tt> is the decoded version of the largest prefix of
|
||||
<tt>C..D</tt>
|
||||
that can be decoded unambiguously. <tt>B</tt> has the remaining bytes of
|
||||
<tt>C..D</tt>, <em>before</em> decoding.
|
||||
If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is augmented with
|
||||
the encoding of the remaining bytes of <tt>C</tt>.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
Note: The simplest use of this function is to decode a string from it's
|
||||
Quoted-Printable transfer content encoding.
|
||||
Quoted-Printable transfer content encoding.
|
||||
Notice the extra parenthesis around the call to <tt>mime.unqp</tt>, to discard the second return value.
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
<pre class="example">
|
||||
print((mime.qp("ma=E7=E3=")))
|
||||
--> maçã
|
||||
--> ma<EFBFBD><EFBFBD>
|
||||
</pre>
|
||||
|
||||
<!-- wrp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="wrp">
|
||||
<p class="name" id="wrp">
|
||||
A, m = mime.<b>wrp(</b>n [, B, length]<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
Low-level filter to break text into lines with CRLF marker.
|
||||
Text is assumed to be in the <a href=#normalize><tt>normalize</tt></a> form.
|
||||
<p class="description">
|
||||
Low-level filter to break text into lines with CRLF marker.
|
||||
Text is assumed to be in the <a href="#normalize"><tt>normalize</tt></a> form.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<tt>A</tt> is a copy of <tt>B</tt>, broken into lines of at most
|
||||
<tt>length</tt> bytes (defaults to 76).
|
||||
'<tt>n</tt>' should tell how many bytes are left for the first
|
||||
line of <tt>B</tt> and '<tt>m</tt>' returns the number of bytes
|
||||
left in the last line of <tt>A</tt>.
|
||||
<p class="parameters">
|
||||
<tt>A</tt> is a copy of <tt>B</tt>, broken into lines of at most
|
||||
<tt>length</tt> bytes (defaults to 76).
|
||||
'<tt>n</tt>' should tell how many bytes are left for the first
|
||||
line of <tt>B</tt> and '<tt>m</tt>' returns the number of bytes
|
||||
left in the last line of <tt>A</tt>.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
Note: This function only breaks lines that are bigger than
|
||||
<p class="note">
|
||||
Note: This function only breaks lines that are bigger than
|
||||
<tt>length</tt> bytes. The resulting line length does not include the CRLF
|
||||
marker.
|
||||
</p>
|
||||
@ -454,10 +454,10 @@ marker.
|
||||
|
||||
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<div class=footer>
|
||||
<div class="footer">
|
||||
<hr>
|
||||
<center>
|
||||
<p class=bar>
|
||||
<p class="bar">
|
||||
<a href="index.html">home</a> ·
|
||||
<a href="index.html#down">download</a> ·
|
||||
<a href="installation.html">installation</a> ·
|
@ -1,11 +1,11 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
||||
"http://www.w3.org/TR/html4/strict.dtd">
|
||||
<html>
|
||||
|
||||
<head>
|
||||
<meta name="description" content="LuaSocket: Index to reference manual">
|
||||
<meta name="keywords" content="Lua, LuaSocket, Index, Manual, Network, Library,
|
||||
Support, Manual">
|
||||
Support, Manual">
|
||||
<title>LuaSocket: Index to reference manual</title>
|
||||
<link rel="stylesheet" href="reference.css" type="text/css">
|
||||
</head>
|
||||
@ -14,22 +14,22 @@ Support, Manual">
|
||||
|
||||
<!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<div class=header>
|
||||
<div class="header">
|
||||
<hr>
|
||||
<center>
|
||||
<table summary="LuaSocket logo">
|
||||
<tr><td align=center><a href="http://www.lua.org">
|
||||
<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png">
|
||||
<tr><td align="center"><a href="http://www.lua.org">
|
||||
<img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
|
||||
</a></td></tr>
|
||||
<tr><td align=center valign=top>Network support for the Lua language
|
||||
<tr><td align="center" valign="top">Network support for the Lua language
|
||||
</td></tr>
|
||||
</table>
|
||||
<p class=bar>
|
||||
<p class="bar">
|
||||
<a href="index.html">home</a> ·
|
||||
<a href="index.html#download">download</a> ·
|
||||
<a href="installation.html">installation</a> ·
|
||||
<a href="introduction.html">introduction</a> ·
|
||||
<a href="reference.html">reference</a>
|
||||
<a href="reference.html">reference</a>
|
||||
</p>
|
||||
</center>
|
||||
<hr>
|
||||
@ -92,7 +92,7 @@ Support, Manual">
|
||||
<a href="ltn12.html#sink.table">table</a>.
|
||||
</blockquote>
|
||||
<blockquote>
|
||||
<a href="ltn12.html#source">source</a>:
|
||||
<a href="ltn12.html#source">source</a>:
|
||||
<a href="ltn12.html#source.cat">cat</a>,
|
||||
<a href="ltn12.html#source.chain">chain</a>,
|
||||
<a href="ltn12.html#source.empty">empty</a>,
|
||||
@ -238,10 +238,10 @@ Support, Manual">
|
||||
|
||||
<!-- footer ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<div class=footer>
|
||||
<div class="footer">
|
||||
<hr>
|
||||
<center>
|
||||
<p class=bar>
|
||||
<p class="bar">
|
||||
<a href="index.html">home</a> ·
|
||||
<a href="index.html#down">download</a> ·
|
||||
<a href="installation.html">installation</a> ·
|
@ -1,11 +1,11 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
||||
"http://www.w3.org/TR/html4/strict.dtd">
|
||||
<html>
|
||||
|
||||
<head>
|
||||
<meta name="description" content="LuaSocket: SMTP support">
|
||||
<meta name="keywords" content="Lua, LuaSocket, SMTP, E-Mail, MIME, Multipart,
|
||||
Library, Support">
|
||||
Library, Support">
|
||||
<title>LuaSocket: SMTP support</title>
|
||||
<link rel="stylesheet" href="reference.css" type="text/css">
|
||||
</head>
|
||||
@ -14,22 +14,22 @@ Library, Support">
|
||||
|
||||
<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<div class=header>
|
||||
<div class="header">
|
||||
<hr>
|
||||
<center>
|
||||
<table summary="LuaSocket logo">
|
||||
<tr><td align=center><a href="http://www.lua.org">
|
||||
<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png">
|
||||
<tr><td align="center"><a href="http://www.lua.org">
|
||||
<img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
|
||||
</a></td></tr>
|
||||
<tr><td align=center valign=top>Network support for the Lua language
|
||||
<tr><td align="center" valign="top">Network support for the Lua language
|
||||
</td></tr>
|
||||
</table>
|
||||
<p class=bar>
|
||||
<p class="bar">
|
||||
<a href="index.html">home</a> ·
|
||||
<a href="index.html#download">download</a> ·
|
||||
<a href="installation.html">installation</a> ·
|
||||
<a href="introduction.html">introduction</a> ·
|
||||
<a href="reference.html">reference</a>
|
||||
<a href="reference.html">reference</a>
|
||||
</p>
|
||||
</center>
|
||||
<hr>
|
||||
@ -37,14 +37,14 @@ Library, Support">
|
||||
|
||||
<!-- smtp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<h2 id=smtp>SMTP</h2>
|
||||
<h2 id="smtp">SMTP</h2>
|
||||
|
||||
<p> The <tt>smtp</tt> namespace provides functionality to send e-mail
|
||||
messages. The high-level API consists of two functions: one to
|
||||
messages. The high-level API consists of two functions: one to
|
||||
define an e-mail message, and another to actually send the message.
|
||||
Although almost all users will find that these functions provide more than
|
||||
enough functionality, the underlying implementation allows for even more
|
||||
control (if you bother to read the code).
|
||||
control (if you bother to read the code).
|
||||
</p>
|
||||
|
||||
<p>The implementation conforms to the Simple Mail Transfer Protocol,
|
||||
@ -54,19 +54,19 @@ href="http://www.ietf.org/rfc/rfc2822.txt">RFC 2822</a>,
|
||||
which governs the Internet Message Format.
|
||||
Multipart messages (those that contain attachments) are part
|
||||
of the MIME standard, but described mainly
|
||||
in <a href="http://www.ietf.org/rfc/rfc2046.txt">RFC 2046</a>
|
||||
in <a href="http://www.ietf.org/rfc/rfc2046.txt">RFC 2046</a>.</p>
|
||||
|
||||
<p> In the description below, good understanding of <a
|
||||
href="http://lua-users.org/wiki/FiltersSourcesAndSinks"> LTN012, Filters
|
||||
sources and sinks</a> and the <a href=mime.html>MIME</a> module is
|
||||
assumed. In fact, the SMTP module was the main reason for their
|
||||
sources and sinks</a> and the <a href="mime.html">MIME</a> module is
|
||||
assumed. In fact, the SMTP module was the main reason for their
|
||||
creation. </p>
|
||||
|
||||
<p>
|
||||
<p>
|
||||
To obtain the <tt>smtp</tt> namespace, run:
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
<pre class="example">
|
||||
-- loads the SMTP module and everything it requires
|
||||
local smtp = require("socket.smtp")
|
||||
</pre>
|
||||
@ -92,40 +92,40 @@ headers = {<br>
|
||||
<p>
|
||||
Field names are case insensitive (as specified by the standard) and all
|
||||
functions work with lowercase field names (but see
|
||||
<a href=socket.html#headers.canonic><tt>socket.headers.canonic</tt></a>).
|
||||
<a href="socket.html#headers.canonic"><tt>socket.headers.canonic</tt></a>).
|
||||
Field values are left unmodified.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
Note: MIME headers are independent of order. Therefore, there is no problem
|
||||
in representing them in a Lua table.
|
||||
in representing them in a Lua table.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The following constants can be set to control the default behavior of
|
||||
the SMTP module:
|
||||
the SMTP module:
|
||||
</p>
|
||||
|
||||
<ul>
|
||||
<li> <tt>DOMAIN</tt>: domain used to greet the server;
|
||||
<li> <tt>PORT</tt>: default port used for the connection;
|
||||
<li> <tt>SERVER</tt>: default server used for the connection;
|
||||
<li> <tt>TIMEOUT</tt>: default timeout for all I/O operations;
|
||||
<li> <tt>ZONE</tt>: default time zone.
|
||||
<li> <tt>DOMAIN</tt>: domain used to greet the server;</li>
|
||||
<li> <tt>PORT</tt>: default port used for the connection;</li>
|
||||
<li> <tt>SERVER</tt>: default server used for the connection;</li>
|
||||
<li> <tt>TIMEOUT</tt>: default timeout for all I/O operations;</li>
|
||||
<li> <tt>ZONE</tt>: default time zone.</li>
|
||||
</ul>
|
||||
|
||||
<!-- message ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id=message>
|
||||
<p class="name" id="message">
|
||||
smtp.<b>message(</b>mesgt<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Returns a <em>simple</em>
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> source that sends an SMTP message body, possibly multipart (arbitrarily deep).
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> source that sends an SMTP message body, possibly multipart (arbitrarily deep).
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<p class="parameters">
|
||||
The only parameter of the function is a table describing the message.
|
||||
<tt>Mesgt</tt> has the following form (notice the recursive structure):
|
||||
</p>
|
||||
@ -135,7 +135,7 @@ The only parameter of the function is a table describing the message.
|
||||
<tr><td><tt>
|
||||
mesgt = {<br>
|
||||
headers = <i>header-table</i>,<br>
|
||||
body = <i>LTN12 source</i> or <i>string</i> or
|
||||
body = <i>LTN12 source</i> or <i>string</i> or
|
||||
<i>multipart-mesgt</i><br>
|
||||
}<br>
|
||||
<br>
|
||||
@ -151,36 +151,36 @@ multipart-mesgt = {<br>
|
||||
</table>
|
||||
</blockquote>
|
||||
|
||||
<p class=parameters>
|
||||
<p class="parameters">
|
||||
For a simple message, all that is needed is a set of <tt>headers</tt>
|
||||
and the <tt>body</tt>. The message <tt>body</tt> can be given as a string
|
||||
or as a <em>simple</em>
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
||||
or as a <em>simple</em>
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
||||
source. For multipart messages, the body is a table that
|
||||
recursively defines each part as an independent message, plus an optional
|
||||
<tt>preamble</tt> and <tt>epilogue</tt>.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
The function returns a <em>simple</em>
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
||||
<p class="return">
|
||||
The function returns a <em>simple</em>
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
||||
source that produces the
|
||||
message contents as defined by <tt>mesgt</tt>, chunk by chunk.
|
||||
message contents as defined by <tt>mesgt</tt>, chunk by chunk.
|
||||
Hopefully, the following
|
||||
example will make things clear. When in doubt, refer to the appropriate RFC
|
||||
as listed in the introduction. </p>
|
||||
|
||||
<pre class=example>
|
||||
<pre class="example">
|
||||
-- load the smtp support and its friends
|
||||
local smtp = require("socket.smtp")
|
||||
local mime = require("mime")
|
||||
local ltn12 = require("ltn12")
|
||||
|
||||
-- creates a source to send a message with two parts. The first part is
|
||||
-- creates a source to send a message with two parts. The first part is
|
||||
-- plain text, the second part is a PNG image, encoded as base64.
|
||||
source = smtp.message{
|
||||
headers = {
|
||||
-- Remember that headers are *ignored* by smtp.send.
|
||||
-- Remember that headers are *ignored* by smtp.send.
|
||||
from = "Sicrano de Oliveira <sicrano@example.com>",
|
||||
to = "Fulano da Silva <fulano@example.com>",
|
||||
subject = "Here is a message with attachments"
|
||||
@ -191,20 +191,20 @@ source = smtp.message{
|
||||
"Preamble will probably appear even in a MIME enabled client.",
|
||||
-- first part: no headers means plain text, us-ascii.
|
||||
-- The mime.eol low-level filter normalizes end-of-line markers.
|
||||
[1] = {
|
||||
[1] = {
|
||||
body = mime.eol(0, [[
|
||||
Lines in a message body should always end with CRLF.
|
||||
The smtp module will *NOT* perform translation. However, the
|
||||
Lines in a message body should always end with CRLF.
|
||||
The smtp module will *NOT* perform translation. However, the
|
||||
send function *DOES* perform SMTP stuffing, whereas the message
|
||||
function does *NOT*.
|
||||
]])
|
||||
},
|
||||
-- second part: headers describe content to be a png image,
|
||||
-- second part: headers describe content to be a png image,
|
||||
-- sent under the base64 transfer content encoding.
|
||||
-- notice that nothing happens until the message is actually sent.
|
||||
-- small chunks are loaded into memory right before transmission and
|
||||
-- notice that nothing happens until the message is actually sent.
|
||||
-- small chunks are loaded into memory right before transmission and
|
||||
-- translation happens on the fly.
|
||||
[2] = {
|
||||
[2] = {
|
||||
headers = {
|
||||
["content-type"] = 'image/png; name="image.png"',
|
||||
["content-disposition"] = 'attachment; filename="image.png"',
|
||||
@ -234,7 +234,7 @@ r, e = smtp.send{
|
||||
|
||||
<!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id=send>
|
||||
<p class="name" id="send">
|
||||
smtp.<b>send{</b><br>
|
||||
from = <i>string</i>,<br>
|
||||
rcpt = <i>string</i> or <i>string-table</i>,<br>
|
||||
@ -249,53 +249,53 @@ smtp.<b>send{</b><br>
|
||||
<b>}</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Sends a message to a recipient list. Since sending messages is not as
|
||||
simple as downloading an URL from a FTP or HTTP server, this function
|
||||
doesn't have a simple interface. However, see the
|
||||
<a href=#message><tt>message</tt></a> source factory for
|
||||
simple as downloading an URL from a FTP or HTTP server, this function
|
||||
doesn't have a simple interface. However, see the
|
||||
<a href="#message"><tt>message</tt></a> source factory for
|
||||
a very powerful way to define the message contents.
|
||||
</p>
|
||||
|
||||
|
||||
<p class=parameters>
|
||||
The sender is given by the e-mail address in the <tt>from</tt> field.
|
||||
<p class="parameters">
|
||||
The sender is given by the e-mail address in the <tt>from</tt> field.
|
||||
<tt>Rcpt</tt> is a Lua table with one entry for each recipient e-mail
|
||||
address, or a string
|
||||
in case there is just one recipient.
|
||||
The contents of the message are given by a <em>simple</em>
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
||||
in case there is just one recipient.
|
||||
The contents of the message are given by a <em>simple</em>
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
||||
<tt>source</tt>. Several arguments are optional:
|
||||
</p>
|
||||
<ul>
|
||||
<li> <tt>user</tt>, <tt>password</tt>: User and password for
|
||||
authentication. The function will attempt LOGIN and PLAIN authentication
|
||||
methods if supported by the server (both are unsafe);
|
||||
<li> <tt>server</tt>: Server to connect to. Defaults to "localhost";
|
||||
<li> <tt>port</tt>: Port to connect to. Defaults to 25;
|
||||
methods if supported by the server (both are unsafe);</li>
|
||||
<li> <tt>server</tt>: Server to connect to. Defaults to "localhost";</li>
|
||||
<li> <tt>port</tt>: Port to connect to. Defaults to 25;</li>
|
||||
<li> <tt>domain</tt>: Domain name used to greet the server; Defaults to the
|
||||
local machine host name;
|
||||
<li> <tt>step</tt>:
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
||||
local machine host name;</li>
|
||||
<li> <tt>step</tt>:
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
||||
pump step function used to pass data from the
|
||||
source to the server. Defaults to the LTN12 <tt>pump.step</tt> function;
|
||||
source to the server. Defaults to the LTN12 <tt>pump.step</tt> function;</li>
|
||||
<li><tt>create</tt>: An optional function to be used instead of
|
||||
<a href=tcp.html#socket.tcp><tt>socket.tcp</tt></a> when the communications socket is created.
|
||||
<a href="tcp.html#socket.tcp"><tt>socket.tcp</tt></a> when the communications socket is created.</li>
|
||||
</ul>
|
||||
|
||||
<p class=return>
|
||||
<p class="return">
|
||||
If successful, the function returns 1. Otherwise, the function returns
|
||||
<b><tt>nil</tt></b> followed by an error message.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
Note: SMTP servers can be very picky with the format of e-mail
|
||||
addresses. To be safe, use only addresses of the form
|
||||
"<tt><fulano@example.com></tt>" in the <tt>from</tt> and
|
||||
<tt>rcpt</tt> arguments to the <tt>send</tt> function. In headers, e-mail
|
||||
addresses can take whatever form you like. </p>
|
||||
|
||||
<p class=note>
|
||||
<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
|
||||
@ -303,68 +303,69 @@ and, more importantly, the '<tt>Bcc</tt>' headers. Do <em>not</em> add a
|
||||
exact opposite of what you expect.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
Only recipients specified in the <tt>rcpt</tt> 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
|
||||
<em>are</em> part of the message and should be produced by the
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
||||
<em>are</em> part of the message and should be produced by the
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
||||
<tt>source</tt> function. The <tt>rcpt</tt> list is <em>not</em>
|
||||
part of the message and will not be sent to anyone.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
<a href="http://www.ietf.org/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:
|
||||
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;
|
||||
of the message;</li>
|
||||
<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;
|
||||
content of the message may not be directed at them;</li>
|
||||
<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>
|
||||
Copy") contains addresses of recipients of the message whose addresses are not
|
||||
to be revealed to other recipients of the message.</li>
|
||||
</ul>
|
||||
|
||||
<p class=note>
|
||||
The LuaSocket <tt>send</tt> function does not care or interpret the
|
||||
headers you send, but it gives you full control over what is sent and
|
||||
<p class="note">
|
||||
The LuaSocket <tt>send</tt> function does not care or interpret the
|
||||
headers you send, 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
|
||||
gets a copy of the message;</li>
|
||||
<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;
|
||||
similar to the <tt>Bcc</tt> field of popular e-mail clients;</li>
|
||||
<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
|
||||
recipients so that other recipients can see it;</li>
|
||||
<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>
|
||||
<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!
|
||||
exactly what you <em>don't</em> want to happen!</li>
|
||||
</ul>
|
||||
|
||||
<p class=note>
|
||||
I hope this clarifies the issue. Otherwise, please refer to
|
||||
<p class="note">
|
||||
I hope this clarifies the issue. Otherwise, please refer to
|
||||
<a href="http://www.ietf.org/rfc/rfc2821.txt">RFC 2821</a>
|
||||
and
|
||||
<a href="http://www.ietf.org/rfc/rfc2822.txt">RFC 2822</a>.
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
<pre class="example">
|
||||
-- load the smtp support
|
||||
local smtp = require("socket.smtp")
|
||||
|
||||
-- Connects to server "localhost" and sends a message to users
|
||||
-- "fulano@example.com", "beltrano@example.com",
|
||||
-- "fulano@example.com", "beltrano@example.com",
|
||||
-- and "sicrano@example.com".
|
||||
-- Note that "fulano" is the primary recipient, "beltrano" receives a
|
||||
-- carbon copy and neither of them knows that "sicrano" received a blind
|
||||
@ -388,17 +389,17 @@ mesgt = {
|
||||
|
||||
r, e = smtp.send{
|
||||
from = from,
|
||||
rcpt = rcpt,
|
||||
rcpt = rcpt,
|
||||
source = smtp.message(mesgt)
|
||||
}
|
||||
</pre>
|
||||
|
||||
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<div class=footer>
|
||||
<div class="footer">
|
||||
<hr>
|
||||
<center>
|
||||
<p class=bar>
|
||||
<p class="bar">
|
||||
<a href="index.html">home</a> ·
|
||||
<a href="index.html#down">download</a> ·
|
||||
<a href="installation.html">installation</a> ·
|
@ -1,10 +1,10 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
||||
"http://www.w3.org/TR/html4/strict.dtd">
|
||||
<html>
|
||||
|
||||
<head>
|
||||
<meta name="description" content="LuaSocket: The core namespace">
|
||||
<meta name="keywords" content="Lua, LuaSocket, Socket, Network, Library, Support">
|
||||
<meta name="keywords" content="Lua, LuaSocket, Socket, Network, Library, Support">
|
||||
<title>LuaSocket: The socket namespace</title>
|
||||
<link rel="stylesheet" href="reference.css" type="text/css">
|
||||
</head>
|
||||
@ -13,22 +13,22 @@
|
||||
|
||||
<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<div class=header>
|
||||
<div class="header">
|
||||
<hr>
|
||||
<center>
|
||||
<table summary="LuaSocket logo">
|
||||
<tr><td align=center><a href="http://www.lua.org">
|
||||
<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png">
|
||||
<tr><td align="center"><a href="https://www.lua.org">
|
||||
<img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
|
||||
</a></td></tr>
|
||||
<tr><td align=center valign=top>Network support for the Lua language
|
||||
<tr><td align="center" valign="top">Network support for the Lua language
|
||||
</td></tr>
|
||||
</table>
|
||||
<p class=bar>
|
||||
<p class="bar">
|
||||
<a href="index.html">home</a> ·
|
||||
<a href="index.html#download">download</a> ·
|
||||
<a href="installation.html">installation</a> ·
|
||||
<a href="introduction.html">introduction</a> ·
|
||||
<a href="reference.html">reference</a>
|
||||
<a href="reference.html">reference</a>
|
||||
</p>
|
||||
</center>
|
||||
<hr>
|
||||
@ -36,71 +36,71 @@
|
||||
|
||||
<!-- socket +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<h2 id=socket>The socket namespace</h2>
|
||||
<h2 id="socket">The socket namespace</h2>
|
||||
|
||||
<p>
|
||||
The <tt>socket</tt> namespace contains the core functionality of LuaSocket.
|
||||
The <tt>socket</tt> namespace contains the core functionality of LuaSocket.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<p>
|
||||
To obtain the <tt>socket</tt> namespace, run:
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
-- loads the socket module
|
||||
<pre class="example">
|
||||
-- loads the socket module
|
||||
local socket = require("socket")
|
||||
</pre>
|
||||
|
||||
<!-- headers.canonic ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="headers.canonic">
|
||||
<p class="name" id="headers.canonic">
|
||||
socket.headers.<b>canonic</b></p>
|
||||
|
||||
<p> The <tt>socket.headers.canonic</tt> table
|
||||
is used by the HTTP and SMTP modules to translate from
|
||||
lowercase field names back into their canonic
|
||||
<p> The <tt>socket.headers.canonic</tt> table
|
||||
is used by the HTTP and SMTP modules to translate from
|
||||
lowercase field names back into their canonic
|
||||
capitalization. When a lowercase field name exists as a key
|
||||
in this table, the associated value is substituted in
|
||||
whenever the field name is sent out.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<p>
|
||||
You can obtain the <tt>headers</tt> namespace if case run-time
|
||||
modifications are required by running:
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
-- loads the headers module
|
||||
<pre class="example">
|
||||
-- loads the headers module
|
||||
local headers = require("headers")
|
||||
</pre>
|
||||
|
||||
|
||||
<!-- bind ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id=bind>
|
||||
<p class="name" id="bind">
|
||||
socket.<b>bind(</b>address, port [, backlog]<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
This function is a shortcut that creates and returns a TCP server object
|
||||
bound to a local <tt>address</tt> and <tt>port</tt>, ready to
|
||||
bound to a local <tt>address</tt> and <tt>port</tt>, ready to
|
||||
accept client connections. Optionally,
|
||||
user can also specify the <tt>backlog</tt> argument to the
|
||||
<a href=tcp.html#listen><tt>listen</tt></a> method (defaults to 32).
|
||||
user can also specify the <tt>backlog</tt> argument to the
|
||||
<a href="tcp.html#listen"><tt>listen</tt></a> method (defaults to 32).
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
Note: The server object returned will have the option "<tt>reuseaddr</tt>"
|
||||
<p class="note">
|
||||
Note: The server object returned will have the option "<tt>reuseaddr</tt>"
|
||||
set to <tt><b>true</b></tt>.
|
||||
</p>
|
||||
|
||||
<!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id=connect>
|
||||
<p class="name" id="connect">
|
||||
socket.<b>connect[46](</b>address, port [, locaddr] [, locport] [, family]<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
This function is a shortcut that creates and returns a TCP client object
|
||||
connected to a remote <tt>address</tt> at a given <tt>port</tt>. Optionally,
|
||||
the user can also specify the local address and port to bind
|
||||
@ -114,40 +114,40 @@ of connect are defined as simple helper functions that restrict the
|
||||
|
||||
<!-- debug ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id=debug>
|
||||
<p class="name" id="debug">
|
||||
socket.<b>_DEBUG</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
This constant is set to <tt><b>true</b></tt> if the library was compiled
|
||||
with debug support.
|
||||
</p>
|
||||
|
||||
<!-- datagramsize +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id=debug>
|
||||
<p class="name" id="datagramsize">
|
||||
socket.<b>_DATAGRAMSIZE</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Default datagram size used by calls to
|
||||
<a href="udp.html#receive"<tt>receive</tt></a> and
|
||||
<a href="udp.html#receive"><tt>receive</tt></a> and
|
||||
<a href="udp.html#receivefrom"><tt>receivefrom</tt></a>.
|
||||
(Unless changed in compile time, the value is 8192.)
|
||||
</p>
|
||||
|
||||
<!-- get time +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id=gettime>
|
||||
<p class="name" id="gettime">
|
||||
socket.<b>gettime()</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Returns the UNIX time in seconds. You should subtract the values returned by this function
|
||||
to get meaningful values.
|
||||
to get meaningful values.
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
<pre class="example">
|
||||
t = socket.gettime()
|
||||
-- do stuff
|
||||
print(socket.gettime() - t .. " seconds elapsed")
|
||||
@ -155,38 +155,38 @@ print(socket.gettime() - t .. " seconds elapsed")
|
||||
|
||||
<!-- newtry +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id=newtry>
|
||||
<p class="name" id="newtry">
|
||||
socket.<b>newtry(</b>finalizer<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
Creates and returns a <em>clean</em>
|
||||
<p class="description">
|
||||
Creates and returns a <em>clean</em>
|
||||
<a href="#try"><tt>try</tt></a>
|
||||
function that allows for cleanup before the exception
|
||||
is raised.
|
||||
function that allows for cleanup before the exception
|
||||
is raised.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<p class="parameters">
|
||||
<tt>Finalizer</tt> is a function that will be called before
|
||||
<tt>try</tt> throws the exception.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
The function returns your customized <tt>try</tt> function.
|
||||
<p class="return">
|
||||
The function returns your customized <tt>try</tt> function.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
Note: This idea saved a <em>lot</em> of work with the
|
||||
implementation of protocols in LuaSocket:
|
||||
<p class="note">
|
||||
Note: This idea saved a <em>lot</em> of work with the
|
||||
implementation of protocols in LuaSocket:
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
<pre class="example">
|
||||
foo = socket.protect(function()
|
||||
-- connect somewhere
|
||||
local c = socket.try(socket.connect("somewhere", 42))
|
||||
-- create a try function that closes 'c' on error
|
||||
local try = socket.newtry(function() c:close() end)
|
||||
-- do everything reassured c will be closed
|
||||
-- do everything reassured c will be closed
|
||||
try(c:send("hello there?\r\n"))
|
||||
local answer = try(c:receive())
|
||||
...
|
||||
@ -198,40 +198,40 @@ end)
|
||||
|
||||
<!-- protect +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id=protect>
|
||||
<p class="name" id="protect">
|
||||
socket.<b>protect(</b>func<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Converts a function that throws exceptions into a safe function. This
|
||||
function only catches exceptions thrown by the <a href=#try><tt>try</tt></a>
|
||||
and <a href=#newtry><tt>newtry</tt></a> functions. It does not catch normal
|
||||
function only catches exceptions thrown by the <a href="#try"><tt>try</tt></a>
|
||||
and <a href="#newtry"><tt>newtry</tt></a> functions. It does not catch normal
|
||||
Lua errors.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<tt>Func</tt> is a function that calls
|
||||
<a href=#try><tt>try</tt></a> (or <tt>assert</tt>, or <tt>error</tt>)
|
||||
to throw exceptions.
|
||||
<p class="parameters">
|
||||
<tt>Func</tt> is a function that calls
|
||||
<a href="#try"><tt>try</tt></a> (or <tt>assert</tt>, or <tt>error</tt>)
|
||||
to throw exceptions.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
<p class="return">
|
||||
Returns an equivalent function that instead of throwing exceptions in case of
|
||||
a failed <a href=#try><tt>try</tt></a> call, returns <tt><b>nil</b></tt>
|
||||
a failed <a href="#try"><tt>try</tt></a> call, returns <tt><b>nil</b></tt>
|
||||
followed by an error message.
|
||||
</p>
|
||||
|
||||
<!-- select +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id=select>
|
||||
<p class="name" id="select">
|
||||
socket.<b>select(</b>recvt, sendt [, timeout]<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
Waits for a number of sockets to change status.
|
||||
<p class="description">
|
||||
Waits for a number of sockets to change status.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<p class="parameters">
|
||||
<tt>Recvt</tt> is an array with the sockets to test for characters
|
||||
available for reading. Sockets in the <tt>sendt</tt> array are watched to
|
||||
see if it is OK to immediately write on them. <tt>Timeout</tt> is the
|
||||
@ -242,7 +242,7 @@ be empty tables or <tt><b>nil</b></tt>. Non-socket values (or values with
|
||||
non-numeric indices) in the arrays will be silently ignored.
|
||||
</p>
|
||||
|
||||
<p class=return> The function returns a list with the sockets ready for
|
||||
<p class="return"> The function returns a list with the sockets ready for
|
||||
reading, a list with the sockets ready for writing and an error message.
|
||||
The error message is "<tt>timeout</tt>" if a timeout
|
||||
condition was met, "<tt>select failed</tt>" if the call
|
||||
@ -250,216 +250,218 @@ to <tt>select</tt> failed, and
|
||||
<tt><b>nil</b></tt> otherwise. The returned tables are
|
||||
doubly keyed both by integers and also by the sockets
|
||||
themselves, to simplify the test if a specific socket has
|
||||
changed status.
|
||||
changed status.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
<b>Note:</b> <tt>select</tt> can monitor a limited number
|
||||
of sockets, as defined by the constant <tt>socket._SETSIZE</tt>. This
|
||||
of sockets, as defined by the constant <a href="#setsize">
|
||||
<tt>socket._SETSIZE</tt></a>. This
|
||||
number may be as high as 1024 or as low as 64 by default,
|
||||
depending on the system. It is usually possible to change this
|
||||
at compile time. Invoking <tt>select</tt> with a larger
|
||||
number of sockets will raise an error.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<b>Important note</b>: a known bug in WinSock causes <tt>select</tt> to fail
|
||||
<p class="note">
|
||||
<b>Important note</b>: a known bug in WinSock causes <tt>select</tt> to fail
|
||||
on non-blocking TCP sockets. The function may return a socket as
|
||||
writable even though the socket is <em>not</em> ready for sending.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
<b>Another important note</b>: calling select with a server socket in the receive parameter before a call to accept does <em>not</em> guarantee
|
||||
<a href=tcp.html#accept><tt>accept</tt></a> will return immediately.
|
||||
Use the <a href=tcp.html#settimeout><tt>settimeout</tt></a>
|
||||
method or <tt>accept</tt> might block forever.
|
||||
<a href="tcp.html#accept"><tt>accept</tt></a> will return immediately.
|
||||
Use the <a href="tcp.html#settimeout"><tt>settimeout</tt></a>
|
||||
method or <tt>accept</tt> might block forever.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
<b>Yet another note</b>: If you close a socket and pass
|
||||
it to <tt>select</tt>, it will be ignored.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
<b>Using select with non-socket objects</b>: Any object that implements <tt>getfd</tt> and <tt>dirty</tt> can be used with <tt>select</tt>, allowing objects from other libraries to be used within a <tt>socket.select</tt> driven loop.
|
||||
</p>
|
||||
|
||||
<!-- setsize ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id=setsize>
|
||||
<p class="name" id="setsize">
|
||||
socket.<b>_SETSIZE</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
The maximum number of sockets that the <a
|
||||
href=#select><tt>select</tt></a> function can handle.
|
||||
href="#select"><tt>select</tt></a> function can handle.
|
||||
</p>
|
||||
|
||||
|
||||
<!-- sink ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id=sink>
|
||||
<p class="name" id="sink">
|
||||
socket.<b>sink(</b>mode, socket<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
Creates an
|
||||
<p class="description">
|
||||
Creates an
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
||||
sink from a stream socket object.
|
||||
sink from a stream socket object.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<p class="parameters">
|
||||
<tt>Mode</tt> defines the behavior of the sink. The following
|
||||
options are available:
|
||||
</p>
|
||||
<ul>
|
||||
<li> <tt>"http-chunked"</tt>: sends data through socket after applying the
|
||||
<em>chunked transfer coding</em>, closing the socket when done;
|
||||
<em>chunked transfer coding</em>, closing the socket when done;</li>
|
||||
<li> <tt>"close-when-done"</tt>: sends all received data through the
|
||||
socket, closing the socket when done;
|
||||
socket, closing the socket when done;</li>
|
||||
<li> <tt>"keep-open"</tt>: sends all received data through the
|
||||
socket, leaving it open when done.
|
||||
socket, leaving it open when done.</li>
|
||||
</ul>
|
||||
<p>
|
||||
<tt>Socket</tt> is the stream socket object used to send the data.
|
||||
<tt>Socket</tt> is the stream socket object used to send the data.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
The function returns a sink with the appropriate behavior.
|
||||
<p class="return">
|
||||
The function returns a sink with the appropriate behavior.
|
||||
</p>
|
||||
|
||||
<!-- skip ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id=skip>
|
||||
<p class="name" id="skip">
|
||||
socket.<b>skip(</b>d [, ret<sub>1</sub>, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Drops a number of arguments and returns the remaining.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<p class="parameters">
|
||||
<tt>D</tt> is the number of arguments to drop. <tt>Ret<sub>1</sub></tt> to
|
||||
<tt>ret<sub>N</sub></tt> are the arguments.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
<p class="return">
|
||||
The function returns <tt>ret<sub>d+1</sub></tt> to <tt>ret<sub>N</sub></tt>.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
Note: This function is useful to avoid creation of dummy variables:
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
-- get the status code and separator from SMTP server reply
|
||||
<pre class="example">
|
||||
-- get the status code and separator from SMTP server reply
|
||||
local code, sep = socket.skip(2, string.find(line, "^(%d%d%d)(.?)"))
|
||||
</pre>
|
||||
|
||||
<!-- sleep ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id=sleep>
|
||||
<p class="name" id="sleep">
|
||||
socket.<b>sleep(</b>time<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Freezes the program execution during a given amount of time.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<p class="parameters">
|
||||
<tt>Time</tt> is the number of seconds to sleep for. If
|
||||
<tt>time</tt> is negative, the function returns immediately.
|
||||
</p>
|
||||
|
||||
<!-- source +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id=source>
|
||||
<p class="name" id="source">
|
||||
socket.<b>source(</b>mode, socket [, length]<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
Creates an
|
||||
<p class="description">
|
||||
Creates an
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
||||
source from a stream socket object.
|
||||
source from a stream socket object.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<p class="parameters">
|
||||
<tt>Mode</tt> defines the behavior of the source. The following
|
||||
options are available:
|
||||
</p>
|
||||
<ul>
|
||||
<li> <tt>"http-chunked"</tt>: receives data from socket and removes the
|
||||
<em>chunked transfer coding</em> before returning the data;
|
||||
<em>chunked transfer coding</em> before returning the data;</li>
|
||||
<li> <tt>"by-length"</tt>: receives a fixed number of bytes from the
|
||||
socket. This mode requires the extra argument <tt>length</tt>;
|
||||
socket. This mode requires the extra argument <tt>length</tt>;</li>
|
||||
<li> <tt>"until-closed"</tt>: receives data from a socket until the other
|
||||
side closes the connection.
|
||||
side closes the connection.</li>
|
||||
</ul>
|
||||
<p>
|
||||
<tt>Socket</tt> is the stream socket object used to receive the data.
|
||||
<tt>Socket</tt> is the stream socket object used to receive the data.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
The function returns a source with the appropriate behavior.
|
||||
<p class="return">
|
||||
The function returns a source with the appropriate behavior.
|
||||
</p>
|
||||
|
||||
<!-- socketinvalid ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id=socketinvalid>
|
||||
<p class="name" id="socketinvalid">
|
||||
socket.<b>_SOCKETINVALID</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
The OS value for an invalid socket.
|
||||
<p class="description">
|
||||
The OS value for an invalid socket. This can be used with <a href="tcp.html#getfd">
|
||||
<tt>tcp:getfd</tt></a> and <a href="tcp.html#setfd"><tt>tcp:setfd</tt></a> methods.
|
||||
</p>
|
||||
|
||||
<!-- try ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id=try>
|
||||
<p class="name" id="try">
|
||||
socket.<b>try(</b>ret<sub>1</sub> [, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Throws an exception in case <tt>ret<sub>1</sub></tt> is falsy, using
|
||||
<tt>ret<sub>2</sub></tt> as the error message. The exception is supposed to be caught
|
||||
by a <a href=#protect><tt>protect</tt></a>ed function only.
|
||||
<tt>ret<sub>2</sub></tt> as the error message. The exception is supposed to be caught
|
||||
by a <a href="#protect"><tt>protect</tt></a>ed function only.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<p class="parameters">
|
||||
<tt>Ret<sub>1</sub></tt> to <tt>ret<sub>N</sub></tt> can be arbitrary
|
||||
arguments, but are usually the return values of a function call
|
||||
nested with <tt>try</tt>.
|
||||
arguments, but are usually the return values of a function call
|
||||
nested with <tt>try</tt>.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
<p class="return">
|
||||
The function returns <tt>ret</tt><sub>1</sub> to <tt>ret</tt><sub>N</sub> if
|
||||
<tt>ret</tt><sub>1</sub> is not <tt><b>nil</b></tt> or <tt><b>false</b></tt>.
|
||||
Otherwise, it calls <tt>error</tt> passing <tt>ret</tt><sub>2</sub> wrapped
|
||||
in a table with metatable used by <a href=#protect><tt>protect</tt></a> to
|
||||
in a table with metatable used by <a href="#protect"><tt>protect</tt></a> to
|
||||
distinguish exceptions from runtime errors.
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
<pre class="example">
|
||||
-- connects or throws an exception with the appropriate error message
|
||||
c = socket.try(socket.connect("localhost", 80))
|
||||
</pre>
|
||||
|
||||
<!-- version ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id=version>
|
||||
<p class="name" id="version">
|
||||
socket.<b>_VERSION</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
This constant has a string describing the current LuaSocket version.
|
||||
<p class="description">
|
||||
This constant has a string describing the current LuaSocket version.
|
||||
</p>
|
||||
|
||||
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<div class=footer>
|
||||
<div class="footer">
|
||||
<hr>
|
||||
<center>
|
||||
<p class=bar>
|
||||
<p class="bar">
|
||||
<a href="index.html">home</a> ·
|
||||
<a href="index.html#down">download</a> ·
|
||||
<a href="installation.html">installation</a> ·
|
@ -13,17 +13,17 @@
|
||||
|
||||
<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<div class=header>
|
||||
<div class="header">
|
||||
<hr>
|
||||
<center>
|
||||
<table summary="LuaSocket logo">
|
||||
<tr><td align=center><a href="http://www.lua.org">
|
||||
<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png">
|
||||
<tr><td align="center"><a href="http://www.lua.org">
|
||||
<img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
|
||||
</a></td></tr>
|
||||
<tr><td align=center valign=top>Network support for the Lua language
|
||||
<tr><td align="center" valign="top">Network support for the Lua language
|
||||
</td></tr>
|
||||
</table>
|
||||
<p class=bar>
|
||||
<p class="bar">
|
||||
<a href="index.html">home</a> ·
|
||||
<a href="index.html#download">download</a> ·
|
||||
<a href="installation.html">installation</a> ·
|
||||
@ -40,42 +40,43 @@
|
||||
|
||||
<!-- accept +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="accept">
|
||||
<p class="name" id="accept">
|
||||
server:<b>accept()</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Waits for a remote connection on the server
|
||||
object and returns a client object representing that connection.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
<p class="return">
|
||||
If a connection is successfully initiated, a client object is returned.
|
||||
If a timeout condition is met, the method returns <b><tt>nil</tt></b>
|
||||
followed by the error string '<tt>timeout</tt>'. Other errors are
|
||||
reported by <b><tt>nil</tt></b> followed by a message describing the error.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
Note: calling <a href=socket.html#select><tt>socket.select</tt></a>
|
||||
<p class="note">
|
||||
Note: calling <a href="socket.html#select"><tt>socket.select</tt></a>
|
||||
with a server object in
|
||||
the <tt>recvt</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>
|
||||
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">
|
||||
<p class="name" id="bind">
|
||||
master:<b>bind(</b>address, port<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Binds a master object to <tt>address</tt> and <tt>port</tt> on the
|
||||
local host.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<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>
|
||||
@ -86,25 +87,25 @@ If <tt>port</tt> is 0, the system automatically
|
||||
chooses an ephemeral port.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
<p class="return">
|
||||
In case of success, the method returns 1. In case of error, the
|
||||
method returns <b><tt>nil</tt></b> followed by an error message.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
Note: The function <a href=socket.html#bind><tt>socket.bind</tt></a>
|
||||
<p class="note">
|
||||
Note: The function <a href="socket.html#bind"><tt>socket.bind</tt></a>
|
||||
is available and is a shortcut for the creation of server sockets.
|
||||
</p>
|
||||
|
||||
<!-- close ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="close">
|
||||
<p class="name" id="close">
|
||||
master:<b>close()</b><br>
|
||||
client:<b>close()</b><br>
|
||||
server:<b>close()</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<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
|
||||
@ -112,7 +113,7 @@ bound is made available to other applications. No further operations
|
||||
a closed socket.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<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
|
||||
@ -121,53 +122,53 @@ automatically closed before destruction, though.
|
||||
|
||||
<!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="connect">
|
||||
<p class="name" id="connect">
|
||||
master:<b>connect(</b>address, port<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<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>.
|
||||
<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>
|
||||
<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>
|
||||
<p class="return">
|
||||
In case of error, the method returns <b><tt>nil</tt></b> followed by a string
|
||||
describing the error. In case of success, the method returns 1.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
Note: The function <a href=socket.html#connect><tt>socket.connect</tt></a>
|
||||
<p class="note">
|
||||
Note: The function <a href="socket.html#connect"><tt>socket.connect</tt></a>
|
||||
is available and is a shortcut for the creation of client sockets.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
Note: Starting with LuaSocket 2.0,
|
||||
the <a href=#settimeout><tt>settimeout</tt></a>
|
||||
the <a href="#settimeout"><tt>settimeout</tt></a>
|
||||
method affects the behavior of <tt>connect</tt>, causing it to return
|
||||
with an error in case of a timeout. If that happens, you can still call <a
|
||||
href=socket.html#select><tt>socket.select</tt></a> with the socket in the
|
||||
href="socket.html#select"><tt>socket.select</tt></a> with the socket in the
|
||||
<tt>sendt</tt> table. The socket will be writable when the connection is
|
||||
established.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
Note: Starting with LuaSocket 3.0, the host name resolution
|
||||
depends on whether the socket was created by
|
||||
<a href=#socket.tcp><tt>socket.tcp</tt></a>,
|
||||
<a href=#socket.tcp4><tt>socket.tcp4</tt></a> or
|
||||
<a href=#socket.tcp6><tt>socket.tcp6</tt></a>. Addresses from
|
||||
<a href="#socket.tcp"><tt>socket.tcp</tt></a>,
|
||||
<a href="#socket.tcp4"><tt>socket.tcp4</tt></a> or
|
||||
<a href="#socket.tcp6"><tt>socket.tcp6</tt></a>. Addresses from
|
||||
the appropriate family (or both) are tried in the order
|
||||
returned by the resolver until the
|
||||
first success or until the last failure. If the timeout was
|
||||
@ -176,42 +177,44 @@ set to zero, only the first address is tried.
|
||||
|
||||
<!-- dirty +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="dirty">
|
||||
<p class="name" id="dirty">
|
||||
master:<b>dirty()</b><br>
|
||||
client:<b>dirty()</b><br>
|
||||
server:<b>dirty()</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Check the read buffer status.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
<p class="return">
|
||||
Returns <tt>true</tt> if there is any data in the read buffer, <tt>false</tt> otherwise.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
Note: <b>This is an internal method, use at your own risk.</b>
|
||||
</p>
|
||||
|
||||
|
||||
<!-- getfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="getfd">
|
||||
<p class="name" id="getfd">
|
||||
master:<b>getfd()</b><br>
|
||||
client:<b>getfd()</b><br>
|
||||
server:<b>getfd()</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Returns the underling socket descriptor or handle associated to the object.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
The descriptor or handle. In case the object has been closed, the return will be -1.
|
||||
<p class="return">
|
||||
The descriptor or handle. In case the object has been closed, the return value
|
||||
will be -1. For an invalid socket it will be <a href="socket.html#socketinvalid">
|
||||
<tt>_SOCKETINVALID</tt></a>.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
Note: <b>This is an internal method. Unlikely to be
|
||||
portable. Use at your own risk. </b>
|
||||
</p>
|
||||
@ -219,28 +222,27 @@ portable. Use at your own risk. </b>
|
||||
|
||||
<!-- getoption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="getoption">
|
||||
client:<b>getoption(</b>option)</b><br>
|
||||
server:<b>getoption(</b>option)</b>
|
||||
<p class="name" id="getoption">
|
||||
client:<b>getoption(option)</b><br>
|
||||
server:<b>getoption(option)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Gets options for the TCP object.
|
||||
See <a href=#setoption><tt>setoption</tt></a> for description of the
|
||||
See <a href="#setoption"><tt>setoption</tt></a> for description of the
|
||||
option names and values.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<tt>Option</tt> is a string with the option name.
|
||||
<p class="parameters">
|
||||
<tt>Option</tt> is a string with the option name.</p>
|
||||
<ul>
|
||||
|
||||
<li> '<tt>keepalive</tt>'
|
||||
<li> '<tt>linger</tt>'
|
||||
<li> '<tt>reuseaddr</tt>'
|
||||
<li> '<tt>tcp-nodelay</tt>'
|
||||
<li> '<tt>keepalive</tt>'</li>
|
||||
<li> '<tt>linger</tt>'</li>
|
||||
<li> '<tt>reuseaddr</tt>'</li>
|
||||
<li> '<tt>tcp-nodelay</tt>'</li>
|
||||
</ul>
|
||||
|
||||
<p class=return>
|
||||
<p class="return">
|
||||
The method returns the option <tt>value</tt> in case of success, or
|
||||
<b><tt>nil</tt></b> followed by an error message otherwise.
|
||||
</p>
|
||||
@ -248,38 +250,38 @@ The method returns the option <tt>value</tt> in case of success, or
|
||||
|
||||
<!-- getpeername ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="getpeername">
|
||||
<p class="name" id="getpeername">
|
||||
client:<b>getpeername()</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Returns information about the remote side of a connected client object.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
<p class="return">
|
||||
Returns a string with the IP address of the peer, the
|
||||
port number that peer is using for the connection,
|
||||
and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>").
|
||||
In case of error, the method returns <b><tt>nil</tt></b>.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
Note: It makes no sense to call this method on server objects.
|
||||
</p>
|
||||
|
||||
<!-- getsockname ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="getsockname">
|
||||
<p class="name" id="getsockname">
|
||||
master:<b>getsockname()</b><br>
|
||||
client:<b>getsockname()</b><br>
|
||||
server:<b>getsockname()</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Returns the local address information associated to the object.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
<p class="return">
|
||||
The method returns a string with local IP address, a number with
|
||||
the local port,
|
||||
and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>").
|
||||
@ -288,31 +290,31 @@ In case of error, the method returns <b><tt>nil</tt></b>.
|
||||
|
||||
<!-- getstats +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="getstats">
|
||||
<p class="name" id="getstats">
|
||||
master:<b>getstats()</b><br>
|
||||
client:<b>getstats()</b><br>
|
||||
server:<b>getstats()</b><br>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Returns accounting information on the socket, useful for throttling
|
||||
of bandwidth.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
<p class="return">
|
||||
The method returns the number of bytes received, the number of bytes sent,
|
||||
and the age of the socket object in seconds.
|
||||
</p>
|
||||
|
||||
<!-- gettimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="gettimeout">
|
||||
<p class="name" id="gettimeout">
|
||||
master:<b>gettimeout()</b><br>
|
||||
client:<b>gettimeout()</b><br>
|
||||
server:<b>gettimeout()</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Returns the current block timeout followed by the curent
|
||||
total timeout.
|
||||
</p>
|
||||
@ -320,65 +322,65 @@ total timeout.
|
||||
|
||||
<!-- listen ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="listen">
|
||||
<p class="name" id="listen">
|
||||
master:<b>listen(</b>backlog<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Specifies the socket is willing to receive connections, transforming the
|
||||
object 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.
|
||||
<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>
|
||||
<p class="parameters">
|
||||
The parameter <tt>backlog</tt> 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>
|
||||
<p class="return">
|
||||
In case of success, the method returns 1. In case of error, the
|
||||
method returns <b><tt>nil</tt></b> followed by an error message.
|
||||
</p>
|
||||
|
||||
<!-- receive ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="receive">
|
||||
<p class="name" id="receive">
|
||||
client:<b>receive(</b>[pattern [, prefix]]<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Reads data from a client object, according to the specified <em>read
|
||||
pattern</em>. Patterns follow the Lua file I/O format, and the difference in performance between all patterns is negligible.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<p class="parameters">
|
||||
<tt>Pattern</tt> 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;
|
||||
closed. No end-of-line translation is performed;</li>
|
||||
<li> '<tt>*l</tt>': reads a line of text from the socket. The line is
|
||||
terminated by a LF character (ASCII 10), optionally preceded by a
|
||||
CR character (ASCII 13). The CR and LF characters are not included in
|
||||
the returned line. In fact, <em>all</em> CR characters are
|
||||
ignored by the pattern. This is the default pattern;
|
||||
ignored by the pattern. This is the default pattern;</li>
|
||||
<li> <tt>number</tt>: causes the method to read a specified <tt>number</tt>
|
||||
of bytes from the socket.
|
||||
of bytes from the socket.</li>
|
||||
</ul>
|
||||
|
||||
<p class=parameters>
|
||||
<p class="parameters">
|
||||
<tt>Prefix</tt> is an optional string to be concatenated to the beginning
|
||||
of any received data before return.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
<p class="return">
|
||||
If successful, the method returns the received pattern. In case of error,
|
||||
the method returns <tt><b>nil</b></tt> followed by an error
|
||||
message, followed by a (possibly empty) string containing
|
||||
@ -388,7 +390,7 @@ 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>
|
||||
<p class="note">
|
||||
<b>Important note</b>: This function was changed <em>severely</em>. It used
|
||||
to support multiple patterns (but I have never seen this feature used) and
|
||||
now it doesn't anymore. Partial results used to be returned in the same
|
||||
@ -399,22 +401,22 @@ too.
|
||||
|
||||
<!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="send">
|
||||
<p class="name" id="send">
|
||||
client:<b>send(</b>data [, i [, j]]<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Sends <tt>data</tt> through client object.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<p class="parameters">
|
||||
<tt>Data</tt> is the string to be sent. The optional arguments
|
||||
<tt>i</tt> and <tt>j</tt> work exactly like the standard
|
||||
<tt>string.sub</tt> Lua function to allow the selection of a
|
||||
substring to be sent.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
<p class="return">
|
||||
If successful, the method returns the index of the last byte
|
||||
within <tt>[i, j]</tt> that has been sent. Notice that, if
|
||||
<tt>i</tt> is 1 or absent, this is effectively the total
|
||||
@ -428,7 +430,7 @@ was completed or the string '<tt>timeout</tt>' in case
|
||||
there was a timeout during the operation.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
Note: Output is <em>not</em> buffered. For small strings,
|
||||
it is always better to concatenate them in Lua
|
||||
(with the '<tt>..</tt>' operator) and send the result in one call
|
||||
@ -437,27 +439,27 @@ instead of calling the method several times.
|
||||
|
||||
<!-- setoption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="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>
|
||||
<p class="description">
|
||||
Sets options for the TCP object. Options are only needed by low-level or
|
||||
time-critical applications. You should only modify an option if you
|
||||
are sure you need it.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<p class="parameters">
|
||||
<tt>Option</tt> is a string with the option name, and <tt>value</tt>
|
||||
depends on the option being set:
|
||||
depends on the option being set:</p>
|
||||
|
||||
<ul>
|
||||
|
||||
<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;
|
||||
considered broken and processes using the socket are notified;</li>
|
||||
|
||||
<li> '<tt>linger</tt>': Controls the action taken when unsent data are
|
||||
queued on a socket and a close is performed. The value is a table with a
|
||||
@ -468,79 +470,79 @@ 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;
|
||||
zero;</li>
|
||||
|
||||
<li> '<tt>reuseaddr</tt>': Setting this option indicates that the rules
|
||||
used in validating addresses supplied in a call to
|
||||
<a href=#bind><tt>bind</tt></a> should allow reuse of local addresses;
|
||||
<a href="#bind"><tt>bind</tt></a> should allow reuse of local addresses;</li>
|
||||
|
||||
<li> '<tt>tcp-nodelay</tt>': Setting this option to <tt>true</tt>
|
||||
disables the Nagle's algorithm for the connection;
|
||||
disables the Nagle's algorithm for the connection;</li>
|
||||
|
||||
<li> '<tt>tcp-keepidle</tt>': value in seconds for <tt>TCP_KEEPIDLE</tt> Linux only!!
|
||||
<li> '<tt>tcp-keepidle</tt>': value in seconds for <tt>TCP_KEEPIDLE</tt> Linux only!!</li>
|
||||
|
||||
<li> '<tt>tcp-keepcnt</tt>': value for <tt>TCP_KEEPCNT</tt> Linux only!!
|
||||
<li> '<tt>tcp-keepcnt</tt>': value for <tt>TCP_KEEPCNT</tt> Linux only!!</li>
|
||||
|
||||
<li> '<tt>tcp-keepintvl</tt>': value for <tt>TCP_KEEPINTVL</tt> Linux only!!
|
||||
<li> '<tt>tcp-keepintvl</tt>': value for <tt>TCP_KEEPINTVL</tt> Linux only!!</li>
|
||||
|
||||
<li> '<tt>ipv6-v6only</tt>':
|
||||
Setting this option to <tt>true</tt> restricts an <tt>inet6</tt> socket to
|
||||
sending and receiving only IPv6 packets.
|
||||
sending and receiving only IPv6 packets.</li>
|
||||
</ul>
|
||||
|
||||
<p class=return>
|
||||
<p class="return">
|
||||
The method returns 1 in case of success, or <b><tt>nil</tt></b>
|
||||
followed by an error message otherwise.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
Note: The descriptions above come from the man pages.
|
||||
</p>
|
||||
|
||||
<!-- setstats +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="setstats">
|
||||
<p class="name" id="setstats">
|
||||
master:<b>setstats(</b>received, sent, age<b>)</b><br>
|
||||
client:<b>setstats(</b>received, sent, age<b>)</b><br>
|
||||
server:<b>setstats(</b>received, sent, age<b>)</b><br>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Resets accounting information on the socket, useful for throttling
|
||||
of bandwidth.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<p class="parameters">
|
||||
<tt>Received</tt> is a number with the new number of bytes received.
|
||||
<tt>Sent</tt> is a number with the new number of bytes sent.
|
||||
<tt>Age</tt> is the new age in seconds.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
<p class="return">
|
||||
The method returns 1 in case of success and <tt><b>nil</b></tt> otherwise.
|
||||
</p>
|
||||
|
||||
<!-- settimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="settimeout">
|
||||
<p class="name" id="settimeout">
|
||||
master:<b>settimeout(</b>value [, mode]<b>)</b><br>
|
||||
client:<b>settimeout(</b>value [, mode]<b>)</b><br>
|
||||
server:<b>settimeout(</b>value [, mode]<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<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>
|
||||
<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>
|
||||
<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:
|
||||
@ -557,12 +559,12 @@ the amount of time LuaSocket can block a Lua script before returning from
|
||||
a call.</li>
|
||||
</ul>
|
||||
|
||||
<p class=parameters>
|
||||
<p class="parameters">
|
||||
The <b><tt>nil</tt></b> timeout <tt>value</tt> allows operations to block
|
||||
indefinitely. Negative timeout values have the same effect.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<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
|
||||
@ -571,7 +573,7 @@ and perform automatic name resolution might be blocked by the resolver for
|
||||
longer than the specified timeout value.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<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.
|
||||
@ -579,123 +581,126 @@ contained verbs making their imperative nature obvious.
|
||||
|
||||
<!-- shutdown +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="shutdown">
|
||||
<p class="name" id="shutdown">
|
||||
client:<b>shutdown(</b>mode<b>)</b><br>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Shuts down part of a full-duplex connection.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<p class="parameters">
|
||||
Mode tells which way of the connection should be shut down and can
|
||||
take the value:
|
||||
<ul>
|
||||
<li>"<tt>both</tt>": disallow further sends and receives on the object.
|
||||
This is the default mode;
|
||||
<li>"<tt>send</tt>": disallow further sends on the object;
|
||||
<li>"<tt>receive</tt>": disallow further receives on the object.
|
||||
This is the default mode;</li>
|
||||
<li>"<tt>send</tt>": disallow further sends on the object;</li>
|
||||
<li>"<tt>receive</tt>": disallow further receives on the object.</li>
|
||||
</ul>
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
<p class="return">
|
||||
This function returns 1.
|
||||
</p>
|
||||
|
||||
<!-- setfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="setfd">
|
||||
<p class="name" id="setfd">
|
||||
master:<b>setfd(</b>fd<b>)</b><br>
|
||||
client:<b>setfd(</b>fd<b>)</b><br>
|
||||
server:<b>setfd(</b>fd<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
Sets the underling socket descriptor or handle associated to the object. The current one is simply replaced, not closed, and no other change to the object state is made.
|
||||
<p class="description">
|
||||
Sets the underling socket descriptor or handle associated to the object. The current one
|
||||
is simply replaced, not closed, and no other change to the object state is made.
|
||||
To set it as invalid use <a href="socket.html#socketinvalid"><tt>_SOCKETINVALID</tt></a>.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
<p class="return">
|
||||
No return value.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
Note: <b>This is an internal method. Unlikely to be
|
||||
portable. Use at your own risk. </b>
|
||||
</p>
|
||||
|
||||
<!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="socket.tcp">
|
||||
<p class="name" id="socket.tcp">
|
||||
socket.<b>tcp()</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Creates and returns an TCP master object. A master object can
|
||||
be transformed into a server object with the method
|
||||
<a href=#listen><tt>listen</tt></a> (after a call to <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
|
||||
<a href="#listen"><tt>listen</tt></a> (after a call to <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>
|
||||
<a href="#close"><tt>close</tt></a> method.</p>
|
||||
|
||||
<p class=return>
|
||||
<p class="return">
|
||||
In case of success, a new master object is returned. In case of error,
|
||||
<b><tt>nil</tt></b> is returned, followed by an error message.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
Note: The choice between IPv4 and IPv6 happens during a call to
|
||||
<a href=#bind><tt>bind</tt></a> or <a
|
||||
href=#bind><tt>connect</tt></a>, depending on the address
|
||||
<a href="#bind"><tt>bind</tt></a> or <a
|
||||
href="#bind"><tt>connect</tt></a>, depending on the address
|
||||
family obtained from the resolver.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
Note: Before the choice between IPv4 and IPv6 happens,
|
||||
the internal socket object is invalid and therefore <a
|
||||
href=#setoption><tt>setoption</tt></a> will fail.
|
||||
href="#setoption"><tt>setoption</tt></a> will fail.
|
||||
</p>
|
||||
|
||||
<!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="socket.tcp4">
|
||||
<p class="name" id="socket.tcp4">
|
||||
socket.<b>tcp4()</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Creates and returns an IPv4 TCP master object. A master object can
|
||||
be transformed into a server object with the method
|
||||
<a href=#listen><tt>listen</tt></a> (after a call to <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
|
||||
<a href="#listen"><tt>listen</tt></a> (after a call to <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>
|
||||
<a href="#close"><tt>close</tt></a> method.</p>
|
||||
|
||||
<p class=return>
|
||||
<p class="return">
|
||||
In case of success, a new master object is returned. In case of error,
|
||||
<b><tt>nil</tt></b> is returned, followed by an error message.
|
||||
</p>
|
||||
|
||||
<!-- socket.tcp6 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="socket.tcp6">
|
||||
<p class="name" id="socket.tcp6">
|
||||
socket.<b>tcp6()</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Creates and returns an IPv6 TCP master object. A master object can
|
||||
be transformed into a server object with the method
|
||||
<a href=#listen><tt>listen</tt></a> (after a call to <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
|
||||
<a href="#listen"><tt>listen</tt></a> (after a call to <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>
|
||||
<a href="#close"><tt>close</tt></a> method.</p>
|
||||
|
||||
<p class=return>
|
||||
<p class="return">
|
||||
In case of success, a new master object is returned. In case of error,
|
||||
<b><tt>nil</tt></b> is returned, followed by an error message.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
Note: The TCP object returned will have the option
|
||||
"<tt>ipv6-v6only</tt>" set to <tt><b>true</b></tt>.
|
||||
</p>
|
||||
@ -704,10 +709,10 @@ Note: The TCP object returned will have the option
|
||||
|
||||
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<div class=footer>
|
||||
<div class="footer">
|
||||
<hr>
|
||||
<center>
|
||||
<p class=bar>
|
||||
<p class="bar">
|
||||
<a href="index.html">home</a> ·
|
||||
<a href="index.html#down">download</a> ·
|
||||
<a href="installation.html">installation</a> ·
|
@ -13,17 +13,17 @@
|
||||
|
||||
<!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<div class=header>
|
||||
<div class="header">
|
||||
<hr>
|
||||
<center>
|
||||
<table summary="LuaSocket logo">
|
||||
<tr><td align=center><a href="http://www.lua.org">
|
||||
<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png">
|
||||
<tr><td align="center"><a href="http://www.lua.org">
|
||||
<img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
|
||||
</a></td></tr>
|
||||
<tr><td align=center valign=top>Network support for the Lua language
|
||||
<tr><td align="center" valign="top">Network support for the Lua language
|
||||
</td></tr>
|
||||
</table>
|
||||
<p class=bar>
|
||||
<p class="bar">
|
||||
<a href="index.html">home</a> ·
|
||||
<a href="index.html#download">download</a> ·
|
||||
<a href="installation.html">installation</a> ·
|
||||
@ -71,26 +71,26 @@ unconnected:<b>getoption()</b>
|
||||
|
||||
<p class="description">
|
||||
Gets an option value from the UDP object.
|
||||
See <a href=#setoption><tt>setoption</tt></a> for
|
||||
See <a href="#setoption"><tt>setoption</tt></a> for
|
||||
description of the option names and values.
|
||||
</p>
|
||||
|
||||
<p class="parameters"><tt>Option</tt> is a string with the option name.
|
||||
<ul>
|
||||
<li> '<tt>dontroute</tt>'
|
||||
<li> '<tt>broadcast</tt>'
|
||||
<li> '<tt>reuseaddr</tt>'
|
||||
<li> '<tt>reuseport</tt>'
|
||||
<li> '<tt>ip-multicast-loop</tt>'
|
||||
<li> '<tt>ipv6-v6only</tt>'
|
||||
<li> '<tt>ip-multicast-if</tt>'
|
||||
<li> '<tt>ip-multicast-ttl</tt>'
|
||||
<li> '<tt>ip-add-membership</tt>'
|
||||
<li> '<tt>ip-drop-membership</tt>'
|
||||
<li> '<tt>dontroute</tt>'</li>
|
||||
<li> '<tt>broadcast</tt>'</li>
|
||||
<li> '<tt>reuseaddr</tt>'</li>
|
||||
<li> '<tt>reuseport</tt>'</li>
|
||||
<li> '<tt>ip-multicast-loop</tt>'</li>
|
||||
<li> '<tt>ipv6-v6only</tt>'</li>
|
||||
<li> '<tt>ip-multicast-if</tt>'</li>
|
||||
<li> '<tt>ip-multicast-ttl</tt>'</li>
|
||||
<li> '<tt>ip-add-membership</tt>'</li>
|
||||
<li> '<tt>ip-drop-membership</tt>'</li>
|
||||
</ul>
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
<p class="return">
|
||||
The method returns the option <tt>value</tt> in case of
|
||||
success, or
|
||||
<b><tt>nil</tt></b> followed by an error message otherwise.
|
||||
@ -108,7 +108,7 @@ associated with a connected UDP object.
|
||||
</p>
|
||||
|
||||
|
||||
<p class=return>
|
||||
<p class="return">
|
||||
Returns a string with the IP address of the peer, the
|
||||
port number that peer is using for the connection,
|
||||
and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>").
|
||||
@ -131,7 +131,7 @@ Returns the local address information associated to the object.
|
||||
</p>
|
||||
|
||||
|
||||
<p class=return>
|
||||
<p class="return">
|
||||
The method returns a string with local IP address, a number with
|
||||
the local port,
|
||||
and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>").
|
||||
@ -148,12 +148,12 @@ wild-card address).
|
||||
|
||||
<!-- gettimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="gettimeout">
|
||||
<p class="name" id="gettimeout">
|
||||
connected:<b>settimeout(</b>value<b>)</b><br>
|
||||
unconnected:<b>settimeout(</b>value<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
<p class="description">
|
||||
Returns the current timeout value.
|
||||
</p>
|
||||
|
||||
@ -180,8 +180,8 @@ 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
|
||||
compile-time constant <a
|
||||
href=socket.html#datagramsize><tt>socket._DATAGRAMSIZE</tt></a> is used
|
||||
compile-time constant <a href="socket.html#datagramsize">
|
||||
<tt>socket._DATAGRAMSIZE</tt></a> is used
|
||||
(it defaults to 8192 bytes). Larger sizes will cause a
|
||||
temporary buffer to be allocated for the operation.
|
||||
</p>
|
||||
@ -286,45 +286,45 @@ name, and <tt>value</tt> depends on the option being set:
|
||||
<ul>
|
||||
<li> '<tt>dontroute</tt>': Indicates that outgoing
|
||||
messages should bypass the standard routing facilities.
|
||||
Receives a boolean value;
|
||||
Receives a boolean value;</li>
|
||||
<li> '<tt>broadcast</tt>': Requests permission to send
|
||||
broadcast datagrams on the socket.
|
||||
Receives a boolean value;
|
||||
Receives a boolean value;</li>
|
||||
<li> '<tt>reuseaddr</tt>': Indicates that the rules used in
|
||||
validating addresses supplied in a <tt>bind()</tt> call
|
||||
should allow reuse of local addresses.
|
||||
Receives a boolean value;
|
||||
Receives a boolean value;</li>
|
||||
<li> '<tt>reuseport</tt>': Allows completely duplicate
|
||||
bindings by multiple processes if they all set
|
||||
'<tt>reuseport</tt>' before binding the port.
|
||||
Receives a boolean value;
|
||||
Receives a boolean value;</li>
|
||||
<li> '<tt>ip-multicast-loop</tt>':
|
||||
Specifies whether or not a copy of an outgoing multicast
|
||||
datagram is delivered to the sending host as long as it is a
|
||||
member of the multicast group.
|
||||
Receives a boolean value;
|
||||
Receives a boolean value;</li>
|
||||
<li> '<tt>ipv6-v6only</tt>':
|
||||
Specifies whether to restrict <tt>inet6</tt> sockets to
|
||||
sending and receiving only IPv6 packets.
|
||||
Receive a boolean value;
|
||||
Receive a boolean value;</li>
|
||||
<li> '<tt>ip-multicast-if</tt>':
|
||||
Sets the interface over which outgoing multicast datagrams
|
||||
are sent.
|
||||
Receives an IP address;
|
||||
Receives an IP address;</li>
|
||||
<li> '<tt>ip-multicast-ttl</tt>':
|
||||
Sets the Time To Live in the IP header for outgoing
|
||||
multicast datagrams.
|
||||
Receives a number;
|
||||
Receives a number;</li>
|
||||
<li> '<tt>ip-add-membership</tt>':
|
||||
Joins the multicast group specified.
|
||||
Receives a table with fields
|
||||
<tt>multiaddr</tt> and <tt>interface</tt>, each containing an
|
||||
IP address;
|
||||
IP address;</li>
|
||||
<li> '<tt>ip-drop-membership</tt>': Leaves the multicast
|
||||
group specified.
|
||||
Receives a table with fields
|
||||
<tt>multiaddr</tt> and <tt>interface</tt>, each containing an
|
||||
IP address.
|
||||
IP address.</li>
|
||||
</ul>
|
||||
|
||||
<p class="return">
|
||||
@ -332,7 +332,7 @@ The method returns 1 in case of success, or
|
||||
<b><tt>nil</tt></b> followed by an error message otherwise.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
Note: The descriptions above come from the man pages.
|
||||
</p>
|
||||
|
||||
@ -381,11 +381,11 @@ is recommended when the same peer is used for several transmissions
|
||||
and can result in up to 30% performance gains.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
Note: Starting with LuaSocket 3.0, the host name resolution
|
||||
depends on whether the socket was created by <a
|
||||
href=#socket.udp><tt>socket.udp</tt></a> or <a
|
||||
href=#socket.udp6><tt>socket.udp6</tt></a>. Addresses from
|
||||
href="#socket.udp"><tt>socket.udp</tt></a> or <a
|
||||
href="#socket.udp6"><tt>socket.udp6</tt></a>. Addresses from
|
||||
the appropriate family are tried in succession until the
|
||||
first success or until the last failure.
|
||||
</p>
|
||||
@ -492,23 +492,23 @@ returned. In case of error, <b><tt>nil</tt></b> is returned, followed by
|
||||
an error message.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
Note: The choice between IPv4 and IPv6 happens during a call to
|
||||
<a href=#sendto><tt>sendto</tt></a>, <a
|
||||
href=#setpeername><tt>setpeername</tt></a>, or <a
|
||||
href=#setsockname><tt>sockname</tt></a>, depending on the address
|
||||
<a href="#sendto"><tt>sendto</tt></a>, <a
|
||||
href="#setpeername"><tt>setpeername</tt></a>, or <a
|
||||
href="#setsockname"><tt>sockname</tt></a>, depending on the address
|
||||
family obtained from the resolver.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
Note: Before the choice between IPv4 and IPv6 happens,
|
||||
the internal socket object is invalid and therefore <a
|
||||
href=#setoption><tt>setoption</tt></a> will fail.
|
||||
href="#setoption"><tt>setoption</tt></a> will fail.
|
||||
</p>
|
||||
|
||||
<!-- socket.udp4 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class="name" id="socket.udp">
|
||||
<p class="name" id="socket.udp4">
|
||||
socket.<b>udp4()</b>
|
||||
</p>
|
||||
|
||||
@ -564,7 +564,7 @@ returned. In case of error, <b><tt>nil</tt></b> is returned, followed by
|
||||
an error message.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
<p class="note">
|
||||
Note: The TCP object returned will have the option
|
||||
"<tt>ipv6-v6only</tt>" set to <tt><b>true</b></tt>.
|
||||
</p>
|
||||
@ -573,10 +573,10 @@ Note: The TCP object returned will have the option
|
||||
|
||||
<!-- footer ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<div class=footer>
|
||||
<div class="footer">
|
||||
<hr>
|
||||
<center>
|
||||
<p class=bar>
|
||||
<p class="bar">
|
||||
<a href="index.html">home</a> ·
|
||||
<a href="index.html#download">download</a> ·
|
||||
<a href="installation.html">installation</a> ·
|
@ -127,7 +127,7 @@ build = {
|
||||
mingw32 = make_plat("mingw32")
|
||||
},
|
||||
copy_directories = {
|
||||
"doc"
|
||||
"docs"
|
||||
, "samples"
|
||||
, "etc"
|
||||
, "test" }
|
||||
|
6
makefile
6
makefile
@ -33,6 +33,9 @@ install-both:
|
||||
$(MAKE) clean
|
||||
@cd src; $(MAKE) $(PLAT) LUAV=5.3
|
||||
@cd src; $(MAKE) install LUAV=5.3
|
||||
$(MAKE) clean
|
||||
@cd src; $(MAKE) $(PLAT) LUAV=5.4
|
||||
@cd src; $(MAKE) install LUAV=5.4
|
||||
|
||||
install-both-unix:
|
||||
$(MAKE) clean
|
||||
@ -44,6 +47,9 @@ install-both-unix:
|
||||
$(MAKE) clean
|
||||
@cd src; $(MAKE) $(PLAT) LUAV=5.3
|
||||
@cd src; $(MAKE) install-unix LUAV=5.3
|
||||
$(MAKE) clean
|
||||
@cd src; $(MAKE) $(PLAT) LUAV=5.4
|
||||
@cd src; $(MAKE) install-unix LUAV=5.4
|
||||
|
||||
.PHONY: test
|
||||
|
||||
|
@ -92,23 +92,23 @@ MAKE = \
|
||||
socket.vcxproj \
|
||||
mime.vcxproj
|
||||
|
||||
DOC = \
|
||||
doc/dns.html \
|
||||
doc/ftp.html \
|
||||
doc/index.html \
|
||||
doc/http.html \
|
||||
doc/installation.html \
|
||||
doc/introduction.html \
|
||||
doc/ltn12.html \
|
||||
doc/luasocket.png \
|
||||
doc/mime.html \
|
||||
doc/reference.css \
|
||||
doc/reference.html \
|
||||
doc/smtp.html \
|
||||
doc/socket.html \
|
||||
doc/tcp.html \
|
||||
doc/udp.html \
|
||||
doc/url.html
|
||||
DOCS = \
|
||||
docs/dns.html \
|
||||
docs/ftp.html \
|
||||
docs/index.html \
|
||||
docs/http.html \
|
||||
docs/installation.html \
|
||||
docs/introduction.html \
|
||||
docs/ltn12.html \
|
||||
docs/luasocket.png \
|
||||
docs/mime.html \
|
||||
docs/reference.css \
|
||||
docs/reference.html \
|
||||
docs/smtp.html \
|
||||
docs/socket.html \
|
||||
docs/tcp.html \
|
||||
docs/udp.html \
|
||||
docs/url.html
|
||||
|
||||
dist:
|
||||
mkdir -p $(DIST)
|
||||
@ -123,8 +123,8 @@ dist:
|
||||
mkdir -p $(DIST)/src
|
||||
cp -vf $(SRC) $(DIST)/src
|
||||
|
||||
mkdir -p $(DIST)/doc
|
||||
cp -vf $(DOC) $(DIST)/doc
|
||||
mkdir -p $(DIST)/docs
|
||||
cp -vf $(DOCS) $(DIST)/docs
|
||||
|
||||
mkdir -p $(DIST)/samples
|
||||
cp -vf $(SAMPLES) $(DIST)/samples
|
||||
|
@ -20,6 +20,7 @@
|
||||
</ItemGroup>
|
||||
<ItemGroup>
|
||||
<ClCompile Include="src\mime.c" />
|
||||
<ClCompile Include="src\compat.c" />
|
||||
</ItemGroup>
|
||||
<PropertyGroup Label="Globals">
|
||||
<ProjectGuid>{128E8BD0-174A-48F0-8771-92B1E8D18713}</ProjectGuid>
|
||||
|
@ -21,6 +21,7 @@
|
||||
<ItemGroup>
|
||||
<ClCompile Include="src\auxiliar.c" />
|
||||
<ClCompile Include="src\buffer.c" />
|
||||
<ClCompile Include="src\compat.c" />
|
||||
<ClCompile Include="src\except.c" />
|
||||
<ClCompile Include="src\inet.c" />
|
||||
<ClCompile Include="src\io.c" />
|
||||
|
@ -283,6 +283,13 @@ local function adjustrequest(reqt)
|
||||
nreqt.uri = reqt.uri or adjusturi(nreqt)
|
||||
-- adjust headers in request
|
||||
nreqt.headers = adjustheaders(nreqt)
|
||||
if nreqt.source
|
||||
and not nreqt.headers["content-length"]
|
||||
and not nreqt.headers["transfer-encoding"]
|
||||
then
|
||||
nreqt.headers["transfer-encoding"] = "chunked"
|
||||
end
|
||||
|
||||
-- ajust host and port if there is a proxy
|
||||
nreqt.host, nreqt.port = adjustproxy(nreqt)
|
||||
return nreqt
|
||||
|
@ -11,6 +11,8 @@ local string = require("string")
|
||||
local table = require("table")
|
||||
local unpack = unpack or table.unpack
|
||||
local base = _G
|
||||
local select = select
|
||||
|
||||
local _M = {}
|
||||
if module then -- heuristic for exporting a global package table
|
||||
ltn12 = _M -- luacheck: ignore
|
||||
@ -22,8 +24,6 @@ _M.source = source
|
||||
_M.sink = sink
|
||||
_M.pump = pump
|
||||
|
||||
local unpack = unpack or table.unpack
|
||||
|
||||
-- 2048 seems to be better in windows...
|
||||
_M.BLOCKSIZE = 2048
|
||||
_M._VERSION = "LTN12 1.0.3"
|
||||
@ -45,7 +45,7 @@ end
|
||||
-- (thanks to Wim Couwenberg)
|
||||
function filter.chain(...)
|
||||
local arg = {...}
|
||||
local n = base.select('#',...)
|
||||
local n = select('#',...)
|
||||
local top, index = 1, 1
|
||||
local retry = ""
|
||||
return function(chunk)
|
||||
|
12
src/makefile
12
src/makefile
@ -16,7 +16,7 @@
|
||||
# platform to build for
|
||||
PLAT?=linux
|
||||
|
||||
# LUAV: 5.1 5.2
|
||||
# LUAV: 5.1 5.2 5.3 5.4
|
||||
# lua version to build against
|
||||
LUAV?=5.1
|
||||
|
||||
@ -163,7 +163,7 @@ O_macosx=o
|
||||
CC_macosx=gcc
|
||||
DEF_macosx= -DLUASOCKET_$(DEBUG) -DUNIX_HAS_SUN_LEN
|
||||
CFLAGS_macosx=$(LUAINC:%=-I%) $(DEF) -Wall -O2 -fno-common
|
||||
LDFLAGS_macosx= -bundle -undefined dynamic_lookup -o
|
||||
LDFLAGS_macosx= -bundle -undefined dynamic_lookup -o
|
||||
LD_macosx=gcc
|
||||
SOCKET_macosx=usocket.o
|
||||
|
||||
@ -176,7 +176,7 @@ CC_linux=gcc
|
||||
DEF_linux=-DLUASOCKET_$(DEBUG)
|
||||
CFLAGS_linux=$(LUAINC:%=-I%) $(DEF) -Wall -Wshadow -Wextra \
|
||||
-Wimplicit -O2 -ggdb3 -fpic
|
||||
LDFLAGS_linux=-O -shared -fpic -o
|
||||
LDFLAGS_linux=-O -shared -fpic -o
|
||||
LD_linux=gcc
|
||||
SOCKET_linux=usocket.o
|
||||
|
||||
@ -189,7 +189,7 @@ CC_freebsd=gcc
|
||||
DEF_freebsd=-DLUASOCKET_$(DEBUG) -DUNIX_HAS_SUN_LEN
|
||||
CFLAGS_freebsd=$(LUAINC:%=-I%) $(DEF) -Wall -Wshadow -Wextra \
|
||||
-Wimplicit -O2 -ggdb3 -fpic
|
||||
LDFLAGS_freebsd=-O -shared -fpic -o
|
||||
LDFLAGS_freebsd=-O -shared -fpic -o
|
||||
LD_freebsd=gcc
|
||||
SOCKET_freebsd=usocket.o
|
||||
|
||||
@ -202,7 +202,7 @@ CC_solaris=gcc
|
||||
DEF_solaris=-DLUASOCKET_$(DEBUG)
|
||||
CFLAGS_solaris=$(LUAINC:%=-I%) $(DEF) -Wall -Wshadow -Wextra \
|
||||
-Wimplicit -O2 -ggdb3 -fpic
|
||||
LDFLAGS_solaris=-lnsl -lsocket -lresolv -O -shared -fpic -o
|
||||
LDFLAGS_solaris=-lnsl -lsocket -lresolv -O -shared -fpic -o
|
||||
LD_solaris=gcc
|
||||
SOCKET_solaris=usocket.o
|
||||
|
||||
@ -215,7 +215,7 @@ CC_mingw=gcc
|
||||
DEF_mingw= -DLUASOCKET_$(DEBUG) \
|
||||
-DWINVER=0x0501
|
||||
CFLAGS_mingw=$(LUAINC:%=-I%) $(DEF) -Wall -O2 -fno-common
|
||||
LDFLAGS_mingw= $(LUALIB) -shared -Wl,-s -lws2_32 -o
|
||||
LDFLAGS_mingw= $(LUALIB) -shared -Wl,-s -lws2_32 -o
|
||||
LD_mingw=gcc
|
||||
SOCKET_mingw=wsocket.o
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user