luasocket/doc/callback.html

239 lines
7.0 KiB
HTML
Raw Normal View History

2004-01-21 07:33:47 +01:00
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>LuaSocket: Network support for the Lua language</title>
<link rel="stylesheet" href="reference.css" type="text/css">
</head>
<body>
<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=header>
<hr>
<center>
<table summary="LuaSocket logo">
<tr><td align=center><a href="http://www.lua.org">
<img border=0 alt="LuaSocket" src="luasocket.png">
</a></td></tr>
<tr><td align=center valign=top>Network support for the Lua language
</td></tr>
</table>
<p class=bar>
<a href="home.html">home</a> &middot;
<a href="home.html#download">download</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>
</p>
</center>
<hr>
</div>
<!-- stream ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h2 id=stream>Streaming with Callbacks</h2>
<p>
HTTP, 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 received contents
as a big to the Lua application, the library allows the user to
2004-01-21 07:33:47 +01:00
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.
2004-01-21 07:33:47 +01:00
</p>
<!-- tohostname +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=receive>
<b>receive_cb(</b>chunk, err<b>)</b>
2004-01-21 07:33:47 +01:00
</p>
<p class=description>
A receive callback will be repeatedly called by
LuaSocket wheneve new data is available. Each time it is called, the
callback receives successive chunks of downloaded data.
2004-01-21 07:33:47 +01:00
</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.&nbsp;<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>.
2004-01-21 07:33:47 +01:00
</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.
2004-01-21 07:33:47 +01:00
</p>
<!-- send_cb ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=send>
<b>send_cb()</b>
2004-01-21 07:33:47 +01:00
</p>
<p class=description>
A send callback will be called whenever LuaSocket
needs more data to be sent.
2004-01-21 07:33:47 +01:00
</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.
2004-01-21 07:33:47 +01:00
</p>
<!-- predefined +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h2 id=predefined>Predefined Callbacks</h2>
<p>
The Callback module provides several predefined callbacks to
2004-01-21 07:33:47 +01:00
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.
2004-01-21 07:33:47 +01:00
</p>
<!-- send.file ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=send.file>
<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.
2004-01-21 07:33:47 +01:00
</p>
<p class=parameters>
<tt>File</tt> is a file 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.
2004-01-21 07:33:47 +01:00
</p>
<p class=return>
Returns a send callback for the file.
</p>
<p class=note>
Note: This function is designed so that it directly accepts the return
2004-01-21 07:33:47 +01:00
values of the <tt>io.open</tt> function.
</p>
<!-- send.string ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=send.string>
<b>send.string(</b>str, err<b>)</b>
2004-01-21 07:33:47 +01:00
</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.
<!--
If <tt>str</tt> is
<b><tt>nil</tt></b>, <tt>err</tt> can optionally contain an error message.
-->
2004-01-21 07:33:47 +01:00
</p>
<p class=return>
Returns a send callback for the string, or <b><tt>nil</tt></b> if the string is
<b><tt>nil</tt></b>.
2004-01-21 07:33:47 +01:00
</p>
<p class=note>
Note: A <tt>nil</tt></b>
send callback is equivalent to a callback that returns the empty string.
2004-01-21 07:33:47 +01:00
</p>
<!-- send.chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=send.chain>
2004-01-21 07:33:47 +01:00
<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.
2004-01-21 07:33:47 +01:00
</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>socket.mime.chain</tt></a>
creates a chained filter that encodes it's input and then breaks it
into lines. The call to <tt>socket.callback.chain</tt> creates a chained
send callback that reads the file from disk and passes it through the
filter before sending it.
</p>
2004-01-21 07:33:47 +01:00
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=footer>
<hr>
<center>
<p class=bar>
<a href="home.html">home</a> &middot;
<a href="home.html#down">download</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>
</p>
<p>
<small>
Last modified by Diego Nehab on <br>
Sat Aug 9 01:00:41 PDT 2003
</small>
</p>
</center>
</div>
</body>
</html>