diff --git a/doc/dns.html b/doc/dns.html index 8e63407..226a604 100644 --- a/doc/dns.html +++ b/doc/dns.html @@ -70,7 +70,7 @@ The function returns a string with the host name.
-socket.dns.tohostname() +socket.dns.tohostname(address)
@@ -91,7 +91,7 @@ followed by an error message.
-socket.dns.toip() +socket.dns.toip(address)
diff --git a/doc/http.html b/doc/http.html index 16595f7..39eb2e4 100644 --- a/doc/http.html +++ b/doc/http.html @@ -98,36 +98,36 @@ Note: MIME headers are independent of order. Therefore, there is no problem in representing them in a Lua table.
++The following constants can be set to control the default behaviour of +the HTTP module: +
+ +
-socket.http.get(url)
-socket.http.get{
- url = string,
- headers = header-table,
- user = string,
- password = string,
- stay = bool,
-}
+http.get(url)
-Performs the HTTP method GET. +Performs the HTTP method GET.
-The function can be -called either directly with a url or with a request table. -The use of a request table allows complete control over the components of -the request. Values passed explicitly as fields of the request table -override those given by the url. For a description of the fields, -see the request function. +Url identifies the entity to retrieve.
-The function returns the response message body, the mime headers, the -status code and an error message (if any). In case of failure, the -function returns all information it managed to gather. +If successful, the function returns the response message body, the mime +headers, and the status code. In case of failure, the +function returns nil followed by an error message.
@@ -136,35 +136,30 @@ Note: The function is trivially implemented with the use of the
+-- load the http module +http = require("http") + -- connect to server "www.tecgraf.puc-rio.br" and retrieves this manual -- file from "/luasocket/http.html" -b, h, c, e = socket.http.get("http://www.tecgraf.puc-rio.br/luasocket/http.html") +b, h, c = http.get("http://www.tecgraf.puc-rio.br/luasocket/http.html") -- connect to server "www.tecgraf.puc-rio.br" and tries to retrieve -- "~diego/auth/index.html". Fails because authentication is needed. -b, h, c, e = socket.http.get("http://www.tecgraf.puc-rio.br/~diego/auth/index.html") +b, h, c = http.get("http://www.tecgraf.puc-rio.br/~diego/auth/index.html") -- b returns some useless page telling about the denied access, -- h returns authentication information -- and c returns with value 401 (Authentication Required) -- tries to connect to server "wrong.host" to retrieve "/" -- and fails because the host does not exist. -b, h, c, e = socket.http.get("http://wrong.host/") --- b, h, c are nil, and e returns with value "host not found" +r, e = http.get("http://wrong.host/") +-- r is nil, and e returns with value "host not found"
-socket.http.post(url, body)
-socket.http.post{
- url = string,
- headers = header-table,
- body = string,
- user = string,
- password = string,
- stay = bool,
-}
+http.post(url, body)
@@ -181,50 +176,64 @@ Note: This function is also trivially implemented with the use of the
-socket.http.request{
- method = string,
+http.request{
url = string,
- headers = header-table,
- body = string,
- user = string,
- password = string,
- stay = string,
+ [sink = LTN12 sink],]
+ [method = string,]
+ [headers = header-table,]
+ [source = LTN12 source],
+ [step = LTN12 pump step,]
+ [proxy = string,]
+ [redirect = boolean]
}
-Performs the generic HTTP request using. +Performs the generic HTTP request, controled by a request table.
-The request uses method on url -sending the request headers and request body in the -request message. If authentication information is provided, the function +The most important parameters are the url and the LTN12 +sink that will receive the downloaded content. +Any part of the url can be overriden by including +the appropriate field in the request table. +If authentication information is provided, the function uses the Basic Authentication Scheme (see note) -to retrieve the document. User and password provided -explicitly override those given by the url. The stay -parameter, when set to anything but nil, prevents the function -from automatically following 301 or 302 server redirect messages. +to retrieve the document. If sink is nil, the +function discards the downloaded data. The optional parameters are the +following:
+-The function returns a table with all components of the response message -it managed to retrieve. The response table has the following form: +In case of failure, the function returns nil followed by an +error message. If successful, the function returns a table +with all components of the response message. The response table has the following form:
-response = {
- body = string,
+respt = {
headers = header-table,
status = string,
code = number,
- error = string
}
Even when there was failure (URL not found, for example), the -function may succeed retrieving a message body (a web page informing the +function usually succeeds retrieving a message body (a web page informing the URL was not found or some other useless page). To make sure the operation was successful, check the returned status code. For a list of the possible values and their meanings, refer to RFC
+-- load the http module +http = require("http") + -- Requests information about a document, without downloading it. -- Useful, for example, if you want to display a download gauge and need -- to know the size of the document in advance -response = socket.http.request { +respt = http.request { method = "HEAD", url = "http://www.tecgraf.puc-rio.br/~diego" } -- Would return the following headers: --- response.headers = { +-- respt.headers = { -- date = "Tue, 18 Sep 2001 20:42:21 GMT", -- server = "Apache/1.3.12 (Unix) (Red Hat/Linux)", -- ["last-modified"] = "Wed, 05 Sep 2001 06:11:20 GMT", @@ -276,10 +288,14 @@ authentication is required.+-- load required modules +http = require("http") +mime = require("mime") + -- Connect to server "www.tecgraf.puc-rio.br" and tries to retrieve -- "~diego/auth/index.html", using the provided name and password to -- authenticate the request -response = socket.http.request{ +respt = http.request{ url = "http://www.tecgraf.puc-rio.br/~diego/auth/index.html", user = "diego", password = "password" @@ -287,83 +303,12 @@ response = socket.http.request{ -- Alternatively, one could fill the appropriate header and authenticate -- the request directly. -headers = { - authentication = "Basic " .. socket.code.base64("diego:password") -} -response = socket.http.request { +respt = http.request { url = "http://www.tecgraf.puc-rio.br/~diego/auth/index.html", - headers = headers + headers = { authentication = "Basic " .. (mime.b64("diego:password")) } }- - --socket.http.request_cb(request, response) -
- --Performs the generic HTTP request. -
- --The function receives two tables as parameters. The request table -provides information about the request: -
- --request = {- -
- method = string,
- url = string,
- headers = header-table,
- body_cb = send-callback,
- user = string,
- password = string,
- stay = string,
-} --The function uses the HTTP method specified in -request.method on the URL request.url, -sending request.headers along with the request. The request -message body is sent via the send callback request.body_cb. -If authentication information is provided, the function uses the Basic -Authentication Scheme (see note) to -retrieve the document. Request.user and -request.password override those given by the -request.url. The request.stay parameter, when set to -anything but nil, prevents the function from automatically -following 301 or 302 server redirect messages. -
- --The response table specifies information about the desired -response: -
- --response = {- -
- body_cb = receive-callback
-} --The function returns the same response table as that returned by the -socket.http.request function, except the response message body is -returned to the receive callback given by the -response.body_cb field. -
- --Note: For more information on callbacks, please refer to -Streaming with callbacks. -
- --Note: Method names are case sensitive -
-