|
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[]
|