aboutsummaryrefslogtreecommitdiff
path: root/doc/stream.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/stream.html
parent5c13076f8936ae6face0779f75c7e6f148e4989e (diff)
downloadluasocket-c53dad98839f5139dcedc128d2545dd2542a7157.tar.gz
luasocket-c53dad98839f5139dcedc128d2545dd2542a7157.tar.bz2
luasocket-c53dad98839f5139dcedc128d2545dd2542a7157.zip
Starting the manual. Oh well.
Diffstat (limited to 'doc/stream.html')
-rw-r--r--doc/stream.html166
1 files changed, 0 insertions, 166 deletions
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-09 17:35:41 +0000