diegonehab/luasocket
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Starting the manual. Oh well.

Browse Source
This commit is contained in:
Diego Nehab 2004-05-25 06:51:43 +00:00
parent 5c13076f89
commit c53dad9883
5 changed files with 71 additions and 765 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

348
doc/callback.html
View File

@ -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> &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>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.&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>.
</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> &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>

202
doc/code.html
View File

@ -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> &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>
<!-- 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> &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>

2
doc/dns.html
View File

@ -82,7 +82,7 @@ Converts from IP address to host name.
</p> </p>
<p class=return> <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 <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> the resolver. In case of error, the function returns <b><tt>nil</tt></b>
followed by an error message. followed by an error message.

118
doc/reference.html
View File

@ -35,31 +35,6 @@
<h2>Reference</h2> <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> <blockquote>
<a href="dns.html">DNS services (socket.dns)</a> <a href="dns.html">DNS services (socket.dns)</a>
<blockquote> <blockquote>
@ -75,34 +50,45 @@
<a href="ftp.html">FTP (socket.ftp)</a> <a href="ftp.html">FTP (socket.ftp)</a>
<blockquote> <blockquote>
<a href="ftp.html#get">get</a>, <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">put</a>,
<a href="ftp.html#put_cb">put_cb</a>. <a href="ftp.html#open">open</a>.
</blockquote> </blockquote>
</blockquote> </blockquote>
<!-- misc ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- misc ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<blockquote> <blockquote>
<a href="global.html">Globals (socket)</a> <a href="global.html">Globals</a>
<blockquote> <blockquote>
<a href="global.html#bind">bind</a>, <a href="global.html#LUASOCKET_LIBNAME">LUASOCKET_LIBNAME</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#mime">mime</a>, <a href="global.html#mime">mime</a>,
<a href="global.html#select">select</a>, <a href="global.html#ltn12">ltn12</a>,
<a href="global.html#sleep">sleep</a>, <a href="global.html#socket">socket</a>.
<a href="global.html#smtp">smtp</a>, </blockquote>
<a href="global.html#time">time</a>, </blockquote>
<a href="global.html#tcp">tcp</a>. </table>
<a href="global.html#udp">udp</a>,
<a href="global.html#url">url</a>, <blockquote>
<a href="global.html#version">version</a>. <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>
</blockquote> </blockquote>
</table> </table>
@ -115,15 +101,49 @@
<blockquote> <blockquote>
<a href="http.html#get">get</a>, <a href="http.html#get">get</a>,
<a href="http.html#post">post</a>, <a href="http.html#post">post</a>,
<a href="http.html#request">request</a>, <a href="http.html#request">request</a>.
<a href="http.html#request_cb">request_cb</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>
</blockquote> </blockquote>
<!-- mime +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- mime +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<blockquote> <blockquote>
<a href="mime.html">MIME (socket.mime) </a> <a href="mime.html">MIME (mime) </a>
<blockquote> <blockquote>
<a href="mime.html#high">high-level</a>: <a href="mime.html#high">high-level</a>:
<a href="mime.html#normalize">normalize</a>, <a href="mime.html#normalize">normalize</a>,
@ -149,7 +169,9 @@
<blockquote> <blockquote>
<a href="smtp.html">SMTP (socket.smtp)</a> <a href="smtp.html">SMTP (socket.smtp)</a>
<blockquote> <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>
</blockquote> </blockquote>

166
doc/stream.html
View File

@ -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> &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 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.&nbsp;<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> &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>