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