Mercurial > luasocket
diff doc/http.html @ 0:4b915342e2a8
LuaSocket 2.0.2 + CMake build description.
| author | Eric Wing <ewing . public |-at-| gmail . com> |
|---|---|
| date | Tue, 26 Aug 2008 18:40:01 -0700 |
| parents | |
| children |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/http.html Tue Aug 26 18:40:01 2008 -0700 @@ -0,0 +1,333 @@ +<!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>