From 83dcb84ea62f3bb7479a7fad88bbccedcc2cc8a6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Helleu?= Date: Fri, 8 Sep 2023 17:07:24 +0200 Subject: [PATCH] doc/api: add function hook_url --- doc/en/weechat_plugin_api.en.adoc | 148 +++++++++++++++++++++++++++- doc/fr/weechat_plugin_api.fr.adoc | 157 +++++++++++++++++++++++++++++- doc/it/weechat_plugin_api.it.adoc | 153 ++++++++++++++++++++++++++++- doc/ja/weechat_plugin_api.ja.adoc | 152 ++++++++++++++++++++++++++++- doc/sr/weechat_plugin_api.sr.adoc | 143 ++++++++++++++++++++++++++- 5 files changed, 742 insertions(+), 11 deletions(-) diff --git a/doc/en/weechat_plugin_api.en.adoc b/doc/en/weechat_plugin_api.en.adoc index da0f8bda2..7ec332489 100644 --- a/doc/en/weechat_plugin_api.en.adoc +++ b/doc/en/weechat_plugin_api.en.adoc @@ -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._ diff --git a/doc/fr/weechat_plugin_api.fr.adoc b/doc/fr/weechat_plugin_api.fr.adoc index cd4bdc33f..b50d0d1ce 100644 --- a/doc/fr/weechat_plugin_api.fr.adoc +++ b/doc/fr/weechat_plugin_api.fr.adoc @@ -10207,7 +10207,6 @@ struct t_hook *weechat_hook_process (const char *command, void *callback_data); ---- - Paramètres : * _command_ : commande à lancer dans le processus fils, URL _(WeeChat ≥ 0.3.7)_ @@ -10441,7 +10440,7 @@ struct t_hook *weechat_hook_process_hashtable (const char *command, Les paramètres sont les mêmes que ceux de la fonction <<_hook_process,hook_process>>, avec un paramètre supplémentaire : -* _options_ : options pour la commande exécutée; la table de hachage est +* _options_ : options pour la commande exécutée ; la table de hachage est dupliquée dans la fonction, donc il est possible de la supprimer après cet appel @@ -10649,6 +10648,160 @@ hook4 = weechat.hook_process_hashtable("sh", 20000, "my_process_cb", "") ---- +==== hook_url + +_WeeChat ≥ 4.1.0._ + +Transfert d'URL. + +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); +---- + +Paramètres : + +* _url_ : URL +* _options_ : options pour le transfert d'URL (voir ci-dessous) ; la table de + hachage est dupliquée dans la fonction, donc il est possible de la supprimer + après cet appel +* _timeout_ : timeout pour le transfert d'URL (en millisecondes) : après de délai, + le transfert est stoppé (0 signifie pas de limite) +* _callback_ : fonction appelée lorsque le transfert est terminé, paramètres et + valeur de retour : +** _const void *pointer_ : pointeur +** _void *data_ : pointeur +** _const char *url_ : URL +** _struct t_hashtable *options_ : options +** _struct t_hashtable *output_ : résultat (les clés et valeurs sont des chaînes), + qui peut contenir les clés suivantes : +*** _response_code_ : code réponse HTTP +*** _headers_ : en-têtes HTTP dans la réponse +*** _output_ : sortie standard (défini seulement si _file_out_ n'était pas défini + dans les options) +*** _error_ : message d'erreur (défini seulement en cas d'erreur) +** valeur de retour : +*** _WEECHAT_RC_OK_ +*** _WEECHAT_RC_ERROR_ +* _callback_pointer_ : pointeur donné à la fonction de rappel lorsqu'elle est + appelée par WeeChat +* _callback_data_ : pointeur donné à la fonction de rappel lorsqu'elle est + appelée par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une + fonction similaire) et est automatiquement libéré (par free) lorsque le + "hook" est supprimé + +Les options Curl suivantes sont disponibles (voir `+man curl_easy_setopt+` pour +une description de chaque option) : + +include::{autogendir}/autogen_api_url_options.fr.adoc[tag=url_options] + +[NOTE] +^(1)^ Pour les options avec le type "mask", le format est : +"value1+value2+value3" ; +pour les options avec le type "list", les éléments de la liste doivent être +séparés par un retour à la ligne (`\n`). + +^(2)^ Lorsque des constantes sont disponibles, elles doivent être utilisées +comme valeur pour l'option. + +Ces deux options supplémentaires (chaînes) sont autorisées, pour le fichier en +entrée/sortie : + +* _file_in_ : fichier à lire pour envoyer avec l'URL (envoi de fichier "post") +* _file_out_ : écrire l'URL/fichier dans ce fichier (au lieu de la sortie + standard) + +Valeur de retour : + +* pointeur vers le nouveau "hook", NULL en cas d'erreur + +Exemple en C : + +[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: sortie dans un fichier */ +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: en-têtes HTTP personnalisés, sortie envoyée à la fonction de rappel */ +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: valeur1\n" + "Header2: valeur2"); + 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: ... + +# exemple +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 + +# exemple 1 : sortie dans un fichier +hook1 = weechat.hook_url("https://weechat.org/", + {"file_out": "/tmp/weechat.org.html"}, + 20000, "my_url_cb", "") + +# exemple 2 : en-têtes HTTP personnalisés, sortie envoyée à la fonction de rappel +options = { + "httpheader": "\n".join([ + "Header1: valeur1", + "Header2: valeur2", + ]), +} +hook2 = weechat.hook_url("http://localhost:8080/", options, 20000, "my_url_cb", "") +---- + ==== hook_connect _Mis à jour dans la 1.5, 2.0._ diff --git a/doc/it/weechat_plugin_api.it.adoc b/doc/it/weechat_plugin_api.it.adoc index 4b998b0f2..f20cd1f1a 100644 --- a/doc/it/weechat_plugin_api.it.adoc +++ b/doc/it/weechat_plugin_api.it.adoc @@ -10385,7 +10385,6 @@ struct t_hook *weechat_hook_process (const char *command, void *callback_data); ---- - Argomenti: // TRANSLATION MISSING @@ -10672,8 +10671,7 @@ Per un URL, sono consentite due opzioni aggiuntive (stringhe) per il file in input/output: * _file_in_: file da leggere e inviare con gli URL (invio del file "post") -* _file_out_: scrive URL scaricato/file in questo file (invece dello standard -* output) +* _file_out_: scrive URL scaricato/file in questo file (invece dello standard output) Valore restituito: @@ -10833,6 +10831,155 @@ hook4 = weechat.hook_process_hashtable("sh", 20000, "my_process_cb", "") ---- +// TRANSLATION MISSING +==== hook_url + +_WeeChat ≥ 4.1.0._ + +URL transfer. + +Prototipo: + +[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); +---- + +Argomenti: + +* _url_: URL +* _options_: options for URL transfer (see below); la tabella hash è duplicata + nella funzione, per cui è possibile liberarla dopo questa chiamata +* _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_: puntatore fornito alla callback quando chiamata da WeeChat +* _callback_data_: puntatore fornito alla callback quando chiamata da 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.it.adoc[tag=url_options] + +// TRANSLATION MISSING +[NOTE] +^(1)^ Per le opzioni con il tipo "mask" il formato è: "value1+value2+value3"; +for options with type "list", the list items must be separated by a newline +(`\n`). + +^(2)^ Quando sono disponibili le costanti, esse vanno usate come valore per +l'opzione. + +These two extra options (strings) are allowed for input/output file: + +* _file_in_: file da leggere e inviare con gli URL (invio del file "post") +* _file_out_: scrive URL scaricato/file in questo file (invece dello standard output) + +Valore restituito: + +* puntatore al nuovo hook, NULL in caso di errore + +Esempio in C: + +[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] +---- +# prototipo +def hook_url(url: str, options: Dict[str, str], timeout: int, callback: str, callback_data: str) -> str: ... + +# esempio +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 // TRANSLATION MISSING diff --git a/doc/ja/weechat_plugin_api.ja.adoc b/doc/ja/weechat_plugin_api.ja.adoc index cea431ebb..131468d0e 100644 --- a/doc/ja/weechat_plugin_api.ja.adoc +++ b/doc/ja/weechat_plugin_api.ja.adoc @@ -2430,7 +2430,6 @@ _WeeChat バージョン 2.4 以上で利用可。_ base 16、32、64 で文字列をエンコード。 - プロトタイプ: [source,c] @@ -7211,7 +7210,6 @@ Ruby では、3 組のコールバックとデータ (6 つの文字列変数) link:++weechat_scripting.ja.html#_ruby++[WeeChat スクリプト作成ガイド ^↗^^]を参照してください _(WeeChat バージョン 0.4.1 で修正済み)_。 - ==== config_search_option 設定ファイルのセクションからオプションを検索。 @@ -10134,7 +10132,6 @@ struct t_hook *weechat_hook_process (const char *command, void *callback_data); ---- - 引数: * _command_: 子プロセスで実行するコマンド、URL _(WeeChat バージョン 0.3.7 以上で利用可)_ @@ -10565,6 +10562,154 @@ hook4 = weechat.hook_process_hashtable("sh", 20000, "my_process_cb", "") ---- +// TRANSLATION MISSING +==== hook_url + +_WeeChat ≥ 4.1.0._ + +URL transfer. + +プロトタイプ: + +[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); +---- + +引数: + +* _url_: URL +* _options_: options for URL transfer (see below); + ハッシュテーブルは関数の中で複製されるため、この関数を呼び出した後にハッシュテーブルを安全に開放できます。 +* _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_: WeeChat が _callback_ コールバックを呼び出す際にコールバックに渡すポインタ +* _callback_data_: WeeChat が _callback_ コールバックを呼び出す際にコールバックに渡すポインタ; + このポインタが NULL でない場合、このポインタは malloc (または類似の関数) + によって割り当てられたものでなければいけません。さらに、このポインタはここで作成したフックが削除された時点で自動的に開放されます + +The following Curl options are available (see `+man curl_easy_setopt+` for +a description of each option): + +include::{autogendir}/autogen_api_url_options.ja.adoc[tag=url_options] + +[NOTE] +^(1)^ "mask" タイプのオプションでは、フォーマットは "value1+value2+value3" です。 +"list" タイプのオプションでは、リスト要素を改行で区切ってください。 +(`\n`). + +^(2)^ 定数が利用可能な場合、定数は必ずオプションの値に含めてください。 + +These two extra options (strings) are allowed for input/output file: + +* _file_in_: 読み込んで URL に送信するファイル (ファイルを送信) +* _file_out_: ダウンロードした URL/ファイルをこのファイルに書き込む + (標準出力を使わない) + +戻り値: + +* 新しいフックへのポインタ、エラーが起きた場合は NULL + +C 言語での使用例: + +[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); +} +---- + +スクリプト (Python) での使用例: + +[source,python] +---- +# プロトタイプ +def hook_url(url: str, options: Dict[str, str], timeout: int, callback: str, callback_data: str) -> str: ... + +# 例 +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 _WeeChat バージョン 1.5 と 2.0 で更新。_ @@ -16741,7 +16886,6 @@ if (hashtable_in) "irc_message_parse" の出力に関するより詳しい情報は link:weechat_scripting.ja.html#irc_message_parse[WeeChat スクリプト作成ガイド / メッセージの構文解析 ^↗^^]を参照してください。 - スクリプト (Python) での使用例: [source,python] diff --git a/doc/sr/weechat_plugin_api.sr.adoc b/doc/sr/weechat_plugin_api.sr.adoc index c2bc5a982..209855639 100644 --- a/doc/sr/weechat_plugin_api.sr.adoc +++ b/doc/sr/weechat_plugin_api.sr.adoc @@ -9725,7 +9725,6 @@ struct t_hook *weechat_hook_process (const char *command, void *callback_data); ---- - Аргументи: * _command_: команда која се покреће у дете процесу, URL _(WeeChat ≥ 0.3.7)_ или функција _(WeeChat ≥ 1.5)_ (погледајте испод) @@ -10127,6 +10126,148 @@ hook4 = weechat.hook_process_hashtable("sh", 20000, "my_process_cb", "") ---- +// TRANSLATION MISSING +==== hook_url + +_WeeChat ≥ 4.1.0._ + +URL transfer. + +Прототип: + +[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); +---- + +Аргументи: + +* _url_: URL +* _options_: options for URL transfer (see below); хеш табела се дуплира у функцији, тако да након овог позива безбедно можете да ослободите меморију коју заузима +* _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_: показивач који се прослеђује функцији повратног позива када је позове програм WeeChat +* _callback_data_: показивач који се прослеђује функцији повратног позива када је позове програм WeeChat; ако није NULL, алоцирала га је malloc (или нека слична функција) и аутоматски се ослобађа када се кука обрише + +The following Curl options are available (see `+man curl_easy_setopt+` for +a description of each option): + +include::{autogendir}/autogen_api_url_options.sr.adoc[tag=url_options] + +[NOTE] +^(1)^ За опције типа „mask”, формат је: „вредност1+вредност2+вредност3”; за опције типа „list”, ставке листе морају да се раздвоје преломом линије (`\n`). + +^(2)^ Ако су доступне константе, оне морају да се користе као вредност опције. + +These two extra options (strings) are allowed for input/output file: + +* _file_in_: фајл који се чита и шаље URL адресама (post фајл) +* _file_out_: преузети URL/фајл се уписује у овај фајл (уместо на стандардни излаз) + +Повратна вредност: + +* показивач на нову куку, NULL у случају грешке + +C пример: + +[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); +} +---- + +Скрипта (Python): + +[source,python] +---- +# прототип +def hook_url(url: str, options: Dict[str, str], timeout: int, callback: str, callback_data: str) -> str: ... + +# пример +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 _Ажурирано у верзијама 1.5, 2.0._