aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDiego Nehab <diego@tecgraf.puc-rio.br>2004-01-21 06:33:47 +0000
committerDiego Nehab <diego@tecgraf.puc-rio.br>2004-01-21 06:33:47 +0000
commite63f500d24ff0238425c9e13f220daf09a277ef5 (patch)
tree52dd4ac536c2dbba1284476584e79442b3dda7ef
parent68d57dc931e3567e46fddf08036a3328df8b6d2e (diff)
downloadluasocket-e63f500d24ff0238425c9e13f220daf09a277ef5.tar.gz
luasocket-e63f500d24ff0238425c9e13f220daf09a277ef5.tar.bz2
luasocket-e63f500d24ff0238425c9e13f220daf09a277ef5.zip
Adding the callback.lua documentation.
Diffstat
-rw-r--r--doc/callback.html252
-rw-r--r--doc/smtp.html2
2 files changed, 253 insertions, 1 deletions
diff --git a/doc/callback.html b/doc/callback.html
new file mode 100644
index 0000000..2c7ecd5
--- /dev/null
+++ b/doc/callback.html
@@ -0,0 +1,252 @@
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>
59ret, err_or_f = <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 <tt>nil</tt>
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 <tt>nil</tt> 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-<tt>nil</tt> 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>
112chunk, err_or_r = <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<tt>nil</tt> 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<!-- predefined +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
146
147<h2 id=predefined>Predefined Callbacks</h2>
148
149<p>
150The module <tt>callback.lua</tt> provides several predefined callbacks to
151perform the most common input/output operations. Callbacks are provided
152that send and receive contents of files and strings. Furthermore,
153composition functions are provided to chain callbacks with filters, such as
154the filters defined in the <tt>mime.lua</tt> module.
155</p>
156
157<!-- send.file ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
158
159<p class=name id=send.file>
160<b>send.file</b>(file, io_err<b>)</b>
161</p>
162
163<p class=description>
164This function creates a send callback that will return the contents
165of a the file, until the file has been entirely sent. When done, the
166callback closes the file.
167</p>
168
169<p class=parameters>
170<tt>File</tt> is a file open for reading. If <tt>file</tt> is
171<tt>nil</tt>, <tt>io_err</tt> can contain an error message and the
172returned callback just aborts transmission with the error message.
173</p>
174
175<p class=return>
176Returns a send callback for the file.
177</p>
178
179<p class=note>
180Note: The function is designed so that it directly accepts the return
181values of the <tt>io.open</tt> function.
182</p>
183
184<!-- send.string ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
185
186<p class=name id=send.string>
187<b>send.string(</b>str<b>)</b>
188</p>
189
190<p class=description>
191This function creates a send callback that will send
192the contents of a string.
193</p>
194
195<p class=parameters>
196<tt>Str</tt> is the string to be sent.
197</p>
198
199<p class=return>
200Returns a send callback for the string, or <tt>nil</tt> if the string is
201<tt>nil</tt>.
202</p>
203
204<p class=note>
205Note: If any function in the LuaSocket API receives a <tt>nil</tt>
206send callback, it assumes there is nothing to be sent.
207</p>
208
209<!-- send.chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
210
211<p class=name id=send.string>
212<b>send.chain(</b>send_cb, filter<b>)</b>
213</p>
214
215<p class=description>
216This function creates a send callback that will send
217all data that it gets from another callback,
218after passing the data through a filter.
219</p>
220
221<p class=parameters>
222<tt>Send_cb</tt> is the send callback to be chained to <tt>filter</tt>.
223</p>
224
225<p class=return>
226Returns a callback chained with the filter.
227</p>
228
229(write a note!)
230
231<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
232
233<div class=footer>
234<hr>
235<center>
236<p class=bar>
237<a href="home.html">home</a> &middot;
238<a href="home.html#down">download</a> &middot;
239<a href="introduction.html">introduction</a> &middot;
240<a href="reference.html">reference</a>
241</p>
242<p>
243<small>
244Last modified by Diego Nehab on <br>
245Sat Aug 9 01:00:41 PDT 2003
246</small>
247</p>
248</center>
249</div>
250
251</body>
252</html>
diff --git a/doc/smtp.html b/doc/smtp.html
index 3a30a07..aa92149 100644
--- a/doc/smtp.html
+++ b/doc/smtp.html
@@ -36,7 +36,7 @@
36<h2 id=smtp>SMTP</h2> 36<h2 id=smtp>SMTP</h2>
37 37
38<p> 38<p>
39The module <tt>smtp.lua</tt> provides functionality to send e-mail 39The <tt>smtp.lua</tt> module provides functionality to send e-mail
40messages. The implementation conforms to the Simple Mail Transfer Protocol, 40messages. The implementation conforms to the Simple Mail Transfer Protocol,
41<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2821.txt">RFC 2821</a>. 41<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2821.txt">RFC 2821</a>.
42The other RFC of interest in this implementation is 42The other RFC of interest in this implementation is
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-03-22 15:01:34 +0000