From 0b2542d1a61fc5425ff65ab3dbf7ba7de174763f Mon Sep 17 00:00:00 2001 From: Diego Nehab Date: Wed, 4 Feb 2004 14:29:11 +0000 Subject: Worked on the manual. Implemented stuffing (needs test) Added cddb and qp examples. --- doc/callback.html | 158 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 134 insertions(+), 24 deletions(-) (limited to 'doc/callback.html') diff --git a/doc/callback.html b/doc/callback.html index 94af8ff..98b4476 100644 --- a/doc/callback.html +++ b/doc/callback.html @@ -31,16 +31,16 @@
- + -

Streaming with Callbacks

+

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 +bodies and FTP file contents to be streamed through the callback mechanism outlined below.

@@ -52,7 +52,7 @@ 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) @@ -60,7 +60,7 @@ callback mechanism can be used when the application wants to incrementally

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

@@ -113,10 +113,129 @@ 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. +

+

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

@@ -126,25 +245,25 @@ When done, the callback closes the file.

-File is a file opened for reading. If file is +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.

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

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

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

@@ -154,26 +273,17 @@ 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: A nil -send callback is equivalent to a callback that returns the empty string. +It returns a send callback for the string, +or nil if str is nil.

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

@@ -207,9 +317,9 @@ send_cb = socket.callback.send.chain(

-The call to socket.mime.chain +The call to 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 +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