mirror of
https://github.com/lunarmodules/luasocket.git
synced 2024-12-27 04:48:21 +01:00
Adding the callback.lua documentation.
This commit is contained in:
Diego Nehab
parent
68d57dc931
commit
e63f500d24
252
doc/callback.html
Normal file
252
doc/callback.html
Normal file
@ -0,0 +1,252 @@
|
|||||||
|
<!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>
|
||||||
|
ret, err_or_f = <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 <tt>nil</tt>
|
||||||
|
as <tt>chunk</tt> and an error message in <tt>err</tt>.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class=return>
|
||||||
|
The callback can abort transmission by returning <tt>nil</tt> 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-<tt>nil</tt> 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>
|
||||||
|
chunk, err_or_r = <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
|
||||||
|
<tt>nil</tt> 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>
|
||||||
|
|
||||||
|
<!-- predefined +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
|
<h2 id=predefined>Predefined Callbacks</h2>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
The module <tt>callback.lua</tt> 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 <tt>mime.lua</tt> module.
|
||||||
|
</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 will return the contents
|
||||||
|
of a the file, until the file has been entirely sent. When done, the
|
||||||
|
callback closes the file.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class=parameters>
|
||||||
|
<tt>File</tt> is a file open for reading. If <tt>file</tt> is
|
||||||
|
<tt>nil</tt>, <tt>io_err</tt> can contain an error message and the
|
||||||
|
returned callback just aborts transmission with the error message.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class=return>
|
||||||
|
Returns a send callback for the file.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class=note>
|
||||||
|
Note: The function is designed so that it directly accepts the return
|
||||||
|
values of the <tt>io.open</tt> function.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<!-- send.string ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
|
<p class=name id=send.string>
|
||||||
|
<b>send.string(</b>str<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>
|
||||||
|
Returns a send callback for the string, or <tt>nil</tt> if the string is
|
||||||
|
<tt>nil</tt>.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class=note>
|
||||||
|
Note: If any function in the LuaSocket API receives a <tt>nil</tt>
|
||||||
|
send callback, it assumes there is nothing to be sent.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<!-- send.chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
|
<p class=name id=send.string>
|
||||||
|
<b>send.chain(</b>send_cb, filter<b>)</b>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class=description>
|
||||||
|
This function creates a send callback that will send
|
||||||
|
all data that it gets from another callback,
|
||||||
|
after passing the data through a filter.
|
||||||
|
</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>
|
||||||
|
|
||||||
|
(write a note!)
|
||||||
|
|
||||||
|
<!-- 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>
|
||||||
@ -36,7 +36,7 @@
|
|||||||
<h2 id=smtp>SMTP</h2>
|
<h2 id=smtp>SMTP</h2>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
The module <tt>smtp.lua</tt> provides functionality to send e-mail
|
The <tt>smtp.lua</tt> module provides functionality to send e-mail
|
||||||
messages. The implementation conforms to the Simple Mail Transfer Protocol,
|
messages. The implementation conforms to the Simple Mail Transfer Protocol,
|
||||||
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2821.txt">RFC 2821</a>.
|
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2821.txt">RFC 2821</a>.
|
||||||
The other RFC of interest in this implementation is
|
The other RFC of interest in this implementation is
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user