LuaSocket: Network support for the Lua language

From c53dad98839f5139dcedc128d2545dd2542a7157 Mon Sep 17 00:00:00 2001 From: Diego Nehab Date: Tue, 25 May 2004 06:51:43 +0000 Subject: Starting the manual. Oh well. --- doc/callback.html | 348 ------------------------------------------------------ 1 file changed, 348 deletions(-) delete mode 100644 doc/callback.html (limited to 'doc/callback.html') diff --git a/doc/callback.html b/doc/callback.html deleted file mode 100644 index 98b4476..0000000 --- a/doc/callback.html +++ /dev/null @@ -1,348 +0,0 @@ - - - - -LuaSocket: Network support for the Lua language - - - - - - - - - - - -

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 streamed through the -callback mechanism outlined below. -

- -

-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 -callback mechanism can be used when the application wants to incrementally provide LuaSocket with the data to be sent. -

- - - -

-receive_cb(chunk, err) -

- -

-A receive callback will be repeatedly called by -LuaSocket whenever new data is available. Each time it is called, the -callback receives successive chunks of downloaded data. -

- -

-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. 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. -

- - - -

-send_cb() -

- -

-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. -

- - - -

Predefined Callbacks

- -

-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 module. -Together, these two modules provide a powerful interface to send and -receive information. -

- - - -

-socket.callback.done() -

- -

-This function creates and returns a callback that successfully terminates -the transmission. -

- - - -

-socket.callback.fail(message) -

- -

-This function creates and returns a callback that aborts the -transmission with a given error message. -

- - - -

-socket.callback.receive.concat(cat) -

- -

-This function creates a receive callback that stores whatever it receives -into a concat object. When done, the application can get the contents -received as a single string, directly from the concat object. -

- -

-Cat is the target concat object, or nil. -If cat is nil, the function creates its own -concat object. -

- -

-The function returns a receive callback for the file, and the concat object -that will be used to store the received contents. -

- - - -

-socket.callback.receive.file(file, io_err) -

- -

-This function creates a receive callback that stores whatever it receives -into a file. When done, the callback closes the file. -

- -

-File is a file handle opened for writing. 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. -

- -

-The function returns a receive callback for the file. -

- -

-Note: This function is designed so that it directly accepts the return -values of Lua's IO io.open library function. -

- - - -

-socket.callback.receive.chain(filter, receive_cb) -

- -

-This function creates a receive callback that passes all received data -through a filter, before handing it to a given receive callback. -

- -

-Cat is the target concat object, or nil. -If cat is nil, the function creates its own -concat object. -

- -

-The function returns a receive callback for the file, and the concat object -that will be used to store the received contents. -

- -

-Note: Several filters are defined in the MIME -module. Below is an example that creates a receive callback that -creates a string from the received contents, after decoding the -Quoted-Printable transfer content encoding. -

- -

-string_cb, concat = socket.callback.receive.concat()
-receive_cb = socket.callback.receive.chain(
-   socket.mime.decode("quoted-printable"),
-   string_cb
-)
-

- -

-The call to callback.chain creates a chained -receive callback that decodes data using the -mime.decode -Quoted-Printable MIME filter and -hands the decoded data to a concat receive callback. -The concatenated decoded data can be retrieved later -from the associated concat object. -

- - - -

-socket.callback.send.file(file, io_err) -

- -

-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 handle 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. -

- -

-The function returns a send callback for the file. -

- -

-Note: This function is designed so that it directly accepts the return -values of Lua's IO io.open library function. -

- - - -

-socket.callback.send.string(str, err) -

- -

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

- -

-Str is the string to be sent. -

- -

-It returns a send callback for the string, -or nil if str is nil. -

- - - -

-socket.callback.send.chain(send_cb, filter) -

- -

-This function creates a send callback that will filter -all the data it receives from another send callback, before -sending it through. -

- -

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

- -

-Returns a callback chained with the filter. -

- -

-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 mime.chain -creates a chained filter that encodes it's input and then breaks it -into lines. The call to 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