aboutsummaryrefslogtreecommitdiff
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
parent5c13076f8936ae6face0779f75c7e6f148e4989e (diff)
downloadluasocket-c53dad98839f5139dcedc128d2545dd2542a7157.tar.gz
luasocket-c53dad98839f5139dcedc128d2545dd2542a7157.tar.bz2
luasocket-c53dad98839f5139dcedc128d2545dd2542a7157.zip
Starting the manual. Oh well.
Diffstat
-rw-r--r--doc/callback.html348
-rw-r--r--doc/code.html202
-rw-r--r--doc/dns.html2
-rw-r--r--doc/reference.html118
-rw-r--r--doc/stream.html166
5 files changed, 71 insertions, 765 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>
diff --git a/doc/code.html b/doc/code.html
deleted file mode 100644
index 4668b7a..0000000
--- a/doc/code.html
+++ /dev/null
@@ -1,202 +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<!-- code +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
35
36<h2 id=code>Code</h2>
37
38<p>
39The <tt>code.lua</tt> module offers routines to convert back and forth
40some common types of content encoding, including Base 64 and URL
41escaping. Base 64 is described in
42<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2045.txt">RFC
432045</a>,
44URL escaping is described in
45<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2396.txt">RFC
462396</a>.
47</p>
48
49<!-- base64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
50
51<p class=name id="base64">
52socket.code.<b>base64(</b>content, single<b>)</b>
53</p>
54
55<p class=description>
56Applies the Base 64 content coding to a string.
57</p>
58
59<p class=parameters>
60<tt>Content</tt> is the string to be encoded.
61If <tt>single</tt> is set to anything
62but <b><tt>nil</tt></b>, the output is returned as a single
63line, otherwise the function splits the content into 76 character long
64lines after encoding.
65</p>
66
67<p class=result>
68The function returns the encoded string.
69</p>
70
71<pre class=example>
72code = socket.code.base64("diego:password")
73-- code = "ZGllZ286cGFzc3dvcmQ="
74</pre>
75
76<!-- unbase64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
77
78<p class=name id="unbase64">
79socket.code.<b>unbase64(</b>content<b>)</b>
80</p>
81
82<p class=description>
83Removes the Base 64 content coding from a string.
84</p>
85
86<p class=parameters>
87<tt>Content</tt> is the string to be decoded.
88</p>
89
90<p class=result>
91The function returns the decoded string.
92</p>
93
94<!-- escape +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
95
96<p class=name id="escape">
97socket.code.<b>escape(</b>content<b>)</b>
98</p>
99
100<p class=description>
101Applies the URL escaping content coding to a string
102Each byte is encoded as a percent character followed
103by the two byte hexadecimal representation of its integer
104value.
105</p>
106
107<p class=parameters>
108<tt>Content</tt> is the string to be encoded.
109</p>
110
111<p class=result>
112The function returns the encoded string.
113</p>
114
115<pre class=example>
116code = socket.code.escape("/#?;")
117-- code = "%2f%23%3f%3b"
118</pre>
119
120<!-- unescape +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
121
122<p class=name id="unescape">
123socket.code.<b>unescape(</b>content<b>)</b>
124</p>
125
126<p class=description>
127Removes the URL escaping content coding from a string.
128</p>
129
130<p class=parameters>
131<tt>Content</tt> is the string to be decoded.
132</p>
133
134<p class=return>
135The function returns the decoded string.
136</p>
137
138<!-- hexa +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
139
140<p class=name id="hexa">
141socket.code.<b>hexa(</b>content<b>)</b>
142</p>
143
144<p class=description>
145Applies the hexadecimal content coding to a string.
146Each byte is encoded as the byte hexadecimal
147representation of its integer value. <p>
148</p>
149
150<p class=parameters>
151<tt>Content</tt> is the string to be encoded.
152</p>
153
154<p class=return>
155The function returns the encoded string.
156</p>
157
158<pre class=example>
159code = socket.code.hexa("\16\32\255")
160-- code = "1020ff"
161</pre>
162
163<!-- unhexa +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
164
165<p class=name id="unhexa">
166socket.code.<b>unhexa(</b>content<b>)</b>
167</p>
168
169<p class=description>
170Removes the hexadecimal content coding from a string.
171</p>
172
173<p class=parameters>
174<tt>Content</tt> is the string to be decoded.
175</p>
176
177<p class=return>
178The function returns the decoded string.
179</p>
180
181<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
182
183<div class=footer>
184<hr>
185<center>
186<p class=bar>
187<a href="home.html">home</a> &middot;
188<a href="home.html#down">download</a> &middot;
189<a href="introduction.html">introduction</a> &middot;
190<a href="reference.html">reference</a>
191</p>
192<p>
193<small>
194Last modified by Diego Nehab on <br>
195Sat Aug 9 01:00:41 PDT 2003
196</small>
197</p>
198</center>
199</div>
200
201</body>
202</html>
diff --git a/doc/dns.html b/doc/dns.html
index 71a9719..8e63407 100644
--- a/doc/dns.html
+++ b/doc/dns.html
@@ -82,7 +82,7 @@ Converts from IP address to host name.
82</p> 82</p>
83 83
84<p class=return> 84<p class=return>
85The function a string with the canonic host name of the given 85The function returns a string with the canonic host name of the given
86<tt>address</tt>, followed by a table with all information returned by 86<tt>address</tt>, followed by a table with all information returned by
87the resolver. In case of error, the function returns <b><tt>nil</tt></b> 87the resolver. In case of error, the function returns <b><tt>nil</tt></b>
88followed by an error message. 88followed by an error message.
diff --git a/doc/reference.html b/doc/reference.html
index 6e14891..6372e64 100644
--- a/doc/reference.html
+++ b/doc/reference.html
@@ -35,31 +35,6 @@
35 35
36<h2>Reference</h2> 36<h2>Reference</h2>
37 37
38<!-- callback +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
39
40<blockquote>
41<a href="callback.html">Callbacks (socket.callback)</a>
42<blockquote>
43<a href="callback.html#done">done</a>,
44<a href="callback.html#fail">fail</a>.
45</blockquote>
46<blockquote>
47<a href="callback.html#send">send</a>:
48<a href="callback.html#send.chain">chain</a>,
49<a href="callback.html#send.file">file</a>,
50<a href="callback.html#send.string">string</a>.
51</blockquote>
52<blockquote>
53<a href="callback.html#receive">receive</a>:
54<a href="callback.html#receive.chain">chain</a>,
55<a href="callback.html#receive.file">file</a>,
56<a href="callback.html#receive.concat">concat</a>.
57</blockquote>
58</blockquote>
59</table>
60
61<!-- dns ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
62
63<blockquote> 38<blockquote>
64<a href="dns.html">DNS services (socket.dns)</a> 39<a href="dns.html">DNS services (socket.dns)</a>
65<blockquote> 40<blockquote>
@@ -75,34 +50,45 @@
75<a href="ftp.html">FTP (socket.ftp)</a> 50<a href="ftp.html">FTP (socket.ftp)</a>
76<blockquote> 51<blockquote>
77<a href="ftp.html#get">get</a>, 52<a href="ftp.html#get">get</a>,
78<a href="ftp.html#get_cb">get_cb</a>,
79<a href="ftp.html#put">put</a>, 53<a href="ftp.html#put">put</a>,
80<a href="ftp.html#put_cb">put_cb</a>. 54<a href="ftp.html#open">open</a>.
81</blockquote> 55</blockquote>
82</blockquote> 56</blockquote>
83 57
84<!-- misc ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 58<!-- misc ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
85 59
86<blockquote> 60<blockquote>
87<a href="global.html">Globals (socket)</a> 61<a href="global.html">Globals</a>
88<blockquote> 62<blockquote>
89<a href="global.html#bind">bind</a>, 63<a href="global.html#LUASOCKET_LIBNAME">LUASOCKET_LIBNAME</a>,
90<a href="global.html#callback">callback</a>,
91<a href="global.html#concat">concat</a>,
92<a href="global.html#connect">connect</a>,
93<a href="global.html#debug">debug</a>,
94<a href="global.html#dns">dns</a>,
95<a href="global.html#ftp">ftp</a>,
96<a href="global.html#http">http</a>,
97<a href="global.html#mime">mime</a>, 64<a href="global.html#mime">mime</a>,
98<a href="global.html#select">select</a>, 65<a href="global.html#ltn12">ltn12</a>,
99<a href="global.html#sleep">sleep</a>, 66<a href="global.html#socket">socket</a>.
100<a href="global.html#smtp">smtp</a>, 67</blockquote>
101<a href="global.html#time">time</a>, 68</blockquote>
102<a href="global.html#tcp">tcp</a>. 69</table>
103<a href="global.html#udp">udp</a>, 70
104<a href="global.html#url">url</a>, 71<blockquote>
105<a href="global.html#version">version</a>. 72<a href="socket.html">LuaSocket namespace (socket)</a>
73<blockquote>
74<a href="socket.html#bind">bind</a>,
75<a href="socket.html#connect">connect</a>,
76<a href="socket.html#debug">debug</a>,
77<a href="socket.html#dns">dns</a>,
78<a href="socket.html#ftp">ftp</a>,
79<a href="socket.html#http">http</a>,
80<a href="socket.html#protect">protect</a>,
81<a href="socket.html#select">select</a>,
82<a href="socket.html#sink">sink</a>,
83<a href="socket.html#source">source</a>,
84<a href="socket.html#sleep">sleep</a>,
85<a href="socket.html#smtp">smtp</a>,
86<a href="socket.html#time">time</a>,
87<a href="socket.html#tcp">tcp</a>,
88<a href="socket.html#try">try</a>,
89<a href="socket.html#udp">udp</a>,
90<a href="socket.html#url">url</a>,
91<a href="socket.html#version">version</a>.
106</blockquote> 92</blockquote>
107</blockquote> 93</blockquote>
108</table> 94</table>
@@ -115,15 +101,49 @@
115<blockquote> 101<blockquote>
116<a href="http.html#get">get</a>, 102<a href="http.html#get">get</a>,
117<a href="http.html#post">post</a>, 103<a href="http.html#post">post</a>,
118<a href="http.html#request">request</a>, 104<a href="http.html#request">request</a>.
119<a href="http.html#request_cb">request_cb</a>. 105</blockquote>
106</blockquote>
107
108<!-- ltn12 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
109
110<blockquote>
111<a href="ltn12.html">LTN012 (ltn12)</a>
112<blockquote>
113<a href="ltn12.html#filter">filter</a>:
114<a href="ltn12.html#chain">chain</a>,
115<a href="ltn12.html#cycle">cycle</a>.
116</blockquote>
117<blockquote>
118<a href="ltn12.html#pump">pump</a>:
119<a href="ltn12.html#all">all</a>,
120<a href="ltn12.html#step">step</a>.
121</blockquote>
122<blockquote>
123<a href="ltn12.html#sink">sink</a>:
124<a href="ltn12.html#chain">chain</a>,
125<a href="ltn12.html#error">error</a>,
126<a href="ltn12.html#chain">file</a>,
127<a href="ltn12.html#file">null</a>,
128<a href="ltn12.html#simplify">simplify</a>,
129<a href="ltn12.html#table">table</a>.
130</blockquote>
131<blockquote>
132<a href="ltn12.html#source">source</a>:
133<a href="ltn12.html#cat">cat</a>,
134<a href="ltn12.html#chain">chain</a>,
135<a href="ltn12.html#empty">empty</a>,
136<a href="ltn12.html#file">file</a>,
137<a href="ltn12.html#simplify">simplify</a>,
138<a href="ltn12.html#simplify">rewind</a>,
139<a href="ltn12.html#simplify">string</a>.
120</blockquote> 140</blockquote>
121</blockquote> 141</blockquote>
122 142
123<!-- mime +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 143<!-- mime +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
124 144
125<blockquote> 145<blockquote>
126<a href="mime.html">MIME (socket.mime) </a> 146<a href="mime.html">MIME (mime) </a>
127<blockquote> 147<blockquote>
128<a href="mime.html#high">high-level</a>: 148<a href="mime.html#high">high-level</a>:
129<a href="mime.html#normalize">normalize</a>, 149<a href="mime.html#normalize">normalize</a>,
@@ -149,7 +169,9 @@
149<blockquote> 169<blockquote>
150<a href="smtp.html">SMTP (socket.smtp)</a> 170<a href="smtp.html">SMTP (socket.smtp)</a>
151<blockquote> 171<blockquote>
152<a href="smtp.html#mail">mail</a> 172<a href="smtp.html#mail">open</a>,
173<a href="smtp.html#message">message</a>,
174<a href="smtp.html#send">send</a>.
153</blockquote> 175</blockquote>
154</blockquote> 176</blockquote>
155 177
diff --git a/doc/stream.html b/doc/stream.html
deleted file mode 100644
index 585ad18..0000000
--- a/doc/stream.html
+++ /dev/null
@@ -1,166 +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>Streaming with 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 received or sent through the
44callback mechanism outlined below.
45</p>
46
47<p>
48Instead of returning the entire contents of an entity
49as 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> can be used when the application wants to incrementally
53provide LuaSocket with the data to be sent.
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>.
72If an error occurs, the function receives <b><tt>nil</tt></b>
73as <tt>chunk</tt> and an error message in <tt>err</tt>.
74</p>
75
76<p class=return>
77The callback can abort transmission by returning <b><tt>nil</tt></b> as its first
78return value, and an optional error message as the
79second return value. If the application wants to continue receiving
80data, the function should return non-<b><tt>nil</tt></b> as it's first return
81value. In this case, the function can optionally return a
82new callback function, to replace itself, as the second return value.
83</p>
84
85<p class=note>
86Note: The <tt>callback</tt> module provides several standard receive callbacks, including the following:
87</p>
88
89<pre class=example>
90function receive.concat(concat)
91 concat = concat or socket.concat.create()
92 local callback = function(chunk, err)
93 -- if not finished, add chunk
94 if chunk and chunk ~= "" then
95 concat:addstring(chunk)
96 return 1
97 end
98 end
99 return callback, concat
100end
101</pre>
102
103<p class=note>
104This function creates a new receive callback that concatenates all
105received chunks into a the same concat object, which can later be
106queried for its contents.
107</p>
108
109<!-- send_cb ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
110
111<p class=name>
112<b>send_cb()</b>
113</p>
114
115<p class=description>
116The callback provided by the user will be repeatedly called whenever the
117library needs more data to be sent.
118</p>
119
120<p class=return>
121Each time the callback is called, it should return the next chunk of data. It
122can optionally return, as it's second return value, a new callback to replace
123itself. The callback can abort the process at any time by returning
124<b><tt>nil</tt></b> followed by an optional error message.
125</p>
126
127<p class=note>
128Note: Below is the implementation of the <tt>callback.send.file</tt>
129function. Given an open file handle, it returns a send callback that will send the contents of that file, chunk by chunk.
130</p>
131
132<pre class=example>
133function send.file(file, io_err)
134 -- if successful, return the callback that reads from the file
135 if file then
136 return function()
137 -- send next block of data
138 return (file:read(BLOCKSIZE)) or ""
139 end
140 -- else, return a callback that just aborts the transfer
141 else return fail(io_err or "unable to open file") end
142end
143</pre>
144
145<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
146
147<div class=footer>
148<hr>
149<center>
150<p class=bar>
151<a href="home.html">home</a> &middot;
152<a href="home.html#down">download</a> &middot;
153<a href="introduction.html">introduction</a> &middot;
154<a href="reference.html">reference</a>
155</p>
156<p>
157<small>
158Last modified by Diego Nehab on <br>
159Sat Aug 9 01:00:41 PDT 2003
160</small>
161</p>
162</center>
163</div>
164
165</body>
166</html>
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2026-01-06 21:31:51 +0000