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: Cookies are always enabled for the current libcurl session handle,
 205       meaning that libcurl will parse the received cookies and use them
 206       in the subsequent HTTP requests
 207
 208 quvi.http.fetch(<URL>[,qoo])::
 209   Fetch an URL over an HTTP connection.
 210   +
 211   The second argument ('qoo') is expected to be a dictionary of
 212   additional 'quvi object options', if defined at all.
 213   +
 214   The function will return the 'data' value among the values in
 215   the returned dictionary.
 216
 217 quvi.http.header(<VALUE>[,qoo])::
 218   Add, remove or replace internally used libcurl HTTP headers.
 219   +
 220   The second argument ('qoo') is expected to be a dictionary of
 221   additional 'quvi object options', if defined at all.
 222   +
 223   This function essentially wraps CURLOPT_HTTPHEADER, and will not
 224   return any additional values in the dictionary. See
 225   linkman:curl_easy_setopt[3] for the full description of
 226   CURLOPT_HTTPHEADER.
 227
 228 NOTE: To clear the custom headers, pass "" as the VALUE; the custom
 229       headers are also cleared automatically when a support script
 230       function 'parse' is called
 231
 232 quvi.http.metainfo(<URL>[,qoo])::
 233   Query the HTTP metainfo for the URL.
 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 'content_length' and the 'content_type'
 239   values among the values in the returned dictionary.
 240
 241 quvi.http.resolve(<URL>[,qoo])::
 242   Resolve an URL redirection.
 243   +
 244   The second argument ('qoo') is expected to be a dictionary of
 245   additional 'quvi object options', if defined at all.
 246   +
 247   The function will return the 'resolved_url' among the values in the
 248   returned dictionary. If the URL did not redirect to another location,
 249   the value of the 'resolved_url' is left empty.
 250
 251 EXAMPLES
 252 --------
 253
 254 Base64
 255 ~~~~~~
 256
 257 * Base64 encode a string:
 258 +
 259 ----
 260 local H = require 'quvi/hex'
 261 local s = H.to_hex('foo') -- Pass in hexadecimal form
 262
 263 local r = quvi.base64.encode(s)
 264 print(r.base64)
 265 ----
 266
 267 * Reverse the process:
 268 +
 269 ----
 270 local r = quvi.base64.decode(r.base64)
 271 local s = H.to_str(r.plaintext)
 272 ----
 273
 274 Crypto
 275 ~~~~~~
 276
 277 * Encrypt plaintext:
 278 +
 279 ----
 280 local plaintext = 'f34481ec3cc627bacd5dc3fb08f273e6'
 281 local key = '00000000000000000000000000000000'
 282
 283 local C = require 'quvi/const'
 284 local o = {
 285   [C.qoo_crypto_cipher_mode] = C.qoco_cipher_mode_cbc,
 286   [C.qoo_crypto_algorithm] = 'aes',
 287   [C.qoo_crypto_cipher_key = key
 288 }
 289
 290 local r = quvi.crypto.encrypt(plaintext, o)
 291 print(r.ciphertext)
 292 ----
 293
 294 * Reverse the process:
 295 +
 296 ----
 297 local r = quvi.crypto.decrypt(r.ciphertext, o)
 298 print(r.plaintext)
 299 ----
 300
 301 * Generate a hash (message digest):
 302 +
 303 ----
 304 local H = require 'quvi/hex'
 305 local s = H.to_hex('foo') -- Pass in hexadecimal form
 306
 307 local C = require 'quvi/const'
 308 local o = { [C.qoo_crypto_algorithm] = 'sha1' }
 309
 310 local r = quvi.crypto.hash(s, o)
 311 print(r.digest)
 312 ----
 313
 314 * Same as above, but use the shorthand function:
 315 +
 316 ----
 317 local A = require 'quvi/hash'
 318 local r = A.sha1sum('foo')
 319 print(r)
 320 ----
 321
 322 HTTP
 323 ~~~~
 324
 325 * Dump the cookies in the memory to stdout:
 326 +
 327 ----
 328 local C = require 'quvi/const'
 329 local o = { [C.qoo_http_cookie_mode] = C.qohco_mode_jar }
 330 local r = quvi.http.cookie('-', o)
 331 ----
 332
 333 * Identical to the above but use the wrapper module:
 334 +
 335 ----
 336 local K = require 'quvi/http/cookie'
 337 local r = K.jar('-')
 338 ----
 339
 340 * Fetch an URL:
 341 +
 342 ----
 343 local r = quvi.http.fetch('http://example.com')
 344 ----
 345 +
 346 r.data would now hold the contents. If an error occurred, e.g.
 347 connection failed, the library would exit the process with an error.
 348
 349 * Same as above, but handle the error in the script:
 350 +
 351 ----
 352 local C = require 'quvi/const'
 353 local o = { [C.qoo_croak_if_error] = false }
 354
 355 local r = quvi.http.fetch('http://example.com', o)
 356 if r.quvi_code ~= C.qerr_ok then
 357   local s =
 358     string.format('quvi.http.fetch: %s (libquvi=%d, http/%d)',
 359                   r.error_message, r.quvi_code, r.response_code)
 360   error(s)
 361 end
 362 ----
 363 +
 364 By setting qoo_croak_if_error to 'false', we tell the library to
 365 only register that an error occurred and return the control to
 366 the script. Handling of the error is then left for the script to do.
 367 +
 368 NOTE: Typically, the scripts would not need to handle the error
 369
 370 * Force conversion from ISO-8859-1 to UTF-8:
 371 +
 372 ----
 373 local C = require 'quvi/const'
 374 local o = { [C.qoo_fetch_from_charset] = 'ISO-8859-1' }
 375 local r = quvi.http.fetch('http://example.com', o)
 376 ----
 377
 378 * Override user-agent header in the HTTP request:
 379 +
 380 ----
 381 local r = quvi.http.header('User-Agent: foo/1.0')
 382 r = quvi.http.fetch(...)
 383 ----
 384
 385 * Disable an internal header in the HTTP request:
 386 +
 387 ----
 388 local r = quvi.http.header('Accept:')
 389 r = quvi.http.fetch(...)
 390 ----
 391
 392 * Send a cookie in the HTTP request:
 393 +
 394 ----
 395 local r = quvi.http.header('Cookie: foo=1')
 396 r = quvi.http.fetch(...)
 397 ----
 398
 399 * Query metainfo for an URL:
 400 +
 401 ----
 402 local r = quvi.http.metainfo('http://is.gd/SKyg8m')
 403 print(r.content_length, r.content_type)
 404 ----
 405
 406 * Resolve URL redirection:
 407 +
 408 ----
 409 local r = quvi.http.resolve('http://is.gd/SKyg8m')
 410 if #r.resolved_url >0 then
 411   print('new location:', r.resolved_url)
 412 end
 413 ----
 414
 415 SEE ALSO
 416 --------
 417 linkman:libquvi-scripts[7], linkman:libquvi[3], linkman:quvi-modules[7],
 418 linkman:quvi-modules-3rdparty[7]
 419
 420 include::../footer.txt[]