--- name: "quvi-object" section: "7" platform: "linux" package: "libquvi-0.9-dev" version: "0.9.4-3+b2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/quvi-object" --- # quvi-object(7) Overview of the libquvi quvi-object ## NAME quvi-object - Overview of the libquvi quvi-object ## DESCRIPTION *quvi-object* is a collection of libquvi functions provided for the [**libquvi-scripts**(7)](/libquvi-scripts/7.md). 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)](/libquvi-scripts/7.md). ## 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=\ 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=\ Specifies the algorithm that should be used. The *value* is expected to be a string, e.g. *sha1* or *aes256*. qoo\_crypto\_cipher\_flags=\ 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=\ 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=\ 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=\ 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=\ 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)](/libcurl-tutorial/3.md) 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(\\[,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(\) 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(\, \) 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(\, \) 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(\, \) 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(\,\) 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(\\[,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(\\[,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)](/curl_easy_setopt/3.md) 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(\\[,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(\\[,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 • 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) ``` • Reverse the process: ``` local r = quvi.base64.decode(r.base64) local s = H.to_str(r.plaintext) ``` ### Crypto • 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) ``` • Reverse the process: ``` local r = quvi.crypto.decrypt(r.ciphertext, o) print(r.plaintext) ``` • 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) ``` • Same as above, but use the shorthand function: ``` local A = require 'quvi/hash' local r = A.sha1sum('foo') print(r) ``` ### HTTP • 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) ``` • Identical to the above but use the wrapper module: ``` local K = require 'quvi/http/cookie' local r = K.jar('-') ``` • 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. • 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 • 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) ``` • Override user-agent header in the HTTP request: ``` local r = quvi.http.header('User-Agent: foo/1.0') r = quvi.http.fetch(...) ``` • Disable an internal header in the HTTP request: ``` local r = quvi.http.header('Accept:') r = quvi.http.fetch(...) ``` • Send a cookie in the HTTP request: ``` local r = quvi.http.header('Cookie: foo=1') r = quvi.http.fetch(...) ``` • Query metainfo for an URL: ``` local r = quvi.http.metainfo('http://is.gd/SKyg8m') print(r.content_length, r.content_type) ``` • 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-scripts/7.md), [**libquvi**(3)](/libquvi/3.md), **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 \ Author. ## REPORTING BUGS Report bugs to the quvi-devel mailing list \ 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)](/libquvi/3.md) suite