doc/man7/quvi-object.7.txt

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