mirror of
https://github.com/lunarmodules/luasocket.git
synced 2024-11-19 11:48:21 +01:00
174 lines
5.0 KiB
HTML
174 lines
5.0 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>Streaming with Callbacks</h2>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
HTTP and FTP 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 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 a FTP file or HTTP message
|
||
|
|
body 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> should be used when data needed by LuaSocket
|
||
|
|
is generated incrementally by the application.
|
||
|
|
</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 <tt>nil</tt> as <tt>chunk</tt> and an error message as
|
||
|
|
<tt>err</tt>.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<p class=return>
|
||
|
|
The callback can abort transmission by returning
|
||
|
|
<tt>nil</tt> as its first return value. In that case, it can also return
|
||
|
|
an error message. Any non-<tt>nil</tt> return value proceeds with the
|
||
|
|
transmission.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<pre class=example>
|
||
|
|
-- The implementation of socket.callback.receive_concat
|
||
|
|
function Public.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>
|
||
|
|
|
||
|
|
<!-- 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 part of the information the library is expecting,
|
||
|
|
followed by the total number of bytes to be sent.
|
||
|
|
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: The need for the second return value comes from the fact that, with
|
||
|
|
the HTTP protocol for instance, the library needs to know in advance the
|
||
|
|
total number of bytes that will be sent.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<pre class=example>
|
||
|
|
-- The implementation of socket.callback.send_file
|
||
|
|
function Public.send_file(file)
|
||
|
|
local callback
|
||
|
|
-- if successfull, return the callback that reads from the file
|
||
|
|
if file then
|
||
|
|
-- get total size
|
||
|
|
local size = file:seek("end")
|
||
|
|
-- go back to start of file
|
||
|
|
file:seek("set")
|
||
|
|
callback = function()
|
||
|
|
-- send next block of data
|
||
|
|
local chunk = file:read(Public.BLOCKSIZE)
|
||
|
|
if not chunk then file:close() end
|
||
|
|
return chunk, size
|
||
|
|
end
|
||
|
|
-- else, return a callback that just aborts the transfer
|
||
|
|
else
|
||
|
|
callback = function()
|
||
|
|
-- just abort
|
||
|
|
return nil, "unable to open file"
|
||
|
|
end
|
||
|
|
end
|
||
|
|
return callback, file
|
||
|
|
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>
|