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.
diff --git a/doc/dns.html b/doc/dns.html index 17cee45..71a9719 100644 --- a/doc/dns.html +++ b/doc/dns.html @@ -36,8 +36,7 @@-The following functions can be used to convert between host names and IP -addresses. Both functions return all information returned by the +Name resolution function return all information returned by the resolver in a table of the form:
@@ -53,6 +52,21 @@ resolved = {+socket.dns.gethostname() +
+ ++Returns the standard host name for the machine. +
+ ++The function returns a string with the host name. +
+ +@@ -74,7 +88,6 @@ the resolver. In case of error, the function returns nil followed by an error message.
-diff --git a/doc/http.html b/doc/http.html index f977ea9..f82f515 100644 --- a/doc/http.html +++ b/doc/http.html @@ -49,7 +49,7 @@ implementation conforms to the HTTP/1.1 standard, The module exports functions that provide HTTP functionality in different levels of abstraction, from a simple get, to the generic, stream oriented - request_cb. +request_cb.
diff --git a/doc/index.html b/doc/index.html index 620f385..a2c2d59 100644 --- a/doc/index.html +++ b/doc/index.html @@ -40,7 +40,8 @@ LuaSocket is a Lua extension library that is composed by two parts: a C layer that provides support for the TCP and UDP transport layers, and a set of Lua modules that add support for the SMTP (sending e-mails), HTTP (WWW access) and FTP (uploading and -downloading files) protocols. +downloading files) protocols and other functionality commonly needed by +applications that deal with the Internet.
@@ -106,10 +107,25 @@ This binary has been compiled with the LUASOCKET_DEBUG option, and should be able to run the automatic test procedures.
+ + ++Throughout LuaSocket its history, many people gave sugestions that helped +improve it. For that, I thank the Lua comunity. +Special thanks go to +David Burgess, who has pushed the library to a new level of quality and +from whom I have learned a lot stuff that doesn't show up in RFCs. +Special thanks also to Carlos Cassino, who played a big part in the +extensible design seen in the C core of LuaSocket 2.0. +
+Most of the changes for 2.0 happened in the C layer, which has been almost completely rewritten. The code has been ported to Lua 5.0 diff --git a/doc/reference.html b/doc/reference.html index 0bfd378..e6efb6e 100644 --- a/doc/reference.html +++ b/doc/reference.html @@ -40,6 +40,10 @@
Callbacks (socket.callback)+done, +fail. ++send: chain, file, @@ -121,7 +125,7 @@MIME (socket.mime)-filters: +high-level: canonic, chain, decode, @@ -129,7 +133,7 @@ wrap.-low-level: +low-level: b64, unb64, eol, diff --git a/doc/tcp.html b/doc/tcp.html index eb4cdfa..34d6c6e 100644 --- a/doc/tcp.html +++ b/doc/tcp.html @@ -44,10 +44,11 @@ socket.tcp()Creates and returns a TCP master object. A master object can be transformed into a server object with the method -bind or into a client object with the method -connect. The only other method -supported by a master object is the close -method.
+listen (after a call to bind) or into a client object with +the method connect. The only other +method supported by a master object is the +close method.In case of success, a new master object is returned. In case of error, @@ -67,8 +68,9 @@ object and returns a client object representing that connection.
If a connection is successfully initiated, a client object is returned. -If a timeout condition is met, the method returns nil followed -by the error string 'timeout'. +If a timeout condition is met, the method returns nil +followed by the error string 'timeout'. Other errors are +reported by nil followed by a message describing the error.
@@ -77,25 +79,18 @@ with a server object in the receive parameter before a call to accept does not guarantee accept will return immediately. Use the settimeout method or accept -might block until another client shows up. +might block until another client shows up.
-master:bind(address, port [, backlog]) +master:bind(address, port)
Binds a master object to address and port on the -local host, transforming it into a server object. Server -objects support the -accept, -getsockname, -setoption, -settimeout, -and close methods. -
+local host.Address can be an IP address or a host name. @@ -103,10 +98,7 @@ and close methods. If address is '*', the system binds to all local interfaces using the INADDR_ANY constant. If port is 0, the system automatically -chooses an ephemeral port. The optional parameter backlog, which -defaults to 1, specifies the number of client connections that can -be queued waiting for service. If the queue is full and another client -attempts connection, the connection is refused. +chooses an ephemeral port.
@@ -115,8 +107,8 @@ method returns nil followed by an error message.
-Note: The function socket.bind is available and is a short -for socket.tcp followed by the bind method. +Note: The function socket.bind +is available and is a shortcut for the creation server sockets.
@@ -150,7 +142,8 @@ master:connect(address, port)Attempts to connect a master object to a remote host, transforming it into a -client object. Client objects support methods +client object. +Client objects support methods send, receive, getsockname, @@ -170,8 +163,15 @@ describing the error. In case of success, the method returns 1.
-Note: The function socket.connect is available and is a short -for socket.tcp followed by the connect method. +Note: The function socket.connect +is available and is a shortcut for the creation of client sockets. +
+ ++Note: Starting with LuaSocket 2.0, +the settimeout +function affects the behavior of connect, causing it to return in case of +a timeout error.
@@ -210,12 +210,32 @@ The method returns a string with local IP address and a number with the port. In case of error, the method returns nil. --Note: Naturally, for a server object, the address and port returned are -those passed to the bind method. If the port value -passed to bind was 0, the OS assigned ephemeral port is returned. For -client objects, both the address and port are ephemeral and these are the -values returned. + + +
+master:listen(backlog) +
+ ++Specifies the socket is willing to receive connections, transforming the +object into a server object. Server objects support the +accept, +getsockname, +setoption, +settimeout, +and close methods. +
+ ++The parameter backlog specifies the number of client +connections that can +be queued waiting for service. If the queue is full and another client +attempts connection, the connection is refused. +
+ ++In case of success, the method returns 1. In case of error, the +method returns nil followed by an error message.
@@ -242,8 +262,8 @@ closed. No end-of-line translation is performed; terminated by a LF character (ASCII 10), optionally preceded by a CR character (ASCII 13). The CR and LF characters are not included in the returned line. This is the default pattern; -number: causes the method to read number raw -bytes from the socket. + number: causes the method to read a specified number +of bytes from the socket. @@ -311,22 +331,30 @@ are sure you need it. depends on the option being set:
-
- 'tcp-nodelay': Setting this option to true disables the -Nagle's algorithm for the connection; + +
- 'keepalive': Setting this option to true enables +the periodic transmission of messages on a connected socket. Should the +connected party fail to respond to these messages, the connection is +considered broken and processes using the socket are notified; +
- 'linger': Controls the action taken when unsent data are queued on a socket and a close is performed. The value is a table with a boolean entry 'on' and a numeric entry for the time interval -'timeout' in seconds. - If the 'on' field is set to true, -the system will block the process on the close attempt until it is able to -transmit the data or until 'timeout' has passed. If 'on' -is false and a close is issued, the system will process the close -in a manner that allows the process to continue as quickly as possible. I -do not advise you to set this to anything other than zero. -
- 'keepalive': Setting this option to true enables -the periodic transmission of messages on a connected socket. Should the - connected party fail to respond to these messages, the connection is -considered broken and processes using the socket are notified. +'timeout' in seconds. If the 'on' field is set to +true, the system will block the process on the close attempt until +it is able to transmit the data or until 'timeout' has passed. If +'on' is false and a close is issued, the system will +process the close in a manner that allows the process to continue as +quickly as possible. I do not advise you to set this to anything other than +zero; + +
- 'reuseaddr': Setting this option indicates that the rules +used in validating addresses supplied in a call to +bind should allow reuse of local addresses; + +
- 'tcp-nodelay': Setting this option to true +disables the Nagle's algorithm for the connection. +
@@ -382,7 +410,9 @@ indefinitely. Negative timeout values have the same effect. Note: although timeout values have millisecond precision in LuaSocket, large blocks can cause I/O functions not to respect timeout values due to the time the library takes to transfer blocks to and from the OS -and to and from the Lua interpreter. +and to and from the Lua interpreter. Also, function that accept host names +and perform automatic name resolution might be blocked by the resolver for +longer than the specified timeout value.
@@ -391,6 +421,30 @@ changed for sake of uniformity, since all other method names already contained verbs making their imperative nature obvious.
+ + ++client:shutdown(mode)
+ +
++Shuts down part of a full duplex connection. +
+ ++Mode tells which way of the connection should be shut down and can +take the value: +
+
+ +- "both": disallow further sends and receives on the object. +This is the default mode; +
- "send": disallow further sends on the object; +
- "receive": disallow further receives on the object. +
+This function returns 1. +
+