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
scaricato 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_toupper (str); /* str ora è: "ABCDé" */
----------------------------------------

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

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

Confronta stringa non sensibile alle maiuscole e alla localizzazione.

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_strcasecmp_range
^^^^^^^^^^^^^^^^^^^^^^^^

Confronta stringa non sensibile alle maiuscole e alla localizzazione, usando una
serie per il confronto.

Prototipo:

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

Argomenti:

* 'string1': prima stringa da comparare
* 'string2': seconda stringa da comparare
* 'range': numero di caratteri nel confronto maiuscole/minuscole, ad esempio:
** 26: "A-Z" vengono ridotti ad "a-z"
** 29: "A-Z [ \ ]" vengono ridotti ad "a-z { | }"
** 30: "A-Z [ \ ] ^" vengono ridotti ad "a-z { | } ~"

[NOTE]
I valori 29 e 30 vengono usati da alcuni protocolli come IRC.

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 ("nick{away}", "NICK[AWAY]"); /* == 0 */
----------------------------------------

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

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

Confronta stringa indipendente non sensibile alle maiuscole e alla
localizzazione, 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 string1 < string2
** zero se string1 == string1
** positiva se string1 > string2

Esempio in C:

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

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

weechat_strncasecmp_range
^^^^^^^^^^^^^^^^^^^^^^^^^

Confronta una stringa non sensibile alle maiuscole e alla localizzazione, per un
numero 'max' di caratteri, usando una serie per il confronto.

Prototipo:

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

Argomenti:

* 'string1': prima stringa da comparare
* 'string2': seconda stringa da comparare
* 'max': numero massimo di caratteri da comparare
* 'range': numero di caratteri nel confronto maiuscole/minuscole, ad esempio:
** 26: "A-Z" vengono ridotti ad "a-z"
** 29: "A-Z [ \ ]" vengono ridotti ad "a-z { | }"
** 30: "A-Z [ \ ] ^" vengono ridotti ad "a-z { | } ~"

[NOTE]
I valori 29 e 30 vengono usati da alcuni protocolli come IRC.

Valore restituito:

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

Esempio in C:

[source,C]
----------------------------------------
int diff = weechat_strncasecmp_range ("nick{away}", "NICK[away]", 6, 29); /* == 0 */
----------------------------------------

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

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

Confronta una stringa localizzata (e opzionalmente non sensibile alle
maiuscole), 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 sensibile alle maiuscole, 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 non sensibile alle maiuscole e indipendente dalla
localizzazione.

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)
* 'case_sensitive': 1 per il confronto sensibile alle maiuscole, altrimenti 0

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_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_regex_flags
^^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.7._

Restituisce sia il puntatore sulla stringa dopo le flag che la mask con le flag
per compilare l'espressione regolare.

Prototipo:

[source,C]
----------------------------------------
const char *weechat_string_regex_flags (const char *regex, int default_flags, int *flags)
----------------------------------------

Argomenti:

* 'regex': espressione regolare
* 'default_flags': combinazione dei seguenti valori (consultare `man regcomp`):
** REG_EXTENDED
** REG_ICASE
** REG_NEWLINE
** REG_NOSUB
* 'flags': pointer value is set with flags used in regular expression (default
  flags + flags set in regular expression)

Flags must be at beginning of regular expression. Format is:
"(?eins-eins)string".

Allowed flags are:

* 'e': POSIX extended regular expression ('REG_EXTENDED')
* 'i': case insensitive ('REG_ICASE')
* 'n': match-any-character operators don't match a newline ('REG_NEWLINE')
* 's': support for substring addressing of matches is not required ('REG_NOSUB')

Valore restituito:

* pointer in 'regex', after flags

Esempio in C:

[source,C]
----------------------------------------
const char *regex = "(?i)test";
int flags;
const char *ptr_regex = weechat_string_regex_flags (regex, REG_EXTENDED, &flags);
/* ptr_regex == "test", flags == REG_EXTENDED | REG_ICASE */
----------------------------------------

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

weechat_string_regcomp
^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.7._

Compila un'espressione regolare usando flag opzionali all'inizio della stringa
(per il formato delle flag consultare
<<_weechat_string_regex_flags,weechat_string_regex_flags>>).

Prototipo:

[source,C]
----------------------------------------
int weechat_string_regcomp (void *preg, const char *regex, int default_flags)
----------------------------------------

Argomenti:

* 'preg': pointer to 'regex_t' structure
* 'regex': regular expression
* 'default_flags': combination of following values (see `man regcomp`):
** REG_EXTENDED
** REG_ICASE
** REG_NEWLINE
** REG_NOSUB

Valore restituito:

* same return code as function `regcomp` (0 if ok, other value for error,
  see `man regcomp`)

Esempio in C:

[source,C]
----------------------------------------
regex_t my_regex;
if (weechat_string_regcomp (&my_regex, "(?i)test", REG_EXTENDED) != 0)
{
    /* error */
}
----------------------------------------

[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_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':
** 0: ogni stringa conterrà una parola
** 1: ogni stringa conterrà tutte le stringhe fino a fine riga
   (consultare il seguente esempio)
** 2: come il punto 1, ma non rimuove i delimitatori alla fine della stringa
   prima della divisione (_novità nella versione 0.3.6_)
* 'num_items_max': numero massimo di elementi creati (0 = nessun limite)
* 'num_items': puntatore ad int che conterrà il numero di elementi creati

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 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.

Prototipo:

[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 è '/').

Prototipo:

[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]
----------------------------------------
# prototipo
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.

Prototipo:

[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]
----------------------------------------
# prototipo
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 (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 la sensibilità alle maiuscole.

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 alla callback quando chiamata 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_search_pos
^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.4._

Cerca la posizione di un elemento nella lista.

Prototipo:

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

Argomenti:

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

Valore restituito:

* posizione dell'elemento trovato, -1 se non trovato

Esempio in C:

[source,C]
----------------------------------------
int pos_item = weechat_list_search_pos (list, "my data");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
pos_item = weechat.list_search_pos(list, data)

# esempio
pos_item = weechat.list_search_pos(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_casesearch_pos
^^^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.4._

Cerca la posizione di un elemento in una lista, ricerca normale.

Prototipo:

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

Argomenti:

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

Valore restituito:

* posizione dell'elemento trovato, -1 se non trovato

Esempio in C:

[source,C]
----------------------------------------
int pos_item = weechat_list_casesearch_pos (list, "my data");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
pos_item = weechat.list_casesearch_pos(list, data)

# esempio
pos_item = weechat.list_casesearch_pos(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));
----------------------------------------

Argomenti:

* '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), argomenti e valore restituito:
** 'struct t_hashtable *hashtable': puntatore alla tabella hash
** 'const void *key': chiave
** return value: hash della chiave
* '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), argomenti e valore restituito:
** 'struct t_hashtable *hashtable': puntatore alla tabella hash
** 'const void *key1': prima chiave
** 'const void *key2': seconda chiave
** valore restituito:
*** numero negativo se 'key1' è minore di 'key2'
*** 0 se 'key1' è uguale a 'key2'
*** numero positivo se 'key1' è maggiore di 'key2'

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);
----------------------------------------

Argomenti:

* '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_hashtable *hashtable,
                    void (*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_map_string
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.7._

Chiama una funzione su tutte le voci della tabella hash, inviando chiavi e
valori come stringhe.

Prototipo:

[source,C]
----------------------------------------
void hashtable_map_string (struct t_hashtable *hashtable,
                           void (*callback_map)(void *data,
                                                struct t_hashtable *hashtable,
                                                const char *key,
                                                const char *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

[NOTE]
Le stringhe 'key' e 'value' inviate alla callback sono temporanee, vengono
eliminate dopo la chiamata alla callback.

Esempio in C:

[source,C]
----------------------------------------
void
map_cb (void *data, struct t_hashtable *hashtable,
        const char *key, const char *value)
{
    /* display key and value */
    weechat_printf (NULL, "key: '%s', value: '%s'",
                    key, value);
}
/* ... */
weechat_hashtable_map_string (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.

Prototipo:

[source,C]
----------------------------------------
const char *weechat_hashtable_get_string (struct t_hashtable *hashtable,
                                          const char *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")
** 'keys_sorted': stringa con l'elenco di chiavi ordinate (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")
** 'keys_values_sorted': stringa con la lista di chiavi e valori (ordinata per 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_set_pointer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.4._

Imposta il valore puntatore della proprietà di una tabella hash.

Prototipo:

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

Argomenti:

* 'hashtable': puntatore alla tabella hash
* 'property' e 'value': nome della proprietà, con il proprio valore:
** 'callback_free_value': imposta la funzione callback usata per
   liberare i valori nella tabella hash

Esempio in C:

[source,C]
----------------------------------------
void
my_free_value_cb (struct t_hashtable *hashtable, const void *key, void *value)
{
    /* ... */
}

weechat_hashtable_set_pointer (hashtable, "callback_free_value", &my_free_value_cb);
----------------------------------------

[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_00000"  = "key1"
     "testhash_value_00000" = "value 1"
     "testhash_name_00001"  = "key2"
     "testhash_value_00001" = "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 e valore
  restituito:
** 'void *data': puntatore
** 'struct t_config_file *config_file': puntatore al file di configurazione
** valore restituito:
*** 'WEECHAT_CONFIG_READ_OK'
*** 'WEECHAT_CONFIG_READ_MEMORY_ERROR'
*** 'WEECHAT_CONFIG_READ_FILE_NOT_FOUND'
* '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 e valore restituito:
** '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
** valore restituito:
*** 'WEECHAT_CONFIG_READ_OK'
*** 'WEECHAT_CONFIG_READ_MEMORY_ERROR'
*** 'WEECHAT_CONFIG_READ_FILE_NOT_FOUND'
* 'callback_read_data': puntatore fornito alla callback quando chiamata 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 e valore restituito:
** '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
** valore restituito:
*** 'WEECHAT_CONFIG_WRITE_OK'
*** 'WEECHAT_CONFIG_WRITE_ERROR'
*** 'WEECHAT_CONFIG_WRITE_MEMORY_ERROR'
* callback_write_data: puntatore fornito alla callback quando chiamata da WeeChat
* callback_write_default: funzione chiamata quando i valori predefiniti per la sezione
  devono essere scritti in un file, argomenti e valore restituito:
** 'void *data': puntatore
** 'struct t_config_file *config_file': puntatore al file di configurazione
** 'const char *section_name': nome della sezione
** valore restituito:
*** 'WEECHAT_CONFIG_WRITE_OK'
*** 'WEECHAT_CONFIG_WRITE_ERROR'
*** 'WEECHAT_CONFIG_WRITE_MEMORY_ERROR'
* 'callback_write_default_data': puntatore fornito alla callback quando chiamata 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 e valore restituito:
** '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
** valore restituito:
*** 'WEECHAT_CONFIG_OPTION_SET_OK_CHANGED'
*** 'WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE'
*** 'WEECHAT_CONFIG_OPTION_SET_ERROR'
*** 'WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND'
* 'callback_create_option_data': puntatore fornito alla callback quando chiamata
  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 e valore restituito:
** '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
** valore restituito:
*** 'WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET'
*** 'WEECHAT_CONFIG_OPTION_UNSET_OK_RESET'
*** 'WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED'
*** 'WEECHAT_CONFIG_OPTION_UNSET_ERROR'
* 'callback_delete_option_data': puntatore fornito alla callback quando chiamata
  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,
    void (*callback_change)(void *data,
                            struct t_config_option *option),
    void *callback_change_data,
    void (*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 e valore restituito:
** 'void *data': puntatore
** 'struct t_config_option *option': puntatore all'opzione
** 'const char *value': nuovo valore per l'opzione
** valore restituito:
*** 1 se il valore è corretto
*** 0 se il valore non è valido
* 'callback_check_value_data': puntatore fornito alla callback check_value
  quando chiamata 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, 0, "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);
----------------------------------------

Argomenti:

* '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_boolean(option)

# esempio
if weechat.config_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_boolean_default(option)

# esempio
if weechat.config_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_integer(option)

# esempio
if weechat.config_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_integer_default(option)

# esempio
if weechat.config_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_string(option)

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

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

Restituisce il valore stringa predefinito di un'opzione.

Prototipo:

[source,C]
----------------------------------------
const char *weechat_config_string_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_string_default(option)

# esempio
value = weechat.config_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_color(option)

# esempio
value = weechat.config_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_color_default(option)

# esempio
value = weechat.config_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_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_set_desc_plugin
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.5._

Imposta la descrizione per l'opzione nel file di configurazione dei plugin
(plugins.conf).

Prototipo:

[source,C]
----------------------------------------
void weechat_config_set_desc_plugin (const char *option_name,
                                     const char *description);
----------------------------------------

Argomenti:

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

[NOTE]
Non è un problema se l'opzione (plugins.var.xx.option_name) non esiste.
Una futura creazione dell'opzione con questo nome userà questa descrizione.

Esempio in C:

[source,C]
----------------------------------------
weechat_config_set_desc_plugin ("option", "description of option");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.config_set_desc_plugin(option_name, description)

# esempio
version = weechat.info_get("version_number", "") or 0
if int(version) >= 0x00030500:
    weechat.config_set_desc_plugin("option", "description of option")
----------------------------------------

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:
    # ...
----------------------------------------

[[key_bindings]]
Combinazione tasti
~~~~~~~~~~~~~~~~~~

Funzioni per le combinazioni dei tasti.

weechat_key_bind
^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.6._

Aggiunge una nuova combinazione tasto.

[NOTE]
A differenza del comando `/key bind`, questa funzione non cambia mai una
combinazione tasti esistente, ma ne vengono create di nuove. Per rimuovere
una combinazione tasti, usare <<_weechat_key_unbind,weechat_key_unbind>>.

Prototipo:

[source,C]
----------------------------------------
int weechat_key_bind (const char *context, struct t_hashtable *keys);
----------------------------------------

Argomenti:

* 'context': contesto per i tasti:
** 'default': contesto default (azioni comuni)
** 'search': contesto search (quando si cerca testo nel buffer)
** 'cursor': movimento libero del cursore sullo schermo
** 'mouse': tasti per gli eventi del mouse
* 'keys': tabella hash con le combinazioni dei tasti

Valore restituito:

* numero delle combinazioni tasti aggiunte

Esempio in C:

[source,C]
----------------------------------------
struct t_hashtable *keys = weechat_hashtable_new (8,
                                                  WEECHAT_HASHTABLE_STRING,
                                                  WEECHAT_HASHTABLE_STRING,
                                                  NULL,
                                                  NULL);
if (keys)
{
    weechat_hashtable_set (keys, "@chat(plugin.buffer):button1", "hsignal:test_mouse");
    weechat_hashtable_set (keys, "@chat(plugin.buffer):wheelup", "/mycommand up");
    weechat_hashtable_set (keys, "@chat(plugin.buffer):wheeldown", "/mycommand down");
    weechat_key_bind ("mouse", keys);
    weechat_hashtable_free (keys);
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
num_keys = weechat.key_bind(context, keys)

# esempio
keys = { "@chat(python.test):button1": "hsignal:test_mouse",
         "@chat(python.test):wheelup": "/mycommand up",
         "@chat(python.test):wheeldown": "/mycommand down" }
weechat.key_bind("mouse", keys)
----------------------------------------

weechat_key_unbind
^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.6._

Rimuove una o più associazioni tasti.

[WARNING]
Alla chiamata di questa funzione, assicurarsi che non venga rimossa una
combinazione tasti definita dall'utente.

Prototipo:

[source,C]
----------------------------------------
int weechat_key_unbind (const char *context, const char *key);
----------------------------------------

Argomenti:

* 'context': contesto per i tasti (consultare <<_weechat_key_bind,weechat_key_bind>>)
* 'key': tasto da rimuovere o un valore speciale "area:XXX" per rimuovere tutti
  i tasti che hanno 'XXX' come prima o seconda area

Valore restituito:

* numero di combinazioni tasti rimosse

Esempio in C:

[source,C]
----------------------------------------
/* rimuove un singolo tasto */
weechat_key_unbind ("mouse", "@chat(plugin.buffer):button1");

/* rimuove tutti i tasti con la zona "chat(plugin.buffer)" */
weechat_key_unbind ("mouse", "area:chat(plugin.buffer)");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
num_keys = weechat.key_unbind(context, key)

# esempi

# rimuove un singolo tasto
weechat.key_unbind("mouse", "@chat(plugin.buffer):button1")

# rimuove tutti i tasti con la zona "chat(python.test)"
weechat.key_unbind("mouse", "area:chat(python.test)")
----------------------------------------

[[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 attributi/sfondo opzionali (vedi sotto)
** 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
** reset:
*** 'reset': ripristina colore ed attributi
*** 'resetcolor': ripristina colore (mantiene attributi)
    (_novità nella versione 0.3.6_)

Il formato del colore è: attributi (opzionale) + nome colore +",sfondo"
(opzionale). Gli attributi possibili sono:

* `*` : testo in grassetto
* `!` : video inverso
* `_` : testo sottolineato
* `|` : mantiene attributi: non ripristina grassetto/inverso/sottolineato
  al cambio di colore (_novità nella versione 0.3.6_)

Esempi:

* `yellow` : giallo
* `_green` : verde sottolineato
* `*214` : arancione grassetto
* `yellow,red` : giallo su rosso
* `|cyan` : ciano (e mantiene qualsiasi attributo impostato in precedenza)

Valore restituito:

* stringa con il codice colore, o una stringa vuota se non trovata

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

[NOTE]
La prima tabulazione nel messaggio ("\t") è usata per separare il prefisso dal messaggio. +
Se il proprio messaggio ha alcune tabulazioni e non si vuole il prefisso, allora
bisogna utilizzare uno spazio, una tabulazione, poi il messaggio (consultare
l'esempio successivo): ciò disabilita il prefisso (lo spazio prima della
tabulazione non verrà mostrato).

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL, "Benvenuto sul buffer di WeeChat");
weechat_printf (buffer, "Benvenuto su questo buffer");
weechat_printf (buffer, "%sQuesto è un errore!", weechat_prefix ("error"));
weechat_printf (buffer, " \tMessaggio senza prefisso ma con \t alcune \t tabulazioni");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
weechat.prnt(buffer, message)

# esempio
weechat.prnt("", "Benvenuto sul buffer di WeeChat")
weechat.prnt(buffer, "Benvenuto su questo buffer")
weechat.prnt(buffer, "%sQuesto è un errore!" % weechat.prefix("error"))
weechat.prnt(buffer, " \tMessaggio senza prefisso ma con \t alcune \t tabulazioni")
----------------------------------------

[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 (0 indica data/ora corrente)
* '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 (0 indica data/ora corrente)
* 'tags': lista di tag separati da virgole
* 'message': messaggio da visualizzare

Tag usati di frequente (elenco non esaustivo):

[width="70%",cols="1m,4",options="header"]
|========================================
| Tag              | Descrizione
| no_filter        | La riga non può essere filtrata
| no_highlight     | Evidenziazione non possibile sulla riga
| no_log           | La riga non viene scritta nel file di log
| log0 ... log9    | Livello di log per la riga (consultare `/help logger`)
| notify_none      | Il buffer con la riga non viene aggiunto alla hotlist
| notify_message   | Il buffer con la riga viene aggiunto alla hotlist con il livello "message"
| notify_private   | Il buffer con la riga viene aggiunto alla hotlist con il livello "private"
| notify_highlight | Il buffer con la riga viene aggiunto alla hotlist con il livello "higlight"
| nick_xxx         | Il messaggio viene dal nick "xxx"
| prefix_nick_ccc  | Il prefisso è un nick con il colore "ccc"
| irc_xxx          | Messaggio IRC "xxx" (può essere un comando o un numero di 3 cifre)
| irc_numeric      | Messaggio IRC numerico
| irc_error        | Errore dal server IRC
| irc_action       | Azione da un nic (comando `/me`)
| irc_ctcp         | Messaggio CTCP
| irc_ctcp_reply   | Risposta ad un messaggio CTCP
| irc_smart_filter | Messaggio IRC filtrabile tramite lo "smart filter" (filtro intelligente)
| away_info        | Messagio con informazioni sull'assenza
|========================================

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, completion, modifier, info, info_hashtable, infolist,
hdata, focus.

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 e
  valore restituito:
** '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)
** valore restituito:
*** 'WEECHAT_RC_OK'
*** 'WEECHAT_RC_ERROR'
* '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]' == "/command"
** 'argv[1]' == "abc"
** 'argv[2]' == "def"
** 'argv[3]' == "ghi"
* 'argv_eol':
** 'argv_eol[0]' == "/command abc def ghi"
** 'argv_eol[1]' == "abc def ghi"
** 'argv_eol[2]' == "def ghi"
** 'argv_eol[3]' == "ghi"

Per gli script, 'args' ha valore "abc def 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 e
  valore restituito:
** 'void *data': puntatore
** 'struct t_gui_buffer *buffer': buffer dove viene eseguito il comando
** 'const char *command': il comando eseguito, con i propri argomenti
** valore restituito:
*** 'WEECHAT_RC_OK'
*** 'WEECHAT_RC_OK_EAT'
*** 'WEECHAT_RC_ERROR'
* '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,
                                   int align_second,
                                   int 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, argomenti e valore
  restituito:
** 'void *data': pointer
** 'int remaining_calls': remaining calls (-1 if timer has no end)
** valore restituito:
*** 'WEECHAT_RC_OK'
*** 'WEECHAT_RC_ERROR'
* 'callback_data': pointer given to callback when it is called by WeeChat

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

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 e valore restituito:
** 'void *data': puntatore
** 'int fd': descrittore file
** valore restituito:
*** 'WEECHAT_RC_OK'
*** 'WEECHAT_RC_ERROR'
* '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 o URL
  (_novità nella versione 0.3.7_), segue:
* 'timeout': timeout per il comando (in millisecondi): dopo questo timeout,
  il processo figlio viene terminato (0 indica nessun timeout)
* 'callback': funzione chiamata quando i dati dal processo figlio sono disponibili,
  oppure quando è terminato, argomenti e valore restituito:
** 'void *data': puntatore
** 'const char *command': comando eseguito dal processo figlio
** 'int return_code': codice restituito:
*** '>= 0': codice ritorno figlio per un comando, e per un URL i valori
    possibili sono:
**** '0': trasferimento riuscito
**** '1': URL non valido
**** '2': errore di trasferimento
**** '3': memoria non sufficiente
**** '4': errore con un file
*** '< 0': 'WEECHAT_HOOK_PROCESS_RUNNING' (dati disponibili, ma figlio
    ancora in esecuzione) o 'WEECHAT_HOOK_PROCESS_ERROR' (errore nella
    esecuzione del comando)
** 'out': output standard del comando (stdout)
** 'err': output di errore del comando (stderr)
** valore restituito:
*** 'WEECHAT_RC_OK'
*** 'WEECHAT_RC_ERROR'
* 'callback_data': puntatore fornito alla callback quando chiamata da WeeChat

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Quando il comando ha terminato, o se viene raggiunto il timeout, WeeChat
effettua automaticamente l'unhook (e termina il processo se ancora in esecuzione).

Il comando può essere un URL con il formato: "url:http://www.esempio.com", per
scaricare il contenuto dell'URL (_novità nella versione 0.3.7_). Le opzioni per
un URL sono disponibili con la funzione
<<_weechat_hook_process_hashtable,weechat_hook_process_hashtable>>.

[NOTE]
La dimensione del buffer per l'invio dei dati alla callback è di 64KB (ci sono
2 buffer: uno per stdout ed uno per stderr).
Se l'output che viene da un processo figlio (stdout o stderr) è più lungo di
64KB, la callback verrà chiamata più di una volta.

[IMPORTANT]
Anche se la maggior parte delle volte la callback viene chiamata una sola volta,
ci si deve assicurare che più chiamate alla callback siano corrette nel codice:
bisogna concatenare i dati forniti da più chiamate ed utilizzarli quando il
codice restituito è non-negativo.

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_process_hashtable
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.7._

Hook su un processo (avviato con un fork) usando le opzioni nella tabella hash,
e cattura dell'output.

Prototipo:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_process_hashtable (const char *command,
                                               struct t_hashtable *options,
                                               int timeout,
                                               int (*callback)(void *data,
                                                               const char *command,
                                                               int return_code,
                                                               const char *out,
                                                               const char *err),
                                               void *callback_data);
----------------------------------------

Gli argomenti sono gli stessi della funzione
<<_weechat_hook_process,weechat_hook_process>>, con un argomento aggiuntivo:

* 'options': le opzioni per il comando eseguito (consultare la tabella in
  basso); la tabella hash è duplicata nella funzione, per cui è possibile
  liberarla dopo questa chiamata

Per il comando "url:..." sono disponibili le seguenti opzioni (consultare
`man curl_easy_setopt` per la descrizione di ogni opzione):

include::autogen/plugin_api/url_options.txt[]

[NOTE]
^(1)^ Quando sono disponibili le costanti, esse vanno usate come valore per
l'opzione. Per le opzioni con il tipo "mask" il formato è:
"value1+value2+value3".

Per un URL, sono consentite due opzioni aggiuntive (stringhe) per il file in
input/output:

* 'file_in': file da leggere e inviare con gli URL (invio del file "post")
* 'file_out': scrive URL scaricato/file in questo file (invece dello standard
* output)

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, "Error with command '%s'", command);
        return WEECHAT_RC_OK;
    }

    if (return_code >= 0)
    {
        weechat_printf (NULL, "return_code = %d", return_code);
    }

    if (out)
    {
        weechat_printf (NULL, "stdout: %s", out);
    }

    if (err)
    {
        weechat_printf (NULL, "stderr: %s", err);
    }

    return WEECHAT_RC_OK;
}

struct t_hashtable *options = weechat_hashtable_new (8,
                                                     WEECHAT_HASHTABLE_STRING,
                                                     WEECHAT_HASHTABLE_STRING,
                                                     NULL,
                                                     NULL);
if (hashtable)
{
    weechat_hashtable_set (options, "file_out", "/tmp/weechat.org.html");
    struct t_hook *my_process_hook = weechat_hook_process_hashtable ("url:http://www.weechat.org/",
                                                                     options,
                                                                     20000,
                                                                     &my_process_cb, NULL);
    weechat_hashtable_free (options);
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
hook = weechat.hook_process_hashtable(command, options, 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_hashtable("url:http://www.weechat.org/",
                                      { "file_out": "/tmp/weechat.org.html" },
                                      20000, "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 *gnutls_priorities,
                                     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)
* 'gnutls_priorities': priorità per gnutls (per la sintassi, consultare la
  documentazione della funzione 'gnutls_priority_init' nel manuale di gnutls), i
  valori di base sono:
** 'PERFORMANCE'
** 'NORMAL' (predefinito)
** 'SECURE128'
** 'SECURE256'
** 'EXPORT'
** 'NONE'
* 'local_hostname': nome host locale da utilizzare per la connessione
  (opzionale)
* 'callback': funzione chiamata quando la connessione è avvenuta con
  successo oppure no, argomenti e valore restituito:
** '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
*** 'WEECHAT_HOOK_CONNECT_TIMEOUT': timeout
** '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
** valore restituito:
*** 'WEECHAT_RC_OK'
*** 'WEECHAT_RC_ERROR'
* '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;
        case WEECHAT_HOOK_CONNECT_TIMEOUT:
            /* ... */
            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:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_TIMEOUT:
        # ...
    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 e
  valore restituito:
** '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
** valore restituito:
*** 'WEECHAT_RC_OK'
*** 'WEECHAT_RC_ERROR'
* '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)^ +
  (_novità nella versione 0.3.2_) |
  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)^ +
  (_novità nella versione 0.3.2_) |
  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_out1_yyy ^(1)^ +
  (_novità nella versione 0.3.7_) |
  string: messaggio |
  messaggio irc inviato al server (prima della divisione automatica da adattare in 512 byte)

| irc | xxx,irc_out_yyy ^(1)^ |
  string: messaggio |
  messaggio irc inviato al server (dopo la divisione automatica da adattare in 512 byte)

| irc | xxx,irc_outtags_yyy ^(1)^ +
  (_novità nella versione 0.3.4_) |
  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_opened +
  (_novità nella versione 0.3.7_) |
  puntatore: buffer |
  server del buffer aperto

| 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

| irc | irc_notify_join +
  (_novità nella versione 0.3.8_) |
  string: nome server + "," + nick |
  un nick nella lista notifiche è entrato sul server

| irc | irc_notify_quit +
  (_novità nella versione 0.3.8_) |
  string: nome server + "," + nick |
  un nick nella lista notifiche è uscito dal server

| irc | irc_notify_away +
  (_novità nella versione 0.3.8_) |
  string: nome server + "," + nick + "," + messaggio di assenza |
  un nick nella lista notifiche è ora assente sul server

| irc | irc_notify_still_away +
  (_novità nella versione 0.3.8_) |
  string: nome server + "," + nick + "," + messaggio di assenza |
  un nick nella lista notifiche è ancora assente sul server (messaggio di assenza cambiato)

| irc | irc_notify_back +
  (_novità nella versione 0.3.8_) |
  string: nome server + "," + nick |
  un nick nella lista notifiche è tornato (messaggio di assenza 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 | buffer_line_added +
  (_novità nella versione 0.3.7_) |
  puntatore: riga |
  riga aggiunta in un buffer

| weechat | day_changed +
  (_novità nella versione 0.3.2_) |
  string: nuova data, formato: "2010-01-31" |
  data di sistema modificata

| weechat | debug_dump |
  stringa: nome plugin |
  richiesta di dump

| weechat | filter_added |
  puntatore: filtro |
  filtro aggiunto

| weechat | filter_removing |
  puntatore: filtro |
  rimozione del filtro

| weechat | filter_removed |
  - |
  filtro rimosso

| weechat | filters_enabled |
  - |
  filtri abilitati

| weechat | filters_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 +
  (_novità nella versione 0.3.2_) |
  string: buffer pointer + "," + group name |
  group added in nicklist

| weechat | nicklist_group_removed +
  (_novità nella versione 0.3.2_) |
  string: buffer pointer + "," + group name |
  group removed from nicklist

| weechat | nicklist_nick_added +
  (_novità nella versione 0.3.2_) |
  string: buffer pointer + "," + nick name |
  nick added in nicklist

| weechat | nicklist_nick_removed +
  (_novità nella versione 0.3.2_) |
  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 | upgrade_ended +
  (_novità nella versione 0.3.4_) |
  - |
  fine del processo di aggiornamento (comando `/upgrade`)

| 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_switch +
  (_novità nella versione 0.3.7_) |
  puntatore: finestra |
  passaggio alla finestra

| weechat | window_unzoom |
  puntatore: finestra corrente |
  minimizzazione della finestra

| weechat | window_unzoomed |
  puntatore: finestra corrente |
  window unzoomed
  finestra minimizzata

| weechat | window_zoom |
  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 +
  (_novità nella versione 0.3.2_) |
  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 e valore
  restituito:
** '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
** valore restituito:
*** 'WEECHAT_RC_OK'
*** 'WEECHAT_RC_ERROR'
* '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)
----------------------------------------

[[signal_logger_backlog]]
Signal logger_backlog
+++++++++++++++++++++

Il segnale "logger_backlog" può essere inviato per visualizzare il backlog
(cronologia di chat) nel buffer (ad esempio se il proprio buffer viene aperto
in un plugin/script).

L'argomento è un puntatore al buffer.

Esempio in C:

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

[[signals_xxx_script_install]]
Signals xxx_script_install
++++++++++++++++++++++++++

Cinque segnali che possono essere inviati per installare uno script, a seconda
del linguaggio:

* 'perl_script_install'
* 'python_script_install'
* 'ruby_script_install'
* 'lua_script_install'
* 'tcl_script_install'

La callback compirà le seguenti azioni alla ricezione del segnale:

. scarica e rimuove lo script installato
. sposta il nuovo script nella cartella '~/.weechat/xxx/' (dove 'xxx' è il
  linguaggio)
. crea un link al nuovo script nella cartella '~/.weechat/xxx/autoload/'
. carica il nuovo script

Questi segnali vengono usati dallo script 'weeget.py' per installare gli
script.

L'argomento è una stringa con il percorso dello script da installare.

Esempio in C:

[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")
----------------------------------------

[[signals_xxx_script_remove]]
Signals xxx_script_remove
+++++++++++++++++++++++++

Cinque segnali che possono essere inviati per rimuovere un elenco di script, a
seconda del linguaggio:

* 'perl_script_remove'
* 'python_script_remove'
* 'ruby_script_remove'
* 'lua_script_remove'
* 'tcl_script_remove'

Per ogni script nella lista, la callback scaricherà e rimuoverà lo script.

Questi segnali vengono utilizzati dallo script 'weeget.py' per rimuovere gli
script.

L'argomento è una stringa con una lista separata da virgole di script da
rimuovere (script è il nome senza percorso, ad esempio 'script.py').

Esempio in C:

[source,C]
----------------------------------------
/* scarica e rimuove gli script test.py e script.py */
weechat_hook_signal_send ("python_script_remove", WEECHAT_HOOK_SIGNAL_STRING,
                          "test.py,script.py");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# scarica e rimuove gli script test.py e script.py
weechat.hook_signal_send("python_script_remove", WEECHAT_HOOK_SIGNAL_STRING,
                         "test.py,script.py")
----------------------------------------

[[signal_irc_input_send]]
Signal irc_input_send
+++++++++++++++++++++

_Novità nella versione 0.3.4._

Il segnale "irc_input_send" può essere inviato per simulare input in un buffer
irc (server, canale o privato).

L'argomento è una stringa con il seguente formato:

* nome interno del server (richiesto)
* punto e virgola
* nome canale (opzionale)
* punto e virgola
* flag usate per l'invio del messaggio (opzionale, la predefinita è 1):
** '1': coda con la priorità maggiore (come i messaggi utente)
** '2': coda con la priorità minore (come i messaggi inviati automaticamente
   da WeeChat)
* punto e virgola
* elenco separato da virgole di tag usate per l'invio di un messaggio
  (opzionale)
* punto e virgola
* testo o comando (richiesto)

Esempi in C:

[source,C]
----------------------------------------
/* dice "Hello!" sul server freenode, canale #weechat */
weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING,
                          "freenode;#weechat;1;;Hello!");

/* invia il comando "/whois FlashCode" sul server freenode, con priorità minore */
weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING,
                          "freenode;;2;;/whois FlashCode");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# dice "Hello!" sul server freenode server, canale #weechat
weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING,
                         "freenode;#weechat;1;;Hello!")

# invia il comando "/whois FlashCode" sul server freenode, con priorità minore
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 e valore
  restituito:
** 'void *data': puntatore
** 'const char *signal': segnale ricevuto
** 'struct t_hashtable *hashtable': tabella hash
** valore restituito:
*** 'WEECHAT_RC_OK'
*** 'WEECHAT_RC_ERROR'
* '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" })
----------------------------------------

[[hsignal_irc_redirect_command]]
Hsignal irc_redirect_command
++++++++++++++++++++++++++++

_Novità nella versione 0.3.4._

L'hsignal "irc_redirect_command" può essere inviato per redirigere l'output
di un comando irc ad una callback.

L'argomento è una tabella hash con le seguenti componenti (chiavi e valori
sono stringhe):

* 'server': nome interno del server (richiesto)
* 'pattern': schema di redirezione da usare (richiesto), sia uno di default
  (definito dal plugin irc), oppure definito dall'utente (consultare
  <<hsignal_irc_redirect_pattern>>), gli schemi predefiniti sono:
** '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': nome segnale (richiesto)
* 'count': numero di volte in  cui verrà utilizzata la redirezione (opzionale, predefinito è 1)
* 'string': stringa che deve essere presente nei messaggi irc ricevuti (opzionale, ma
  raccomandata, se una stringa può essere usata per identificare i messaggi)
* 'timeout': timeout per la redirezione, in secondi (opzionale, predefiniti sono)
* 'cmd_filter': elenco separato da virgole di comandi irc da filtrare (solo questi
  comandi verranno inviati alle callback, altri ignorati) (opzionale)

Subito dopo aver inviato questo hsignal, è necessario inviare il comando al
server irc, e la redirezione verrà usata per questo comando.

Quando è stata ricevuta la risposta completa dal proprio comando, verrà
inviato un hsignal. Questo hsignal ha il nome 'irc_redirection_xxx_yyy' dove
'xxx' è il segnale e 'yyy' lo 'schema' usato.

La tabella hash inviata in hsignal ha il seguente contenuto (chiavi e valori
sono stringhe):

* 'output': output del comando (i messaggi vengono separati da "\n")
* 'output_size': numero di byte in 'output' (come stringa)
* 'error': stringa di errore (in caso di errore):
** 'timeout': redirezione fermata dopo il timeout
* 'server': nome interno del server
* 'pattern': schema di redirezione
* 'signal': nome del segnale
* 'command': comando rediretto

Esempio in C:

[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_STRING,
                                                       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")
----------------------------------------

[[hsignal_irc_redirect_pattern]]
Hsignal irc_redirect_pattern
++++++++++++++++++++++++++++

_Novità nella versione 0.3.4._

L'hsignal "irc_redirect_pattern" può essere inviato per creare uno schema
per la redirezione irc (consultare <<hsignal_irc_redirect_command>>).

L'argomento è una tabella hash con le seguenti voci (chiavi e valori sono stringa):

* 'pattern': nome dello schema (richiesto)
* 'timeout': timeout predefinito per lo schema, in secondi (opzionale, predefinito è 60)
* 'cmd_start': elenco separato da virgole di comandi che avviano la redirezione (opzionale)
* 'cmd_stop': elenco separato da virgole di comandi che fermano la redirezione (richiesto)
* 'cmd_extra': elenco separato da virgole di comandi che possono essere ricevuti dopo aver
  fermato i comandi (opzionale)

Per ogni comando in 'cmd_start', 'cmd_stop' e 'cmd_extra', è possibile fornire
un intero con la posizione di "string" che va trovato nel messaggio ricevuto,
ad esempio:

----------------------------------------
352:1,354,401:1
----------------------------------------

Per i comandi 352 e 401, "string" deve essere trovata nel messaggio ricevuto,
come primo argomento.

[IMPORTANT]
Lo schema viene rimosso quando usato da una redirezione. Se uno schema si
rivelasse necessario per diverse redirezioni, è necessario crearne uno prima
di ogni redirezione.

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, "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 e valore restituito:
** 'void *data': puntatore
** 'const char *option': nome dell'opzione
** 'const char *value': nuovo valore per l'opzione
** valore restituito:
*** 'WEECHAT_RC_OK'
*** 'WEECHAT_RC_ERROR'
* '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 e valore
  restituito:
** '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>>)
** valore restituito:
*** 'WEECHAT_RC_OK'
*** 'WEECHAT_RC_ERROR'
* '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", "")
----------------------------------------

weechat_hook_completion_get_string
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versioe 0.3.4._

Ottiene il completamento di una proprietà come stringa.

Prototipo:

[source,C]
----------------------------------------
const char *weechat_hook_completion_get_string (struct t_gui_completion *completion,
                                                const char *property);
----------------------------------------

Argomenti:

* 'completion': puntatore al completamento
* 'property': nome della proprietà:
** 'base_command': comando usato per il completamento
** 'base_word': parola che viene completata
** 'args': argomenti del comando (inclusa la parola base)

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)
{
    /* ottiene l'argomento del comando */
    const char *args = weechat_hook_completion_get_string (completion, "args");

    /* completamento che dipende dagli argomenti */
    /* ... */

    return WEECHAT_RC_OK;
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.hook_completion_get_string(completion, property)

# esempio
def my_completion_cb(data, completion_item, buffer, completion):
    # ottiene l'argomento del comando
    args = weechat.hook_completion_get_string(completion, "args")
    # completamento che dipende dagli argomenti
    # ...
    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 (prima della codifica del set caratteri) |
  nuovo contenuto del messaggio

| irc | irc_in2_xxx ^(1)^ +
  (_novità nella versione 0.3.5_) |
  nome server |
  contenuto del messaggio ricevuto dal server IRC (dopo la codifica del set caratteri) |
  nuovo contenuto del messaggio

| irc | irc_out1_xxx ^(1)^ +
  (_novità nella versione 0.3.7_) |
  nome server |
  contenuto del messaggio che sta per essere inviato al server IRC (prima della divisione automatica da adattare in 512 byte) |
  nuovo contenuto del messaggio

| irc | irc_out_xxx ^(1)^ |
  nome server |
  contenuto del messaggio che sta per essere inviato al server IRC (dopo la divisione automatica da adattare in 512 byte) |
  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 +
  (_novità nella versione 0.3.2_) |
  stringa con puntatore al buffer ("0x123..") |
  contenuto della riga di comando da aggiungere nella cronologia comandi (buffer e globale |
  stringa aggiunta alla cronologia comandi

| weechat | input_text_content |
  stringa con puntatore al buffer ("0x123..") |
  contenuto della riga di comando |
  nuovo contenuto della riga di comando

| weechat | input_text_display |
  stringa con puntatore al buffer ("0x123..") |
  contenuto della riga di comando, senza tag al cursore |
  nuova stringa, solo da mostrare (la riga di comando non viene modificata)

| weechat | input_text_display_with_cursor |
  stringa con puntatore al buffer ("0x123..") |
  contenuto della riga di comando, con tag al cursore |
  nuova stringa, solo da mostrare (la riga di comando non viene modificata)

| weechat | input_text_for_buffer +
  (_novità nella versione 0.3.7_) |
  stringa con puntatore al buffer ("0x123..") |
  contenuto della riga di comando inviata al buffer (testo o comando) |
  nuovo contenuto della riga di comando inviata al buffer

| 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 e valore restituito:
** 'void *data': puntatore
** 'const char *modifier': nome del modificatore
** 'const char *modifier_data': dati per il modificatore
** 'const char *string': stringa da modificare
** valore restituito: nuova 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 in caso di errore

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 e valore
  restituito:
** 'void *data': puntatore
** 'const char *info_name': nome della info
** 'const char *arguments': argomenti addizionali, dipendono dalle info
** valore restituito: valore dell'info richiesta
* '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).

Prototipo:

[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 e valore
  restituito:
** 'void *data': puntatore
** 'const char *info_name': nome della info
** 'struct t_hashtable *hashtable': tabella hash, in base alla info
** valore restituito: tabella hash richiesta
* '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]
----------------------------------------
# prototipo
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,
                                      struct t_infolist *(*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 e
  valore restituito:
** '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
** valore restituito: lista info richiesta
* '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_hook_hdata
^^^^^^^^^^^^^^^^^^

Hook di un hdata: la callback restituisce il puntatore all'hdata richiesto.

Prototipo:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_hdata (const char *hdata_name,
                                   const char *description,
                                   struct t_hdata *(*callback)(void *data,
                                                               const char *hdata_name),
                                   void *callback_data);
----------------------------------------

Argomenti:

* 'hdata_name': nome dell'hdata
  (priorità consentita, consultare la nota a proposito di <<hook_priority,priority>>)
* 'description': descrizione
* 'callback': funzione chiamata alla richiesta di hdata, argomenti e valore restituito:
** 'void *data': puntatore
** 'const char *hdata_name': nome dell'hdata
** return value: hdata richiesto
* '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_hdata *
my_hdata_cb (void *data, const char *hdata_name)
{
    struct t_hdata *my_hdata;

    /* build hdata */
    /* ... */

    return my_hdata;
}

/* add hdata "my_hdata" */
struct t_hook *my_hdata = weechat_hook_hdata ("my_hdata",
                                              "Hdata for my structure",
                                              &my_hdata_cb, NULL);
----------------------------------------

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

weechat_hook_focus
^^^^^^^^^^^^^^^^^^

Hook sul foucus: evento del mouse o tasto premuto nella modalità cursore
(movimento libero del cursore).

Prototipo:

[source,C]
----------------------------------------
struct t_hook *weechat_hook_focus (const char *area,
                                   struct t_hashtable *(*callback)(void *data,
                                                                   struct t_hashtable *info),
                                   void *callback_data);
----------------------------------------

Argomenti:

* 'area': "chat" per la zona di chat, o il nome di un elemento barra
  (priorità consentita, consultare la nota a riguardo di <<hook_priority,priority>>)
* 'callback': funzione chiamata al momento del focus, argomenti e valore restituito:
** 'void *data': puntatore
** 'struct t_hashtable *info': tabella hash con informazioni sul focus e
   stringhe restituite da altre chiamate alle callback sul focus (con la
   priorità più alta) (consultare la tabella in basso)
** valore restituito: sia il puntatore "info" tabella hash completa), o il
   puntatore ad una nuova tabella hash (creata dalla callback, con chiavi e
   valori di tipo "string), questa nuovo contenuto della tabella hash verrà
   aggiunto ad 'info' per le altre chiamate alle callback del focus
* 'callback_data': puntatore fornito alla callback quando chiamata da WeeChat

[IMPORTANT]
Per l'azione di un mouse, la callback verrà chiamata due volte: la prima quando
il pulsante viene premuto (qui la zona corrisponde sempre alla propria area), la
seconda quando il pulsante viene rilasciato, e allora la zona potrà non
corrispondere con la propria: per cui bisogna *sempre* verificare nella propria
callback se l'area corrisponde prima di usare le informazioni nella tabella hash.

Contenuto della tabella hash inviata alla callback (tasti e valori sono di tipo
"string"):

[width="100%",cols="5m,5,8,3",options="header"]
|========================================
| Key ^(1)^                  | Descrizione                 | Valori di esempio                                | Valore se N/D
| _x                         | colonna sullo schermo     2+| "0" ... "n"
| _y                         | riga sullo schermo        2+| "0" ... "n"
| _key                       | evento tasto o mouse      2+| "button1", "button2-gesture-left", ...
| _window                    | puntatore alla finestra     | "0x12345678"                                     | ""
| _window_number             | numero della finestra       | "1" ... "n"                                      | "*"
| _buffer                    | puntatore al buffer         | "0x12345678"                                     | ""
| _buffer_number             | numero del buffer           | "1" ... "n"                                      | "-1"
| _buffer_plugin             | nome plugin del buffer      | "core", "irc", ...                               | ""
| _buffer_name               | nome del buffer             | "weechat", "freenode.#weechat", ...              | ""
| _buffer_full_name          | nome completo del buffer    | "core.weechat", "irc.freenode.#weechat", ...     | ""
| _buffer_localvar_XXX ^(2)^ | variabili locali del buffer | qualsiasi valore                                 | non impostato
| _chat                      | indicatore area di chat     | "0" o  "1"                                       | "0"
| _chat_line_x               | colonna nella riga ^(3)^    | "0" ... "n"                                      | "-1"
| _chat_line_y               | numero della riga ^(3)^     | "0" ... "n"                                      | "-1"
| _chat_line_date            | riga con data/ora           | "1313237175"                                     | "0"
| _chat_line_date_printed    | riga con data/ora ^(4)^     | "1313237175"                                     | "0"
| _chat_line_time            | ora visualizzata            | "14:06:15"                                       | ""
| _chat_line_tags            | tag della riga              | "irc_privmsg,notify_message,nick_FlashCode,log1" | ""
| _chat_line_nick            | nick della riga             | "FlashCode"                                      | ""
| _chat_line_prefix          | prefisso della riga         | "@FlashCode"                                     | ""
| _chat_line_message         | messaggio della riga        | "Hello world!"                                   | ""
| _chat_word                 | parola a (x,y)              | "Hello"                                          | ""
| _chat_bol                  | inizio della riga ⇒ (x-1,y) | "He"                                             | ""
| _chat_eol                  | (x,y) ⇒ fine della riga     | "llo world!"                                     | ""
| _bar_name                  | nome della barra            | "title", "nicklist", ...                         | ""
| _bar_filling               | riempimento della barra     | "horizontal", "vertical", ...                    | ""
| _bar_item_name             | nome dell'elemento barra    | "buffer_nicklist", "hotlist", ...                | ""
| _bar_item_line             | riga nell'elemento barra    | "0" ... "n"                                      | "-1"
| _bar_item_col              | colonna nell'elemento barra | "0" ... "n"                                      | "-1"
|========================================

[NOTE]
^(1)^ Ci sono alcune chiavi con il suffisso "2" (es: "_x2", "_y2", "_window2",
...) con informazioni sul secondo punto (utile solo per le azioni del mouse,
per sapere dove il pulsante del mouse è stato rilasciato). +
^(2)^ `XXX` è il nome della variabile locale nel buffer. +
^(3)^ È impostato solo per l buffer con contenuto libero. +
^(4)^ Data/ora in cui WeeChat aggiunge una riga nel buffer (maggiore o uguale a
"chat_line_date").

Informazioni aggiuntive per l'elemento barra "buffer_nicklist":

[width="70%",cols="3m,3,8",options="header"]
|========================================
| Chiave         | Plugin | Descrizione
| nick           | core   | nick
| prefix         | core   | prefisso per il nick
| group          | core   | nome gruppo
| irc_host       | irc    | host per il nick (se conosciuto)
|========================================

[NOTE]
^(1)^ Il nome del plugin che definisce un hook_focus per restituire
informazioni su questo elemento della barra (ad esempio se il plugin è "irc",
tale informazione sarà disponibile solo sui buffer irc).

Valore restituito:

* puntatore al nuovo hook, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
struct t_hashtable *
my_focus_nicklist_cb (void *data, struct t_hashtable *info)
{
    /* add strings in hashtable */
    /* ... */

    return info;
}

/* add focus on nicklist */
struct t_hook *my_focus = weechat_hook_focus ("buffer_nicklist",
                                              &my_focus_nicklist_cb, NULL);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
hook = weechat.hook_focus(area, callback, callback_data)

# esempio
def my_focus_nicklist_cb(data, info):
    # build dict
    # ...
    return my_dict

hook = weechat.hook_focus("buffer_nicklist", "my_focus_nicklist_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 e valore restituito:
** 'void *data': puntatore
** 'struct t_gui_buffer *buffer': puntatore al buffer
** 'const char *input_data': dati in input
** valore restituito:
*** 'WEECHAT_RC_OK'
*** 'WEECHAT_RC_ERROR'
* 'callback_data': puntatore fornito alla callback quando chiamata da WeeChat
* 'close_callback': funzione chiamata alla chiusura del buffer, argomenti e
  valore restituito:
** 'void *data': puntatore
** 'struct t_gui_buffer *buffer': puntatore al buffer
** valore restituito:
*** 'WEECHAT_RC_OK'
*** 'WEECHAT_RC_ERROR'
* '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
** 'layout_number_merge_order': ordine di unione per i layout
** 'short_name_is_set': 1 se il nome breve è impostato, 0 in caso contrario
** '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 sensibili alle maiuscole,
   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
** 'full_name': nome completo del buffer ("plugin.nome") (_novità nella versione 0.3.7_)
** 'short_name': nome breve del buffer (nota: usato solo per il display e può
   essere cambiato dall'utente, questo nome non va usato per trovare il nome del
   buffer, utilizzare invece 'name', 'fullname' o la variabile locale 'channel')
** '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_regex': espressione regolare per l'evento
** 'highlight_tags': elenco di tag da evidenziare
** 'hotlist_max_level_nicks': livello massimo della hotlist per alcuni nick
** '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)
** 'highlight_regex_compiled': espressione regolare 'highlight_regex' compilata

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: %s" % 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 non sensibile alle maiuscole, "1" per
  una lista nick sensibile alle maiuscole

| 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_regex | qualsiasi stringa |
  espressione regolare per l'evento

| highlight_tags | elenco separato da virgole di tag |
  elenco separato da virgole di tag da evidenziare in questo buffer

| hotlist_max_level_nicks | elenco separado da virgole di "nick:livello" |
  elenco separato da virgole di nick con il livello massimo per la hotlist
  su questo buffer (il livello può essere: -1: mai nella hotlist, 0: basso,
  1: messaggio, 2: privato, 3: evento), ad esempio: "joe:2,mike:-1,robert:-1"
  (joe non produce eventi sul buffer, mike e robert non modificano la hotlist)

| hotlist_max_level_nicks_add | elenco separato da virgole di "nick:livello" |
  elenco separato da virgole di nick con il livello per la hotlist, questi
  nick vengono aggiunti a quelli esistenti nel buffer

| hotlist_max_level_nicks_del | elenco separato da virgole di nick |
  elenco separato da virgole di nick da rimuovere dai livelli massimi della
  hotlist

| 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.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", "")
----------------------------------------

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"
----------------------------------------

weechat_buffer_match_list
^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.5._

Verifica se il buffer corrisponde ad una lista di buffer.

Prototipo:

[source,C]
----------------------------------------
int weechat_buffer_match_list (struct t_gui_buffer *buffer, const char *string);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'string': elenco separato da virgole di buffer:
** "*" indica tutti i buffer
** il nome preceduto da "!" viene escluso
** il nome può iniziare o terminare con "*" per corrispondere a più buffer

Valore restituito:

* 1 se il buffer coincide con la lista, altrimenti 0

Esempio in C:

[source,C]
----------------------------------------
struct t_gui_buffer *buffer = weechat_buffer_search ("irc", "freenode.#weechat");
if (buffer)
{
    weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "*"));                   /* 1 */
    weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "*,!*#weechat*"));       /* 0 */
    weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "irc.freenode.*"));      /* 1 */
    weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "irc.oftc.*,python.*")); /* 0 */
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
match = weechat.buffer_match_list(buffer, string)

# esempio
buffer = weechat.buffer_search("irc", "freenode.#weechat")
if buffer:
    weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "*"))                   # 1
    weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "*,!*#weechat*"))       # 0
    weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "irc.freenode.*"))      # 1
    weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "irc.oftc.*,python.*")) # 0
----------------------------------------

[[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_search_with_buffer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.5._

Restituisce il puntatore alla finestra che mostra il buffer.

Prototipo:

[source,C]
----------------------------------------
struct t_gui_window *weechat_window_search_with_buffer (struct t_gui_buffer *buffer);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer

Valore restituito:

* puntatore alla finestra che mostra il buffer (NULL se nessuna finestra sta
  mostrando il buffer)

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL,
                "window displaying core buffer: %lx",
                weechat_window_search_with_buffer (weechat_buffer_search_main ()));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
window = weechat.window_search_with_buffer(buffer)

# esempio
weechat.prnt("", "window displaying core buffer: %s"
    % weechat.window_search_with_buffer(weechat.buffer_search_main()))
----------------------------------------

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à:
** 'number': numero della finestra (inizia da 1)
** '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 indica metà grandezza)
** 'win_height_pct': misura percentuale, paragonata alla finestra genitore
   (ad esempio 50 indica 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
** 'scrolling': 1 se lo scorrimento è attivo sulla finestra (ultima riga non
   visualizzata)
** '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: %s"
    % 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
* '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
* 'visible':
** '1': gruppi e sottogruppi/nick sono visibili
** '0': gruppi e sottogruppi/nick sono nascosti

[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_get_next_item
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.7._

Ottiene il prossimo gruppo oppure il nick dalla lista nick (usato principalmente
per mostrare la lista nick).

Prototipo:

[source,C]
----------------------------------------
void gui_nicklist_get_next_item (struct t_gui_buffer *buffer,
                                 struct t_gui_nick_group **group,
                                 struct t_gui_nick **nick);
----------------------------------------

Argomenti:

* 'buffer': puntatore al buffer
* 'group': puntatore sul puntatore al gruppo
* 'nick': puntatore sul puntatore al nick

Esempio in C:

[source,C]
----------------------------------------
struct t_gui_nick_group *ptr_group;
struct t_gui_nick *ptr_nick;

ptr_group = NULL;
ptr_nick = NULL;
gui_nicklist_get_next_item (buffer, &ptr_group, &ptr_nick);
while (ptr_group || ptr_nick)
{
    if (ptr_nick)
    {
        /* nick */
        /* ... */
    }
    else
    {
        /* gruppo */
        /* ... */
    }
    gui_nicklist_get_next_item (buffer, &ptr_group, &ptr_nick);
}
----------------------------------------

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

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
|========================================

Esempio in C:

[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, argomenti e valore restituito:
** 'void *data': puntatore
** 'struct t_gui_bar_item *item': puntatore all'elemento barra
** 'struct t_gui_window *window': puntatore alla finestra
** valore restituito: 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);
----------------------------------------

Argomenti:

* '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_message_parse",
                                                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]
----------------------------------------
# prototipo
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_message_parse", 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.

[IMPORTANT]
Il contenuto della lista info è un duplicato dei dati attuali. Se si sta
richiedendo una lista info con molti dati (come "buffer_lines"), WeeChat
allocherà memoria per duplicare tutti i dati, e potrebbe essere necessario un
po' di tempo. +
Invece di usare liste info più grandi, è preferibilie usare hdata (ma le liste
info potrebbero avere più info di hdata, che sono dati raw), consultare <<hdata,hdata>>.

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%s" % 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)
----------------------------------------

[[hdata]]
Hdata
~~~~~

Funzioni per hdata (accesso raw a WeeChat o ai dati dei plugin).

[IMPORTANT]
Hdata fornisce un accesso in sola lettura ai dati. È *SEVERAMENTE VIETATO*
scrivere qualcosa in memoria puntato dalle variabili in hdata.

weechat_hdata_new
^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.6._

Crea un nuovo hdata.

[NOTE]
.hdata vs infolist
========================================
Hdata è un metodo veloce per leggere i dati di WeeChat o dei plugin. È simile
alle liste info, ma ci sono alcune differenze:

* è più veloce ed usa meno memoria: lettura diretta dei dati senza duplicazione
* può contenere informazioni differenti rispetto alle liste info: esso contiene
  solo dati raw in strutture (le liste info possono aggiungere alcuni dati extra
  per convenienza)

========================================

Prototipo:

[source,C]
----------------------------------------
struct t_hdata *weechat_hdata_new (const char *hdata_name, const char *var_prev, const char *var_next);
----------------------------------------

Argomenti:

* 'hdata_name': nome di un hdata
* 'var_prev': nome della variabile nella struttura che è puntatore all'elemento
  precedente nella lista (può essere NULL se non è disponibile tale variabile)
* 'var_next': nome della variabile nella struttura che è puntatore all'elemento
  successivo nella lista (può essere NULL se non è disponibile tale variabile)

Valore restituito:

* puntatore al nuovo hdata

Esempio in C:

[source,C]
----------------------------------------
struct t_hdata *hdata = weechat_hdata_new ("myplugin_list", "prev", "next");
----------------------------------------

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

weechat_hdata_new_var
^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.6._

Crea una nuova variabile in hdata.

Prototipo:

[source,C]
----------------------------------------
void weechat_hdata_new_var (struct t_hdata *hdata, const char *name, int offset, int type,
                            const char *hdata_name);
----------------------------------------

Argomenti:

* 'hdata': puntatore ad hdata
* 'name': nome della variabile
* 'offset': offset della variabile nella struttura
* 'type': tipo variabile, una di:
** WEECHAT_HDATA_CHAR
** WEECHAT_HDATA_INTEGER
** WEECHAT_HDATA_LONG
** WEECHAT_HDATA_STRING
** WEECHAT_HDATA_POINTER
** WEECHAT_HDATA_TIME
** WEECHAT_HDATA_OTHER
* 'hdata_name': nome di un hdata (se è un puntatore ad una struttura con dati)

Esempio in C:

[source,C]
----------------------------------------
struct t_myplugin_list
{
    char *name;
    struct t_gui_buffer *buffer;
    int count;
    struct t_myplugin_list *prev;
    struct t_myplugin_list *next;
};

/* ... */

struct t_hdata *hdata = weechat_hdata_new ("myplugin_list", "prev", "next");
weechat_hdata_new_var (hdata, "name", offsetof (struct t_myplugin_list, name), WEECHAT_HDATA_STRING, NULL);
weechat_hdata_new_var (hdata, "buffer", offsetof (struct t_myplugin_list, buffer), WEECHAT_HDATA_POINTER, NULL);
weechat_hdata_new_var (hdata, "count", offsetof (struct t_myplugin_list, count), WEECHAT_HDATA_INTEGER, NULL);
weechat_hdata_new_var (hdata, "prev", offsetof (struct t_myplugin_list, prev), WEECHAT_HDATA_POINTER, "myplugin_list");
weechat_hdata_new_var (hdata, "next", offsetof (struct t_myplugin_list, next), WEECHAT_HDATA_POINTER, "myplugin_list");
----------------------------------------

La macro "WEECHAT_HDATA_VAR" può essere usata per accorciare il codice:

[source,C]
----------------------------------------
WEECHAT_HDATA_VAR(struct t_myplugin_list, name, STRING, NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, buffer, POINTER, NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, count, INTEGER, NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, prev, POINTER, "myplugin_list");
WEECHAT_HDATA_VAR(struct t_myplugin_list, next, POINTER, "myplugin_list");
----------------------------------------

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

weechat_hdata_new_list
^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.6._

Crea una nuovo puntatore alla lista in hdata.

Prototipo:

[source,C]
----------------------------------------
void weechat_hdata_new_list (struct t_hdata *hdata, const char *name, void *pointer);
----------------------------------------

Argomenti:

* 'hdata': puntatore hdata
* 'name': nome delal variabile
* 'pointer': puntatore alla lista

Esempio in C:

[source,C]
----------------------------------------
struct t_myplugin_list
{
    char *name;
    struct t_gui_buffer *buffer;
    int count;
        struct t_myplugin_list *prev;
    struct t_myplugin_list *next;
};

struct t_myplugin_list *buffers = NULL;
struct t_myplugin_list *last_buffer = NULL;

/* ... */

struct t_hdata *hdata = weechat_hdata_new ("myplugin_list", "prev", "next");
weechat_hdata_new_var (hdata, "name", offsetof (struct t_myplugin_list, name), WEECHAT_HDATA_STRING, NULL);
weechat_hdata_new_var (hdata, "buffer", offsetof (struct t_myplugin_list, buffer), WEECHAT_HDATA_POINTER, NULL);
weechat_hdata_new_var (hdata, "count", offsetof (struct t_myplugin_list, count), WEECHAT_HDATA_INTEGER, NULL);
weechat_hdata_new_var (hdata, "prev", offsetof (struct t_myplugin_list, prev), WEECHAT_HDATA_POINTER, "myplugin_list");
weechat_hdata_new_var (hdata, "next", offsetof (struct t_myplugin_list, next), WEECHAT_HDATA_POINTER, "myplugin_list");
weechat_hdata_new_list (hdata, "buffers", &buffers);
weechat_hdata_new_list (hdata, "last_buffer", &last_buffer);
----------------------------------------

La macro "WEECHAT_HDATA_LIST" può essere usata per accorciare il codice:

[source,C]
----------------------------------------
WEECHAT_HDATA_LIST(buffers);
WEECHAT_HDATA_LIST(last_buffer);
----------------------------------------

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

weechat_hdata_get
^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.6._

Restituisce hdata per una struttura di WeeChat o di un plugin.

[NOTE]
Hdata non contiene dati, è una tabella hash con la posizione delle variabili
nella struttura. Ciò indica che è necessario questo hdata ed un puntatore ad
un oggetto di WeeChat/plugin per leggere dei dati.

Prototipo:

[source,C]
----------------------------------------
struct t_hdata *weechat_hdata_get (const char *hdata_name);
----------------------------------------

Argomenti:

* 'hdata_name': nome di un hdata:
include::autogen/plugin_api/hdata.txt[]

Valore restituito:

* puntatore ad un hdata, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
struct t_hdata *hdata = weechat_hdata_get ("irc_server");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
hdata = weechat.hdata_get(hdata_name)

# esempio
hdata = weechat.hdata_get("irc_server")
----------------------------------------

weechat_hdata_get_var_offset
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.6._

Return offset of variable in hdata.
Restituisce l'offset della variabile in hdata.

Prototipo:

[source,C]
----------------------------------------
int weechat_hdata_get_var_offset (struct t_hdata *hdata, const char *name);
----------------------------------------

Argomenti:

* 'hdata': puntatore hdata
* 'name': nome della variabile

Valore restituito:

* offset della variabile, 0 in caso di errore

Esempio in C:

[source,C]
----------------------------------------
int offset = weechat_hdata_get_var_offset (hdata, "name");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
offset = weechat.hdata_get_var_offset(hdata, name)

# esempio
offset = weechat.hdata_get(hdata, "name")
----------------------------------------

weechat_hdata_get_var_type
^^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.6._

Restituisce il tipo di variabile in hdata (come intero).

Prototipo:

[source,C]
----------------------------------------
int weechat_hdata_get_var_type (struct t_hdata *hdata, const char *name);
----------------------------------------

Argomenti:

* 'hdata': puntatore hdata
* 'name': nome della variabile

Valore restituito:

* tipo della variabile, -1 in caso di errore

Esempio in C:

[source,C]
----------------------------------------
int type = weechat_hdata_get_var_type (hdata, "name");
switch (type)
{
    case WEECHAT_HDATA_CHAR:
        /* ... */
        break;
    case WEECHAT_HDATA_INTEGER:
        /* ... */
        break;
    case WEECHAT_HDATA_LONG:
        /* ... */
        break;
    case WEECHAT_HDATA_STRING:
        /* ... */
        break;
    case WEECHAT_HDATA_POINTER:
        /* ... */
        break;
    case WEECHAT_HDATA_TIME:
        /* ... */
        break;
    case WEECHAT_HDATA_OTHER:
        /* ... */
        break;
    default:
        /* variable not found */
        break;
}
----------------------------------------

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

weechat_hdata_get_var_type_string
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.6._

Restituisce il tipo di variabile in hdata (come stringa).

Prototipo:

[source,C]
----------------------------------------
const char *weechat_hdata_get_var_type_string (struct t_hdata *hdata, const char *name);
----------------------------------------

Argomenti:

* 'hdata': puntatore hdata
* 'name': nome della variabile

Valore restituito:

* tipo della variabile, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL, "type = %s",
                weechat_hdata_get_var_type_string (hdata, "name"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
type = weechat.hdata_get_var_type_string(hdata, name)

# esempio
weechat.prnt("", "type = %s" % weechat.hdata_get_var_type_string(hdata, "name"))
----------------------------------------

weechat_hdata_get_var_hdata
^^^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.6._

Restituisce hdata per la variabile in hdata.

Prototipo:

[source,C]
----------------------------------------
const char *weechat_hdata_get_var_hdata (struct t_hdata *hdata, const char *name);
----------------------------------------

Argomenti:

* 'hdata': puntatore hdata
* 'name': nome della variabile

Valore restituito:

* hdata per la variabile, NULL in caso di nessun hdata presente o di errore

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL, "hdata = %s", weechat_hdata_get_var_hdata (hdata, "name"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
hdata_name = weechat.hdata_get_var_hdata(hdata, name)

# esempio
weechat.prnt("", "hdata = %s" % weechat.hdata_get_var_hdata(hdata, "name"))
----------------------------------------

weechat_hdata_get_var
^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.6._

Restituisce il puntatore al contenuto della variabile in hdata.

Prototipo:

[source,C]
----------------------------------------
void *weechat_hdata_get_var (struct t_hdata *hdata, void *pointer, const char *name);
----------------------------------------

Argomenti:

* 'hdata': puntatore hdata
* 'pointer': puntarore all'oggetto di WeeChat/plugin
* 'name': nome della variabile

Valore restituito:

* puntatore al contenuto della variabile, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
void *pointer = weechat_hdata_get_var (hdata, buffer, "name");
----------------------------------------

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

weechat_hdata_get_var_at_offset
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.6._

Restituisce il puntatore al contenuto della variabile in hdata, usando un offset.

Prototipo:

[source,C]
----------------------------------------
void *weechat_hdata_get_var_at_offset (struct t_hdata *hdata, void *pointer, int offset);
----------------------------------------

Argomenti:

* 'hdata': puntatore hdata
* 'pointer': puntatore ad un oggetto di WeeChat/plugin
* 'offset': offset della variabile

Valore restituito:

* puntatore al contenuto della variabile, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
int offset = weechat_hdata_get_var_offset (hdata, "name");
void *pointer = weechat_hdata_get_var_at_offset (hdata, buffer, offset);
----------------------------------------

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

weechat_hdata_get_list
^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.6._

Restituisce il puntatore alla lista da hdata.

Prototipo:

[source,C]
----------------------------------------
void *weechat_hdata_get_list (struct t_hdata *hdata, const char *name);
----------------------------------------

Argomenti:

* 'hdata': puntatore hdata
* 'name': nome della lista

Valore restituito:

* puntatore alla lista, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffers = weechat_hdata_get_list (hdata, "gui_buffers");
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
list = weechat.hdata_get_list(hdata, name)

# esempio
hdata = weechat.hdata_get("buffer")
buffers = weechat.hdata_get_list(hdata, "gui_buffers")
----------------------------------------

weechat_hdata_check_pointer
^^^^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.7._

Verifica se un puntatore è valido per un hdata e un puntatore della lista.

Prototipo:

[source,C]
----------------------------------------
int weechat_hdata_check_pointer (struct t_hdata *hdata, void *list, void *pointer);
----------------------------------------

Argomenti:

* 'hdata': puntatore hdata
* 'list': puntatore alla lista
* 'pointer': puntatore da verificare

Valore restituito:

* 1 se il puntatore è in lista, 0 in caso contrario

Esempio in C:

[source,C]
----------------------------------------
/* check if a buffer pointer is valid */
struct t_hdata *hdata = weechat_hdata_get ("buffer");
if (weechat_hdata_check_pointer (hdata,
                                 weechat_hdata_get_list (hdata, "gui_buffers"),
                                 ptr_buffer))
{
    /* valid pointer */
}
else
{
    /* invalid pointer */
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
rc = weechat.hdata_check_pointer(hdata, list, pointer)

# esempio
hdata = weechat.hdata_get("buffer")
if weechat.hdata_check_pointer(hdata, weechat.hdata_get_list(hdata, "gui_buffers"), ptr_buffer):
    # valid pointer
    # ...
else:
    # invalid pointer
    # ...
----------------------------------------

weechat_hdata_move
^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.6._

Sposta il puntatore ad un altro elemento nella lista.

Prototipo:

[source,C]
----------------------------------------
void *weechat_hdata_move (struct t_hdata *hdata, void *pointer, int count);
----------------------------------------

Argomenti:

* 'hdata': puntatore hdata
* 'pointer': puntatore ad un oggetto di WeeChat/plugin
* 'count': numero di salto(i) da eseguire (intero positivo o negativo, diverso
  da 0)

Valore restituito:

* puntatore all'elemento raggiunto, NULL in caso di errore

Esempio in C:

[source,C]
----------------------------------------
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();

/* passa al buffer successivo, 2 volte */
buffer = weechat_hdata_move (hdata, buffer, 2);

/* passa al buffer precedente */
if (buffer)
    buffer = weechat_hdata_move (hdata, buffer, -1);
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
pointer = weechat.hdata_move(hdata, pointer, count)

# esempio
hdata = weechat.hdata_get("buffer")
buffer = weechat.buffer_search_main()

# passa al buffer successivo, 2 volte
buffer = weechat.hdata_move(hdata, buffer, 2)

# passa al buffer precedente
if buffer:
    buffer = weechat.hdata_move(hdata, buffer, -1)
----------------------------------------

weechat_hdata_char
^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.7._

Restituisce il valore di una variabile char in una struttura dati usando hdata.

Prototipo:

[source,C]
----------------------------------------
char weechat_hdata_char (struct t_hdata *hdata, void *pointer, const char *name);
----------------------------------------

Argomenti:

* 'hdata': puntatore hdata
* 'pointer': puntatore all'oggetto di WeeChat/plugin
* 'name': nome della variabile (deve essere di tipo "char")

Valore restituito:

* valore char della variabile

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL, "letter = %c", weechat_hdata_char (hdata, pointer, "letter"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.hdata_char(hdata, pointer, name)

# esempio
weechat.prnt("", "letter = %c" % weechat.hdata_char(hdata, pointer, "letter"))
----------------------------------------

weechat_hdata_integer
^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.6._

Restituisce il valore di una variabile integer in una struttura dati usando hdata.

Prototipo:

[source,C]
----------------------------------------
int weechat_hdata_integer (struct t_hdata *hdata, void *pointer, const char *name);
----------------------------------------

Argomenti:

* 'hdata': puntatore hdata
* 'pointer': puntatore all'oggetto di WeeChat/plugin
* 'name': nome della variabile (deve essere di tipo "integer")

Valore restituito:

* valore intero della variabile

Esempio in C:

[source,C]
----------------------------------------
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
weechat_printf (NULL, "number = %d", weechat_hdata_integer (hdata, buffer, "number"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.hdata_integer(hdata, pointer, name)

# esempio
hdata = weechat.hdata_get("buffer")
buffer = weechat.buffer_search_main()
weechat.prnt("", "number = %d" % weechat.hdata_integer(hdata, buffer, "number"))
----------------------------------------

weechat_hdata_long
^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.6._

Restituisce il valore della variabile long della struttura usando hdata.

Prototipo:

[source,C]
----------------------------------------
long weechat_hdata_long (struct t_hdata *hdata, void *pointer, const char *name);
----------------------------------------

Argomenti:

* 'hdata': puntatore hdata
* 'pointer': puntatore all'oggetto di WeeChat/plugin
* 'name': nome della variabile (deve essere di tipo "long")

Valore restituito:

* valore long della variabile

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL, "longvar = %ld", weechat_hdata_long (hdata, pointer, "longvar"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.hdata_long(hdata, pointer, name)

# esempio
weechat.prnt("", "longvar = %ld" % weechat.hdata_long(hdata, pointer, "longvar"))
----------------------------------------

weechat_hdata_string
^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.6._

Restituisce il valore della variabile string nella struttura usando hdata.

Prototipo:

[source,C]
----------------------------------------
const char *weechat_hdata_string (struct t_hdata *hdata, void *pointer, const char *name);
----------------------------------------

Argomenti:

* 'hdata': puntatore hdata
* 'pointer': puntatore all'oggetto di WeeChat/plugin
* 'name': nome della variabile (deve essere di tipo "string")

Valore restituito:

* valore stringa della variabile

Esempio in C:

[source,C]
----------------------------------------
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
weechat_printf (NULL, "name = %s", weechat_hdata_string (hdata, buffer, "name"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.hdata_string(hdata, pointer, name)

# esempio
hdata = weechat.hdata_get("buffer")
buffer = weechat.buffer_search_main()
weechat.prnt("", "name = %s" % weechat.hdata_string(hdata, buffer, "name"))
----------------------------------------

weechat_hdata_pointer
^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.6._

Restituisce il valore della variabile puntatore nella struttura usando hdata.

Prototipo:

[source,C]
----------------------------------------
void *weechat_hdata_pointer (struct t_hdata *hdata, void *pointer, const char *name);
----------------------------------------

Argomenti:

* 'hdata': hdata hdata
* 'pointer': pointer all'oggetto di WeeChat/plugin
* 'name': nome della variabile (deve essere di tipo "pointer")

Valore restituito:

* valore puntatore della variabile

Esempio in C:

[source,C]
----------------------------------------
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
weechat_printf (NULL, "lines = %lx", weechat_hdata_pointer (hdata, buffer, "lines"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.hdata_pointer(hdata, pointer, name)

# esempio
hdata = weechat.hdata_get("buffer")
buffer = weechat.buffer_search_main()
weechat.prnt("", "lines = %lx" % weechat.hdata_pointer(hdata, buffer, "lines"))
----------------------------------------

weechat_hdata_time
^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.6._

Restituisce il valore della variabile time nella struttura usando hdata.

Prototipo:

[source,C]
----------------------------------------
time_t weechat_hdata_time (struct t_hdata *hdata, void *pointer, const char *name);
----------------------------------------

Argomenti:

* 'hdata': puntatore hdata
* 'pointer': puntatore all'oggetto di WeeChat/plugin
* 'name': nome della variabile (deve essere di tipo "time")

Valore restituito:

* valore time della variabile

Esempio in C:

[source,C]
----------------------------------------
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *ptr = weechat_buffer_search_main ();
ptr = weechat_hdata_pointer (hdata, ptr, "lines");
if (ptr)
{
    hdata = weechat_hdata_get ("lines");
    ptr = weechat_hdata_pointer (hdata, ptr, "first_line");
    if (ptr)
    {
        hdata = weechat_hdata_get ("line");
        ptr = weechat_hdata_pointer (hdata, ptr, "data");
        if (ptr)
        {
            hdata = weechat_hdata_get ("line_data");
            time_t date = weechat_hdata_time (hdata, hdata, "date");
            weechat_printf (NULL, "time of last line displayed = %s", ctime (&date));
        }
    }
}
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.hdata_time(hdata, pointer, name)

# esempio
hdata = weechat.hdata_get("buffer")
ptr = weechat.buffer_search_main()
ptr = weechat.hdata_pointer(hdata, ptr, "lines")
if ptr:
    hdata = weechat.hdata_get("lines")
    ptr = weechat.hdata_pointer(hdata, ptr, "first_line")
    if ptr:
        hdata = weechat.hdata_get("line")
        ptr = weechat.hdata_pointer(hdata, ptr, "data")
        if ptr:
            hdata = weechat.hdata_get("line_data")
            weechat.prnt("", "time of last line displayed = %s" % weechat.hdata_time(hdata, ptr, "date"))
----------------------------------------

weechat_hdata_hashtable
^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.7._

Restituisce il valore di una variabile nella tabella hash nella struttura usando
hdata.

Prototipo:

[source,C]
----------------------------------------
struct t_hashtable *weechat_hdata_hashtable (struct t_hdata *hdata, void *pointer, const char *name);
----------------------------------------

Argomenti:

* 'hdata': puntatore hdata
* 'pointer': puntatore all'oggetto di WeeChat/plugin
* 'name': nome della variabile (deve essere di tipo "hashtable")

Valore restituito:

* valore della tabella hash della variabile (puntatore alla tabella hash)

Esempio in C:

[source,C]
----------------------------------------
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
struct t_hashtable *hashtable = weechat_hdata_hashtable (hdata, buffer, "local_variables");
weechat_printf (NULL, "%d local variables in core buffer",
                weechat_hashtable_get_integer (hashtable, "items_count"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
hashtable = weechat.hdata_hashtable(hdata, pointer, name)

# esempio
hdata = weechat.hdata_get("buffer")
buffer = weechat.buffer_search_main()
hash = weechat.hdata_hashtable(hdata, buffer, "local_variables")
weechat.prnt("", "local variables in core buffer:")
for key in hash:
    weechat.prnt("", "  %s == %s" % (key, hash[key]))
----------------------------------------

weechat_hdata_get_string
^^^^^^^^^^^^^^^^^^^^^^^^

_Novità nella versione 0.3.6._

Restituisce il valore stringa di una proprietà di hdata.

Prototipo:

[source,C]
----------------------------------------
const char *weechat_hdata_get_string (struct t_hdata *hdata, const char *property);
----------------------------------------

Argomenti:

* 'hdata': puntatore hdata
* 'property': nome della proprietà:
** 'var_keys': stringa con la lista di chiavi per le variabili in hdata
   (formato: "key1,key2,key3")
** 'var_values': stringa con la lista di valori per le variabili in hdata
   (formato: "value1,value2,value3")
** 'var_keys_values': stringa cona la lista di chiavi e valori per le variabili in hdata
   (formato: "key1:value1,key2:value2,key3:value3")
** 'var_prev': nome della variabile nella struttura che fa da puntatore al
   precedente elemento nella lista
** 'var_next': nome della variabile nella struttura che fa da puntatore al
   successivo elemento nella lista
** 'list_keys': stringa con la lista di chiavi per le liste in hdata
   (formato: "key1,key2,key3")
** 'list_values': stringa con la lista di valori per le liste in hdata
   (formato: "value1,value2,value3")
** 'list_keys_values': stringa con la lista di chiavi e valori per le liste in hdata
   (formato: "key1:value1,key2:value2,key3:value3")

Valore restituito:

* valore stringa della proprietà

Esempio in C:

[source,C]
----------------------------------------
weechat_printf (NULL, "variables in hdata: %s" weechat_hdata_get_string (hdata, "var_keys"));
weechat_printf (NULL, "lists in hdata: %s" weechat_hdata_get_string (hdata, "list_keys"));
----------------------------------------

Script (Python):

[source,python]
----------------------------------------
# prototipo
value = weechat.hdata_get_string(hdata, property)

# esempio
weechat.prnt("", "variables in hdata: %s" % weechat.hdata_get_string(hdata, "var_keys"))
weechat.prnt("", "lists in hdata: %s" % weechat.hdata_get_string(hdata, "list_keys"))
----------------------------------------

[[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, argomenti e valore restituito:
** 'void *data': puntatore
** 'struct t_upgrade_file *upgrade_file': puntatore al file di aggiornamento
** 'int object_id': id dell'oggetto
** 'struct t_infolist *infolist': lista info con il contenuto dell'oggetto
** valore restituito:
*** 'WEECHAT_RC_OK'
*** 'WEECHAT_RC_ERROR'
* 'callback_read_data': puntatore assegnato per la lettura della chiamata
  quando chiamata 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)
----------------------------------------
