Blame doc/man7/quvi-object.7.txt

Packit 3ff1e7
quvi-object(7)
Packit 3ff1e7
==============
Packit 3ff1e7
Packit 3ff1e7
NAME
Packit 3ff1e7
----
Packit 3ff1e7
quvi-object - Overview of the libquvi quvi-object
Packit 3ff1e7
Packit 3ff1e7
DESCRIPTION
Packit 3ff1e7
-----------
Packit 3ff1e7
'quvi-object' is a collection of libquvi functions provided for the
Packit 3ff1e7
linkman:libquvi-scripts[7]. These functions vary from HTTP functions to
Packit 3ff1e7
cryptographic functions. All of the 'quvi-object' functions are
Packit 3ff1e7
implemented in C.
Packit 3ff1e7
Packit 3ff1e7
NOTE: The 'quvi-object' should not be confused with the
Packit 3ff1e7
      linkman:quvi-modules[7] which are a selection of importable
Packit 3ff1e7
      modules implemented in Lua. These modules are intended to be
Packit 3ff1e7
      loaded ('require') from the linkman:libquvi-scripts[7].
Packit 3ff1e7
Packit 3ff1e7
OPTIONS
Packit 3ff1e7
-------
Packit 3ff1e7
Each of the quvi-object functions may be passed a dictionary defining
Packit 3ff1e7
the additional option properties. The following options are supported by
Packit 3ff1e7
all of the functions:
Packit 3ff1e7
Packit 3ff1e7
qoo_croak_if_error=<boolean>::
Packit 3ff1e7
  By default the library terminates the process if an error occurs. By
Packit 3ff1e7
  setting this option to 'false', it will register the error and
Packit 3ff1e7
  continues execution, leaving the error handling for the script to
Packit 3ff1e7
  determine. See also "RETURN VALUES".
Packit 3ff1e7
Packit 3ff1e7
The 'qoo' prefix is short for 'quvi object option'. The functions will
Packit 3ff1e7
ignore any unknown options, e.g. the crypto functions would ignore the
Packit 3ff1e7
HTTP options.
Packit 3ff1e7
Packit 3ff1e7
NOTE: The options have been defined in the 'quvi/const' of
Packit 3ff1e7
      the linkman:quvi-modules[7]
Packit 3ff1e7
Packit 3ff1e7
Crypto
Packit 3ff1e7
~~~~~~
Packit 3ff1e7
Packit 3ff1e7
These options are specific to the quvi.crypto.* functions of the
Packit 3ff1e7
quvi-object.
Packit 3ff1e7
Packit 3ff1e7
qoo_crypto_algorithm=<value>::
Packit 3ff1e7
  Specifies the algorithm that should be used. The 'value' is expected to
Packit 3ff1e7
  be a string, e.g. 'sha1' or 'aes256'.
Packit 3ff1e7
Packit 3ff1e7
qoo_crypto_cipher_flags=<value>::
Packit 3ff1e7
  Specifies the cipher flags (bit OR'd, see
Packit 3ff1e7
  linkman:quvi-modules-3rdparty[7] for 'bit operations') to be used with
Packit 3ff1e7
  the cipher.  These values are identical to those defined by libgcrypt.
Packit 3ff1e7
  See the 'quvi/const' of the linkman:quvi-modules[7] for a complete
Packit 3ff1e7
  list of the available cipher flags.
Packit 3ff1e7
Packit 3ff1e7
qoo_crypto_cipher_mode=<value>::
Packit 3ff1e7
  Specifies the cipher mode to be used. These are identical to the
Packit 3ff1e7
  values defined by libgcrypt. See the 'quvi/const' of the
Packit 3ff1e7
  linkman:quvi-modules[7] for a complete list of the available cipher
Packit 3ff1e7
  modes.
Packit 3ff1e7
Packit 3ff1e7
qoo_crypto_cipher_key=<value>::
Packit 3ff1e7
  Used to specify the cipher key. It should be noted that the 'key' is
Packit 3ff1e7
  expected to be passed in hexadecimal form. See 'quvi/hex' of the
Packit 3ff1e7
  linkman:quvi-modules[7] for the conversion functions.
Packit 3ff1e7
  +
Packit 3ff1e7
  NOTE: The key derivation is left for the script to do
Packit 3ff1e7
  +
Packit 3ff1e7
  NOTE: The key is not a pass{word,phrase}
Packit 3ff1e7
  +
Packit 3ff1e7
  See also:
Packit 3ff1e7
    http://www.di-mgt.com.au/cryptokeys.html#passwordpassphraseandkey
Packit 3ff1e7
Packit 3ff1e7
HTTP
Packit 3ff1e7
~~~~
Packit 3ff1e7
Packit 3ff1e7
These options are specific to the quvi.http.* functions of the
Packit 3ff1e7
quvi-object.
Packit 3ff1e7
Packit 3ff1e7
qoo_fetch_from_charset=<charset>::
Packit 3ff1e7
  Instructs the library to convert from this charset to UTF-8. Using this
Packit 3ff1e7
  option may be required with the websites that use a specific (non-UTF8)
Packit 3ff1e7
  encoding.
Packit 3ff1e7
  +
Packit 3ff1e7
  The purpose of this option is to make sure that the data is encoded to
Packit 3ff1e7
  unicode (UTF-8) before any of it is parsed and returned to the
Packit 3ff1e7
  application using libquvi.
Packit 3ff1e7
  +
Packit 3ff1e7
  By default, libquvi converts the data which is in the encoding used for
Packit 3ff1e7
  the strings by the C runtime in the current locale into UTF-8.  IF this
Packit 3ff1e7
  fails, and the 'from charset' option is set, the library will then try
Packit 3ff1e7
  to convert to UTF-8 using the 'from charset' value.
Packit 3ff1e7
Packit 3ff1e7
qoo_http_cookie_mode=<value>::
Packit 3ff1e7
  Modify the cookie settings for the libcurl session handle. This
Packit 3ff1e7
  feature wraps the cookie features provided by
Packit 3ff1e7
  linkman:libcurl_easy_setopt[3].  See the 'quvi/const' of the
Packit 3ff1e7
  linkman:quvi-modules[7] for a complete list of the available cookie
Packit 3ff1e7
  modes.
Packit 3ff1e7
  +
Packit 3ff1e7
  See also linkman:libcurl-tutorial[3] which covers the use of cookies
Packit 3ff1e7
  with the library in greater detail.
Packit 3ff1e7
Packit 3ff1e7
RETURN VALUES
Packit 3ff1e7
-------------
Packit 3ff1e7
Each quvi-object function will return a dictionary containing the
Packit 3ff1e7
following values:
Packit 3ff1e7
Packit 3ff1e7
error_message::
Packit 3ff1e7
  The error message, or an empty value.
Packit 3ff1e7
Packit 3ff1e7
quvi_code::
Packit 3ff1e7
  The code returned by the library. See also 'quvi/const'
Packit 3ff1e7
  of linkman:quvi-modules[7].
Packit 3ff1e7
Packit 3ff1e7
Refer to the function documentation for the information about the additional
Packit 3ff1e7
values returned in the dictionary.
Packit 3ff1e7
Packit 3ff1e7
FUNCTIONS
Packit 3ff1e7
---------
Packit 3ff1e7
Packit 3ff1e7
Base64
Packit 3ff1e7
~~~~~~
Packit 3ff1e7
Packit 3ff1e7
quvi.base64.encode(<plaintext>[,qoo])::
Packit 3ff1e7
  Encode the 'plaintext' to base64 format. The 'plaintext' is expected
Packit 3ff1e7
  to be passed in hexadecimal form. See 'quvi/hex' of the
Packit 3ff1e7
  linkman:quvi-modules[7] for the conversion functions.
Packit 3ff1e7
  +
Packit 3ff1e7
  The second argument ('qoo') is expected to be a dictionary of
Packit 3ff1e7
  additional 'quvi object options', if defined at all.
Packit 3ff1e7
  +
Packit 3ff1e7
  The function will return the 'base64' value in the dictionary.
Packit 3ff1e7
Packit 3ff1e7
quvi.base64.decode(<base64>)::
Packit 3ff1e7
  Decode the 'base64' value to plaintext.
Packit 3ff1e7
  +
Packit 3ff1e7
  The function will return the 'plaintext' value in the dictionary.
Packit 3ff1e7
  The value is returned in hexadecimal form.
Packit 3ff1e7
Packit 3ff1e7
Crypto
Packit 3ff1e7
~~~~~~
Packit 3ff1e7
Packit 3ff1e7
The crypto facility of the quvi-object wraps the libgcrypt symmetric
Packit 3ff1e7
cryptography and the hash (message digest) functions.
Packit 3ff1e7
Packit 3ff1e7
NOTE: The availability of the algorithms is determined by libgcrypt, and
Packit 3ff1e7
      how it was built
Packit 3ff1e7
Packit 3ff1e7
quvi.crypto.encrypt(<plaintext>, <qoo>)::
Packit 3ff1e7
  Encrypt the 'plaintext'. The 'plaintext' is expected to be passed in
Packit 3ff1e7
  hexadecimal form. See 'quvi/hex' of the linkman:quvi-modules[7] for
Packit 3ff1e7
  the conversion functions.
Packit 3ff1e7
  +
Packit 3ff1e7
  The second argument ('qoo') is expected to be a dictionary containing
Packit 3ff1e7
  the cipher options.
Packit 3ff1e7
  +
Packit 3ff1e7
  The function will return the 'ciphertext' value in the dictionary.
Packit 3ff1e7
  The value is returned in hexadecimal form.
Packit 3ff1e7
Packit 3ff1e7
quvi.crypto.decrypt(<ciphertext>, <qoo>)::
Packit 3ff1e7
  Decrypt the 'ciphertext'. The 'ciphertext' is expected to be passed in
Packit 3ff1e7
  hexadecimal form. See 'quvi/hex' of the linkman:quvi-modules[7] for
Packit 3ff1e7
  the conversion functions.
Packit 3ff1e7
  +
Packit 3ff1e7
  The second argument ('qoo') is expected to be a dictionary containing
Packit 3ff1e7
  the cipher options.
Packit 3ff1e7
  +
Packit 3ff1e7
  The function will return the 'plaintext' value in the dictionary.
Packit 3ff1e7
  This value is returned in hexadecimal form.
Packit 3ff1e7
Packit 3ff1e7
quvi.crypto.hash(<value>, <qoo>)::
Packit 3ff1e7
  Generate a hash from the 'value'. The 'value' is expected to be passed
Packit 3ff1e7
  in hexadecimal format. See 'quvi/hex' of the linkman:quvi-modules[7]
Packit 3ff1e7
  for the conversion functions.
Packit 3ff1e7
  +
Packit 3ff1e7
  The second argument ('qoo') is expected to be a dictionary containing
Packit 3ff1e7
  the hash options, e.g. the algorithm that should be used.
Packit 3ff1e7
  +
Packit 3ff1e7
  The function will return the 'digest' value in the dictionary.
Packit 3ff1e7
  The value is returned in hexadecimal form.
Packit 3ff1e7
Packit 3ff1e7
HTTP
Packit 3ff1e7
~~~~
Packit 3ff1e7
Packit 3ff1e7
The HTTP functions will return 'response_code' along the other "RETURN
Packit 3ff1e7
VALUES", and the values specific to the HTTP function.
Packit 3ff1e7
Packit 3ff1e7
quvi.http.cookie(<VALUE>,<qoo>)::
Packit 3ff1e7
  Modify the libcurl session handle cookie settings that libquvi
Packit 3ff1e7
  currently uses.
Packit 3ff1e7
  +
Packit 3ff1e7
  The second argument ('qoo') is expected to be a dictionary containing
Packit 3ff1e7
  the cookie options, e.g. the cookie mode that should be used.
Packit 3ff1e7
  +
Packit 3ff1e7
  The complete list of the available cookie modes can be found in the
Packit 3ff1e7
  'quvi/const' module of the linkman:quvi-modules[7]. The mode names are
Packit 3ff1e7
  named after their equivalent CURLOPT_COOKIE{SESSION,FILE,LIST,JAR}
Packit 3ff1e7
  variable names. For a description of each option, see
Packit 3ff1e7
  linkman:libcurl_easy_setopt[3].
Packit 3ff1e7
  +
Packit 3ff1e7
  This function will not return any additional values in the dictionary.
Packit 3ff1e7
Packit 3ff1e7
NOTE: libquvi will ignore any calls to quvi.http.cookie unless
Packit 3ff1e7
      QUVI_OPTION_ALLOW_COOKIES is QUVI_TRUE
Packit 3ff1e7
Packit 3ff1e7
NOTE: libcurl will parse the received cookies and use them in the
Packit 3ff1e7
      subsequent HTTP requests only if libquvi QUVI_OPTION_ALLOW_COOKIES
Packit 3ff1e7
      is QUVI_TRUE
Packit 3ff1e7
Packit 3ff1e7
quvi.http.fetch(<URL>[,qoo])::
Packit 3ff1e7
  Fetch an URL over an HTTP connection.
Packit 3ff1e7
  +
Packit 3ff1e7
  The second argument ('qoo') is expected to be a dictionary of
Packit 3ff1e7
  additional 'quvi object options', if defined at all.
Packit 3ff1e7
  +
Packit 3ff1e7
  The function will return the 'data' value among the values in
Packit 3ff1e7
  the returned dictionary.
Packit 3ff1e7
Packit 3ff1e7
quvi.http.header(<VALUE>[,qoo])::
Packit 3ff1e7
  Add, remove or replace internally used libcurl HTTP headers.
Packit 3ff1e7
  +
Packit 3ff1e7
  The second argument ('qoo') is expected to be a dictionary of
Packit 3ff1e7
  additional 'quvi object options', if defined at all.
Packit 3ff1e7
  +
Packit 3ff1e7
  This function essentially wraps CURLOPT_HTTPHEADER, and will not
Packit 3ff1e7
  return any additional values in the dictionary. See
Packit 3ff1e7
  linkman:curl_easy_setopt[3] for the full description of
Packit 3ff1e7
  CURLOPT_HTTPHEADER.
Packit 3ff1e7
Packit 3ff1e7
NOTE: To clear the custom headers, pass "" as the VALUE; the custom
Packit 3ff1e7
      headers are also cleared automatically when a support script
Packit 3ff1e7
      function 'parse' is called
Packit 3ff1e7
Packit 3ff1e7
quvi.http.metainfo(<URL>[,qoo])::
Packit 3ff1e7
  Query the HTTP metainfo for the URL.
Packit 3ff1e7
  +
Packit 3ff1e7
  The second argument ('qoo') is expected to be a dictionary of
Packit 3ff1e7
  additional 'quvi object options', if defined at all.
Packit 3ff1e7
  +
Packit 3ff1e7
  The function will return the 'content_length' and the 'content_type'
Packit 3ff1e7
  values among the values in the returned dictionary.
Packit 3ff1e7
Packit 3ff1e7
quvi.http.resolve(<URL>[,qoo])::
Packit 3ff1e7
  Resolve an URL redirection.
Packit 3ff1e7
  +
Packit 3ff1e7
  The second argument ('qoo') is expected to be a dictionary of
Packit 3ff1e7
  additional 'quvi object options', if defined at all.
Packit 3ff1e7
  +
Packit 3ff1e7
  The function will return the 'resolved_url' among the values in the
Packit 3ff1e7
  returned dictionary. If the URL did not redirect to another location,
Packit 3ff1e7
  the value of the 'resolved_url' is left empty.
Packit 3ff1e7
Packit 3ff1e7
EXAMPLES
Packit 3ff1e7
--------
Packit 3ff1e7
Packit 3ff1e7
Base64
Packit 3ff1e7
~~~~~~
Packit 3ff1e7
Packit 3ff1e7
* Base64 encode a string:
Packit 3ff1e7
+
Packit 3ff1e7
----
Packit 3ff1e7
local H = require 'quvi/hex'
Packit 3ff1e7
local s = H.to_hex('foo') -- Pass in hexadecimal form
Packit 3ff1e7
Packit 3ff1e7
local r = quvi.base64.encode(s)
Packit 3ff1e7
print(r.base64)
Packit 3ff1e7
----
Packit 3ff1e7
Packit 3ff1e7
* Reverse the process:
Packit 3ff1e7
+
Packit 3ff1e7
----
Packit 3ff1e7
local r = quvi.base64.decode(r.base64)
Packit 3ff1e7
local s = H.to_str(r.plaintext)
Packit 3ff1e7
----
Packit 3ff1e7
Packit 3ff1e7
Crypto
Packit 3ff1e7
~~~~~~
Packit 3ff1e7
Packit 3ff1e7
* Encrypt plaintext:
Packit 3ff1e7
+
Packit 3ff1e7
----
Packit 3ff1e7
local plaintext = 'f34481ec3cc627bacd5dc3fb08f273e6'
Packit 3ff1e7
local key = '00000000000000000000000000000000'
Packit 3ff1e7
Packit 3ff1e7
local C = require 'quvi/const'
Packit 3ff1e7
local o = {
Packit 3ff1e7
  [C.qoo_crypto_cipher_mode] = C.qoco_cipher_mode_cbc,
Packit 3ff1e7
  [C.qoo_crypto_algorithm] = 'aes',
Packit 3ff1e7
  [C.qoo_crypto_cipher_key = key
Packit 3ff1e7
}
Packit 3ff1e7
Packit 3ff1e7
local r = quvi.crypto.encrypt(plaintext, o)
Packit 3ff1e7
print(r.ciphertext)
Packit 3ff1e7
----
Packit 3ff1e7
Packit 3ff1e7
* Reverse the process:
Packit 3ff1e7
+
Packit 3ff1e7
----
Packit 3ff1e7
local r = quvi.crypto.decrypt(r.ciphertext, o)
Packit 3ff1e7
print(r.plaintext)
Packit 3ff1e7
----
Packit 3ff1e7
Packit 3ff1e7
* Generate a hash (message digest):
Packit 3ff1e7
+
Packit 3ff1e7
----
Packit 3ff1e7
local H = require 'quvi/hex'
Packit 3ff1e7
local s = H.to_hex('foo') -- Pass in hexadecimal form
Packit 3ff1e7
Packit 3ff1e7
local C = require 'quvi/const'
Packit 3ff1e7
local o = { [C.qoo_crypto_algorithm] = 'sha1' }
Packit 3ff1e7
Packit 3ff1e7
local r = quvi.crypto.hash(s, o)
Packit 3ff1e7
print(r.digest)
Packit 3ff1e7
----
Packit 3ff1e7
Packit 3ff1e7
* Same as above, but use the shorthand function:
Packit 3ff1e7
+
Packit 3ff1e7
----
Packit 3ff1e7
local A = require 'quvi/hash'
Packit 3ff1e7
local r = A.sha1sum('foo')
Packit 3ff1e7
print(r)
Packit 3ff1e7
----
Packit 3ff1e7
Packit 3ff1e7
HTTP
Packit 3ff1e7
~~~~
Packit 3ff1e7
Packit 3ff1e7
* Dump the cookies in the memory to stdout:
Packit 3ff1e7
+
Packit 3ff1e7
----
Packit 3ff1e7
local C = require 'quvi/const'
Packit 3ff1e7
local o = { [C.qoo_http_cookie_mode] = C.qohco_mode_jar }
Packit 3ff1e7
local r = quvi.http.cookie('-', o)
Packit 3ff1e7
----
Packit 3ff1e7
Packit 3ff1e7
* Identical to the above but use the wrapper module:
Packit 3ff1e7
+
Packit 3ff1e7
----
Packit 3ff1e7
local K = require 'quvi/http/cookie'
Packit 3ff1e7
local r = K.jar('-')
Packit 3ff1e7
----
Packit 3ff1e7
Packit 3ff1e7
* Fetch an URL:
Packit 3ff1e7
+
Packit 3ff1e7
----
Packit 3ff1e7
local r = quvi.http.fetch('http://example.com')
Packit 3ff1e7
----
Packit 3ff1e7
+
Packit 3ff1e7
r.data would now hold the contents. If an error occurred, e.g.
Packit 3ff1e7
connection failed, the library would exit the process with an error.
Packit 3ff1e7
Packit 3ff1e7
* Same as above, but handle the error in the script:
Packit 3ff1e7
+
Packit 3ff1e7
----
Packit 3ff1e7
local C = require 'quvi/const'
Packit 3ff1e7
local o = { [C.qoo_croak_if_error] = false }
Packit 3ff1e7
Packit 3ff1e7
local r = quvi.http.fetch('http://example.com', o)
Packit 3ff1e7
if r.quvi_code ~= C.qerr_ok then
Packit 3ff1e7
  local s =
Packit 3ff1e7
    string.format('quvi.http.fetch: %s (libquvi=%d, http/%d)',
Packit 3ff1e7
                  r.error_message, r.quvi_code, r.response_code)
Packit 3ff1e7
  error(s)
Packit 3ff1e7
end
Packit 3ff1e7
----
Packit 3ff1e7
+
Packit 3ff1e7
By setting qoo_croak_if_error to 'false', we tell the library to
Packit 3ff1e7
only register that an error occurred and return the control to
Packit 3ff1e7
the script. Handling of the error is then left for the script to do.
Packit 3ff1e7
+
Packit 3ff1e7
NOTE: Typically, the scripts would not need to handle the error
Packit 3ff1e7
Packit 3ff1e7
* Force conversion from ISO-8859-1 to UTF-8:
Packit 3ff1e7
+
Packit 3ff1e7
----
Packit 3ff1e7
local C = require 'quvi/const'
Packit 3ff1e7
local o = { [C.qoo_fetch_from_charset] = 'ISO-8859-1' }
Packit 3ff1e7
local r = quvi.http.fetch('http://example.com', o)
Packit 3ff1e7
----
Packit 3ff1e7
Packit 3ff1e7
* Override user-agent header in the HTTP request:
Packit 3ff1e7
+
Packit 3ff1e7
----
Packit 3ff1e7
local r = quvi.http.header('User-Agent: foo/1.0')
Packit 3ff1e7
r = quvi.http.fetch(...)
Packit 3ff1e7
----
Packit 3ff1e7
Packit 3ff1e7
* Disable an internal header in the HTTP request:
Packit 3ff1e7
+
Packit 3ff1e7
----
Packit 3ff1e7
local r = quvi.http.header('Accept:')
Packit 3ff1e7
r = quvi.http.fetch(...)
Packit 3ff1e7
----
Packit 3ff1e7
Packit 3ff1e7
* Send a cookie in the HTTP request:
Packit 3ff1e7
+
Packit 3ff1e7
----
Packit 3ff1e7
local r = quvi.http.header('Cookie: foo=1')
Packit 3ff1e7
r = quvi.http.fetch(...)
Packit 3ff1e7
----
Packit 3ff1e7
Packit 3ff1e7
* Query metainfo for an URL:
Packit 3ff1e7
+
Packit 3ff1e7
----
Packit 3ff1e7
local r = quvi.http.metainfo('http://is.gd/SKyg8m')
Packit 3ff1e7
print(r.content_length, r.content_type)
Packit 3ff1e7
----
Packit 3ff1e7
Packit 3ff1e7
* Resolve URL redirection:
Packit 3ff1e7
+
Packit 3ff1e7
----
Packit 3ff1e7
local r = quvi.http.resolve('http://is.gd/SKyg8m')
Packit 3ff1e7
if #r.resolved_url >0 then
Packit 3ff1e7
  print('new location:', r.resolved_url)
Packit 3ff1e7
end
Packit 3ff1e7
----
Packit 3ff1e7
Packit 3ff1e7
SEE ALSO
Packit 3ff1e7
--------
Packit 3ff1e7
linkman:libquvi-scripts[7], linkman:libquvi[3], linkman:quvi-modules[7],
Packit 3ff1e7
linkman:quvi-modules-3rdparty[7]
Packit 3ff1e7
Packit 3ff1e7
include::../footer.txt[]