api: add support of functions in hook_process

4 files changed, 355 insertions, 25 deletions

diff --git a/doc/en/weechat_plugin_api.en.asciidoc b/doc/en/weechat_plugin_api.en.asciidoc
index 7212082ec..a9789cb1f 100644
--- a/doc/en/weechat_plugin_api.en.asciidoc
+++ b/doc/en/weechat_plugin_api.en.asciidoc
@@ -7517,8 +7517,8 @@ struct t_hook *weechat_hook_process (const char *command,
 
 Arguments:
 
-* 'command': command to launch in child process or URL _(WeeChat ≥ 0.3.7)_
-  (see below)
+* 'command': command to launch in child process, URL _(WeeChat ≥ 0.3.7)_ or
+  function _(WeeChat ≥ 1.5)_ (see below)
 * 'timeout': timeout for command (in milliseconds): after this timeout, child
   process is killed (0 means no timeout)
 * 'callback': function called when data from child is available, or when child
@@ -7533,13 +7533,16 @@ Arguments:
 **** '2': transfer error
 **** '3': not enough memory
 **** '4': error with a file
-*** '< 0': 'WEECHAT_HOOK_PROCESS_RUNNING' (data available, but child still
-    running) or 'WEECHAT_HOOK_PROCESS_ERROR' (error when launching command)
+*** '< 0':
+**** 'WEECHAT_HOOK_PROCESS_RUNNING': data available, but child still running)
+**** 'WEECHAT_HOOK_PROCESS_ERROR': error when launching command
+**** 'WEECHAT_HOOK_PROCESS_CHILD': callback is called in the child process
 ** 'out': standard output of command (stdout)
 ** 'err': error output of command (stderr)
 ** return value:
 *** 'WEECHAT_RC_OK'
 *** 'WEECHAT_RC_ERROR'
+*** child process return code (in case of function with "func:" in command)
 * '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)
@@ -7552,9 +7555,18 @@ Return value:
 When command has ended, or if timeout is reached, WeeChat will automatically
 unhook (and kill process if it is still running).
 
-The command can be an URL with format: "url:http://www.example.com", to download
-content of URL _(WeeChat ≥ 0.3.7)_. Options are possible for URL with
-function <<_hook_process_hashtable,weechat_hook_process_hashtable>>.
+The command can be an URL with format: "url:http://www.example.com",
+to download content of URL _(WeeChat ≥ 0.3.7)_. Options are possible for URL
+with function <<_hook_process_hashtable,weechat_hook_process_hashtable>>.
+
+The command can also be a function name with format: "func:name", to execute
+the function "name" _(WeeChat ≥ 1.5)_. This function receives a single argument
+('data') and must return a string, which is sent to the callback. +
+In C API, the callback is called with the return code set to
+'WEECHAT_HOOK_PROCESS_CHILD', which means the callback is running in the child
+process (after fork). +
+In scripting API, the function 'name' is called directly and its result
+(string) is sent to the callback (like the output of an external command).
 
 [TIP]
 If you want to retrieve infos about WeeChat (like current stable version,
@@ -7575,6 +7587,7 @@ C example:
 
 [source,C]
 ----
+/* example with an external command */
 int
 my_process_cb (const void *pointer, void *data, const char *command,
                int return_code, const char *out, const char *err)
@@ -7605,6 +7618,52 @@ my_process_cb (const void *pointer, void *data, const char *command,
 
 struct t_hook *my_process_hook = weechat_hook_process ("ls", 5000,
                                                        &my_process_cb, NULL, NULL);
+
+/* example with the callback called in the child process */
+int
+my_process_cb (const void *pointer, void *data, const char *command,
+               int return_code, const char *out, const char *err)
+{
+    if (return_code == WEECHAT_HOOK_PROCESS_CHILD)
+    {
+        /* do something blocking... */
+        /* ... */
+
+        /* the stdout will be sent as "out" in the parent callback */
+        printf ("this is the result");
+
+        /* return code of the process */
+        return 0;
+    }
+    else
+    {
+        if (return_code == WEECHAT_HOOK_PROCESS_ERROR)
+        {
+            weechat_printf (NULL, "Error with command '%s'", command);
+            return WEECHAT_RC_OK;
+        }
+
+        if (return_code >= 0)
+        {
+            weechat_printf (NULL, "return_code = %d", return_code);
+        }
+
+        if (out)
+        {
+            weechat_printf (NULL, "stdout: %s", out);
+        }
+
+        if (err)
+        {
+            weechat_printf (NULL, "stderr: %s", err);
+        }
+
+        return WEECHAT_RC_OK;
+    }
+}
+
+struct t_hook *my_process_hook = weechat_hook_process ("func:get_status", 5000,
+                                                       &my_process_cb, NULL, NULL);
 ----
 
 Script (Python):
@@ -7614,7 +7673,7 @@ Script (Python):
 # prototype
 hook = weechat.hook_process(command, timeout, callback, callback_data)
 
-# example
+# example with an external command
 def my_process_cb(data, command, return_code, out, err):
     if return_code == weechat.WEECHAT_HOOK_PROCESS_ERROR:
         weechat.prnt("", "Error with command '%s'" % command)
@@ -7628,6 +7687,26 @@ def my_process_cb(data, command, return_code, out, err):
     return weechat.WEECHAT_RC_OK
 
 hook = weechat.hook_process("ls", 5000, "my_process_cb", "")
+
+# example with a script function
+def get_status(data):
+    # do something blocking...
+    # ...
+    return "this is the result"
+
+def my_process_cb(data, command, return_code, out, err):
+    if return_code == weechat.WEECHAT_HOOK_PROCESS_ERROR:
+        weechat.prnt("", "Error with command '%s'" % command)
+        return weechat.WEECHAT_RC_OK
+    if return_code >= 0:
+        weechat.prnt("", "return_code = %d" % return_code)
+    if out != "":
+        weechat.prnt("", "stdout: %s" % out)
+    if err != "":
+        weechat.prnt("", "stderr: %s" % err)
+    return weechat.WEECHAT_RC_OK
+
+hook = weechat.hook_process("func:get_status", 5000, "my_process_cb", "")
 ----
 
 ==== hook_process_hashtable
diff --git a/doc/fr/weechat_plugin_api.fr.asciidoc b/doc/fr/weechat_plugin_api.fr.asciidoc
index 030f733f9..4f7cd595d 100644
--- a/doc/fr/weechat_plugin_api.fr.asciidoc
+++ b/doc/fr/weechat_plugin_api.fr.asciidoc
@@ -7654,8 +7654,8 @@ struct t_hook *weechat_hook_process (const char *command,
 
 Paramètres :
 
-* 'command' : commande à lancer dans le processus fils ou URL
-  _(WeeChat ≥ 0.3.7)_ (voir ci-dessous)
+* 'command' : commande à lancer dans le processus fils, URL _(WeeChat ≥ 0.3.7)_
+  ou fonction _(WeeChat ≥ 1.5)_ (voir ci-dessous)
 * 'timeout' : timeout pour la commande (en millisecondes) : après ce délai, le
   processus fils est tué (0 signifie pas de limite)
 * 'callback' : fonction appelée quand des données du fils sont disponibles, or
@@ -7671,14 +7671,19 @@ Paramètres :
 **** '2' : erreur de transfert
 **** '3' : pas assez de mémoire
 **** '4' : erreur avec un fichier
-*** '< 0' : 'WEECHAT_HOOK_PROCESS_RUNNING' (données disponibles, mais le
-    fils tourne toujours) ou 'WEECHAT_HOOK_PROCESS_ERROR' (erreur en lançant
-    la commande)
+*** '< 0' :
+**** 'WEECHAT_HOOK_PROCESS_RUNNING' : données disponibles, mais le fils tourne
+     toujours
+**** 'WEECHAT_HOOK_PROCESS_ERROR' : erreur en lançant la commande
+**** 'WEECHAT_HOOK_PROCESS_CHILD': le "callback" est appelé dans le processus
+     fils
 ** 'out' : sortie standard de la commande (stdout)
 ** 'err' : erreurs de la commande (stderr)
 ** valeur de retour :
 *** 'WEECHAT_RC_OK'
 *** 'WEECHAT_RC_ERROR'
+*** code retour du processus fils (dans le cas d'une fonction avec "func:" dans
+    la commande)
 * 'callback_pointer' : pointeur donné au "callback" lorsqu'il est appelé par
   WeeChat
 * 'callback_data' : pointeur donné au "callback" lorsqu'il est appelé par
@@ -7699,6 +7704,17 @@ pour télécharger le contenu de l'URL _(WeeChat ≥ 0.3.7)_.
 Des options pour l'URL sont possibles avec la fonction
 <<_hook_process_hashtable,weechat_hook_process_hashtable>>.
 
+La commande peut aussi être le nom d'une fonction avec le format : "func:nom",
+pour exécuter la fonction "nom" _(WeeChat ≥ 1.5)_. Cette fonction reçoit un
+paramètre ('data') et doit retourner une chaîne de caractères, qui sera envoyée
+au "callback". +
+Dans l'API C, le "callback" est appelé avec le code retour qui vaut
+'WEECHAT_HOOK_PROCESS_CHILD', cela signifie que le "callback" tourne dans le
+processus fils (après le fork). +
+Dans l'API script, la fonction 'nom' est appelée directement et le résultat
+(chaîne de caractères) est envoyé au "callback" (comme la sortie d'une commande
+externe).
+
 [TIP]
 Si vous souhaitez récupérer des infos à propos de WeeChat (comme la version
 stable actuelle, le dernier commit git, etc...), vous pouvez utiliser les URLs
@@ -7720,6 +7736,7 @@ Exemple en C :
 
 [source,C]
 ----
+/* exemple avec une commande externe */
 int
 my_process_cb (const void *pointer, void *data, const char *command,
                int return_code, const char *out, const char *err)
@@ -7750,6 +7767,52 @@ my_process_cb (const void *pointer, void *data, const char *command,
 
 struct t_hook *my_process_hook = weechat_hook_process ("ls", 5000,
                                                        &my_process_cb, NULL, NULL);
+
+/* exemple avec le "callback" appelé dans le processus fils */
+int
+my_process_cb (const void *pointer, void *data, const char *command,
+               int return_code, const char *out, const char *err)
+{
+    if (return_code == WEECHAT_HOOK_PROCESS_CHILD)
+    {
+        /* faire quelque chose de bloquant... */
+        /* ... */
+
+        /* la sortie "stdout" sera envoyée comme "out" au "callback" parent */
+        printf ("ceci est le résultat");
+
+        /* code retour du processus */
+        return 0;
+    }
+    else
+    {
+        if (return_code == WEECHAT_HOOK_PROCESS_ERROR)
+        {
+            weechat_printf (NULL, "Erreur avec la commande '%s'", command);
+            return WEECHAT_RC_OK;
+        }
+
+        if (return_code >= 0)
+        {
+            weechat_printf (NULL, "return_code = %d", return_code);
+        }
+
+        if (out)
+        {
+            weechat_printf (NULL, "stdout : %s", out);
+        }
+
+        if (err)
+        {
+            weechat_printf (NULL, "stderr : %s", err);
+        }
+
+        return WEECHAT_RC_OK;
+    }
+}
+
+struct t_hook *my_process_hook = weechat_hook_process ("func:get_status", 5000,
+                                                       &my_process_cb, NULL, NULL);
 ----
 
 Script (Python) :
@@ -7759,7 +7822,7 @@ Script (Python) :
 # prototype
 hook = weechat.hook_process(command, timeout, callback, callback_data)
 
-# exemple
+# exemple avec une commande externe
 def my_process_cb(data, command, return_code, out, err):
     if return_code == weechat.WEECHAT_HOOK_PROCESS_ERROR:
         weechat.prnt("", "Erreur avec la commande '%s'" % command)
@@ -7773,6 +7836,26 @@ def my_process_cb(data, command, return_code, out, err):
     return weechat.WEECHAT_RC_OK
 
 hook = weechat.hook_process("ls", 5000, "my_process_cb", "")
+
+# exemple avec une fonction du script
+def get_status(data):
+    # faire quelque chose de bloquant...
+    # ...
+    return "ceci est le résultat"
+
+def my_process_cb(data, command, return_code, out, err):
+    if return_code == weechat.WEECHAT_HOOK_PROCESS_ERROR:
+        weechat.prnt("", "Erreur avec la commande '%s'" % command)
+        return weechat.WEECHAT_RC_OK
+    if return_code >= 0:
+        weechat.prnt("", "return_code = %d" % return_code)
+    if out != "":
+        weechat.prnt("", "stdout : %s" % out)
+    if err != "":
+        weechat.prnt("", "stderr : %s" % err)
+    return weechat.WEECHAT_RC_OK
+
+hook = weechat.hook_process("func:get_status", 5000, "my_process_cb", "")
 ----
 
 ==== hook_process_hashtable
diff --git a/doc/it/weechat_plugin_api.it.asciidoc b/doc/it/weechat_plugin_api.it.asciidoc
index 641303e62..3b006c07d 100644
--- a/doc/it/weechat_plugin_api.it.asciidoc
+++ b/doc/it/weechat_plugin_api.it.asciidoc
@@ -7718,8 +7718,9 @@ struct t_hook *weechat_hook_process (const char *command,
 
 Argomenti:
 
-* 'command': comando da avviare nel processo figlio o URL
-  _(WeeChat ≥ 0.3.7)_, segue:
+// TRANSLATION MISSING
+* 'command': command to launch in child process, URL _(WeeChat ≥ 0.3.7)_ or
+  function _(WeeChat ≥ 1.5)_ (see below)
 * 'timeout': timeout per il comando (in millisecondi): dopo questo timeout,
   il processo figlio viene terminato (0 indica nessun timeout)
 * 'callback': funzione chiamata quando i dati dal processo figlio sono disponibili,
@@ -7735,14 +7736,19 @@ Argomenti:
 **** '2': errore di trasferimento
 **** '3': memoria non sufficiente
 **** '4': errore con un file
-*** '< 0': 'WEECHAT_HOOK_PROCESS_RUNNING' (dati disponibili, ma figlio
-    ancora in esecuzione) o 'WEECHAT_HOOK_PROCESS_ERROR' (errore nella
-    esecuzione del comando)
+*** '< 0':
+**** 'WEECHAT_HOOK_PROCESS_RUNNING': dati disponibili, ma figlio ancora in
+     esecuzione)
+**** 'WEECHAT_HOOK_PROCESS_ERROR': errore nella esecuzione del comando
+// TRANSLATION MISSING
+**** 'WEECHAT_HOOK_PROCESS_CHILD': callback is called in the child process
 ** 'out': output standard del comando (stdout)
 ** 'err': output di errore del comando (stderr)
 ** valore restituito:
 *** 'WEECHAT_RC_OK'
 *** 'WEECHAT_RC_ERROR'
+// TRANSLATION MISSING
+*** child process return code (in case of function with "func:" in command)
 * 'callback_pointer': puntatore fornito alla callback quando chiamata da WeeChat
 // TRANSLATION MISSING
 * 'callback_data': puntatore fornito alla callback quando chiamata da WeeChat;
@@ -7762,6 +7768,16 @@ un URL sono disponibili con la funzione
 <<_hook_process_hashtable,weechat_hook_process_hashtable>>.
 
 // TRANSLATION MISSING
+The command can also be a function name with format: "func:name", to execute
+the function "name" _(WeeChat ≥ 1.5)_. This function receives a single argument
+('data') and must return a string, which is sent to the callback. +
+In C API, the callback is called with the return code set to
+'WEECHAT_HOOK_PROCESS_CHILD', which means the callback is running in the child
+process (after fork). +
+In scripting API, the function 'name' is called directly and its result
+(string) is sent to the callback (like the output of an external command).
+
+// TRANSLATION MISSING
 [TIP]
 If you want to retrieve infos about WeeChat (like current stable version,
 latest git commit, ...), you can use URLs on page https://weechat.org/dev/info
@@ -7782,6 +7798,7 @@ Esempio in C:
 
 [source,C]
 ----
+/* example with an external command */
 int
 my_process_cb (const void *pointer, void *data, const char *command,
                int return_code, const char *out, const char *err)
@@ -7812,6 +7829,52 @@ my_process_cb (const void *pointer, void *data, const char *command,
 
 struct t_hook *my_process_hook = weechat_hook_process ("ls", 5000,
                                                        &my_process_cb, NULL, NULL);
+
+/* example with the callback called in the child process */
+int
+my_process_cb (const void *pointer, void *data, const char *command,
+               int return_code, const char *out, const char *err)
+{
+    if (return_code == WEECHAT_HOOK_PROCESS_CHILD)
+    {
+        /* do something blocking... */
+        /* ... */
+
+        /* the stdout will be sent as "out" in the parent callback */
+        printf ("this is the result");
+
+        /* return code of the process */
+        return 0;
+    }
+    else
+    {
+        if (return_code == WEECHAT_HOOK_PROCESS_ERROR)
+        {
+            weechat_printf (NULL, "Error with command '%s'", command);
+            return WEECHAT_RC_OK;
+        }
+
+        if (return_code >= 0)
+        {
+            weechat_printf (NULL, "return_code = %d", return_code);
+        }
+
+        if (out)
+        {
+            weechat_printf (NULL, "stdout: %s", out);
+        }
+
+        if (err)
+        {
+            weechat_printf (NULL, "stderr: %s", err);
+        }
+
+        return WEECHAT_RC_OK;
+    }
+}
+
+struct t_hook *my_process_hook = weechat_hook_process ("func:get_status", 5000,
+                                                       &my_process_cb, NULL, NULL);
 ----
 
 Script (Python):
@@ -7821,7 +7884,7 @@ Script (Python):
 # prototipo
 hook = weechat.hook_process(command, timeout, callback, callback_data)
 
-# esempio
+# example with an external command
 def my_process_cb(data, command, return_code, out, err):
     if return_code == weechat.WEECHAT_HOOK_PROCESS_ERROR:
         weechat.prnt("", "Error with command '%s'" % command)
@@ -7835,6 +7898,26 @@ def my_process_cb(data, command, return_code, out, err):
     return weechat.WEECHAT_RC_OK
 
 hook = weechat.hook_process("ls", 5000, "my_process_cb", "")
+
+# example with a script function
+def get_status(data):
+    # do something blocking...
+    # ...
+    return "this is the result"
+
+def my_process_cb(data, command, return_code, out, err):
+    if return_code == weechat.WEECHAT_HOOK_PROCESS_ERROR:
+        weechat.prnt("", "Error with command '%s'" % command)
+        return weechat.WEECHAT_RC_OK
+    if return_code >= 0:
+        weechat.prnt("", "return_code = %d" % return_code)
+    if out != "":
+        weechat.prnt("", "stdout: %s" % out)
+    if err != "":
+        weechat.prnt("", "stderr: %s" % err)
+    return weechat.WEECHAT_RC_OK
+
+hook = weechat.hook_process("func:get_status", 5000, "my_process_cb", "")
 ----
 
 ==== hook_process_hashtable
diff --git a/doc/ja/weechat_plugin_api.ja.asciidoc b/doc/ja/weechat_plugin_api.ja.asciidoc
index d544da27c..693ef2ccf 100644
--- a/doc/ja/weechat_plugin_api.ja.asciidoc
+++ b/doc/ja/weechat_plugin_api.ja.asciidoc
@@ -7515,8 +7515,9 @@ struct t_hook *weechat_hook_process (const char *command,
 
 引数:
 
-* 'command': 子プロセスで実行するコマンドまたは
-  URL _(WeeChat バージョン 0.3.7 以上で利用可)_ (以下を参照)
+// TRANSLATION MISSING
+* 'command': command to launch in child process, URL _(WeeChat ≥ 0.3.7)_ or
+  function _(WeeChat ≥ 1.5)_ (see below)
 * 'timeout': コマンドのタイムアウト (ミリ秒):
   このタイムアウトを過ぎたら、子プロセスを kill します (タイムアウトさせない場合は 0)
 * 'callback':
@@ -7531,13 +7532,20 @@ struct t_hook *weechat_hook_process (const char *command,
 **** '2': 転送エラー
 **** '3': メモリ不足
 **** '4': ファイルに関するエラー
-*** '< 0': 'WEECHAT_HOOK_PROCESS_RUNNING' (データは利用可能だが子プロセスは終了していない)
-    または 'WEECHAT_HOOK_PROCESS_ERROR' (コマンドの実行中にエラー)
+*** '< 0':
+// TRANSLATION MISSING
+**** 'WEECHAT_HOOK_PROCESS_RUNNING': data available, but child still running)
+// TRANSLATION MISSING
+**** 'WEECHAT_HOOK_PROCESS_ERROR': error when launching command
+// TRANSLATION MISSING
+**** 'WEECHAT_HOOK_PROCESS_CHILD': callback is called in the child process
 ** 'out': コマンドの標準出力 (stdout)
 ** 'err': コマンドの標準エラー出力 (stderr)
 ** 戻り値:
 *** 'WEECHAT_RC_OK'
 *** 'WEECHAT_RC_ERROR'
+// TRANSLATION MISSING
+*** child process return code (in case of function with "func:" in command)
 * 'callback_pointer': WeeChat が 'callback' コールバックを呼び出す際にコールバックに渡すポインタ
 * 'callback_data': WeeChat が 'callback' コールバックを呼び出す際にコールバックに渡すポインタ;
   このポインタが NULL でない場合、このポインタは malloc (または類似の関数)
@@ -7554,6 +7562,16 @@ struct t_hook *weechat_hook_process (const char *command,
 の内容がダウンロードされます _(WeeChat バージョン 0.3.7 以上で利用可)_ 。<<_hook_process_hashtable,weechat_hook_process_hashtable>>
 関数を使えば URL に対してオプションを与えることもできます。
 
+// TRANSLATION MISSING
+The command can also be a function name with format: "func:name", to execute
+the function "name" _(WeeChat ≥ 1.5)_. This function receives a single argument
+('data') and must return a string, which is sent to the callback. +
+In C API, the callback is called with the return code set to
+'WEECHAT_HOOK_PROCESS_CHILD', which means the callback is running in the child
+process (after fork). +
+In scripting API, the function 'name' is called directly and its result
+(string) is sent to the callback (like the output of an external command).
+
 [TIP]
 WeeChat に関する情報 (例えば現在の安定版、最新の git コミット、...)
 が欲しい場合、https://weechat.org/dev/info に書かれている URL を使ってください
@@ -7573,6 +7591,7 @@ C 言語での使用例:
 
 [source,C]
 ----
+/* example with an external command */
 int
 my_process_cb (const void *pointer, void *data, const char *command,
                int return_code, const char *out, const char *err)
@@ -7603,6 +7622,52 @@ my_process_cb (const void *pointer, void *data, const char *command,
 
 struct t_hook *my_process_hook = weechat_hook_process ("ls", 5000,
                                                        &my_process_cb, NULL, NULL);
+
+/* example with the callback called in the child process */
+int
+my_process_cb (const void *pointer, void *data, const char *command,
+               int return_code, const char *out, const char *err)
+{
+    if (return_code == WEECHAT_HOOK_PROCESS_CHILD)
+    {
+        /* do something blocking... */
+        /* ... */
+
+        /* the stdout will be sent as "out" in the parent callback */
+        printf ("this is the result");
+
+        /* return code of the process */
+        return 0;
+    }
+    else
+    {
+        if (return_code == WEECHAT_HOOK_PROCESS_ERROR)
+        {
+            weechat_printf (NULL, "Error with command '%s'", command);
+            return WEECHAT_RC_OK;
+        }
+
+        if (return_code >= 0)
+        {
+            weechat_printf (NULL, "return_code = %d", return_code);
+        }
+
+        if (out)
+        {
+            weechat_printf (NULL, "stdout: %s", out);
+        }
+
+        if (err)
+        {
+            weechat_printf (NULL, "stderr: %s", err);
+        }
+
+        return WEECHAT_RC_OK;
+    }
+}
+
+struct t_hook *my_process_hook = weechat_hook_process ("func:get_status", 5000,
+                                                       &my_process_cb, NULL, NULL);
 ----
 
 スクリプト (Python) での使用例:
@@ -7612,7 +7677,7 @@ struct t_hook *my_process_hook = weechat_hook_process ("ls", 5000,
 # プロトタイプ
 hook = weechat.hook_process(command, timeout, callback, callback_data)
 
-# 例
+# example with an external command
 def my_process_cb(data, command, return_code, out, err):
     if return_code == weechat.WEECHAT_HOOK_PROCESS_ERROR:
         weechat.prnt("", "Error with command '%s'" % command)
@@ -7626,6 +7691,26 @@ def my_process_cb(data, command, return_code, out, err):
     return weechat.WEECHAT_RC_OK
 
 hook = weechat.hook_process("ls", 5000, "my_process_cb", "")
+
+# example with a script function
+def get_status(data):
+    # do something blocking...
+    # ...
+    return "this is the result"
+
+def my_process_cb(data, command, return_code, out, err):
+    if return_code == weechat.WEECHAT_HOOK_PROCESS_ERROR:
+        weechat.prnt("", "Error with command '%s'" % command)
+        return weechat.WEECHAT_RC_OK
+    if return_code >= 0:
+        weechat.prnt("", "return_code = %d" % return_code)
+    if out != "":
+        weechat.prnt("", "stdout: %s" % out)
+    if err != "":
+        weechat.prnt("", "stderr: %s" % err)
+    return weechat.WEECHAT_RC_OK
+
+hook = weechat.hook_process("func:get_status", 5000, "my_process_cb", "")
 ----
 
 ==== hook_process_hashtable