diff options
Diffstat (limited to 'Build/source/texk/web2c/luatexdir/luasocket/doc/http.html')
-rw-r--r-- | Build/source/texk/web2c/luatexdir/luasocket/doc/http.html | 335 |
1 files changed, 0 insertions, 335 deletions
diff --git a/Build/source/texk/web2c/luatexdir/luasocket/doc/http.html b/Build/source/texk/web2c/luatexdir/luasocket/doc/http.html deleted file mode 100644 index 3b7a8b1a26a..00000000000 --- a/Build/source/texk/web2c/luatexdir/luasocket/doc/http.html +++ /dev/null @@ -1,335 +0,0 @@ -<!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="index.html">home</a> · -<a href="index.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.ietf.org/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.ietf.org/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 (but see -<a href=socket.html#headers.canonic><tt>socket.headers.canonic</tt></a>). -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>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> - -<p class=note id="post"> -Note: These constants are global. Changing them will also -change the behavior other code that might be using LuaSocket. -</p> - -<!-- 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.ietf.org/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.ietf.org/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 = { authorization = "Basic " .. (mime.b64("fulano:silva")) } -} -</pre> - -<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> - -<div class=footer> -<hr> -<center> -<p class=bar> -<a href="index.html">home</a> · -<a href="index.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> |