|
| Network support for the Lua language |
|
|
| Network support for the Lua language |
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 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 wheneve 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.
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.
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 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.
Note: This function is designed so that it directly accepts the return values of the io.open function.
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.
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.
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 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.