| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" |
| "http://www.w3.org/TR/html4/strict.dtd"> |
| <html> |
| |
| <head> |
| <meta name="description" content="LuaSocket: HTTP support"> |
| <meta name="keywords" content="Lua, HTTP, Library, WWW, Browser, Network, Support"> |
| <title>LuaSocket: HTTP support</title> |
| <link rel="stylesheet" href="reference.css" type="text/css"> |
| </head> |
| |
| <body> |
| |
| <!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| |
| <div class=header> |
| <hr> |
| <center> |
| <table summary="LuaSocket logo"> |
| <tr><td align=center><a href="http://www.lua.org"> |
| <img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> |
| </a></td></tr> |
| <tr><td align=center valign=top>Network support for the Lua language |
| </td></tr> |
| </table> |
| <p class=bar> |
| <a href="home.html">home</a> · |
| <a href="home.html#download">download</a> · |
| <a href="introduction.html">introduction</a> · |
| <a href="introduction.html">introduction</a> · |
| <a href="reference.html">reference</a> |
| </p> |
| </center> |
| <hr> |
| </div> |
| |
| <!-- http +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| |
| <h2 id=http>HTTP</h2> |
| |
| <p> |
| HTTP (Hyper Text Transfer Protocol) is the protocol used to exchange |
| information between web-browsers and servers. The <tt>http</tt> |
| namespace offers full support for the client side of the HTTP |
| protocol (i.e., |
| the facilities that would be used by a web-browser implementation). The |
| implementation conforms to the HTTP/1.1 standard, |
| <a href="http://www.cs.princeton.edu/~diego/rfc/rfc2616.txt">RFC |
| 2616</a>. |
| </p> |
| |
| <p> |
| The module exports functions that provide HTTP functionality in different |
| levels of abstraction. From the simple |
| string oriented requests, through generic |
| <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> based, down to even lower-level if you bother to look through the source code. |
| </p> |
| |
| <p> |
| To obtain the <tt>http</tt> namespace, run: |
| </p> |
| |
| <pre class=example> |
| -- loads the HTTP module and any libraries it requires |
| local http = require("socket.http") |
| </pre> |
| |
| <p> |
| URLs must conform to |
| <a href="http://www.cs.princeton.edu/~diego/rfc/rfc1738.txt">RFC |
| 1738</a>, |
| that is, an URL is a string in the form: |
| </p> |
| |
| <blockquote> |
| <pre> |
| [http://][<user>[:<password>]@]<host>[:<port>][/<path>] |
| </pre> |
| </blockquote> |
| |
| <p> |
| MIME headers are represented as a Lua table in the form: |
| </p> |
| |
| <blockquote> |
| <table summary="MIME headers in Lua table"> |
| <tr><td><tt> |
| headers = {<br> |
| field-1-name = <i>field-1-value</i>,<br> |
| field-2-name = <i>field-2-value</i>,<br> |
| field-3-name = <i>field-3-value</i>,<br> |
| ...<br> |
| field-n-name = <i>field-n-value</i><br> |
| } |
| </tt></td></tr> |
| </table> |
| </blockquote> |
| |
| <p> |
| Field names are case insensitive (as specified by the standard) and all |
| functions work with lowercase field names. |
| Field values are left unmodified. |
| </p> |
| |
| <p class=note> |
| Note: MIME headers are independent of order. Therefore, there is no problem |
| in representing them in a Lua table. |
| </p> |
| |
| <p> |
| The following constants can be set to control the default behavior of |
| the HTTP module: |
| </p> |
| |
| <ul> |
| <li> <tt>PORT</tt>: default port used for connections; |
| <li> <tt>PROXY</tt>: default proxy used for connections; |
| <li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations; |
| <li> <tt>USERAGENT</tt>: default user agent reported to server. |
| </ul> |
| |
| <!-- http.request ++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| |
| <p class=name id=request> |
| http.<b>request(</b>url [, body]<b>)</b><br> |
| http.<b>request{</b><br> |
| url = <i>string</i>,<br> |
| [sink = <i>LTN12 sink</i>,]<br> |
| [method = <i>string</i>,]<br> |
| [headers = <i>header-table</i>,]<br> |
| [source = <i>LTN12 source</i>],<br> |
| [step = <i>LTN12 pump step</i>,]<br> |
| [proxy = <i>string</i>,]<br> |
| [redirect = <i>boolean</i>,]<br> |
| [create = <i>function</i>]<br> |
| <b>}</b> |
| </p> |
| |
| <p class=description> |
| The request function has two forms. The simple form downloads |
| a URL using the <tt>GET</tt> or <tt>POST</tt> method and is based |
| on strings. The generic form performs any HTTP method and is |
| <a href=http://lua-users.org/wiki/FiltersSourcesAndSinks>LTN12</a> based. |
| </p> |
| |
| <p class=parameters> |
| If the first argument of the <tt>request</tt> function is a string, it |
| should be an <tt>url</tt>. In that case, if a <tt>body</tt> |
| is provided as a string, the function will perform a <tt>POST</tt> method |
| in the <tt>url</tt>. Otherwise, it performs a <tt>GET</tt> in the |
| <tt>url</tt> |
| </p> |
| |
| <p class=parameters> |
| If the first argument is instead a table, the most important fields are |
| the <tt>url</tt> and the <em>simple</em> |
| <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> |
| <tt>sink</tt> that will receive the downloaded content. |
| Any part of the <tt>url</tt> can be overridden by including |
| the appropriate field in the request table. |
| If authentication information is provided, the function |
| uses the Basic Authentication Scheme (see <a href="#authentication">note</a>) |
| to retrieve the document. If <tt>sink</tt> is <tt><b>nil</b></tt>, the |
| function discards the downloaded data. The optional parameters are the |
| following: |
| </p> |
| <ul> |
| <li><tt>method</tt>: The HTTP request method. Defaults to "GET"; |
| <li><tt>headers</tt>: Any additional HTTP headers to send with the request; |
| <li><tt>source</tt>: <em>simple</em> |
| <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> |
| source to provide the request body. If there |
| is a body, you need to provide an appropriate "<tt>content-length</tt>" |
| request header field, or the function will attempt to send the body as |
| "<tt>chunked</tt>" (something few servers support). Defaults to the empty source; |
| <li><tt>step</tt>: |
| <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> |
| pump step function used to move data. |
| Defaults to the LTN12 <tt>pump.step</tt> function. |
| <li><tt>proxy</tt>: The URL of a proxy server to use. Defaults to no proxy; |
| <li><tt>redirect</tt>: Set to <tt><b>false</b></tt> to prevent the |
| function from automatically following 301 or 302 server redirect messages; |
| <li><tt>create</tt>: An optional function to be used instead of |
| <a href=tcp.html#socket.tcp><tt>socket.tcp</tt></a> when the communications socket is created. |
| </ul> |
| |
| <p class=return> |
| In case of failure, the function returns <tt><b>nil</b></tt> followed by an |
| error message. If successful, the simple form returns the response |
| body as a string, followed by the response status code, the response |
| headers and the response status line. The generic function returns the same |
| information, except the first return value is just the number 1 (the body |
| goes to the <tt>sink</tt>). |
| </p> |
| |
| <p class=return> |
| Even when the server fails to provide the contents of the requested URL (URL not found, for example), |
| it usually returns 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 <tt>code</tt>. For |
| a list of the possible values and their meanings, refer to <a |
| href="http://www.cs.princeton.edu/~diego/rfc/rfc2616.txt">RFC |
| 2616</a>. |
| </p> |
| |
| <p class=description> |
| Here are a few examples with the simple interface: |
| </p> |
| |
| <pre class=example> |
| -- load the http module |
| local io = require("io") |
| local http = require("socket.http") |
| local ltn12 = require("ltn12") |
| |
| -- connect to server "www.cs.princeton.edu" and retrieves this manual |
| -- file from "~diego/professional/luasocket/http.html" and print it to stdout |
| http.request{ |
| url = "http://www.cs.princeton.edu/~diego/professional/luasocket/http.html", |
| sink = ltn12.sink.file(io.stdout) |
| } |
| |
| -- connect to server "www.example.com" and tries to retrieve |
| -- "/private/index.html". Fails because authentication is needed. |
| b, c, h = http.request("http://www.example.com/private/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. |
| r, e = http.request("http://wrong.host/") |
| -- r is nil, and e returns with value "host not found" |
| </pre> |
| |
| <p class=description> |
| And here is an example using the generic interface: |
| </p> |
| |
| <pre class=example> |
| -- load the http module |
| http = require("socket.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 |
| r, c, h = http.request { |
| method = "HEAD", |
| url = "http://www.tecgraf.puc-rio.br/~diego" |
| } |
| -- r is 1, c is 200, and h would return the following headers: |
| -- h = { |
| -- 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", |
| -- ["content-length"] = 15652, |
| -- ["connection"] = "close", |
| -- ["content-Type"] = "text/html" |
| -- } |
| </pre> |
| |
| <p class=note id=post> |
| Note: When sending a POST request, simple interface adds a |
| "<tt>Content-type: application/x-www-form-urlencoded</tt>" |
| header to the request. This is the type used by |
| HTML forms. If you need another type, use the generic |
| interface. |
| </p> |
| |
| <p class=note id=authentication> |
| Note: Some URLs are protected by their |
| servers from anonymous download. For those URLs, the server must receive |
| some sort of authentication along with the request or it will deny |
| download and return status "401 Authentication Required". |
| </p> |
| |
| <p class=note> |
| The HTTP/1.1 standard defines two authentication methods: the Basic |
| Authentication Scheme and the Digest Authentication Scheme, both |
| explained in detail in |
| <a href="http://www.cs.princeton.edu/~diego/rfc/rfc2068.txt">RFC 2068</a>. |
| </p> |
| |
| <p class=note>The Basic Authentication Scheme sends |
| <tt><user></tt> and |
| <tt><password></tt> unencrypted to the server and is therefore |
| considered unsafe. Unfortunately, by the time of this implementation, |
| the wide majority of servers and browsers support the Basic Scheme only. |
| Therefore, this is the method used by the toolkit whenever |
| authentication is required. |
| </p> |
| |
| <pre class=example> |
| -- load required modules |
| http = require("socket.http") |
| mime = require("mime") |
| |
| -- Connect to server "www.example.com" and tries to retrieve |
| -- "/private/index.html", using the provided name and password to |
| -- authenticate the request |
| b, c, h = http.request("http://fulano:silva@www.example.com/private/index.html") |
| |
| -- Alternatively, one could fill the appropriate header and authenticate |
| -- the request directly. |
| r, c = http.request { |
| url = "http://www.example.com/private/index.html", |
| headers = { authentication = "Basic " .. (mime.b64("fulano:silva")) } |
| } |
| </pre> |
| |
| <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| |
| <div class=footer> |
| <hr> |
| <center> |
| <p class=bar> |
| <a href="home.html">home</a> · |
| <a href="home.html#download">download</a> · |
| <a href="installation.html">installation</a> · |
| <a href="introduction.html">introduction</a> · |
| <a href="reference.html">reference</a> |
| </p> |
| <p> |
| <small> |
| Last modified by Diego Nehab on <br> |
| Thu Apr 20 00:25:26 EDT 2006 |
| </small> |
| </p> |
| </center> |
| </div> |
| |
| </body> |
| </html> |
