From 62a4c505e488c714e8795ea85564504562d30301 Mon Sep 17 00:00:00 2001 From: Diego Nehab Date: Sat, 24 Jan 2004 02:47:24 +0000 Subject: Working on the manual... Making better tests for error messages. Changed a few names. Moved gethostname to inet.c. --- doc/callback.html | 160 +++++++++++++++++++++++++----------------------------- 1 file changed, 73 insertions(+), 87 deletions(-) (limited to 'doc/callback.html') diff --git a/doc/callback.html b/doc/callback.html index 2c7ecd5..94af8ff 100644 --- a/doc/callback.html +++ b/doc/callback.html @@ -45,113 +45,72 @@ 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 +Instead of returning the received contents +as a big 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. +callback mechanism 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) +

+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. +A receive callback will be repeatedly called by +LuaSocket wheneve 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. +Chunk contains the latest downloaded chunk of data. +When the transmission is over, the function is called with an +empty string (i.e. "") in chunk. +If an error occurs, the function receives a nil +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. +The callback can abort transmission by returning nil as its first +return value, and an optional error message as the +second return value. To continue receiving +data, the function should return non-nil as its first return +value. Optionally, in this case, it may return a +second return value, with a new callback function to take its place.

-

-chunk, err_or_r = send_cb() +

+send_cb()

-The callback provided by the user will be repeatedly called whenever the -library needs more data to be sent. +A send callback will be called whenever LuaSocket +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. +nil followed by an optional error message.

-
-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 +The Callback module 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. +the filters defined in the MIME module. +Together, these two modules provide a powerful interface to send and +receive information.

@@ -161,15 +120,16 @@ the filters defined in the mime.lua module.

-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. +This function creates a send callback that returns the contents +of a file, chunk by chunk, 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. +File is a file opened for reading. If file is +nil, io_err can contain an error message. In this +case, the function returns a callback that just aborts +transmission with the error message.

@@ -177,14 +137,14 @@ Returns a send callback for the file.

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

-send.string(str) +send.string(str, err)

@@ -193,29 +153,33 @@ the contents of a string.

-Str is the string to be sent. +Str is the string to be sent. +

-Returns a send callback for the string, or nil if the string is -nil. +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. +Note: A nil +send callback is equivalent to a callback that returns the empty string.

-

+

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. +This function creates a send callback that will filter +all the data it receives from another send callback, before +sending it through.

@@ -226,7 +190,29 @@ after passing the data through a filter. Returns a callback chained with the filter.

-(write a note!) +

+Note: Several filters are defined in the MIME +module. Below is an example that creates a send callback that sends +a file's contents encoded in the Base64 transfer content encoding. +

+ +
+send_cb = socket.callback.send.chain(
+   socket.callback.send.file(io.open("input.bin"))
+   socket.mime.chain(
+       socket.mime.encode("base64"),
+       socket.mime.wrap("base64")
+   )
+)
+
+ +

+The call to socket.mime.chain +creates a chained filter that encodes it's input and then breaks it +into lines. The call to socket.callback.chain creates a chained +send callback that reads the file from disk and passes it through the +filter before sending it. +

-- cgit v1.2.3-55-g6feb