Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
QUVI-OBJECT(7)			libquvi	Manual			QUVI-OBJECT(7)

NAME
       quvi-object - Overview of the libquvi quvi-object

DESCRIPTION
       quvi-object is a	collection of libquvi functions	provided for the
       libquvi-scripts(7). These functions vary	from HTTP functions to
       cryptographic functions.	All of the quvi-object functions are
       implemented in C.

	   Note
	   The quvi-object should not be confused with the quvi-modules(7)
	   which are a selection of importable modules implemented in Lua.
	   These modules are intended to be loaded (require) from the libquvi-
	   scripts(7).

OPTIONS
       Each of the quvi-object functions may be	passed a dictionary defining
       the additional option properties. The following options are supported
       by all of the functions:

       qoo_croak_if_error=<boolean>
	   By default the library terminates the process if an error occurs.
	   By setting this option to false, it will register the error and
	   continues execution,	leaving	the error handling for the script to
	   determine. See also "RETURN VALUES".

       The qoo prefix is short for quvi	object option. The functions will
       ignore any unknown options, e.g.	the crypto functions would ignore the
       HTTP options.

	   Note
	   The options have been defined in the	quvi/const of the quvi-
	   modules(7)

   Crypto
       These options are specific to the quvi.crypto.* functions of the
       quvi-object.

       qoo_crypto_algorithm=<value>
	   Specifies the algorithm that	should be used.	The value is expected
	   to be a string, e.g.	 sha1 or aes256.

       qoo_crypto_cipher_flags=<value>
	   Specifies the cipher	flags (bit OR'd, see quvi-modules-3rdparty(7)
	   for bit operations) to be used with the cipher. These values	are
	   identical to	those defined by libgcrypt. See	the quvi/const of the
	   quvi-modules(7) for a complete list of the available	cipher flags.

       qoo_crypto_cipher_mode=<value>
	   Specifies the cipher	mode to	be used. These are identical to	the
	   values defined by libgcrypt.	See the	quvi/const of the quvi-
	   modules(7) for a complete list of the available cipher modes.

       qoo_crypto_cipher_key=<value>
	   Used	to specify the cipher key. It should be	noted that the key is
	   expected to be passed in hexadecimal	form. See quvi/hex of the
	   quvi-modules(7) for the conversion functions.

	   NOTE: The key derivation is left for	the script to do

	   NOTE: The key is not	a pass{word,phrase}

	   See also:
	   http://www.di-mgt.com.au/cryptokeys.html#passwordpassphraseandkey

   HTTP
       These options are specific to the quvi.http.* functions of the
       quvi-object.

       qoo_fetch_from_charset=<charset>
	   Instructs the library to convert from this charset to UTF-8.	Using
	   this	option may be required with the	websites that use a specific
	   (non-UTF8) encoding.

	   The purpose of this option is to make sure that the data is encoded
	   to unicode (UTF-8) before any of it is parsed and returned to the
	   application using libquvi.

	   By default, libquvi converts	the data which is in the encoding used
	   for the strings by the C runtime in the current locale into UTF-8.
	   IF this fails, and the from charset option is set, the library will
	   then	try to convert to UTF-8	using the from charset value.

       qoo_http_cookie_mode=<value>
	   Modify the cookie settings for the libcurl session handle. This
	   feature wraps the cookie features provided by
	   libcurl_easy_setopt(3). See the quvi/const of the quvi-modules(7)
	   for a complete list of the available	cookie modes.

	   See also libcurl-tutorial(3)	which covers the use of	cookies	with
	   the library in greater detail.

RETURN VALUES
       Each quvi-object	function will return a dictionary containing the
       following values:

       error_message
	   The error message, or an empty value.

       quvi_code
	   The code returned by	the library. See also quvi/const of quvi-
	   modules(7).

       Refer to	the function documentation for the information about the
       additional values returned in the dictionary.

FUNCTIONS
   Base64
       quvi.base64.encode(<plaintext>[,qoo])
	   Encode the plaintext	to base64 format. The plaintext	is expected to
	   be passed in	hexadecimal form. See quvi/hex of the quvi-modules(7)
	   for the conversion functions.

	   The second argument (qoo) is	expected to be a dictionary of
	   additional quvi object options, if defined at all.

	   The function	will return the	base64 value in	the dictionary.

       quvi.base64.decode(<base64>)
	   Decode the base64 value to plaintext.

	   The function	will return the	plaintext value	in the dictionary. The
	   value is returned in	hexadecimal form.

   Crypto
       The crypto facility of the quvi-object wraps the	libgcrypt symmetric
       cryptography and	the hash (message digest) functions.

	   Note
	   The availability of the algorithms is determined by libgcrypt, and
	   how it was built

       quvi.crypto.encrypt(<plaintext>,	<qoo>)
	   Encrypt the plaintext. The plaintext	is expected to be passed in
	   hexadecimal form. See quvi/hex of the quvi-modules(7) for the
	   conversion functions.

	   The second argument (qoo) is	expected to be a dictionary containing
	   the cipher options.

	   The function	will return the	ciphertext value in the	dictionary.
	   The value is	returned in hexadecimal	form.

       quvi.crypto.decrypt(<ciphertext>, <qoo>)
	   Decrypt the ciphertext. The ciphertext is expected to be passed in
	   hexadecimal form. See quvi/hex of the quvi-modules(7) for the
	   conversion functions.

	   The second argument (qoo) is	expected to be a dictionary containing
	   the cipher options.

	   The function	will return the	plaintext value	in the dictionary.
	   This	value is returned in hexadecimal form.

       quvi.crypto.hash(<value>, <qoo>)
	   Generate a hash from	the value. The value is	expected to be passed
	   in hexadecimal format. See quvi/hex of the quvi-modules(7) for the
	   conversion functions.

	   The second argument (qoo) is	expected to be a dictionary containing
	   the hash options, e.g. the algorithm	that should be used.

	   The function	will return the	digest value in	the dictionary.	The
	   value is returned in	hexadecimal form.

   HTTP
       The HTTP	functions will return response_code along the other "RETURN
       VALUES",	and the	values specific	to the HTTP function.

       quvi.http.cookie(<VALUE>,<qoo>)
	   Modify the libcurl session handle cookie settings that libquvi
	   currently uses.

	   The second argument (qoo) is	expected to be a dictionary containing
	   the cookie options, e.g. the	cookie mode that should	be used.

	   The complete	list of	the available cookie modes can be found	in the
	   quvi/const module of	the quvi-modules(7). The mode names are	named
	   after their equivalent CURLOPT_COOKIE{SESSION,FILE,LIST,JAR}
	   variable names. For a description of	each option, see
	   libcurl_easy_setopt(3).

	   This	function will not return any additional	values in the
	   dictionary.

	   Note
	   libquvi will	ignore any calls to quvi.http.cookie unless
	   QUVI_OPTION_ALLOW_COOKIES is	QUVI_TRUE

	   Note
	   libcurl will	parse the received cookies and use them	in the
	   subsequent HTTP requests only if libquvi QUVI_OPTION_ALLOW_COOKIES
	   is QUVI_TRUE

       quvi.http.fetch(<URL>[,qoo])
	   Fetch an URL	over an	HTTP connection.

	   The second argument (qoo) is	expected to be a dictionary of
	   additional quvi object options, if defined at all.

	   The function	will return the	data value among the values in the
	   returned dictionary.

       quvi.http.header(<VALUE>[,qoo])
	   Add,	remove or replace internally used libcurl HTTP headers.

	   The second argument (qoo) is	expected to be a dictionary of
	   additional quvi object options, if defined at all.

	   This	function essentially wraps CURLOPT_HTTPHEADER, and will	not
	   return any additional values	in the dictionary. See
	   curl_easy_setopt(3) for the full description	of CURLOPT_HTTPHEADER.

	   Note
	   To clear the	custom headers,	pass ""	as the VALUE; the custom
	   headers are also cleared automatically when a support script
	   function parse is called

       quvi.http.metainfo(<URL>[,qoo])
	   Query the HTTP metainfo for the URL.

	   The second argument (qoo) is	expected to be a dictionary of
	   additional quvi object options, if defined at all.

	   The function	will return the	content_length and the content_type
	   values among	the values in the returned dictionary.

       quvi.http.resolve(<URL>[,qoo])
	   Resolve an URL redirection.

	   The second argument (qoo) is	expected to be a dictionary of
	   additional quvi object options, if defined at all.

	   The function	will return the	resolved_url among the values in the
	   returned dictionary.	If the URL did not redirect to another
	   location, the value of the resolved_url is left empty.

EXAMPLES
   Base64
       o   Base64 encode a string:

	       local H = require 'quvi/hex'
	       local s = H.to_hex('foo') -- Pass in hexadecimal	form

	       local r = quvi.base64.encode(s)
	       print(r.base64)

       o   Reverse the process:

	       local r = quvi.base64.decode(r.base64)
	       local s = H.to_str(r.plaintext)

   Crypto
       o   Encrypt plaintext:

	       local plaintext = 'f34481ec3cc627bacd5dc3fb08f273e6'
	       local key = '00000000000000000000000000000000'

	       local C = require 'quvi/const'
	       local o = {
		 [C.qoo_crypto_cipher_mode] = C.qoco_cipher_mode_cbc,
		 [C.qoo_crypto_algorithm] = 'aes',
		 [C.qoo_crypto_cipher_key = key
	       }

	       local r = quvi.crypto.encrypt(plaintext,	o)
	       print(r.ciphertext)

       o   Reverse the process:

	       local r = quvi.crypto.decrypt(r.ciphertext, o)
	       print(r.plaintext)

       o   Generate a hash (message digest):

	       local H = require 'quvi/hex'
	       local s = H.to_hex('foo') -- Pass in hexadecimal	form

	       local C = require 'quvi/const'
	       local o = { [C.qoo_crypto_algorithm] = 'sha1' }

	       local r = quvi.crypto.hash(s, o)
	       print(r.digest)

       o   Same	as above, but use the shorthand	function:

	       local A = require 'quvi/hash'
	       local r = A.sha1sum('foo')
	       print(r)

   HTTP
       o   Dump	the cookies in the memory to stdout:

	       local C = require 'quvi/const'
	       local o = { [C.qoo_http_cookie_mode] = C.qohco_mode_jar }
	       local r = quvi.http.cookie('-', o)

       o   Identical to	the above but use the wrapper module:

	       local K = require 'quvi/http/cookie'
	       local r = K.jar('-')

       o   Fetch an URL:

	       local r = quvi.http.fetch('http://example.com')

	   r.data would	now hold the contents. If an error occurred, e.g.
	   connection failed, the library would	exit the process with an
	   error.

       o   Same	as above, but handle the error in the script:

	       local C = require 'quvi/const'
	       local o = { [C.qoo_croak_if_error] = false }

	       local r = quvi.http.fetch('http://example.com', o)
	       if r.quvi_code ~= C.qerr_ok then
		 local s =
		   string.format('quvi.http.fetch: %s (libquvi=%d, http/%d)',
				 r.error_message, r.quvi_code, r.response_code)
		 error(s)
	       end

	   By setting qoo_croak_if_error to false, we tell the library to only
	   register that an error occurred and return the control to the
	   script. Handling of the error is then left for the script to	do.

	       Note
	       Typically, the scripts would not	need to	handle the error

       o   Force conversion from ISO-8859-1 to UTF-8:

	       local C = require 'quvi/const'
	       local o = { [C.qoo_fetch_from_charset] =	'ISO-8859-1' }
	       local r = quvi.http.fetch('http://example.com', o)

       o   Override user-agent header in the HTTP request:

	       local r = quvi.http.header('User-Agent: foo/1.0')
	       r = quvi.http.fetch(...)

       o   Disable an internal header in the HTTP request:

	       local r = quvi.http.header('Accept:')
	       r = quvi.http.fetch(...)

       o   Send	a cookie in the	HTTP request:

	       local r = quvi.http.header('Cookie: foo=1')
	       r = quvi.http.fetch(...)

       o   Query metainfo for an URL:

	       local r = quvi.http.metainfo('http://is.gd/SKyg8m')
	       print(r.content_length, r.content_type)

       o   Resolve URL redirection:

	       local r = quvi.http.resolve('http://is.gd/SKyg8m')
	       if #r.resolved_url >0 then
		 print('new location:',	r.resolved_url)
	       end

SEE ALSO
       libquvi-scripts(7), libquvi(3), quvi-modules(7),	quvi-
       modules-3rdparty(7)

FURTHER	RESOURCES
       Home

	   http://quvi.sourceforge.net/

       Development code

	   git://repo.or.cz/libquvi.git

       gitweb

	   http://repo.or.cz/w/libquvi.git

       C API reference
	   The latest C	API reference documentation may	be viewed online at
	   http://quvi.sourceforge.net/r/api/0.9/.

       GLib

	   http://developer.gnome.org/glib/stable/glib-Base64-Encoding.html

       libcurl

	   http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTUSERAGENT
	   http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTCOOKIE

       libgcrypt reference manual

	   http://www.gnupg.org/documentation/manuals/gcrypt/

AUTHORS
       Toni Gundogdu <legatvs@gmail.com>
	   Author.

REPORTING BUGS
       Report bugs to the quvi-devel mailing list
       <quvi-devel@lists.sourceforge.net> where	the development	and the
       maintenance is primarily	done. You do not have to be subscribed to the
       list to send a message there.

LICENSE
       libquvi is Free Software	licensed under the GNU Affero GPLv3+

LIBQUVI
       Part of the libquvi(3) suite

libquvi	0.9.4			  11/10/2013			QUVI-OBJECT(7)

NAME | DESCRIPTION | OPTIONS | RETURN VALUES | FUNCTIONS | EXAMPLES | SEE ALSO | FURTHER RESOURCES | AUTHORS | REPORTING BUGS | LICENSE | LIBQUVI

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=quvi-object09&sektion=7&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help