mirror of
https://github.com/lunarmodules/luasocket.git
synced 2024-11-08 06:18:21 +01:00
Starting the manual. Oh well.
This commit is contained in:
Diego Nehab
parent
5c13076f89
commit
c53dad9883
@ -1,348 +0,0 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
||||
"http://www.w3.org/TR/html4/strict.dtd">
|
||||
<html>
|
||||
|
||||
<head>
|
||||
<title>LuaSocket: Network support for the Lua language</title>
|
||||
<link rel="stylesheet" href="reference.css" type="text/css">
|
||||
</head>
|
||||
|
||||
<body>
|
||||
|
||||
<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<div class=header>
|
||||
<hr>
|
||||
<center>
|
||||
<table summary="LuaSocket logo">
|
||||
<tr><td align=center><a href="http://www.lua.org">
|
||||
<img border=0 alt="LuaSocket" src="luasocket.png">
|
||||
</a></td></tr>
|
||||
<tr><td align=center valign=top>Network support for the Lua language
|
||||
</td></tr>
|
||||
</table>
|
||||
<p class=bar>
|
||||
<a href="home.html">home</a> ·
|
||||
<a href="home.html#download">download</a> ·
|
||||
<a href="introduction.html">introduction</a> ·
|
||||
<a href="reference.html">reference</a>
|
||||
</p>
|
||||
</center>
|
||||
<hr>
|
||||
</div>
|
||||
|
||||
<!-- stream ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<h2 id=stream>Callbacks</h2>
|
||||
|
||||
<p>
|
||||
HTTP, FTP, and SMTP transfers sometimes involve large amounts of
|
||||
information. Sometimes an application needs to generate outgoing data
|
||||
in real time, or needs to process incoming information as it is being
|
||||
received. To address these problems, LuaSocket allows HTTP and SMTP message
|
||||
bodies and FTP file contents to be streamed through the
|
||||
callback mechanism outlined below.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Instead of returning the received contents
|
||||
as a big to the Lua application, the library allows the user to
|
||||
provide a <em>receive callback</em> that will be called with successive
|
||||
chunks of data, as the data becomes available. Conversely, the <em>send
|
||||
callback</em> mechanism can be used when the application wants to incrementally provide LuaSocket with the data to be sent.
|
||||
</p>
|
||||
|
||||
<!-- receive +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id=receive>
|
||||
<b>receive_cb(</b>chunk, err<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
A receive callback will be repeatedly called by
|
||||
LuaSocket whenever new data is available. Each time it is called, the
|
||||
callback receives successive chunks of downloaded data.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<tt>Chunk</tt> contains the latest downloaded chunk of data.
|
||||
When the transmission is over, the function is called with an
|
||||
empty string (i.e. <tt>""</tt>) in <tt>chunk</tt>.
|
||||
If an error occurs, the function receives a <b><tt>nil</tt></b>
|
||||
<tt>chunk</tt> and an error message in <tt>err</tt>.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
The callback can abort transmission by returning <b><tt>nil</tt></b> as its first
|
||||
return value, and an optional error message as the
|
||||
second return value. To continue receiving
|
||||
data, the function should return non-<b><tt>nil</tt></b> as its first return
|
||||
value. Optionally, in this case, it may return a
|
||||
second return value, with a new callback function to take its place.
|
||||
</p>
|
||||
|
||||
<!-- send_cb ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id=send>
|
||||
<b>send_cb()</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
A send callback will be called whenever LuaSocket
|
||||
needs more data to be sent.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
Each time the callback is called, it should return the next chunk of data. It
|
||||
can optionally return, as it's second return value, a new callback to replace
|
||||
itself. The callback can abort the process at any time by returning
|
||||
<b><tt>nil</tt></b> followed by an optional error message.
|
||||
</p>
|
||||
|
||||
<!-- predefined +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<h2 id=predefined>Predefined Callbacks</h2>
|
||||
|
||||
<p>
|
||||
The Callback module provides several predefined callbacks to
|
||||
perform the most common input/output operations. Callbacks are provided
|
||||
that send and receive contents of files and strings. Furthermore,
|
||||
composition functions are provided to chain callbacks with filters, such as
|
||||
the filters defined in the <a href=mime.html>MIME</a> module.
|
||||
Together, these two modules provide a powerful interface to send and
|
||||
receive information.
|
||||
</p>
|
||||
|
||||
<!-- done +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id=done>
|
||||
socket.callback.<b>done()</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
This function creates and returns a callback that successfully terminates
|
||||
the transmission.
|
||||
</p>
|
||||
|
||||
<!-- fail +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id=fail>
|
||||
socket.callback.<b>fail(</b>message<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
This function creates and returns a callback that aborts the
|
||||
transmission with a given error <tt>message</tt>.
|
||||
</p>
|
||||
|
||||
<!-- receive.concat +++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id=receive.concat>
|
||||
socket.callback.<b>receive.concat(</b>cat<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
This function creates a receive callback that stores whatever it receives
|
||||
into a concat object. When done, the application can get the contents
|
||||
received as a single string, directly from the concat object.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<tt>Cat</tt> is the target concat object, or <b><tt>nil</tt></b>.
|
||||
If <tt>cat</tt> is <b><tt>nil</tt></b>, the function creates its own
|
||||
concat object.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
The function returns a receive callback for the file, and the concat object
|
||||
that will be used to store the received contents.
|
||||
</p>
|
||||
|
||||
<!-- receive.file +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id=receive.file>
|
||||
socket.callback.<b>receive.file(</b>file, io_err<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
This function creates a receive callback that stores whatever it receives
|
||||
into a file. When done, the callback closes the file.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<tt>File</tt> is a file handle opened for writing. If <tt>file</tt> is
|
||||
<b><tt>nil</tt></b>, <tt>io_err</tt> can contain an error message. In this
|
||||
case, the function returns a callback that just aborts
|
||||
transmission with the error message.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
The function returns a receive callback for the file.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
Note: This function is designed so that it directly accepts the return
|
||||
values of Lua's IO <tt>io.open</tt> library function.
|
||||
</p>
|
||||
|
||||
<!-- receive.chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id=receive.chain>
|
||||
socket.callback.<b>receive.chain(</b>filter, receive_cb<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
This function creates a receive callback that passes all received data
|
||||
through a filter, before handing it to a given receive callback.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<tt>Cat</tt> is the target concat object, or <b><tt>nil</tt></b>.
|
||||
If <tt>cat</tt> is <b><tt>nil</tt></b>, the function creates its own
|
||||
concat object.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
The function returns a receive callback for the file, and the concat object
|
||||
that will be used to store the received contents.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
Note: Several filters are defined in the <a href=mime.html>MIME</a>
|
||||
module. Below is an example that creates a receive callback that
|
||||
creates a string from the received contents, after decoding the
|
||||
Quoted-Printable transfer content encoding.
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
string_cb, concat = socket.callback.receive.concat()
|
||||
receive_cb = socket.callback.receive.chain(
|
||||
socket.mime.decode("quoted-printable"),
|
||||
string_cb
|
||||
)
|
||||
</pre>
|
||||
|
||||
<p class=note>
|
||||
The call to <tt>callback.chain</tt> creates a chained
|
||||
receive callback that decodes data using the
|
||||
<tt><a href=mime.html#decode>mime.decode</a></tt>
|
||||
Quoted-Printable MIME filter and
|
||||
hands the decoded data to a concat receive callback.
|
||||
The concatenated decoded data can be retrieved later
|
||||
from the associated concat object.
|
||||
</p>
|
||||
|
||||
<!-- send.file ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id=send.file>
|
||||
socket.callback.<b>send.file(</b>file, io_err<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
This function creates a send callback that returns the contents
|
||||
of a file, chunk by chunk, until the file has been entirely sent.
|
||||
When done, the callback closes the file.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<tt>File</tt> is a file handle opened for reading. If <tt>file</tt> is
|
||||
<b><tt>nil</tt></b>, <tt>io_err</tt> can contain an error message. In this
|
||||
case, the function returns a callback that just aborts
|
||||
transmission with the error message.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
The function returns a send callback for the file.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
Note: This function is designed so that it directly accepts the return
|
||||
values of Lua's IO <tt>io.open</tt> library function.
|
||||
</p>
|
||||
|
||||
<!-- send.string ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id=send.string>
|
||||
socket.callback.<b>send.string(</b>str, err<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
This function creates a send callback that will send
|
||||
the contents of a string.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<tt>Str</tt> is the string to be sent.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
It returns a send callback for the string,
|
||||
or <b><tt>nil</tt></b> if <tt>str</tt> is <b><tt>nil</tt></b>.
|
||||
</p>
|
||||
|
||||
<!-- send.chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id=send.chain>
|
||||
socket.callback.<b>send.chain(</b>send_cb, filter<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
This function creates a send callback that will filter
|
||||
all the data it receives from another send callback, before
|
||||
sending it through.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<tt>Send_cb</tt> is the send callback to be chained to <tt>filter</tt>.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
Returns a callback chained with the filter.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
Note: Several filters are defined in the <a href=mime.html>MIME</a>
|
||||
module. Below is an example that creates a send callback that sends
|
||||
a file's contents encoded in the Base64 transfer content encoding.
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
send_cb = socket.callback.send.chain(
|
||||
socket.callback.send.file(io.open("input.bin"))
|
||||
socket.mime.chain(
|
||||
socket.mime.encode("base64"),
|
||||
socket.mime.wrap("base64")
|
||||
)
|
||||
)
|
||||
</pre>
|
||||
|
||||
<p class=note>
|
||||
The call to <a href=mime.html#chain><tt>mime.chain</tt></a>
|
||||
creates a chained filter that encodes it's input and then breaks it
|
||||
into lines. The call to <tt>callback.chain</tt> creates a chained
|
||||
send callback that reads the file from disk and passes it through the
|
||||
filter before sending it.
|
||||
</p>
|
||||
|
||||
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<div class=footer>
|
||||
<hr>
|
||||
<center>
|
||||
<p class=bar>
|
||||
<a href="home.html">home</a> ·
|
||||
<a href="home.html#down">download</a> ·
|
||||
<a href="introduction.html">introduction</a> ·
|
||||
<a href="reference.html">reference</a>
|
||||
</p>
|
||||
<p>
|
||||
<small>
|
||||
Last modified by Diego Nehab on <br>
|
||||
Sat Aug 9 01:00:41 PDT 2003
|
||||
</small>
|
||||
</p>
|
||||
</center>
|
||||
</div>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
202
doc/code.html
202
doc/code.html
@ -1,202 +0,0 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
||||
"http://www.w3.org/TR/html4/strict.dtd">
|
||||
<html>
|
||||
|
||||
<head>
|
||||
<title>LuaSocket: Network support for the Lua language</title>
|
||||
<link rel="stylesheet" href="reference.css" type="text/css">
|
||||
</head>
|
||||
|
||||
<body>
|
||||
|
||||
<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<div class=header>
|
||||
<hr>
|
||||
<center>
|
||||
<table summary="LuaSocket logo">
|
||||
<tr><td align=center><a href="http://www.lua.org">
|
||||
<img border=0 alt="LuaSocket" src="luasocket.png">
|
||||
</a></td></tr>
|
||||
<tr><td align=center valign=top>Network support for the Lua language
|
||||
</td></tr>
|
||||
</table>
|
||||
<p class=bar>
|
||||
<a href="home.html">home</a> ·
|
||||
<a href="home.html#download">download</a> ·
|
||||
<a href="introduction.html">introduction</a> ·
|
||||
<a href="reference.html">reference</a>
|
||||
</p>
|
||||
</center>
|
||||
<hr>
|
||||
</div>
|
||||
|
||||
<!-- code +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<h2 id=code>Code</h2>
|
||||
|
||||
<p>
|
||||
The <tt>code.lua</tt> module offers routines to convert back and forth
|
||||
some common types of content encoding, including Base 64 and URL
|
||||
escaping. Base 64 is described in
|
||||
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2045.txt">RFC
|
||||
2045</a>,
|
||||
URL escaping is described in
|
||||
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2396.txt">RFC
|
||||
2396</a>.
|
||||
</p>
|
||||
|
||||
<!-- base64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="base64">
|
||||
socket.code.<b>base64(</b>content, single<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
Applies the Base 64 content coding to a string.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<tt>Content</tt> is the string to be encoded.
|
||||
If <tt>single</tt> is set to anything
|
||||
but <b><tt>nil</tt></b>, the output is returned as a single
|
||||
line, otherwise the function splits the content into 76 character long
|
||||
lines after encoding.
|
||||
</p>
|
||||
|
||||
<p class=result>
|
||||
The function returns the encoded string.
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
code = socket.code.base64("diego:password")
|
||||
-- code = "ZGllZ286cGFzc3dvcmQ="
|
||||
</pre>
|
||||
|
||||
<!-- unbase64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="unbase64">
|
||||
socket.code.<b>unbase64(</b>content<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
Removes the Base 64 content coding from a string.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<tt>Content</tt> is the string to be decoded.
|
||||
</p>
|
||||
|
||||
<p class=result>
|
||||
The function returns the decoded string.
|
||||
</p>
|
||||
|
||||
<!-- escape +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="escape">
|
||||
socket.code.<b>escape(</b>content<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
Applies the URL escaping content coding to a string
|
||||
Each byte is encoded as a percent character followed
|
||||
by the two byte hexadecimal representation of its integer
|
||||
value.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<tt>Content</tt> is the string to be encoded.
|
||||
</p>
|
||||
|
||||
<p class=result>
|
||||
The function returns the encoded string.
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
code = socket.code.escape("/#?;")
|
||||
-- code = "%2f%23%3f%3b"
|
||||
</pre>
|
||||
|
||||
<!-- unescape +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="unescape">
|
||||
socket.code.<b>unescape(</b>content<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
Removes the URL escaping content coding from a string.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<tt>Content</tt> is the string to be decoded.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
The function returns the decoded string.
|
||||
</p>
|
||||
|
||||
<!-- hexa +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="hexa">
|
||||
socket.code.<b>hexa(</b>content<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
Applies the hexadecimal content coding to a string.
|
||||
Each byte is encoded as the byte hexadecimal
|
||||
representation of its integer value. <p>
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<tt>Content</tt> is the string to be encoded.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
The function returns the encoded string.
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
code = socket.code.hexa("\16\32\255")
|
||||
-- code = "1020ff"
|
||||
</pre>
|
||||
|
||||
<!-- unhexa +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id="unhexa">
|
||||
socket.code.<b>unhexa(</b>content<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
Removes the hexadecimal content coding from a string.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<tt>Content</tt> is the string to be decoded.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
The function returns the decoded string.
|
||||
</p>
|
||||
|
||||
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<div class=footer>
|
||||
<hr>
|
||||
<center>
|
||||
<p class=bar>
|
||||
<a href="home.html">home</a> ·
|
||||
<a href="home.html#down">download</a> ·
|
||||
<a href="introduction.html">introduction</a> ·
|
||||
<a href="reference.html">reference</a>
|
||||
</p>
|
||||
<p>
|
||||
<small>
|
||||
Last modified by Diego Nehab on <br>
|
||||
Sat Aug 9 01:00:41 PDT 2003
|
||||
</small>
|
||||
</p>
|
||||
</center>
|
||||
</div>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@ -82,7 +82,7 @@ Converts from IP address to host name.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
The function a string with the canonic host name of the given
|
||||
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.
|
||||
|
||||
@ -35,31 +35,6 @@
|
||||
|
||||
<h2>Reference</h2>
|
||||
|
||||
<!-- callback +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<blockquote>
|
||||
<a href="callback.html">Callbacks (socket.callback)</a>
|
||||
<blockquote>
|
||||
<a href="callback.html#done">done</a>,
|
||||
<a href="callback.html#fail">fail</a>.
|
||||
</blockquote>
|
||||
<blockquote>
|
||||
<a href="callback.html#send">send</a>:
|
||||
<a href="callback.html#send.chain">chain</a>,
|
||||
<a href="callback.html#send.file">file</a>,
|
||||
<a href="callback.html#send.string">string</a>.
|
||||
</blockquote>
|
||||
<blockquote>
|
||||
<a href="callback.html#receive">receive</a>:
|
||||
<a href="callback.html#receive.chain">chain</a>,
|
||||
<a href="callback.html#receive.file">file</a>,
|
||||
<a href="callback.html#receive.concat">concat</a>.
|
||||
</blockquote>
|
||||
</blockquote>
|
||||
</table>
|
||||
|
||||
<!-- dns ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<blockquote>
|
||||
<a href="dns.html">DNS services (socket.dns)</a>
|
||||
<blockquote>
|
||||
@ -75,34 +50,45 @@
|
||||
<a href="ftp.html">FTP (socket.ftp)</a>
|
||||
<blockquote>
|
||||
<a href="ftp.html#get">get</a>,
|
||||
<a href="ftp.html#get_cb">get_cb</a>,
|
||||
<a href="ftp.html#put">put</a>,
|
||||
<a href="ftp.html#put_cb">put_cb</a>.
|
||||
<a href="ftp.html#open">open</a>.
|
||||
</blockquote>
|
||||
</blockquote>
|
||||
|
||||
<!-- misc ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<blockquote>
|
||||
<a href="global.html">Globals (socket)</a>
|
||||
<a href="global.html">Globals</a>
|
||||
<blockquote>
|
||||
<a href="global.html#bind">bind</a>,
|
||||
<a href="global.html#callback">callback</a>,
|
||||
<a href="global.html#concat">concat</a>,
|
||||
<a href="global.html#connect">connect</a>,
|
||||
<a href="global.html#debug">debug</a>,
|
||||
<a href="global.html#dns">dns</a>,
|
||||
<a href="global.html#ftp">ftp</a>,
|
||||
<a href="global.html#http">http</a>,
|
||||
<a href="global.html#LUASOCKET_LIBNAME">LUASOCKET_LIBNAME</a>,
|
||||
<a href="global.html#mime">mime</a>,
|
||||
<a href="global.html#select">select</a>,
|
||||
<a href="global.html#sleep">sleep</a>,
|
||||
<a href="global.html#smtp">smtp</a>,
|
||||
<a href="global.html#time">time</a>,
|
||||
<a href="global.html#tcp">tcp</a>.
|
||||
<a href="global.html#udp">udp</a>,
|
||||
<a href="global.html#url">url</a>,
|
||||
<a href="global.html#version">version</a>.
|
||||
<a href="global.html#ltn12">ltn12</a>,
|
||||
<a href="global.html#socket">socket</a>.
|
||||
</blockquote>
|
||||
</blockquote>
|
||||
</table>
|
||||
|
||||
<blockquote>
|
||||
<a href="socket.html">LuaSocket namespace (socket)</a>
|
||||
<blockquote>
|
||||
<a href="socket.html#bind">bind</a>,
|
||||
<a href="socket.html#connect">connect</a>,
|
||||
<a href="socket.html#debug">debug</a>,
|
||||
<a href="socket.html#dns">dns</a>,
|
||||
<a href="socket.html#ftp">ftp</a>,
|
||||
<a href="socket.html#http">http</a>,
|
||||
<a href="socket.html#protect">protect</a>,
|
||||
<a href="socket.html#select">select</a>,
|
||||
<a href="socket.html#sink">sink</a>,
|
||||
<a href="socket.html#source">source</a>,
|
||||
<a href="socket.html#sleep">sleep</a>,
|
||||
<a href="socket.html#smtp">smtp</a>,
|
||||
<a href="socket.html#time">time</a>,
|
||||
<a href="socket.html#tcp">tcp</a>,
|
||||
<a href="socket.html#try">try</a>,
|
||||
<a href="socket.html#udp">udp</a>,
|
||||
<a href="socket.html#url">url</a>,
|
||||
<a href="socket.html#version">version</a>.
|
||||
</blockquote>
|
||||
</blockquote>
|
||||
</table>
|
||||
@ -115,15 +101,49 @@
|
||||
<blockquote>
|
||||
<a href="http.html#get">get</a>,
|
||||
<a href="http.html#post">post</a>,
|
||||
<a href="http.html#request">request</a>,
|
||||
<a href="http.html#request_cb">request_cb</a>.
|
||||
<a href="http.html#request">request</a>.
|
||||
</blockquote>
|
||||
</blockquote>
|
||||
|
||||
<!-- ltn12 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<blockquote>
|
||||
<a href="ltn12.html">LTN012 (ltn12)</a>
|
||||
<blockquote>
|
||||
<a href="ltn12.html#filter">filter</a>:
|
||||
<a href="ltn12.html#chain">chain</a>,
|
||||
<a href="ltn12.html#cycle">cycle</a>.
|
||||
</blockquote>
|
||||
<blockquote>
|
||||
<a href="ltn12.html#pump">pump</a>:
|
||||
<a href="ltn12.html#all">all</a>,
|
||||
<a href="ltn12.html#step">step</a>.
|
||||
</blockquote>
|
||||
<blockquote>
|
||||
<a href="ltn12.html#sink">sink</a>:
|
||||
<a href="ltn12.html#chain">chain</a>,
|
||||
<a href="ltn12.html#error">error</a>,
|
||||
<a href="ltn12.html#chain">file</a>,
|
||||
<a href="ltn12.html#file">null</a>,
|
||||
<a href="ltn12.html#simplify">simplify</a>,
|
||||
<a href="ltn12.html#table">table</a>.
|
||||
</blockquote>
|
||||
<blockquote>
|
||||
<a href="ltn12.html#source">source</a>:
|
||||
<a href="ltn12.html#cat">cat</a>,
|
||||
<a href="ltn12.html#chain">chain</a>,
|
||||
<a href="ltn12.html#empty">empty</a>,
|
||||
<a href="ltn12.html#file">file</a>,
|
||||
<a href="ltn12.html#simplify">simplify</a>,
|
||||
<a href="ltn12.html#simplify">rewind</a>,
|
||||
<a href="ltn12.html#simplify">string</a>.
|
||||
</blockquote>
|
||||
</blockquote>
|
||||
|
||||
<!-- mime +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<blockquote>
|
||||
<a href="mime.html">MIME (socket.mime) </a>
|
||||
<a href="mime.html">MIME (mime) </a>
|
||||
<blockquote>
|
||||
<a href="mime.html#high">high-level</a>:
|
||||
<a href="mime.html#normalize">normalize</a>,
|
||||
@ -149,7 +169,9 @@
|
||||
<blockquote>
|
||||
<a href="smtp.html">SMTP (socket.smtp)</a>
|
||||
<blockquote>
|
||||
<a href="smtp.html#mail">mail</a>
|
||||
<a href="smtp.html#mail">open</a>,
|
||||
<a href="smtp.html#message">message</a>,
|
||||
<a href="smtp.html#send">send</a>.
|
||||
</blockquote>
|
||||
</blockquote>
|
||||
|
||||
|
||||
166
doc/stream.html
166
doc/stream.html
@ -1,166 +0,0 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
||||
"http://www.w3.org/TR/html4/strict.dtd">
|
||||
<html>
|
||||
|
||||
<head>
|
||||
<title>LuaSocket: Network support for the Lua language</title>
|
||||
<link rel="stylesheet" href="reference.css" type="text/css">
|
||||
</head>
|
||||
|
||||
<body>
|
||||
|
||||
<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<div class=header>
|
||||
<hr>
|
||||
<center>
|
||||
<table summary="LuaSocket logo">
|
||||
<tr><td align=center><a href="http://www.lua.org">
|
||||
<img border=0 alt="LuaSocket" src="luasocket.png">
|
||||
</a></td></tr>
|
||||
<tr><td align=center valign=top>Network support for the Lua language
|
||||
</td></tr>
|
||||
</table>
|
||||
<p class=bar>
|
||||
<a href="home.html">home</a> ·
|
||||
<a href="home.html#download">download</a> ·
|
||||
<a href="introduction.html">introduction</a> ·
|
||||
<a href="reference.html">reference</a>
|
||||
</p>
|
||||
</center>
|
||||
<hr>
|
||||
</div>
|
||||
|
||||
<!-- stream ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<h2 id=stream>Streaming with Callbacks</h2>
|
||||
|
||||
<p>
|
||||
HTTP, FTP, and SMTP transfers sometimes involve large amounts of
|
||||
information. Sometimes an application needs to generate outgoing data
|
||||
in real time, or needs to process incoming information as it is being
|
||||
received. To address these problems, LuaSocket allows HTTP and SMTP message
|
||||
bodies and FTP file contents to be received or sent through the
|
||||
callback mechanism outlined below.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Instead of returning the entire contents of an entity
|
||||
as strings to the Lua application, the library allows the user to
|
||||
provide a <em>receive callback</em> that will be called with successive
|
||||
chunks of data, as the data becomes available. Conversely, the <em>send
|
||||
callbacks</em> can be used when the application wants to incrementally
|
||||
provide LuaSocket with the data to be sent.
|
||||
</p>
|
||||
|
||||
<!-- tohostname +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name id=receive_cb>
|
||||
<b>receive_cb(</b>chunk, err<b>)</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
The callback provided by the user will be repeatedly called by the
|
||||
library whenever new data is available. Each time it is called, the
|
||||
callback receives successive chunks of downloaded data.
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
<tt>Chunk</tt> contains the current chunk of data.
|
||||
When the transmission is over, the function is called with an
|
||||
empty string (i.e. <tt>""</tt>) as the <tt>chunk</tt>.
|
||||
If an error occurs, the function receives <b><tt>nil</tt></b>
|
||||
as <tt>chunk</tt> and an error message in <tt>err</tt>.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
The callback can abort transmission by returning <b><tt>nil</tt></b> as its first
|
||||
return value, and an optional error message as the
|
||||
second return value. If the application wants to continue receiving
|
||||
data, the function should return non-<b><tt>nil</tt></b> as it's first return
|
||||
value. In this case, the function can optionally return a
|
||||
new callback function, to replace itself, as the second return value.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
Note: The <tt>callback</tt> module provides several standard receive callbacks, including the following:
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
function receive.concat(concat)
|
||||
concat = concat or socket.concat.create()
|
||||
local callback = function(chunk, err)
|
||||
-- if not finished, add chunk
|
||||
if chunk and chunk ~= "" then
|
||||
concat:addstring(chunk)
|
||||
return 1
|
||||
end
|
||||
end
|
||||
return callback, concat
|
||||
end
|
||||
</pre>
|
||||
|
||||
<p class=note>
|
||||
This function creates a new receive callback that concatenates all
|
||||
received chunks into a the same concat object, which can later be
|
||||
queried for its contents.
|
||||
</p>
|
||||
|
||||
<!-- send_cb ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<p class=name>
|
||||
<b>send_cb()</b>
|
||||
</p>
|
||||
|
||||
<p class=description>
|
||||
The callback provided by the user will be repeatedly called whenever the
|
||||
library needs more data to be sent.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
Each time the callback is called, it should return the next chunk of data. It
|
||||
can optionally return, as it's second return value, a new callback to replace
|
||||
itself. The callback can abort the process at any time by returning
|
||||
<b><tt>nil</tt></b> followed by an optional error message.
|
||||
</p>
|
||||
|
||||
<p class=note>
|
||||
Note: Below is the implementation of the <tt>callback.send.file</tt>
|
||||
function. Given an open file handle, it returns a send callback that will send the contents of that file, chunk by chunk.
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
function send.file(file, io_err)
|
||||
-- if successful, return the callback that reads from the file
|
||||
if file then
|
||||
return function()
|
||||
-- send next block of data
|
||||
return (file:read(BLOCKSIZE)) or ""
|
||||
end
|
||||
-- else, return a callback that just aborts the transfer
|
||||
else return fail(io_err or "unable to open file") end
|
||||
end
|
||||
</pre>
|
||||
|
||||
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||
|
||||
<div class=footer>
|
||||
<hr>
|
||||
<center>
|
||||
<p class=bar>
|
||||
<a href="home.html">home</a> ·
|
||||
<a href="home.html#down">download</a> ·
|
||||
<a href="introduction.html">introduction</a> ·
|
||||
<a href="reference.html">reference</a>
|
||||
</p>
|
||||
<p>
|
||||
<small>
|
||||
Last modified by Diego Nehab on <br>
|
||||
Sat Aug 9 01:00:41 PDT 2003
|
||||
</small>
|
||||
</p>
|
||||
</center>
|
||||
</div>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
Loading…
Reference in New Issue
Block a user