aboutsummaryrefslogtreecommitdiff
path: root/doc/callback.html
diff options
context:
space:
mode:
authorDiego Nehab <diego@tecgraf.puc-rio.br>2004-05-25 06:51:43 +0000
committerDiego Nehab <diego@tecgraf.puc-rio.br>2004-05-25 06:51:43 +0000
commitc53dad98839f5139dcedc128d2545dd2542a7157 (patch)
treef50f3aaae16eb8f7001037b1d70b0b7b5f7ee0b6 /doc/callback.html
parent5c13076f8936ae6face0779f75c7e6f148e4989e (diff)
downloadluasocket-c53dad98839f5139dcedc128d2545dd2542a7157.tar.gz
luasocket-c53dad98839f5139dcedc128d2545dd2542a7157.tar.bz2
luasocket-c53dad98839f5139dcedc128d2545dd2542a7157.zip
Starting the manual. Oh well.
Diffstat (limited to 'doc/callback.html')
-rw-r--r--doc/callback.html348
1 files changed, 0 insertions, 348 deletions
diff --git a/doc/callback.html b/doc/callback.html
deleted file mode 100644
index 98b4476..0000000
--- a/doc/callback.html
+++ /dev/null
@@ -1,348 +0,0 @@
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>Callbacks</h2>
37
38<p>
39HTTP, FTP, and SMTP transfers sometimes involve large amounts of
40information. Sometimes an application needs to generate outgoing data
41in real time, or needs to process incoming information as it is being
42received. To address these problems, LuaSocket allows HTTP and SMTP message
43bodies and FTP file contents to be streamed through the
44callback mechanism outlined below.
45</p>
46
47<p>
48Instead of returning the received contents
49as a big 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
52callback</em> mechanism can be used when the application wants to incrementally provide LuaSocket with the data to be sent.
53</p>
54
55<!-- receive +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
56
57<p class=name id=receive>
58<b>receive_cb(</b>chunk, err<b>)</b>
59</p>
60
61<p class=description>
62A receive callback will be repeatedly called by
63LuaSocket whenever new data is available. Each time it is called, the
64callback receives successive chunks of downloaded data.
65</p>
66
67<p class=parameters>
68<tt>Chunk</tt> contains the latest downloaded chunk of data.
69When the transmission is over, the function is called with an
70empty string (i.e.&nbsp;<tt>""</tt>) in <tt>chunk</tt>.
71If an error occurs, the function receives a <b><tt>nil</tt></b>
72<tt>chunk</tt> and an error message in <tt>err</tt>.
73</p>
74
75<p class=return>
76The callback can abort transmission by returning <b><tt>nil</tt></b> as its first
77return value, and an optional error message as the
78second return value. To continue receiving
79data, the function should return non-<b><tt>nil</tt></b> as its first return
80value. Optionally, in this case, it may return a
81second return value, with a new callback function to take its place.
82</p>
83
84<!-- send_cb ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
85
86<p class=name id=send>
87<b>send_cb()</b>
88</p>
89
90<p class=description>
91A send callback will be called whenever LuaSocket
92needs more data to be sent.
93</p>
94
95<p class=return>
96Each time the callback is called, it should return the next chunk of data. It
97can optionally return, as it's second return value, a new callback to replace
98itself. The callback can abort the process at any time by returning
99<b><tt>nil</tt></b> followed by an optional error message.
100</p>
101
102<!-- predefined +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
103
104<h2 id=predefined>Predefined Callbacks</h2>
105
106<p>
107The Callback module provides several predefined callbacks to
108perform the most common input/output operations. Callbacks are provided
109that send and receive contents of files and strings. Furthermore,
110composition functions are provided to chain callbacks with filters, such as
111the filters defined in the <a href=mime.html>MIME</a> module.
112Together, these two modules provide a powerful interface to send and
113receive information.
114</p>
115
116<!-- done +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
117
118<p class=name id=done>
119socket.callback.<b>done()</b>
120</p>
121
122<p class=description>
123This function creates and returns a callback that successfully terminates
124the transmission.
125</p>
126
127<!-- fail +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
128
129<p class=name id=fail>
130socket.callback.<b>fail(</b>message<b>)</b>
131</p>
132
133<p class=description>
134This function creates and returns a callback that aborts the
135transmission with a given error <tt>message</tt>.
136</p>
137
138<!-- receive.concat +++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
139
140<p class=name id=receive.concat>
141socket.callback.<b>receive.concat(</b>cat<b>)</b>
142</p>
143
144<p class=description>
145This function creates a receive callback that stores whatever it receives
146into a concat object. When done, the application can get the contents
147received as a single string, directly from the concat object.
148</p>
149
150<p class=parameters>
151<tt>Cat</tt> is the target concat object, or <b><tt>nil</tt></b>.
152If <tt>cat</tt> is <b><tt>nil</tt></b>, the function creates its own
153concat object.
154</p>
155
156<p class=return>
157The function returns a receive callback for the file, and the concat object
158that will be used to store the received contents.
159</p>
160
161<!-- receive.file +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
162
163<p class=name id=receive.file>
164socket.callback.<b>receive.file(</b>file, io_err<b>)</b>
165</p>
166
167<p class=description>
168This function creates a receive callback that stores whatever it receives
169into a file. When done, the callback closes the file.
170</p>
171
172<p class=parameters>
173<tt>File</tt> is a file handle opened for writing. If <tt>file</tt> is
174<b><tt>nil</tt></b>, <tt>io_err</tt> can contain an error message. In this
175case, the function returns a callback that just aborts
176transmission with the error message.
177</p>
178
179<p class=return>
180The function returns a receive callback for the file.
181</p>
182
183<p class=note>
184Note: This function is designed so that it directly accepts the return
185values of Lua's IO <tt>io.open</tt> library function.
186</p>
187
188<!-- receive.chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
189
190<p class=name id=receive.chain>
191socket.callback.<b>receive.chain(</b>filter, receive_cb<b>)</b>
192</p>
193
194<p class=description>
195This function creates a receive callback that passes all received data
196through a filter, before handing it to a given receive callback.
197</p>
198
199<p class=parameters>
200<tt>Cat</tt> is the target concat object, or <b><tt>nil</tt></b>.
201If <tt>cat</tt> is <b><tt>nil</tt></b>, the function creates its own
202concat object.
203</p>
204
205<p class=return>
206The function returns a receive callback for the file, and the concat object
207that will be used to store the received contents.
208</p>
209
210<p class=note>
211Note: Several filters are defined in the <a href=mime.html>MIME</a>
212module. Below is an example that creates a receive callback that
213creates a string from the received contents, after decoding the
214Quoted-Printable transfer content encoding.
215</p>
216
217<pre class=example>
218string_cb, concat = socket.callback.receive.concat()
219receive_cb = socket.callback.receive.chain(
220 socket.mime.decode("quoted-printable"),
221 string_cb
222)
223</pre>
224
225<p class=note>
226The call to <tt>callback.chain</tt> creates a chained
227receive callback that decodes data using the
228<tt><a href=mime.html#decode>mime.decode</a></tt>
229Quoted-Printable MIME filter and
230hands the decoded data to a concat receive callback.
231The concatenated decoded data can be retrieved later
232from the associated concat object.
233</p>
234
235<!-- send.file ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
236
237<p class=name id=send.file>
238socket.callback.<b>send.file(</b>file, io_err<b>)</b>
239</p>
240
241<p class=description>
242This function creates a send callback that returns the contents
243of a file, chunk by chunk, until the file has been entirely sent.
244When done, the callback closes the file.
245</p>
246
247<p class=parameters>
248<tt>File</tt> is a file handle opened for reading. If <tt>file</tt> is
249<b><tt>nil</tt></b>, <tt>io_err</tt> can contain an error message. In this
250case, the function returns a callback that just aborts
251transmission with the error message.
252</p>
253
254<p class=return>
255The function returns a send callback for the file.
256</p>
257
258<p class=note>
259Note: This function is designed so that it directly accepts the return
260values of Lua's IO <tt>io.open</tt> library function.
261</p>
262
263<!-- send.string ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
264
265<p class=name id=send.string>
266socket.callback.<b>send.string(</b>str, err<b>)</b>
267</p>
268
269<p class=description>
270This function creates a send callback that will send
271the contents of a string.
272</p>
273
274<p class=parameters>
275<tt>Str</tt> is the string to be sent.
276</p>
277
278<p class=return>
279It returns a send callback for the string,
280or <b><tt>nil</tt></b> if <tt>str</tt> is <b><tt>nil</tt></b>.
281</p>
282
283<!-- send.chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
284
285<p class=name id=send.chain>
286socket.callback.<b>send.chain(</b>send_cb, filter<b>)</b>
287</p>
288
289<p class=description>
290This function creates a send callback that will filter
291all the data it receives from another send callback, before
292sending it through.
293</p>
294
295<p class=parameters>
296<tt>Send_cb</tt> is the send callback to be chained to <tt>filter</tt>.
297</p>
298
299<p class=return>
300Returns a callback chained with the filter.
301</p>
302
303<p class=note>
304Note: Several filters are defined in the <a href=mime.html>MIME</a>
305module. Below is an example that creates a send callback that sends
306a file's contents encoded in the Base64 transfer content encoding.
307</p>
308
309<pre class=example>
310send_cb = socket.callback.send.chain(
311 socket.callback.send.file(io.open("input.bin"))
312 socket.mime.chain(
313 socket.mime.encode("base64"),
314 socket.mime.wrap("base64")
315 )
316)
317</pre>
318
319<p class=note>
320The call to <a href=mime.html#chain><tt>mime.chain</tt></a>
321creates a chained filter that encodes it's input and then breaks it
322into lines. The call to <tt>callback.chain</tt> creates a chained
323send callback that reads the file from disk and passes it through the
324filter before sending it.
325</p>
326
327<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
328
329<div class=footer>
330<hr>
331<center>
332<p class=bar>
333<a href="home.html">home</a> &middot;
334<a href="home.html#down">download</a> &middot;
335<a href="introduction.html">introduction</a> &middot;
336<a href="reference.html">reference</a>
337</p>
338<p>
339<small>
340Last modified by Diego Nehab on <br>
341Sat Aug 9 01:00:41 PDT 2003
342</small>
343</p>
344</center>
345</div>
346
347</body>
348</html>
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-12-30 06:23:54 +0000