mirror of
https://github.com/lunarmodules/luasocket.git
synced 2024-11-19 11:48:21 +01:00
349 lines
10 KiB
HTML
349 lines
10 KiB
HTML
<!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>
|