From 843a431ef98fd541d98fd3898463985d9bfcde28 Mon Sep 17 00:00:00 2001 From: Diego Nehab Date: Tue, 15 Jun 2004 23:00:56 +0000 Subject: Almost done with manual... --- doc/http.html | 203 +++++++++++++++++++++------------------------------------- 1 file changed, 74 insertions(+), 129 deletions(-) (limited to 'doc/http.html') 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
-

-
 
 
 

-- 
cgit v1.2.3-55-g6feb