mirror of
https://github.com/weechat/weechat.git
synced 2026-07-09 19:23:13 +02:00
doc/api: add function hook_url
This commit is contained in:
Sébastien Helleu
@@ -10025,7 +10025,6 @@ struct t_hook *weechat_hook_process (const char *command,
|
||||
void *callback_data);
|
||||
----
|
||||
|
||||
|
||||
Arguments:
|
||||
|
||||
* _command_: command to launch in child process, URL _(WeeChat ≥ 0.3.7)_ or
|
||||
@@ -10452,6 +10451,153 @@ hook4 = weechat.hook_process_hashtable("sh",
|
||||
20000, "my_process_cb", "")
|
||||
----
|
||||
|
||||
==== hook_url
|
||||
|
||||
_WeeChat ≥ 4.1.0._
|
||||
|
||||
URL transfer.
|
||||
|
||||
Prototype:
|
||||
|
||||
[source,c]
|
||||
----
|
||||
struct t_hook *weechat_hook_url (const char *url,
|
||||
struct t_hashtable *options,
|
||||
int timeout,
|
||||
int (*callback)(const void *pointer,
|
||||
void *data,
|
||||
const char *url,
|
||||
struct t_hashtable *options,
|
||||
struct t_hashtable *output),
|
||||
const void *callback_pointer,
|
||||
void *callback_data);
|
||||
----
|
||||
|
||||
Arguments:
|
||||
|
||||
* _url_: URL
|
||||
* _options_: options for URL transfer (see below); the hashtable is duplicated in
|
||||
function, so it's safe to free it after this call
|
||||
* _timeout_: timeout for URL transfer (in milliseconds): after this timeout,
|
||||
the transfer is stopped (0 means no timeout)
|
||||
* _callback_: function called when the transfer has ended, arguments and return
|
||||
value:
|
||||
** _const void *pointer_: pointer
|
||||
** _void *data_: pointer
|
||||
** _const char *url_: URL
|
||||
** _struct t_hashtable *options_: options
|
||||
** _struct t_hashtable *output_: result (keys and values are strings), which may
|
||||
contain the following keys:
|
||||
*** _response_code_: HTTP response code
|
||||
*** _headers_: HTTP headers in response
|
||||
*** _output_: standard output (set only if _file_out_ was not set in options)
|
||||
*** _error_: error message (set only in case of error)
|
||||
** return value:
|
||||
*** _WEECHAT_RC_OK_
|
||||
*** _WEECHAT_RC_ERROR_
|
||||
* _callback_pointer_: pointer given to callback when it is called by WeeChat
|
||||
* _callback_data_: pointer given to callback when it is called by WeeChat;
|
||||
if not NULL, it must have been allocated with malloc (or similar function)
|
||||
and it is automatically freed when the hook is deleted
|
||||
|
||||
The following Curl options are available (see `+man curl_easy_setopt+` for
|
||||
a description of each option):
|
||||
|
||||
include::{autogendir}/autogen_api_url_options.en.adoc[tag=url_options]
|
||||
|
||||
[NOTE]
|
||||
^(1)^ For options with type "mask", format is: "value1+value2+value3";
|
||||
for options with type "list", the list items must be separated by a newline
|
||||
(`\n`). +
|
||||
^(2)^ When constants are available they must be used as value for option.
|
||||
|
||||
These two extra options (strings) are allowed for input/output file:
|
||||
|
||||
* _file_in_: file to read and send with URLs (post file)
|
||||
* _file_out_: write downloaded URL/file in this file (instead of standard
|
||||
output)
|
||||
|
||||
Return value:
|
||||
|
||||
* pointer to new hook, NULL if error occurred
|
||||
|
||||
C example:
|
||||
|
||||
[source,c]
|
||||
----
|
||||
int
|
||||
my_url_cb (const void *pointer, void *data, const char *url,
|
||||
struct t_hashtable *options, struct t_hashtable *output)
|
||||
{
|
||||
weechat_printf (NULL, "response_code: %s", weechat_hashtable_get (output, "response_code"));
|
||||
weechat_printf (NULL, "headers: %s", weechat_hashtable_get (output, "headers"));
|
||||
weechat_printf (NULL, "output: %s", weechat_hashtable_get (output, "output"));
|
||||
weechat_printf (NULL, "error: %s", weechat_hashtable_get (output, "error"));
|
||||
return WEECHAT_RC_OK;
|
||||
}
|
||||
|
||||
/* example 1: output to a file */
|
||||
struct t_hashtable *options_url1 = weechat_hashtable_new (8,
|
||||
WEECHAT_HASHTABLE_STRING,
|
||||
WEECHAT_HASHTABLE_STRING,
|
||||
NULL,
|
||||
NULL);
|
||||
if (options_url1)
|
||||
{
|
||||
weechat_hashtable_set (options_url1, "file_out", "/tmp/weechat.org.html");
|
||||
struct t_hook *my_url_hook = weechat_hook_url ("https://weechat.org/",
|
||||
options_url1,
|
||||
20000,
|
||||
&my_url_cb, NULL, NULL);
|
||||
weechat_hashtable_free (options_url1);
|
||||
}
|
||||
|
||||
/* example 2: custom HTTP headers, output sent to callback */
|
||||
struct t_hashtable *options_url2 = weechat_hashtable_new (8,
|
||||
WEECHAT_HASHTABLE_STRING,
|
||||
WEECHAT_HASHTABLE_STRING,
|
||||
NULL,
|
||||
NULL);
|
||||
if (options_url2)
|
||||
{
|
||||
weechat_hashtable_set (options_url2, "httpheader",
|
||||
"Header1: value1\n"
|
||||
"Header2: value2");
|
||||
struct t_hook *my_url_hook = weechat_hook_url ("http://localhost:8080/",
|
||||
options_url2,
|
||||
20000,
|
||||
&my_url_cb, NULL, NULL);
|
||||
weechat_hashtable_free (options_url2);
|
||||
}
|
||||
----
|
||||
|
||||
Script (Python):
|
||||
|
||||
[source,python]
|
||||
----
|
||||
# prototype
|
||||
def hook_url(url: str, options: Dict[str, str], timeout: int, callback: str, callback_data: str) -> str: ...
|
||||
|
||||
# example
|
||||
def my_url_cb(data: str, url: str, options: Dict[str, str], output: Dict[str, str]) -> int:
|
||||
weechat.prnt("", "output: %s" % output)
|
||||
return weechat.WEECHAT_RC_OK
|
||||
|
||||
# example 1: output to a file
|
||||
hook1 = weechat.hook_url("https://weechat.org/",
|
||||
{"file_out": "/tmp/weechat.org.html"},
|
||||
20000, "my_url_cb", "")
|
||||
|
||||
# example 2: custom HTTP headers, output sent to callback
|
||||
options = {
|
||||
"httpheader": "\n".join([
|
||||
"Header1: value1",
|
||||
"Header2: value2",
|
||||
]),
|
||||
}
|
||||
hook2 = weechat.hook_url("http://localhost:8080/", options, 20000, "my_url_cb", "")
|
||||
----
|
||||
|
||||
==== hook_connect
|
||||
|
||||
_Updated in 1.5, 2.0._
|
||||
|
||||
Reference in New Issue
Block a user