'\" t

.\"     Title: quvi-object

.\"    Author: [see the "Authors" section]

.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>

.\"      Date: 11/10/2013

.\"    Manual: libquvi Manual

.\"    Source: libquvi 0.9.4

.\"  Language: English

.\"

.TH "QUVI\-OBJECT" "7" "11/10/2013" "libquvi 0\&.9\&.4" "libquvi Manual"

.\" -----------------------------------------------------------------

.\" * Define some portability stuff

.\" -----------------------------------------------------------------

.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.\" http://bugs.debian.org/507673

.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html

.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.ie \n(.g .ds Aq \(aq

.el       .ds Aq '

.\" -----------------------------------------------------------------

.\" * set default formatting

.\" -----------------------------------------------------------------

.\" disable hyphenation

.nh

.\" disable justification (adjust text to left margin only)

.ad l

.\" -----------------------------------------------------------------

.\" * MAIN CONTENT STARTS HERE *

.\" -----------------------------------------------------------------

.SH "NAME"

quvi-object \- Overview of the libquvi quvi\-object

.SH "DESCRIPTION"

.sp

\fIquvi\-object\fR is a collection of libquvi functions provided for the \fBlibquvi-scripts\fR(7)\&. These functions vary from HTTP functions to cryptographic functions\&. All of the \fIquvi\-object\fR functions are implemented in C\&.

.if n \{\

.sp

.\}

.RS 4

.it 1 an-trap

.nr an-no-space-flag 1

.nr an-break-flag 1

.br

.ps +1

\fBNote\fR

.ps -1

.br

.sp

The \fIquvi\-object\fR should not be confused with the \fBquvi-modules\fR(7) which are a selection of importable modules implemented in Lua\&. These modules are intended to be loaded (\fIrequire\fR) from the \fBlibquvi-scripts\fR(7)\&.

.sp .5v

.RE

.SH "OPTIONS"

.sp

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:

.PP

qoo_croak_if_error=<boolean>

.RS 4

By default the library terminates the process if an error occurs\&. By setting this option to

\fIfalse\fR, it will register the error and continues execution, leaving the error handling for the script to determine\&. See also "RETURN VALUES"\&.

.RE

.sp

The \fIqoo\fR prefix is short for \fIquvi object option\fR\&. The functions will ignore any unknown options, e\&.g\&. the crypto functions would ignore the HTTP options\&.

.if n \{\

.sp

.\}

.RS 4

.it 1 an-trap

.nr an-no-space-flag 1

.nr an-break-flag 1

.br

.ps +1

\fBNote\fR

.ps -1

.br

.sp

The options have been defined in the \fIquvi/const\fR of the \fBquvi-modules\fR(7)

.sp .5v

.RE

.SS "Crypto"

.sp

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

.PP

qoo_crypto_algorithm=<value>

.RS 4

Specifies the algorithm that should be used\&. The

\fIvalue\fR

is expected to be a string, e\&.g\&.

\fIsha1\fR

or

\fIaes256\fR\&.

.RE

.PP

qoo_crypto_cipher_flags=<value>

.RS 4

Specifies the cipher flags (bit OR\(cqd, see

\fBquvi-modules-3rdparty\fR(7)

for

\fIbit operations\fR) to be used with the cipher\&. These values are identical to those defined by libgcrypt\&. See the

\fIquvi/const\fR

of the

\fBquvi-modules\fR(7)

for a complete list of the available cipher flags\&.

.RE

.PP

qoo_crypto_cipher_mode=<value>

.RS 4

Specifies the cipher mode to be used\&. These are identical to the values defined by libgcrypt\&. See the

\fIquvi/const\fR

of the

\fBquvi-modules\fR(7)

for a complete list of the available cipher modes\&.

.RE

.PP

qoo_crypto_cipher_key=<value>

.RS 4

Used to specify the cipher key\&. It should be noted that the

\fIkey\fR

is expected to be passed in hexadecimal form\&. See

\fIquvi/hex\fR

of the

\fBquvi-modules\fR(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

.RE

.SS "HTTP"

.sp

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

.PP

qoo_fetch_from_charset=<charset>

.RS 4

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

\fIfrom charset\fR

option is set, the library will then try to convert to UTF\-8 using the

\fIfrom charset\fR

value\&.

.RE

.PP

qoo_http_cookie_mode=<value>

.RS 4

Modify the cookie settings for the libcurl session handle\&. This feature wraps the cookie features provided by

\fBlibcurl_easy_setopt\fR(3)\&. See the

\fIquvi/const\fR

of the

\fBquvi-modules\fR(7)

for a complete list of the available cookie modes\&.

See also

\fBlibcurl-tutorial\fR(3)

which covers the use of cookies with the library in greater detail\&.

.RE

.SH "RETURN VALUES"

.sp

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

.PP

error_message

.RS 4

The error message, or an empty value\&.

.RE

.PP

quvi_code

.RS 4

The code returned by the library\&. See also

\fIquvi/const\fR

of

\fBquvi-modules\fR(7)\&.

.RE

.sp

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

.SH "FUNCTIONS"

.SS "Base64"

.PP

quvi\&.base64\&.encode(<plaintext>[,qoo])

.RS 4

Encode the

\fIplaintext\fR

to base64 format\&. The

\fIplaintext\fR

is expected to be passed in hexadecimal form\&. See

\fIquvi/hex\fR

of the

\fBquvi-modules\fR(7)

for the conversion functions\&.

The second argument (\fIqoo\fR) is expected to be a dictionary of additional

\fIquvi object options\fR, if defined at all\&.

The function will return the

\fIbase64\fR

value in the dictionary\&.

.RE

.PP

quvi\&.base64\&.decode(<base64>)

.RS 4

Decode the

\fIbase64\fR

value to plaintext\&.

The function will return the

\fIplaintext\fR

value in the dictionary\&. The value is returned in hexadecimal form\&.

.RE

.SS "Crypto"

.sp

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

.if n \{\

.sp

.\}

.RS 4

.it 1 an-trap

.nr an-no-space-flag 1

.nr an-break-flag 1

.br

.ps +1

\fBNote\fR

.ps -1

.br

.sp

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

.sp .5v

.RE

.PP

quvi\&.crypto\&.encrypt(<plaintext>, <qoo>)

.RS 4

Encrypt the

\fIplaintext\fR\&. The

\fIplaintext\fR

is expected to be passed in hexadecimal form\&. See

\fIquvi/hex\fR

of the

\fBquvi-modules\fR(7)

for the conversion functions\&.

The second argument (\fIqoo\fR) is expected to be a dictionary containing the cipher options\&.

The function will return the

\fIciphertext\fR

value in the dictionary\&. The value is returned in hexadecimal form\&.

.RE

.PP

quvi\&.crypto\&.decrypt(<ciphertext>, <qoo>)

.RS 4

Decrypt the

\fIciphertext\fR\&. The

\fIciphertext\fR

is expected to be passed in hexadecimal form\&. See

\fIquvi/hex\fR

of the

\fBquvi-modules\fR(7)

for the conversion functions\&.

The second argument (\fIqoo\fR) is expected to be a dictionary containing the cipher options\&.

The function will return the

\fIplaintext\fR

value in the dictionary\&. This value is returned in hexadecimal form\&.

.RE

.PP

quvi\&.crypto\&.hash(<value>, <qoo>)

.RS 4

Generate a hash from the

\fIvalue\fR\&. The

\fIvalue\fR

is expected to be passed in hexadecimal format\&. See

\fIquvi/hex\fR

of the

\fBquvi-modules\fR(7)

for the conversion functions\&.

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

The function will return the

\fIdigest\fR

value in the dictionary\&. The value is returned in hexadecimal form\&.

.RE

.SS "HTTP"

.sp

The HTTP functions will return \fIresponse_code\fR along the other "RETURN VALUES", and the values specific to the HTTP function\&.

.PP

quvi\&.http\&.cookie(<VALUE>,<qoo>)

.RS 4

Modify the libcurl session handle cookie settings that libquvi currently uses\&.

The second argument (\fIqoo\fR) 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

\fIquvi/const\fR

module of the

\fBquvi-modules\fR(7)\&. The mode names are named after their equivalent CURLOPT_COOKIE{SESSION,FILE,LIST,JAR} variable names\&. For a description of each option, see

\fBlibcurl_easy_setopt\fR(3)\&.

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

.RE

.if n \{\

.sp

.\}

.RS 4

.it 1 an-trap

.nr an-no-space-flag 1

.nr an-break-flag 1

.br

.ps +1

\fBNote\fR

.ps -1

.br

.sp

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

.sp .5v

.RE

.if n \{\

.sp

.\}

.RS 4

.it 1 an-trap

.nr an-no-space-flag 1

.nr an-break-flag 1

.br

.ps +1

\fBNote\fR

.ps -1

.br

.sp

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

.sp .5v

.RE

.PP

quvi\&.http\&.fetch(<URL>[,qoo])

.RS 4

Fetch an URL over an HTTP connection\&.

The second argument (\fIqoo\fR) is expected to be a dictionary of additional

\fIquvi object options\fR, if defined at all\&.

The function will return the

\fIdata\fR

value among the values in the returned dictionary\&.

.RE

.PP

quvi\&.http\&.header(<VALUE>[,qoo])

.RS 4

Add, remove or replace internally used libcurl HTTP headers\&.

The second argument (\fIqoo\fR) is expected to be a dictionary of additional

\fIquvi object options\fR, if defined at all\&.

This function essentially wraps CURLOPT_HTTPHEADER, and will not return any additional values in the dictionary\&. See

\fBcurl_easy_setopt\fR(3)

for the full description of CURLOPT_HTTPHEADER\&.

.RE

.if n \{\

.sp

.\}

.RS 4

.it 1 an-trap

.nr an-no-space-flag 1

.nr an-break-flag 1

.br

.ps +1

\fBNote\fR

.ps -1

.br

.sp

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

.sp .5v

.RE

.PP

quvi\&.http\&.metainfo(<URL>[,qoo])

.RS 4

Query the HTTP metainfo for the URL\&.

The second argument (\fIqoo\fR) is expected to be a dictionary of additional

\fIquvi object options\fR, if defined at all\&.

The function will return the

\fIcontent_length\fR

and the

\fIcontent_type\fR

values among the values in the returned dictionary\&.

.RE

.PP

quvi\&.http\&.resolve(<URL>[,qoo])

.RS 4

Resolve an URL redirection\&.

The second argument (\fIqoo\fR) is expected to be a dictionary of additional

\fIquvi object options\fR, if defined at all\&.

The function will return the

\fIresolved_url\fR

among the values in the returned dictionary\&. If the URL did not redirect to another location, the value of the

\fIresolved_url\fR

is left empty\&.

.RE

.SH "EXAMPLES"

.SS "Base64"

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

Base64 encode a string:

.sp

.if n \{\

.RS 4

.\}

.nf

local H = require \*(Aqquvi/hex\*(Aq

local s = H\&.to_hex(\*(Aqfoo\*(Aq) \-\- Pass in hexadecimal form

local r = quvi\&.base64\&.encode(s)

print(r\&.base64)

.fi

.if n \{\

.RE

.\}

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

Reverse the process:

.sp

.if n \{\

.RS 4

.\}

.nf

local r = quvi\&.base64\&.decode(r\&.base64)

local s = H\&.to_str(r\&.plaintext)

.fi

.if n \{\

.RE

.\}

.RE

.SS "Crypto"

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

Encrypt plaintext:

.sp

.if n \{\

.RS 4

.\}

.nf

local plaintext = \*(Aqf34481ec3cc627bacd5dc3fb08f273e6\*(Aq

local key = \*(Aq00000000000000000000000000000000\*(Aq

local C = require \*(Aqquvi/const\*(Aq

local o = {

  [C\&.qoo_crypto_cipher_mode] = C\&.qoco_cipher_mode_cbc,

  [C\&.qoo_crypto_algorithm] = \*(Aqaes\*(Aq,

  [C\&.qoo_crypto_cipher_key = key

}

local r = quvi\&.crypto\&.encrypt(plaintext, o)

print(r\&.ciphertext)

.fi

.if n \{\

.RE

.\}

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

Reverse the process:

.sp

.if n \{\

.RS 4

.\}

.nf

local r = quvi\&.crypto\&.decrypt(r\&.ciphertext, o)

print(r\&.plaintext)

.fi

.if n \{\

.RE

.\}

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

Generate a hash (message digest):

.sp

.if n \{\

.RS 4

.\}

.nf

local H = require \*(Aqquvi/hex\*(Aq

local s = H\&.to_hex(\*(Aqfoo\*(Aq) \-\- Pass in hexadecimal form

local C = require \*(Aqquvi/const\*(Aq

local o = { [C\&.qoo_crypto_algorithm] = \*(Aqsha1\*(Aq }

local r = quvi\&.crypto\&.hash(s, o)

print(r\&.digest)

.fi

.if n \{\

.RE

.\}

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

Same as above, but use the shorthand function:

.sp

.if n \{\

.RS 4

.\}

.nf

local A = require \*(Aqquvi/hash\*(Aq

local r = A\&.sha1sum(\*(Aqfoo\*(Aq)

print(r)

.fi

.if n \{\

.RE

.\}

.RE

.SS "HTTP"

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

Dump the cookies in the memory to stdout:

.sp

.if n \{\

.RS 4

.\}

.nf

local C = require \*(Aqquvi/const\*(Aq

local o = { [C\&.qoo_http_cookie_mode] = C\&.qohco_mode_jar }

local r = quvi\&.http\&.cookie(\*(Aq\-\*(Aq, o)

.fi

.if n \{\

.RE

.\}

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

Identical to the above but use the wrapper module:

.sp

.if n \{\

.RS 4

.\}

.nf

local K = require \*(Aqquvi/http/cookie\*(Aq

local r = K\&.jar(\*(Aq\-\*(Aq)

.fi

.if n \{\

.RE

.\}

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

Fetch an URL:

.sp

.if n \{\

.RS 4

.\}

.nf

local r = quvi\&.http\&.fetch(\*(Aqhttp://example\&.com\*(Aq)

.fi

.if n \{\

.RE

.\}

.sp

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

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

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

.sp

.if n \{\

.RS 4

.\}

.nf

local C = require \*(Aqquvi/const\*(Aq

local o = { [C\&.qoo_croak_if_error] = false }

local r = quvi\&.http\&.fetch(\*(Aqhttp://example\&.com\*(Aq, o)

if r\&.quvi_code ~= C\&.qerr_ok then

  local s =

    string\&.format(\*(Aqquvi\&.http\&.fetch: %s (libquvi=%d, http/%d)\*(Aq,

                  r\&.error_message, r\&.quvi_code, r\&.response_code)

  error(s)

end

.fi

.if n \{\

.RE

.\}

.sp

By setting qoo_croak_if_error to

\fIfalse\fR, 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\&.

.if n \{\

.sp

.\}

.RS 4

.it 1 an-trap

.nr an-no-space-flag 1

.nr an-break-flag 1

.br

.ps +1

\fBNote\fR

.ps -1

.br

Typically, the scripts would not need to handle the error

.sp .5v

.RE

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

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

.sp

.if n \{\

.RS 4

.\}

.nf

local C = require \*(Aqquvi/const\*(Aq

local o = { [C\&.qoo_fetch_from_charset] = \*(AqISO\-8859\-1\*(Aq }

local r = quvi\&.http\&.fetch(\*(Aqhttp://example\&.com\*(Aq, o)

.fi

.if n \{\

.RE

.\}

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

Override user\-agent header in the HTTP request:

.sp

.if n \{\

.RS 4

.\}

.nf

local r = quvi\&.http\&.header(\*(AqUser\-Agent: foo/1\&.0\*(Aq)

r = quvi\&.http\&.fetch(\&.\&.\&.)

.fi

.if n \{\

.RE

.\}

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

Disable an internal header in the HTTP request:

.sp

.if n \{\

.RS 4

.\}

.nf

local r = quvi\&.http\&.header(\*(AqAccept:\*(Aq)

r = quvi\&.http\&.fetch(\&.\&.\&.)

.fi

.if n \{\

.RE

.\}

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

Send a cookie in the HTTP request:

.sp

.if n \{\

.RS 4

.\}

.nf

local r = quvi\&.http\&.header(\*(AqCookie: foo=1\*(Aq)

r = quvi\&.http\&.fetch(\&.\&.\&.)

.fi

.if n \{\

.RE

.\}

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

Query metainfo for an URL:

.sp

.if n \{\

.RS 4

.\}

.nf

local r = quvi\&.http\&.metainfo(\*(Aqhttp://is\&.gd/SKyg8m\*(Aq)

print(r\&.content_length, r\&.content_type)

.fi

.if n \{\

.RE

.\}

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

Resolve URL redirection:

.sp

.if n \{\

.RS 4

.\}

.nf

local r = quvi\&.http\&.resolve(\*(Aqhttp://is\&.gd/SKyg8m\*(Aq)

if #r\&.resolved_url >0 then

  print(\*(Aqnew location:\*(Aq, r\&.resolved_url)

end

.fi

.if n \{\

.RE

.\}

.RE

.SH "SEE ALSO"

.sp

\fBlibquvi-scripts\fR(7), \fBlibquvi\fR(3), \fBquvi-modules\fR(7), \fBquvi-modules-3rdparty\fR(7)

.SH "FURTHER RESOURCES"

.PP

Home

.RS 4

http://quvi\&.sourceforge\&.net/

.RE

.PP

Development code

.RS 4

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

.RE

.PP

gitweb

.RS 4

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

.RE

.PP

C API reference

.RS 4

The latest C API reference documentation may be viewed online at

http://quvi\&.sourceforge\&.net/r/api/0\&.9/\&.

.RE

.PP

GLib

.RS 4

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

.RE

.PP

libcurl

.RS 4

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

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

.RE

.PP

libgcrypt reference manual

.RS 4

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

.RE

.SH "AUTHORS"

.PP

Toni Gundogdu <legatvs@gmail\&.com>

.RS 4

Author\&.

.RE

.SH "REPORTING BUGS"

.sp

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\&.

.SH "LICENSE"

.sp

libquvi is Free Software licensed under the GNU Affero GPLv3+

.SH "LIBQUVI"

.sp

Part of the \fBlibquvi\fR(3) suite