summaryrefslogtreecommitdiff
path: root/Build/source/texk/web2c/luatexdir/luasocket/doc/http.html
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/texk/web2c/luatexdir/luasocket/doc/http.html')
-rw-r--r--Build/source/texk/web2c/luatexdir/luasocket/doc/http.html335
1 files changed, 335 insertions, 0 deletions
diff --git a/Build/source/texk/web2c/luatexdir/luasocket/doc/http.html b/Build/source/texk/web2c/luatexdir/luasocket/doc/http.html
new file mode 100644
index 00000000000..3b7a8b1a26a
--- /dev/null
+++ b/Build/source/texk/web2c/luatexdir/luasocket/doc/http.html
@@ -0,0 +1,335 @@
+<!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> &middot;
+<a href="index.html#download">download</a> &middot;
+<a href="introduction.html">introduction</a> &middot;
+<a href="introduction.html">introduction</a> &middot;
+<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://][&lt;user&gt;[:&lt;password&gt;]@]&lt;host&gt;[:&lt;port&gt;][/&lt;path&gt;]
+</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>
+&nbsp;&nbsp;field-1-name = <i>field-1-value</i>,<br>
+&nbsp;&nbsp;field-2-name = <i>field-2-value</i>,<br>
+&nbsp;&nbsp;field-3-name = <i>field-3-value</i>,<br>
+&nbsp;&nbsp;...<br>
+&nbsp;&nbsp;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>
+&nbsp;&nbsp;url = <i>string</i>,<br>
+&nbsp;&nbsp;[sink = <i>LTN12 sink</i>,]<br>
+&nbsp;&nbsp;[method = <i>string</i>,]<br>
+&nbsp;&nbsp;[headers = <i>header-table</i>,]<br>
+&nbsp;&nbsp;[source = <i>LTN12 source</i>],<br>
+&nbsp;&nbsp;[step = <i>LTN12 pump step</i>,]<br>
+&nbsp;&nbsp;[proxy = <i>string</i>,]<br>
+&nbsp;&nbsp;[redirect = <i>boolean</i>,]<br>
+&nbsp;&nbsp;[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&nbsp;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>&lt;user&gt;</tt> and
+<tt>&lt;password&gt;</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> &middot;
+<a href="index.html#download">download</a> &middot;
+<a href="installation.html">installation</a> &middot;
+<a href="introduction.html">introduction</a> &middot;
+<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>