~ubuntu-branches/ubuntu/intrepid/luatex/intrepid

« back to all changes in this revision

Viewing changes to src/libs/luasocket/doc/http.html

  • Committer: Bazaar Package Importer
  • Author(s): Norbert Preining
  • Date: 2008-07-07 11:01:13 UTC
  • mfrom: (1.1.5 upstream) (4.1.1 lenny)
  • Revision ID: james.westby@ubuntu.com-20080707110113-1y7lam37zbbb7bbt
Tags: 0.28.0-1
* two new upstream releases, see the respective ANNOUCE files
* add luasocket license statement to debian/copyright
* activate the pdfluatex format
* prepare for latex based formats
  - add the ini files from TeX Live
  - add debian/formats file
  - adjust dh_installtex incantation
  the problem is that luatex dies when loading ukrhypmp.tex from 
  texlive-lang-cyrillic, but we don't want to conflict with it by now.
* policy 3.8.0, rename README.Debian-source to README.source, and add
  notes about quilt usage
* disable patch fix-pwd-inclusion (it was from svn)

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 
 
2
    "http://www.w3.org/TR/html4/strict.dtd">
 
3
<html>
 
4
 
 
5
<head>
 
6
<meta name="description" content="LuaSocket: HTTP support">
 
7
<meta name="keywords" content="Lua, HTTP, Library, WWW, Browser, Network, Support"> 
 
8
<title>LuaSocket: HTTP support</title>
 
9
<link rel="stylesheet" href="reference.css" type="text/css">
 
10
</head>
 
11
 
 
12
<body>
 
13
 
 
14
<!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
15
 
 
16
<div class=header>
 
17
<hr>
 
18
<center>
 
19
<table summary="LuaSocket logo">
 
20
<tr><td align=center><a href="http://www.lua.org">
 
21
<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png">
 
22
</a></td></tr>
 
23
<tr><td align=center valign=top>Network support for the Lua language
 
24
</td></tr>
 
25
</table>
 
26
<p class=bar>
 
27
<a href="home.html">home</a> &middot;
 
28
<a href="home.html#download">download</a> &middot;
 
29
<a href="introduction.html">introduction</a> &middot;
 
30
<a href="introduction.html">introduction</a> &middot;
 
31
<a href="reference.html">reference</a> 
 
32
</p>
 
33
</center>
 
34
<hr>
 
35
</div>
 
36
 
 
37
<!-- http +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
38
 
 
39
<h2 id=http>HTTP</h2> 
 
40
 
 
41
<p>
 
42
HTTP (Hyper Text  Transfer Protocol) is the protocol  used to exchange
 
43
information  between  web-browsers and  servers.  The  <tt>http</tt>
 
44
namespace offers  full support for the client  side of the HTTP  
 
45
protocol (i.e.,
 
46
the facilities that would be  used by a web-browser implementation). The
 
47
implementation    conforms     to    the    HTTP/1.1     standard,
 
48
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2616.txt">RFC
 
49
2616</a>.
 
50
</p>
 
51
 
 
52
<p>
 
53
The module exports functions that provide HTTP functionality in different
 
54
levels of abstraction. From the simple 
 
55
string oriented requests, through generic
 
56
<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.
 
57
</p>
 
58
 
 
59
<p> 
 
60
To obtain the <tt>http</tt> namespace, run:
 
61
</p>
 
62
 
 
63
<pre class=example>
 
64
-- loads the HTTP module and any libraries it requires
 
65
local http = require("socket.http")
 
66
</pre>
 
67
 
 
68
<p>
 
69
URLs must conform to
 
70
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc1738.txt">RFC
 
71
1738</a>,
 
72
that is, an URL is a string in the form: 
 
73
</p>
 
74
 
 
75
<blockquote>
 
76
<pre>
 
77
[http://][&lt;user&gt;[:&lt;password&gt;]@]&lt;host&gt;[:&lt;port&gt;][/&lt;path&gt;] 
 
78
</pre>
 
79
</blockquote>
 
80
 
 
81
<p>
 
82
MIME headers are represented as a Lua table in the form:
 
83
</p>
 
84
 
 
85
<blockquote>
 
86
<table summary="MIME headers in Lua table">
 
87
<tr><td><tt>
 
88
headers = {<br>
 
89
&nbsp;&nbsp;field-1-name = <i>field-1-value</i>,<br>
 
90
&nbsp;&nbsp;field-2-name = <i>field-2-value</i>,<br>
 
91
&nbsp;&nbsp;field-3-name = <i>field-3-value</i>,<br>
 
92
&nbsp;&nbsp;...<br>
 
93
&nbsp;&nbsp;field-n-name = <i>field-n-value</i><br>
 
94
}
 
95
</tt></td></tr>
 
96
</table>
 
97
</blockquote>
 
98
 
 
99
<p>
 
100
Field names are case insensitive (as  specified by the standard) and all
 
101
functions  work with  lowercase field names.  
 
102
Field values are left unmodified.
 
103
</p>
 
104
 
 
105
<p class=note>
 
106
Note: MIME headers are independent of order. Therefore, there is no problem
 
107
in representing them in a Lua table. 
 
108
</p>
 
109
 
 
110
<p>
 
111
The following constants can be set to control the default behavior of
 
112
the HTTP module: 
 
113
</p>
 
114
 
 
115
<ul>
 
116
<li> <tt>PORT</tt>: default port used for connections; 
 
117
<li> <tt>PROXY</tt>: default proxy used for connections; 
 
118
<li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations;
 
119
<li> <tt>USERAGENT</tt>: default user agent reported to server.
 
120
</ul>
 
121
 
 
122
<!-- http.request ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
123
 
 
124
<p class=name id=request>
 
125
http.<b>request(</b>url [, body]<b>)</b><br>
 
126
http.<b>request{</b><br>
 
127
&nbsp;&nbsp;url = <i>string</i>,<br>
 
128
&nbsp;&nbsp;[sink = <i>LTN12 sink</i>,]<br>
 
129
&nbsp;&nbsp;[method = <i>string</i>,]<br>
 
130
&nbsp;&nbsp;[headers = <i>header-table</i>,]<br>
 
131
&nbsp;&nbsp;[source = <i>LTN12 source</i>],<br>
 
132
&nbsp;&nbsp;[step = <i>LTN12 pump step</i>,]<br>
 
133
&nbsp;&nbsp;[proxy = <i>string</i>,]<br>
 
134
&nbsp;&nbsp;[redirect = <i>boolean</i>,]<br>
 
135
&nbsp;&nbsp;[create = <i>function</i>]<br>
 
136
<b>}</b>
 
137
</p>
 
138
 
 
139
<p class=description>
 
140
The request function has two forms. The simple form downloads 
 
141
a URL using the <tt>GET</tt> or <tt>POST</tt> method and is based 
 
142
on strings. The generic form performs any HTTP method and is 
 
143
<a href=http://lua-users.org/wiki/FiltersSourcesAndSinks>LTN12</a> based.
 
144
</p>
 
145
 
 
146
<p class=parameters>
 
147
If the first argument of the <tt>request</tt> function is a string, it
 
148
should be an <tt>url</tt>. In that case, if a <tt>body</tt>
 
149
is provided as a string, the function will perform a <tt>POST</tt> method
 
150
in the <tt>url</tt>. Otherwise, it performs a <tt>GET</tt> in the
 
151
<tt>url</tt> 
 
152
</p>
 
153
 
 
154
<p class=parameters>
 
155
If the first argument is instead a table, the most important fields are 
 
156
the <tt>url</tt> and the <em>simple</em>
 
157
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 
 
158
<tt>sink</tt> that will receive the downloaded content.  
 
159
Any part of the <tt>url</tt> can be overridden by including
 
160
the appropriate field in the request table.
 
161
If authentication information is provided, the function
 
162
uses the  Basic Authentication Scheme (see  <a href="#authentication">note</a>)
 
163
to retrieve  the document. If <tt>sink</tt> is <tt><b>nil</b></tt>, the
 
164
function discards the downloaded data. The optional parameters are the
 
165
following:
 
166
</p>
 
167
<ul>
 
168
<li><tt>method</tt>: The HTTP request method. Defaults to "GET"; 
 
169
<li><tt>headers</tt>: Any additional HTTP headers to send with the request; 
 
170
<li><tt>source</tt>: <em>simple</em> 
 
171
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 
 
172
source to provide the request body. If there
 
173
is a body, you need to provide an appropriate "<tt>content-length</tt>"
 
174
request header field, or the function will attempt to send the body as
 
175
"<tt>chunked</tt>" (something few servers support). Defaults to the empty source; 
 
176
<li><tt>step</tt>: 
 
177
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 
 
178
pump step function used to move data.  
 
179
Defaults to the LTN12 <tt>pump.step</tt> function.
 
180
<li><tt>proxy</tt>: The URL of a proxy server to use. Defaults to no proxy; 
 
181
<li><tt>redirect</tt>: Set to <tt><b>false</b></tt> to prevent the 
 
182
function from  automatically following 301 or 302 server redirect messages; 
 
183
<li><tt>create</tt>: An optional function to be used instead of
 
184
<a href=tcp.html#socket.tcp><tt>socket.tcp</tt></a> when the communications socket is created. 
 
185
</ul>
 
186
 
 
187
<p class=return>
 
188
In case of failure, the function returns <tt><b>nil</b></tt> followed by an
 
189
error message. If successful, the simple form returns the response 
 
190
body as a string, followed by the response status code, the response
 
191
headers and the response status line. The generic function returns the same
 
192
information, except the first return value is just the number 1 (the body
 
193
goes to the <tt>sink</tt>).
 
194
</p>
 
195
 
 
196
<p class=return>
 
197
Even  when the server fails to provide the contents of the requested URL (URL not  found, for  example), 
 
198
it usually returns a message body (a web page informing the
 
199
URL  was  not found  or  some  other useless  page).  To  make sure  the
 
200
operation was successful, check  the returned status <tt>code</tt>. For
 
201
a  list  of  the  possible  values  and  their  meanings,  refer  to  <a
 
202
href="http://www.cs.princeton.edu/~diego/rfc/rfc2616.txt">RFC
 
203
2616</a>. 
 
204
</p>
 
205
 
 
206
<p class=description>
 
207
Here are a few examples with the simple interface:
 
208
</p>
 
209
 
 
210
<pre class=example>
 
211
-- load the http module
 
212
local io = require("io")
 
213
local http = require("socket.http")
 
214
local ltn12 = require("ltn12")
 
215
 
 
216
-- connect to server "www.cs.princeton.edu" and retrieves this manual
 
217
-- file from "~diego/professional/luasocket/http.html" and print it to stdout
 
218
http.request{ 
 
219
    url = "http://www.cs.princeton.edu/~diego/professional/luasocket/http.html", 
 
220
    sink = ltn12.sink.file(io.stdout)
 
221
}
 
222
 
 
223
-- connect to server "www.example.com" and tries to retrieve
 
224
-- "/private/index.html". Fails because authentication is needed.
 
225
b, c, h = http.request("http://www.example.com/private/index.html")
 
226
-- b returns some useless page telling about the denied access, 
 
227
-- h returns authentication information
 
228
-- and c returns with value 401 (Authentication Required)
 
229
 
 
230
-- tries to connect to server "wrong.host" to retrieve "/"
 
231
-- and fails because the host does not exist.
 
232
r, e = http.request("http://wrong.host/")
 
233
-- r is nil, and e returns with value "host not found"
 
234
</pre>
 
235
 
 
236
<p class=description>
 
237
And here is an example using the generic interface:
 
238
</p>
 
239
 
 
240
<pre class=example>
 
241
-- load the http module
 
242
http = require("socket.http")
 
243
 
 
244
-- Requests information about a document, without downloading it.
 
245
-- Useful, for example, if you want to display a download gauge and need
 
246
-- to know the size of the document in advance
 
247
r, c, h = http.request {
 
248
  method = "HEAD",
 
249
  url = "http://www.tecgraf.puc-rio.br/~diego"
 
250
}
 
251
-- r is 1, c is 200, and h would return the following headers:
 
252
-- h = {
 
253
--   date = "Tue, 18 Sep 2001 20:42:21 GMT",
 
254
--   server = "Apache/1.3.12 (Unix)  (Red Hat/Linux)",
 
255
--   ["last-modified"] = "Wed, 05 Sep 2001 06:11:20 GMT",
 
256
--   ["content-length"] = 15652,
 
257
--   ["connection"] = "close",
 
258
--   ["content-Type"] = "text/html"
 
259
-- }
 
260
</pre>
 
261
 
 
262
<p class=note id=post> 
 
263
Note: When sending a POST request, simple interface adds a
 
264
"<tt>Content-type: application/x-www-form-urlencoded</tt>"
 
265
header to the request. This is the type used by
 
266
HTML forms. If you need another type, use the generic
 
267
interface.
 
268
</p>
 
269
 
 
270
<p class=note id=authentication> 
 
271
Note: Some URLs are protected by their
 
272
servers from anonymous download. For those URLs, the server must receive
 
273
some  sort of  authentication along  with the  request or  it will  deny
 
274
download and return status "401&nbsp;Authentication Required". 
 
275
</p>
 
276
 
 
277
<p class=note>
 
278
The  HTTP/1.1 standard  defines  two authentication  methods: the  Basic
 
279
Authentication  Scheme  and  the   Digest  Authentication  Scheme,  both
 
280
explained in detail in
 
281
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2068.txt">RFC 2068</a>.
 
282
</p>
 
283
 
 
284
<p class=note>The Basic  Authentication   Scheme  sends   
 
285
<tt>&lt;user&gt;</tt>  and
 
286
<tt>&lt;password&gt;</tt>  unencrypted to  the server  and is  therefore
 
287
considered unsafe.  Unfortunately, by  the time of  this implementation,
 
288
the wide majority of servers and browsers support the Basic Scheme only.
 
289
Therefore,   this  is   the  method   used  by   the  toolkit   whenever
 
290
authentication is required.
 
291
</p>
 
292
 
 
293
<pre class=example>
 
294
-- load required modules
 
295
http = require("socket.http")
 
296
mime = require("mime")
 
297
 
 
298
-- Connect to server "www.example.com" and tries to retrieve
 
299
-- "/private/index.html", using the provided name and password to
 
300
-- authenticate the request
 
301
b, c, h = http.request("http://fulano:silva@www.example.com/private/index.html")
 
302
 
 
303
-- Alternatively, one could fill the appropriate header and authenticate
 
304
-- the request directly.
 
305
r, c = http.request {
 
306
  url = "http://www.example.com/private/index.html",
 
307
  headers = { authentication = "Basic " .. (mime.b64("fulano:silva")) }
 
308
}
 
309
</pre>
 
310
 
 
311
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
312
 
 
313
<div class=footer>
 
314
<hr>
 
315
<center>
 
316
<p class=bar>
 
317
<a href="home.html">home</a> &middot;
 
318
<a href="home.html#download">download</a> &middot;
 
319
<a href="installation.html">installation</a> &middot;
 
320
<a href="introduction.html">introduction</a> &middot;
 
321
<a href="reference.html">reference</a> 
 
322
</p>
 
323
<p>
 
324
<small>
 
325
Last modified by Diego Nehab on <br>
 
326
Thu Apr 20 00:25:26 EDT 2006
 
327
</small>
 
328
</p>
 
329
</center>
 
330
</div>
 
331
 
 
332
</body>
 
333
</html>