-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathindex.html
377 lines (312 loc) · 11.4 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
<!DOCTYPE html>
<html>
<head>
<meta charset='utf-8'>
<meta http-equiv="X-UA-Compatible" content="chrome=1">
<link rel="stylesheet" type="text/css" href="stylesheets/stylesheet.css" media="screen" />
<link rel="stylesheet" type="text/css" href="stylesheets/pygment_trac.css" media="screen" />
<link rel="stylesheet" type="text/css" href="stylesheets/print.css" media="print" />
<title>Lua-cURL by msva</title>
</head>
<body>
<header>
<div class="container">
<h1>Lua-cURL</h1>
<h2>Lua-cURL is aiming for a full-fledged libcurl binding (easy/multi/share interface) to the functionality of Lua</h2>
<section id="downloads">
<a href="https://github.com/lua-curl/lua-curlv2/zipball/master" class="btn">Download as .zip</a>
<a href="https://github.com/lua-curl/lua-curlv2/tarball/master" class="btn">Download as .tar.gz</a>
<a href="https://github.com/lua-curl/lua-curlv2" class="btn btn-github"><span class="icon"></span>View on GitHub</a>
</section>
</div>
</header>
<div class="container">
<section id="main_content">
<table frame="void" rules="none">
<tr>
<th>Original Author (before of 4Q-2011):</th>
<td>Jürgen Hötzel</td>
</tr>
<tr>
<th>Current Lead Developer:</th>
<td>Vadim A. Misbakh-Soloviov</td>
</tr>
<tr>
<th>Contact:</th>
<td><a href="http://mva.name/">http://mva.name/</a></td>
</tr>
</table>
<p><a name="contents">Contents</a></p>
<ul>
<li><a href="#introduction" name="id1">Introduction</a></li>
<li><a href="#installation" name="id2">Installation</a></li>
<li>
<a href="#easy-interface" name="id3">Easy interface</a><ul>
<li><a href="#example-1-fetch-the-example-com-homepage" name="id4">Example 1: Fetch the example.com homepage</a></li>
<li><a href="#example-2-on-the-fly-file-upload" name="id5">Example 2: "On-The-Fly" file upload</a></li>
<li><a href="#example-3-posting-data" name="id6">Example 3: "Posting" data</a></li>
</ul>
</li>
<li>
<a href="#multi-interface" name="id7">Multi interface</a><ul>
<li><a href="#example-1-on-the-fly-xml-parsing" name="id8">Example 1: "On-The-Fly" XML parsing</a></li>
</ul>
</li>
<li>
<a href="#share-interface" name="id9">Share interface</a><ul>
<li><a href="#example-1-share-cookie-date-across-easy-handles" name="id10">Example 1: Share Cookie date across easy handles</a></li>
</ul>
</li>
<li>
<a href="#appendix" name="id11">Appendix</a><ul>
<li><a href="#using-ssl" name="id12">Using SSL</a></li>
</ul>
</li>
</ul>
<h1><a href="#id1" name="introduction">Introduction</a></h1>
<p>This project is <strong>not</strong> a fork of <a href="http://luaforge.net/projects/luacurl/">LuaCURL</a>, which is a direct mapping of parts of the <a href="http://curl.haxx.se/libcurl/c/libcurl-easy.html">libcurl-easy</a> interface.</p>
<p>The intent of Lua-cURL is to adapt the</p>
<ul>
<li>Easy Interface</li>
<li>Multi Interface</li>
<li>Shared Interface</li>
</ul><p>of <a href="http://curl.haxx.se/libcurl/c/">libcurl</a> to the functionality of Lua (for example by using iterators instead of callbacks when possible).</p>
<h1><a href="#id2" name="installation">Installation</a></h1>
<p>We now using <a href="http://cmake.org/">CMake</a> to configure, build and install. Just run:</p>
<pre>
cmake ${CMAKE_ARGUMENTS} . && make ${MAKE_ARGUMENTS} install
</pre>
<p>Where <code>CMAKE_ARGUMENTS</code> may contain one or all of the following (in one space-delimited string or bash's array, without comments):</p>
<pre>
-DCMAKE_C_FLAGS="-flto"
# to use LTO (Link-Time Optimisations). Requires GCC>=4.6
-DUSE_LUAJIT=ON
# to use LuaJIT includes instead of 'C' Lua library. Requires LuaJIT>=2.0
-DCMAKE_LINKER="/usr/bin/ld.gold"
# To use 'gold' linker. Requires newer binutils.
-DUSE_LUA52=ON
# to install for Lua 5.2. Requires Lua>=5.2
</pre>
<p>And <code>MAKE_ARGUMENTS</code> may also contain one or all of the following (in one space-delimited string or bash's array, without comments):</p>
<pre>
-jN
# Where N = Number of processor cores * Number of processors + 1,
# to build in N threads, to speedup compilation (by default, -j1)
DESTDIR="<PATH>"
# Where <PATH> can be either absolute or relative prefix-path to the place,
# where you want to install Lua-cURL (by default, DESTDIR=/)
</pre>
<p>On some systems, CMake may fail to include the right lua header files.
This error can be identified at runtime, after requiring the cURL module, by the
error message "undefined symbol". In that case the module must be recompiled
specifying the include path for lua header files. This can be done with the
LUA_DIR environment variable. E.g. in a posix-compliant shell:</p>
<pre>
LUA_DIR="/usr/include/lua5.1" cmake ${CMAKE_ARGUMENTS}
</pre>
<h1><a href="#id3" name="easy-interface">Easy interface</a></h1>
<dl>
<dt><strong>cURL.easy_init()</strong></dt>
<dd>returns a new easy handle.</dd>
<dt><strong>cURL.version_info()</strong></dt>
<dd>returns a table containing version info and features/protocols sub table</dd>
<dt><strong>easy:escape(string)</strong></dt>
<dd>return URL encoded string</dd>
<dt><strong>easy:unescape(string)</strong></dt>
<dd>return URL decoded string</dd>
<dt><strong>easy:setopt*(value)</strong></dt>
<dd><dl>
<dt>libcurl properties an options are mapped to individual functions:</dt>
<dd><ul>
<li><strong>easy:setopt_url(string)</strong></li>
<li><strong>easy:setopt_verbose(number)</strong></li>
<li><strong>easy:setopt_proxytype(string)</strong></li>
<li>
<strong>easy:setopt_share(share)</strong> (See: <a href="#share">share</a>)</li>
<li>...</li>
</ul></dd>
</dl></dd>
<dt><strong>easy:perform(table)</strong></dt>
<dd><dl>
<dt>Perform the transfer as described in the options, using an optional callback table.The callback table indices are named after the equivalent cURL callbacks:</dt>
<dd><ul>
<li><strong>writefunction = function(str)</strong></li>
<li><strong>readfunction = function()</strong></li>
<li><strong>headerfunction = function(str)</strong></li>
</ul></dd>
</dl></dd>
<dt><strong>easy:post(table)</strong></dt>
<dd>
<p>Prepare a multipart/formdata post. The table indices are named after the form fields and should map to string values:</p>
<pre>
{field1 = value1,
field2 = value1}
</pre>
<p>or more generic descriptions in tables:</p>
<pre>
{field1 = {file="/tmp/test.txt",
type="text/plain"},
{field2 = {file="dummy.html",
data="<html><bold>bold</bold></html>,
type="text/html"}}
</pre>
</dd>
</dl>
<h2><a href="#id4" name="example-1-fetch-the-example-com-homepage">Example 1: Fetch the example.com homepage</a></h2>
<pre>
require("cURL")
-- open output file
f = io.open("example_homepage", "w")
c = cURL.easy_init()
-- setup url
c:setopt_url("<a href="http://www.example.com/"">http://www.example.com/"</a>)
-- perform, invokes callbacks
c:perform({writefunction = function(str)
f:write(str)
end})
-- close output file
f:close()
print("Done")
</pre>
<h2><a href="#id5" name="example-2-on-the-fly-file-upload">Example 2: "On-The-Fly" file upload</a></h2>
<pre>
-- simple "On the fly" fileupload
require("cURL")
c=cURL.easy_init()
c:setopt_url("ftp://ftptest:secret0815@targethost/file.dat")
c:setopt_upload(1)
count=0
c:perform({readfunction=function(n)
count = count + 1
if (count < 10) then
return "Line " .. count .. "\n"
end
return nil
end})
print("Fileupload done")
</pre>
<h2><a href="#id6" name="example-3-posting-data">Example 3: "Posting" data</a></h2>
<pre>
require("cURL")
c = cURL.easy_init()
c:setopt_url("http://localhost")
postdata = {
-- post file from filesystem
name = {file="post.lua",
type="text/plain"},
-- post file from data variable
name2 = {file="dummy.html",
data="<html><bold>bold</bold></html>",
type="text/html"}}
c:post(postdata)
c:perform()
print("Done")
</pre>
<p></p>
<h1><a href="#id7" name="multi-interface">Multi interface</a></h1>
<dl>
<dt><strong>cURL.multi_init()</strong></dt>
<dd>returns a new multi handle</dd>
<dt><strong>multi:add_handle(easy)</strong></dt>
<dd>add an easy handle to a multi session</dd>
<dt><strong>multi:perform()</strong></dt>
<dd>
<p>returns an iterator function that, each time it is called, returns the next data, type and corresponding easy handle:</p>
<blockquote>
<dl>
<dt>
<strong>data</strong>:</dt>
<dd>data returned by the cURL library</dd>
<dt><strong>type</strong></dt>
<dd>type of data returned ("header" or "data")</dd>
<dt><strong>easy</strong></dt>
<dd>corresponding easy handle of the data returned</dd>
</dl>
</blockquote>
</dd>
</dl>
<h2><a href="#id8" name="example-1-on-the-fly-xml-parsing">Example 1: "On-The-Fly" XML parsing</a></h2>
<pre>
-- use LuaExpat and Lua-CuRL together for On-The-Fly XML parsing
require("lxp")
require("cURL")
tags = {}
items = {}
callback = {}
function callback.StartElement(parser, tagname)
tags[#tags + 1] = tagname
if (tagname == "item") then
items[#items + 1] = {}
end
end
function callback.CharacterData(parser, str)
if (tags[#tags -1] == "item") then
--we are parsing a item, get rid of trailing whitespace
items[#items][tags[#tags]] = string.gsub(str, "%s*$", "")
end
end
function callback.EndElement(parser, tagname)
--assuming well formed xml
tags[#tags] = nil
end
p = lxp.new(callback)
-- create and setup easy handle
c = cURL.easy_init()
c:setopt_url("<a href="http://www.lua.org/news.rss"">http://www.lua.org/news.rss"</a>)
m = cURL.multi_init()
m:add_handle(c)
for data,type in m:perform() do
-- ign "header"
if (type == "data") then
assert(p:parse(data))
end
end
--finish document
assert(p:parse())
p:close()
for i, item in ipairs(items) do
for k, v in pairs(item) do
print(k,v)
end
print()
end
</pre>
<p></p>
<h1><a href="#id9" name="share-interface">Share interface</a></h1>
<dl>
<dt><strong>cURL.share_init()</strong></dt>
<dd>returns a new share handle</dd>
<dt><strong>share:setopt_share(string)</strong></dt>
<dd>specifies the type of data that should be shared ("DNS" or "COOKIE")</dd>
</dl><p>Since Lua is single-threaded, there is no mapping for the lock options.</p>
<h2><a href="#id10" name="example-1-share-cookie-date-across-easy-handles">Example 1: Share Cookie date across easy handles</a></h2>
<pre>
-- Cookie data will be shared across the easy handles to do an authorized download
require("cURL")
-- create share handle (share COOKIE and DNS Cache)
s = cURL.share_init()
s:setopt_share("COOKIE")
s:setopt_share("DNS")
-- create first easy handle to do the login
c = cURL.easy_init()
c:setopt_share(s)
c:setopt_url("http://targethost/login.php?username=foo&password=bar")
-- create second easy handle to do the download
c2 = cURL.easy_init()
c2:setopt_share(s)
c2:setopt_url("http://targethost/download.php?id=test")
--login
c:perform()
--download
c2:perform()
</pre>
<h1><a href="#id11" name="appendix">Appendix</a></h1>
<h2><a href="#id12" name="using-ssl">Using SSL</a></h2>
<p>The cert bundle distributed with cURL may be out of date and cannot validate many certificates. You can supply a different
PEM cert bundle by using <strong>easy:setopt_cainfo(string)</strong>.
Also, it is a shell script, writen by original author (Jürgen), that can be used for converting the cacert keystore distributed with the Java Runtime Environment to PEM. This script currently distributed in «examples» folder in repository</p>
<p></p>
</section>
</div>
</body>
</html>