aboutsummaryrefslogtreecommitdiff
path: root/doc/stream.html
diff options
context:
space:
mode:
authorDiego Nehab <diego@tecgraf.puc-rio.br>2003-08-31 01:00:15 +0000
committerDiego Nehab <diego@tecgraf.puc-rio.br>2003-08-31 01:00:15 +0000
commit982781f1464c9b7a8133130433f83dbf1f59a2c0 (patch)
tree8f96f9e9fa1e6bef8b8356037986ddc18673cade /doc/stream.html
parent6789b83ff5c15296267f880d3b98cf8a1800c30a (diff)
downloadluasocket-982781f1464c9b7a8133130433f83dbf1f59a2c0.tar.gz
luasocket-982781f1464c9b7a8133130433f83dbf1f59a2c0.tar.bz2
luasocket-982781f1464c9b7a8133130433f83dbf1f59a2c0.zip
LuaSocket 2.0 User's Manual.
Diffstat (limited to 'doc/stream.html')
-rw-r--r--doc/stream.html173
1 files changed, 173 insertions, 0 deletions
diff --git a/doc/stream.html b/doc/stream.html
new file mode 100644
index 0000000..296ca2e
--- /dev/null
+++ b/doc/stream.html
@@ -0,0 +1,173 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
3<html>
4
5<head>
6<title>LuaSocket: Network support for the Lua language</title>
7<link rel="stylesheet" href="reference.css" type="text/css">
8</head>
9
10<body>
11
12<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
13
14<div class=header>
15<hr>
16<center>
17<table summary="LuaSocket logo">
18<tr><td align=center><a href="http://www.lua.org">
19<img border=0 alt="LuaSocket" src="luasocket.png">
20</a></td></tr>
21<tr><td align=center valign=top>Network support for the Lua language
22</td></tr>
23</table>
24<p class=bar>
25<a href="home.html">home</a> &middot;
26<a href="home.html#download">download</a> &middot;
27<a href="introduction.html">introduction</a> &middot;
28<a href="reference.html">reference</a>
29</p>
30</center>
31<hr>
32</div>
33
34<!-- stream ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
35
36<h2 id=stream>Streaming with Callbacks</h2>
37
38<p>
39HTTP and FTP transfers sometimes involve large amounts of information.
40Sometimes an application needs to generate outgoing data in real time,
41or needs to process incoming information as it is being received. To
42address these problems, LuaSocket allows HTTP message bodies and FTP
43file contents to be received or sent through the callback mechanism
44outlined below.
45</p>
46
47<p>
48Instead of returning the entire contents of a FTP file or HTTP message
49body as strings to the Lua application, the library allows the user to
50provide a <em>receive callback</em> that will be called with successive
51chunks of data, as the data becomes available. Conversely, the <em>send
52callbacks</em> should be used when data needed by LuaSocket
53is generated incrementally by the application.
54</p>
55
56<!-- tohostname +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
57
58<p class=name id=receive_cb>
59<b>receive_cb(</b>chunk, err<b>)</b>
60</p>
61
62<p class=description>
63The callback provided by the user will be repeatedly called by the
64library whenever new data is available. Each time it is called, the
65callback receives successive chunks of downloaded data.
66</p>
67
68<p class=parameters>
69<tt>Chunk</tt> contains the current chunk of data.
70When the transmission is over, the function is called with an
71empty string (i.e.&nbsp;<tt>""</tt>) as the <tt>chunk</tt>. If an error occurs, the
72function receives <tt>nil</tt> as <tt>chunk</tt> and an error message as
73<tt>err</tt>.
74</p>
75
76<p class=return>
77The callback can abort transmission by returning
78<tt>nil</tt> as its first return value. In that case, it can also return
79an error message. Any non-<tt>nil</tt> return value proceeds with the
80transmission.
81</p>
82
83<pre class=example>
84-- The implementation of socket.callback.receive_concat
85function Public.receive_concat(concat)
86 concat = concat or socket.concat.create()
87 local callback = function(chunk, err)
88 -- if not finished, add chunk
89 if chunk and chunk ~= "" then
90 concat:addstring(chunk)
91 return 1
92 end
93 end
94 return callback, concat
95end
96</pre>
97
98<!-- send_cb ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
99
100<p class=name>
101<b>send_cb()</b>
102</p>
103
104<p class=description>
105The callback provided by the user will be repeatedly called whenever the
106library needs more data to be sent.
107</p>
108
109<p class=return>
110Each time the callback is called, it
111should return the next part of the information the library is expecting,
112followed by the total number of bytes to be sent.
113The callback can abort
114the process at any time by returning <tt>nil</tt> followed by an
115optional error message.
116</p>
117
118
119<p class=note>
120Note: The need for the second return value comes from the fact that, with
121the HTTP protocol for instance, the library needs to know in advance the
122total number of bytes that will be sent.
123</p>
124
125<pre class=example>
126-- The implementation of socket.callback.send_file
127function Public.send_file(file)
128 local callback
129 -- if successfull, return the callback that reads from the file
130 if file then
131 -- get total size
132 local size = file:seek("end")
133 -- go back to start of file
134 file:seek("set")
135 callback = function()
136 -- send next block of data
137 local chunk = file:read(Public.BLOCKSIZE)
138 if not chunk then file:close() end
139 return chunk, size
140 end
141 -- else, return a callback that just aborts the transfer
142 else
143 callback = function()
144 -- just abort
145 return nil, "unable to open file"
146 end
147 end
148 return callback, file
149end
150</pre>
151
152<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
153
154<div class=footer>
155<hr>
156<center>
157<p class=bar>
158<a href="home.html">home</a> &middot;
159<a href="home.html#down">download</a> &middot;
160<a href="introduction.html">introduction</a> &middot;
161<a href="reference.html">reference</a>
162</p>
163<p>
164<small>
165Last modified by Diego Nehab on <br>
166Sat Aug 9 01:00:41 PDT 2003
167</small>
168</p>
169</center>
170</div>
171
172</body>
173</html>
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2026-01-27 23:38:01 +0000