1QUVI-OBJECT(7) libquvi Manual QUVI-OBJECT(7)
2
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 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 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 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 Note
36 The options have been defined in the quvi/const of the quvi-
37 modules(7)
38 Crypto
40 These options are specific to the quvi.crypto.* functions of the
41 quvi-object.
42 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 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 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 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 NOTE: The key derivation is left for the script to do
64 NOTE: The key is not a pass{word,phrase}
66 See also:
68 http://www.di-mgt.com.au/cryptokeys.html#passwordpassphraseandkey
69 HTTP
71 These options are specific to the quvi.http.* functions of the
72 quvi-object.
73 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 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 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 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 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 error_message
102 The error message, or an empty value.
103 quvi_code
105 The code returned by the library. See also quvi/const of quvi-
106 modules(7).
107 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 The second argument (qoo) is expected to be a dictionary of
119 additional quvi object options, if defined at all.
120 The function will return the base64 value in the dictionary.
122 quvi.base64.decode(<base64>)
124 Decode the base64 value to plaintext.
125 The function will return the plaintext value in the dictionary. The
127 value is returned in hexadecimal form.
128 Crypto
130 The crypto facility of the quvi-object wraps the libgcrypt symmetric
131 cryptography and the hash (message digest) functions.
132 Note
134 The availability of the algorithms is determined by libgcrypt, and
135 how it was built
136 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 The second argument (qoo) is expected to be a dictionary containing
143 the cipher options.
144 The function will return the ciphertext value in the dictionary.
146 The value is returned in hexadecimal form.
147 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 The second argument (qoo) is expected to be a dictionary containing
154 the cipher options.
155 The function will return the plaintext value in the dictionary.
157 This value is returned in hexadecimal form.
158 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 The second argument (qoo) is expected to be a dictionary containing
165 the hash options, e.g. the algorithm that should be used.
166 The function will return the digest value in the dictionary. The
168 value is returned in hexadecimal form.
169 HTTP
171 The HTTP functions will return response_code along the other "RETURN
172 VALUES", and the values specific to the HTTP function.
173 quvi.http.cookie(<VALUE>,<qoo>)
175 Modify the libcurl session handle cookie settings that libquvi
176 currently uses.
177 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 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 This function will not return any additional values in the
188 dictionary.
189 Note
191 libquvi will ignore any calls to quvi.http.cookie unless
192 QUVI_OPTION_ALLOW_COOKIES is QUVI_TRUE
193 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 quvi.http.fetch(<URL>[,qoo])
200 Fetch an URL over an HTTP connection.
201 The second argument (qoo) is expected to be a dictionary of
203 additional quvi object options, if defined at all.
204 The function will return the data value among the values in the
206 returned dictionary.
207 quvi.http.header(<VALUE>[,qoo])
209 Add, remove or replace internally used libcurl HTTP headers.
210 The second argument (qoo) is expected to be a dictionary of
212 additional quvi object options, if defined at all.
213 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 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 quvi.http.metainfo(<URL>[,qoo])
224 Query the HTTP metainfo for the URL.
225 The second argument (qoo) is expected to be a dictionary of
227 additional quvi object options, if defined at all.
228 The function will return the content_length and the content_type
230 values among the values in the returned dictionary.
231 quvi.http.resolve(<URL>[,qoo])
233 Resolve an URL redirection.
234 The second argument (qoo) is expected to be a dictionary of
236 additional quvi object options, if defined at all.
237 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 local H = require 'quvi/hex'
247 local s = H.to_hex('foo') -- Pass in hexadecimal form
248 local r = quvi.base64.encode(s)
250 print(r.base64)
251 · Reverse the process:
253 local r = quvi.base64.decode(r.base64)
255 local s = H.to_str(r.plaintext)
256 Crypto
258 · Encrypt plaintext:
259 local plaintext = 'f34481ec3cc627bacd5dc3fb08f273e6'
261 local key = '00000000000000000000000000000000'
262 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 local r = quvi.crypto.encrypt(plaintext, o)
271 print(r.ciphertext)
272 · Reverse the process:
274 local r = quvi.crypto.decrypt(r.ciphertext, o)
276 print(r.plaintext)
277 · Generate a hash (message digest):
279 local H = require 'quvi/hex'
281 local s = H.to_hex('foo') -- Pass in hexadecimal form
282 local C = require 'quvi/const'
284 local o = { [C.qoo_crypto_algorithm] = 'sha1' }
285 local r = quvi.crypto.hash(s, o)
287 print(r.digest)
288 · Same as above, but use the shorthand function:
290 local A = require 'quvi/hash'
292 local r = A.sha1sum('foo')
293 print(r)
294 HTTP
296 · Dump the cookies in the memory to stdout:
297 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 · Identical to the above but use the wrapper module:
303 local K = require 'quvi/http/cookie'
305 local r = K.jar('-')
306 · Fetch an URL:
308 local r = quvi.http.fetch('http://example.com')
310 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 · Same as above, but handle the error in the script:
316 local C = require 'quvi/const'
318 local o = { [C.qoo_croak_if_error] = false }
319 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 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 Note
333 Typically, the scripts would not need to handle the error
334 · Force conversion from ISO-8859-1 to UTF-8:
336 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 · Override user-agent header in the HTTP request:
342 local r = quvi.http.header('User-Agent: foo/1.0')
344 r = quvi.http.fetch(...)
345 · Disable an internal header in the HTTP request:
347 local r = quvi.http.header('Accept:')
349 r = quvi.http.fetch(...)
350 · Send a cookie in the HTTP request:
352 local r = quvi.http.header('Cookie: foo=1')
354 r = quvi.http.fetch(...)
355 · Query metainfo for an URL:
357 local r = quvi.http.metainfo('http://is.gd/SKyg8m')
359 print(r.content_length, r.content_type)
360 · Resolve URL redirection:
362 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 http://quvi.sourceforge.net/
376 Development code
378 git://repo.or.cz/libquvi.git
380 gitweb
382 http://repo.or.cz/w/libquvi.git
384 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 GLib
390 http://developer.gnome.org/glib/stable/glib-Base64-Encoding.html
392 libcurl
394 http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTUSERAGENT
396 http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTCOOKIE
397 libgcrypt reference manual
399 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
417libquvi 0.9.4 11/10/2013 QUVI-OBJECT(7)