weechat/doc/it/weechat_plugin_api.it.txt

Referenze API per Plugin di WeeChat
===================================
Sébastien Helleu <flashcode@flashtux.org>


Questo manuale documenta il client di chat WeeChat, ed è parte
del programma stesso.

La versione più recente di questo documento si trova qui:
http://www.weechat.org/doc


[[introduction]]
Introduzione
------------

WeeChat (Wee Enhanced Environment for Chat) è un client di chat
libero, veloce e leggero, realizzato per molti sistemi operativi.

Questo manuale documenta le API per i plugin di WeeChat, utilizzate
dai plugin C per interagire con il core di WeeChat.

[[plugins_in_weechat]]
Plugin in WeeChat
-----------------

Un plugin è un programma C che può richiamare le funzioni di WeeChat
definite in un'interfaccia.

Questo programma C non richiede i sorgenti di WeeChat per essere compilato
e può essere caricato dinamicamente in WeeChat con il comano `/plugin`.

Il plugin deve essere una libreria dinamica, per essere caricato dinamicamente
dal del sistema operativo.
In GNU/Linux, il file ha estensione ".so", ".dll" in Windows.

Il plugin deve includere il file "weechat-plugin.h" (disponibile nel codice
sorgente di WeeChat).
Il file definisce strutture e tipi utilizzati per comunicare con WeeChat.

[[macros]]
Macro
~~~~~

Il plugin deve utilizzare alcune macro (per definire alcune variabili):

WEECHAT_PLUGIN_NAME("nome")::
    nome del plugin

WEECHAT_PLUGIN_DESCRIPTION("descrizione")::
    breve descrizione del plugin

WEECHAT_PLUGIN_VERSION("1.0")::
    versione del plugin

WEECHAT_PLUGIN_LICENSE("GPL3")::
    licenza del plugin

[[main_functions]]
Funzioni principali
~~~~~~~~~~~~~~~~~~~

Il plugin deve usare due funzioni:

* weechat_plugin_init
* weechat_plugin_end

weechat_plugin_init
^^^^^^^^^^^^^^^^^^^

Questa funzione viene chiamata quando il plugin è caricato.
da WeeChat.

Prototipo:

[source,C]
----------------------------------------
int weechat_plugin_init (struct t_weechat_plugin *plugin,
                         int argc, char *argv[]);
----------------------------------------

Argomenti:

* 'plugin': puntatore alla struttura del plugin di WeeChat
* 'argc': numero di argomenti per il plugin (fornito dalla riga di comando
  dall'utente)
* 'argv': argomenti per il plugin

Valori restituiti:

* 'WEECHAT_RC_OK' se l'operazione ha successo (il plugin
  verrà caricato)
* 'WEECHAT_RC_ERROR' se c'è un errore (il plugin NON
  verrà caricato)

weechat_plugin_end
^^^^^^^^^^^^^^^^^^

Questa funzione viene chiamata quando il plugin viene
disattivato da WeeChat.

Prototipo:

[source,C]
----------------------------------------
int weechat_plugin_end (struct t_weechat_plugin *plugin);
----------------------------------------

Argomenti:

* 'plugin': puntatore alla struttura plugin di WeeChat

Valori restituiti:

* 'WEECHAT_RC_OK' se l'operazione ha successo
* 'WEECHAT_RC_ERROR' se c'è un errore

[[compile_plugin]]
Compilazione del plugin
~~~~~~~~~~~~~~~~~~~~~~~

La compilazione non richiede i sorgenti di WeeChat, è richiesto solo
il file 'weechat-plugin.h'.

Per compilare un plugin che ha un file "tizio.c" (in GNU/Linux):

----------------------------------------
$ gcc -fPIC -Wall -c tizio.c
$ gcc -shared -fPIC -o libtizio.so tizio.o
----------------------------------------

[[load_plugin]]
Caricamento del plugin
~~~~~~~~~~~~~~~~~~~~~~

Copiare il file 'libtizio.so' nella cartella plugin di sistema (ad
esempio '/usr/local/lib/weechat/plugins') oppure nella cartella
plugin dell'utente (ad esempio '/home/xxx/.weechat/plugins').

In WeeChat:

----------------------------------------
/plugin load tizio
----------------------------------------

[[plugin_example]]
Plugin di esempio
~~~~~~~~~~~~~~~~~

Un esempio completo di plugin, che aggiunge un comando '/double':
visualizza due volte gli argomenti nel buffer corrente, oppure esegue un
comando due volte (ok, non sarà molto utile, ma è solo un esempio!):

[source,C]
----------------------------------------
#include <stdlib.h>

#include "weechat-plugin.h"

WEECHAT_PLUGIN_NAME("double");
WEECHAT_PLUGIN_DESCRIPTION("Test plugin for WeeChat");
WEECHAT_PLUGIN_AUTHOR("Sebastien Helleu <flashcode@flashtux.org>");
WEECHAT_PLUGIN_VERSION("0.1");
WEECHAT_PLUGIN_LICENSE("GPL3");

struct t_weechat_plugin *weechat_plugin = NULL;


/* callback per il comando "/double" */

int
command_double_cb (void *data, struct t_gui_buffer *buffer, int argc,
                   char **argv, char **argv_eol)
{
    /* fa felice il compilatore C */
    (void) data;
    (void) buffer;
    (void) argv;
    
    if (argc > 1)
    {
        weechat_command (NULL, argv_eol[1]);
        weechat_command (NULL, argv_eol[1]);
    }
    
    return WEECHAT_RC_OK;
}

int
weechat_plugin_init (struct t_weechat_plugin *plugin,
                     int argc, char *argv[])
{
    weechat_plugin = plugin;
    
    weechat_hook_command ("double",
                          "Visualizza due volte un messaggio "
                          "oppure esegue un comando due volte",
                          "messaggio | comando",
                          "messaggio: messaggio da visualizzare due volte\n"
                          "comando: comando da eseguire due volte",
                          NULL,
                          &command_double_cb, NULL);
    
    return WEECHAT_RC_OK;
}

int
weechat_plugin_end (struct t_weechat_plugin *plugin)
{
    /* fa felice il compilatore C */
    (void) plugin;
    
    return WEECHAT_RC_OK;
}
----------------------------------------

[[plugin_api]]
Plugin API
----------

I capitoli seguenti descrivono le funzioni  nelle API, organizzate
in categorie.

Per ogni funzione, viene fornita:

* descrizione della funzione,
* prototipo C,
* dettaglio degli argomenti,
* valore restituito,
* esempio C,
* esempio nello script Python (la sintassi è simile per gli altri linguaggi di
  scripting).

[[plugins]]
Plugin
~~~~~~

Funzioni per ottenere informazioni sui plugin.

weechat_plugin_get_name
^^^^^^^^^^^^^^^^^^^^^^^

Ottiene il nome del plugin.

Prototipo:

[source,C]
----------------------------------------
const char *weechat_plugin_get_name (struct t_weechat_plugin *plugin);
----------------------------------------

Argomenti:

* 'plugin': puntatore alla struttura plugin di WeeChat (può essere NULL)

Valore restituito:

* nome del plugin, "core" per il core di WeeChat (se il puntatore al plugin
  è NULL)

Esempio in C:

[source,C]
----------------------------------------
const char *name = weechat_plugin_get_name (plugin);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
name = weechat.plugin_get_name(plugin)

# esempio
plugin = weechat.buffer_get_pointer(weechat.current_buffer(), "plugin")
name = weechat.plugin_get_name(plugin)
----------------------------------------

[[strings]]
Stringhe
~~~~~~~~

Molte delle funzioni stringa che seguono sono già disponibili tramite
funzioni standard in C, ma si raccomanda di utilizzare le funzioni in
questa API perché compatibili con UTF-8 e il locale.

weechat_charset_set
^^^^^^^^^^^^^^^^^^^

Imposta il nuovo set caratteri del nuovo plugin (il set caratteri predefinito
è 'UTF-8', così se il plugin usa 'UTF-8' non è necessario chiamare questa
funzione).

Prototipo:

[source,C]
----------------------------------------
void weechat_charset_set (const char *charset);
----------------------------------------

Argomenti:

* 'charset': nuovo set caratteri da usare

Esempio in C:

[source,C]
----------------------------------------
weechat_charset_set (plugin, "iso-8859-1");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.charset_set(charset)

# esempio
weechat.charset_set("iso-8859-1")
----------------------------------------

weechat_iconv_to_internal
^^^^^^^^^^^^^^^^^^^^^^^^^

Converte le stringhe per il set caratteri interno di
WeeChat (UTF-8).

Prototipo:

[source,C]
----------------------------------------
char *weechat_iconv_to_internal (const char *charset, const char *string);
----------------------------------------

Argomenti:

* 'charset': set caratteri da convertire
* 'string': stringa da convertire

Valore restituito:

* la stringa convertita (deve essere liberata richiamando "free"
  dopo l'utilizzo)

Esempio in C:

[source,C]
----------------------------------------
char *str = weechat_iconv_to_internal (plugin, "iso-8859-1", "iso string: é à");
/* ... */
free (str);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
str = weechat.iconv_to_internal(charset, string)

# esempio
str = weechat.iconv_to_internal("iso-8859-1", "iso string: é à")
----------------------------------------

weechat_iconv_from_internal
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Converte la stringa dal set caratteri interno di WeeChat (UTF-8)
in un'altra.

Prototipo:

[source,C]
----------------------------------------
char *weechat_iconv_from_internal (const char *charset, const char *string);
----------------------------------------

Argomenti:

* 'charset': set caratteri in uscita
* 'string': stringa da convertire

Valore restituito:

* la stringa convertita (deve essere liberata richiamando "free"
  dopo l'utilizzo

Esempio in C:

[source,C]
----------------------------------------
char *str = weechat_iconv_from_internal ("iso-8859-1", "utf-8 string: é à");
/* ... */
free (str);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
str = weechat.iconv_from_internal(charset, string)

# esempio
str = weechat.iconv_from_internal("iso-8859-1", "utf-8 string: é à")
----------------------------------------

weechat_gettext
^^^^^^^^^^^^^^^

Restituisce la stringa tradotta (dipende dalla lingua).

Prototipo:

[source,C]
----------------------------------------
const char *weechat_gettext (const char *string);
----------------------------------------

Argomenti:

* 'string': stringa da tradurre

Valore restituito:

* stringa tradotta

Esempio in C:

[source,C]
----------------------------------------
char *str = weechat_gettext ("hello");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
str = weechat.gettext(string)

# esempio
str = weechat.gettext("hello")
----------------------------------------

weechat_ngettext
^^^^^^^^^^^^^^^^

Restituisce la stringa tradotta, utilizzando il singolare o il plurale, in base
all'argomento 'count' (contatore).

Prototipo:

[source,C]
----------------------------------------
const char *weechat_ngettext (const char *string, const char *plural,
                              int count);
----------------------------------------

Argomenti:

* 'string': stringa da tradurre, singolare
* 'plural': stringa da tradurre, plurale
* 'count': utilizzato per scegliere tra singolare e plurale (la scelta viene
  fatta in base alla lingua locale)

Valore restituito:

* stringa tradotta

Esempio in C:

[source,C]
----------------------------------------
char *str = weechat_ngettext ("file", "files", num_files);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
str = weechat.ngettext(string, plural, count)

# esempio
num_files = 2
str = weechat.ngettext("file", "files", num_files)
----------------------------------------

weechat_strndup
^^^^^^^^^^^^^^^

Restituisce una stringa duplicata, con un massimo di caratteri
impostato su 'chars'.

Prototipo:

[source,C]
----------------------------------------
char *weechat_strndup (const char *string, int length);
----------------------------------------

Argomenti:

* 'string': stringa da duplicare
* 'length': caratteri massimi da duplicare

Valore restituito:

* stringa duplicata (deve essere liberata chiamando "free" dopo
  l'utilizzo)

Esempio in C:

[source,C]
----------------------------------------
char *str = weechat_strndup ("abcdef", 3); /* result: "abc" */
/* ... */
free (str);
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_string_tolower
^^^^^^^^^^^^^^^^^^^^^^

Converte una stringa UTF-8 in minuscolo.

Prototipo:

[source,C]
----------------------------------------
void weechat_string_tolower (const char *string);
----------------------------------------

Argomenti:

* 'string': stringa da convertire

Esempio in C:

[source,C]
----------------------------------------
char *str = "AbCdé";
weechat_string_tolower (str); /* str ora è: "abcdé" */
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_string_toupper
^^^^^^^^^^^^^^^^^^^^^^

Converte una stringa UTF-8 in maiuscolo.

Prototipo:

[source,C]
----------------------------------------
void weechat_string_toupper (const char *string);
----------------------------------------

Argomenti:

* 'string': stringa da convertire

Esempio in C:

[source,C]
----------------------------------------
char *str = "AbCdé";
weechat_string_tolower (str); /* str ora è: "ABCDé" */
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_strcasecmp
^^^^^^^^^^^^^^^^^^

Confronta stringa indipendente da caso (maiuscole
o minuscole) e da locale.

Prototipo:

[source,C]
----------------------------------------
int weechat_strcasecmp (const char *string1, const char *string2);
----------------------------------------

Argomenti:

* 'string1': prima stringa da comparare
* 'string2': seconda stringa da comparare

Valore restituito:

* differenze tra le due stringhe:
** negativa se stringa1 < stringa2
** zero se stringa1 == stringa1
** positiva se stringa1 > stringa2

Esempio in C:

[source,C]
----------------------------------------
int diff = weechat_strcasecmp ("aaa", "CCC"); /* == -2 */
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_strncasecmp
^^^^^^^^^^^^^^^^^^^

Confronta stringa indipendente da caso (maiuscole o minuscole) e da locale, per
un numero 'max' di caratteri.

Prototipo:

[source,C]
----------------------------------------
int weechat_strncasecmp (const char *string1, const char *string2, int max);
----------------------------------------

Argomenti:

* 'string1': prima stringa da comparare
* 'string2': seconda stringa da comparare
* 'max': numero massimo di caratteri da comparare

Valore restituito:

* differenze tra le due stringhe:
** negativa se stringa1 < stringa2
** zero se stringa1 == stringa1
** positiva se stringa1 > stringa2

Esempio in C:

[source,C]
----------------------------------------
int diff = weechat_strncasecmp ("aabb", "aacc", 2); /* == 0 */
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_strcmp_ignore_chars
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Confronta una stringa locale (ed opzionalmente indipendente
da maiuscole/minuscole), ignorando alcuni caratteri.

Prototipo:

[source,C]
----------------------------------------
int weechat_strcmp_ignore_chars (const char *string1, const char *string2,
                                 const char *chars_ignored,
                                 int case_sensitive);
----------------------------------------

Argomenti:

* 'string1': prima stringa per il confronto
* 'string2': seconda stringa per il confronto
* 'chars_ignored': stringa con caratteri da ignorare
* 'case_sensitive': 1 per il confronto con caso esatto (maiuscole/minuscole),
  altrimenti 0

Valore restituito:

* differenza tra le due stringhe:
** negativa se string1 < string2
** zero se string1 == string2
** positiva se string1 > string2

Esempio in C:

[source,C]
----------------------------------------
int diff = weechat_strcmp_ignore_chars ("a-b", "--a-e", "-", 1); /* == -3 */
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_strcasestr
^^^^^^^^^^^^^^^^^^

Cerca una stringa indipendente da locale e caso esatto
(maiuscole/minuscole).

Prototipo:

[source,C]
----------------------------------------
char *weechat_strcasestr (const char *string, const char *search);
----------------------------------------

Argomenti:

* 'string': stringa
* 'search': stringa da cercare in 'string'

Valore restituito:

* puntatore alla stringa trovata, o NULL se non trovata

Esempio in C:

[source,C]
----------------------------------------
char *pos = weechat_strcasestr ("aBcDeF", "de"); /* risultato: puntatore a "DeF" */
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_string_match
^^^^^^^^^^^^^^^^^^^^

Verifica se una stringa coincide ad una mask.

Prototipo:

[source,C]
----------------------------------------
int weechat_string_match (const char *string, const char *mask,
                          int case_sensitive);
----------------------------------------

Argomenti:

* 'string': stringa
* 'mask': mask, può iniziare o terminare con "`*`" (nessun altro "`*`"
  consentito all'interno della mask)

Valore restituito:

* 1 se la stringa coincide alla mask, altrimenti 0

Esempio in C:

[source,C]
----------------------------------------
int match1 = weechat_string_match ("abcdef", "abc*", 0); /* == 1 */
int match2 = weechat_string_match ("abcdef", "*dd*", 0); /* == 0 */
int match3 = weechat_string_match ("abcdef", "*def", 0); /* == 1 */
int match4 = weechat_string_match ("abcdef", "*de*", 0); /* == 1 */
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
match = weechat.string_match(string, mask, case_sensitive)

# esempio
match1 = weechat.string_match("abcdef", "abc*", 0) # 1
match2 = weechat.string_match("abcdef", "*dd*", 0) # 0
match3 = weechat.string_match("abcdef", "*def", 0) # 1
match4 = weechat.string_match("abcdef", "*de*", 0) # 1
----------------------------------------

weechat_string_replace
^^^^^^^^^^^^^^^^^^^^^^

Sostituisce tutte le ricorrenze di una stringa con un'altra.

Prototipo:

[source,C]
----------------------------------------
char *weechat_string_replace (const char *string, const char *search,
                              const char *replace);
----------------------------------------

Argomenti:

* 'string': stringa
* 'search': stringa da sostituire
* 'replace': sostituzione per la stringa 'search'

Valore restituito:

* la stringa dopo 'search' sostituita da 'replace' (deve essere liberata
  chiamando "free" dopo l'uso)

Esempio in C:

[source,C]
----------------------------------------
char *str = weechat_string_replace ("test", "s", "x"); /* result: "text" */
/* ... */
free (str);
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_string_expand_home
^^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.3._

Sostituisce la `~` iniziale con la stringa con la cartella home. Se la stringa
non inizia con `~`, viene restituita la stessa stringa.

Prototipo:

[source,C]
----------------------------------------
char *weechat_string_expand_home (const char *path);
----------------------------------------

Argomenti:

* 'path': percorso

Valore restituito:

* percorso con la `~` iniziale sostituita dalla cartella home (deve essere
  liberata chiamando "free" dopo l'uso)

Esempio in C:

[source,C]
----------------------------------------
char *str = weechat_string_expand_home ("~/file.txt");
/* result: "/home/xxx/file.txt" */
/* ... */
free (str);
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_string_remove_quotes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Rimuove le virgolette all'inizio e alla fine della stringa (ignora gli
spazi se presenti prima delle prime virgolette o dopo le ultime virgolette).

Prototipo:

[source,C]
----------------------------------------
char *weechat_string_remove_quotes (const char *string, const char *quotes);
----------------------------------------

Argomenti:

* 'string': stringa
* 'quotes': stringa con elenco di virgolette

Valore restituito:

* stringa senza virgolette all'inizio/fine (deve essere liberata chiamando "free"
  dopo l'uso)

Esempio in C:

[source,C]
----------------------------------------
char *str = weechat_string_remove_quotes (string, " 'Non posso' ", "'");
/* risultato: "Non posso" */
/* ... */
free (str);
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_string_strip
^^^^^^^^^^^^^^^^^^^^

Rimuove i caratteri ad inizio/fine della stringa.

Prototipo:

[source,C]
----------------------------------------
char *weechat_string_strip (const char *string, int left, int right,
                            const char *chars);
----------------------------------------

Argomenti:

* 'string': stringa
* 'left': rimuove i caratteri a sinistra se diversi da 0
* 'right': rimuove i caratteri a destra se diversi da 0
* 'chars': stringa con i caratteri da rimuovere

Valore restituito:

* stringa corretta (deve essere liberata chiamando "free" dopo l'uso)

Esempio in C:

[source,C]
----------------------------------------
char *str = weechat_string_strip (".abc -", 0, 1, "- ."); /* risultato: ".abc" */
/* ... */
free (str);
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_string_has_highlight
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Controlla se una stringa ha uno o più eventi, usando la lista di parole per
gli eventi.

Prototipo:

[source,C]
----------------------------------------
int weechat_string_has_highlight (const char *string,
                                  const char highlight_words);
----------------------------------------

Argomenti:

* 'string': stringa
* 'highlight_words': lista di parole per gli eventi, separate da virgole

Valore restituito:

* 1 se la stringa ha uno o più eventi, altrimenti 0

Esempio in C:

[source,C]
----------------------------------------
int hl = weechat_string_has_highlight ("my test string", "test,word2"); /* == 1 */
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
highlight = weechat.string_has_highlight(string, highlight_words)

# esempio
highlight = weechat.string_has_highlight("my test string", "test,word2") # 1
----------------------------------------

weechat_string_mask_to_regex
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Restituisce una espressione regolare con una mask, dove l'unico carattere
speciale è "`*`". Tutti gli altri caratteri speciali per le espressioni regolari
non vengono riconosciuti.

Prototipo:

[source,C]
----------------------------------------
char *weechat_string_mask_to_regex (const char *mask);
----------------------------------------

Argomenti:

* 'mask': mask

Valore restituito:

* espressione regolare, come stringa (deve essere liberata chiamando "free"
  dopo l'uso)

Esempio in C:

[source,C]
----------------------------------------
char *str_regex = weechat_string_mask_to_regex ("test*mask");
/* result: "test.*mask" */
/* ... */
free (str_regex);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
regex = weechat.string_mask_to_regex(mask)

# esempio
regex = weechat.string_mask_to_regex("test*mask") # "test.*mask"
----------------------------------------

weechat_string_split
^^^^^^^^^^^^^^^^^^^^

Divide una stringa in base a uno o più delimitatori.

Prototipo:

[source,C]
----------------------------------------
char **weechat_string_split (const char *string, const char *separators,
                             int keep_eol, int num_items_max,
                             int *num_items);
----------------------------------------

Argomenti:

* 'string': stringa da dividere
* 'separators': delimitatori usati per dividere
* 'keep_eol': se diversa da 0, allora ogni argomento conterrà tutte le stringhe
  fino a fine riga (consultare l'esempio in basso)
* 'num_items_max': maximum number of items created (0 = no limit)
* 'num_items': pointer to int which will contain number of items created

Valore restituito:

* array di stringhe, NULL se si verifica un problema (deve essere liberata chiamando
  <<_weechat_string_free_split,weechat_string_free_split>> dopo l'uso)

Esempi:

[source,C]
----------------------------------------
char **argv;
int argc;
argv = weechat_string_split ("abc de  fghi", " ", 0, 0, &argc);
/* result: argv[0] == "abc"
           argv[1] == "de"
           argv[2] == "fghi"
           argv[3] == NULL
           argc == 3
*/
weechat_string_free_split (argv);

argv = weechat_string_split ("abc de  fghi", " ", 1, 0, &argc);
/* result: argv[0] == "abc de  fghi"
           argv[1] == "de  fghi"
           argv[2] == "fghi"
           argv[3] == NULL
           argc == 3
*/
weechat_string_free_split (argv);
----------------------------------------

weechat_string_free_split
^^^^^^^^^^^^^^^^^^^^^^^^^

Libera la memoria usata per la divisione di una stringa.

Prototipo:

[source,C]
----------------------------------------
void weechat_string_free_split (char **split_string);
----------------------------------------

Argomenti:

* 'split_string': stringa divisa dalla funzione
  <<_weechat_string_split,weechat_string_split>>

Esempio in C:

[source,C]
----------------------------------------
char *argv;
int argc;
argv = weechat_string_split (string, " ", 0, 0, &argc);
/* ... */
weechat_string_free_split (argv);
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_string_build_with_split_string
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Compila una stringa con una stringa divisa.

Prototipo:

[source,C]
----------------------------------------
char *weechat_string_build_with_split_string (char **split_string,
                                              const char *separator);
----------------------------------------

Argomenti:

* 'split_string': stringa divisa dalla funzione
  <<_weechat_string_split,weechat_string_split>>
* 'separator': stringa usata per separare le stringhe

Valore restituito:

* stringa compilata con la stringa divisa (deve essere liberata chiamando
  "free" dopo l'uso)

Esempio in C:

[source,C]
----------------------------------------
char **argv;
int argc;
argv = weechat_string_split ("abc def ghi", " ", 0, 0, &argc);
char *str = weechat_string_build_with_split_string (argv, ";");
/* str == "abc;def;ghi" */
/* ... */
free (str);
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_string_split_command
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Divide una lista di comandi separata da 'separator' (che può essere
omesso aggiungendo "\" nella stringa).

Prototipo:

[source,C]
----------------------------------------
char **weechat_string_split_command (const char *command, char separator);
----------------------------------------

Argomenti:

* 'command': comando da dividere
* 'separator': separatore

Valore restituito:

* array di stringhe, NULL in caso di problemi (deve essere liberata chiamando
  <<_weechat_free_split_command,weechat_free_split_command>> dopo l'uso)

Esempio in C:

[source,C]
----------------------------------------
char **argv = weechat_string_split_command ("/command1 arg;/command2", ';');
/* result: argv[0] == "/command1 arg"
           argv[1] == "/command2"
*/
weechat_free_split_command (argv);
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_string_free_split_command
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Libera la memoria utilizzata dalla divisione di un comando.

Prototipo:

[source,C]
----------------------------------------
void weechat_string_free_split_command (char **split_command);
----------------------------------------

Argomenti:

* 'split_command': comando diviso da
  <<_weechat_string_split_command,weechat_string_split_command>>

Esempio in C:

[source,C]
----------------------------------------
char **argv = weechat_string_split_command ("/command1 arg;/command2", ';');
/* ... */
weechat_free_split_command (argv);
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_string_format_size
^^^^^^^^^^^^^^^^^^^^^^^^^^

Compila una stringa con un file di dimensione fissa ed una unità
tradotta nella lingua locale.

Prototipo:

[source,C]
----------------------------------------
char *weechat_string_format_size (unsigned long size);
----------------------------------------

Argomenti:

* 'size': dimensione (in byte)

Valore restituito:

* stringa formattata (deve essere liberata chiamando "free" dopo l'uso)

Esempi in C:

[source,C]
----------------------------------------
/* esempi in lingua inglese */

char *str = weechat_string_format_size (0); /* str == "0 byte" */
/* ... */
free (str);

char *str = weechat_string_format_size (200); /* str == "200 bytes" */
/* ... */
free (str);

char *str = weechat_string_format_size (1536); /* str == "1.5 KB" */
/* ... */
free (str);

char *str = weechat_string_format_size (2097152); /* str == "2 MB" */
/* ... */
free (str);
----------------------------------------

weechat_string_remove_color
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Rimuove i colori di WeeChat da una stringa.

Prototipo:

[source,C]
----------------------------------------
char *weechat_string_remove_color (const char *string,
                                   const char *replacement);
----------------------------------------

Argomenti:

* 'string': stringa
* 'replacement': se non NULL e non vuota, i codici colore di WeeChat sono
  sostituiti dal primo carattere di questa stringa, altrimenti i codici colori di
  WeeChat ed i caratteri seguenti (se correlate al colore) sono rimossi dalla
  stringa

Valore restituito:

* stringa senza un colore (deve essere liberata chiamando "free" dopo l'uso)

Esempi:

[source,C]
----------------------------------------
/* rimuove i codici colore */
char *str = weechat_string_remove_color (my_string1, NULL);
/* ... */
free (str);

/* sostituisce i codici colore con "?" */
char *str = weechat_string_remove_color (my_string2, "?");
/* ... */
free (str);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
str = weechat.string_remove_color(string, replacement)

# esempio
str = weechat.string_remove_color(my_string, "?")
----------------------------------------

weechat_string_encode_base64
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.2._

Codifica una stringa in base64.

Prototype:

[source,C]
----------------------------------------
void weechat_string_encode_base64 (const char *from, int length, char *to);
----------------------------------------

Argomenti:

* 'from': stringa da codificare
* 'length': lunghezza della stringa da codificare (ad esempio `strlen(from)`)
* 'to': puntatore alla stringa per memorizzare il risultato (deve essere
  sufficientemente lunga, il risultato è più lungo della stringa iniziale)

Esempio in C:

[source,C]
----------------------------------------
char *string = "abcdefgh", result[128];
weechat_string_encode_base64 (string, strlen (string), result);
/* result == "YWJjZGVmZ2g=" */
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_string_decode_base64
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.2._

Decodifica una stringa in base64.

Prototipo:

[source,C]
----------------------------------------
int weechat_string_decode_base64 (const char *from, char *to);
----------------------------------------

Argomenti:

* 'from': stringa da decodificare
* 'to': puntatore alla stringa per memorizzare il risultato (deve essere
  sufficientemente lunga, il risultato è più lungo della stringa iniziale)

Valore restituito:

* lunghezza della stringa memorizzata in *to (lo '\0' finale non conta)

Esempio in C:

[source,C]
----------------------------------------
char *string = "YWJjZGVmZ2g=", result[128];
int length;
length = weechat_string_decode_base64 (string, result);
/* length == 8, result == "abcdefgh" */
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_string_is_command_char
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.2._

Verifica che il primo carattere della stringa sia un carattere comando
(il comando carattere predefinito è '/').

Prototype:

[source,C]
----------------------------------------
int weechat_string_is_command_char (const char *string);
----------------------------------------

Argomenti:

* 'string': stringa

Valore restituito:

* 1 se il primo carattere della stringa è un comando carattere,
  altrimenti 0

Esempi in C:

[source,C]
----------------------------------------
int command_char1 = weechat_string_is_command_char ("/test"); /* == 1 */
int command_char2 = weechat_string_is_command_char ("test");  /* == 0 */
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
is_cmdchar = weechat.string_is_command_char(string)

# esempi
command_char1 = weechat.string_is_command_char("/test") # == 1
command_char2 = weechat.string_is_command_char("test")  # == 0
----------------------------------------

weechat_string_input_for_buffer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.2._

Restituisce il puntatore al testo in input per il buffer (puntatore all'interno
dell'argomento "string"), oppure NULL se è un comando.

Prototype:

[source,C]
----------------------------------------
const char *weechat_string_input_for_buffer (const char *string);
----------------------------------------

Argomenti:

* 'string': stringa

Valore restituito:

* puntatore all'interno di "string", oppure NULL

Esempi in C:

[source,C]
----------------------------------------
const char *str1 = weechat_string_input_for_buffer ("test");   /* "test"  */
const char *str2 = weechat_string_input_for_buffer ("/test");  /* NULL    */
const char *str3 = weechat_string_input_for_buffer ("//test"); /* "/test" */
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
str = weechat.string_input_for_buffer(string)

# esempi
str1 = weechat.string_input_for_buffer("test")   # "test"
str2 = weechat.string_input_for_buffer("/test")  # ""
str3 = weechat.string_input_for_buffer("//test") # "/test"
----------------------------------------

[[utf-8]]
UTF-8
~~~~~

Alcune funzioni stringa UTF-8.

weechat_utf8_has_8bits
^^^^^^^^^^^^^^^^^^^^^^

Verifica che una stringa abbia caratteri a 8-bit.

Prototipo:

[source,C]
----------------------------------------
int weechat_utf8_has_8bits (const char *string);
----------------------------------------

Argomenti:

* 'string': stringa

Valore restituito:

* 1 se la stringa ha caratteri a 8-bit, 0 se solo a 7-bit

Esempio in C:

[source,C]
----------------------------------------
if (weechat_utf8_has_8bits (string))
{
    /* ... */
}
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_utf8_is_valid
^^^^^^^^^^^^^^^^^^^^^

Verifica che una stringa sia valida in UTF-8.

Prototipo:

[source,C]
----------------------------------------
int weechat_utf8_is_valid (const char *string, char **error);
----------------------------------------

Argomenti:

* 'string': stringa
* 'error': se non NULL, '*error*' è impostato con il puntatore al primo
  carattere UTF-8 non valido nella stringa, se esiste

Valore restituito:

* 1 se la stringa UTF-8 è valida, altrimenti 0

Esempio in C:

[source,C]
----------------------------------------
char *error;
if (weechat_utf8_is_valid (string, &error))
{
    /* ... */
}
else
{
    /* "error" punta al primo carattere non valido */
}
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_utf8_normalize
^^^^^^^^^^^^^^^^^^^^^^

Normalizza le stringhe UTF-8: rimuove i caratteri non UTF-8 e li sostituisce con
un carattere.

Prototipo:

[source,C]
----------------------------------------
void weechat_utf8_normalize (const char *string, char replacement);
----------------------------------------

Argomenti:

* 'string': stringa
* 'replacement': carattere sotitutivo per i caratteri non validi

Esempio in C:

[source,C]
----------------------------------------
weechat_utf8_normalize (string, '?');
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_utf8_prev_char
^^^^^^^^^^^^^^^^^^^^^^

Restituisce il puntatore al carattere UTF-8 precedente in una stringa.

Prototipo:

[source,C]
----------------------------------------
char *weechat_utf8_prev_char (const char *string_start, const char *string);
----------------------------------------

Argomenti:

* 'string_start': inizio della stringa (la funzione non restituirà un carattere prima
  di questo puntatore)
* 'string': puntatore alla stringa (deve essere > = 'string_start')

Valore restituito:

* puntatore al precedente carattere UTF-8, NULL se non trovata (raggiunta
  l'inizio della stringa)

Esempio in C:

[source,C]
----------------------------------------
char *prev_char = weechat_utf8_prev_char (string, ptr_in_string);
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_utf8_next_char
^^^^^^^^^^^^^^^^^^^^^^

Restituisce il puntatore al successivo carattere UTF-8 in una stringa.

Prototipo:

[source,C]
----------------------------------------
char *weechat_utf8_next_char (const char *string);
----------------------------------------

Argomenti:

* 'string': stringa

Valore restituito:

* puntatore al carattere UTF-8 successivo, NULL se non trovato
  (raggiunta la fine della stringa)

Esempio in C:

[source,C]
----------------------------------------
char *next_char = weechat_utf8_next_char (string);
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_utf8_char_int
^^^^^^^^^^^^^^^^^^^^^

Restituisce un carattere UTF-8 come intero.

Prototipo:

[source,C]
----------------------------------------
int weechat_utf8_char_int (const char *string);
----------------------------------------

Argomenti:

* 'string': stringa

Valore restituito:

* carattere UTF-8 come intero

Esempio in C:

[source,C]
----------------------------------------
int char_int = weechat_utf8_char_int ("être"); /* "ê" come intero */
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_utf8_char_size
^^^^^^^^^^^^^^^^^^^^^^

Restituisce la dimensione di un carattere UTF-8 (in byte).

Prototipo:

[source,C]
----------------------------------------
int weechat_utf8_char_size (const char *string);
----------------------------------------

Argomenti:

* 'string': stringa

Valore restituito:

* dimensione carattere UTF-8 (in byte)

Esempio in C:

[source,C]
----------------------------------------
int char_size = weechat_utf8_char_size ("être"); /* == 2 */
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_utf8_strlen
^^^^^^^^^^^^^^^^^^^

Restituisce la lunghezza della stringa UTF-8 (nei caratteri UTF-8).

Prototipo:

[source,C]
----------------------------------------
int weechat_utf8_strlen (const char *string);
----------------------------------------

Argomenti:

* 'string': stringa

Valore restituito:

* lunghezza della stringa UTF-8 (numero di caratteri UTF-8)

Esempio in C:

[source,C]
----------------------------------------
int length = weechat_utf8_strlen ("chêne"); /* == 5 */
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_utf8_strnlen
^^^^^^^^^^^^^^^^^^^^

Restituisce la lunghezza della stringa UTF-8 (in caratteri UTF-8), per
un massimo di 'bytes' nella stringa.

Prototipo:

[source,C]
----------------------------------------
int weechat_utf8_strnlen (const char *string, int bytes);
----------------------------------------

Argomenti:

* 'string': stringa
* 'bytes': massimo di byte

Valore restituito:

* lunghezza della stringa UTF-8 (numero di caratteri UTF-8)

Esempio in C:

[source,C]
----------------------------------------
int length = weechat_utf8_strnlen ("chêne", 4); /* == 3 */
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_utf8_strlen_screen
^^^^^^^^^^^^^^^^^^^^^^^^^^

Restituisce il numero di caratteri necessari per visualizzare la stringa
UTF-8 su schermo.

Prototipo:

[source,C]
----------------------------------------
int weechat_utf8_strlen_screen (const char *string);
----------------------------------------

Argomenti:

* 'string': stringa

Valore restituito:

* numero di caratteri necessari per visualizzare la stringa UTF-8
su schermo

Esempio in C:

[source,C]
----------------------------------------
int length_on_screen = weechat_utf8_strlen_screen ("é"); /* == 1 */
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_utf8_charcmp
^^^^^^^^^^^^^^^^^^^^

Confronta due caratteri UTF-8.

Prototipo:

[source,C]
----------------------------------------
int weechat_utf8_charcmp (const char *string1, const char *string2);
----------------------------------------

Argomenti:

* 'string1': prima stringa da comparare
* 'string2': seconda stringa da comparare

Valore restituito:

* differenza tra i primi caratteri di ogni stringa:
** negativa se char1 < char2
** zero se char1 == char2
** positivao se char1 > char2

Esempio in C:

[source,C]
----------------------------------------
int diff = weechat_utf8_charcmp ("aaa", "ccc"); /* == -2 */
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_utf8_charcasecmp
^^^^^^^^^^^^^^^^^^^^^^^^

Confronta due caratteri UTF-8, ignorando maiuscole/minuscole.

Prototipo:

[source,C]
----------------------------------------
int weechat_utf8_charcasecmp (const char *string1, const char *string2);
----------------------------------------

Argomenti:

* 'string1': prima stringa da comparare
* 'string2': seconda stringa da comparare

Valore restituito:

* differenza tra i primi caratteri di ogni stringa:
** negativa se char1 < char2
** zero se char1 == char2
** positivao se char1 > char2

Esempio in C:

[source,C]
----------------------------------------
int diff = weechat_utf8_charcasecmp ("aaa", "CCC"); /* == -2 */
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_utf8_char_size_screen
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Restituisce il numero di caratteri necessari per visualizzare il
carattere UTF-8 sullo schermo.

Prototipo:

[source,C]
----------------------------------------
int weechat_utf8_char_size_screen (const char *string);
----------------------------------------

Argomenti:

* 'string': stringa

Valore restituito:

* numero di caratteri necessario per visualizzare il carattere
  UTF-8 su schermo

Esempio in C:

[source,C]
----------------------------------------
int length_on_screen = weechat_utf8_char_size_screen ("é"); /* == 1 */
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_utf8_add_offset
^^^^^^^^^^^^^^^^^^^^^^^

Si sposta in avanti di N caratteri in una stringa UTF-8.

Prototipo:

[source,C]
----------------------------------------
char *weechat_utf8_add_offset (const char *string, int offset);
----------------------------------------

Argomenti:

* 'string': stringa
* 'offset': numero di caratteri

Valore restituito:

* puntatore alla stringa, N caratteri dopo (NULL se non raggiungibile)

Esempio in C:

[source,C]
----------------------------------------
char *str = "chêne";
char *str2 = weechat_utf8_add_offset (str, 3); /* points to "ne" */
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_utf8_real_pos
^^^^^^^^^^^^^^^^^^^^^

Restituisce la posizione reale nella stringa UTF-8.

Prototipo:

[source,C]
----------------------------------------
int weechat_utf8_real_pos (const char *string, int pos);
----------------------------------------

Argomenti:

* 'string': stringa
* 'pos': posizione (numero di caratteri)

Valore restituito:

* pozisione reale (in byte)

Esempio in C:

[source,C]
----------------------------------------
int pos = weechat_utf8_real_pos ("chêne", 3); /* == 4 */
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_utf8_pos
^^^^^^^^^^^^^^^^

Restituisce la posizione nella stringa UTF-8.

Prototipo:

[source,C]
----------------------------------------
int weechat_utf8_pos (const char *string, int real_pos);
----------------------------------------

Argomenti:

* 'string': stringa
* 'real_pos': posizione (byte)

Valore restituito:

* posizione (numero di caratteri)

Esempio in C:

[source,C]
----------------------------------------
int pos = weechat_utf8_pos ("chêne", 4); /* == 3 */
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_utf8_strndup
^^^^^^^^^^^^^^^^^^^^

Restituisce la stringa duplicata, di lunghezza massima 'lenght'.

Prototipo:

[source,C]
----------------------------------------
char *weechat_utf8_strndup (const char *string, int length);
----------------------------------------

Argomenti:

* 'string': stringa
* 'length': caratteri massimi da duplicare

Valore restituito:

* stringa duplicata (deve essere liberata chiamando "free" dopo l'uso)

Esempio in C:

[source,C]
----------------------------------------
char *string = weechat_utf8_strndup ("chêne", 3); /* restituisce "chê" */
/* ... */
free (string);
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

[[directories]]
Cartelle
~~~~~~~~

Alcune funzioni legate alle cartelle.

weechat_mkdir_home
^^^^^^^^^^^^^^^^^^

Crea una cartella nella home di WeeChat.

Prototipo:

[source,C]
----------------------------------------
int weechat_mkdir_home (char *directory, int mode);
----------------------------------------

Argomenti:

* 'directory': nome della cartella da creare
* 'mode': modalità per la cartella

Valore restituito:

* 1 se la cartella è stata creata con successo, 0 in caso di errore

Esempio in C:

[source,C]
----------------------------------------
if (!weechat_mkdir_home ("temp", 0755))
{
    /* errore */
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.mkdir_home(directory, mode)

# esempio
weechat.mkdir_home("temp", 0755)
----------------------------------------

weechat_mkdir
^^^^^^^^^^^^^

Crea una cartella.

Prototipo:

[source,C]
----------------------------------------
int weechat_mkdir (char *directory, int mode);
----------------------------------------

Argomenti:

* 'directory': nome della cartella da creare
* 'mode': modalità per la cartella

Valore restituito:

* 1 se la cartella è stata creata con successo, 0 in caso di errore

Esempio in C:

[source,C]
----------------------------------------
if (!weechat_mkdir ("/tmp/mydir", 0755))
{
    /* errore */
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.mkdir(directory, mode)

# esempio
weechat.mkdir("/tmp/mydir", 0755)
----------------------------------------

weechat_mkdir_parents
^^^^^^^^^^^^^^^^^^^^^

Crea una cartella e le cartelle genitore se necessario.

Prototipo:

[source,C]
----------------------------------------
int weechat_mkdir_parents (char *directory, int mode);
----------------------------------------

Argomenti:

* 'directory': nome della cartella da creare
* 'mode': modalità per la cartella

Valore restituito:

* 1 se la cartella è stata creata con successo, 0 in caso di errore

Esempio in C:

[source,C]
----------------------------------------
if (!weechat_mkdir_parents ("/tmp/my/dir", 0755))
{
    /* errore */
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.mkdir_parents(directory, mode)

# esempio
weechat.mkdir_parents("/tmp/my/dir", 0755)
----------------------------------------

weechat_exec_on_files
^^^^^^^^^^^^^^^^^^^^^

Cerca i file in una cartella ed esegue una callback su ogni file.

Prototipo:

[source,C]
----------------------------------------
void weechat_exec_on_files (const char *directory,
                            int hidden_files,
                            void *data,
                            void (*callback)(void *data,
                                             const char *filename));
----------------------------------------

Argomenti:

* 'directory': cartella in cui cercare i file
* 'hidden_files': 1 per includere i file nascosti, altrimenti 0
* 'data': puntatore fornito al callback quando chiamato da WeeChat
* 'callback': funzione chiamata per ogni file trovato, argomenti:
** 'void *data': puntatore
** 'const char *filename': nome file trovato

Esempio in C:

[source,C]
----------------------------------------
void callback (void *data, const char *filename)
{
    /* ... */
}
...
weechat_exec_on_files ("/tmp", 0, NULL, &callback);
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_file_get_content
^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.1._

Ottiene il contenuto del file di testo in una stringa.

Prototipo:

[source,C]
----------------------------------------
char *weechat_file_get_content (const char *filename);
----------------------------------------

Argomenti:

* 'filename': percorso e nome file

Valore restituito:

* contenuto del file come stringa (deve essere liberata chiamando "free dopo
  l'uso)

Esempio in C:

[source,C]
----------------------------------------
char *content;

content = weechat_file_get_content ("/tmp/test.txt");
/* ... */
free (content);
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

[[util]]
Utilità
~~~~~~~

Alcune funzioni utili.

weechat_util_timeval_cmp
^^^^^^^^^^^^^^^^^^^^^^^^

Confronta due strutture "timeval".

Prototipo:

[source,C]
----------------------------------------
int weechat_util_timeval_cmp (struct timeval *tv1, struct timeval *tv2);
----------------------------------------

Argomenti:

* 'tv1': prima struttura "timeval"
* 'tv2': seconda struttura "timeval"

Valore restituito:

* -1 se tv1 < tv2
* zero se tv1 == tv2
* +1 se tv1 > tv2

Esempio in C:

[source,C]
----------------------------------------
if (weechat_util_timeval_cmp (&tv1, &tv2) > 0)
{
    /* tv1 > tv2 */
}
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_util_timeval_diff
^^^^^^^^^^^^^^^^^^^^^^^^^

Restituisce la differenza (in millisecondi) tra due strutture "timeval".

Prototipo:

[source,C]
----------------------------------------
long weechat_util_timeval_diff (struct timeval *tv1, struct timeval *tv2);
----------------------------------------

Argomenti:

* 'tv1': prima struttura "timeval"
* 'tv2': seconda struttura "timeval"

Valore restituito:

* differenza in millisecondi

Esempio in C:

[source,C]
----------------------------------------
long diff = weechat_util_timeval_diff (&tv1, &tv2);
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_util_timeval_add
^^^^^^^^^^^^^^^^^^^^^^^^

Aggiungi intervallo (in millisecondi) ad una struttura timeval.

Prototipo:

[source,C]
----------------------------------------
void weechat_util_timeval_add (struct timeval *tv, long interval);
----------------------------------------

Argomenti:

* 'tv': struttura timeval
* 'interval': intervallo (in millisecondi)

Esempio in C:

[source,C]
----------------------------------------
weechat_util_timeval_add (&tv, 2000); /* aggiunge 2 secondi */
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_util_get_time_string
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.2._

Riceve data/ora come stringa compilata con "strftime".

Prototipo:

[source,C]
----------------------------------------
char *weechat_util_get_time_string (const time_t *date);
----------------------------------------

Argomenti:

* 'date': puntatore alla data

Esempio in C:

[source,C]
----------------------------------------
time_t date = time (NULL);
weechat_printf (NULL, "date: %s",
                weechat_util_get_time_string (&date));
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

[[sorted_lists]]
Elenchi ordinati
~~~~~~~~~~~~~~~~

Funzioni lista ordinata.

weechat_list_new
^^^^^^^^^^^^^^^^

Crea una nuova lista.

Prototipo:

[source,C]
----------------------------------------
struct t_weelist *weechat_list_new ();
----------------------------------------

Valore restituito:

* puntatore alla nuova lista

Esempio in C:

[source,C]
----------------------------------------
struct t_weelist *list = weechat_list_new ();
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
list = weechat.list_new()

# esempio
list = weechat.list_new()
----------------------------------------

weechat_list_add
^^^^^^^^^^^^^^^^

Aggiunge un elemento in una lista.

Prototipo:

[source,C]
----------------------------------------
struct t_weelist_item *weechat_list_add (struct t_weelist *weelist,
                                         const char *data,
                                         const char *where,
                                         void *user_data);
----------------------------------------

Argomenti:

* 'weelist': puntatore alla lista
* 'data': dati da inserire nella lista
* 'where': posizione nella lista:
** 'WEECHAT_LIST_POS_SORT': aggiunge alla lista, mantenendola ordinata
** 'WEECHAT_LIST_POS_BEGINNING': aggiunge all'inizio della lista
** 'WEECHAT_LIST_POS_END': aggiunge alla fine della lista
* 'user_data': qualsiasi puntatore

Valore restituito:

* puntatore al nuovo elemento

Esempio in C:

[source,C]
----------------------------------------
struct t_weelist_item *my_item =
    weechat_list_add (list, "my data", WEECHAT_LIST_POS_SORT, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
item = weechat.list_add(list, data, where, user_data)

# esempio
item = weechat.list_add(list, "my data", weechat.WEECHAT_LIST_POS_SORT, "")
----------------------------------------

weechat_list_search
^^^^^^^^^^^^^^^^^^^

Cerca un elemento nella lista.

Prototipo:

[source,C]
----------------------------------------
struct t_weelist_item *weechat_list_search (struct t_weelist *weelist,
                                            const char *data);
----------------------------------------

Argomenti:

* 'weelist': puntatore alla lista
* 'data': dati da cercare nella lista

Valore restituito:

* puntatore all'elemento trovato, NULL se non trovato

Esempio in C:

[source,C]
----------------------------------------
struct t_weelist_item *item = weechat_list_search (list, "my data");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
item = weechat.list_search(list, data)

# esempio
item = weechat.list_search(list, "my data")
----------------------------------------

weechat_list_casesearch
^^^^^^^^^^^^^^^^^^^^^^^

Cerca un elemento nella lista, senza effettuare una ricerca
esatta.

Prototipo:

[source,C]
----------------------------------------
struct t_weelist_item *weechat_list_casesearch (struct t_weelist *weelist,
                                                const char *data);
----------------------------------------

Argomenti:

* 'weelist': puntatore alla lista
* 'data': dati da cercare nella lista

Valore restituito:

* puntatore all'elemento trovato, NULL se non trovato

Esempio in C:

[source,C]
----------------------------------------
struct t_weelist_item *item = weechat_list_casesearch (list, "my data");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
item = weechat.list_casesearch(list, data)

# esempio
item = weechat.list_casesearch(list, "my data")
----------------------------------------

weechat_list_get
^^^^^^^^^^^^^^^^

Restituisce un elemento in una lista in base alla sua posizione.

Prototipo:

[source,C]
----------------------------------------
struct t_weelist_item *weechat_list_get (struct t_weelist *weelist,
                                         int position);
----------------------------------------

Argomenti:

* 'weelist': puntatore alla lista
* 'position': posizione nella lista (il primo elemento è 0)

Valore restituito:

* puntatore all'elemento trovato, NULL se non trovato

Esempio in C:

[source,C]
----------------------------------------
struct t_weelist_item *item = weechat_list_get (list, 0); /* primo elemento */
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
item = weechat.list_get(list, position)

# esempio
item = weechat.list_get(list, 0)
----------------------------------------

weechat_list_set
^^^^^^^^^^^^^^^^

Imposta un nuovo valore per un elemento.

Prototipo:

[source,C]
----------------------------------------
void weechat_list_set (struct t_weelist_item *item, const char *value);
----------------------------------------

Argomenti:

* 'item': puntatore all'elemento
* 'value': nuovo valore per l'elemento

Esempio in C:

[source,C]
----------------------------------------
weechat_list_set (item, "nuovi dati");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.list_set(item, value)

# esempio
weechat.list_set(item, "nuovi dati")
----------------------------------------

weechat_list_next
^^^^^^^^^^^^^^^^^

Restituisce l'elemento successivo nella lista.

Prototipo:

[source,C]
----------------------------------------
struct t_weelist_item *weechat_list_next (struct t_weelist_item *item);
----------------------------------------

Argomenti:

* 'item': puntatore all'elemento

Valore restituito:

* puntatore all'elemento successivo, NULL se il puntatore è
  l'ultimo oggetto nella lista

Esempio in C:

[source,C]
----------------------------------------
struct t_weelist_item *next_item = weechat_list_next (item);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
item = weechat.list_next(item)

# esempio
item = weechat.list_next(item)
----------------------------------------

weechat_list_prev
^^^^^^^^^^^^^^^^^

Restituisce l'elemento precedente nella lista.

Prototipo:

[source,C]
----------------------------------------
struct t_weelist_item *weechat_list_prev (struct t_weelist_item *item);
----------------------------------------

Argomenti:

* 'item': puntatore all'elemento

Valore restituito:

* puntatore all'elemento precedente, NULL se il puntatore è
  l'ultimo elemento nella lista

Esempio in C:

[source,C]
----------------------------------------
struct t_weelist_item *prev_item = weechat_list_prev (item);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
item = weechat.list_prev(item)

# esempio
item = weechat.list_prev(item)
----------------------------------------

weechat_list_string
^^^^^^^^^^^^^^^^^^^

Restituisce il valore stringa di un elemento.

Prototipo:

[source,C]
----------------------------------------
const char *weechat_list_string (struct t_weelist_item *item);
----------------------------------------

Argomenti:

* 'item': puntatore all'elemento

Valore restituito:

* valore stringa di un elemento

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL, "valore dell'elemento: %s", weechat_list_string (item));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.list_string(item)

# esempio
weechat.prnt("", "valore dell'elemento: %s" % weechat.list_string(item))
----------------------------------------

weechat_list_size
^^^^^^^^^^^^^^^^^

Restituisce la dimensione della lista (numero di elementi).

Prototipo:

[source,C]
----------------------------------------
char *weechat_list_size (struct t_weelist *weelist);
----------------------------------------

Argomenti:

* 'weelist': puntatore alla lista

Valore restituito:

* dimensione della lista (numero di elementi), 0 se la lista
  è vuota

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL, "dimensione della lista: %d", weechat_list_size (list));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
size = weechat.list_size(list)

# esempio
weechat.prnt("", "dimensione della lista: %d" % weechat.list_size(list))
----------------------------------------

weechat_list_remove
^^^^^^^^^^^^^^^^^^^

Rimuove un elemento in una lista.

Prototipo:

[source,C]
----------------------------------------
void weechat_list_remove (struct t_weelist *weelist,
                          struct t_weelist_item *item);
----------------------------------------

Argomenti:

* 'weelist': puntatore alla lista
* 'item': puntatore all'elemento

Esempio in C:

[source,C]
----------------------------------------
weechat_list_remove (list, item);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.list_remove(list, item)

# esempio
weechat.list_remove(list, item)
----------------------------------------

weechat_list_remove_all
^^^^^^^^^^^^^^^^^^^^^^^

Rimuove tutti gli elementi in una lista.

Prototipo:

[source,C]
----------------------------------------
void weechat_list_remove_all (struct t_weelist *weelist);
----------------------------------------

Argomenti:

* 'weelist': puntatore alla lista

Esempio in C:

[source,C]
----------------------------------------
weechat_list_remove_all (list);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.list_remove_all(list)

# esempio
weechat.list_remove_all(list)
----------------------------------------

weechat_list_free
^^^^^^^^^^^^^^^^^

Libera una lista.

Prototipo:

[source,C]
----------------------------------------
void weechat_list_free (struct t_weelist *weelist);
----------------------------------------

Argomenti:

* 'weelist': puntatore alla lista

Esempio in C:

[source,C]
----------------------------------------
weechat_list_free (list);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.list_free(list)

# esempio
weechat.list_free(list)
----------------------------------------

[[hashtables]]
Tabelle hash
~~~~~~~~~~~~

Funzioni per le tabelle hash.

weechat_hashtable_new
^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.3._

Crea una nuova tabella hash.

Prototipo:

[source,C]
----------------------------------------
struct t_hashtable *weechat_hashtable_new (int size,
                                           const char *type_keys,
                                           const char *type_values,
                                           unsigned int (*callback_hash_key)(struct t_hashtable *hashtable,
                                                                             const void *key),
                                           int (*callback_keycmp)(struct t_hashtable *hashtable,
                                                                  const void *key1,
                                                                  const void *key2));
----------------------------------------

Arguments:

* 'size': dimensione dell'array interno per memorizzare le chiavi con hash, un
  valore più alto usa più memoria, ma ha migliori performance. (questo *non* è
  un limite per il numero di elementi nella tabella hash)
* 'type_keys': tipo per le chiavi nella tabella hash:
** 'WEECHAT_HASHTABLE_INTEGER'
** 'WEECHAT_HASHTABLE_STRING'
** 'WEECHAT_HASHTABLE_POINTER'
** 'WEECHAT_HASHTABLE_BUFFER'
** 'WEECHAT_HASHTABLE_TIME'
* 'type_values': tipo per i valori nella tabella hash:
** 'WEECHAT_HASHTABLE_INTEGER'
** 'WEECHAT_HASHTABLE_STRING'
** 'WEECHAT_HASHTABLE_POINTER'
** 'WEECHAT_HASHTABLE_BUFFER'
** 'WEECHAT_HASHTABLE_TIME'
* 'callback_hash_key': callback utilizzata per effettuare un "hash" di una
  chiave (chiave come valore intero), può essere NULL se il tipo della chiave è
  "string" (viene usata una funzione predefinita per le stringhe, e solo per le
  stringhe)
* 'callback_keycmp': callback utilizzata per comparare due chiavi, può essere
  NULL se il tipo di valore è "string" (una funzione di confronto predefinita è
  usata per le stringhe e solo per le stringhe)

Valore restituito:

* puntatore alla nuova tabella hash, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       NULL,
                                                       NULL);
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_hashtable_set_with_size
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.3._

Aggiunge o aggiorna un elemento nella tabella hash con la dimensione per la
chiave ed il valore.

Prototipo:

[source,C]
----------------------------------------
int weechat_hashtable_set_with_size (struct t_hashtable *hashtable,
                                     const void *key, int key_size,
                                     const void *value, int value_size);
----------------------------------------

Arguments:

* 'hashtable': puntatore alla tabella hash
* 'key': puntatore alla chiave
* 'key_size': dimensione della chiave (in byte), usata solo se il tipo delle
   chiavi nella tabella hash è "buffer"
* 'value': puntatore al valore
* 'value_size': dimensione del valore (in byte), utilizzata solo se il tipo dei
   valori nella tabella è "buffer"

Valore restituito:

* 1 se ok, 0 in caso di errore

Esempio in C:

[source,C]
----------------------------------------
weechat_hashtable_set_with_size (hashtable, "my_key", 0,
                                 my_buffer, sizeof (my_buffer_struct));
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_hashtable_set
^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.3._

Aggiunge o aggiorna un elemento nella tabella hash.

Prototipo:

[source,C]
----------------------------------------
int weechat_hashtable_set (struct t_hashtable *hashtable,
                           const void *key, const void *value);
----------------------------------------

Argomenti:

* 'hashtable': puntatore alla tabella hash
* 'key': puntatore alla chiave
* 'value': puntatore al valore

Valore restituito:

* 1 se ok, 0 in caso di errore

Esempio in C:

[source,C]
----------------------------------------
weechat_hashtable_set (hashtable, "my_key", "my_value");
----------------------------------------

weechat_hashtable_get
^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.3._

Ottiene il valore associato ad una chiave in una tabella hash.

Prototipo:

[source,C]
----------------------------------------
void *weechat_hashtable_get (struct t_hashtable *hashtable, void *key);
----------------------------------------

Argomenti:

* 'hashtable': puntatore alla tabella hash
* 'key': puntatore alla chiave

Valore restituito:

* valore per la chiave, NULL se non trovata

Esempio in C:

[source,C]
----------------------------------------
void *value = weechat_hashtable_get (hashtable, "my_key");
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_hashtable_has_key
^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.4._

Restituisce 1 se la tabella hash ha una chiave, altrimenti 0.

Prototipo:

[source,C]
----------------------------------------
int weechat_hashtable_has_key (struct t_hashtable *hashtable, void *key);
----------------------------------------

Argomenti:

* 'hashtable': puntatore alla tabella hash
* 'key': puntatore alla chiave

Valore restituito:

* 1 se la chiave si trova nella tabella hash, 0 in caso contrario

Esempio in C:

[source,C]
----------------------------------------
if (weechat_hashtable_has_key (hashtable, "my_key"))
{
    /* la chiave è nella tabella hash */
    /* ... */
}
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_hashtable_map
^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.3._

Chiama una funzione su tutte le voci della tabella hash.

Prototipo:

[source,C]
----------------------------------------
void hashtable_map (struct t_hashlist *hashlist,
                    int (*callback_map)(void *data,
                                        struct t_hashtable *hashtable,
                                        const void *key,
                                        const void *value),
                    void *callback_map_data);
----------------------------------------

Argomenti:

* 'hashtable': puntatore alla tabella hash
* 'callback_map': funzione chiamata per ogni voce nella tabella hash
* 'callback_map_data': puntatore fornito alla mappa di callback quando chiamata

Esempio in C:

[source,C]
----------------------------------------
void
map_cb (void *data, struct t_hashtable *hashtable,
        const void *key, const void *value)
{
    /* display key and value (they are both strings here) */
    weechat_printf (NULL, "key: '%s', value: '%s'",
                    (const char *)key,
                    (const char *)value);
}
/* ... */
weechat_hashtable_map (hashtable, &map_cb, NULL);
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_hashtable_get_integer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.3._

Restituisce un valore intero per la proprietà di una tabella hash.

Prototipo:

[source,C]
----------------------------------------
int weechat_hashtable_get_integer (struct t_hashtable *hashtable,
                                   void *property);
----------------------------------------

Argomenti:

* 'hashtable': puntatore alla tabella hash
* 'property': nome della proprietà:
** 'size': dimensione dell'array interno "htable" nella tabella hash
** 'items_count': numero di elementi nella tabella hash

Valore restituito:

* valore intero della proprietà

Esempio in C:

[source,C]
----------------------------------------
int items_count = weechat_hashtable_get_integer (hashtable, "items_count");
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_hashtable_get_string
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.4._

Restituisce il valore stringa della proprietà di una tabella hash.

Prototype:

[source,C]
----------------------------------------
const char *weechat_hashtable_get_string (struct t_hashtable *hashtable,
                                          void *property);
----------------------------------------

Argomenti:

* 'hashtable': puntatore alla tabella hash
* 'property': nome della proprietà:
** 'type_keys': tipo per le chiavi:
*** 'integer': intero
*** 'string': stringa
*** 'pointer': puntatore
*** 'buffer': buffer
*** 'time': tempo
** 'type_values': tipo per i valori:
*** 'integer': intero
*** 'string': stringa
*** 'pointer': puntatore
*** 'buffer': buffer
*** 'time': tempo
** 'keys': stringa con la lista di chiavi (formato: "chiave1,chiave2,chiave3")
** 'values': stringa  con la lista di valori (formato: "valore1,valore2,valore3")
** 'keys_values': stringa con la lista di valori e chiavi
   (formato: "chiave1:valore1,chiave2:valore2,chiave3:valore3")

Valore restituito:

* valore stringa della proprietà

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL, "keys are type: %s",
                weechat_hashtable_get_string (hashtable, "type_keys"));
weechat_printf (NULL, "list of keys: %s",
                weechat_hashtable_get_string (hashtable, "keys"));
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_hashtable_add_to_infolist
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.3._

Aggiunge elementi della tabella hash ad un elemento della lista info.

Prototipo:

[source,C]
----------------------------------------
int weechat_hashtable_add_to_infolist (struct t_hashtable *hashtable,
                                       struct t_infolist_item *infolist_item,
                                       const char *prefix);
----------------------------------------

Argomenti:

* 'hashtable': puntatore alla tabella hash
* 'infolist_item': puntatore all'elemento della lista info
* 'prefix': stringa usata come prefisso per i nomi nella lista info

Valore restituito:

* 1 se ok, 0 in caso di errore

Esempio in C:

[source,C]
----------------------------------------
weechat_hashtable_add_to_infolist (hashtable, infolist_item, "testhash");

/* se la tabella hash contiene:
     "key1" => "value 1"
     "key2" => "value 2"
   allora le seguenti variabili verranno aggiunti all'elemento  della lista info:
     "testhash_name_00001"  = "key1"
     "testhash_value_00001" = "value 1"
     "testhash_name_00002"  = "key2"
     "testhash_value_00002" = "value 2"
*/
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_hashtable_remove
^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.3._

Rimuove un elemento in una tabella hash.

Prototipo:

[source,C]
----------------------------------------
void weechat_hashtable_remove (struct t_hashtable *hashtable, const void *key);
----------------------------------------

Argomenti:

* 'hashtable': puntatore alla tabella hash
* 'key': puntatore alla chiave

Esempio in C:

[source,C]
----------------------------------------
weechat_hashtable_remove (hashtable, "my_key");
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_hashtable_remove_all
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.3._

Rimuove tutti gli elementi in una tabella hash.

Prototipo:

[source,C]
----------------------------------------
void weechat_hashtable_remove_all (struct t_hashtable *hashtable);
----------------------------------------

Argomenti:

* 'hashtable': puntatore alla tabella hash

Esempio in C:

[source,C]
----------------------------------------
weechat_hashtable_remove_all (hashtable);
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_hashtable_free
^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.3._

Libera una tabella hash.

Prototipo:

[source,C]
----------------------------------------
void weechat_hashtable_free (struct t_hashtable *hashtable);
----------------------------------------

Argomenti:

* 'hashtable': puntatore alla tabella hash

Esempio in C:

[source,C]
----------------------------------------
weechat_hashtable_free (hashtable);
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

[[configuration_files]]
File di configurazione
~~~~~~~~~~~~~~~~~~~~~~

Funzioni per i file di configurazione.

weechat_config_new
^^^^^^^^^^^^^^^^^^

Crea un nuovo file di configurazione.

Prototipo:

[source,C]
----------------------------------------
struct t_config_file *weechat_config_new (const char *name,
                                          int (*callback_reload)(void *data,
                                                                 struct t_config_file *config_file),
                                          void *callback_reload_data);
----------------------------------------

Argomenti:

* 'name': nome del file di configurazione (senza percorso o estensione)
* 'callback_reload': funzione chiamata quando il file di configurazione viene
  ricaricato con `/reload` (opzionale, può essere NULL), argomenti:
** 'void *data': puntatore
** 'struct t_config_file *config_file': puntatore al file di configurazione
* 'callback_reload_data': puntatore fornito per ricaricare il callback
  quando richiesto da WeeChat

Valore restituito:

* puntatore al nuovo file di configurazione, NULL in caso di errore

[NOTE]
Il file NON viene creato su disco da questa funzione. Verrà creato chiamando
la funzione <<_weechat_write_config,weechat_write_config>>.
Si dovrebbe chiamare questa funzione solo dopo aver aggiunto alcune sezioni
(con <<_weechat_config_new_section,weechat_config_new_section>>) e le
opzioni (con <<_weechat_config_new_option,weechat_config_new_option>>).

Esempio in C:

[source,C]
----------------------------------------
int
my_config_reload_cb (void *data, struct t_config_file *config_file)
{
    /* ... */
    
    return WEECHAT_RC_OK;
}

struct t_config_file *config_file = weechat_config_new ("test",
                                                        &my_config_reload_cb,
                                                        NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
config_file = weechat.config_new(name, calback_reload, callback_reload_data)

# esempio
def my_config_reload_cb(data, config_file):
    # ...
    return weechat.WEECHAT_RC_OK

config_file = weechat.config_new("test", "my_config_reload_cb", "")
----------------------------------------

weechat_config_new_section
^^^^^^^^^^^^^^^^^^^^^^^^^^

Crea una nuova sezione nel file di configurazione.

Prototipo:

[source,C]
----------------------------------------
struct t_config_section *weechat_config_new_section (
    struct t_config_file *config_file,
    const char *name,
    int user_can_add_options,
    int user_can_delete_options,
    int (*callback_read)(void *data,
                         struct t_config_file *config_file,
                         struct t_config_section *section,
                         const char *option_name,
                         const char *value),
    void *callback_read_data,
    int (*callback_write)(void *data,
                          struct t_config_file *config_file,
                          const char *section_name),
    void *callback_write_data,
    int (*callback_write_default)(void *data,
                                  struct t_config_file *config_file,
                                  const char *section_name);
    void *callback_write_default_data,
    int (*callback_create_option)(void *data,
                                  struct t_config_file *config_file,
                                  struct t_config_section *section,
                                  const char *option_name,
                                  const char *value),
    void *callback_create_option_data,
    int (*callback_delete_option)(void *data,
                                  struct t_config_file *config_file,
                                  struct t_config_section *section,
                                  struct t_config_option *option),
    void *callback_delete_option_data);
----------------------------------------

Argomenti:

* 'config_file': puntatore al file di configurazione
* 'name': nome della sezione
* 'user_can_add_options': 1 se l'utente può creare nuove opzioni nella sezione,
  oppure 0 se non gli è consentito
* 'user_can_delete_options': 1 se l'utente può eliminare le opzioni nella sezione,
  oppure 0 se non gli è consentito
* 'callback_read': funzione chiamata quando un'opzione nella sezione viene letta
  da disco (dovrebbe essere NULL in molti casi, tranne se l'opzione nella sezione
  necessita di una funzione personalizza), argomenti:
** 'void *data': puntatore
** 'struct t_config_file *config_file': puntatore al file di configurazione
** 'struct t_config_section *section': puntatore alla sezione
** 'const char *option_name': nome dell'opzione
** 'const char *value': valore
* 'callback_read_data': puntatore fornito al callback quando chiamato da WeeChat
* 'callback_write': funzione chiamata quando la sezione è scritta nel file (dovrebbe
  essere NULL in molti casi, tranne se la sezione necessita di una funzione
  personalizzata), argomenti:
** 'void *data': puntatore
** 'struct t_config_file *config_file': puntatore al file di configurazione
** 'struct t_config_section *section': puntatore alla sezione
** 'const char *option_name': nome dell'opzione
* callback_write_data: puntatore fornito al callback quando chiamato da WeeChat
* callback_write_default: funzione chiamata quando i valori predefiniti per la sezione
  devono essere scritti in un file, argomenti:
** 'void *data': puntatore
** 'struct t_config_file *config_file': puntatore al file di configurazione
** 'const char *section_name': nome della sezione
* 'callback_write_default_data': puntatore fornito al callback quando chiamato da
  WeeChat
* 'callback_create_option': funzione chiamata quando viene creata una nuova
  opzione nella sezione (NULL se la sezione non consente di creare nuove
  opzioni), argomenti:
** 'void *data': puntatore
** 'struct t_config_file *config_file': puntatore al file di configurazione
** 'struct t_config_section *section': puntatore alla sezione
** 'const char *option_name': nome dell'opzione
** 'const char *value': valore
* 'callback_create_option_data': puntatore fornito al callback quando chiamato
  da WeeChat
* 'callback_delete_option': funzione chiamata quando un'opzione viene eliminata
  nella sezione (NULL se la sezione non consente di eliminare delle opzioni),
  argomenti:
** 'void *data': puntatore
** 'struct t_config_file *config_file': puntatore al file di configurazione
** 'struct t_config_section *section': puntatore alla sezione
** 'struct t_config_option *option': puntatore all'opzione
* 'callback_delete_option_data': puntatore fornito al callback quando chiamato
  da WeeChat

Valore restituito:

* puntatore alla nuova sezione nel file di configurazione, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
int
my_section_read_cb (void *data, struct t_config_file *config_file,
                    struct t_config_section *section, const char *option_name,
                    const char *value)
{
    /* ... */
    
    return WEECHAT_CONFIG_OPTION_SET_OK_CHANGED;
    /* return WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE; */
    /* return WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND; */
    /* return WEECHAT_CONFIG_OPTION_SET_ERROR; */
}

int
my_section_write_cb (void *data, struct t_config_file *config_file,
                     const char *section_name)
{
    /* ... */
    
    return WEECHAT_CONFIG_WRITE_OK;
    /* return WEECHAT_CONFIG_WRITE_ERROR; */
}

int
my_section_write_default_cb (void *data, struct t_config_file *config_file,
                             const char *section_name)
{
    /* ... */
    
    return WEECHAT_CONFIG_WRITE_OK;
    /* return WEECHAT_CONFIG_WRITE_ERROR; */
}

int
my_section_create_option_cb (void *data, struct t_config_file *config_file,
                             struct t_config_section *section,
                             const char *option_name, const char *value)
{
    /* ... */
    
    return WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE;
    /* return WEECHAT_CONFIG_OPTION_SET_ERROR; */
}

int
my_section_delete_option_cb (void *data, struct t_config_file *config_file,
                             struct t_config_section *section,
                             struct t_config_option *option)
{
    /* ... */
    
    return WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED;
    /* return WEECHAT_CONFIG_OPTION_UNSET_ERROR; */
}

/* sezione standard, l'utente non può aggiungere/rimuovere opzioni */
struct t_config_section *new_section1 =
    weechat_config_new_section (config_file, "section1", 0, 0,
                                NULL, NULL, /* read callback */
                                NULL, NULL, /* write callback */
                                NULL, NULL, /* write default callback */
                                NULL, NULL, /* create option callback */
                                NULL, NULL); /* delete option callback */

/* sezione speciale, l'utente può aggiungere/eliminare opzioni, e le
   opzioni necessitano di un callback per essere lette/scritte */
struct t_config_section *new_section2 =
    weechat_config_new_section (config_file, "section2", 1, 1,
                                &my_section_read_cb, NULL,
                                &my_section_write_cb, NULL,
                                &my_section_write_default_cb, NULL,
                                &my_section_create_option_cb, NULL,
                                &my_section_delete_option_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
section = weechat.config_new_section(config_file, name,
    user_can_add_options, user_can_delete_options,
    callback_read, callback_read_data,
    callback_write, callback_write_data,
    callback_create_option, callback_create_option_data,
    callback_delete_option, callback_delete_option_data)

# esempio
def my_section_read_cb(data, config_file, section, option_name, value):
    # ...
    return weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED
    # return weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE
    # return weechat.WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND
    # return weechat.WEECHAT_CONFIG_OPTION_SET_ERROR

def my_section_write_cb(data, config_file, section_name):
    # ...
    return weechat.WEECHAT_CONFIG_WRITE_OK

def my_section_write_default_cb(data, config_file, section_name):
    # ...
    return weechat.WEECHAT_CONFIG_WRITE_OK

def my_section_create_option_cb(data, config_file, section, option_name, value):
    # ...
    return weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE

def my_section_delete_option_cb(data, config_file, section, option):
    # ...
    return weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED

section = weechat.config_new_section(config_file, "section1", 1, 1,
    "my_section_read_cb", "",
    "my_section_write_cb", "",
    "my_section_write_default_cb", "",
    "my_section_create_option_cb", "",
    "my_section_delete_option_cb", "")
----------------------------------------

weechat_config_search_section
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Cerca una sezione in un file di configurazione.

Prototipo:

[source,C]
----------------------------------------
struct t_config_section *weechat_config_search_section (
    struct t_config_file *config_file,
    const char *section_name);
----------------------------------------

Argomenti:

* 'config_file': puntatore al file di configurazione
* 'section_name': nome della sezione da cercare

Valore restituito:

* puntatore alla sezione trovata, NULL se non trovata

Esempio in C:

[source,C]
----------------------------------------
struct t_config_section *section = weechat_config_search_section (config_file,
                                                                  "section");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
section = weechat.config_search_section(config_file, section_name)

# esempio
section = weechat.config_search_section(config_file, "section")
----------------------------------------

weechat_config_new_option
^^^^^^^^^^^^^^^^^^^^^^^^^

Crea una nuova opzione nella sezione di un file di configurazione.

Prototipo:

[source,C]
----------------------------------------
struct t_config_option *weechat_config_new_option (
    struct t_config_file *config_file,
    struct t_config_section *section,
    const char *name,
    const char *type,
    const char *description,
    const char *string_values,
    int min,
    int max,
    const char *default_value,
    const char *value,
    int null_value_allowed,
    int (*callback_check_value)(void *data,
                                struct t_config_option *option,
                                const char *value),
    void *callback_check_value_data,
    int (*callback_change)(void *data,
                           struct t_config_option *option),
    void *callback_change_data,
    int (*callback_delete)(void *data,
                           struct t_config_option *option),
    void *callback_delete_data);
----------------------------------------

Argomenti:

* 'config_file': puntatore al file di configurazione
* 'section': puntatore alla sezione
* 'name': nome dell'opzione
* 'type': tipo dell'opzione:
** 'boolean': valore booleano (on/off)
** 'integer': valore intero (con stringhe opzionali per i valori)
** 'string': valore stringa
** 'color': colore
* 'description': descrizione dell'opzione
* 'string_values': valori come stringa (separati da "|"), usato dal tipo 'integer'
  (opzionale)
* 'min': valore minimo (per il tipo 'integer')
* 'max': valore massimo (per il tipo 'integer')
* 'default_value': valore predefinito per l'opzione (usato per il reset dell'opzione)
* 'value': valore per l'opzione
* 'null_value_allowed': 1 se 'null' (valore non definito) è consentito per l'opzione,
  altrimenti 0
* 'callback_check_value': funzione chiamata per verificare il nuovo valore per
  l'opzione (ozionale), argomenti:
** 'void *data': puntatore
** 'struct t_config_option *option': puntatore all'opzione
** 'const char *value': nuovo valore per l'opzione
* 'callback_check_value_data': puntatore fornito alla callback check_value
  quando chiamato da WeeChat
* 'callback_change': funzione chiamata quando il valore dell'opzione è stata
  cambiata (opzionale), argomenti:
** 'void *data': puntatore
** 'struct t_config_option *option': puntatore all'opzione
* 'callback_change_data': puntatore fornito per cambiare alla callback quando
  chiamato da WeeChat
* 'callback_delete': funzione chiamata quando l'opzione verrà eliminata
  (opzionale), argomenti:
** 'void *data': puntatore
** 'struct t_config_option *option': puntatore all'opzione
* 'callback_delete_data': puntatore fornito per eiliminare alla callback quando
  chiamato da WeeChat

Valore restituito:

 alla nuova opzione nella sezione, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
/* booleano */
struct t_config_option *option1 =
    weechat_config_new_option (config_file, section, "option1", "boolean",
                               "My option, type boolean"
                               NULL, /* valori stringa */
                               0, 0, /* min, max */
                               "on", /* predefinito */
                               "on", /* valore */
                               0, /* null value allowed */
                               NULL, NULL, /* verifica callback */
                               NULL, NULL, /* modifica callback */
                               NULL, NULL); /* elimina callback */

/* intero */
struct t_config_option *option2 =
    weechat_config_new_option (config_file, section, "option2", "integer",
                               "My option, type integer"
                               NULL, /* string values */
                               0, 100, /* min, max */
                               "15", /* default */
                               "15", /* value */
                               0, /* null value allowed */
                               NULL, NULL, /* verifica callback */
                               NULL, NULL, /* modifica callback */
                               NULL, NULL); /* elimina callback */

/* intero (con valori stringa) */
struct t_config_option *option3 =
    weechat_config_new_option (config_file, section, "option3", "integer",
                               "My option, type integer (with string values)"
                               "top|bottom|left|right", /* string values */
                               0, 0, /* min, max */
                               "bottom", /* predefinito */
                               "bottom", /* valoree */
                               0, /* null value allowed */
                               NULL, NULL, /* verifica callback */
                               NULL, NULL, /* modifica callback */
                               NULL, NULL); /* elimina callback */

/* stringa */
struct t_config_option *option4 =
    weechat_config_new_option (config_file, section, "option4", "string",
                               "My option, type string"
                               NULL, /* valori stringa */
                               0, 0, /* min, max */
                               "test", /* predefinito */
                               "test", /* valore */
                               1, /* valore null consentito */
                               NULL, NULL, /* verifica callback */
                               NULL, NULL, /* modifica callback */
                               NULL, NULL); /* elimina callback */

/* colore */
struct t_config_option *option5 =
    weechat_config_new_option (config_file, section, "option5", "color",
                               "My option, type color"
                               NULL, /* valori stringa */
                               0, 0, /* min, max */
                               "lightblue", /* predefinito */
                               "lightblue", /* valore */
                               0, /* valore null consentito */
                               NULL, NULL, /* verifica callback */
                               NULL, NULL, /* modifica callback */
                               NULL, NULL); /* elimina callback */
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
option = weechat.config_new_option(config_file, section, name, type, description,
    string_values, min, max, default_value, value, null_value_allowed,
    callback_check_value, callback_check_value_data,
    callback_change, callback_change_data,
    callback_delete, callback_delete_data)

# esempio
def option4_check_value_cb(data, option, value):
    # ...
    return 1
    # return 0

def option4_change_cb(data, option):
    # ...

def option4_delete_cb(data, option):
    # ...

option1 = weechat.config_new_option(config_file, section, "option1", "boolean",
    "My option, type boolean",
    "", 0, 0, "on", "on", 0,
    "", "",
    "", "",
    "", "")

option2 = weechat.config_new_option(config_file, section, "option2", "integer",
    "My option, type integer",
    "", 0, 100, "15", "15", 0,
    "", "",
    "", "",
    "", "")

option3 = weechat.config_new_option(config_file, section, "option3", "integer",
    "My option, type integer (with string values)",
    "top|bottom|left|right",
    0, 0, "bottom", "bottom", 0,
    "", "",
    "", "",
    "", "")

option4 = weechat.config_new_option(config_file, section, "option4", "string",
    "My option, type string",
    "", 0, 0, "test", "test", 1,
    "option4_check_value_cb", ""
    "option4_change_cb", "",
    "option4_delete_cb", "")

option5 = weechat.config_new_option(config_file, section, "option5", "color",
    "My option, type color",
    "", 0, 100, "lightblue", "lightblue", 0,
    "", "",
    "", "",
    "", "")
----------------------------------------

weechat_config_search_option
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Cerca un'opzione nella sezione di un file di configurazione.

Prototipo:

[source,C]
----------------------------------------
struct t_config_option *weechat_config_search_option (
    struct t_config_file *config_file,
    struct t_config_section *section,
    const char *option_name);
----------------------------------------

Argomenti:

* 'config_file': puntatore al file di configurazione
* 'section': puntatore alla sezione
* 'name': nome dell'opzione da cercare

Valore restituito:

* puntatore all'opzione trovata, NULL se non trovata

Esempio in C:

[source,C]
----------------------------------------
struct t_config_option *option =
    weechat_config_search_option (config_file, section, "option");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
option = weechat.config_search_option(config_file, section, option_name)

# esempio
option = weechat.config_search_option(config_file, section, "option")
----------------------------------------

weechat_config_search_section_option
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Cerca una sezione ed un'opzione in un file di configurazione o sezione.

Prototipo:

[source,C]
----------------------------------------
void weechat_config_search_section_option (struct t_config_file *config_file,
                                           struct t_config_section *section,
                                           const char *option_name,
                                           struct t_config_section **section_found,
                                           struct t_config_option **option_found);
----------------------------------------

Arguments:

* 'config_file': puntatore al file di configurazione
* 'section': puntatore alla sezione
* 'option_name': nome dell'opzione
* 'section_found': puntatore al puntatore della sezione, sarà impostato alla
  sezione dell'opzione, se viene trovata
* 'option_found': puntatore al puntatore dell'opzione, sarà impostato al
  puntatore di un'opzione, se viene trovata

Esempio in C:

[source,C]
----------------------------------------
struct t_config_section *ptr_section;
struct t_config_option *ptr_option;

weechat_config_search_section_option(config_file,
                                     section,
                                     "option",
                                     &ptr_section,
                                     &ptr_option);
if (ptr_option)
{
    /* opzione trovata */
}
else
{
    /* opzione non trovata */
}
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_config_search_with_string
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Cerca un'opzione con il nome completo.

Prototipo:

[source,C]
----------------------------------------
void weechat_config_search_with_string (const char *option_name,
                                        struct t_config_file **config_file,
                                        struct t_config_section **section,
                                        struct t_config_option **option);
----------------------------------------

Argomenti:

* 'option_name': nome completo dell'opzione (formato: "file.section.option")
* 'config_file': puntatore al puntatore del file di configurazione, sarà impostato
  al puntatore al file di configurazione se l'opzione viene trovata
* 'section': puntatore al puntatore della sezione, sarà impostato alla sezione
  dell'opzione, se viene trovata
* 'option': puntatore al puntatore dell'opzione, sarà impostato al puntatore di
  un'opzione, se viene trovata

Esempio in C:

[source,C]
----------------------------------------
struct t_config_file *ptr_config_file;
struct t_config_section *ptr_section;
struct t_config_option *ptr_option;

weechat_config_search_with_string ("file.section.option",
                                   &ptr_config_file,
                                   &ptr_section,
                                   &ptr_option);
if (ptr_option)
{
    /* opzione trovata */
}
else
{
    /* opzione non trovata */
}
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_config_string_to_boolean
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Verifica se un testo è "vero" o "falso", come valore booleano.

Prototipo:

[source,C]
----------------------------------------
int weechat_config_string_to_boolean (const char *text);
----------------------------------------

Argomenti:

* 'text': testo da analizzare

Valore restituito:

* 1 se il testo è "true" ("on", "yes", "y", "true", "t", "1")
* 0 se il testo è "false" ("off", "no", "n", "false", "f", "0")

Esempio in C:

[source,C]
----------------------------------------
if (weechat_config_string_to_boolean (option_value))
{
    /* il valore è "true" */
}
else
{
    /* il valore è "false" */
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.config_string_to_boolean(text)

# esempio
if weechat.config_string_to_boolean(text):
    # ...
----------------------------------------

weechat_config_option_reset
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Resetta un'opzione al proprio valore predefinito.

Prototipo:

[source,C]
----------------------------------------
int weechat_config_option_reset (struct t_config_option *option,
                                 int run_callback);
----------------------------------------

Argomenti:

* 'option': puntatore all'opzione
* 'run_callback': 1 per la chiamata alla callbackse il valore dell'opzione
  è cambiato, altrimenti 0

Valore restituito:

* 'WEECHAT_CONFIG_OPTION_SET_OK_CHANGED' se il valore dell'opzione è stato
  resettato
* 'WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE' se il valore non è stato
  modificato
* 'WEECHAT_CONFIG_OPTION_SET_ERROR' in caso di errore

Esempio in C:

[source,C]
----------------------------------------
switch (weechat_config_option_reset (option, 1))
{
    case WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
        /* .... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
        /* .... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_ERROR:
        /* .... */
        break;
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
rc = weechat.config_option_reset(option, run_callback)

# esempio
rc = weechat.config_option_reset(option, 1)
if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
    # ...
----------------------------------------

weechat_config_option_set
^^^^^^^^^^^^^^^^^^^^^^^^^

Imposta un nuovo valore per l'opzione.

Prototipo:

[source,C]
----------------------------------------
int weechat_config_option_set (struct t_config_option *option,
                               const char *value, int run_callback);
----------------------------------------

Argomenti:

* 'option': puntatore all'opzione
* 'value': nuovo valore per l'opzione
* 'run_callback': 1 per la chiamata alla callback chang se il valore dell'opzione
  è cambiato, altrimenti 0

Valore restituito:

* 'WEECHAT_CONFIG_OPTION_SET_OK_CHANGED' se il valore dell'opzione è
  cambiato
* 'WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE' se il valore non è cambiato
* 'WEECHAT_CONFIG_OPTION_SET_ERROR' in caso di errore

Esempio in C:

[source,C]
----------------------------------------
switch (weechat_config_option_set (option, "new_value", 1))
{
    case WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
        /* .... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
        /* .... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_ERROR:
        /* .... */
        break;
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
rc = weechat.config_option_set(option, value, run_callback)

# esempio
rc = weechat.config_option_set(option, "new_value", 1)
if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
    # ...
----------------------------------------

weechat_config_option_set_null
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Imposta null (valore non definito) per un'opzione.

Prototipo:

[source,C]
----------------------------------------
int weechat_config_option_set_null (struct t_config_option *option,
                                    int run_callback);
----------------------------------------

Argomenti:

* 'option': puntatore all'opzione
* 'run_callback': 1 per la chiamata alla callback chang se il valore
  dell'opzione è cambiato (se non è null), altrimenti 0

[NOTE]
È possibile impostare il valore a null solo se è consentito per l'opzione
(consultare <<_weechat_config_new_option,weechat_config_new_option>>).

Valore restituito:

* 'WEECHAT_CONFIG_OPTION_SET_OK_CHANGED' se il valore dell'opzione è
  cambiato
* 'WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE' se il valore non è cambiato
* 'WEECHAT_CONFIG_OPTION_SET_ERROR' in caso di errore

Esempio in C:

[source,C]
----------------------------------------
switch (weechat_config_option_set_null (option, 1))
{
    case WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
        /* .... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
        /* .... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_ERROR:
        /* .... */
        break;
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
rc = weechat.config_option_set_null(option, run_callback)

# esempio
rc = weechat.config_option_set_null(option, 1)
if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
    # ...
----------------------------------------

weechat_config_option_unset
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Rimuove/ripristina un'opzione.

Prototipo:

[source,C]
----------------------------------------
int weechat_config_option_unset (struct t_config_option *option);
----------------------------------------

Argomenti:

* 'option': puntatore all'opzione

Valore restituito:

* 'WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET' se il valore dell'opzione non è
  stato ripristinato
* 'WEECHAT_CONFIG_OPTION_UNSET_OK_RESET' se il valore dell'opzione è stato
  ripristinato
* 'WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED' se l'opzione è stata rimossa
* 'WEECHAT_CONFIG_OPTION_UNSET_ERROR' in caso di errore

Esempio in C:

[source,C]
----------------------------------------
switch (weechat_config_option_unset (option))
{
    case WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET:
        /* .... */
        break;
    case WEECHAT_CONFIG_OPTION_UNSET_OK_RESET:
        /* .... */
        break;
    case WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED:
        /* .... */
        break;
    case WEECHAT_CONFIG_OPTION_UNSET_ERROR:
        /* .... */
        break;
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
rc = weechat.config_option_unset(option)

# esempio
rc = weechat.config_option_unset(option)
if rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_RESET:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_ERROR:
    # ...
----------------------------------------

weechat_config_option_rename
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Rinomina un'opzione.

Prototipo:

[source,C]
----------------------------------------
void weechat_config_option_rename (struct t_config_option *option,
                                   const char *new_name);
----------------------------------------

Argomenti:

* 'option': puntatore all'opzione
* 'new_name': nuovo nome per l'opzione

Esempio in C:

[source,C]
----------------------------------------
weechat_config_option_rename (option, "new_name");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.config_option_rename(option, new_name)

# esempio
weechat.config_option_rename(option, "new_name")
----------------------------------------

weechat_config_option_get_pointer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Restituisce un puntatore alla proprietà di un'opzione.

Prototipo:

[source,C]
----------------------------------------
void *weechat_config_option_get_pointer (struct t_config_option *option,
                                         const char *property);
----------------------------------------

Argomenti:

* 'option': puntatore all'opzione
* 'property': nome della proprietà:
** 'config_file': puntatore al file di configurazione ('struct t_config_file *')
** 'section': puntatore alla sezione ('struct t_config_section *')
** 'name': nome dell'opzione ('char *')
** 'type': tipo dell'opzione ('int *')
** 'description': descrizione dell'opzione ('char *')
** 'string_values': valori stringa ('char *')
** 'min': valore minimo ('int *')
** 'max': valore massimo ('int *')
** 'default_value': valore predefinito (dipende dal tipo)
** 'value': valore corrente (dipende dal tipo)
** 'prev_option': puntatore all'opzione precedente ('struct t_config_option *')
** 'next_option': puntatore all'opzione successiva ('struct t_config_option *')

Valore restituito:

* puntatore alla proprietà richiesta

Esempio in C:

[source,C]
----------------------------------------
char *description = weechat_config_option_get_pointer (option, "description");
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_config_option_is_null
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Verifica se un opzione è "null" (valore non definito).

Prototipo:

[source,C]
----------------------------------------
int weechat_config_option_is_null (struct t_config_option *option);
----------------------------------------

Argomenti:

* 'option': puntatore all'opzione

Valore restituito:

* 1 se il valore dell'opzione è "null"
* 0 se il valore dell'opzione non è "null"

Esempio in C:

[source,C]
----------------------------------------
if (weechat_config_option_is_null (option))
{
    /* il valore è "null" */
}
else
{
    /* il valore non è "null" */
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.config_option_is_null(option)

# esempio
if weechat.config_option_is_null(option):
    # ...
----------------------------------------

weechat_config_option_default_is_null
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Verifica che il valore predefinito di un'opzione sia "null" (valore non definito).

Prototipo:

[source,C]
----------------------------------------
int weechat_config_option_default_is_null (struct t_config_option *option);
----------------------------------------

Argomenti:

* 'option': puntatore all'opzione

Valore restituito:

* 1 se il valore predefinito di un'opzione è "null"
* 0 se il valore predefinito di un'opzione non è  "null"

Esempio in C:

[source,C]
----------------------------------------
if (weechat_config_option_default_is_null (option))
{
    /* il valore predefinito è "null" */
}
else
{
    /* il valore predefinito non è "null" */
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.config_option_default_is_null(option)

# esempio
if weechat.config_option_default_is_null(option):
    # ...
----------------------------------------

weechat_config_boolean
^^^^^^^^^^^^^^^^^^^^^^

Restituisce il valore bool di un'opzione.

Prototipo:

[source,C]
----------------------------------------
int weechat_config_boolean (struct t_config_option *option);
----------------------------------------

Argomenti:

* 'option': puntatore all'opzione

Valore restituito:

* valore bool di un'opzione (0 o 1)

Esempio in C:

[source,C]
----------------------------------------
if (weechat_config_boolean (option))
{
    /* il valore è "true" */
}
else
{
    /* il valore è "false" */
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.config_option_boolean(option)

# esempio
if weechat.config_option_boolean(option):
    # ...
----------------------------------------

weechat_config_boolean_default
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Restituisce il valore bool predefinito di un'opzione.

Prototipo:

[source,C]
----------------------------------------
int weechat_config_boolean_default (struct t_config_option *option);
----------------------------------------

Argomenti:

* 'option': puntatore all'opzione

Valore restituito:

* il valore bool predefinito di un'opzione (0 o 1)

Esempio in C:

[source,C]
----------------------------------------
if (weechat_config_boolean_default (option))
{
    /* il valore è "true" */
}
else
{
    /* il valore è "false" */
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.config_option_boolean_default(option)

# esempio
if weechat.config_option_boolean_default(option):
    # ...
----------------------------------------

weechat_config_integer
^^^^^^^^^^^^^^^^^^^^^^

Restituisce il valore intero di un'opzione.

Prototipo:

[source,C]
----------------------------------------
int weechat_config_integer (struct t_config_option *option);
----------------------------------------

Argomenti:

* 'option': puntatore all'opzione

Valore restituito:

* valore intero di un'opzione

Esempio in C:

[source,C]
----------------------------------------
int value = weechat_config_integer (option);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.config_option_integer(option)

# esempio
if weechat.config_option_integer(option):
    # ...
----------------------------------------

weechat_config_integer_default
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Restituisce il valore intero predefinito di un'opzione.

Prototipo:

[source,C]
----------------------------------------
int weechat_config_integer_default (struct t_config_option *option);
----------------------------------------

Argomenti:

* 'option': puntatore all'opzione

Valore restituito:

* valore intero predefinito di un'opzione

Esempio in C:

[source,C]
----------------------------------------
int value = weechat_config_integer_default (option);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.config_option_integer_default(option)

# esempio
if weechat.config_option_integer_default(option):
    # ...
----------------------------------------

weechat_config_string
^^^^^^^^^^^^^^^^^^^^^

Restituisce il valore stringa di un'opzione.

Prototipo:

[source,C]
----------------------------------------
const char *weechat_config_string (struct t_config_option *option);
----------------------------------------

Argomenti:

* 'option': puntatore all'opzione

Valore restituito:

* valore stringa di un'opzione

Esempio in C:

[source,C]
----------------------------------------
const char *value = weechat_config_string (option);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.config_option_string(option)

# esempio
value = weechat.config_option_string(option):
----------------------------------------

weechat_config_string_default
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Restituisce il valore stringa predefinito di un'opzione.

Prototipo:

[source,C]
----------------------------------------
const char *weechat_config_integer_default (struct t_config_option *option);
----------------------------------------

Argomenti:

* 'option': puntatore all'opzione

Valore restituito:

* valore stringa predefinito di un'opzione

Esempio in C:

[source,C]
----------------------------------------
const char *value = weechat_config_string_default (option);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.config_option_string_default(option)

# esempio
value = weechat.config_option_string_default(option):
----------------------------------------

weechat_config_color
^^^^^^^^^^^^^^^^^^^^

Restituisce il valore colore di un'opzione.

Prototipo:

[source,C]
----------------------------------------
const char *weechat_config_color (struct t_config_option *option);
----------------------------------------

Argomenti:

* 'option': puntatore all'opzione

Valore restituito:

* valore colore dell'opzione (stringa con il nome del colore)

Esempio in C:

[source,C]
----------------------------------------
const char *color = weechat_config_color (option);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.config_option_color(option)

# esempio
value = weechat.config_option_color(option):
----------------------------------------

weechat_config_color_default
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Restituisce il valore colore predefinito di un'opzione.

Prototipo:

[source,C]
----------------------------------------
const char *weechat_config_color_default (struct t_config_option *option);
----------------------------------------

Argomenti:

* 'option': puntatore all'opzione

Valore restituito:

* valore colore predefinito di un'opzione (stringa con il nome del colore)

Esempio in C:

[source,C]
----------------------------------------
const char *color = weechat_config_color_default (option);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.config_option_color_default(option)

# esempio
value = weechat.config_option_color_default(option):
----------------------------------------

weechat_config_write_option
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Scrive una riga nel file di configurazione con l'opzione ed il suo valore
(questa funzione dovrebbe essere chiamata solo nelle callback "write"
o "write_default" per una sezione).

Prototipo:

[source,C]
----------------------------------------
void weechat_config_write_option (struct t_config_file *config_file,
                                  struct t_config_option *option);
----------------------------------------

Argomenti:

* 'config_file': puntatore al file di configurazione
* 'option': puntatore all'opzione

Esempio in C:

[source,C]
----------------------------------------
int
my_section_write_cb (void *data, struct t_config_file *config_file,
                     const char *section_name)
{
    weechat_config_write_line (config_file, "my_section", NULL);
    
    weechat_config_write_option (config_file, option);
    
    return WEECHAT_RC_OK;
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.config_write_option(config_file, option)

# esempio
def my_section_write_cb(data, config_file, section_name):
    weechat.config_write_line(config_file, "my_section", "")
    weechat.config_write_option(config_file, option)
    return weechat.WEECHAT_RC_OK
----------------------------------------

weechat_config_write_line
^^^^^^^^^^^^^^^^^^^^^^^^^

Scrive una riga nel file di configurazione (questa funzione dovrebbe
essere chiamata solo nelle callback "write" o "write_default" per una
sezione).

Prototipo:

[source,C]
----------------------------------------
void weechat_config_write_line (struct t_config_file *config_file,
                                const char *option_name,
                                const char *value, ...);
----------------------------------------

Argomenti:

* 'config_file': puntatore al file di configurazione
* 'option_name': nome dell'opzione
* 'value': valore (se NULL, allora la riga con il nome della sezione viene
  scritto, ad esempio: "[section]")

Esempio in C:

[source,C]
----------------------------------------
int
my_section_write_cb (void *data, struct t_config_file *config_file,
                     const char *section_name)
{
    weechat_config_write_line (config_file, "my_section", NULL);
    
    weechat_config_write_line (config_file, "option", "%s;%d",
                               "value", 123);
                               
    return WEECHAT_RC_OK;
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.config_write_line(config_file, option_name, value)

# esempio
def my_section_write_cb(data, config_file, section_name):
    weechat.config_write_line(config_file, "my_section", "")
    weechat.config_write_line(config_file, "option", "value")
    return weechat.WEECHAT_RC_OK
----------------------------------------

weechat_config_write
^^^^^^^^^^^^^^^^^^^^

Scrive il file di configurazione su disco.

Prototipo:

[source,C]
----------------------------------------
int weechat_config_write (struct t_config_file *config_file);
----------------------------------------

Argomenti:

* 'config_file': puntatore al file di configurazione

Valore restituito:

* 'WEECHAT_CONFIG_WRITE_OK' se la configurazione è stata scritta
* 'WEECHAT_CONFIG_WRITE_MEMORY_ERROR' se non c'è memoria sufficiente
* 'WEECHAT_CONFIG_WRITE_ERROR' se si è verificato un altro errore

Esempio in C:

[source,C]
----------------------------------------
switch (weechat_config_write (config_file))
{
    case WEECHAT_CONFIG_WRITE_OK:
        /* ... */
        break;
    case WEECHAT_CONFIG_WRITE_MEMORY_ERROR:
        /* ... */
        break;
    case WEECHAT_CONFIG_WRITE_ERROR:
        /* ... */
        break;
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
rc = weechat.config_write(config_file)

# esempio
rc = weechat.config_write(config_file)
if rc == weechat.WEECHAT_CONFIG_WRITE_OK:
    # ...
elif rc == weechat.WEECHAT_CONFIG_WRITE_MEMORY_ERROR:
    # ...
elif rc == weechat.WEECHAT_CONFIG_WRITE_ERROR:
    # ...
----------------------------------------

weechat_config_read
^^^^^^^^^^^^^^^^^^^

Legge il file di configurazione da disco.

Prototipo:

[source,C]
----------------------------------------
int weechat_config_read (struct t_config_file *config_file);
----------------------------------------

Argomenti:

* 'config_file': puntatore al file di configurazione

Valore restituito:

* 'WEECHAT_CONFIG_READ_OK' se la configurazione è stata caricata
* 'WEECHAT_CONFIG_READ_MEMORY_ERROR' se non c'è memoria sufficiente
* 'WEECHAT_CONFIG_READ_FILE_NOT_FOUND' se il file non è stato trovato

Esempio in C:

[source,C]
----------------------------------------
switch (weechat_config_read (config_file))
{
    case WEECHAT_CONFIG_READ_OK:
        /* ... */
        break;
    case WEECHAT_CONFIG_READ_MEMORY_ERROR:
        /* ... */
        break;
    case WEECHAT_CONFIG_READ_FILE_NOT_FOUND:
        /* ... */
        break;
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
rc = weechat.config_read(config_file)

# esempio
rc = weechat.config_read(config_file)
if rc == weechat.WEECHAT_CONFIG_READ_OK:
    # ...
elif rc == weechat.WEECHAT_CONFIG_READ_MEMORY_ERROR:
    # ...
elif rc == weechat.WEECHAT_CONFIG_READ_FILE_NOT_FOUND:
    # ...
----------------------------------------

weechat_config_reload
^^^^^^^^^^^^^^^^^^^^^

Ricarica il file di configurazione da disco.

Prototipo:

[source,C]
----------------------------------------
int weechat_config_reload (struct t_config_file *config_file);
----------------------------------------

Argomenti:

* 'config_file': configuration file pointer

Valore restituito:

* 'WEECHAT_CONFIG_READ_OK' se il file di configurazione è stato ricaricato
* 'WEECHAT_CONFIG_READ_MEMORY_ERROR' se non c'è memoria sufficiente
* 'WEECHAT_CONFIG_READ_FILE_NOT_FOUND' se il file non è stato trovato

Esempio in C:

[source,C]
----------------------------------------
switch (weechat_config_reload (config_file))
{
    case WEECHAT_CONFIG_READ_OK:
        /* ... */
        break;
    case WEECHAT_CONFIG_READ_MEMORY_ERROR:
        /* ... */
        break;
    case WEECHAT_CONFIG_READ_FILE_NOT_FOUND:
        /* ... */
        break;
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
rc = weechat.config_reload(config_file)

# esempio
rc = weechat.config_reload(config_file)
if rc == weechat.WEECHAT_CONFIG_READ_OK:
    # ...
elif rc == weechat.WEECHAT_CONFIG_READ_MEMORY_ERROR:
    # ...
elif rc == weechat.WEECHAT_CONFIG_READ_FILE_NOT_FOUND:
    # ...
----------------------------------------

weechat_config_option_free
^^^^^^^^^^^^^^^^^^^^^^^^^^

Libera un'opzione.

Prototipo:

[source,C]
----------------------------------------
void weechat_config_option_free (struct t_config_option *option);
----------------------------------------

Argomenti:

* 'option': puntatore all'opzione

Esempio in C:

[source,C]
----------------------------------------
weechat_config_option_free (option);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.config_option_free(option)

# esempio
weechat.config_option_free(option)
----------------------------------------

weechat_config_section_free_options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Libera tutte le opzioni in una sessione.

Prototipo:

[source,C]
----------------------------------------
void weechat_config_section_free_options (struct t_config_section *section);
----------------------------------------

Argomenti:

* 'section': puntatore alla sezione

Esempio in C:

[source,C]
----------------------------------------
weechat_config_section_free_options (section);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.config_section_free_options(section)

# esempio
weechat.config_section_free_options(section)
----------------------------------------

weechat_config_section_free
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Libera una sezione.

Prototipo:

[source,C]
----------------------------------------
void weechat_config_section_free (struct t_config_option *option);
----------------------------------------

Argomenti:

* 'section': puntatore alla sezione

Esempio in C:

[source,C]
----------------------------------------
weechat_config_section_free (section);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.config_section_free(section)

# esempio
weechat.config_section_free(section)
----------------------------------------

weechat_config_free
^^^^^^^^^^^^^^^^^^^

Libera un file di configurazione.

Prototipo:

[source,C]
----------------------------------------
void weechat_config_free (struct t_config_file *config_file);
----------------------------------------

Argomenti:

* 'config_file': puntatore al file di configurazione

Esempio in C:

[source,C]
----------------------------------------
weechat_config_free (config_file);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.config_free(config_file)

# esempio
weechat.config_free(config_file)
----------------------------------------

weechat_config_get
^^^^^^^^^^^^^^^^^^

Cerca un'opzione con il nome completo.

Prototipo:

[source,C]
----------------------------------------
struct t_config_option *weechat_config_get (const char *option_name);
----------------------------------------

Argomenti:

* 'option_name': nome completo dell'opzione (formato: "file.section.option")

Valore restituito:

* puntatore all'opzione trovata, NULL se non trovata

Esempio in C:

[source,C]
----------------------------------------
struct t_config_option *option = weechat_config_get ("weechat.look.item_time_format");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
option = weechat.config_get(option_name)

# esempio
option = weechat.config_get("weechat.look.item_time_format")
----------------------------------------

weechat_config_get_plugin
^^^^^^^^^^^^^^^^^^^^^^^^^

Cerca un'opzione nei file di configurazione dei plugin (plugins.conf).

Prototipo:

[source,C]
----------------------------------------
const char *weechat_config_get_plugin (const char *option_name);
----------------------------------------

Argomenti:

* 'option_name': nome dell'opzione, WeeChat aggiungerà il prefisso
  "plugins.var.xxx." (dove "xxx" è il nome del plugin corrente)

Valore restituito:

* valore dell'opzione trovata, NULL se non trovata

Esempio in C:

[source,C]
----------------------------------------
/* se il plugin corrente è "test", allora cerca il valore
   dell'opzione "plugins.var.test.option" nel file plugins.conf */
char *value = weechat_config_get_plugin ("option");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.config_get_plugin(option_name)

# esempio
value = weechat.config_get_plugin("option")
----------------------------------------

weechat_config_is_set_plugin
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Verifica se un'opzione è impostata nel file di configurazione dei
plugin (plugins.conf).

Prototipo:

[source,C]
----------------------------------------
int weechat_config_is_set_plugin (const char *option_name);
----------------------------------------

Argomenti:

* 'option_name': nome dell'opzione, WeeChat aggiunge il prefisso "plugins.var.xxx."
  (dove "xxx" è il nome del plugin corrente)

Valore restituito:

* 1 se l'opzione è impostata, 0 se l'opzione non esiste

Esempio in C:

[source,C]
----------------------------------------
if (weechat_config_is_set_plugin ("option"))
{
    /* l'opzione è impostata */
}
else
{
    /* l'opzione non esiste */
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.config_is_set_plugin(option_name)

# esempio
if weechat.config_is_set_plugin("option"):
    # l'opzione è impostata
    # ...
else:
    # l'opzione non esiste
    # ...
----------------------------------------

weechat_config_set_plugin
^^^^^^^^^^^^^^^^^^^^^^^^^

Imposta il nuovo valore per l'opzione nel file di configurazione dei plugin (plugins.conf).

Prototipo:

[source,C]
----------------------------------------
int weechat_config_set_plugin (const char *option_name, const char *value);
----------------------------------------

Argomenti:

* 'option_name': nome dell'opzione, WeeChat aggiunge il prefisso "plugins.var.xxx."
  (dove "xxx" è il nome del plugin corrente)
* 'value': new value for option

Valore restituito:

* 'WEECHAT_CONFIG_OPTION_SET_OK_CHANGED' se il valore dell'opzione è stato modificato
* 'WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE' se il valore non è cambiato
* 'WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND' se l'opzione non è stata trovata
* 'WEECHAT_CONFIG_OPTION_SET_ERROR' in caso di errore

Esempio in C:

[source,C]
----------------------------------------
switch (weechat_config_set_plugin ("option", "test_value"))
{
    case WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
        /* ... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
        /* ... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND:
        /* ... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_ERROR:
        /* ... */
        break;
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
rc = weechat.config_set_plugin(option_name, value)

# esempio
rc = weechat.config_is_set_plugin("option", "test_value")
if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
    # ...
----------------------------------------

weechat_config_unset_plugin
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Disattiva l'opzione nel file di configurazione dei plugin (plugins.conf).

Prototipo:

[source,C]
----------------------------------------
int weechat_config_unset_plugin (const char *option_name);
----------------------------------------

Argomenti:

* 'option_name': nome dell'opzione, WeeChat aggiunge il prefisso "plugins.var.xxx."
  (dove xxx è il nome del plugin corrente)

Valore restituito:

* 'WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET' se il valore dell'opzione non è
  stato resettato
* 'WEECHAT_CONFIG_OPTION_UNSET_OK_RESET' se il valore dell'opzione è stato
  resettato
* 'WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED' se l'opzione è stata rimossa
* 'WEECHAT_CONFIG_OPTION_UNSET_ERROR' in caso di errore

Esempio in C:

[source,C]
----------------------------------------
switch (weechat_config_unset_plugin ("option"))
{
    case WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET:
        /* ... */
        break;
    case WEECHAT_CONFIG_OPTION_UNSET_OK_RESET:
        /* ... */
        break;
    case WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED:
        /* ... */
        break;
    case WEECHAT_CONFIG_OPTION_UNSET_ERROR:
        /* ... */
        break;
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
rc = weechat.config_unset_plugin(option_name)

# esempio
rc = weechat.config_unset_plugin("option")
if rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_RESET:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_ERROR:
    # ...
----------------------------------------

[[display]]
Visualizzazione
~~~~~~~~~~~~~~~

Funzioni per visualizzare il testo nei buffer.

weechat_prefix
^^^^^^^^^^^^^^

Restituisce un prefisso.

Prototipo:

[source,C]
----------------------------------------
const char *weechat_prefix (const char *prefix);
----------------------------------------

Argomenti:

* 'prefix': nome del prefisso:

[width="70%",cols="^2e,^1l,^3,5",options="header"]
|========================================
| Prefisso | Valore | Colore       | Descrizione
| error    | =!=    | giallo       | messaggio di errore
| network  | --     | magenta      | messaggio dalla rete
| action   | *      | bianco       | azione automatica
| join     | -->    | verde chiaro | qualcuno entra nella chat corrente
| quit     | <--    | rosso chiaro | qualcuno lascia la chat corrente
|========================================

[NOTE]
Valori e colori possono essere personalizzati con il comando `/set`.

Valore restituito:

* valore del prefisso (stringa con prefisso e codici colori), stringa vuota
  se il prefisso non è stato trovato

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL, "%sQuesto è un errore...", weechat_prefix ("error"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.prefix(prefix)

# esempio
weechat.prnt("", "%sQuesto è un errore..." % weechat.prefix("error"))
----------------------------------------

weechat_color
^^^^^^^^^^^^^

Restituisce una codice colore stringa da visualizzare.

Prototipo:

[source,C]
----------------------------------------
const char *weechat_color (const char *color_name);
----------------------------------------

Argomenti:

* 'color_name': nome del colore, uno di:
** nome opzione di WeeChat (da weechat.color.xxx), ad esempio 'chat_delimiters'
** colore con sfondo opzionale, ad esempio 'yellow' o 'yellow,red'
** attributo:
*** 'bold': imposta grassetto
*** '-bold': rimuove grassetto
*** 'reverse': imposta inverso
*** '-reverse': rimuove inverso
*** 'italic': imposta corsivo
*** '-italic': rimuove corsivo
*** 'underline': imposta sottolineato
*** '-underline': rimuove sottolineato
** nome colore della barra:
*** 'bar_fg': colore di primo piano della barra
*** 'bar_delim': colore dei delimitatori della barra
*** 'bar_bg': colore di sfondo della barra

Valore restituito:

* stringa con codice colore, o un codice "reset color" se il colore non è stato trovato

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL, "Color: %sblue %sdefault color %syellow on red",
                weechat_color ("blue"),
                weechat_color ("chat"),
                weechat_color ("yellow,red"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.color(color_name)

# esempio
weechat.prnt("", "%sColor: %sblue %sdefault color %syellow on red"
    % (weechat.color("blue"), weechat.color("chat"), weechat.color("yellow,red")))
----------------------------------------

weechat_printf
^^^^^^^^^^^^^^

Visualizza un messaggio su un buffer.

Prototipo:

[source,C]
----------------------------------------
void weechat_printf (struct t_gui_buffer *buffer, const char *message, ...);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer, se NULL il messaggio viene visualizzato sul buffer di WeeChat
* 'message': messaggio da visualizzare

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL, "Benvenuto sul buffer di WeeChat");
weechat_printf (buffer, "Benvenuto su questo buffer");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.prnt(buffer, message)

# esempio
weechat.prnt("", "Benvenuto sul buffer di WeeChat")
weechat.prnt(buffer, "Benvenuto su questo buffer")
----------------------------------------

[NOTE]
La funzione è chiamata "print" negli script ("prnt" in Python).

weechat_printf_date
^^^^^^^^^^^^^^^^^^^

Visualizza un messaggio sul buffer, utilizzando una data personalizzata.

Prototipo:

[source,C]
----------------------------------------
void weechat_printf_date (struct t_gui_buffer *buffer, time_t date,
                          const char *message, ...);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer, se NULL, il messaggio viene visualizzato
  sul buffer di WeeChat
* 'date': data per il messaggio
* 'message': messaggio da visualizzare

Esempio in C:

[source,C]
----------------------------------------
weechat_printf_date (NULL, time (NULL) - 120, "Ciao, 2 minuti fa");
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_printf_tags
^^^^^^^^^^^^^^^^^^^

Visualizza un messaggio sul buffer, utilizzando tag personalizzati.

Prototipo:

[source,C]
----------------------------------------
void weechat_printf_tags (struct t_gui_buffer *buffer, const char *tags,
                          const char *message, ...);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer, se NULL il messaggio viene visualizzato
  sul buffer di WeeChat
* 'tags': lista di tag separati da virgole
* 'message': messaggio da visualizzare

Esempio in C:

[source,C]
----------------------------------------
weechat_printf_tags (NULL, "notify_message",
                     "Messaggio con tag 'notify_message'");
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_printf_date_tags
^^^^^^^^^^^^^^^^^^^^^^^^

Visualizza un messaggio sul buffer, usando tag e data personalizzati.

Prototipo:

[source,C]
----------------------------------------
void weechat_printf_date_tags (struct t_gui_buffer *buffer, time_t date,
                               const char *tags, const char *message, ...);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer, se NULL il messaggio viene visualizzato
  sul buffer di WeeChat
* 'date': data per il messaggio
* 'tags': lista di tag separati da virgole
* 'message': messaggio da visualizzare

Esempio in C:

[source,C]
----------------------------------------
weechat_printf_date_tags (NULL, time (NULL) - 120, "notify_message",
                          "Messaggio 2 minuti fa, con tag 'notify_message'");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.prnt_date_tags(buffer, date, tags, message)

# esempio
time = int(time.time())
weechat.prnt_date_tags("", time - 120, "notify_message",
    "Messaggio 2 minuti fa, con tag 'notify_message'")
----------------------------------------

[NOTE]
La funzione è chiamata "print_date_tags" negli script ("prnt_date_tags" in Python).

weechat_printf_y
^^^^^^^^^^^^^^^^

Visualizza un messaggio sulla riga di un buffer con contenuto libero.

Prototipo:

[source,C]
----------------------------------------
void weechat_printf_y (struct t_gui_buffer *buffer, int y,
                       const char *message, ...);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'y': numero di riga (la prima riga è 0)
* 'message': messaggio da visualizzare

Esempio in C:

[source,C]
----------------------------------------
weechat_printf_y (buffer, 2, "Mio messaggio sulla terza riga");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.prnt_y(buffer, y, message)

# esempio
weechat.prnt_y("", 2, "Mio messaggio sulla terza riga")
----------------------------------------

[NOTE]
La funzione è chiamata "print_y" negli script ("prnt_y in Python).

weechat_log_printf
^^^^^^^^^^^^^^^^^^

Scrive un messaggio nel file di log di WeeChat (weechat.log).

Prototipo:

[source,C]
----------------------------------------
void weechat_log_printf (const char *message, ...);
----------------------------------------

Argomenti:

* 'message': messaggio da scrivere

Esempio in C:

[source,C]
----------------------------------------
weechat_log_printf ("Mio messaggio nel file di log");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.log_print(message)

# esempio
weechat.log_print("Mio messaggio nel file di log")
----------------------------------------

[NOTE]
La funzione è chiamata "log_print" negli script.

[[hooks]]
Hook
~~~~

[[hook_priority]]
[float]
Priorità degli hook
^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.4._

In alcuni hook è possibile impostare una priorità. Un hook con priorità
maggiore si trova all'inizio della lista, in modo da poter essere eseguita
prima di altri. Può risultare utile per i modificatori, data l'importanza
nell'ordine di esecuzione.

Per impostare la priorità, è necessario usare questa sintassi per gli
argomenti dove è consentita la priorità: "nnn|nome" dove "nnn" è un intero non
negativo con la priorità e "nome" è il nome per l'argomenti (la priorità non
compare nel nome, viene rimossa automaticamente dalla stringa).

La priorità predefinita è 1000.

Esempio in C:

[source,C]
----------------------------------------
/* hook per il modificatore con priorità = 2000 */
weechat_hook_modifier ("2000|input_text_display", &modifier_cb, NULL);
----------------------------------------

I tipi di hook che seguono consentono la priorità: command, command_run,
signal, hsignal, config.

weechat_hook_command
^^^^^^^^^^^^^^^^^^^^

Hook su un comando.

Prototipo:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_command (const char *command,
                                     const char *description,
                                     const char *args,
                                     const char *args_description,
                                     const char *completion,
                                     int (*callback)(void *data,
                                                     struct t_gui_buffer *buffer,
                                                     int argc,
                                                     char **argv,
                                                     char **argv_eol),
                                     void *callback_data);
----------------------------------------

Argomenti:

* 'command': nome del comando
  (priorità consentita, consultare la nota riguardo la <<hook_priority,priority>>)
* 'description': descrizione per il comando (visualizzata con `/help comando`)
* 'args': argomenti per il comando (visualizzati con `/help command`)
* 'args_description': descrizione degli argomenti (visualizzata con `/help command`)
* 'completion': modello di completamento per il comando:: elenco di completamenti
  per ogni argomento, separati da spazio. Sono possibili più  completamenti sono
  possibili per un singolo argomento, separati da "|". Più modelli sono possibili per
  lo stesso comando, separati da "||".
* 'callback': funzione chiamata quando viene utilizzato il comando, argomenti:
** 'void *data': puntatore
** 'struct t_gui_buffer *buffer': buffer quando il comando viene eseguito
** 'int argc': numero di argomenti forniti per un comando
** 'char **argv': argomenti forniti per un comando
** 'char **argv_eol': argomenti forniti per un comando (fino a fine riga per ogni
   argomento)
* 'callback_data': puntatore fornito dalla callback quando chiamata da WeeChat

I codici predefiniti per il completamento sono:
include::autogen/plugin_api/completions.txt[]

Codici speciali:

* '%%command': riutilizza il modello di completamento dal comando 'command'
* '%-': ferma completamento
* '%*': ripete l'ultimo completamento

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
int
my_command_cb (void *data, struct t_gui_buffer *buffer, int argc,
               char **argv, char **argv_eol)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* questo esempio si ispira al comando /filter */
struct t_hook *my_command_hook =
    weechat_hook_command (/* nome comando */
                          "myfilter",
                          /* description */
                          "description of myfilter",
                          /* args */
                          "[list] | [enable|disable|toggle [name]] | "
                          "[add name plugin.buffer tags regex] | "
                          "[del name|-all]",
                          /* args description */
                          "description of arguments...",
                          /* completion */
                          "list"
                          " || enable %(filters_names)"
                          " || disable %(filters_names)"
                          " || toggle %(filters_names)"
                          " || add %(filters_names) %(buffers_plugins_names)|*"
                          " || del %(filters_names)|-all",
                          /* callback */
                          &my_command_cb,
                          /* callback_data */
                          NULL);
----------------------------------------

Ad esempio, se il comando chiamato è `/comando abc def ghi`, allora
argv e argv_eol contengono i seguenti valori:

* 'argv':
** 'argv[0]' == "abc"
** 'argv[1]' == "def"
** 'argv[2]' == "ghi"
* 'argv_eol':
** 'argv_eol[0]' == "abc def ghi"
** 'argv_eol[1]' == "def ghi"
** 'argv_eol[2]' == "ghi"

Script (Python):

[source,python]
----------------------------------------
# prototipo
hook = weechat.hook_command(command, description, args, args_description,
    completion, callback, callback_data)

# esempio
def my_command_cb(data, buffer, args):
    # ...
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_command("myfilter", "descrizione di myfilter",
    "[list] | [enable|disable|toggle [name]] | "
    "[add name plugin.buffer tags regex] | "
    "[del name|-all]",
    "description of arguments...",
    "list"
    " || enable %(filters_names)"
    " || disable %(filters_names)"
    " || toggle %(filters_names)"
    " || add %(filters_names) %(buffers_plugins_names)|*"
    " || del %(filters_names)|-all",
    "my_command_cb", "")
----------------------------------------

weechat_hook_command_run
^^^^^^^^^^^^^^^^^^^^^^^^

Hook su un comando quando eseguito da WeeChat.

Prototipo:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_command_run (const char *command,
                                         int (*callback)(void *data,
                                                         struct t_gui_buffer *buffer,
                                                         const char *command),
                                         void *callback_data);
----------------------------------------

Argomenti:

* 'command': comando su cui eseguire l'hook, può iniziare o terminare con "*"
  (priorità consentita, consultare la nota riguardo la
  <<hook_priority,priority>>)
* 'callback': funzione chiamata quando il comando è in esecuzione, argomenti:
** 'void *data': puntatore
** 'struct t_gui_buffer *buffer': buffer dove viene eseguito il comando
** 'const char *command': il comando eseguito, con i propri argomenti
* 'callback_data': puntatore fornito alla callback quando chiamata da WeeChat

[NOTE]
La callback può restituire 'WEECHAT_RC_OK' o 'WEECHAT_RC_OK_EAT' (il comando
non verrà eseguito da WeeChat dopo la callback).

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
int
my_command_run_cb (void *data, struct t_gui_buffer *buffer,
                   const char *command)
{
    weechat_printf (NULL,
                    "Vuoi completare? Sto mangiando il completamento, ahah!);
    return WEECHAT_RC_OK_EAT;
}

struct t_hook *my_command_run_hook =
    weechat_hook_command_run ("/input complete*",
                              &my_command_run_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
hook = weechat.hook_command_run(command, callback, callback_data)

# esempio
def my_command_run_cb(data, buffer, command):
    weechat.prnt("". "Vuoi completare? Sto mangiando il completamento, ahah!")
    return weechat.WEECHAT_RC_OK_EAT

hook = weechat.hook_command_run("/input complete*", "my_command_run_cb", "")
----------------------------------------

weechat_hook_timer
^^^^^^^^^^^^^^^^^^

Hook sul timer.

Prototipo:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_timer (long interval,
                                   const char *align_second,
                                   const char *max_calls,
                                   int (*callback)(void *data,
                                                   int remaining_calls),
                                   void *callback_data);
----------------------------------------

Argomenti:

* 'interval': intervallo tra due chiamate (millisecondi, 1000 = 1 secondo)
* 'align_second': allineamento su un secondo. Per esempio, rrent time is 09:00,
  if interval = 60000 (60 seconds), and align_second = 60, then timer is
  called each minute when second is 00
* 'max_calls': number of calls to timer (if 0, then timer has no end)
* 'callback': function called when time is reached, arguments:
** 'void *data': pointer
** 'int remaining_calls': remaining calls (-1 if timer has no end)
* 'callback_data': pointer given to callback when it is called by WeeChat

Valore restituito:

* pointer to new hook, NULL if error occured

Esempio in C:

[source,C]
----------------------------------------
int
my_timer_cb (void *data, int remaining_calls)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* timer chiamato ogni 20 secondi */
struct t_hook *my_timer_hook =
    weechat_hook_timer (20 * 1000, 0, 0, &my_timer_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
hook = weechat.hook_timer(interval, align_second, max_calls, callback, callback_data)

# esempio
def my_timer_cb(data, remaining_calls):
    # ...
    return weechat.WEECHAT_RC_OK

# timer chiamato ogni 20 secondi
hook = weechat.hook_timer(20 * 1000, 0, 0, "my_timer_cb", "")
----------------------------------------

weechat_hook_fd
^^^^^^^^^^^^^^^

Hook su un descrittore file (file oppure socket).

Prototipo:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_fd (int fd,
                                int flag_read,
                                int flag_write,
                                int flag_exception,
                                int (*callback)(void *data,
                                                int fd),
                                void *callback_data);
----------------------------------------

Argomenti:

* 'fd': descrittore file
* 'flag_read': 1 = cattura l'evento lettura (read), 0 = ignora
* 'flag_write': 1 = cattura l'evento scrittura (write), 0 = ignora
* 'flag_exception': 1 = cattura l'eccezione evento (event), 0 = ignora
* 'callback': funzione che chiama un evento selezionato che si verifica
  per un file (o un socket), argomenti:
** 'void *data': puntatore
** 'int fd': descrittore file
* 'callback_data': puntatore fornito alla calback quando chiamata da WeeChat

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
int
my_fd_cb (void *data, int fd)
{
    /* ... */
    return WEECHAT_RC_OK;
}

int sock = socket (AF_INET, SOCK_STREAM, 0);
/* imposta le opzioni del socket */
/* ... */
struct t_hook *my_fd_hook = weechat_hook_fd (sock, 1, 0, 0, &my_fd_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
hook = weechat.hook_fd(fd, flag_read, flag_write, flag_exception, callback, callback_data)

# esempio
def my_fd_cb(data, fd):
    # ...
    return weechat.WEECHAT_RC_OK

sock = ...
hook = weechat.hook_fd(sock, 1, 0, 0, "my_fd_cb", "")
----------------------------------------

weechat_hook_process
^^^^^^^^^^^^^^^^^^^^

Hook su un processo (lanciato con un fork), e cattura l'output.

Prototipo:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_process (const char *command,
                                     int timeout,
                                     int (*callback)(void *data,
                                                     const char *command,
                                                     int return_code,
                                                     const char *out,
                                                     const char *err),
                                     void *callback_data);
----------------------------------------


Argomenti:

* 'command': comando da avviare nel processo figlio
* 'timeout': timeout per il comando (in millisecondi): dopo questo timeout,
  il processo figlio viene terminato (0 vuol dire nessun timeout)
* 'callback': funzione chiamata quando i dati dal processo figlio sono disponibili,
  oppure quando è terminato, argomenti:
** 'void *data': puntatore
** 'const char *command': comando eseguito dal processo figlio
** 'int return_code': codice restituito:
*** '>= 0': codice restituito dal comando figlio
*** '< 0': 'WEECHAT_HOOK_PROCESS_OK_RUNNING' (dati disponibili, ma figlio
    ancora in esecuzione) o 'WEECHAT_HOOK_PROCESS_ERROR' (errore nella
    esecuzione del comando)
** 'out': output standard del comando (stdout)
** 'err': output di errore del comando (stderr)
* 'callback_data': puntatore fornito alla callback quando fornita da WeeChat

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
int
my_process_cb (void *data, const char *command, int return_code,
               const char *out, const char *err)
{
    if (return_code == WEECHAT_HOOK_PROCESS_ERROR)
    {
        weechat_printf (NULL, "Errore con il comando '%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 ("ls", 5000,
                                                       &my_process_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
hook = weechat.hook_process(command, timeout, callback, callback_data)

# esempio
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("ls", 5000, "my_process_cb", "")
----------------------------------------

weechat_hook_connect
^^^^^^^^^^^^^^^^^^^^

Hook su una connessione (connessione in secondo piano ad un host remoto).

Prototipo:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_connect (const char *proxy,
                                     const char *address,
                                     int port,
                                     int sock,
                                     int ipv6,
                                     void *gnutls_sess,
                                     void *gnutls_cb,
                                     int gnutls_dhkey_size,
                                     const char *local_hostname,
                                     int (*callback)(void *data,
                                                     int status,
                                                     int gnutls_rc,
                                                     const char *error,
                                                     const char *ip_address),
                                     void *callback_data);
----------------------------------------

Argomenti:

* 'proxy': nome del proxy da utilizzare per la connessione (opzionale,
  NULL significa connessione senza proxy)
* 'address': nome o indirizzo IP al quale connettersi
* 'port': numero della porta
* 'sock': socket utilizzato per la connessione
* 'ipv6': 1 per usare IPv6, 0 per usare IPv4
* 'gnutls_sess': sessione GnuTLS (opzionale)
* 'gnutls_cb' callback GnuTLS (opzionale)
* 'gnutls_dhkey_size': dimensione della chiave utilizzata nello Scambio
  Chiavi Diffie-Hellman (GnuTLS)
* 'local_hostname': nome host locale da utilizzare per la connessione
  (opzionale)
* 'callback': funzione chiamata quando la connessione è avvenuta con
  successo oppure no, argomenti:
** 'void *data': puntatore
** 'int status': stato della connessione:
*** 'WEECHAT_HOOK_CONNECT_OK': connessione avvenuta con successo
*** 'WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND': indirizzo non trovato
*** 'WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND': indirizzo IP non trovato
*** 'WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED': connessione rifiutata
*** 'WEECHAT_HOOK_CONNECT_PROXY_ERROR': errore con il proxy
*** 'WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR': errore con il nome host locale
*** 'WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR': errore inizializzazione GnuTLS
*** 'WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR': errore di handshake GnuTLS
*** 'WEECHAT_HOOK_CONNECT_MEMORY_ERROR': memoria insufficiente
** 'gnutls_rc': valore del risultato di 'gnutls_handshake()'
** 'const char *error': valore del risultato di 'gnutls_strerror(gnutls_rc)'
** 'const char *ip_address': indirizzo IP trovato
* 'callback_data': puntatore fornito alla callback quando chiamata da WeeChat

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
int
my_connect_cb (void *data, int status, int gnutls_rc, const char *error,
               const char *ip_address)
{
    switch (status)
    {
        case WEECHAT_HOOK_CONNECT_OK:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_PROXY_ERROR:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_MEMORY_ERROR:
            /* ... */
            break;
    }
    return WEECHAT_RC_OK;
}

struct t_hook *my_connect_hook = weechat_hook_connect (NULL,
                                                       "my.server.org", 1234,
                                                       sock, 0,
                                                       NULL, NULL, 0, /* GnuTLS */
                                                       NULL,
                                                       &my_connect_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
hook = weechat.hook_connect(proxy, address, port, sock, ipv6, local_hostname,
    callback, callback_data)

# esempio
def my_connect_cb(data, status, gnutls_rc, error, ip_address):
    if status == WEECHAT_HOOK_CONNECT_OK:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_PROXY_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_MEMORY_ERROR:
        # ...
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_connect("", "my.server.org", 1234, sock, 0, "",
                            "my_connect_cb", "")
----------------------------------------

weechat_hook_print
^^^^^^^^^^^^^^^^^^

Hook su un messaggio stampato.

Prototipo:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_print (struct t_gui_buffer *buffer,
                                   const char *tags,
                                   const char *message,
                                   int strip_colors,
                                   int (*callback)(void *data,
                                                   struct t_gui_buffer *buffer,
                                                   time_t date,
                                                   int tags_count,
                                                   const char **tags,
                                                   int displayed,
                                                   int highlight,
                                                   const char *prefix,
                                                   const char *message),
                                   void *callback_data);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer, se NULL, verranno catturati i messaggi da qualsiasi
  buffer
* 'tags': verranno catturati solo messaggi con queste tag (elenco separato da virgole)
  (opzionale)
* 'message': verranno catturati solo i messaggi con questa stringa (opzionale)
* 'strip_colors': se 1, i colori verranno estratti dal messaggio visualizzato, prima
  di chiamare la callback
* 'callback': funzione chiamata quando viene stampato un messaggio, argomenti:
** 'void *data': puntatore
** 'struct t_gui_buffer *buffer': puntatore al buffer
** 'time_t date': data
** 'int tags_count': numero di tag per riga
** 'const char **tags': array con tag per riga
** 'int displayed': 1 se la riga è visualizzata, 0 se filtrata (nascosta)
** 'int highlight': 1 se la riga viene evidenziata, altrimenti 0
** 'const char *prefix': prefisso
** 'const char *message': messaggio
* 'callback_data': puntatore fornito alla callback quando chiamata da WeeChat

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
int
my_print_cb (void *data, struct t_gui_buffer *buffer, time_t date,
             int tags_count, const char **tags,
             int displayed, int highlight,
             const char *prefix, const char *message)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* cattura tutti i messaggi, su tutti i buffer, senza colore */
struct t_hook *my_print_hook =
    weechat_hook_print (NULL, NULL, NULL, 1, &my_print_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
hook = weechat.hook_print(buffer, tags, message, strip_colors, callback, callback_data)

# esempio
def my_print_cb(data, buffer, date, tags, displayed, highlight, prefix, message):
    # ...
    return weechat.WEECHAT_RC_OK

# cattura tutti i messaggi, su tutti i buffer, senza colore
hook = weechat.hook_print("", "", "", 1, "my_print_cb", "")
----------------------------------------

weechat_hook_signal
^^^^^^^^^^^^^^^^^^^

Hook su un segnale.

Prototipo:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_signal (const char *signal,
                                    int (*callback)(void *data,
                                                    const char *signal,
                                                    const char *type_data,
                                                    void *signal_data),
                                    void *callback_data);
----------------------------------------

Argomenti:

* 'signal': segnale da catturare, può iniziare o terminare con "*"
  (priorità consentita, consultare la nota riguardo la
  <<hook_priority,priority>>):

[width="100%",cols="^1,^3,^4,5",options="header"]
|========================================
| Plugin | Segnale | Argomenti | Descrizione

| irc | xxx,irc_in_yyy ^(1)^ | string: messaggio |
  messaggio irc dal server (prima di essere utilizzato
  dal plugin irc, il segnale viene inviato solo se il
  messaggio *non* viene ignorato)

| irc | xxx,irc_in2_yyy ^(1)^ | string: messaggio |
  messaggio irc dal server (dopo essere stato
  utilizzato dal plugin irc, il segnale viene inviato
  solo se il messaggio *non* viene ignorato)

| irc | xxx,irc_raw_in_yyy ^(1)^ | string: messaggio |
  messaggio irc dal server (prima di essere utilizzato
  dal plugin irc, il segnale viene inviato anche se il
  messaggio è stato ignorato)

| irc | xxx,irc_raw_in2_yyy ^(1)^ | string: messaggio |
  messaggio irc dal server (dopo essere stato
  utilizzato dal plugin irc, il segnale viene inviato
  anche se il messaggio è stato ignorato)

| irc | xxx,irc_out_yyy ^1^ | string: messaggio |
  messaggio irc inviato al server

| irc | xxx,irc_outtags_yyy ^(1)^ | stringa: tag + ";" + messaggio |
  tag + messaggio irc inviato al server

| irc | irc_ctcp | string: messaggio |
  CTCP ricevuto

| irc | irc_dcc | string: messaggio |
  nuova DCC

| irc | irc_pv | string: messaggio |
  messaggio privato ricevuto

| irc | irc_channel_opened | puntatore: buffer |
  canale aperto

| irc | irc_pv_opened | puntatore: buffer |
  chat privata aperta

| irc | irc_server_connecting | string: nome server |
  connessione al server

| irc | irc_server_connected | string: nome server |
  connesso al server

| irc | irc_server_disconnected | string: nome server |
  disconnesso dal server

| irc | irc_ignore_removing | puntatore: ignore |
  rimozione dell'ignore

| irc | irc_ignore_removed | - |
  ignore rimosso

| logger | logger_start | puntatore: buffer |
  avvia il logging per il buffer

| logger | logger_stop | puntatore: buffer |
  ferma il logging per il buffer

| logger | logger_backlog | puntatore: buffer |
  visualizza log precedenti per il buffer

| weechat | buffer_closing | puntatore: buffer |
  chiusura del buffer

| weechat | buffer_closed | puntatore: buffer |
  buffer chiuso

| weechat | buffer_lines_hidden | puntatore: buffer |
  righe nascoste nel buffer

| weechat | buffer_localvar_added | puntatore: buffer |
  variabili locali aggiunte

| weechat | buffer_localvar_changed | puntatore: buffer |
  variabili locali modificate

| weechat | buffer_localvar_removed | puntatore: buffer |
  variabili locali rimosse

| weechat | buffer_moved | puntatore: buffer |
  buffer spostato

| weechat | buffer_opened | puntatore: buffer |
  buffer aperto

| weechat | buffer_renamed | puntatore: buffer |
  buffer rinominato

| weechat | buffer_switch | puntatore: buffer |
  passaggio tra buffer

| weechat | buffer_title_changed | puntatore: buffer |
  titolo del buffer modificato

| weechat | buffer_type_changed | puntatore: buffer |
  tipo di buffer modificato

| weechat | debug_dump | stringa: nome plugin |
  richiesta di dump

| weechat | day_changed | string: nuova data, formato: "2010-01-31" |
  data di sistema modificata

| weechat | filter_added | puntatore: filtro |
  filtro aggiunto

| weechat | filter_removing | puntatore: filtro |
  rimozione del filtro

| weechat | filter_removed | - |
  filtro rimosso

| weechat | filter_enabled | - |
  filtri abilitati

| weechat | filter_disabled | - |
  filtri disabilitati

| weechat | hotlist_changed | - |
  hotlist modificata

| weechat | input_paste_pending | - |
  incolla testo in attesa

| weechat | input_search | - |
  ricerca testo nel buffer

| weechat | input_text_changed | - |
  testo in input modificato

| weechat | input_text_cursor_moved | - |
  cursore del testo di input spostato

| weechat | key_pressed | string: tasto digitato |
  tasto digitato

| weechat | nicklist_group_added | string: buffer pointer + "," + group name |
  group added in nicklist

| weechat | nicklist_group_removed | string: buffer pointer + "," + group name |
  group removed from nicklist

| weechat | nicklist_nick_added | string: buffer pointer + "," + nick name |
  nick added in nicklist

| weechat | nicklist_nick_removed | string: buffer pointer + "," + nick name |
  nick removed from nicklist

| weechat | partial_completion | - |
  completamento parziale avvenuto

| weechat | quit | string: argomenti per /quit |
  comando `/quit` digitato dall'utente

| weechat | upgrade | - |
  comando `/upgrade` digitato dall'utente

| weechat | weechat_highlight | string: messaggio con prefisso |
  evento accaduto

| weechat | weechat_pv | string: messaggio con prefisso |
  messaggio privato visualizzato

| weechat | window_scrolled | puntatore: finestra |
  scroll nella finestra

| weechat | window_unzooming | puntatore: finestra corrente |
  minimizzazione della finestra

| weechat | window_unzoomed | puntatore: finestra corrente |
  window unzoomed
  finestra minimizzata

| weechat | window_zooming | puntatore: finestra corrente |
  massimizzazione della finestra

| weechat | window_zoomed | puntatore: finestra corrente |
  finestra massimizzata

| xfer | xfer_add | puntatore: lista info con info per xfer|
  nuovo xfer

| xfer | xfer_send_ready | puntatore: lista info xon info per xfer |
  xfer pronto

| xfer | xfer_accept_resume | puntatore: lista info con info per xfer |
  xfer accetta la ripresa

| xfer | xfer_send_accept_resume | puntatore: lista info con info per xfer |
  xfer accetta la ripresa (invio)

| xfer | xfer_start_resume |  puntatore: lista info con info per xfer |
  avvia ripresa

| xfer | xfer_resume_ready | puntatore: lista info con info per xfer |
  ripresa xfer pronta

| xfer | xfer_ended | puntatore: lista info con info per xfer |
  xfer terminato

|========================================

[NOTE]
^(1)^ 'xxx' è il nome del server IRC, 'yyy' è il nome del comando IRC.

* 'callback': funzione chiamata a segnale ricevuto, argomenti:
** 'void *data': puntatore
** 'const char *signal': segnale ricevuto
** 'const char *type_data': tipo di dati inviati con il segnale:
*** 'WEECHAT_HOOK_SIGNAL_STRING': stringa
*** 'WEECHAT_HOOK_SIGNAL_INT': numero intero
*** 'WEECHAT_HOOK_SIGNAL_POINTER': puntatore
** 'void *signal_data': dati inviati con il segnale
* 'callback_data': puntatore fornito alla callback quando chiamata da WeeChat

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
int
my_signal_cb (void *data, const char *signal, const char *type_data,
              void *signal_data)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* cattura il segnale "quit" */
struct t_hook *my_signal_hook = weechat_hook_signal ("quit",
                                                     &my_signal_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
hook = weechat.hook_signal(signal, callback, callback_data)

# esempio
def my_signal_cb(data, signal, signal_data):
    # ...
    return weechat.WEECHAT_RC_OK

# cattura il segnale "quit"
hook = weechat.hook_signal("quit", "my_signal_cb", "")
----------------------------------------

weechat_hook_signal_send
^^^^^^^^^^^^^^^^^^^^^^^^

Invia un segnale.

Prototipo:

[source,C]
----------------------------------------
void weechat_hook_signal_send (const char *signal, const char *type_data,
                               void *signal_data);
----------------------------------------

Argomenti:

* 'signal': segnale da inviare
* 'type_data': tipo di dati inviati con il segnale (consultare
  <<_weechat_hook_signal,weechat_hook_signal>>)
* 'signal_data': dati inviati con il segnale

Esempio in C:

[source,C]
----------------------------------------
weechat_hook_signal_send ("my_signal", WEECHAT_HOOK_SIGNAL_STRING, my_string);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.hook_signal_send(signal, type_data, signal_data)

# esempio
weechat.hook_signal_send("my_signal", weechat.WEECHAT_HOOK_SIGNAL_STRING, my_string)
----------------------------------------

// TRANSLATION MISSING
[[signal_logger_backlog]]
Signal logger_backlog
+++++++++++++++++++++

The signal "logger_backlog" can be sent to display backlog (chat history) in
buffer (for example if you open your own buffer in your plugin/script).

Argument is a pointer to buffer.

C example:

[source,C]
----------------------------------------
weechat_hook_signal_send ("logger_backlog", WEECHAT_HOOK_SIGNAL_POINTER, buffer);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
weechat.hook_signal_send("logger_backlog", weechat.WEECHAT_HOOK_SIGNAL_POINTER, buffer)
----------------------------------------

// TRANSLATION MISSING
[[signals_xxx_script_install]]
Signals xxx_script_install
++++++++++++++++++++++++++

Five signals can be sent to install a script, according to language:

* 'perl_script_install'
* 'python_script_install'
* 'ruby_script_install'
* 'lua_script_install'
* 'tcl_script_install'

The callback will do following actions when receiving signal:

. unload and remove installed script
. move new script to directory '~/.weechat/xxx/' (where 'xxx' is language) 
. create link to new script in directory '~/.weechat/xxx/autoload/'
. load new script

These signals are used by script 'weeget.py' to install scripts.

Argument is a string with path to script to install.

C example:

[source,C]
----------------------------------------
weechat_hook_signal_send ("python_script_install", WEECHAT_HOOK_SIGNAL_STRING,
                          "/home/xxx/.weechat/test.py");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
weechat.hook_signal_send("python_script_install", WEECHAT_HOOK_SIGNAL_STRING,
                         "/home/xxx/.weechat/test.py")
----------------------------------------

// TRANSLATION MISSING
[[signals_xxx_script_remove]]
Signals xxx_script_remove
+++++++++++++++++++++++++

Five signals can be sent to remove list of scripts, according to language:

* 'perl_script_remove'
* 'python_script_remove'
* 'ruby_script_remove'
* 'lua_script_remove'
* 'tcl_script_remove'

For each script in list, the callback will unload then remove script.

These signals are used by script 'weeget.py' to remove scripts.

Argument is a string with comma-separated list of script to remove (script
is name without path, for example 'script.py').

C example:

[source,C]
----------------------------------------
/* unload and remove scripts test.py and script.py */
weechat_hook_signal_send ("python_script_remove", WEECHAT_HOOK_SIGNAL_STRING,
                          "test.py,script.py");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# unload and remove scripts test.py and script.py
weechat.hook_signal_send("python_script_remove", WEECHAT_HOOK_SIGNAL_STRING,
                         "test.py,script.py")
----------------------------------------

// TRANSLATION MISSING
[[signal_irc_input_send]]
Signal irc_input_send
+++++++++++++++++++++

_New in version 0.3.4._

The signal "irc_input_send" can be sent to simulate input in an irc buffer
(server, channel or private).

Argument is a string with following format:

* internal server name (required)
* semicolon
* channel name (optional)
* semicolon
* flags used when sending message (optional, default is 1):
** '1': queue with high priority (like user messages)
** '2': queue with low priority (like messages automatically sent by WeeChat)
* semicolon
* comma-separated list of tags used when sending message (optional)
* semicolon
* text or command (required)

C examples:

[source,C]
----------------------------------------
/* say "Hello!" on freenode server, #weechat channel */
weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING,
                          "freenode;#weechat;1;;Hello!");

/* send command "/whois FlashCode" on freenode server, with low priority */
weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING,
                          "freenode;;2;;/whois FlashCode");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# say "Hello!" on freenode server, #weechat channel
weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING,
                         "freenode;#weechat;1;;Hello!")

# send command "/whois FlashCode" on freenode server, with low priority
weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING,
                         "freenode;;2;;/whois FlashCode")
----------------------------------------

weechat_hook_hsignal
^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.4._

Hook su hsignal (segnale con tabella hash).

Prototipo:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_hsignal (const char *signal,
                                     int (*callback)(void *data,
                                                     const char *signal,
                                                     struct t_hashtable *hashtable),
                                     void *callback_data);
----------------------------------------

Argomenti:

* 'signal': segnale da catturare, può iniziare o terminare con "*"
  (priorità consentita, consultare la nota a proposito di <<hook_priority,priority>>):

[width="100%",cols="^1,^3,5",options="header"]
|========================================
| Plugin | Segnale | Argomenti

| irc | irc_redirection_xxx_yyy ^(1)^ |
  redirection output (consultare <<hsignal_irc_redirect_command>>)
|========================================

[NOTE]
^(1)^ 'xxx' è l'argomento del segnale usato nella redirezione, 'yyy' è lo schema
di redirezione.

* 'callback': funzione chiamata a segnale ricevuto, argomenti:
** 'void *data': puntatore
** 'const char *signal': segnale ricevuto
** 'struct t_hashtable *hashtable': tabella hash
* 'callback_data': puntatore fornito alla callback quando chiamata da WeeChat

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
int
my_hsignal_cb (void *data, const char *signal, struct t_hashtable *hashtable)
{
    /* ... */
    return WEECHAT_RC_OK;
}

struct t_hook *my_hsignal_hook = weechat_hook_hsignal ("test",
                                                       &my_hsignal_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
hook = weechat.hook_hsignal(signal, callback, callback_data)

# esempio
def my_hsignal_cb(data, signal, hashtable):
    # ...
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_hsignal("test", "my_hsignal_cb", "")
----------------------------------------

weechat_hook_hsignal_send
^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.4._

Invia un hsignal (segnale con tabella hash).

Prototipo:

[source,C]
----------------------------------------
void weechat_hook_hsignal_send (const char *signal, struct t_hashtable *hashtable);
----------------------------------------

Argomenti:

* 'signal': segnale da inviare
* 'hashtable': tabella hash

Esempio in C:

[source,C]
----------------------------------------
struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       NULL,
                                                       NULL);
if (hashtable)
{
    weechat_hashtable_set (hashtable, "key", "value");
    weechat_hook_hsignal_send ("my_hsignal", hashtable);
    weechat_hashtable_free (hashtable);
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.hook_hsignal_send(signal, hashtable)

# esempio
weechat.hook_hsignal_send("my_hsignal", { "key": "value" })
----------------------------------------

// TRANSLATION MISSING
[[hsignal_irc_redirect_command]]
Hsignal irc_redirect_command
++++++++++++++++++++++++++++

_New in version 0.3.4._

The hsignal "irc_redirect_command" can be sent to redirect output of irc
command to a callback.

Argument is a hashtable with following entries (keys and values are string):

* 'server': internal server name (required)
* 'pattern': redirect pattern to use (required), either a default one (defined
  by irc plugin), or a user pattern (see <<hsignal_irc_redirect_pattern>>),
  default patterns are:
** 'ison'
** 'list'
** 'mode_channel'
** 'mode_channel_ban' ("mode #channel b")
** 'mode_channel_ban_exception' ("mode #channel e")
** 'mode_channel_invite' ("mode #channel I")
** 'mode_user'
** 'names'
** 'ping'
** 'time'
** 'topic'
** 'userhost'
** 'who'
** 'whois'
** 'whowas'
* 'signal': signal name (required)
* 'count': number of times redirection will work (optional, 1 by default)
* 'string': string that must be in irc messages received (optional, but
  recommended, if a string can be used to identify messages)
* 'timeout': timeout for redirect, in seconds (optional, 60 by default)
* 'cmd_filter': comma-separated list of irc commands to filter (only these
  commands will be sent to callbacks, other will be ignored) (optional)

Immediately after sending this hsignal, you must send command to irc server,
and redirection will be used for this command.

C example:

[source,C]
----------------------------------------
int
test_whois_cb (void *data, const char *signal, struct t_hashtable *hashtable)
{
    weechat_printf (NULL, "error = %s", weechat_hashtable_get (hashtable, "error"));
    weechat_printf (NULL, "output = %s", weechat_hashtable_get (hashtable, "output"));
    return WEECHAT_RC_OK;
}

weechat_hook_hsignal ("irc_redirection_test_whois", &test_whois_cb, NULL);
struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       WEECHAT_HASHTABLE_INTEGER,
                                                       NULL,
                                                       NULL);
if (hashtable)
{
    weechat_hashtable_set (hashtable, "server", "freenode");
    weechat_hashtable_set (hashtable, "pattern", "whois");
    weechat_hashtable_set (hashtable, "signal", "test");
    weechat_hashtable_set (hashtable, "string", "FlashCode");
    weechat_hook_hsignal_send ("irc_redirect_command", hashtable);
    weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING,
                              "freenode;;2;;/whois FlashCode");
    weechat_hashtable_free (hashtable);
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
def test_whois_cb(data, signal, hashtable):
    weechat.prnt("", "error = %s" % hashtable["error"])
    weechat.prnt("", "output = %s" % hashtable["output"])
    return weechat.WEECHAT_RC_OK
}

weechat.hook_hsignal ("irc_redirection_test_whois", "test_whois_cb", "")
weechat.hook_hsignal_send("irc_redirect_command",
                          { "server": "freenode", "pattern": "whois", "signal": "test",
                            "string": "FlashCode" })
weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING,
                         "freenode;;2;;/whois FlashCode")
----------------------------------------

// TRANSLATION MISSING
[[hsignal_irc_redirect_pattern]]
Hsignal irc_redirect_pattern
++++++++++++++++++++++++++++

_New in version 0.3.4._

The hsignal "irc_redirect_pattern" can be sent to create a pattern for irc
redirect (see <<hsignal_irc_redirect_command>>).

Argument is a hashtable with following entries (keys and values are string):

* 'pattern': name of pattern (required)
* 'timeout': default timeout for pattern in, seconds (optional, 60 by default)
* 'cmd_start': comma-separated list of commands starting redirect (optional)
* 'cmd_stop': comma-separated list of commands stopping redirect (required)
* 'cmd_extra': comma-separated list of commands that may be received
  after stop commands (optional)

For each command in 'cmd_start', 'cmd_stop' and 'cmd_extra', it is possible to
give integer with position of "string" that must be found in received message,
for example:

----------------------------------------
352:1,354,401:1
----------------------------------------

For commands 352 and 401, "string" must be found in received message,
as first argument.

[IMPORTANT]
The pattern is destroyed when it is used by a redirection. If you need pattern
for many redirections, you must create pattern before each redirect.

C example:

[source,C]
----------------------------------------
struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       WEECHAT_HASHTABLE_INTEGER,
                                                       NULL,
                                                       NULL);
if (hashtable)
{
    weechat_hashtable_set (hashtable, "pattern", "my_whois");
    weechat_hashtable_set (hashtable, "timeout", "30");
    weechat_hashtable_set (hashtable, "cmd_start", "311:1");
    weechat_hashtable_set (hashtable, "cmd_stop", "318:1,401:1,402:1,431:1,461");
    weechat_hashtable_set (hashtable, "cmd_extra", "318:1");
    weechat_hook_hsignal_send ("irc_redirect_pattern", hashtable);
    /*
     * now redirect irc whois command with hsignal irc_redirect_command,
     * using pattern "my_whois"
     */
    /* ... */
    weechat_hashtable_free (hashtable);
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
weechat.hook_hsignal_send("irc_redirect_pattern",
                          { "pattern": "my_whois", "timeout": "30",
                            "cmd_start": "311:1",
                            "cmd_stop": "318:1,401:1,402:1,431:1,461",
                            "cmd_extra": "318:1" })
# now redirect irc whois command with hsignal irc_redirect_command
# using pattern "my_whois"
# ...
----------------------------------------

weechat_hook_config
^^^^^^^^^^^^^^^^^^^

Hook su un'opzione di configurazione.

Prototipo:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_config (const char *option,
                                    int (*callback)(void *data,
                                                    const char *option,
                                                    const char *value),
                                    void *callback_data);
----------------------------------------

Argomenti:

* 'option': opzione, il formato è il nome completo, come usato con il comando
  `/set` (ad esempio: `weechat.look.item_time_format`)
  (priorità consentita, consultare la note riguardo la
  <<hook_priority,priority>>)
* 'callback': funzione chiamata quando l'opzione di configurazione è cambiata,
  argomenti:
** 'void *data': puntatore
** 'const char *option': nome dell'opzione
** 'const char *value': nuovo valore per l'opzione
* 'callback_data': puntatore fornito alla callback quando chiamata da WeeChat

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
int
my_config_cb (void *data, const char *option, const char *value)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* cattura le modifiche dell'opzione "weechat.look.item_time_format" */
struct t_hook *my_config_hook = weechat_hook_config ("weechat.look.item_time_format",
                                                     &my_config_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
hook = weechat.hook_config(option, callback, callback_data)

# esempio
def my_config_cb(data, option, value):
    # ...
    return weechat.WEECHAT_RC_OK

# cattura le modifiche dell'opzione "weechat.look.item_time_format"
hook = weechat.hook_config("weechat.look.item_time_format", "my_config_cb", "")
----------------------------------------

weechat_hook_completion
^^^^^^^^^^^^^^^^^^^^^^^

Hook su un completamento.

Prototipo:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_completion (const char *completion_item,
                                        const char *description,
                                        int (*callback)(void *data,
                                                        const char *completion_item,
                                                        struct t_gui_buffer *buffer,
                                                        struct t_gui_completion *completion),
                                        void *callback_data);
----------------------------------------

Argomenti:

* 'completion_item': nome dell'elemento del completamento, è possibile usare
  in seguito '%(name)' in un comando con un hook (argomento 'completion')
  (priorità consentita, consultare la nota riguardo la
  <<hook_priority,priority>>)
* 'callback': funzione chiamata quando viene usato l'elemento completamento
  (l'utente sta completando qualcosa usando questo elemento), argomenti:
** 'void *data': puntatore
** 'const char *completion_item': nome dell'elemento del completamento
** 'struct t_gui_buffer *buffer': buffer dove viene eseguito il completamento
** 'struct t_gui_completion *completion': struttura usata per aggiungere
   parole per il completamento (consultare
   <<_weechat_hook_completion_list_add,weechat_hook_completion_list_add>>)
* 'callback_data': puntatore fornito alla callback quando chiamata da WeeChat

[NOTE]
I nomi del completamento sono globali (condivisi tra WeeChat e plugin). Si
raccomanda pertanto di scegliere un nome con un prefisso unico, come
"plugin_xxx" (dove "xxx" è il nome del proprio elemento).

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
int
my_completion_cb (void *data, const char *completion_item,
                  struct t_gui_buffer *buffer,
                  struct t_gui_completion *completion)
{
    weechat_hook_completion_list_add (completion, "word1",
                                      0, WEECHAT_LIST_POS_SORT);
    weechat_hook_completion_list_add (completion, "test_word2",
                                      0, WEECHAT_LIST_POS_SORT);
    return WEECHAT_RC_OK;
}

struct t_hook *my_completion_hook = weechat_hook_completion ("plugin_item",
                                                             "my custom completion!",
                                                             &my_completion_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
hook = weechat.hook_completion(completion_item, description, callback, callback_data)

# esempio
def my_completion_cb(data, completion_item, buffer, completion):
    weechat.hook_completion_list_add(completion, "word1", 0, weechat.WEECHAT_LIST_POS_SORT)
    weechat.hook_completion_list_add(completion, "test_word2", 0, weechat.WEECHAT_LIST_POS_SORT)
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_completion("plugin_item", "my custom completion!",
                               "my_completion_cb", "")
----------------------------------------

// TRANSLATION MISSING
weechat_hook_completion_get_string
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_New in version 0.3.4._

Get a completion property as string.

Prototype:

[source,C]
----------------------------------------
const char *weechat_hook_completion_get_string (struct t_gui_completion *completion,
                                                const char *property);
----------------------------------------

Arguments:

* 'completion': completion pointer
* 'property': property name:
** 'base_command': command used for completion
** 'base_word': word being completed
** 'args': command arguments (including base word)

C example:

[source,C]
----------------------------------------
int
my_completion_cb (void *data, const char *completion_item,
                  struct t_gui_buffer *buffer,
                  struct t_gui_completion *completion)
{
    /* get arguments of command */
    const char *args = weechat_hook_completion_get_string (completion, "args");
    
    /* completion depending on args */
    /* ... */
    
    return WEECHAT_RC_OK;
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
value = weechat.hook_completion_get_string(completion, property)

# example
def my_completion_cb(data, completion_item, buffer, completion):
    # get arguments of command
    args = weechat.hook_completion_get_string(completion, "args")
    # completion depending on args
    # ...
    return weechat.WEECHAT_RC_OK
----------------------------------------

weechat_hook_completion_list_add
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Aggiunge una parola per il completamento.

Prototipo:

[source,C]
----------------------------------------
void weechat_hook_completion_list_add (struct t_gui_completion *completion,
                                       const char *word,
                                       int nick_completion,
                                       const char *where);
----------------------------------------

Argomenti:

* 'completion': puntatore al completamento
* 'word': parola da aggiungere
* 'nick_completion': 1 se la parola è un nick, altrimenti 0
* 'where': posizione in cui la parola sarà inserita nella lista:
** 'WEECHAT_LIST_POS_SORT': qualunque posizione, per mantenere
   la lista ordinata
** 'WEECHAT_LIST_POS_BEGINNING': inizio della lista
** 'WEECHAT_LIST_POS_END': fine della lista

Esempio in C: consultare <<_weechat_hook_completion,weechat_hook_completion>>.

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.hook_completion_list_add(completion, word, nick_completion, where)

# esempio: consultare function hook_completion precedente
----------------------------------------

weechat_hook_modifier
^^^^^^^^^^^^^^^^^^^^^

Hook su un modificatore.

Prototipo:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_modifier (const char *modifier,
                                      char *(*callback)(void *data,
                                                        const char *modifier,
                                                        const char *modifier_data,
                                                        const char *string),
                                      void *callback_data);
----------------------------------------

Argomenti:

* 'modifier': nome modificatore, lista di modificatori utilizzati da
  Weechat o dai plugin
  (priorità consentita, consultare la nota riguardo la
  <<hook_priority,priority>>)

[width="100%",cols="^1,^2,3,4,4",options="header"]
|========================================
| Plugin | Modificatore | Dati modificatore | Stringa | Output

| charset | charset_decode |
  plugin.buffer_name |
  qualsiasi stringa |
  stringa codificata dal set caratteri trovato per plugin/buffer in UTF-8

| charset | charset_encode |
  plugin.buffer_name |
  qualsiasi stringa |
  stringa codificata da UTF-8 al set caratteri trovato per il plugin/buffer

| irc | irc_color_decode |
  "1" per mantenere i colori, "0" per rimuovere i colori |
  qualsiasi stringa |
  stringa con i codici colori di Weechat, o senza colore

| irc | irc_color_encode |
  "1" per mantenere i colori, "0" per rimuovere i colori |
  qualsiasi stringa |
  stringa con i codici colori IRC, o senza colore

| irc | irc_in_xxx ^1^ |
  nome server |
  contenuto del messaggio ricevuto dal server IRC |
  nuovo contenuto del messaggio

| irc | irc_out_xxx ^1^ |
  nome server |
  contenuto del messaggio che sta per essere inviato al server IRC |
  nuovo contenuto del messaggio

| weechat | bar_condition_yyy ^2^ |
  stringa con puntatore alla finestra ("0x123..") |
  stringa vuota |
  "1" per visualizzare la barra, "0" per nasconderla

| weechat | history_add |
  stringa con puntatore al buffer ("0x123..") |
  input buffer (from user) to add in command history (buffer and global) |
  string added to command history

| weechat | input_text_content |
  stringa con puntatore al buffer ("0x123..") |
  input buffer (dall'utente) |
  nuovo contenuto del buffer di input

| weechat | input_text_display |
  stringa con puntatore al buffer ("0x123..") |
  buffer di input (dall'utente), senza tag di cursore |
  nuovo contenuto del buffer di input, solo per visualizzazione (il buffer
  di input non è modificato)

| weechat | input_text_display_with_cursor |
  stringa con puntatore al buffer ("0x123..") |
  buffer di input (dall'utente), con tag di cursore |
  nuovo contenuto del buffer di input, solo per la visualizzazione (buffer di
  input non è modificato)

| weechat | weechat_print |
  plugin;buffer_name;tags |
  messaggio stampato |
  nuovo messaggio stampato
|========================================

[NOTE]
^1^ 'xxx' è il nome del comando IRC. +
^2^ 'yyy' è il nome della barra.

* 'callback': funzione chiamata quando viene usato il modificatore,
  argomenti:
** 'void *data': puntatore
** 'const char *modifier': nome del modificatore
** 'const char *modifier_data': dati per il modificatore
** 'const char *string': stringa da modificare (la funzione deve restituire
   una copia di questa stringa, non è consentito alcun cambiamento in
    questa stringa)
* 'callback_data': puntatore fornito alla callback quando chiamata da WeeChat

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
char *
my_modifier_cb (void *data, const char *modifier,
                const char *modifier_data,
                const char *string)
{
    char *result;
    int length;
    
    if (!string)
        return NULL;
    
    length = strlen (string) + 5;
    result = malloc (length);
    if (result)
    {
        /* aggiunge "xxx" ad ogni messaggio stampato */
        snprintf (result, length, "%s xxx", string);
    }
    
    return result;
}

struct t_hook *my_modifier_hook = weechat_hook_modifier ("weechat_print",
                                                         &my_modifier_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
hook = weechat.hook_modifier(modifier, callback, callback_data)

# esempio
def my_modifier_cb(data, modifier, modifier_data, string):
    return "%s xxx" % string

hook = weechat.hook_modifier("weechat_print", "my_modifier_cb", "")
----------------------------------------

weechat_hook_modifier_exec
^^^^^^^^^^^^^^^^^^^^^^^^^^

Esegue modificatore(i).

Prototipo:

[source,C]
----------------------------------------
char *weechat_hook_modifier_exec (const char *modifier,
                                  const char *modifier_data,
                                  const char *string);
----------------------------------------

Argomenti:

* 'modifier': nome modificatore
* 'modifier_data': dati modificatore
* 'string': stringa da modificare

Valore restituito:

* stringa modificata, NULL se nessun cambiamento nella stringa è
  stato effettuato dal modificatore(i).

Esempio in C:

[source,C]
----------------------------------------
char *new_string = weechat_hook_modifier_exec ("my_modifier",
                                               my_data, my_string);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.hook_modifier_exec(modifier, modifier_data, string)

# esempio
weechat.hook_modifier_exec("my_modifier", my_data, my_string)
----------------------------------------

weechat_hook_info
^^^^^^^^^^^^^^^^^

Hook su una informazione (la callback prende e restituisce una stringa).

Prototipo:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_info (const char *info_name,
                                  const char *description,
                                  const char *args_description,
                                  const char *(*callback)(void *data,
                                                          const char *info_name,
                                                          const char *arguments),
                                  void *callback_data);
----------------------------------------

Argomenti:

* 'info_name': nome della info
  (priorità consentita, consultare la nota riguardo la
  <<hook_priority,priority>>)
* 'description': descrizione
* 'args_description': descrizione degli argomenti
* 'callback': funzione chiamata alla richiesta di una info, argomenti:
** 'void *data': puntatore
** 'const char *info_name': nome della info
** 'const char *arguments': argomenti addizionali, dipendono dalle info
* 'callback_data': puntatore fornito alla callback quando chiamata da WeeChat

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
const char *
my_info_cb (void *data, const char *info_name, const char *arguments)
{
    /* ... */
    return pointer_to_string;
}

/* aggiunge informazione "my_info" */
struct t_hook *my_info_hook = weechat_hook_info ("my_info",
                                                 "Some info",
                                                 "Info about arguments",
                                                 &my_info_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
hook = weechat.hook_info(info_name, description, args_description, callback, callback_data)

# esempio
def my_info_cb(data, info_name, arguments):
    return "some_info"

hook = weechat.hook_info("my_info", "Some info", "Info about arguments",
                         "my_info_cb", "")
----------------------------------------

weechat_hook_info_hashtable
^^^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.4._

Hook su una informazione (la callback prende e restituisce una tabella hash).

Prototype:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_info_hashtable (const char *info_name,
                                            const char *description,
                                            const char *args_description,
                                            const char *output_description,
                                            struct t_hashtable *(*callback)(void *data,
                                                                            const char *info_name,
                                                                            struct t_hashtable *hashtable),
                                            void *callback_data);
----------------------------------------

Argomenti:

* 'info_name': nome della info
  (priorità consentita, consultare la nota riguardo la
  <<hook_priority,priority>>)
* 'description': descrizione
* 'args_description': descrizione della tabella hash attesa (opzionale, può
  essere NULL)
* 'output_description': descrizione della tabella hash restituita dalla
  callback (opzionale, può essere NULL)
* 'callback': funzione chiamata alla richiesta della info, argomenti:
** 'void *data': puntatore
** 'const char *info_name': nome della info
** 'struct t_hashtable *hashtable': tabella hash, in base alla info
* 'callback_data': puntatore fornito alla callback quando chiamata da WeeChat

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
struct t_hashtable *
my_info_hashtable_cb (void *data, const char *info_name, struct t_hashtable *hashtable)
{
    /* ... */
    return pointer_to_new_hashtable;
}

/* add info "my_info_hashtable" */
struct t_hook *my_info_hook = weechat_hook_info_hashtable ("my_info_hashtable",
                                                           "Some info",
                                                           "Info about input hashtable",
                                                           "Info about output hashtable",
                                                           &my_info_hashtable_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
hook = weechat.hook_info_hashtable(info_name, description, args_description,
                                   output_description, callback, callback_data)

# esempio
def my_info_hashtable_cb(data, info_name, hashtable):
    return { "test_key": "test_value" }

hook = weechat.hook_info_hashtable("my_info_hashtable", "Some info",
                                   "Info about input hashtable",
                                   "Info about output hashtable",
                                   "my_info_hashtable_cb", "")
----------------------------------------

weechat_hook_infolist
^^^^^^^^^^^^^^^^^^^^^

Hook su una lista info: la callback restituisce il puntatore alla lista info
richiesta.

Prototipo:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_infolist (const char *infolist_name,
                                      const char *description,
                                      const char *pointer_description,
                                      const char *args_description,
                                      const char *(*callback)(void *data,
                                                              const char *infolist_name,
                                                              void *pointer,
                                      const char *arguments),
                                      void *callback_data);
----------------------------------------

Argomenti:

* 'infolist_name': nome della lista info
  (priotità consentita, consultare la nota riguardo la
  <<hook_priority,priority>>)
* 'description': descrizione
* 'pointer_description': descrizione del puntatore (opzionale, può essere NULL)
* 'args_description': descrizione degli argomenti (opzionale, può essere NULL)
* 'callback': funzione chiamata alla richiesta della lista info, argomenti:
** 'void *data': puntatore
** 'const char *infolist_name': nome della lista info
** 'void *pointer': puntatore ad un oggetto che la lista info deve restituire
   (per ricevere un solo elemento della lista info)
** 'const char *arguments': argomento aggiuntivo, dipende dalla lista info
* 'callback_data': puntatore fornito alla callback quando chiamata da WeeChat

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
struct t_infolist *
my_infolist_cb (void *data, const char *infolist_name, void *pointer,
                const char *arguments)
{
    struct t_infolist *my_infolist;
    
    /* compila lista info */
    /* ... */
    
    return my_infolist;
}

/* aggiunge lista info "my_infolist" */
struct t_hook *my_infolist = weechat_hook_infolist ("my_infolist",
                                                    "Infolist with some data",
                                                    "Info about pointer",
                                                    "Info about arguments",
                                                    &my_infolist_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
hook = weechat.hook_infolist(infolist_name, description, pointer_description,
                             args_description, callback, callback_data)

# esempio
def my_infolist_cb(data, infolist_name, pointer, arguments):
    # build infolist
    # ...
    return my_infolist

hook = weechat.hook_infolist("my_infolist", "Infolist with some data",
                             "Info about pointer", "Info about arguments",
                             "my_infolist_cb", "")
----------------------------------------

weechat_unhook
^^^^^^^^^^^^^^

Rimuove un hook.

Prototipo:

[source,C]
----------------------------------------
void weechat_unhook (struct t_hook *hook);
----------------------------------------

Argomenti:

* 'hook': qualcosa su cui è presente un hook con "weechat_hook_xxx()"

Esempio in C:

[source,C]
----------------------------------------
struct t_hook *my_hook = weechat_hook_command ( /* ... */ );
/* ... */
weechat_unhook (my_hook);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.unhook(hook)

# esempio
weechat.unhook(my_hook)
----------------------------------------

weechat_unhook_all
^^^^^^^^^^^^^^^^^^

Rimuove l'hook in qualsiasi punto in cui è stato attivato dal
plugin corrente.

Prototipo:

[source,C]
----------------------------------------
void weechat_unhook_all ();
----------------------------------------

Esempio in C:

[source,C]
----------------------------------------
weechat_unhook_all ();
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.unhook_all()

# esempio
weechat.unhook_all()
----------------------------------------

[[buffers]]
Buffer
~~~~~~

Funzioni per creare/richiedere/chiudere buffer.

weechat_buffer_new
^^^^^^^^^^^^^^^^^^

Apre un nuovo buffer.

Prototipo:

[source,C]
----------------------------------------
struct t_gui_buffer *weechat_buffer_new (const char *name,
                                         int (*input_callback)(void *data,
                                                               struct t_gui_buffer *buffer,
                                                               const char *input_data),
                                         void *input_callback_data,
                                         int (*close_callback)(void *data,
                                                               struct t_gui_buffer *buffer),
                                         void *close_callback_data);
----------------------------------------

Argomenti:

* 'name': nome del buffer (deve essere unico per il plugin)
* 'input_callback': funzione chiamata quando il testo in input è stato
  inserito nel buffer, argomenti:
*** 'void *data': puntatore
*** 'struct t_gui_buffer *buffer': puntatore al buffer
*** 'const char *input_data': dati in input
* 'callback_data': puntatore fornito alla callback quando chiamata da WeeChat
* 'close_callback': funzione chiamata alla chiusura del buffer, argomenti:
*** 'void *data': puntatore
*** 'struct t_gui_buffer *buffer': puntatore al buffer
* 'callback_data': puntatore fornito alla callback quando chiamata da WeeChat

Valore restituito:

* puntatore al nuovo buffer, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
int
my_input_cb (void *data, struct t_gui_buffer *buffer, const char *input_data)
{
    weechat_printf (buffer, "Testo: %s", input_data);
    return WEECHAT_RC_OK;
}

int
my_close_cb (void *data, struct t_gui_buffer *buffer)
{
    weechat_printf (NULL, "Il buffer '%s' verrà chiuso!",
                    weechat_buffer_get_string (buffer, "name"));
    return WEECHAT_RC_OK;
}

struct t_gui_buffer *my_buffer = weechat_buffer_new ("my_buffer",
                                                     &my_input_cb, NULL,
                                                     &my_close_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
buffer = weechat.buffer_new(name, input_callback, input_callback_data,
    close_callback, close_callback_data)

# esempio
def my_input_cb(data, buffer, input_data):
    weechat.prnt(buffer, "Testo: %s" % input_data)
    return weechat.WEECHAT_RC_OK

def my_close_cb(data, buffer):
    weechat.prnt("", "Il buffer '%s' verrà chiuso!" % weechat.buffer_get_string(buffer, "name"))
    return weechat.WEECHAT_RC_OK

buffer = weechat.buffer_new("my_buffer", "my_input_cb", "", "my_close_cb", "")
----------------------------------------

weechat_current_buffer
^^^^^^^^^^^^^^^^^^^^^^

Restituisce il puntatore al buffer corrente (buffer visualizzato nella
finestra corrente).

Prototipo:

[source,C]
----------------------------------------
struct t_gui_buffer *weechat_current_buffer ();
----------------------------------------

Valore restituito:

* puntatore al buffer corrente

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (weechat_current_buffer (), "Testo sul buffer corrente");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
buffer = weechat.current_buffer()

# esempio
weechat.prnt(weechat.current_buffer(), "Testo sul buffer corrente")
----------------------------------------

weechat_buffer_search
^^^^^^^^^^^^^^^^^^^^^

Cerca un buffer tramite plugin e/o nome.

Prototipo:

[source,C]
----------------------------------------
struct t_gui_buffer *weechat_buffer_search (const char *plugin,
                                            const char *name);
----------------------------------------

Argomenti:

* 'plugin': nome del plugin
* 'name': nome del buffer, se NULL o la stringa è vuota, viene
  restituito il buffer corrente (buffer visualizzato dalla finestra corrente)

Valore restituito:

* puntatore al buffer trovato, NULL in caso contrario

Esempio in C:

[source,C]
----------------------------------------
struct t_gui_buffer *my_buffer = weechat_buffer_search ("my_plugin",
                                                        "my_buffer");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
buffer = weechat.buffer_search(plugin, name)

# esempio
buffer = weechat.buffer_search("my_plugin", "my_buffer")
----------------------------------------

weechat_buffer_search_main
^^^^^^^^^^^^^^^^^^^^^^^^^^

Cerca nel buffer principale di WeeChat (per primo nel buffer 'core', il primo
visualizzato all'avvio di WeeChat).

Prototipo:

[source,C]
----------------------------------------
struct t_gui_buffer *weechat_buffer_search_main ();
----------------------------------------

Valore restituito:

* puntatore al buffer principale di WeeChat (buffer 'core')

Esempio in C:

[source,C]
----------------------------------------
struct t_gui_buffer *weechat_buffer = weechat_buffer_search_main ();
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
buffer = weechat.buffer_search_main()

# esempio
buffer = weechat.buffer_search_main()
----------------------------------------

weechat_buffer_clear
^^^^^^^^^^^^^^^^^^^^

Pulisce il contenuto del buffer.

Prototipo:

[source,C]
----------------------------------------
void weechat_buffer_clear (struct t_gui_buffer *buffer);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer

Esempio in C:

[source,C]
----------------------------------------
struct t_gui_buffer *my_buffer = weechat_buffer_search ("my_plugin",
                                                        "my_buffer");
if (my_buffer)
{
    weechat_buffer_clear (my_buffer);
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.buffer_clear(buffer)

# esempio
buffer = weechat.buffer_search("my_plugin", "my_buffer")
if buffer != "":
    weechat.buffer_clear(buffer)
----------------------------------------

weechat_buffer_close
^^^^^^^^^^^^^^^^^^^^

Chiude un buffer.

Prototipo:

[source,C]
----------------------------------------
void weechat_buffer_close (struct t_gui_buffer *buffer);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer

Esempio in C:

[source,C]
----------------------------------------
struct t_gui_buffer *my_buffer = weechat_buffer_new ("my_buffer",
                                                     &my_input_cb, NULL,
                                                     &my_close_cb, NULL);
/* ... */
weechat_buffer_close (my_buffer);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.buffer_close(buffer)

# esempio
buffer = weechat.buffer_new("my_buffer", "my_input_cb", "", "my_close_cb", "")
# ...
weechat.buffer_close(buffer)
----------------------------------------

weechat_buffer_merge
^^^^^^^^^^^^^^^^^^^^

Unisce un buffer in un altro: entrambi i buffer esistono separatamente, ma
con lo stesso numero, e WeeChat visualizzerà le righe di entrambi i
buffer (righe mischiate).

Prototipo:

[source,C]
----------------------------------------
void weechat_buffer_merge (struct t_gui_buffer *buffer,
                           struct t_gui_buffer *target_buffer);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'target_buffer': buffer di destinazione, dove il buffer verrà unito

Esempio in C:

[source,C]
----------------------------------------
/* merge current buffer with weechat "core" buffer */
weechat_buffer_merge (weechat_current_buffer (),
                      weechat_buffer_search_main ());
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.buffer_merge(buffer, target_buffer)

# esempio
# merge current buffer with WeeChat "core" buffer
weechat.buffer_merge(weechat.current_buffer(), weechat.buffer_search_main())
----------------------------------------

weechat_buffer_unmerge
^^^^^^^^^^^^^^^^^^^^^^

Stacca un buffer da un gruppo di buffer uniti.

Prototipo:

[source,C]
----------------------------------------
void weechat_buffer_unmerge (struct t_gui_buffer *buffer,
                             int number);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'number': numero di destinazione per il buffer staccato,
  se è < 1, allora il buffer verrà spostato al numero di
  'buffer' +1

Esempio in C:

[source,C]
----------------------------------------
weechat_buffer_unmerge (weechat_current_buffer (), 1);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.buffer_unmerge(buffer, number)

# esempio
weechat.buffer_unmerge(weechat.current_buffer(), 1)
----------------------------------------

weechat_buffer_get_integer
^^^^^^^^^^^^^^^^^^^^^^^^^^

Restituisce il valore intero della proprietà di
un buffer.

Prototipo:

[source,C]
----------------------------------------
int weechat_buffer_get_integer (struct t_gui_buffer *buffer,
                                const char *property);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'property': nome della proprietà:
** 'number': numero del buffer (inizia da 1)
** 'layout_number': numero del buffer salvato nel layout
** 'type': tipo dibuffer (0: formattato, 1: contenuto libero)
** 'notify': livello di notifica per il buffer
** 'num_displayed': numero delle finestre che visualizzano il buffer
** 'active': 1 se il buffer è attivo, 0 se il buffer è unito e non selezionato
** 'print_hooks_enabled': 1 se gli hook sulla stampa sono abilitati, altrimenti 0
** 'lines_hidden': 1 se almeno una riga è nascosta sul buffer (filtrata),
   oppure 0 se vengono visualizzate tutte le righe
** 'prefix_max_length': lunghezza massima del prefisso in questo buffer
** 'time_for_each_line': 1 se l'ora è visualizzata per ogni riga nel buffer
   (predefinito), altrimenti 0
** 'nicklist': 1 se la lista nick è abilitata, altrimenti 0
** 'nicklist_case_sensitive': 1 se i nick sono in maiuscole/minuscole, altrimenti 0
** 'nicklist_max_length': lunghezza massima per un nick
** 'nicklist_display_groups': 1 se i gruppi vengono visualizzati, altrimenti 0
** 'nicklist_visible_count': numero di nick/gruppi visualizzati
** 'input': 1 se l'input è abilitato, altrimenti 0
** 'input_get_unknown_commands': 1 se i comandi sconosciuti vengono inviati
   alla callback di input, altrimenti 0
** 'input_size': dimensione per l'input (in byte)
** 'input_length': lunghezza dell'input (numero di caratteri)
** 'input_pos': posizione del cursore nell'input del buffer
** 'input_1st_display': primo carattere visualizzato su schermo
** 'num_history': numero di comandi nella cronologia
** 'text_search': tipo di ricerca nel testo:
*** 0: nessuna ricerca in questo momento
*** 1: ricerca all'indietro (direzione: messaggi più vecchi)
*** 2: ricerca in avanti (direzione: messaggi più nuovi)
** 'text_search_exact': 1 se la ricerca testo è esatta
** 'text_search_found': 1 se il testo viene trovato, altrimenti 0

Valore restituito:

* valore intero della proprietà

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL, "my buffer number is: %d",
                weechat_buffer_get_integer (my_buffer, "number"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.buffer_get_integer(buffer, property)

# esempio
weechat.prnt("", "my buffer number is: %d" % weechat.buffer_get_integer(my_buffer, "number"))
----------------------------------------

weechat_buffer_get_string
^^^^^^^^^^^^^^^^^^^^^^^^^

Restituisce il valore stringa di una proprietà del buffer.

Prototipo:

[source,C]
----------------------------------------
const char *weechat_buffer_get_string (struct t_gui_buffer *buffer,
                                       const char *property);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'property': nome proprietà:
** 'plugin': nome del plugin che ha creato questo buffer ("core"
   per il buffer principale di WeeChat)
** 'name': nome del buffer
** 'short_name': nome breve del buffer
** 'title': titolo del buffer
** 'input': testo in ingresso
** 'text_search_input': input salvato prima della ricerca nel testo
** 'highlight_words': elenco di parole da evidenziare
** 'highlight_tags': elenco di tag da evidenziare
** 'no_highlight_nicks': lista di nick da NON evidenziare
** 'localvar_xxx': ottiene il contenuto della variabile locale "xxx"
   (sostituire "xxx" con il nome della variabile da leggere)

Valore restituito:

* valore stringa della proprietà

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL, "name / short name of buffer are: %s / %s",
                weechat_buffer_get_string (my_buffer, "name"),
                weechat_buffer_get_string (my_buffer, "short_name"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.buffer_get_string(buffer, property)

# esempio
weechat.prnt("", "name / short name of buffer are: %s / %s"
    % (weechat.buffer_get_string(my_buffer, "name"),
    weechat.buffer_get_string(my_buffer, "short_name")))
----------------------------------------

weechat_buffer_get_pointer
^^^^^^^^^^^^^^^^^^^^^^^^^^

Restituisce il valore puntatore della proprietà di un buffer.

Prototipo:

[source,C]
----------------------------------------
void *weechat_buffer_pointer (struct t_gui_buffer *buffer,
                              const char *property);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'property': nome proprietà:
** 'plugin': puntatore al plugin che ha creato questo buffer (NULL
   per il buffer principale di WeeChat)

Valore restituito:

* valore puntatore della proprietà

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL, "plugin pointer of my buffer: %lx",
                weechat_buffer_get_pointer (my_buffer, "plugin"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.buffer_get_pointer(buffer, property)

# esempio
weechat.prnt("", "plugin pointer of my buffer: %lx" % weechat.buffer_get_pointer(my_buffer, "plugin"))
----------------------------------------

weechat_buffer_set
^^^^^^^^^^^^^^^^^^

Imposta il valore stringa della proprietà di un buffer.

Prototipo:

[source,C]
----------------------------------------
void weechat_buffer_set (struct t_gui_buffer *buffer, const char *property,
                         const char *value);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'property' e 'value': nome della proprietà, con il proprio valore:

[width="100%",cols="^2,4,8",options="header"]
|========================================
| Nome | Valore | Descrizione

| hotlist | "+", "-", WEECHAT_HOTLIST_LOW, WEECHAT_HOTLIST_MESSAGE,
  WEECHAT_HOTLIST_PRIVATE, WEECHAT_HOTLIST_HIGHLIGHT |
  "+": abilita hotlist (impostazione globale , il puntatore al buffer pointer non
  è utilizzato) +
  "-": disabilita hotlist (impostazione globale, il puntatore al buffer non è
  utilizzato) +
  priorità: aggiunge il buffer alla hotlist con questa proprietà

| unread | - |
  imposta l'evidenziatore di lettura dopo l'ultima riga del buffer

| display | "1", "auto" |
  "1": passa a questo buffer nella finestra corrente +
  "auto": passa a questo buffer nella finestra corrente, l'evidenziatore di
  lettura non viene resettato

| number | numero |
  sposta buffer a questo numero

| name | qualsiasi stringa |
  imposta nuovo nome per il buffer

| short_name | qualsiasi stringa |
  imposta nuovo nome breve per il buffer

| type | "formatted" oppure "free" |
  imposta tipo per il: "formatted" (per stampare i messaggi di chat),
  oppure "free" (per contenuto libero)

| notify | "0", "1", "2", "3" |
  imposta il livello di notifica per il buffer: "0" = non aggiungere alla hotlist,
  "1" = aggiungere solo per gli eventi, "2" = aggiungere per eventi e
  messaggi, "3" = aggiungere per tutti i messaggi

| title | qualsiasi stringa |
  imposta nuovo titolo per il buffer

| time_for_each_line | "0" oppure "1" |
  "0" per nascondere l'orario in tutte le righe del buffer, "1" per
  visualizzarlo su tutte le righe (predefinito per un nuovo buffer)

| nicklist | "0" oppure "1" |
  "0" per rimuovere la lista nick per il buffer, "1" per aggiungere
  la lista nick per il buffer

| nicklist_case_sensitive | "0" oppure "1" |
  "0" per avere una lista nick case insenstive (maiuscole/minuscole
  ignorate), "1" per avere una lista nick case sensitive
  (maiuscole/minuscole non ignorate)

| nicklist_display_groups | "0" oppure "1" |
  "0" per nascondere i gruppi nella lista nick, "1" per visualizzare
  i gruppi della lista nick

| highlight_words | "-" oppure elenco di parole separato da virgole |
  "-" è un valore speciale per disabilitare qualsiasi evento su questo
  buffer, o un elenco di parole separate da virgole da evidenziare in
  questo buffer, ad esempio: "abc,def,ghi"

| highlight_words_add | elenco di parole separate da virgole |
  elenco di parole separate da virgole da evidenziare in questo buffer,
  queste parole vengono aggiunte alle parole evidenziate esistenti nel
  buffer

| highlight_words_del | elenco di parole separate da virgole|
  elenco di parole separate da virgole da rimuovere dalle
  parole evidenziate nel buffer

| highlight_tags | elenco separato da virgole di tag |
  elenco separato da virgole di tag da evidenziare in questo buffer

| no_highlight_nicks | elenco separato da virgole di nick |
  elenco separato da virgole di nick da NON evidenziare in questo buffer, ad esempio:
  "joe,mike,robert"

| no_highlight_nicks_add | elenco separato da virgole di nick |
  elenco separato da virgole di nick da NON evidenziare in questo buffer, queste
  parole vengono aggiunte ai nick esistenti nel buffer

| no_highlight_nicks_del | elenco separato da virgole di nick |
  elenco separato da virgole di nick da rimuovere dai nick non evidenziati nel buffer

| key_bind_xxx | qualsiasi stringa |
  assegna un nuovo tasto 'xxx', specifico per questo buffer, il valore è il
  comando da eseguire per questo tasto

| key_unbind_xxx | - |
  rimuove l'assegnazione del tasto 'xxx' per questo buffer

| input | qualsiasi stringa |
  imposta un nuovo valore per l'input del buffer

| input_pos | posizione |
  imposta la posizione del cursore per l'input del buffer

| input_get_unknown_commands | "0" oppure "1" |
  "0" per disabilitare i comandi sconosciuti per questo buffer (comportamento
  predefinito), "1" per ricevere i comandi sconosciuti, ad esempio se l'utente
  digita "/unknowncmd", verrà ricevuto dal buffer (nessun errore riguardo il
  comando sconosciuto)

| localvar_set_xxx | qualsiasi stringa |
  imposta il nuovo valore per la variabile locale 'xxx' (la variabile verrà
  creata se non esiste)

| localvar_del_xxx | - |
  rimuove la variabile locale 'xxx'
|========================================

Esempio in C:

[source,C]
----------------------------------------
/* disabilita hotlist (per tutti i buffer) */
weechat_buffer_set (NULL, "hotlist", "-");

/* abilita nuovamente hotlist */
weechat_buffer_set (NULL, "hotlist", "+");

/* cambia il nome buffer */
weechat_buffer_set (my_buffer, "name", "my_new_name");

/* aggiunge una nuova variabile locale "tizio" con il valore "abc" */
weechat_buffer_set (my_buffer, "localvar_set_tizio", "abc");

/* rimuove la variabile locale "tizio" */
weechat_buffer_set (my_buffer, "localvar_del_tizio", NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.buffer_set(buffer, property, value)

# esempi

# disabilita hotlist (per tutti i buffer)
weechat.buffer_set("", "hotlist", "-")

# abilita nuovamente hotlist
weechat.buffer_set("", "hotlist", "+")

# cambia il nome buffer
weechat.buffet_set(my_buffer, "name", "my_new_name")

# aggiunge una nuova variabile locale "tizio" con il valore "abc"
weechat.buffet_set(my_buffer, "localvar_set_tizio", "abc")

# rimuove la variabile locale "tizio"
weechat.buffet_set(my_buffer, "localvar_del_tizio", "")
----------------------------------------

weechat_buffer_set_pointer
^^^^^^^^^^^^^^^^^^^^^^^^^^

Imposta il valore puntatore per la proprietà di un buffer.

Prototipo:

[source,C]
----------------------------------------
void weechat_buffer_set_pointer (struct t_gui_buffer *buffer, const char *property,
                                 void *pointer);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'property' e 'value': nome della proprietà, con il proprio valore:
** 'close_callback': set close callback function
** 'close_callback_data': set close callback data
** 'input_callback': set input callback function
** 'input_callback_data': set input callback data

Esempio in C:

[source,C]
----------------------------------------
int
my_close_cb (void *data, struct t_gui_buffer *buffer)
{
    /* ... */
    return WEECHAT_RC_OK;
}

weechat_buffer_set_pointer (my_buffer, "close_callback", &my_close_cb);
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_buffer_string_replace_local_var
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Sostituisce le variabili globali in una stringa con i loro valori, utilizzando
le variabili del buffer locale.

Prototipo:

[source,C]
----------------------------------------
char *weechat_buffer_string_replace_local_var (struct t_gui_buffer *buffer,
                                               const char *string);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'string': stringa con testo e variabili locali che utilizzano il formato "$var"

Valore restituito:

* stringa con i valori delle variabili locali

Esempio in C:

[source,C]
----------------------------------------
weechat_buffer_set (my_buffer, "localvar_set_toto", "abc");

char *str = weechat_buffer_string_replace_local_var (my_buffer,
                                                     "test with $toto");
/* str contiene "test with abc" */
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.buffer_string_replace_local_var(buffer, string)

# esempio
weechat.buffer_set(my_buffer, "localvar_set_toto", "abc")
str = weechat.buffer_string_replace_local_var(my_buffer, "test with $toto")
# str contains "test with abc"
----------------------------------------

[[windows]]
Finestre
~~~~~~~~

Funzioni per richiedere finestre.

weechat_current_window
^^^^^^^^^^^^^^^^^^^^^^

Restituisce il puntatore alla finestra corrente

Prototipo:

[source,C]
----------------------------------------
struct t_gui_window *weechat_current_window ();
----------------------------------------

Valore restituito:

* puntatore alla finestra corrente

Esempio in C:

[source,C]
----------------------------------------
struct t_gui_window *current_window = weechat_current_window ();
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
window = weechat.current_window()

# esempio
current_window = weechat.current_window()
----------------------------------------

weechat_window_get_integer
^^^^^^^^^^^^^^^^^^^^^^^^^^

Restituisce il valore intero della proprietà di una finestra.

Prototipo:

[source,C]
----------------------------------------
int weechat_window_get_integer (struct t_gui_window *window,
                                const char *property);
----------------------------------------

Argomenti:

* 'window': puntatore alla finestra
* 'property': nome della proprietà:
** 'win_x': posizione X della finestra nel terminale (la prima colonna è 0)
** 'win_y': posizione Y della finestra nel terminale (la prima riga è 0)
** 'win_width': larghezza della finestra, in caratteri
** 'win_height': altezza della finestra, in caratteri
** 'win_width_pct': misura percentuale, paragonata alla finestra genitore
   (ad esempio 50 vuol dire metà grandezza)
** 'win_height_pct': misura percentuale, paragonata alla finestra genitore
   (ad esempio 50 vuol dire metà grandezza)
** 'win_chat_x': posizione X della finestra di chat nel terminale
   (la prima colonna è 0)
** 'win_chat_y': posizione Y della finestra di chat nel terminale
   (la prima riga è 0)
** 'win_chat_width': larghezza della finestra di chat, in caratteri
** 'win_chat_height': altezza della finestra di chat, in caratteri
** 'first_line_displayed': 1 se la prima riga del buffer viene visualizzata
   su schermo, altrimenti 0
** 'scroll': 1 se lo scorrimento è attivo sulla finestra (ultima riga non
   visualizzata)
** 'scroll_lines_after': numero di righe non visualizzate dopo l'ultima
   visualizzata (durante lo scorrimento)

Valore restituito:

* valore intero della proprietà

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL, "current window is at position (x,y): (%d,%d)",
                weechat_window_get_integer (weechat_current_window (), "win_x"),
                weechat_window_get_integer (weechat_current_window (), "win_y"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.window_get_integer(window, property)

# esempio
weechat.prnt("", "current window is at position (x,y): (%d,%d)"
    % (weechat.window_get_integer(weechat.current_window(), "win_x"),
    weechat.window_get_integer(weechat.current_window(), "win_y")))
----------------------------------------

weechat_window_get_string
^^^^^^^^^^^^^^^^^^^^^^^^^

Restituisce il valore stringa della proprietà di una finestra.

[NOTE]
La funzione non è utilizzata oggi, è riservata per una versione futura.

Prototipo:

[source,C]
----------------------------------------
int weechat_window_get_string (struct t_gui_window *window,
                               const char *property);
----------------------------------------

Argomenti:

* 'window': puntatore alla finestra
* 'property': nome della proprietà

Valore restituito:

* valore stringa della proprietà

weechat_window_get_pointer
^^^^^^^^^^^^^^^^^^^^^^^^^^

Restituisce il valore puntatore della proprietà di una finestra.

Prototipo:

[source,C]
----------------------------------------
void *weechat_window_get_pointer (struct t_gui_window *window,
                                  const char *property);
----------------------------------------

Argomenti:

* 'window': puntatore alla finestra
* 'property': nome della proprietà:
** 'current': puntatore alla finestra corrente
** 'buffer': puntatore al buffer visualizzato dalla finestra

Valore restituito:

* valore puntatore della proprietà

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL,
                "buffer displayed in current window: %lx",
                weechat_window_get_pointer (weechat_current_window (), "buffer"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.window_get_pointer(window, property)

# esempio
weechat.prnt("", "buffer displayed in current window: %lx"
    % weechat.window_get_pointer(weechat.current_window(), "buffer"))
----------------------------------------

weechat_window_set_title
^^^^^^^^^^^^^^^^^^^^^^^^

Imposta il titolo per il terminale.

Prototipo:

[source,C]
----------------------------------------
void weechat_window_set_title (const char *title);
----------------------------------------

Argomenti:

* 'title': nuovo titolo per il terminale (NULL per resettarlo)

Esempio in C:

[source,C]
----------------------------------------
weechat_window_set_title ("nuovo titolo qui");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.window_set_title(window, title)

# esempio
weechat.window_set_title("nuovo titolo qui")
----------------------------------------

[[nicklist]]
Lista nick
~~~~~~~~~~

Funzioni per il buffer nicklist.

weechat_nicklist_add_group
^^^^^^^^^^^^^^^^^^^^^^^^^^

Aggiunge un gruppo in una lista nick.

Prototipo:

[source,C]
----------------------------------------
struct t_gui_nick_group *weechat_nicklist_add_group (struct t_gui_buffer *buffer,
                                                     struct t_gui_nick_group *parent_group,
                                                     const char *name,
                                                     const char *color,
                                                     int visible);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'parent_group': puntatore al genitore del gruppo, NULL se il gruppo non ha genitore
  (lista nick radice)
* 'name': nome del gruppo
* 'visible':
** '1': gruppi e sottogruppi/nick sono visibili
** '0': gruppi e sottogruppi/nick sono nascosti
* 'color': nome per l'opzione colore:
** nome opzione per WeeChat, ad esempio 'weechat.color.nicklist_group'
** colore con sfondo opzionale, ad esempio 'yellow' o 'yellow,red'
** nome colore per la barra:
*** 'bar_fg': colore di primo piando per la barra
*** 'bar_delim': colore dei delimitatori per la barra
*** 'bar_bg': colore di sfondo per la barra

[NOTE]
Il nome del gruppo può iniziare con uno o più numeri, seguiti da una pipe, e
infine dal nome del gruppo. Quando questa stringa si trova all'inizio, viene
utilizzata per ordinare i gruppi nella lista nick. Ad esempio i gruppi "1|test" e
"2|abc" verranno visualizzati in quest'ordine: prima "test" poi "abc".

Valore restituito:

* puntatore al nuovo gruppo, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
struct t_gui_nick_group *my_group =
    weechat_nicklist_add_group (my_buffer,
                                my_parent_group,
                                "test_group",
                                "weechat.color.nicklist_group",
                                1);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
group = weechat.nicklist_add_group(buffer, parent_group, name, color, visible)

# esempio
group = weechat.nicklist_add_group(my_buffer, my_parent_group, "test_group",
    "weechat.color.nicklist_group", 1)
----------------------------------------

weechat_nicklist_search_group
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Cerca un gruppo in una lista nick.

Prototipo:

[source,C]
----------------------------------------
struct t_gui_nick_group *weechat_nicklist_search_group (struct t_gui_buffer *buffer,
                                                        struct t_gui_nick_group *from_group,
                                                        const char *name);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'from_group': ricerca solo da questo gruppo, se NULL, allora la cerca in
  tutta la lista nick
* 'name': nome gruppo da cercare

Valore restituito:

* puntatore al gruppo trovato, NULL se non trovato

Esempio in C:

[source,C]
----------------------------------------
struct t_gui_nick_group *ptr_group = weechat_nicklist_search_group (my_buffer,
                                                                    NULL, "test_group");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
group = weechat.nicklist_search_group(buffer, from_group, name)

# esempio
group = weechat.nicklist_search_group(my_buffer, "", "test_group")
----------------------------------------

weechat_nicklist_add_nick
^^^^^^^^^^^^^^^^^^^^^^^^^

Aggiunge un nick in un gruppo.

Prototipo:

[source,C]
----------------------------------------
struct t_gui_nick_group *weechat_nicklist_add_nick (struct t_gui_buffer *buffer,
                                                    struct t_gui_nick_group *group,
                                                    const char *name,
                                                    const char *color,
                                                    const char *prefix,
                                                    const char *prefix_color,
                                                    int visible);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'group': puntatore al gruppo
* 'name': nome nick
* 'color': nome dell'opzione per il colore:
*** nome opzione per WeeChat (da weechat.color.xxx), ad esempio 'chat_delimiters'
*** colore con sfondo opzionale, ad esempio 'yellow' o 'yellow,red'
*** nome colore per la barra:
**** 'bar_fg': colore di primo piano per la barra
**** 'bar_delim': colore dei delimitatori per la barra
**** 'bar_bg': colore di sfondo per la barra
* 'prefix': prefisso visualizzato prima del nick
* 'prefix_color': nome dell'opzione per il colore:
** nome opzione per WeeChat (da weechat.color.xxx), ad esempio 'chat_delimiters'
** colore con sfondo opzionale, ad esempio 'yellow' o 'yellow,red'
** nome colore per la barra:
*** 'bar_fg': colore di primo piano per la barra
*** 'bar_delim': colore dei delimitatori per la barra
*** 'bar_bg': colore di sfondo per la barra
* 'visible':
** '1': il nick è visibile
** '0': il nick è nascosto

Valore restituito:

* puntatore al nuovo nick, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
struct t_gui_nick *my_nick =
    weechat_nicklist_add_nick (my_buffer, my_group,
                               "test_nick",
                               (nick_away) ? "weechat.color.nicklist_away" : "bar_fg",
                               "@", "lightgreen",
                               1);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
nick = weechat.nicklist_add_nick(buffer, group, name, color, prefix, prefix_color, visible)

# esempio
if nick_away:
    color = "weechat.color.nicklist_away"
else:
    color = "bar_fg"
nick = weechat.nicklist_add_nick(my_buffer, my_group, "test_nick", color, "@", "lightgreen", 1)
----------------------------------------

weechat_nicklist_search_nick
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Cerca un nick nella lista nick.

Prototipo:

[source,C]
----------------------------------------
struct t_gui_nick *weechat_nicklist_search_nick (struct t_gui_buffer *buffer,
                                                 struct t_gui_nick_group *from_group,
                                                 const char *name);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'from_group': cerca solo da questo gruppo, se NULL, allora cerca
  nell'intera lista nick
* 'name': nick da cercare

Valore restituito:

* puntatore al nuovo nick, NULL se non trovato

Esempio in C:

[source,C]
----------------------------------------
struct t_gui_nick *ptr_nick = weechat_nicklist_search_nick (my_buffer,
                                                            NULL, "test_nick");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
nick = weechat.nicklist_search_nick(buffer, from_group, name)

# esempio
nick = weechat.nicklist_search_nick(my_buffer, "", "test_nick")
----------------------------------------

weechat_nicklist_remove_group
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Rimuove un gruppo da una lista nick.

Prototipo:

[source,C]
----------------------------------------
void weechat_nicklist_remove_group (struct t_gui_buffer *buffer,
                                    struct t_gui_nick_group *group);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'group': puntatore al gruppo da rimuovere (verranno rimossi anhe
  i sottogruppi/nick)

Esempio in C:

[source,C]
----------------------------------------
weechat_nicklist_remove_group (my_buffer, my_group);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.nicklist_remove_group(buffer, group)

# esempio
weechat.nicklist_remove_group(my_buffer, my_group)
----------------------------------------

weechat_nicklist_remove_nick
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Rimuove un nick dalla lista nick.

Prototipo:

[source,C]
----------------------------------------
void weechat_nicklist_remove_nick (struct t_gui_buffer *buffer,
                                   struct t_gui_nick *nick);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'nick': puntatore al nick da rimuovere

Esempio in C:

[source,C]
----------------------------------------
weechat_nicklist_remove_nick (my_buffer, my_nick);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.nicklist_remove_nick(buffer, nick)

# esempio
weechat.nicklist_remove_nick(my_buffer, my_nick)
----------------------------------------

weechat_nicklist_remove_all
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Rimuove tutti i gruppi/nick da una lista nick.

Prototipo:

[source,C]
----------------------------------------
void weechat_nicklist_remove_all (struct t_gui_buffer *buffer);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer

Esempio in C:

[source,C]
----------------------------------------
weechat_nicklist_remove_all (my_buffer);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.nicklist_remove_all(buffer)

# esempio
weechat.nicklist_remove_all(my_buffer)
----------------------------------------

weechat_nicklist_group_get_integer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.4._

Restituisce un valore intero della proprietà di un gruppo.

Prototipo:

[source,C]
----------------------------------------
int weechat_nicklist_group_get_integer (struct t_gui_buffer *buffer,
                                        struct t_gui_nick_group *group,
                                        const char *property);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'group': puntatore al gruppo
* 'property': nome della proprietà:
** 'visible': 1 se il gruppo è visibile, altrimenti 0
** 'level': livello del gruppo (root è 0)

Valore restituito:

* valore intero della proprietà

Esempio in C:

[source,C]
----------------------------------------
int visible = weechat_nicklist_group_get_integer (buffer, group, "visible");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.nicklist_group_get_integer(buffer, group, property)

# esempio
visible = weechat.nicklist_group_get_integer(buffer, group, "visible")
----------------------------------------

weechat_nicklist_group_get_string
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.4._

Restituisce il valore stringa della proprietà di un gruppo.

Prototipo:

[source,C]
----------------------------------------
const char *weechat_nicklist_group_get_string (struct t_gui_buffer *buffer,
                                               struct t_gui_nick_group *group,
                                               const char *property);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'group': puntatore al gruppo
* 'property': nome della proprietà:
** 'name': nome del gruppo
** 'color': colore del gruppo nella lista nick

Valore restituito:

* valore stringa della proprietà

Esempio in C:

[source,C]
----------------------------------------
const char *color = weechat_nicklist_group_get_string (buffer, group, "color");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.nicklist_group_get_string(buffer, group, property)

# esempio
color = weechat.nicklist_group_get_string(buffer, group, "color")
----------------------------------------

weechat_nicklist_group_get_pointer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.4._

Restituisce il valore puntatore della proprietà di un gruppo.

Prototipo:

[source,C]
----------------------------------------
void *weechat_nicklist_group_get_pointer (struct t_gui_buffer *buffer,
                                          struct t_gui_nick_group *group,
                                          const char *property);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'group': puntatore al gruppo
* 'property': nome della proprietà:
** 'parent': puntatore al gruppo genitore

Valore restituito:

* valore puntatore della proprietà

Esempio in C:

[source,C]
----------------------------------------
struct t_gui_nick_group *parent = weechat_nicklist_group_get_pointer (buffer, group, "parent");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.nicklist_group_get_pointer(buffer, group, property)

# esempio
parent = weechat.nicklist_group_get_pointer(buffer, group, "parent")
----------------------------------------

weechat_nicklist_group_set
^^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.4._

Imposta il valore stringa della proprietà di un gruppo.

Prototipo:

[source,C]
----------------------------------------
void weechat_nicklist_group_set (struct t_gui_buffer *buffer,
                                 struct t_gui_nick_group *group,
                                 const char *property,
                                 const char *value);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'group': puntatore al gruppo
* 'property' e 'value': nome della proprietà, con il suo valore:

[width="100%",cols="^2,4,8",options="header"]
|========================================
| Nome | Valore | Descrizione

| color | nome per l'opzione del colore per WeeChat |
  consultare l'argomento "color" della funzione
  <<_weechat_nicklist_add_group,weechat_nicklist_add_group>>

| visible | "0", "1" |
  "0" = gruppo nascosto, "1" = gruppo visibile
|========================================

C examples:

[source,C]
----------------------------------------
/* cambia colore del gruppo a "bar_fg" */
weechat_nicklist_group_set (buffer, group, "color", "bar_fg");

/* cambia il colore del gruppo a giallo */
weechat_nicklist_group_set (buffer, group, "color", "yellow");

/* nasconde gruppo nella lista nick */
weechat_nicklist_group_set (buffer, group, "visible", "0");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.nicklist_group_set(buffer, group, property, value)

# esempi

# cambia colore del gruppo a "bar_fg"
weechat.nicklist_group_set(buffer, group, "color", "bar_fg")

# cambia colore del gruppo a giallo
weechat.nicklist_group_set(buffer, group, "color", "yellow")

# nasconde gruppo nella lista nick
weechat.nicklist_group_set(buffer, group, "visible", "0")
----------------------------------------

weechat_nicklist_nick_get_integer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.4._

Restituisce il valore intero della proprietà di un nick.

Prototipo:

[source,C]
----------------------------------------
int weechat_nicklist_nick_get_integer (struct t_gui_buffer *buffer,
                                       struct t_gui_nick *nick,
                                       const char *property);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'nick': puntatore al nick
* 'property': nome della proprietà:
** 'visible': 1 se il nick è visibile, altrimenti 0

Valore restituito:

* valore intero della proprietà

Esempio in C:

[source,C]
----------------------------------------
int visible = weechat_nicklist_nick_get_integer (buffer, nick, "visible");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.nicklist_nick_get_integer(buffer, nick, property)

# esempio
visible = weechat.nicklist_nick_get_integer(buffer, nick, "visible")
----------------------------------------

weechat_nicklist_nick_get_string
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.4._

Restituisce il valore stringa della proprietà di un nick.

Prototipo:

[source,C]
----------------------------------------
const char *weechat_nicklist_nick_get_string (struct t_gui_buffer *buffer,
                                              struct t_gui_nick *nick,
                                              const char *property);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'nick': puntatore al nick
* 'property': nome della proprietà:
** 'name': nome del nick
** 'color': colore del nick nella lista nick
** 'prefix': prefisso del nick
** 'prefix_color': colore del prefisso nella lista nick

Valore restituito:

* valore stringa della proprietà

Esempio in C:

[source,C]
----------------------------------------
const char *color = weechat_nicklist_nick_get_string (buffer, nick, "color");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.nicklist_nick_get_string(buffer, nick, property)

# esempio
color = weechat.nicklist_nick_get_string(buffer, nick, "color")
----------------------------------------

weechat_nicklist_nick_get_pointer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.4._

Restituisce il valore puntatore della proprietà di un nick.

Prototipo:

[source,C]
----------------------------------------
void *weechat_nicklist_nick_get_pointer (struct t_gui_buffer *buffer,
                                         struct t_gui_nick *nick,
                                         const char *property);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'nick': puntatore al nick
* 'property': nome proprietà:
** 'group': puntatore al gruppo che contiene questo nick

Valore restituito:

* valore puntatore della proprietà

Esempio in C:

[source,C]
----------------------------------------
struct t_gui_nick_group *group = weechat_nicklist_nick_get_pointer (buffer, nick, "group");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.nicklist_nick_get_pointer(buffer, nick, property)

# esempio
group = weechat.nicklist_nick_get_pointer(buffer, nick, "group")
----------------------------------------

weechat_nicklist_nick_set
^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.4._

Imposta il valore stringa della proprietà di un nick.

Prototipo:

[source,C]
----------------------------------------
void weechat_nicklist_nick_set (struct t_gui_buffer *buffer,
                                struct t_gui_nick *nick,
                                const char *property,
                                const char *value);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'nick': puntatore al nick
* 'property' and 'value': nome della proprietà, con il suo valore:

[width="100%",cols="^2,4,8",options="header"]
|========================================
| Nome | Valore | Descrizione

| color | nome per l'opzione del colore di WeeChat |
  consultare l'argomento "color" della funzione
  <<_weechat_nicklist_add_nick,weechat_nicklist_add_nick>>

| prefix | qualsiasi stringa |
  prefisso del nick

| prefix_color | nome per l'opzione del colore di WeeChat |
  consultare l'argomento "prefix_color" della funzione
  <<_weechat_nicklist_add_nick,weechat_nicklist_add_nick>>

| visible | "0", "1" |
  "0" = nick nascosto, "1" = nick visibile
|========================================

Esempi in C:

[source,C]
----------------------------------------
/* cambia colore del nick in azzurro */
weechat_nicklist_nick_set (buffer, nick, "color", "cyan");

/* cambia prefisso in "+" */
weechat_nicklist_nick_set (buffer, nick, "prefix", "+");

/* cambia colore del prefisso in giallo */
weechat_nicklist_nick_set (buffer, nick, "prefix_color", "yellow");

/* nascondi nick nella lista nick */
weechat_nicklist_nick_set (buffer, nick, "visible", "0");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.nicklist_nick_set(buffer, nick, property, value)

# esempi

# cambia colore del nick in azzurro
weechat.nicklist_nick_set(buffer, nick, "color", "cyan")

# cambia prefisso in "+"
weechat.nicklist_nick_set(buffer, nick, "prefix", "+")

# cambia colore del prefisso in giallo
weechat.nicklist_nick_set(buffer, nick, "prefix_color", "yellow")

# nascondi nick nella lista nick
weechat.nicklist_nick_set(buffer, nick, "visible", "0")
----------------------------------------

[[bars]]
Barre
~~~~~

Funzioni per le barre.

weechat_bar_item_search
^^^^^^^^^^^^^^^^^^^^^^^

Cerca un elemento barra.

Prototipo:

[source,C]
----------------------------------------
struct t_gui_bar_item *weechat_bar_item_search (const char *name);
----------------------------------------

Argomenti:

* 'name': nome dell'elemento barra

Valore restituito:

* puntatore all'elemento barra trovato, NULL se non trovato

Esempio in C:

[source,C]
----------------------------------------
struct t_gui_bar_item *bar_item = weechat_bar_item_search ("myitem");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
bar_item = weechat.bar_item_search(name)

# esempio
bar_item = weechat.bar_item_search("myitem")
----------------------------------------

weechat_bar_item_new
^^^^^^^^^^^^^^^^^^^^

Crea un nuovo elemento barra.

Prototipo:

[source,C]
----------------------------------------
struct t_gui_bar_item *weechat_bar_item_new (const char *name,
                                             char *(build_callback)(void *data,
                                                                    struct t_gui_bar_item *item,
                                                                    struct t_gui_window *window),
                                             void *build_callback_data);
----------------------------------------

Argomenti:

* 'name': nome dell'elemento barra
* 'build_callback': funzione chiamata quando l'elemento barra viene
  compilato; deve restituire il contenuto dell'elemento barra
* 'build_callback_data': puntatore fornito alla callback quando
  chiamata da WeeChat

Valore restituito:

* puntatore al nuovo elemento barra, NULL se non trovato

Esempio in C:

[source,C]
----------------------------------------
char *
my_build_callback (void *data,
                   struct t_gui_bar_item *item,
                   struct t_gui_window *window)
{
    return strdup ("my content");
}

struct t_gui_bar_item *my_item = weechat_bar_item_new ("myitem",
                                                       &my_build_callback,
                                                       NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
bar_item = weechat.bar_item_new(name, build_callback, build_callback_data)

# esempio
def my_build_callback(data, item, window):
    return "my content"

bar_item = weechat.bar_item_new("myitem", "my_build_callback", "")
----------------------------------------

weechat_bar_item_update
^^^^^^^^^^^^^^^^^^^^^^^

Aggiorna il contenuto dell'elemento barra, chiamando la callback
che lo ha compilato.

Prototipo:

[source,C]
----------------------------------------
void weechat_bar_item_update (const char *name);
----------------------------------------

Argomenti:

* 'name': nome dell'elemento barra

Esempio in C:

[source,C]
----------------------------------------
weechat_bar_item_update ("myitem");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.bar_item_update(name)

# esempio
weechat.bar_item_update("myitem")
----------------------------------------

weechat_bar_item_remove
^^^^^^^^^^^^^^^^^^^^^^^

Rimuove un elemento barra.

Prototipo:

[source,C]
----------------------------------------
void weechat_bar_item_remove (struct t_gui_bar_item *item);
----------------------------------------

Argomenti:

* 'item': puntatore all'elemento barra

Esempio in C:

[source,C]
----------------------------------------
weechat_bar_item_remove (&my_item);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.bar_item_remove(item)

# esempio
weechat.bar_item_remove(myitem)
----------------------------------------

weechat_bar_search
^^^^^^^^^^^^^^^^^^

Cerca una barra.

Prototipo:

[source,C]
----------------------------------------
struct t_gui_bar *weechat_bar_search (const char *name);
----------------------------------------

Argomenti:

* 'name': nome della barra

Valore restituito:

* puntatore alla barra trovata, NULL se non trovata

Esempio in C:

[source,C]
----------------------------------------
struct t_gui_bar *bar = weechat_bar_search ("mybar");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
bar = weechat.bar_search(name)

# esempio
bar = weechat.bar_search("mybar")
----------------------------------------

weechat_bar_new
^^^^^^^^^^^^^^^

Crea una nuova barra.

Prototipo:

[source,C]
----------------------------------------
struct t_gui_bar *weechat_bar_new (const char *name,
                                   const char *hidden,
                                   const char *priority,
                                   const char *type,
                                   const char *condition,
                                   const char *position,
                                   const char *filling_top_bottom,
                                   const char *filling_left_right,
                                   const char *size,
                                   const char *size_max,
                                   const char *color_fg,
                                   const char *color_delim,
                                   const char *color_bg,
                                   const char *separator,
                                   const char *items);
----------------------------------------

Argomenti:

* 'name': nome della barra
* 'hidden':
** 'on': la barra è nascosta
** 'off': la barra è visibile
* 'priority': priorità per la barra (intero)
* 'type':
** 'root': barra visualizzata una sola volta, al di fuori delle finestre
** 'window': barra visualizzata in ogni finestra
* 'condition': condizioni per la visualizzazione della barra:
** 'active': la barra viene visualizzata solo nella finestra attiva
** 'inactive': la barra viene visualizzata solo nelle finestre inattive
** 'nicklist': la barra viene visualizzata nelle finestre con liste nick
* 'position': 'top', 'bottom', 'left' o 'right'
* 'filling_top_bottom':
** 'horizontal': gli elementi sono posizionati in orizzontale
   (spazio dopo ogni elemento)
** 'vertical': gli elementi sono posizionati in verticale
   (nuova riga dopo ogni elemento)
** 'columns_horizontal': gli elementi sono posizionati in orizzontale,
   visualizzati su colonne
** 'columns_vertical': gli elementi sono posizionati in verticale,
   visualizzati su colonne
* 'filling_left_right':
** 'horizontal': gli elementi sono posizionati in orizzontale
   (spazio dopo ogni elemento)
** 'vertical': gli elementi sono posizionati in verticale
   (nuova riga dopo ogni elemento)
** 'columns_horizontal': gli elementi sono posizionati in orizzontale,
   visualizzati su colonne
** 'columns_vertical': gli elementi sono posizionati in verticale,
   visualizzati su colonne
* 'size': dimensione della barra in caratteri
  (0 corrisponde a dimensione automatica)
* 'size_max': dimensione massima per la barra
  (0 corrisponde a nessuna dimensione massima)
* 'color_fg': colore per il testo nella barra
* 'color_delim': colore per i delimitatori nella barra
* 'color_bg': colore di sfondo per la barra
* 'separator':
** 'on': la barra ha una riga di separazione con altre finestre/barre
** 'off': nessun separatore
* 'items': elenco di elemento nella barra, separati da virgola (spazio tra
  gli elementi), o "+" (elementi incollati)

Valore restituito:

* puntatore alla nuova barra, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
struct t_gui_bar *my_bar = weechat_bar_new ("mybar",
                                            "off",
                                            100,
                                            "window",
                                            "",
                                            "top",
                                            "horizontal",
                                            "vertical",
                                            "0",
                                            "5",
                                            "default",
                                            "cyan",
                                            "blue",
                                            "off",
                                            "time,buffer_number+buffer_name");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
bar = weechat.bar_new(name, hidden, priority, type, condition, position,
    filling_top_bottom, filling_left_right, size, size_max,
    color_fg, color_delim, color_bg, separator, items)

# esempio
bar = weechat.bar_new("mybar", "off", 100, "window", "", "top", "horizontal", "vertical",
    "0", "5", "default", "cyan", "blue", "off", "time,buffer_number+buffer_name")
----------------------------------------

weechat_bar_set
^^^^^^^^^^^^^^^

Imposta un nuovo valore per la proprietà di una barra.

Prototipo:

[source,C]
----------------------------------------
int weechat_bar_set (struct t_gui_bar *bar, const char *property,
                     const char *value);
----------------------------------------

Argomenti:

* 'bar': puntatore alla barra
* 'property': name, hidden, priority, conditions, position, filling_top_bottom,
  filling_left_right, size, size_max, color_fg, color_delim, color_bg,
  separator, items (consultare <<_weechat_bar_new,weechat_bar_new>>)
* 'value': nuovo valore per la proprietà

Valore restituito:

* 1 se il nuovo valore è stato impostato, 0 in caso di errore

Esempio in C:

[source,C]
----------------------------------------
weechat_bar_set (mybar, "position", "bottom");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.bar_set(bar, property, value)

# esempio
weechat.bar_set(my_bar, "position", "bottom")
----------------------------------------

weechat_bar_update
^^^^^^^^^^^^^^^^^^

Aggiorna il contenuto di una barra su schermo.

Prototipo:

[source,C]
----------------------------------------
void weechat_bar_update (const char *name);
----------------------------------------

Argomenti:

* 'name': nome della barra

Esempio in C:

[source,C]
----------------------------------------
weechat_bar_update ("mybar");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.bar_update(name)

# esempio
weechat.bar_update("mybar")
----------------------------------------

weechat_bar_remove
^^^^^^^^^^^^^^^^^^

Rimuove una barra.

Prototipo:

[source,C]
----------------------------------------
void weechat_bar_remove (struct t_gui_bar *bar);
----------------------------------------

Argomenti:

* 'bar': puntatore alla barra

Esempio in C:

[source,C]
----------------------------------------
weechat_bar_remove (mybar);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.bar_remove(bar)

# esempio
weechat.bar_remove(my_bar)
----------------------------------------

[[commands]]
Comandi
~~~~~~~

Funzioni per eseguire comandi di WeeChat.

weechat_command
^^^^^^^^^^^^^^^

Esegue un comando.

Prototipo:

[source,C]
----------------------------------------
void weechat_command (struct t_gui_buffer *buffer, const char *command);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer (il comando viene eseguito su questo buffer,
  utilizzare NULL per il buffer core di WeeChat)
* 'command': comando da eseguire (se preceduto da "/"), oppure il testo
  viene inviato sul buffer

Esempio in C:

[source,C]
----------------------------------------
weechat_command (weechat_buffer_search ("irc", "freenode.#weechat"),
                 "/whois FlashCode");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.command(buffer, command)

# esempio
weechat.command(weechat.buffer_search("irc", "freenode.#weechat"), "/whois FlashCode")
----------------------------------------

[[network]]
Network
~~~~~~~

Funzioni di rete.

weechat_network_pass_proxy
^^^^^^^^^^^^^^^^^^^^^^^^^^

Stabilisce una connessione/autenticazione con un proxy.

Prototipo:

[source,C]
----------------------------------------
int weechat_network_pass_proxy (const char *proxy,
                                int sock,
                                const char *address,
                                int port);
----------------------------------------

Argomenti:

* 'proxy': nome del proxy da utilizzare
* 'sock': socket da utilizzare
* 'address': indirizzo (nome host o indirizzo IP)
* 'port': port

Valore restituito:

* 1 se la connessione è andata a buon fine, 0 in caso di
  errore

Esempio in C:

[source,C]
----------------------------------------
if (weechat_network_pass_proxy ("my_proxy", sock, "irc.freenode.net", 6667))
{
    /* OK */
}
else
{
    /* errore */
}
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_network_connect_to
^^^^^^^^^^^^^^^^^^^^^^^^^^

Stabilisce una connessione con un host remoto.

Prototipo:

[source,C]
----------------------------------------
int weechat_network_connect_to (const char *proxy,
                                int sock,
                                unsigned long address,
                                int port);
----------------------------------------

Argomenti:

* 'proxy': nome del proxy da utilizzare
* 'sock': socket da utilizzare
* 'address': indirizzo
* 'port': porta

Valore restituito:

* 1 se la connessione è andata a buon fine, 0 in
  caso di errore

Esempio in C:

[source,C]
----------------------------------------
struct sockaddr_in addr;
socklen_t length;
unsigned long address;

memset (&addr, 0, sizeof (struct sockaddr_in));
length = sizeof (addr);
getsockname (sock, (struct sockaddr *) &addr, &length);
addr.sin_family = AF_INET;
address = ntohl (addr.sin_addr.s_addr);

if (weechat_network_connect_to (NULL, sock, address, 6667))
{
    /* OK */
}
else
{
    /* errore */
}
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

[[infos]]
Info
~~~~

Funzioni per ottenere info.

weechat_info_get
^^^^^^^^^^^^^^^^

Restituisce la info, come stringa, da WeeChat o da un plugin.

Prototipo:

[source,C]
----------------------------------------
const char *weechat_info_get (const char *info_name, const char *arguments);
----------------------------------------

Argomenti:

* 'info_name': nome delle informazioni da leggere:
include::autogen/plugin_api/infos.txt[]
* 'arguments': argomenti per l'informazione richiesta (opzionake, NULL se non
  è richiesto alcun argomento)

Valore restituito:

* stringa con l'informazione richiesta, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL, "Current WeeChat version is: %s (compiled on %s)",
                weechat_info_get ("version", NULL),
                weechat_info_get ("date", NULL));
weechat_printf (NULL, "WeeChat home is: %s",
                weechat_info_get ("weechat_dir", NULL));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.info_get(info_name, arguments)

# esempio
weechat.prnt("", "Current WeeChat version is: %s (compiled on %s)"
    % (weechat.info_get("version", ""), weechat.info_get("date", ""))
weechat.prnt("", "WeeChat home is: %s" % weechat.info_get("weechat_dir"))
----------------------------------------

weechat_info_get_hashtable
^^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.4._

Restituisce una info, come tabella hash, da WeeChat o da un plugin.

Prototipo:

[source,C]
----------------------------------------
struct t_hashtable *weechat_info_get_hashtable (const char *info_name,
                                                struct t_hashtable *hashtable);
----------------------------------------

Arguments:

* 'info_name': nome della info da leggere
include::autogen/plugin_api/infos_hashtable.txt[]
* 'hashtable': tabella hash con argomenti (dipende dalla info richiesta)
* (opzionale, NULL se l'argomento non viene richiesto)

Valore restituito:

* tabella hash con la info richiesta, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
struct t_hashtable *hashtable_in, *hashtable_out;

hashtable_in = weechat_hashtable_new (8,
                                      WEECHAT_HASHTABLE_STRING,
                                      WEECHAT_HASHTABLE_STRING,
                                      NULL,
                                      NULL);
if (hashtable_in)
{
    weechat_hashtable_set (hashtable_in, "message",
                           ":nick!user@host PRIVMSG #weechat :message here");
    hashtable_out = weechat_info_get_hashtable ("irc_parse_message",
                                                hashtable_in);
    /*
     * now hashtable_out has following keys/values:
     *   "nick"     : "nick"
     *   "host"     : "nick!user@host"
     *   "command"  : "PRIVMSG"
     *   "channel"  : "#weechat"
     *   "arguments": "#weechat :message here"
     */
    weechat_hashtable_free (hashtable_in);
    weechat_hashtable_free (hashtable_out);
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototype
dict = weechat.info_get_hashtable(info_name, dict_in)

# esempio
dict_in = { "message": ":nick!user@host PRIVMSG #weechat :message here" }
weechat.prnt("", "message parsed: %s"
             % weechat.info_get_hashtable("irc_parse_message", dict_in))
----------------------------------------

[[infolists]]
Liste info
~~~~~~~~~~

Una lista info è una lista di "elementi". Ciascun elemento contiene
delle variabili.

Ad esempio, la lista info "irc_server" ha N elementi (N è il numero di
server IRC definiti). Per ogni elemento, esistono variabili come "name",
"buffer", "is connected",...

Ogni variabile ha un tipo e un valore. I tipi possibili sono:

* 'integer': qualunque valore intero
* 'string': qualunque valore stringa
* 'pointer': qualunque puntatore
* 'buffer': buffer di lunghezza fissa, contenente qualunque dato
* 'time': valore tempo

weechat_infolist_new
^^^^^^^^^^^^^^^^^^^^

Crea una nuova lista info.

Prototipo:

[source,C]
----------------------------------------
struct t_infolist *weechat_infolist_new ();
----------------------------------------

Valore restituito:

* puntatore alla nuova lista info

Esempio in C:

[source,C]
----------------------------------------
struct t_infolist *infolist = weechat_infolist_new ();
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
infolist = weechat.infolist_new()

# esempio
infolist = weechat.infolist_new()
----------------------------------------

weechat_infolist_new_item
^^^^^^^^^^^^^^^^^^^^^^^^^

Aggiunge un elemento alla lista info.

Prototipo:

[source,C]
----------------------------------------
struct t_infolist_item *weechat_infolist_new_item (struct t_infolist *infolist);
----------------------------------------

Argomenti:

* 'infolist': puntatore alla lista info

Valore restituito:

* puntatore al nuovo elemento

Esempio in C:

[source,C]
----------------------------------------
struct t_infolist_item *item = weechat_infolist_new_item (infolist);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
item = weechat.infolist_new_item(infolist)

# esempio
item = weechat.infolist_new_item(infolist)
----------------------------------------

weechat_infolist_new_var_integer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Aggiunge una variabile intera ad un elemento della
lista info.

Prototipo:

[source,C]
----------------------------------------
struct t_infolist_var *weechat_infolist_new_var_integer (struct t_infolist_item *item,
                                                         const char *name,
                                                         int value);
----------------------------------------

Argomenti:

* 'item': puntatore all'elemento della lista info
* 'name': nome variabile
* 'value': valore intero

Valore restituito:

* puntatore alla nuova variabile

Esempio in C:

[source,C]
----------------------------------------
struct t_infolist_var *var = weechat_infolist_new_var_integer (item,
                                                               "my_integer",
                                                               123);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
var = weechat.infolist_new_var_integer(item, name, value)

# esempio
var = weechat.infolist_new_var_integer(item, "my_integer", 123)
----------------------------------------

weechat_infolist_new_var_string
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Aggiunge una variabile stringa ad un elemento
della lista info.

Prototipo:

[source,C]
----------------------------------------
struct t_infolist_var *weechat_infolist_new_var_string (struct t_infolist_item *item,
                                                        const char *name,
                                                        const char *value);
----------------------------------------

Argomenti:

* 'item': puntatore all'elemento della lista info
* 'name': nome variabile
* 'value': valore stringa

Valore restituito:

* puntatore alla nuova variabile

Esempio in C:

[source,C]
----------------------------------------
struct t_infolist_var *var = weechat_infolist_new_var_string (item,
                                                              "my_string",
                                                              "value");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
var = weechat.infolist_new_var_string(item, name, value)

# esempio
var = weechat.infolist_new_var_string(item, "my_string", "value")
----------------------------------------

weechat_infolist_new_var_pointer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Aggiunge una variabile puntatore ad un elemento
della lista info.

Prototipo:

[source,C]
----------------------------------------
struct t_infolist_var *weechat_infolist_new_var_pointer (struct t_infolist_item *item,
                                                         const char *name,
                                                         void *pointer);
----------------------------------------

Argomenti:

* 'item': puntatore all'elemento della lista info
* 'name': nome variabile
* 'pointer': puntatore

Valore restituito:

* puntatore alla nuova variabile

Esempio in C:

[source,C]
----------------------------------------
struct t_infolist_var *var = weechat_infolist_new_var_pointer (item,
                                                               "my_pointer",
                                                               &pointer);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
var = weechat.infolist_new_var_pointer(item, name, pointer)

# esempio
var = weechat.infolist_new_var_pointer(item, "my_pointer", pointer)
----------------------------------------

weechat_infolist_new_var_buffer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Aggiunge una variabile puntatore ad un elemento della lista info.

Prototipo:

[source,C]
----------------------------------------
struct t_infolist_var *weechat_infolist_new_var_buffer (struct t_infolist_item *item,
                                                        const char *name,
                                                        void *pointer,
                                                        int size);
----------------------------------------

Argomenti:

* 'item': puntatore all'elemento della lista info
* 'name': nome della variabile
* 'pointer': puntatore al buffer
* 'size': dimensione del buffer

Valore restituito:

* puntatore alla nuova variabile

Esempio in C:

[source,C]
----------------------------------------
char buffer[256];
/* ... */
struct t_infolist_var *var = weechat_infolist_new_variable_buffer (item,
                                                                   "my_buffer",
                                                                   &buffer,
                                                                   sizeof (buffer));
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_infolist_new_var_time
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Aggiunge una variabile tempo ad un elemento della lista info.

Prototipo:

[source,C]
----------------------------------------
struct t_infolist_var *weechat_infolist_new_var_time (struct t_infolist_item *item,
                                                      const char *name,
                                                      time_t time);
----------------------------------------

Argomenti:

* 'item': puntatore all'elemento della lista info
* 'name': nome della variabile
* 'time': valore tempo

Valore restituito:

* puntatore alla nuova variabile

Esempio in C:

[source,C]
----------------------------------------
struct t_infolist_var *var = weechat_infolist_new_variable_time (item,
                                                                 "my_time",
                                                                 time (NULL));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
var = weechat.infolist_new_var_time(item, name, time)

# esempio
var = weechat.infolist_new_var_time(item, "my_time", int(time.time()))
----------------------------------------

weechat_infolist_get
^^^^^^^^^^^^^^^^^^^^

Restituisce una lista info da WeeChat o da un plugin.

Prototipo:

[source,C]
----------------------------------------
struct t_infolist *weechat_infolist_get (const char *infolist_name,
                                         void *pointer,
                                         const char *arguments);
----------------------------------------

Argomenti:

* 'infolist_name': nome della lista info da leggere:
include::autogen/plugin_api/infolists.txt[]
* 'pointer': puntatore ad un elemento, per ricevere solo questo
  elemento nella lista info (opzionale, può essere NULL)
* 'arguments': argomenti per la lista info richiesta (opzionale, NULL se
  non è necessario alcun argomento)

Valore restituito:

* puntatore alla lista info, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
struct t_infolist *infolist = weechat_infolist_get ("irc_server", NULL, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
infolist = weechat.infolist_get(infolist_name, pointer, arguments)

# esempio
infolist = weechat.infolist_get("irc_server, "", "")
----------------------------------------

weechat_infolist_next
^^^^^^^^^^^^^^^^^^^^^

Sposta "cursor" all'elemento successivo nella lista info. La prima chiamata
a questa funzione per una lista info sposta il cursore al primo elemento
nella lista info.

Prototipo:

[source,C]
----------------------------------------
int weechat_infolist_next (struct t_infolist *infolist);
----------------------------------------

Argomenti:

* 'infolist': puntatore alla lista info

Valore restituito:

* 1 se il cursore è stato spostato sull'elemento successivo, 0 se è
  stata raggiunta la fine della lista

Esempio in C:

[source,C]
----------------------------------------
if (weechat_infolist_next (infolist))
{
    /* legge variabili nell'elemento... */
}
else
{
    /* nessun altro elemento disponibile */
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
rc = weechat.infolist_next(infolist)

# esempio
rc = weechat.infolist_next(infolist)
if rc:
    # legge variabili nell'elemento...
else:
    # nessun altro elemento disponibile
----------------------------------------

weechat_infolist_prev
^^^^^^^^^^^^^^^^^^^^^

Sposta "cursor" all'elemento precedente nella lista info. La prima
chiamata a questa funzione per una lista info sposta il cursore
all'ultimo elemento.

Prototipo:

[source,C]
----------------------------------------
int weechat_infolist_prev (struct t_infolist *infolist);
----------------------------------------

Argomenti:

* 'infolist': puntatore alla lista info

Valore restituito:

* 1 se il cursore è stato spostato sull'elemento precedente, 0 se
  è stato raggiunto l'inizio della lista

Esempio in C:

[source,C]
----------------------------------------
if (weechat_infolist_prev (infolist))
{
    /* legge variabili nell'elemento... */
}
else
{
    /* nessun altro elemento disponibile */
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
rc = weechat.infolist_prev(infolist)

# esempio
rc = weechat.infolist_prev(infolist)
if rc:
    # read variables in item...
else:
    # no more item available
----------------------------------------

weechat_infolist_reset_item_cursor
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Ripristina "cursor" per la lista info.

Prototipo:

[source,C]
----------------------------------------
void weechat_infolist_reset_item_cursor (struct t_infolist *infolist);
----------------------------------------

Argomenti:

* 'infolist': puntatore alla lista info

Esempio in C:

[source,C]
----------------------------------------
weechat_infolist_reset_item_cursor (infolist);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.infolist_reset_item_cursor(infolist)

# esempio
weechat.infolist_reset_item_cursor(infolist)
----------------------------------------

weechat_infolist_fields
^^^^^^^^^^^^^^^^^^^^^^^

Restituisce una lista di campi per l'elemento della
lista info corrente.

Prototipo:

[source,C]
----------------------------------------
const char *weechat_infolist_fields (struct t_infolist *infolist);
----------------------------------------

Argomenti:

* 'infolist': puntatore alla lista info

Valore restituito:

* stringa con una lista di campi per l'elemento della lista info corrente.
  La lista è separata da virgole, e contiene lettere per tipo, seguite dal
  nome della variabile. I tipi sono: "i" (intero), "s" (stringa), "p" (puntatore),
  "b" (buffer), "t" (tempo).

Esempio in C:

[source,C]
----------------------------------------
const char *fields = weechat_infolist_fields (infolist);
/* i campi contengono qualcosa come:
   "i:my_integer,s:my_string,p:my_pointer,b:my_buffer,t:my_time" */
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
fields = weechat.infolist_fields(infolist)

# esempio
fields = weechat.infolist_fields(infolist)
# i campi contengono qualcosa come:
# "i:my_integer,s:my_string,p:my_pointer,b:my_buffer,t:my_time"
----------------------------------------

weechat_infolist_integer
^^^^^^^^^^^^^^^^^^^^^^^^

Restituisce il valore della variabile intera nell'elemento
corrente della lista info.

Prototipo:

[source,C]
----------------------------------------
int weechat_infolist_integer (struct t_infolist *infolist, const char *var);
----------------------------------------

Argomenti:

* 'infolist': puntatore alla lista info
* 'var': nome della variabile (deve essere di tipo "integer")

Valore restituito:

* valore intero della variabile

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL, "integer = %d",
                weechat_infolist_integer (infolist, "my_integer"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.infolist_integer(infolist, var)

# esempio
weechat.prnt("", "integer = %d" % weechat.infolist_integer(infolist, "my_integer"))
----------------------------------------

weechat_infolist_string
^^^^^^^^^^^^^^^^^^^^^^^

Restituisce il valore della variabile stringa nell'elemento
della lista info corrente.

Prototipo:

[source,C]
----------------------------------------
const char *weechat_infolist_string (struct t_infolist *infolist, const char *var);
----------------------------------------

Argomenti:

* 'infolist': puntatore alla lista info
* 'var': nome della variabile (deve essere di tipo "string")

Valore restituito:

* valore stringa della variabile

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL, "string = %s",
                weechat_infolist_string (infolist, "my_string"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.infolist_string(infolist, var)

# esempio
weechat.prnt("", "string = %s" % weechat.infolist_string(infolist, "my_string"))
----------------------------------------

weechat_infolist_pointer
^^^^^^^^^^^^^^^^^^^^^^^^

Restituisce il valore della variabile puntatore nell'elemento
della lista info corrente.

Prototipo:

[source,C]
----------------------------------------
void *weechat_infolist_pointer (struct t_infolist *infolist, const char *var);
----------------------------------------

Argomenti:

* 'infolist': puntatore alla lista info
* 'var': nome della variabile (deve essere di tipo "pointer")

Valore restituito:

* puntatore al valore della variabile

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL, "pointer = 0x%lx",
                weechat_infolist_pointer (infolist, "my_pointer"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.infolist_pointer(infolist, var)

# esempio
weechat.prnt("", "pointer = 0x%lx" % weechat.infolist_pointer(infolist, "my_pointer"))
----------------------------------------

weechat_infolist_buffer
^^^^^^^^^^^^^^^^^^^^^^^

Restituisce il valore della variabile buffer nell'elemento corrente
della lista info.

Prototipo:

[source,C]
----------------------------------------
void *weechat_infolist_buffer (struct t_infolist *infolist, const char *var,
                               int *size);
----------------------------------------

Argomenti:

* 'infolist': puntatore alla lista info
* 'var': nome della variabile (deve essere di tipo "buffer")
* 'size': puntatore ad una variabile intera, verrà impostata con la
  dimensione del buffer

Valore restituito:

* puntatore al buffer

Esempio in C:

[source,C]
----------------------------------------
int size;
void *pointer = weechat_infolist_buffer (infolist, "my_buffer", &size);
weechat_printf (NULL, "buffer = 0x%lx, size = %d",
                pointer, size);
----------------------------------------

[NOTE]
Questa funzione non è disponibile nelle API per lo scripting.

weechat_infolist_time
^^^^^^^^^^^^^^^^^^^^^

Restituisce il valore della variabile data/ora nell'elemento
attivo della lista info.

Prototipo:

[source,C]
----------------------------------------
time_t weechat_infolist_time (struct t_infolist *infolist, const char *var);
----------------------------------------

Argomenti:

* 'infolist': puntatore alla lista info
* 'var': nome della variabile (deve essere di tipo "time")

Valore restituito:

* valore della variabile nel formato data/ora

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL, "time = %ld",
                weechat_infolist_time (infolist, "my_time"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.infolist_time(infolist, var)

# esempio
weechat.prnt("", "time = %ld" % weechat.infolist_time(infolist, "my_time"))
----------------------------------------

weechat_infolist_free
^^^^^^^^^^^^^^^^^^^^^

Libera una lista info.

Prototipo:

[source,C]
----------------------------------------
void weechat_infolist_free (struct t_infolist *infolist);
----------------------------------------

Argomenti:

* 'infolist': puntatore alla lista info

Esempio in C:

[source,C]
----------------------------------------
weechat_infolist_free (infolist);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.infolist_free(infolist)

# esempio
weechat.infolist_free(infolist)
----------------------------------------

[[upgrade]]
Aggiornamento
~~~~~~~~~~~~~

Funzioni per l'aggiornamento di WeeChat (comando "/upgrade").

weechat_upgrade_new
^^^^^^^^^^^^^^^^^^^

Crea o legge un file per l'aggiornamento.

Prototipo:

[source,C]
----------------------------------------
struct t_upgrade_file *weechat_upgrade_new (const char *filename, int write);
----------------------------------------

Argomenti:

* 'filename': nome del file (l'estensione ".upgrade" verrà aggiunta a questo nome
  da WeeChat)
* 'write':
** '1': crea il file (in modalità scrittura, prima dell'aggiornamento)
** '0': legge il file (dopo l'aggiornamento)

Valore restituito:

* puntatore al file di aggiornamento

Esempio in C:

[source,C]
----------------------------------------
struct t_upgrade_file *upgrade_file = weechat_upgrade_new ("my_file", 1);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
upgrade_file = weechat.upgrade_new(filename, write)

# esempio
upgrade_file = weechat.upgrade_new("my_file", 1)
----------------------------------------

weechat_upgrade_write_object
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Scrive un oggetto nel file di aggiornamento.

Prototipo:

[source,C]
----------------------------------------
int weechat_upgrade_write_object (struct t_upgrade_file *upgrade_file,
                                  int object_id,
                                  struct t_infolist *infolist);
----------------------------------------

Argomenti:

* 'upgrade_file': puntatore al file di aggiornamento
* 'object_id': id per l'oggetto
* 'infolist': lista info da scrivere nel file

Valore restituito:

* 1 se ok, 0 se errore

Esempio in C:

[source,C]
----------------------------------------
if (weechat_upgrade_write_object (upgrade_file, 1, &infolist))
{
    /* ok */
}
else
{
    /* errore */
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
rc = weechat.upgrade_write_object(upgrade_file, object_id, infolist)

# esempio
weechat.upgrade_write_object(upgrade_file, 1, infolist)
----------------------------------------

weechat_upgrade_read
^^^^^^^^^^^^^^^^^^^^

Legge un file di aggiornamento.

Prototipo:

[source,C]
----------------------------------------
int weechat_upgrade_read (struct t_upgrade_file *upgrade_file,
                          int (*callback_read)(void *data,
                                               struct t_upgrade_file *upgrade_file,
                                               int object_id,
                                               struct t_infolist *infolist),
                          void *callback_read_data);
----------------------------------------

Argomenti:

* 'upgrade_file': puntatore al file di aggiornamento
* 'callback_read': funzione chiamata per ogni oggetto letto nel file
  di aggiornamento
* 'callback_read_data': puntatore assegnato per la lettura della chiamata
  quando chiamato da WeeChat

Valore restituito:

* 1 se ok, 0 se errore

Esempio in C:

[source,C]
----------------------------------------
int
my_upgrade_read_cb (struct t_upgrade_file *upgrade_file,
                    int object_id,
                    struct t_infolist *infolist)
{
    /* lettura variabili... */
    return WEECHAT_RC_OK;
}

weechat_upgrade_read (upgrade_file, &my_upgrade_read_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
rc = weechat.upgrade_read(upgrade_file, callback_read, callback_read_data)

# esempio
def my_upgrade_read_cb(upgrade_file, object_id, infolist):
    # lettura variabili...
    return weechat.WEECHAT_RC_OK

weechat.upgrade_read(upgrade_file, "my_upgrade_read_cb", ""))
----------------------------------------

weechat_upgrade_close
^^^^^^^^^^^^^^^^^^^^^

Chiude un file di aggiornamento.

Prototipo:

[source,C]
----------------------------------------
void weechat_upgrade_close (struct t_upgrade_file *upgrade_file);
----------------------------------------

Argomenti:

* 'upgrade_file': puntatore al file di aggiornamento

Esempio in C:

[source,C]
----------------------------------------
weechat_upgrade_close (upgrade_file);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.upgrade_close(upgrade_file)

# esempio
weechat.upgrade_close(upgrade_file)
----------------------------------------