From e63f500d24ff0238425c9e13f220daf09a277ef5 Mon Sep 17 00:00:00 2001 From: Diego Nehab Date: Wed, 21 Jan 2004 06:33:47 +0000 Subject: [PATCH] Adding the callback.lua documentation. --- doc/callback.html | 252 ++++++++++++++++++++++++++++++++++++++++++++++ doc/smtp.html | 2 +- 2 files changed, 253 insertions(+), 1 deletion(-) create mode 100644 doc/callback.html 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 @@ + + + + +LuaSocket: Network support for the Lua language + + + + + + + +
+
+
+ + + +
+LuaSocket +
Network support for the Lua language +
+

+home · +download · +introduction · +reference +

+
+
+
+ + + +

Streaming with Callbacks

+ +

+HTTP, FTP, and SMTP transfers sometimes involve large amounts of +information. Sometimes an application needs to generate outgoing data +in real time, or needs to process incoming information as it is being +received. To address these problems, LuaSocket allows HTTP and SMTP message +bodies and FTP file contents to be received or sent through the +callback mechanism outlined below. +

+ +

+Instead of returning the entire contents of an entity +as strings to the Lua application, the library allows the user to +provide a receive callback that will be called with successive +chunks of data, as the data becomes available. Conversely, the send +callbacks can be used when the application wants to incrementally +provide LuaSocket with the data to be sent. +

+ + + +

+ret, err_or_f = receive_cb(chunk, err) +

+ +

+The callback provided by the user will be repeatedly called by the +library whenever new data is available. Each time it is called, the +callback receives successive chunks of downloaded data. +

+ +

+Chunk contains the current chunk of data. +When the transmission is over, the function is called with an +empty string (i.e. "") as the chunk. +If an error occurs, the function receives nil +as chunk and an error message in err. +

+ +

+The callback can abort transmission by returning nil as its first +return value, and an optional error message as the +second return value. If the application wants to continue receiving +data, the function should return non-nil as it's first return +value. In this case, the function can optionally return a +new callback function, to replace itself, as the second return value. +

+ +

+Note: The callback module provides several standard receive callbacks, including the following: +

+ +
+function receive.concat(concat)
+    concat = concat or socket.concat.create()
+    local callback = function(chunk, err)
+        -- if not finished, add chunk
+        if chunk and chunk ~= "" then
+            concat:addstring(chunk)
+            return 1
+        end
+    end
+    return callback, concat
+end
+
+ +

+This function creates a new receive callback that concatenates all +received chunks into a the same concat object, which can later be +queried for its contents. +

+ + + +

+chunk, err_or_r = send_cb() +

+ +

+The callback provided by the user will be repeatedly called whenever the +library needs more data to be sent. +

+ +

+Each time the callback is called, it should return the next chunk of data. It +can optionally return, as it's second return value, a new callback to replace +itself. The callback can abort the process at any time by returning +nil followed by an optional error message. +

+ +

+Note: Below is the implementation of the callback.send.file +function. Given an open file handle, it returns a send callback that will send the contents of that file, chunk by chunk. +

+ +
+function send.file(file, io_err)
+    -- if successful, return the callback that reads from the file
+    if file then
+        return function()
+            -- send next block of data
+            return (file:read(BLOCKSIZE)) or ""
+        end
+    -- else, return a callback that just aborts the transfer
+    else return fail(io_err or "unable to open file") end
+end
+
+ + + +

Predefined Callbacks

+ +

+The module callback.lua provides several predefined callbacks to +perform the most common input/output operations. Callbacks are provided +that send and receive contents of files and strings. Furthermore, +composition functions are provided to chain callbacks with filters, such as +the filters defined in the mime.lua module. +

+ + + +

+send.file(file, io_err) +

+ +

+This function creates a send callback that will return the contents +of a the file, until the file has been entirely sent. When done, the +callback closes the file. +

+ +

+File is a file open for reading. If file is +nil, io_err can contain an error message and the +returned callback just aborts transmission with the error message. +

+ +

+Returns a send callback for the file. +

+ +

+Note: The function is designed so that it directly accepts the return +values of the io.open function. +

+ + + +

+send.string(str) +

+ +

+This function creates a send callback that will send +the contents of a string. +

+ +

+Str is the string to be sent. +

+ +

+Returns a send callback for the string, or nil if the string is +nil. +

+ +

+Note: If any function in the LuaSocket API receives a nil +send callback, it assumes there is nothing to be sent. +

+ + + +

+send.chain(send_cb, filter) +

+ +

+This function creates a send callback that will send +all data that it gets from another callback, +after passing the data through a filter. +

+ +

+Send_cb is the send callback to be chained to filter. +

+ +

+Returns a callback chained with the filter. +

+ +(write a note!) + + + +
+
+
+

+home · +download · +introduction · +reference +

+

+ +Last modified by Diego Nehab on
+Sat Aug 9 01:00:41 PDT 2003 + +

+
+
+ + + 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 @@

SMTP

-The module smtp.lua provides functionality to send e-mail +The smtp.lua module provides functionality to send e-mail messages. The implementation conforms to the Simple Mail Transfer Protocol, RFC 2821. The other RFC of interest in this implementation is