1QUVI-OBJECT(7) libquvi Manual QUVI-OBJECT(7)
2
3
4
6 quvi-object - Overview of the libquvi quvi-object
7
9 quvi-object is a collection of libquvi functions provided for the
10 libquvi-scripts(7). These functions vary from HTTP functions to
11 cryptographic functions. All of the quvi-object functions are
12 implemented in C.
13
14 Note
15 The quvi-object should not be confused with the quvi-modules(7)
16 which are a selection of importable modules implemented in Lua.
17 These modules are intended to be loaded (require) from the libquvi-
18 scripts(7).
19
21 Each of the quvi-object functions may be passed a dictionary defining
22 the additional option properties. The following options are supported
23 by all of the functions:
24
25 qoo_croak_if_error=<boolean>
26 By default the library terminates the process if an error occurs.
27 By setting this option to false, it will register the error and
28 continues execution, leaving the error handling for the script to
29 determine. See also "RETURN VALUES".
30
31 The qoo prefix is short for quvi object option. The functions will
32 ignore any unknown options, e.g. the crypto functions would ignore the
33 HTTP options.
34
35 Note
36 The options have been defined in the quvi/const of the quvi-
37 modules(7)
38
39 Crypto
40 These options are specific to the quvi.crypto.* functions of the
41 quvi-object.
42
43 qoo_crypto_algorithm=<value>
44 Specifies the algorithm that should be used. The value is expected
45 to be a string, e.g. sha1 or aes256.
46
47 qoo_crypto_cipher_flags=<value>
48 Specifies the cipher flags (bit OR’d, see quvi-modules-3rdparty(7)
49 for bit operations) to be used with the cipher. These values are
50 identical to those defined by libgcrypt. See the quvi/const of the
51 quvi-modules(7) for a complete list of the available cipher flags.
52
53 qoo_crypto_cipher_mode=<value>
54 Specifies the cipher mode to be used. These are identical to the
55 values defined by libgcrypt. See the quvi/const of the quvi-
56 modules(7) for a complete list of the available cipher modes.
57
58 qoo_crypto_cipher_key=<value>
59 Used to specify the cipher key. It should be noted that the key is
60 expected to be passed in hexadecimal form. See quvi/hex of the
61 quvi-modules(7) for the conversion functions.
62
63 NOTE: The key derivation is left for the script to do
64
65 NOTE: The key is not a pass{word,phrase}
66
67 See also:
68 http://www.di-mgt.com.au/cryptokeys.html#passwordpassphraseandkey
69
70 HTTP
71 These options are specific to the quvi.http.* functions of the
72 quvi-object.
73
74 qoo_fetch_from_charset=<charset>
75 Instructs the library to convert from this charset to UTF-8. Using
76 this option may be required with the websites that use a specific
77 (non-UTF8) encoding.
78
79 The purpose of this option is to make sure that the data is encoded
80 to unicode (UTF-8) before any of it is parsed and returned to the
81 application using libquvi.
82
83 By default, libquvi converts the data which is in the encoding used
84 for the strings by the C runtime in the current locale into UTF-8.
85 IF this fails, and the from charset option is set, the library will
86 then try to convert to UTF-8 using the from charset value.
87
88 qoo_http_cookie_mode=<value>
89 Modify the cookie settings for the libcurl session handle. This
90 feature wraps the cookie features provided by
91 libcurl_easy_setopt(3). See the quvi/const of the quvi-modules(7)
92 for a complete list of the available cookie modes.
93
94 See also libcurl-tutorial(3) which covers the use of cookies with
95 the library in greater detail.
96
98 Each quvi-object function will return a dictionary containing the
99 following values:
100
101 error_message
102 The error message, or an empty value.
103
104 quvi_code
105 The code returned by the library. See also quvi/const of quvi-
106 modules(7).
107
108 Refer to the function documentation for the information about the
109 additional values returned in the dictionary.
110
112 Base64
113 quvi.base64.encode(<plaintext>[,qoo])
114 Encode the plaintext to base64 format. The plaintext is expected to
115 be passed in hexadecimal form. See quvi/hex of the quvi-modules(7)
116 for the conversion functions.
117
118 The second argument (qoo) is expected to be a dictionary of
119 additional quvi object options, if defined at all.
120
121 The function will return the base64 value in the dictionary.
122
123 quvi.base64.decode(<base64>)
124 Decode the base64 value to plaintext.
125
126 The function will return the plaintext value in the dictionary. The
127 value is returned in hexadecimal form.
128
129 Crypto
130 The crypto facility of the quvi-object wraps the libgcrypt symmetric
131 cryptography and the hash (message digest) functions.
132
133 Note
134 The availability of the algorithms is determined by libgcrypt, and
135 how it was built
136
137 quvi.crypto.encrypt(<plaintext>, <qoo>)
138 Encrypt the plaintext. The plaintext is expected to be passed in
139 hexadecimal form. See quvi/hex of the quvi-modules(7) for the
140 conversion functions.
141
142 The second argument (qoo) is expected to be a dictionary containing
143 the cipher options.
144
145 The function will return the ciphertext value in the dictionary.
146 The value is returned in hexadecimal form.
147
148 quvi.crypto.decrypt(<ciphertext>, <qoo>)
149 Decrypt the ciphertext. The ciphertext is expected to be passed in
150 hexadecimal form. See quvi/hex of the quvi-modules(7) for the
151 conversion functions.
152
153 The second argument (qoo) is expected to be a dictionary containing
154 the cipher options.
155
156 The function will return the plaintext value in the dictionary.
157 This value is returned in hexadecimal form.
158
159 quvi.crypto.hash(<value>, <qoo>)
160 Generate a hash from the value. The value is expected to be passed
161 in hexadecimal format. See quvi/hex of the quvi-modules(7) for the
162 conversion functions.
163
164 The second argument (qoo) is expected to be a dictionary containing
165 the hash options, e.g. the algorithm that should be used.
166
167 The function will return the digest value in the dictionary. The
168 value is returned in hexadecimal form.
169
170 HTTP
171 The HTTP functions will return response_code along the other "RETURN
172 VALUES", and the values specific to the HTTP function.
173
174 quvi.http.cookie(<VALUE>,<qoo>)
175 Modify the libcurl session handle cookie settings that libquvi
176 currently uses.
177
178 The second argument (qoo) is expected to be a dictionary containing
179 the cookie options, e.g. the cookie mode that should be used.
180
181 The complete list of the available cookie modes can be found in the
182 quvi/const module of the quvi-modules(7). The mode names are named
183 after their equivalent CURLOPT_COOKIE{SESSION,FILE,LIST,JAR}
184 variable names. For a description of each option, see
185 libcurl_easy_setopt(3).
186
187 This function will not return any additional values in the
188 dictionary.
189
190 Note
191 libquvi will ignore any calls to quvi.http.cookie unless
192 QUVI_OPTION_ALLOW_COOKIES is QUVI_TRUE
193
194 Note
195 libcurl will parse the received cookies and use them in the
196 subsequent HTTP requests only if libquvi QUVI_OPTION_ALLOW_COOKIES
197 is QUVI_TRUE
198
199 quvi.http.fetch(<URL>[,qoo])
200 Fetch an URL over an HTTP connection.
201
202 The second argument (qoo) is expected to be a dictionary of
203 additional quvi object options, if defined at all.
204
205 The function will return the data value among the values in the
206 returned dictionary.
207
208 quvi.http.header(<VALUE>[,qoo])
209 Add, remove or replace internally used libcurl HTTP headers.
210
211 The second argument (qoo) is expected to be a dictionary of
212 additional quvi object options, if defined at all.
213
214 This function essentially wraps CURLOPT_HTTPHEADER, and will not
215 return any additional values in the dictionary. See
216 curl_easy_setopt(3) for the full description of CURLOPT_HTTPHEADER.
217
218 Note
219 To clear the custom headers, pass "" as the VALUE; the custom
220 headers are also cleared automatically when a support script
221 function parse is called
222
223 quvi.http.metainfo(<URL>[,qoo])
224 Query the HTTP metainfo for the URL.
225
226 The second argument (qoo) is expected to be a dictionary of
227 additional quvi object options, if defined at all.
228
229 The function will return the content_length and the content_type
230 values among the values in the returned dictionary.
231
232 quvi.http.resolve(<URL>[,qoo])
233 Resolve an URL redirection.
234
235 The second argument (qoo) is expected to be a dictionary of
236 additional quvi object options, if defined at all.
237
238 The function will return the resolved_url among the values in the
239 returned dictionary. If the URL did not redirect to another
240 location, the value of the resolved_url is left empty.
241
243 Base64
244 · Base64 encode a string:
245
246 local H = require 'quvi/hex'
247 local s = H.to_hex('foo') -- Pass in hexadecimal form
248
249 local r = quvi.base64.encode(s)
250 print(r.base64)
251
252 · Reverse the process:
253
254 local r = quvi.base64.decode(r.base64)
255 local s = H.to_str(r.plaintext)
256
257 Crypto
258 · Encrypt plaintext:
259
260 local plaintext = 'f34481ec3cc627bacd5dc3fb08f273e6'
261 local key = '00000000000000000000000000000000'
262
263 local C = require 'quvi/const'
264 local o = {
265 [C.qoo_crypto_cipher_mode] = C.qoco_cipher_mode_cbc,
266 [C.qoo_crypto_algorithm] = 'aes',
267 [C.qoo_crypto_cipher_key = key
268 }
269
270 local r = quvi.crypto.encrypt(plaintext, o)
271 print(r.ciphertext)
272
273 · Reverse the process:
274
275 local r = quvi.crypto.decrypt(r.ciphertext, o)
276 print(r.plaintext)
277
278 · Generate a hash (message digest):
279
280 local H = require 'quvi/hex'
281 local s = H.to_hex('foo') -- Pass in hexadecimal form
282
283 local C = require 'quvi/const'
284 local o = { [C.qoo_crypto_algorithm] = 'sha1' }
285
286 local r = quvi.crypto.hash(s, o)
287 print(r.digest)
288
289 · Same as above, but use the shorthand function:
290
291 local A = require 'quvi/hash'
292 local r = A.sha1sum('foo')
293 print(r)
294
295 HTTP
296 · Dump the cookies in the memory to stdout:
297
298 local C = require 'quvi/const'
299 local o = { [C.qoo_http_cookie_mode] = C.qohco_mode_jar }
300 local r = quvi.http.cookie('-', o)
301
302 · Identical to the above but use the wrapper module:
303
304 local K = require 'quvi/http/cookie'
305 local r = K.jar('-')
306
307 · Fetch an URL:
308
309 local r = quvi.http.fetch('http://example.com')
310
311 r.data would now hold the contents. If an error occurred, e.g.
312 connection failed, the library would exit the process with an
313 error.
314
315 · Same as above, but handle the error in the script:
316
317 local C = require 'quvi/const'
318 local o = { [C.qoo_croak_if_error] = false }
319
320 local r = quvi.http.fetch('http://example.com', o)
321 if r.quvi_code ~= C.qerr_ok then
322 local s =
323 string.format('quvi.http.fetch: %s (libquvi=%d, http/%d)',
324 r.error_message, r.quvi_code, r.response_code)
325 error(s)
326 end
327
328 By setting qoo_croak_if_error to false, we tell the library to only
329 register that an error occurred and return the control to the
330 script. Handling of the error is then left for the script to do.
331
332 Note
333 Typically, the scripts would not need to handle the error
334
335 · Force conversion from ISO-8859-1 to UTF-8:
336
337 local C = require 'quvi/const'
338 local o = { [C.qoo_fetch_from_charset] = 'ISO-8859-1' }
339 local r = quvi.http.fetch('http://example.com', o)
340
341 · Override user-agent header in the HTTP request:
342
343 local r = quvi.http.header('User-Agent: foo/1.0')
344 r = quvi.http.fetch(...)
345
346 · Disable an internal header in the HTTP request:
347
348 local r = quvi.http.header('Accept:')
349 r = quvi.http.fetch(...)
350
351 · Send a cookie in the HTTP request:
352
353 local r = quvi.http.header('Cookie: foo=1')
354 r = quvi.http.fetch(...)
355
356 · Query metainfo for an URL:
357
358 local r = quvi.http.metainfo('http://is.gd/SKyg8m')
359 print(r.content_length, r.content_type)
360
361 · Resolve URL redirection:
362
363 local r = quvi.http.resolve('http://is.gd/SKyg8m')
364 if #r.resolved_url >0 then
365 print('new location:', r.resolved_url)
366 end
367
369 libquvi-scripts(7), libquvi(3), quvi-modules(7), quvi-
370 modules-3rdparty(7)
371
373 Home
374
375 http://quvi.sourceforge.net/
376
377 Development code
378
379 git://repo.or.cz/libquvi.git
380
381 gitweb
382
383 http://repo.or.cz/w/libquvi.git
384
385 C API reference
386 The latest C API reference documentation may be viewed online at
387 http://quvi.sourceforge.net/r/api/0.9/.
388
389 GLib
390
391 http://developer.gnome.org/glib/stable/glib-Base64-Encoding.html
392
393 libcurl
394
395 http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTUSERAGENT
396 http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTCOOKIE
397
398 libgcrypt reference manual
399
400 http://www.gnupg.org/documentation/manuals/gcrypt/
401
403 Toni Gundogdu <legatvs@gmail.com>
404 Author.
405
407 Report bugs to the quvi-devel mailing list
408 <quvi-devel@lists.sourceforge.net> where the development and the
409 maintenance is primarily done. You do not have to be subscribed to the
410 list to send a message there.
411
413 libquvi is Free Software licensed under the GNU Affero GPLv3+
414
416 Part of the libquvi(3) suite
417
418
419
420libquvi 0.9.4 11/10/2013 QUVI-OBJECT(7)