pegasus/weechat
1
0
Fork 0
mirror of https://github.com/weechat/weechat.git synced 2026-06-25 20:36:38 +02:00
Code Activity

doc: fix styles in relay protocol (issue #722)

Browse Source
This commit is contained in:
Sébastien Helleu
2016-05-04 22:19:37 +02:00
parent c5c7539406
commit baebbb25a3
3 changed files with 453 additions and 454 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/en/weechat_relay_protocol.en.asciidoc
+152 -153
View File
@@ -7,27 +7,26 @@
:docinfo1:
This document is the specification of WeeChat Relay protocol: the protocol used
to relay WeeChat data to clients, which are mostly remote interfaces.
[[introduction]]
== Introduction
This document is the specification of WeeChat Relay protocol: the protocol used
to relay WeeChat data to clients, which are mostly remote interfaces.
[[terminology]]
=== Terminology
The following terms are used in this document:
* 'relay': this is the WeeChat with relay plugin, which acts as "server" and
allows 'clients' to connect
* 'client': this is another software, connected to 'relay' via a network
connection; in most cases, this 'client' is a remote interface.
* _relay_: this is the WeeChat with relay plugin, which acts as "server" and
allows _clients_ to connect
* _client_: this is another software, connected to _relay_ via a network
connection; in most cases, this _client_ is a remote interface.
[[network_diagram]]
=== Network diagram
The 'clients' are connected to 'relay' like shown in this diagram:
The _clients_ are connected to _relay_ like shown in this diagram:
....
┌──────────┐ Workstation
@@ -48,20 +47,20 @@ network servers ncurses interface relay remote interfaces
....
[NOTE]
All clients here are clients using 'weechat' protocol in 'relay' plugin. The
'relay' plugin also allows IRC clients, then 'relay' plugin acts as an
'IRC proxy' (not described in this document).
All clients here are clients using _weechat_ protocol in _relay_ plugin. The
_relay_ plugin also allows IRC clients, then _relay_ plugin acts as an
_IRC proxy_ (not described in this document).
[[protocol_generalities]]
== Protocol generalities
* Connections from 'client' to 'relay' are made using TCP sockets on IP/port
used by 'relay' plugin to listen to new connections.
* Number of 'clients' is limited by the option 'relay.network.max_clients'.
* Each 'client' is independent from other clients.
* Messages from 'client' to 'relay' are called 'commands', they are sent as text
* Connections from _client_ to _relay_ are made using TCP sockets on IP/port
used by _relay_ plugin to listen to new connections.
* Number of _clients_ is limited by the option _relay.network.max_clients_.
* Each _client_ is independent from other clients.
* Messages from _client_ to _relay_ are called _commands_, they are sent as text
(a string).
* Messages from 'relay' to 'client' are called 'messages', they are sent as
* Messages from _relay_ to _client_ are called _messages_, they are sent as
binary data.
[[commands]]
@@ -71,11 +70,11 @@ Commands have format: "(id) command arguments\n".
Fields are:
* 'id': optional message identifier that will be sent in answer from 'relay';
* _id_: optional message identifier that will be sent in answer from _relay_;
it must be enclosed in parentheses, and must not start with an underscore
("_") (ids starting with underscore are reserved for WeeChat 'event' messages)
* 'command': a command (see table below)
* 'arguments': optional arguments for command (many arguments are separated by
("_") (ids starting with underscore are reserved for WeeChat _event_ messages)
* _command_: a command (see table below)
* _arguments_: optional arguments for command (many arguments are separated by
spaces).
List of available commands (detail in next chapters):
@@ -83,22 +82,22 @@ List of available commands (detail in next chapters):
[width="80%",cols="^3m,14",options="header"]
|===
| Command | Description
| init | Initialize connection with 'relay'
| hdata | Request a 'hdata'
| info | Request an 'info'
| infolist | Request an 'infolist'
| nicklist | Request a 'nicklist'
| init | Initialize connection with _relay_
| hdata | Request a _hdata_
| info | Request an _info_
| infolist | Request an _infolist_
| nicklist | Request a _nicklist_
| input | Send data to a buffer (text or command)
| sync | Synchronize buffer(s) (get updates for buffer(s))
| desync | Desynchronize buffer(s) (stop updates for buffer(s))
| quit | Disconnect from 'relay'
| quit | Disconnect from _relay_
|===
[[command_init]]
=== init
Initialize connection with 'relay'. This must be first command sent to 'relay'.
If not sent, 'relay' will close connection on first command received, without
Initialize connection with _relay_. This must be first command sent to _relay_.
If not sent, _relay_ will close connection on first command received, without
warning.
Syntax:
@@ -109,15 +108,15 @@ init [<option>=<value>,[<option>=<value>,...]]
Arguments:
* 'option': one of following options:
** 'password': password used to authenticate on 'relay' (option
'relay.network.password' in WeeChat)
** 'compression': compression type:
*** 'zlib': enable 'zlib' compression for messages sent by 'relay'
*** 'off': disable compression
* _option_: one of following options:
** _password_: password used to authenticate on _relay_ (option
_relay.network.password_ in WeeChat)
** _compression_: compression type:
*** _zlib_: enable _zlib_ compression for messages sent by _relay_
*** _off_: disable compression
[NOTE]
Compression 'zlib' is enabled by default if 'relay' supports 'zlib' compression.
Compression _zlib_ is enabled by default if _relay_ supports _zlib_ compression.
Examples:
@@ -132,7 +131,7 @@ init password=mypass,compression=off
[[command_hdata]]
=== hdata
Request a 'hdata'.
Request a _hdata_.
Syntax:
@@ -142,14 +141,14 @@ Syntax:
Arguments:
* 'path': path to a hdata, with format: "hdata:pointer/var/var/.../var", the
* _path_: path to a hdata, with format: "hdata:pointer/var/var/.../var", the
last var is the hdata returned:
** 'hdata': name of hdata
** 'pointer': pointer ("0x12345") or list name (for example: "gui_buffers")
** _hdata_: name of hdata
** _pointer_: pointer ("0x12345") or list name (for example: "gui_buffers")
(count allowed, see below)
** 'var': a variable name in parent hdata (previous name in path)
** _var_: a variable name in parent hdata (previous name in path)
(count allowed, see below)
* 'keys': comma-separated list of keys to return in hdata (if not specified, all
* _keys_: comma-separated list of keys to return in hdata (if not specified, all
keys are returned, which is not recommended on large hdata structures)
A count is allowed after pointer and variables, with format "(N)". Possible
@@ -157,7 +156,7 @@ values are:
* positive number: iterate using next element, N times
* negative number: iterate using previous element, N times
* '*': iterate using next element, until end of list
* _*_: iterate using next element, until end of list
Examples:
@@ -177,7 +176,7 @@ hdata buffer:gui_buffers full_name
[[command_info]]
=== info
Request an 'info'.
Request an _info_.
Syntax:
@@ -187,7 +186,7 @@ Syntax:
Arguments:
* 'name': name of info to retrieve
* _name_: name of info to retrieve
Example:
@@ -198,7 +197,7 @@ info version
[[command_infolist]]
=== infolist
Request an 'infolist'.
Request an _infolist_.
[IMPORTANT]
Content of infolist is a duplication of actual data. Wherever possible, use
@@ -213,9 +212,9 @@ Syntax:
Arguments:
* 'name': name of infolist to retrieve
* 'pointer': pointer (optional)
* 'arguments': arguments (optional)
* _name_: name of infolist to retrieve
* _pointer_: pointer (optional)
* _arguments_: arguments (optional)
Example:
@@ -226,7 +225,7 @@ infolist buffer
[[command_nicklist]]
=== nicklist
Request a 'nicklist', for one or all buffers.
Request a _nicklist_, for one or all buffers.
Syntax:
@@ -236,8 +235,8 @@ Syntax:
Arguments:
* 'buffer': pointer ('0x12345') or full name of buffer (for example:
'core.weechat' or 'irc.freenode.#weechat')
* _buffer_: pointer (_0x12345_) or full name of buffer (for example:
_core.weechat_ or _irc.freenode.#weechat_)
Examples:
@@ -262,9 +261,9 @@ input <buffer> <data>
Arguments:
* 'buffer': pointer ('0x12345') or full name of buffer (for example:
'core.weechat' or 'irc.freenode.#weechat')
* 'data': data to send to buffer: if beginning by '/', this will be executed as
* _buffer_: pointer (_0x12345_) or full name of buffer (for example:
_core.weechat_ or _irc.freenode.#weechat_)
* _data_: data to send to buffer: if beginning by `/`, this will be executed as
a command on buffer, otherwise text is sent as input of buffer
Examples:
@@ -294,21 +293,21 @@ sync [<buffer>[,<buffer>...] <option>[,<option>...]]
Arguments:
* 'buffer': pointer ('0x12345') or full name of buffer (for example:
'core.weechat' or 'irc.freenode.#weechat'); name "*" can be used to
* _buffer_: pointer (_0x12345_) or full name of buffer (for example:
_core.weechat_ or _irc.freenode.#weechat_); name "*" can be used to
specify all buffers
* 'options': one of following keywords, separated by commas (default is
'buffers,upgrade,buffer,nicklist' for "*" and 'buffer,nicklist' for a buffer):
** 'buffers': receive signals about buffers (opened/closed, moved, renamed,
* _options_: one of following keywords, separated by commas (default is
_buffers,upgrade,buffer,nicklist_ for "*" and _buffer,nicklist_ for a buffer):
** _buffers_: receive signals about buffers (opened/closed, moved, renamed,
merged/unmerged, hidden/unhidden); this can be used only with name "*"
_(WeeChat ≥ 0.4.1)_
** 'upgrade': receive signals about WeeChat upgrade (upgrade, upgrade ended);
** _upgrade_: receive signals about WeeChat upgrade (upgrade, upgrade ended);
this can be used only with name "*"
_(WeeChat ≥ 0.4.1)_
** 'buffer': receive signals about buffer (new lines, type changed, title
changed, local variable added/removed, and same signals as 'buffers' for the
** _buffer_: receive signals about buffer (new lines, type changed, title
changed, local variable added/removed, and same signals as _buffers_ for the
buffer) _(updated in version 0.4.1)_
** 'nicklist': receive nicklist after changes
** _nicklist_: receive nicklist after changes
Examples:
@@ -339,7 +338,7 @@ _Updated in version 0.4.1._
Desynchronize one or more buffers, to stop updates.
[NOTE]
This will remove 'options' for buffers. If some options are still active for
This will remove _options_ for buffers. If some options are still active for
buffers, the client will still receive updates for these buffers.
Syntax:
@@ -350,11 +349,11 @@ desync [<buffer>[,<buffer>...] <option>[,<option>...]]
Arguments:
* 'buffer': pointer ('0x12345') or full name of buffer (for example:
'core.weechat' or 'irc.freenode.#weechat'); name "*" can be used to
* _buffer_: pointer (_0x12345_) or full name of buffer (for example:
_core.weechat_ or _irc.freenode.#weechat_); name "*" can be used to
specify all buffers
* 'options': one of following keywords, separated by commas (default is
'buffers,upgrade,buffer,nicklist' for "*" and 'buffer,nicklist' for a buffer);
* _options_: one of following keywords, separated by commas (default is
_buffers,upgrade,buffer,nicklist_ for "*" and _buffer,nicklist_ for a buffer);
see <<command_sync,command sync>> for values
[NOTE]
@@ -452,7 +451,7 @@ ping 1370802127000
[[command_quit]]
=== quit
Disconnect from 'relay'.
Disconnect from _relay_.
Syntax:
@@ -480,40 +479,40 @@ Messages are sent as binary data, using following format (with size in bytes):
└────────────────────┘ └──────────────────────────────────────────────────┘
header (5) compressed data (??)
└─────────────────────────────────────────────────────────────────────────┘
'length' bytes
_length_ bytes
....
* 'length' (unsigned integer): number of bytes of whole message (including
* _length_ (unsigned integer): number of bytes of whole message (including
this field)
* 'compression' (byte): flag:
** '0x00': following data is not compressed
** '0x01': following data is compressed with 'zlib'
* 'id' (string): identifier sent by client (before command name); it can be
* _compression_ (byte): flag:
** _0x00_: following data is not compressed
** _0x01_: following data is compressed with _zlib_
* _id_ (string): identifier sent by client (before command name); it can be
empty (string with zero length and no content) if no identifier was given in
command
* 'type' (3 chars): a type: 3 letters (see table below)
* 'object': an object (see table below)
* _type_ (3 chars): a type: 3 letters (see table below)
* _object_: an object (see table below)
[[message_compression]]
=== Compression
If flag 'compression' is equal to 0x01, then *all* data after is compressed
with 'zlib', and therefore must be uncompressed before being processed.
If flag _compression_ is equal to 0x01, then *all* data after is compressed
with _zlib_, and therefore must be uncompressed before being processed.
[[message_identifier]]
=== Identifier
There are two types of identifiers ('id'):
There are two types of identifiers (_id_):
* 'id' sent by 'client': 'relay' will answer with same 'id' in its answer
* 'id' of an event: on some events, 'relay' will send message to 'client' using
a specific 'id', beginning with underscore (see table below)
* _id_ sent by _client_: _relay_ will answer with same _id_ in its answer
* _id_ of an event: on some events, _relay_ will send message to _client_ using
a specific _id_, beginning with underscore (see table below)
WeeChat reserved identifiers:
[width="100%",cols="5,5,3,4,7",options="header"]
|===
| Identifier | Received with 'sync' | Data sent |
| Identifier | Received with _sync_ | Data sent |
Description | Recommended action in client
| _buffer_opened | buffers / buffer | hdata: buffer |
@@ -589,8 +588,8 @@ Data sent as hdata:
|===
| Name | Type | Description
| number | integer | Buffer number (≥ 1)
| full_name | string | Full name (example: 'irc.freenode.#weechat')
| short_name | string | Short name (example: '#weechat')
| full_name | string | Full name (example: _irc.freenode.#weechat_)
| short_name | string | Short name (example: _#weechat_)
| nicklist | integer | 1 if buffer has a nicklist, otherwise 0
| title | string | Buffer title
| local_variables | hashtable | Local variables
@@ -598,8 +597,8 @@ Data sent as hdata:
| next_buffer | pointer | Pointer to next buffer
|===
Example: channel '#weechat' joined on freenode, new buffer
'irc.freenode.#weechat':
Example: channel _#weechat_ joined on freenode, new buffer
_irc.freenode.#weechat_:
[source,python]
----
@@ -632,12 +631,12 @@ Data sent as hdata:
|===
| Name | Type | Description
| number | integer | Buffer number (≥ 1)
| full_name | string | Full name (example: 'irc.freenode.#weechat')
| full_name | string | Full name (example: _irc.freenode.#weechat_)
| prev_buffer | pointer | Pointer to previous buffer
| next_buffer | pointer | Pointer to next buffer
|===
Example: buffer 'irc.freenode.#weechat' moved to number 2:
Example: buffer _irc.freenode.#weechat_ moved to number 2:
[source,python]
----
@@ -665,12 +664,12 @@ Data sent as hdata:
|===
| Name | Type | Description
| number | integer | Buffer number (≥ 1)
| full_name | string | Full name (example: 'irc.freenode.#weechat')
| full_name | string | Full name (example: _irc.freenode.#weechat_)
| prev_buffer | pointer | Pointer to previous buffer
| next_buffer | pointer | Pointer to next buffer
|===
Example: buffer 'irc.freenode.#weechat' merged with buffer #2:
Example: buffer _irc.freenode.#weechat_ merged with buffer #2:
[source,python]
----
@@ -698,12 +697,12 @@ Data sent as hdata:
|===
| Name | Type | Description
| number | integer | Buffer number (≥ 1)
| full_name | string | Full name (example: 'irc.freenode.#weechat')
| full_name | string | Full name (example: _irc.freenode.#weechat_)
| prev_buffer | pointer | Pointer to previous buffer
| next_buffer | pointer | Pointer to next buffer
|===
Example: buffer 'irc.freenode.#weechat' unmerged:
Example: buffer _irc.freenode.#weechat_ unmerged:
[source,python]
----
@@ -733,12 +732,12 @@ Data sent as hdata:
|===
| Name | Type | Description
| number | integer | Buffer number (≥ 1)
| full_name | string | Full name (example: 'irc.freenode.#weechat')
| full_name | string | Full name (example: _irc.freenode.#weechat_)
| prev_buffer | pointer | Pointer to previous buffer
| next_buffer | pointer | Pointer to next buffer
|===
Example: buffer 'irc.freenode.#weechat' hidden:
Example: buffer _irc.freenode.#weechat_ hidden:
[source,python]
----
@@ -768,12 +767,12 @@ Data sent as hdata:
|===
| Name | Type | Description
| number | integer | Buffer number (≥ 1)
| full_name | string | Full name (example: 'irc.freenode.#weechat')
| full_name | string | Full name (example: _irc.freenode.#weechat_)
| prev_buffer | pointer | Pointer to previous buffer
| next_buffer | pointer | Pointer to next buffer
|===
Example: buffer 'irc.freenode.#weechat' unhidden:
Example: buffer _irc.freenode.#weechat_ unhidden:
[source,python]
----
@@ -801,12 +800,12 @@ Data sent as hdata:
|===
| Name | Type | Description
| number | integer | Buffer number (≥ 1)
| full_name | string | Full name (example: 'irc.freenode.#weechat')
| short_name | string | Short name (example: '#weechat')
| full_name | string | Full name (example: _irc.freenode.#weechat_)
| short_name | string | Short name (example: _#weechat_)
| local_variables | hashtable | Local variables
|===
Example: private buffer renamed from 'FlashCode' to 'Flash2':
Example: private buffer renamed from _FlashCode_ to _Flash2_:
[source,python]
----
@@ -835,11 +834,11 @@ Data sent as hdata:
|===
| Name | Type | Description
| number | integer | Buffer number (≥ 1)
| full_name | string | Full name (example: 'irc.freenode.#weechat')
| full_name | string | Full name (example: _irc.freenode.#weechat_)
| title | string | Buffer title
|===
Example: topic changed on channel '#weechat':
Example: topic changed on channel _#weechat_:
[source,python]
----
@@ -868,10 +867,10 @@ Data sent as hdata:
|===
| Name | Type | Description
| number | integer | Buffer number (≥ 1)
| full_name | string | Full name (example: 'irc.freenode.#weechat')
| full_name | string | Full name (example: _irc.freenode.#weechat_)
|===
Example: buffer 'irc.freenode.#weechat' has been cleared:
Example: buffer _irc.freenode.#weechat_ has been cleared:
[source,python]
----
@@ -897,11 +896,11 @@ Data sent as hdata:
|===
| Name | Type | Description
| number | integer | Buffer number (≥ 1)
| full_name | string | Full name (example: 'irc.freenode.#weechat')
| full_name | string | Full name (example: _irc.freenode.#weechat_)
| type | integer | Buffer type: 0 = formatted (default), 1 = free content
|===
Example: type of buffer 'script.scripts' changed from formatted (0) to free
Example: type of buffer _script.scripts_ changed from formatted (0) to free
content (1):
[source,python]
@@ -929,11 +928,11 @@ Data sent as hdata:
|===
| Name | Type | Description
| number | integer | Buffer number (≥ 1)
| full_name | string | Full name (example: 'irc.freenode.#weechat')
| full_name | string | Full name (example: _irc.freenode.#weechat_)
| local_variables | hashtable | Local variables
|===
Example: local variable 'test' added in buffer 'irc.freenode.#weechat':
Example: local variable _test_ added in buffer _irc.freenode.#weechat_:
[source,python]
----
@@ -962,11 +961,11 @@ Data sent as hdata:
|===
| Name | Type | Description
| number | integer | Buffer number (≥ 1)
| full_name | string | Full name (example: 'irc.freenode.#weechat')
| full_name | string | Full name (example: _irc.freenode.#weechat_)
| local_variables | hashtable | Local variables
|===
Example: local variable 'test' updated in buffer 'irc.freenode.#weechat':
Example: local variable _test_ updated in buffer _irc.freenode.#weechat_:
[source,python]
----
@@ -995,11 +994,11 @@ Data sent as hdata:
|===
| Name | Type | Description
| number | integer | Buffer number (≥ 1)
| full_name | string | Full name (example: 'irc.freenode.#weechat')
| full_name | string | Full name (example: _irc.freenode.#weechat_)
| local_variables | hashtable | Local variables
|===
Example: local variable 'test' removed from buffer 'irc.freenode.#weechat':
Example: local variable _test_ removed from buffer _irc.freenode.#weechat_:
[source,python]
----
@@ -1036,7 +1035,7 @@ Data sent as hdata:
| message | string | Message
|===
Example: new message 'hello!' from nick 'FlashCode' on buffer 'irc.freenode.#weechat':
Example: new message _hello!_ from nick _FlashCode_ on buffer _irc.freenode.#weechat_:
[source,python]
----
@@ -1069,10 +1068,10 @@ Data sent as hdata:
|===
| Name | Type | Description
| number | integer | Buffer number (≥ 1)
| full_name | string | Full name (example: 'irc.freenode.#weechat')
| full_name | string | Full name (example: _irc.freenode.#weechat_)
|===
Example: buffer 'irc.freenode.#weechat' is being closed by WeeChat:
Example: buffer _irc.freenode.#weechat_ is being closed by WeeChat:
[source,python]
----
@@ -1093,7 +1092,7 @@ This message is sent to the client when large updates are made on a nicklist
(groups/nicks added/removed/changed). The message contains full nicklist.
When small updates are made on a nicklist (for example just add one nick),
another message with identifier '_nicklist_diff' is sent (see below).
another message with identifier __nicklist_diff_ is sent (see below).
Data sent as hdata:
@@ -1109,7 +1108,7 @@ Data sent as hdata:
| prefix_color | string | Prefix color (only for a nick)
|===
Example: nicklist for buffer 'irc.freenode.#weechat':
Example: nicklist for buffer _irc.freenode.#weechat_:
[source,python]
----
@@ -1198,7 +1197,7 @@ Data sent as hdata:
| prefix_color | string | Prefix color (only for a nick)
|===
The value of '_diff' can be:
The value of __diff_ can be:
* `^`: the parent group: group(s) or nick(s) after this one are related to this
group
@@ -1206,8 +1205,8 @@ The value of '_diff' can be:
* `-`: group/nick removed from the parent group
* `*`: group/nick updated in the parent group
Example: nick 'master' added in group '000|o' (channel ops on an IRC channel),
nicks 'nick1' and 'nick2' added in group '999|...' (standard users on an IRC
Example: nick _master_ added in group _000|o_ (channel ops on an IRC channel),
nicks _nick1_ and _nick2_ added in group _999|..._ (standard users on an IRC
channel):
[source,python]
@@ -1274,7 +1273,7 @@ hda:
_WeeChat ≥ 0.4.2._
This message is sent to the client when 'relay' receives a "ping" message.
This message is sent to the client when _relay_ receives a "ping" message.
Data sent as string: arguments received in the "ping" message.
@@ -1291,7 +1290,7 @@ This message is sent to the client when WeeChat is starting upgrade process.
There is no data in the message.
The recommended action in client is to desynchronize from WeeChat (send command
'desync'), or to disconnect from WeeChat (because after upgrade, all pointers
_desync_), or to disconnect from WeeChat (because after upgrade, all pointers
will change).
[NOTE]
@@ -1309,12 +1308,12 @@ process.
There is no data in the message.
The recommended action in client is to resynchronize with WeeChat: resend all
commands sent on startup after the 'init'.
commands sent on startup after the _init_.
[[objects]]
=== Objects
Objects are identified by 3 letters, called 'type'. Following types are used:
Objects are identified by 3 letters, called _type_. Following types are used:
[width="100%",cols="^2m,5,10",options="header"]
|===
@@ -1322,7 +1321,7 @@ Objects are identified by 3 letters, called 'type'. Following types are used:
| chr | Signed char | 1 byte
| int | Signed integer | 4 bytes
| lon | Signed long integer | 1 byte + length of integer as string
| str | String | 4 bytes + length of string (without final '\0')
| str | String | 4 bytes + length of string (without final _\0_)
| buf | Buffer of bytes | 4 bytes + length of data
| ptr | Pointer | 1 byte + length of pointer as string
| tim | Time | 1 byte + length of time as string
@@ -1392,7 +1391,7 @@ length '-' '1' '2' '3' '4' '5' '6' '7' '8' '9' '0'
[[object_string]]
==== String
A string is a length (integer on 4 bytes) + content of string (without final '\0').
A string is a length (integer on 4 bytes) + content of string (without final _\0_).
Example:
@@ -1414,7 +1413,7 @@ An empty string has a length of zero:
length
....
A 'NULL' string (NULL pointer in C) has a length of -1:
A _NULL_ string (NULL pointer in C) has a length of -1:
....
┌────┬────┬────┬────┐
@@ -1444,7 +1443,7 @@ Example:
length '1' 'a' '2' 'b' '3' 'c' '4' 'd' '5'
....
A 'NULL' pointer has a length of 1 with value 0:
A _NULL_ pointer has a length of 1 with value 0:
....
┌────╥────┐
@@ -1495,7 +1494,7 @@ Example:
[[object_hdata]]
==== Hdata
A 'hdata' contains a path with hdata names, list of keys, number of set of
A _hdata_ contains a path with hdata names, list of keys, number of set of
objects, and then set of objects (path with pointers, then objects).
....
@@ -1508,18 +1507,18 @@ objects, and then set of objects (path with pointers, then objects).
──╨────────┴─────────────────────╨─────┘
....
* 'h-path' (string): path used to reach hdata (example:
'buffer/lines/line/line_data'); the last element in path is the hdata returned
* 'keys' (string): string with list of 'key:type' (separated by commas),
example: 'number:int,name:str'
* 'count' (integer): number of set of objects
* 'p-path': path with pointers to objects (number of pointers here is number of
* _h-path_ (string): path used to reach hdata (example:
_buffer/lines/line/line_data_); the last element in path is the hdata returned
* _keys_ (string): string with list of _key:type_ (separated by commas),
example: _number:int,name:str_
* _count_ (integer): number of set of objects
* _p-path_: path with pointers to objects (number of pointers here is number of
elements in path)
* 'values': list of values (number of values is number of keys returned for
* _values_: list of values (number of values is number of keys returned for
hdata)
Example of hdata with two buffers (weechat core and freenode server) and two
keys ('number' and 'full_name'):
keys (_number_ and _full_name_):
....
# command
@@ -1616,7 +1615,7 @@ nicklist
[[object_info]]
==== Info
A 'info' contains a name and a value (both are strings).
A _info_ contains a name and a value (both are strings).
....
┌──────┬───────┐
@@ -1624,10 +1623,10 @@ A 'info' contains a name and a value (both are strings).
└──────┴───────┘
....
* 'name' (string): name of info
* 'value' (string): value
* _name_ (string): name of info
* _value_ (string): value
Example of info 'version':
Example of info _version_:
....
┌─────────┬───────────────────┐
@@ -1638,7 +1637,7 @@ Example of info 'version':
[[object_infolist]]
==== Infolist
A 'infolist' contains a name, number of items, and then items (set of
A _infolist_ contains a name, number of items, and then items (set of
variables).
....
@@ -1655,13 +1654,13 @@ An item is:
└───────╨────────┴────────┴─────────╨─────╨────────┴────────┴─────────┘
....
* 'name' (string): name of infolist ('buffer', 'window', 'bar', ...)
* 'count' (integer): number of items
* 'item':
** 'count': number of variables in item
** 'name': name of variable
** 'type': type of variable ('int', 'str', ...)
** 'value': value of variable
* _name_ (string): name of infolist (_buffer_, _window_, _bar_, ...)
* _count_ (integer): number of items
* _item_:
** _count_: number of variables in item
** _name_: name of variable
** _type_: type of variable (_int_, _str_, ...)
** _value_: value of variable
Example of infolist with two buffers (weechat core and freenode server):
@@ -1720,7 +1719,7 @@ Example of array with three integers:
456 (0x1C8) 789 (0x315)
....
A 'NULL' array:
A _NULL_ array:
....
┌─────╥────┬────┬────┬────┐
doc/fr/weechat_relay_protocol.fr.asciidoc
+154 -154
View File
@@ -21,16 +21,16 @@ interfaces distantes.
Les termes suivants sont utilisés dans ce document :
* 'relay' : il s'agit de l'extension "relay" de WeeChat, qui agit comme un
"serveur" et autorise les 'clients' à se connecter
* 'client' : il s'agit d'un autre logiciel, connecté au 'relay' via une
connexion réseau; dans la plupart des cas, ce 'client' est une interface
* _relay_ : il s'agit de l'extension "relay" de WeeChat, qui agit comme un
"serveur" et autorise les _clients_ à se connecter
* _client_ : il s'agit d'un autre logiciel, connecté au _relay_ via une
connexion réseau; dans la plupart des cas, ce _client_ est une interface
distante.
[[network_diagram]]
=== Diagramme réseau
Les 'clients' sont connectés au 'relay' comme dans le diagramme ci-dessous :
Les _clients_ sont connectés au _relay_ comme dans le diagramme ci-dessous :
....
┌──────────┐ Station de travail
@@ -51,20 +51,20 @@ Les 'clients' sont connectés au 'relay' comme dans le diagramme ci-dessous :
....
[NOTE]
Tous les clients ici utilisent le protocole 'weechat' dans l'extension 'relay'.
L'extension 'relay' autorise aussi des clients IRC, et 'relay' agit alors comme
un 'proxy IRC' (non décrit dans ce document).
Tous les clients ici utilisent le protocole _weechat_ dans l'extension _relay_.
L'extension _relay_ autorise aussi des clients IRC, et _relay_ agit alors comme
un _proxy IRC_ (non décrit dans ce document).
[[protocol_generalities]]
== Généralités sur le protocole
* Les connexions du 'client' vers 'relay' sont faites avec des sockets TCP sur
l'IP/port utilisé par 'relay' pour écouter les nouvelles connexions.
* Le nombre de clients est limité par l'option 'relay.network.max_clients'.
* Chaque 'client' est indépendant des autres clients.
* Les messages du 'client' vers 'relay' sont appelés 'commandes', elles sont
* Les connexions du _client_ vers _relay_ sont faites avec des sockets TCP sur
l'IP/port utilisé par _relay_ pour écouter les nouvelles connexions.
* Le nombre de clients est limité par l'option _relay.network.max_clients_.
* Chaque _client_ est indépendant des autres clients.
* Les messages du _client_ vers _relay_ sont appelés _commandes_, elles sont
envoyées sous forme de texte (une chaîne de caractères).
* Les messages de 'relay' vers le 'client' sont appelés des 'messages', ils sont
* Les messages de _relay_ vers le _client_ sont appelés des _messages_, ils sont
envoyés sous forme de données binaires.
[[commands]]
@@ -74,12 +74,12 @@ Les commandes ont le format : "(id) commande paramètres\n".
Les champs sont :
* 'id' : identifiant du message (facultatif) qui sera envoyée dans la réponse de
'relay'; elle doit être entre parenthèses, et ne doit pas commencer par un
* _id_ : identifiant du message (facultatif) qui sera envoyée dans la réponse de
_relay_; elle doit être entre parenthèses, et ne doit pas commencer par un
underscore ("_") (les identifiants commençant par un underscore sont réservés
pour les messages 'évènements' de WeeChat)
* 'commande' : une commande (voir le tableau ci-dessous)
* 'paramètres' : paramètres facultatifs pour la commande (plusieurs paramètres
pour les messages _évènements_ de WeeChat)
* _commande_ : une commande (voir le tableau ci-dessous)
* _paramètres_ : paramètres facultatifs pour la commande (plusieurs paramètres
sont séparés par des espaces).
Liste des commandes disponibles (détail dans les chapitres suivants) :
@@ -87,22 +87,22 @@ Liste des commandes disponibles (détail dans les chapitres suivants) :
[width="80%",cols="^3m,14",options="header"]
|===
| Commande | Description
| init | Initialiser la connexion avec 'relay'
| hdata | Demander un 'hdata'
| info | Demander une 'info'
| infolist | Demander une 'infolist'
| nicklist | Demander une 'nicklist' (liste de pseudos)
| init | Initialiser la connexion avec _relay_
| hdata | Demander un _hdata_
| info | Demander une _info_
| infolist | Demander une _infolist_
| nicklist | Demander une _nicklist_ (liste de pseudos)
| input | Envoyer des données à un tampon (texte ou commande)
| sync | Synchroniser un/des tampon(s) (recevoir les mises à jour pour le(s) tampon(s))
| desync | Désynchroniser un/des tampon(s) (stopper les mises à jour pour le(s) tampon(s))
| quit | Se déconnecter de 'relay'
| quit | Se déconnecter de _relay_
|===
[[command_init]]
=== init
Initialiser la connexion avec 'relay'. Il doit s'agir de la première commande
envoyée à 'relay'. Si elle n'est pas envoyée, 'relay' coupera la connexion à la
Initialiser la connexion avec _relay_. Il doit s'agir de la première commande
envoyée à _relay_. Si elle n'est pas envoyée, _relay_ coupera la connexion à la
première commande reçue, sans avertissement.
Syntaxe :
@@ -113,16 +113,16 @@ init [<option>=<valeur>,[<option>=<valeur>,...]]
Paramètres :
* 'option' : une des options suivantes :
** 'password' : mot de passe utilisé pour s'authentifier avec 'relay' (option
'relay.network.password' dans WeeChat)
** 'compression' : type de compression :
*** 'zlib' : activer la compression 'zlib' pour les messages envoyés par 'relay'
*** 'off' : désactiver la compression
* _option_ : une des options suivantes :
** _password_ : mot de passe utilisé pour s'authentifier avec _relay_ (option
_relay.network.password_ dans WeeChat)
** _compression_ : type de compression :
*** _zlib_ : activer la compression _zlib_ pour les messages envoyés par _relay_
*** _off_ : désactiver la compression
[NOTE]
La compression 'zlib' est activée par défaut si 'relay' supporte la compression
'zlib'.
La compression _zlib_ est activée par défaut si _relay_ supporte la compression
_zlib_.
Exemples :
@@ -137,7 +137,7 @@ init password=mypass,compression=off
[[command_hdata]]
=== hdata
Demander un 'hdata'.
Demander un _hdata_.
Syntaxe :
@@ -147,14 +147,14 @@ Syntaxe :
Paramètres :
* 'chemin' : chemin vers le hdata, avec le format :
* _chemin_ : chemin vers le hdata, avec le format :
"hdata:pointeur/var/var/.../var", la dernière variable est le hdata retourné :
** 'hdata' : nom du hdata
** 'pointeur' : pointeur ("0x12345") ou nom de liste (par exemple :
** _hdata_ : nom du hdata
** _pointeur_ : pointeur ("0x12345") ou nom de liste (par exemple :
"gui_buffers") (nombre autorisé, voir ci-dessous)
** 'var' : un nom de variable dans le hdata parent (nom précédent dans le
** _var_ : un nom de variable dans le hdata parent (nom précédent dans le
chemin) (nombre autorisé, voir ci-dessous)
* 'clés' : liste de clés (séparées par des virgules) à retourner dans le hdata
* _clés_ : liste de clés (séparées par des virgules) à retourner dans le hdata
(si non spécifié, toutes les clés sont retournées, ce qui n'est pas recommandé
avec les grosses structures hdata)
@@ -163,7 +163,7 @@ Les valeurs possibles sont :
* nombre positif : itérer en utilisant l'élément suivant, N fois
* nombre négatif : itérer en utilisant l'élément précédent, N fois
* '*' : itérer en utilisant l'élément suivant, jusqu'à la fin de la liste
* _*_ : itérer en utilisant l'élément suivant, jusqu'à la fin de la liste
Exemples :
@@ -184,7 +184,7 @@ hdata buffer:gui_buffers full_name
[[command_info]]
=== info
Demander une 'info'.
Demander une _info_.
Syntaxe :
@@ -194,8 +194,8 @@ Syntaxe :
Paramètres :
* 'nom' : nom de l'info à obtenir
* 'paramètres' : paramètres pour l'info (facultatif)
* _nom_ : nom de l'info à obtenir
* _paramètres_ : paramètres pour l'info (facultatif)
Exemple :
@@ -206,7 +206,7 @@ info version
[[command_infolist]]
=== infolist
Demander une 'infolist'.
Demander une _infolist_.
[IMPORTANT]
Le contenu de l'infolist est une duplication des données. Dans la mesure du
@@ -222,9 +222,9 @@ Syntaxe :
Paramètres :
* 'nom' : nom de l'infolist à obtenir
* 'pointeur' : pointeur (facultatif)
* 'paramètres' : paramètres (facultatif)
* _nom_ : nom de l'infolist à obtenir
* _pointeur_ : pointeur (facultatif)
* _paramètres_ : paramètres (facultatif)
Exemple :
@@ -235,7 +235,7 @@ infolist buffer
[[command_nicklist]]
=== nicklist
Demander une 'nicklist' (liste de pseudos), pour un ou tous les tampons.
Demander une _nicklist_ (liste de pseudos), pour un ou tous les tampons.
Syntaxe :
@@ -245,8 +245,8 @@ Syntaxe :
Paramètres :
* 'tampon' : pointeur ('0x12345') ou nom complet du tampon (par exemple :
'core.weechat' ou 'irc.freenode.#weechat')
* _tampon_ : pointeur (_0x12345_) ou nom complet du tampon (par exemple :
_core.weechat_ ou _irc.freenode.#weechat_)
Exemples :
@@ -271,9 +271,9 @@ input <tampon> <données>
Paramètres :
* 'tampon' : pointeur ('0x12345') ou nom complet du tampon (par exemple :
'core.weechat' ou 'irc.freenode.#weechat')
* 'données' : données à envoyer au tampon : si elles commencent par '/',
* _tampon_ : pointeur (_0x12345_) ou nom complet du tampon (par exemple :
_core.weechat_ ou _irc.freenode.#weechat_)
* _données_ : données à envoyer au tampon : si elles commencent par `/`,
cela sera exécuté comme une commande sur le tampon, sinon le texte est envoyé
comme entrée sur le tampon
@@ -304,22 +304,22 @@ sync [<tampon>[,<tampon>...] <option>[,<option>...]]
Paramètres :
* 'tampon' : pointeur ('0x12345') ou nom complet du tampon (par exemple :
'core.weechat' ou 'irc.freenode.#weechat'); le nom "*" peut être utilisé pour
* _tampon_ : pointeur (_0x12345_) ou nom complet du tampon (par exemple :
_core.weechat_ ou _irc.freenode.#weechat_); le nom "*" peut être utilisé pour
spécifier tous les tampons
* 'options' : un ou plusieurs mots-clés, séparés par des virgules (par défaut
'buffers,upgrade,buffer,nicklist' pour "*" et 'buffer,nicklist' pour un
* _options_ : un ou plusieurs mots-clés, séparés par des virgules (par défaut
_buffers,upgrade,buffer,nicklist_ pour "*" et _buffer,nicklist_ pour un
tampon) :
** 'buffers' : recevoir les signaux à propos des tampons (ouverts/fermés,
** _buffers_ : recevoir les signaux à propos des tampons (ouverts/fermés,
déplacés, renommés, mélangés, masqués/démasqués); peut être utilisé seulement
avec "*" _(WeeChat ≥ 0.4.1)_
** 'upgrade' : recevoir les signaux à propos de la mise à jour de WeeChat
** _upgrade_ : recevoir les signaux à propos de la mise à jour de WeeChat
(mise à jour, fin de mise à jour); peut être utilisé seulement avec "*"
_(WeeChat ≥ 0.4.1)_
** 'buffer' : recevoir les signaux à propos du tampon (nouvelles lignes, type
** _buffer_ : recevoir les signaux à propos du tampon (nouvelles lignes, type
changé, titre changé, variable locale ajoutée/supprimée, et les même signaux
que 'buffers' pour le tampon) _(mis à jour dans la version 0.4.1)_
** 'nicklist' : recevoir la liste de pseudos après des changements
que _buffers_ pour le tampon) _(mis à jour dans la version 0.4.1)_
** _nicklist_ : recevoir la liste de pseudos après des changements
Exemples :
@@ -350,7 +350,7 @@ _Mis à jour dans la version 0.4.1._
Désynchroniser un ou plusieurs tampons, pour stopper les mises à jour.
[NOTE]
Ceci retirera les 'options' pour les tampons. Si des options sont toujours
Ceci retirera les _options_ pour les tampons. Si des options sont toujours
actives pour les tampons, le client recevra toujours les mises à jour pour ces
tampons.
@@ -362,11 +362,11 @@ desync [<tampon>[,<tampon>...] <option>[,<option>...]]
Paramètres :
* 'tampon' : pointeur ('0x12345') ou nom complet du tampon (par exemple :
'core.weechat' ou 'irc.freenode.#weechat'); le nom "*" peut être utilisé pour
* _tampon_ : pointeur (_0x12345_) ou nom complet du tampon (par exemple :
_core.weechat_ ou _irc.freenode.#weechat_); le nom "*" peut être utilisé pour
spécifier tous les tampons
* 'options' : un ou plusieurs mots-clés, séparés par des virgules (le défaut est
'buffers,upgrade,buffer,nicklist' pour "*" et 'buffer,nicklist' pour un
* _options_ : un ou plusieurs mots-clés, séparés par des virgules (le défaut est
_buffers,upgrade,buffer,nicklist_ pour "*" et _buffer,nicklist_ pour un
tampon); voir <<command_sync,la commande sync>> pour les valeurs
[NOTE]
@@ -467,7 +467,7 @@ ping 1370802127000
[[command_quit]]
=== quit
Se déconnecter de 'relay'.
Se déconnecter de _relay_.
Syntaxe :
@@ -499,40 +499,40 @@ suivant (avec la taille en octets) :
'taille' octets
....
* 'taille' (entier non signé) : nombre d'octets du message entier (en incluant
* _taille_ (entier non signé) : nombre d'octets du message entier (en incluant
ce champ)
* 'compression' (octet) : drapeau :
** '0x00' : les données qui suivent ne sont pas compressées
** '0x01' : les données qui suivent sont compressées avec 'zlib'
* 'id' (chaîne) : l'identifiant envoyé par le client (avant le nom de la
* _compression_ (octet) : drapeau :
** _0x00_ : les données qui suivent ne sont pas compressées
** _0x01_ : les données qui suivent sont compressées avec _zlib_
* _id_ (chaîne) : l'identifiant envoyé par le client (avant le nom de la
commande); il peut être vide (chaîne avec une longueur de zéro sans contenu)
si l'identifiant n'était pas donné dans la commande
* 'type' (3 caractères) : un type : 3 lettres (voir le tableau ci-dessous)
* 'objet' : un objet (voir tableau ci-dessous)
* _type_ (3 caractères) : un type : 3 lettres (voir le tableau ci-dessous)
* _objet_ : un objet (voir tableau ci-dessous)
[[message_compression]]
=== Compression
Si le drapeau de 'compression' est égal à 0x01, alors *toutes* les données après
sont compressées avec 'zlib', et par conséquent doivent être décompressées avant
Si le drapeau de _compression_ est égal à 0x01, alors *toutes* les données après
sont compressées avec _zlib_, et par conséquent doivent être décompressées avant
d'être utilisées.
[[message_identifier]]
=== Identifiant
Il y a deux types d'identifiants ('id') :
Il y a deux types d'identifiants (_id_) :
* 'id' envoyé par le 'client' : 'relay' répondra avec le même 'id' dans sa
* _id_ envoyé par le _client_ : _relay_ répondra avec le même _id_ dans sa
réponse
* 'id' d'un évènement : pour certains évènements, 'relay' enverra un message au
'client' en utilisant un 'id' spécifique, commençant par underscore (voir le
* _id_ d'un évènement : pour certains évènements, _relay_ enverra un message au
_client_ en utilisant un _id_ spécifique, commençant par underscore (voir le
tableau ci-dessous)
Les identifiants réservés par WeeChat :
[width="100%",cols="5,5,3,4,7",options="header"]
|===
| Identifiant | Reçu avec 'sync' | Données envoyées |
| Identifiant | Reçu avec _sync_ | Données envoyées |
Description | Action recommandée dans le client
| _buffer_opened | buffers / buffer | hdata : buffer |
@@ -608,8 +608,8 @@ Données envoyées dans le hdata :
|===
| Nom | Type | Description
| number | entier | Numéro de tampon (≥ 1)
| full_name | chaîne | Nom complet (exemple : 'irc.freenode.#weechat')
| short_name | chaîne | Nom court (exemple : '#weechat')
| full_name | chaîne | Nom complet (exemple : _irc.freenode.#weechat_)
| short_name | chaîne | Nom court (exemple : _#weechat_)
| nicklist | entier | 1 si le tampon a une liste de pseudos, sinon 0
| title | chaîne | Titre du tampon
| local_variables | table de hachage | Variables locales
@@ -617,8 +617,8 @@ Données envoyées dans le hdata :
| next_buffer | pointeur | Pointeur vers le tampon suivant
|===
Exemple : canal '#weechat' rejoint sur freenode, nouveau tampon
'irc.freenode.#weechat' :
Exemple : canal _#weechat_ rejoint sur freenode, nouveau tampon
_irc.freenode.#weechat_ :
[source,python]
----
@@ -651,12 +651,12 @@ Données envoyées dans le hdata :
|===
| Nom | Type | Description
| number | entier | Numéro de tampon (≥ 1)
| full_name | chaîne | Nom complet (exemple : 'irc.freenode.#weechat')
| full_name | chaîne | Nom complet (exemple : _irc.freenode.#weechat_)
| prev_buffer | pointeur | Pointeur vers le tampon précédent
| next_buffer | pointeur | Pointeur vers le tampon suivant
|===
Exemple : tampon 'irc.freenode.#weechat' déplacé vers le numéro 2 :
Exemple : tampon _irc.freenode.#weechat_ déplacé vers le numéro 2 :
[source,python]
----
@@ -684,12 +684,12 @@ Données envoyées dans le hdata :
|===
| Nom | Type | Description
| number | entier | Numéro de tampon (≥ 1)
| full_name | chaîne | Nom complet (exemple : 'irc.freenode.#weechat')
| full_name | chaîne | Nom complet (exemple : _irc.freenode.#weechat_)
| prev_buffer | pointeur | Pointeur vers le tampon précédent
| next_buffer | pointeur | Pointeur vers le tampon suivant
|===
Exemple : tampon 'irc.freenode.#weechat' mélangé avec le tampon n°2 :
Exemple : tampon _irc.freenode.#weechat_ mélangé avec le tampon n°2 :
[source,python]
----
@@ -717,12 +717,12 @@ Données envoyées dans le hdata :
|===
| Nom | Type | Description
| number | entier | Numéro de tampon (≥ 1)
| full_name | chaîne | Nom complet (exemple : 'irc.freenode.#weechat')
| full_name | chaîne | Nom complet (exemple : _irc.freenode.#weechat_)
| prev_buffer | pointeur | Pointeur vers le tampon précédent
| next_buffer | pointeur | Pointeur vers le tampon suivant
|===
Exemple : tampon 'irc.freenode.#weechat' sorti du mélange :
Exemple : tampon _irc.freenode.#weechat_ sorti du mélange :
[source,python]
----
@@ -752,12 +752,12 @@ Données envoyées dans le hdata :
|===
| Nom | Type | Description
| number | entier | Numéro de tampon (≥ 1)
| full_name | chaîne | Nom complet (exemple : 'irc.freenode.#weechat')
| full_name | chaîne | Nom complet (exemple : _irc.freenode.#weechat_)
| prev_buffer | pointeur | Pointeur vers le tampon précédent
| next_buffer | pointeur | Pointeur vers le tampon suivant
|===
Exemple : tampon 'irc.freenode.#weechat' masqué :
Exemple : tampon _irc.freenode.#weechat_ masqué :
[source,python]
----
@@ -787,12 +787,12 @@ Données envoyées dans le hdata :
|===
| Nom | Type | Description
| number | entier | Numéro de tampon (≥ 1)
| full_name | chaîne | Nom complet (exemple : 'irc.freenode.#weechat')
| full_name | chaîne | Nom complet (exemple : _irc.freenode.#weechat_)
| prev_buffer | pointeur | Pointeur vers le tampon précédent
| next_buffer | pointeur | Pointeur vers le tampon suivant
|===
Exemple : tampon 'irc.freenode.#weechat' démasqué :
Exemple : tampon _irc.freenode.#weechat_ démasqué :
[source,python]
----
@@ -820,12 +820,12 @@ Données envoyées dans le hdata :
|===
| Nom | Type | Description
| number | entier | Numéro de tampon (≥ 1)
| full_name | chaîne | Nom complet (exemple : 'irc.freenode.#weechat')
| short_name | chaîne | Nom court (exemple : '#weechat')
| full_name | chaîne | Nom complet (exemple : _irc.freenode.#weechat_)
| short_name | chaîne | Nom court (exemple : _#weechat_)
| local_variables | table de hachage | Variables locales
|===
Exemple : tampon privé renommé de 'FlashCode' en 'Flash2' :
Exemple : tampon privé renommé de _FlashCode_ en _Flash2_ :
[source,python]
----
@@ -854,11 +854,11 @@ Données envoyées dans le hdata :
|===
| Nom | Type | Description
| number | entier | Numéro de tampon (≥ 1)
| full_name | chaîne | Nom complet (exemple : 'irc.freenode.#weechat')
| full_name | chaîne | Nom complet (exemple : _irc.freenode.#weechat_)
| title | chaîne | Titre du tampon
|===
Exemple : titre changé sur le canal '#weechat' :
Exemple : titre changé sur le canal _#weechat_ :
[source,python]
----
@@ -887,10 +887,10 @@ Données envoyées dans le hdata :
|===
| Nom | Type | Description
| number | entier | Numéro de tampon (≥ 1)
| full_name | chaîne | Nom complet (exemple : 'irc.freenode.#weechat')
| full_name | chaîne | Nom complet (exemple : _irc.freenode.#weechat_)
|===
Exemple : tampon 'irc.freenode.#weechat' vidé :
Exemple : tampon _irc.freenode.#weechat_ vidé :
[source,python]
----
@@ -916,11 +916,11 @@ Données envoyées dans le hdata :
|===
| Nom | Type | Description
| number | entier | Numéro de tampon (≥ 1)
| full_name | chaîne | Nom complet (exemple : 'irc.freenode.#weechat')
| full_name | chaîne | Nom complet (exemple : _irc.freenode.#weechat_)
| type | entier | Type de tampon : 0 = formaté (par défaut), 1 = contenu libre
|===
Exemple : type de tampon 'script.scripts' changé de formaté (0) à contenu
Exemple : type de tampon _script.scripts_ changé de formaté (0) à contenu
libre (1) :
[source,python]
@@ -948,12 +948,12 @@ Données envoyées dans le hdata :
|===
| Nom | Type | Description
| number | entier | Numéro de tampon (≥ 1)
| full_name | chaîne | Nom complet (exemple : 'irc.freenode.#weechat')
| full_name | chaîne | Nom complet (exemple : _irc.freenode.#weechat_)
| local_variables | table de hachage | Variables locales
|===
Exemple : variable locale 'test' ajoutée dans le tampon
'irc.freenode.#weechat' :
Exemple : variable locale _test_ ajoutée dans le tampon
_irc.freenode.#weechat_ :
[source,python]
----
@@ -982,12 +982,12 @@ Données envoyées dans le hdata :
|===
| Nom | Type | Description
| number | entier | Numéro de tampon (≥ 1)
| full_name | chaîne | Nom complet (exemple : 'irc.freenode.#weechat')
| full_name | chaîne | Nom complet (exemple : _irc.freenode.#weechat_)
| local_variables | table de hachage | Variables locales
|===
Exemple : variable locale 'test' mise à jour dans le tampon
'irc.freenode.#weechat' :
Exemple : variable locale _test_ mise à jour dans le tampon
_irc.freenode.#weechat_ :
[source,python]
----
@@ -1016,11 +1016,11 @@ Données envoyées dans le hdata :
|===
| Nom | Type | Description
| number | entier | Numéro de tampon (≥ 1)
| full_name | chaîne | Nom complet (exemple : 'irc.freenode.#weechat')
| full_name | chaîne | Nom complet (exemple : _irc.freenode.#weechat_)
| local_variables | table de hachage | Variables locales
|===
Exemple : variable locale 'test' supprimée du tampon 'irc.freenode.#weechat' :
Exemple : variable locale _test_ supprimée du tampon _irc.freenode.#weechat_ :
[source,python]
----
@@ -1057,8 +1057,8 @@ Données envoyées dans le hdata :
| message | chaîne | Message
|===
Exemple : nouveau message 'hello!' du pseudo 'FlashCode' sur le tampon
'irc.freenode.#weechat' :
Exemple : nouveau message _hello!_ du pseudo _FlashCode_ sur le tampon
_irc.freenode.#weechat_ :
[source,python]
----
@@ -1091,10 +1091,10 @@ Données envoyées dans le hdata :
|===
| Nom | Type | Description
| number | entier | Numéro de tampon (≥ 1)
| full_name | chaîne | Nom complet (exemple : 'irc.freenode.#weechat')
| full_name | chaîne | Nom complet (exemple : _irc.freenode.#weechat_)
|===
Exemple : tampon 'irc.freenode.#weechat' en cours de fermeture par WeeChat :
Exemple : tampon _irc.freenode.#weechat_ en cours de fermeture par WeeChat :
[source,python]
----
@@ -1116,7 +1116,7 @@ sur la liste de pseudos (groupes/pseudos ajoutés/supprimés/changés). Le messa
contient la liste complète des pseudos.
Lorsque de petites mises à jour sont faites sur la liste de pseudos (par exemple
l'ajout d'un seul pseudo), un autre message avec l'identifiant '_nicklist_diff'
l'ajout d'un seul pseudo), un autre message avec l'identifiant __nicklist_diff_
est envoyé (voir ci-dessous).
Données envoyées dans le hdata :
@@ -1133,7 +1133,7 @@ Données envoyées dans le hdata :
| prefix_color | chaîne | Couleur du préfixe (seulement pour un pseudo)
|===
Exemple : liste de pseudos pour le tampon 'irc.freenode.#weechat' :
Exemple : liste de pseudos pour le tampon _irc.freenode.#weechat_ :
[source,python]
----
@@ -1223,7 +1223,7 @@ Données envoyées dans le hdata :
| prefix_color | chaîne | Couleur du préfixe (seulement pour un pseudo)
|===
La valeur de '_diff' peut être :
La valeur de __diff_ peut être :
* `^` : le groupe parent : le(s) groupe(s)/pseudo(s) après celui-ci sont liés à
ce groupe
@@ -1231,8 +1231,8 @@ La valeur de '_diff' peut être :
* `-` : groupe/pseudo supprimé du groupe parent
* `*` : groupe/pseudo mis à jour dans le groupe parent
Exemple : pseudo 'master' ajouté dans le groupe '000|o' (opérateurs de canel sur
un canal IRC), pseudos 'nick1' et 'nick2' ajoutés dans le groupe '999|...'
Exemple : pseudo _master_ ajouté dans le groupe _000|o_ (opérateurs de canel sur
un canal IRC), pseudos _nick1_ et _nick2_ ajoutés dans le groupe _999|..._
(utilisateurs standard sur un canal IRC) :
[source,python]
@@ -1299,7 +1299,7 @@ hda:
_WeeChat ≥ 0.4.2._
Ce message est envoyé au client lorsque 'relay' reçoit un message "ping".
Ce message est envoyé au client lorsque _relay_ reçoit un message "ping".
Données envoyées dans la chaîne : paramètres reçus dans le message "ping".
@@ -1316,7 +1316,7 @@ Ce message est envoyé au client lorsque WeeChat commence sa mise à jour.
Il n'y a pas de données dans le message.
L'action recommandée dans le client est de se désynchroniser de WeeChat (envoi
de la commande 'desync'), ou de se déconnecter de WeeChat (car après la mise à
de la commande _desync_), ou de se déconnecter de WeeChat (car après la mise à
jour, tous les pointeurs changeront).
[NOTE]
@@ -1333,12 +1333,12 @@ Ce message est envoyé au client lorsque WeeChat a terminé sa mise à jour.
Il n'y a pas de données dans le message.
L'action recommandée dans le client est de se resynchroniser avec WeeChat :
envoyer à nouveau les commandes envoyées au démarrage après 'init'.
envoyer à nouveau les commandes envoyées au démarrage après _init_.
[[objects]]
=== Objets
Les objets sont identifiés par 3 lettres, appelées 'type'. Les types suivants
Les objets sont identifiés par 3 lettres, appelées _type_. Les types suivants
sont utilisés :
[width="100%",cols="^2m,5,10",options="header"]
@@ -1347,7 +1347,7 @@ sont utilisés :
| chr | Caractère signé | 1 octet
| int | Entier signé | 4 octets
| lon | Entier long signé | 1 octet + longueur de l'entier sous forme de chaîne
| str | Chaîne | 4 octets + longueur de la chaîne (sans le '\0' final)
| str | Chaîne | 4 octets + longueur de la chaîne (sans le _\0_ final)
| buf | Tampon d'octets | 4 octets + longueur des données
| ptr | Pointeur | 1 octet + longueur du pointeur sous forme de chaîne
| tim | Date/heure | 1 octet + longueur de la date/heure sous forme de chaîne
@@ -1419,7 +1419,7 @@ long. '-' '1' '2' '3' '4' '5' '6' '7' '8' '9' '0'
==== Chaîne de caractères
Une chaîne de caractère est une longueur (un entier sur 4 octets) + le contenu
de la chaîne (sans le '\0' final).
de la chaîne (sans le _\0_ final).
Exemple :
@@ -1441,7 +1441,7 @@ Une chaîne vide a une longueur de zéro :
longueur
....
Une chaîne 'NULL' (pointeur NULL en C) a une longueur de -1 :
Une chaîne _NULL_ (pointeur NULL en C) a une longueur de -1 :
....
┌────┬────┬────┬────┐
@@ -1473,7 +1473,7 @@ Exemple :
long. '1' 'a' '2' 'b' '3' 'c' '4' 'd' '5'
....
Un pointeur 'NULL' a une longueur de 1 avec la valeur 0 :
Un pointeur _NULL_ a une longueur de 1 avec la valeur 0 :
....
┌────╥────┐
@@ -1526,7 +1526,7 @@ Exemple :
[[object_hdata]]
==== Hdata
Un 'hdata' contient un chemin avec les noms de hdata, une liste de clés, le
Un _hdata_ contient un chemin avec les noms de hdata, une liste de clés, le
nombre d'objets, et l'ensemble des objets (chemin avec les pointeurs, puis les
objets).
@@ -1540,19 +1540,19 @@ objets).
──╨────────┴─────────────────────╨─────┘
....
* 'h-path' (chaîne) : chemin utilise pour atteindre le hdata (exemple :
'buffer/lines/line/line_data'); le dernier élément du chemin est le hdata
* _h-path_ (chaîne) : chemin utilise pour atteindre le hdata (exemple :
_buffer/lines/line/line_data_); le dernier élément du chemin est le hdata
retourné
* 'keys' (chaînes) : chaîne avec une liste de 'clé:type' (séparés par des
virgules), exemple : 'number:int,name:str'
* 'count' (entier) : nombre d'objets
* 'p-path' : chemin avec les pointeurs vers les objets (le nombre de pointeurs
* _keys_ (chaînes) : chaîne avec une liste de _clé:type_ (séparés par des
virgules), exemple : _number:int,name:str_
* _count_ (entier) : nombre d'objets
* _p-path_ : chemin avec les pointeurs vers les objets (le nombre de pointeurs
ici est le nombre d'éléments dans le chemin)
* 'values' : liste de valeurs (le nombre de valeurs est le nombre de clés
* _values_ : liste de valeurs (le nombre de valeurs est le nombre de clés
retournées pour le hdata)
Exemple de hdata avec deux tampons (tampon "core" weechat et le serveur
freenode) et deux clés ('number' et 'full_name') :
freenode) et deux clés (_number_ et _full_name_) :
....
# commande
@@ -1649,7 +1649,7 @@ nicklist
[[object_info]]
==== Info
Une 'info' contient un nom et une valeur (les deux sont des chaînes de
Une _info_ contient un nom et une valeur (les deux sont des chaînes de
caractères).
....
@@ -1658,10 +1658,10 @@ caractères).
└──────┴───────┘
....
* 'nom' (chaîne) : nom de l'info
* 'value' (chaîne) : valeur
* _nom_ (chaîne) : nom de l'info
* _value_ (chaîne) : valeur
Exemple de l'info 'version' :
Exemple de l'info _version_ :
....
┌─────────┬───────────────────┐
@@ -1672,7 +1672,7 @@ Exemple de l'info 'version' :
[[object_infolist]]
==== Infolist
Une 'infolist' contient un nom, nombre d'éléments, et les éléments (ensemble de
Une _infolist_ contient un nom, nombre d'éléments, et les éléments (ensemble de
variables).
....
@@ -1689,13 +1689,13 @@ Un élément est :
└───────╨────────┴────────┴─────────╨─────╨────────┴────────┴─────────┘
....
* 'name' (chaîne) : nom de l'infolist ('buffer', 'window', 'bar', ...)
* 'count' (entier) : nombre d'éléments
* 'item' :
** 'count' : nombre de variables dans l'élément
** 'name' : nom de variable
** 'type' : type de variable ('int', 'str', ...)
** 'value' : valeur de la variable
* _name_ (chaîne) : nom de l'infolist (_buffer_, _window_, _bar_, ...)
* _count_ (entier) : nombre d'éléments
* _item_ :
** _count_ : nombre de variables dans l'élément
** _name_ : nom de variable
** _type_ : type de variable (_int_, _str_, ...)
** _value_ : valeur de la variable
Exemple d'infolist avec deux tampons (tampon "core" weechat et le serveur
freenode) :
@@ -1756,7 +1756,7 @@ Exemple de tableau avec trois entiers :
456 (0x1C8) 789 (0x315)
....
Un tableau 'NULL' :
Un tableau _NULL_ :
....
┌─────╥────┬────┬────┬────┐
doc/ja/weechat_relay_protocol.ja.asciidoc
+147 -147
View File
@@ -25,15 +25,15 @@
この文書では以下の用語を利用します:
* 'リレー': これは relay プラグインを備えた WeeChat を指し、"サーバ"
のように振る舞い、'クライアント' からの接続を受け付けます
* 'クライアント': これは他のソフトウェアのことを指し、ネットワークを介して 'リレー'
に接続します; 多くの場合、'クライアント' はリモートインターフェイスのことを指します。
* _リレー_: これは relay プラグインを備えた WeeChat を指し、"サーバ"
のように振る舞い、_クライアント_ からの接続を受け付けます
* _クライアント_: これは他のソフトウェアのことを指し、ネットワークを介して _リレー_
に接続します; 多くの場合、_クライアント_ はリモートインターフェイスのことを指します。
[[network_diagram]]
=== ネットワーク図
以下の図に示すように'クライアント' は'リレー' に接続しています:
以下の図に示すように_クライアント_ は_リレー_ に接続しています:
....
┌────────────────┐ ワークステーション
@@ -54,20 +54,20 @@
....
[NOTE]
この文書で述べる全てのクライアントは'リレー' プラグインの 'weechat' プロトコルを使っています。また'リレー'
プラグインは IRC クライアントからの接続を受け入れることができます、この場合'リレー'
プラグインは 'IRC プロキシ' のように振舞います (この文書では説明しません)。
この文書で述べる全てのクライアントは_リレー_ プラグインの _weechat_ プロトコルを使っています。また_リレー_
プラグインは IRC クライアントからの接続を受け入れることができます、この場合_リレー_
プラグインは _IRC プロキシ_ のように振舞います (この文書では説明しません)。
[[protocol_generalities]]
== プロトコルの一般的説明
* 'リレー' プラグインは新しい接続を受け入れるために IP/port をリッスンし、'クライアント'
は TCP ソケットを使って'リレー' に接続します。
* 'クライアント' の数はオプション 'relay.network.max_clients' で制限されています。
* それぞれの'クライアント' が自分以外のクライアントと協調して動くことはできません。
* 'クライアント' から'リレー' へのメッセージを'コマンド'
* _リレー_ プラグインは新しい接続を受け入れるために IP/port をリッスンし、_クライアント_
は TCP ソケットを使って_リレー_ に接続します。
* _クライアント_ の数はオプション _relay.network.max_clients_ で制限されています。
* それぞれの_クライアント_ が自分以外のクライアントと協調して動くことはできません。
* _クライアント_ から_リレー_ へのメッセージを_コマンド_
と呼び、これはテキスト形式 (文字列) で送信されます。
* 'リレー' から'クライアント' へのメッセージを'メッセージ'
* _リレー_ から_クライアント_ へのメッセージを_メッセージ_
と呼び、これはバイナリデータとして送信されます。
[[commands]]
@@ -77,11 +77,11 @@
フィールドは:
* 'id': 'リレー' からの応答に含まれる任意指定のメッセージ識別子;
* _id_: _リレー_ からの応答に含まれる任意指定のメッセージ識別子;
識別子は必ず括弧で括り、アンダースコア ("_") を最初につけるのは禁止されています
(アンダースコアが最初についている識別子は WeeChat 'event' メッセージ用に予約されています)
* 'command': コマンド (以下のテーブルを参照)
* 'arguments': コマンドに対する任意指定の引数
(アンダースコアが最初についている識別子は WeeChat _event_ メッセージ用に予約されています)
* _command_: コマンド (以下のテーブルを参照)
* _arguments_: コマンドに対する任意指定の引数
(複数の引数を渡す場合は空白で区切ってください)。
利用可能なコマンドのリスト (詳しくは次の章を参照):
@@ -89,23 +89,23 @@
[width="80%",cols="^3m,14",options="header"]
|===
| コマンド | 説明
| init | 'リレー' 接続を初期化
| hdata | 'hdata' を要求
| info | 'インフォ' を要求
| infolist | 'インフォリスト' を要求
| nicklist | 'ニックネームリスト' を要求
| init | _リレー_ 接続を初期化
| hdata | _hdata_ を要求
| info | _インフォ_ を要求
| infolist | _インフォリスト_ を要求
| nicklist | _ニックネームリスト_ を要求
| input | バッファにデータを送信 (テキストまたはコマンド)
| sync | バッファを同期 (バッファの最新情報を取得)
| desync | バッファを非同期 (バッファの更新を止める)
| quit | 'リレー' から切断
| quit | _リレー_ から切断
|===
[[command_init]]
=== init
'リレー' 接続を初期化。'リレー'
に送るコマンドは必ずこのコマンドから始めてください。'リレー'
がこのコマンドを受信していない場合、'リレー' は最初のコマンドを受け取った時点で警告無しに接続を閉じます。
_リレー_ 接続を初期化。_リレー_
に送るコマンドは必ずこのコマンドから始めてください。_リレー_
がこのコマンドを受信していない場合、_リレー_ は最初のコマンドを受け取った時点で警告無しに接続を閉じます。
構文:
@@ -115,15 +115,15 @@ init [<option>=<value>,[<option>=<value>,...]]
引数:
* 'option': 以下のうちの 1 つ:
** 'password': 'リレー' の認証用パスワード (WeeChat の
'relay.network.password' オプション)
** 'compression': 圧縮タイプ:
*** 'zlib': 'リレー' から受信するメッセージに対して 'zlib' 圧縮を使う
*** 'off': 圧縮を使わない
* _option_: 以下のうちの 1 つ:
** _password_: _リレー_ の認証用パスワード (WeeChat の
_relay.network.password_ オプション)
** _compression_: 圧縮タイプ:
*** _zlib_: _リレー_ から受信するメッセージに対して _zlib_ 圧縮を使う
*** _off_: 圧縮を使わない
[NOTE]
'リレー' が 'zlib' 圧縮をサポートする場合、'zlib' 圧縮はデフォルトで有効化されます。
_リレー_ が _zlib_ 圧縮をサポートする場合、_zlib_ 圧縮はデフォルトで有効化されます。
例:
@@ -138,7 +138,7 @@ init password=mypass,compression=off
[[command_hdata]]
=== hdata
'hdata' を要求。
_hdata_ を要求。
構文:
@@ -148,14 +148,14 @@ init password=mypass,compression=off
引数:
* 'path': hdata へのパス、書式: "hdata:pointer/var/var/.../var"、最後の
* _path_: hdata へのパス、書式: "hdata:pointer/var/var/.../var"、最後の
var に対応する hdata が返されます:
** 'hdata': hdata の名前
** 'pointer': ポインタ ("0x12345") またはリスト名 (例: "gui_buffers")
** _hdata_: hdata の名前
** _pointer_: ポインタ ("0x12345") またはリスト名 (例: "gui_buffers")
(番号も可能、以下を参照)
** 'var': 親 hdata に含まれる変数名 (パスで言う 1 つ前の名前)
** _var_: 親 hdata に含まれる変数名 (パスで言う 1 つ前の名前)
(番号も可能、以下を参照)
* 'keys': hdata で返すキーのコンマ区切りリスト
* _keys_: hdata で返すキーのコンマ区切りリスト
(指定しなかった場合、全てのキーが返されます。強大な hdata 構造体の場合全てのキーを返すことはお勧めしません)
ポインタと変数の後に番号を指定することができます。書式は
@@ -163,7 +163,7 @@ init password=mypass,compression=off
* 正数: N 回次の要素への反復を繰り返す
* 負数: N 回前の要素への反復を繰り返す
* '*': 最後の要素まで、次の要素への反復を繰り返す
* _*_: 最後の要素まで、次の要素への反復を繰り返す
例:
@@ -183,7 +183,7 @@ hdata buffer:gui_buffers full_name
[[command_info]]
=== info
'インフォ' を要求。
_インフォ_ を要求。
構文:
@@ -193,7 +193,7 @@ hdata buffer:gui_buffers full_name
引数:
* 'name': 読み出すインフォの名前
* _name_: 読み出すインフォの名前
例:
@@ -204,7 +204,7 @@ info version
[[command_infolist]]
=== infolist
'インフォリスト' を要求。
_インフォリスト_ を要求。
[IMPORTANT]
インフォリストの内容は実際のデータの複製です。可能な限り <<command_hdata,hdata>>
@@ -219,9 +219,9 @@ info version
引数:
* 'name': 取得するインフォリストの名前
* 'pointer': ポインタ (任意)
* 'arguments': 引数 (任意)
* _name_: 取得するインフォリストの名前
* _pointer_: ポインタ (任意)
* _arguments_: 引数 (任意)
例:
@@ -232,7 +232,7 @@ infolist buffer
[[command_nicklist]]
=== nicklist
1 つまたは全てのバッファから'ニックネームリスト' を要求。
1 つまたは全てのバッファから_ニックネームリスト_ を要求。
構文:
@@ -242,8 +242,8 @@ infolist buffer
引数:
* 'buffer': ポインタ ('0x12345') またはバッファの完全な名前 (例:
'core.weechat' または 'irc.freenode.#weechat')
* _buffer_: ポインタ (_0x12345_) またはバッファの完全な名前 (例:
_core.weechat_ または _irc.freenode.#weechat_)
例:
@@ -268,9 +268,9 @@ input <buffer> <data>
引数:
* 'buffer': ポインタ ('0x12345') またはバッファの完全な名前 (例:
'core.weechat' または 'irc.freenode.#weechat')
* 'data': バッファに送信するデータ: '/'
* _buffer_: ポインタ (_0x12345_) またはバッファの完全な名前 (例:
_core.weechat_ または _irc.freenode.#weechat_)
* _data_: バッファに送信するデータ: `/`
で始まる場合、バッファ内でコマンドとして実行されます、それ以外の場合、テキストはバッファの入力として送信されます。
例:
@@ -300,21 +300,21 @@ sync [<buffer>[,<buffer>...] <option>[,<option>...]]
引数:
* 'buffer': ポインタ ('0x12345') またはバッファの完全な名前 (例:
'core.weechat' または 'irc.freenode.#weechat');
* _buffer_: ポインタ (_0x12345_) またはバッファの完全な名前 (例:
_core.weechat_ または _irc.freenode.#weechat_);
全てのバッファを指定するには "*" を使ってください
* 'options': 以下に挙げるキーワード、コンマ区切り ("*" に対するデフォルトは
'buffers,upgrade,buffer,nicklist' 、バッファに対するデフォルトは 'buffer,nicklist'):
** 'buffers': バッファに関するシグナルを受け取る
* _options_: 以下に挙げるキーワード、コンマ区切り ("*" に対するデフォルトは
_buffers,upgrade,buffer,nicklist_ 、バッファに対するデフォルトは _buffer,nicklist_):
** _buffers_: バッファに関するシグナルを受け取る
(オープン/クローズ、移動、リネーム、マージ/アンマージ、隠す/隠さない); これは名前が "*" の場合のみ利用可能
_(WeeChat バージョン 0.4.1 以上で利用可)_
** 'upgrade': WeeChat アップグレードに関するシグナルを受信 (アップグレード、アップグレードの終了);
** _upgrade_: WeeChat アップグレードに関するシグナルを受信 (アップグレード、アップグレードの終了);
名前が "*" のバッファに対してのみ利用可能
_(WeeChat バージョン 0.4.1 以上で利用可)_
** 'buffer': バッファに関するシグナルを受信
(新しい行、型の変更、タイトルの変更、ローカル変数の追加/削除、'buffers'
** _buffer_: バッファに関するシグナルを受信
(新しい行、型の変更、タイトルの変更、ローカル変数の追加/削除、_buffers_
と同じバッファに関するシグナル) _(WeeChat バージョン 0.4.1 で更新)_
** 'nicklist': 変更後にニックネームリストを受信
** _nicklist_: 変更後にニックネームリストを受信
例:
@@ -345,7 +345,7 @@ _WeeChat バージョン 0.4.1 で更新。_
更新を中止して 1 つまたは複数のバッファの同期を中止。
[NOTE]
バッファの'オプション'
バッファの_オプション_
を削除します。バッファに対する一部のオプションがまだ有効な場合、クライアントはバッファに対するアップデートを受け取ります。
構文:
@@ -356,11 +356,11 @@ desync [<buffer>[,<buffer>...] <option>[,<option>...]]
引数:
* 'buffer': ポインタ ('0x12345') またはバッファの完全な名前 (例:
'core.weechat' または 'irc.freenode.#weechat');
* _buffer_: ポインタ (_0x12345_) またはバッファの完全な名前 (例:
_core.weechat_ または _irc.freenode.#weechat_);
全てのバッファを指定するには "*" を使ってください
* 'options': 以下に挙げるキーワード、コンマ区切り ("*" に対するデフォルトは
'buffers,upgrade,buffer,nicklist' 、バッファに対するデフォルトは 'buffer,nicklist'):
* _options_: 以下に挙げるキーワード、コンマ区切り ("*" に対するデフォルトは
_buffers,upgrade,buffer,nicklist_ 、バッファに対するデフォルトは _buffer,nicklist_):
値に関する詳しい情報は <<command_sync,sync コマンド>>をご覧ください
[NOTE]
@@ -458,7 +458,7 @@ ping 1370802127000
[[command_quit]]
=== quit
'リレー' から切断。
_リレー_ から切断。
構文:
@@ -489,37 +489,37 @@ quit
'length' バイト
....
* 'length' (符号なし整数型): メッセージ全体のバイト数
* _length_ (符号なし整数型): メッセージ全体のバイト数
(このフィールドを含む)
* 'compression' (バイト型): フラグ:
** '0x00': これ以降のデータは圧縮されていません
** '0x01': これ以降のデータは 'zlib' で圧縮されています
* 'id' (文字列型): クライアントが送信した識別子 (コマンド名の前につけられる);
* _compression_ (バイト型): フラグ:
** _0x00_: これ以降のデータは圧縮されていません
** _0x01_: これ以降のデータは _zlib_ で圧縮されています
* _id_ (文字列型): クライアントが送信した識別子 (コマンド名の前につけられる);
コマンドに識別子が含まれない場合は空文字列でも可
(内容を含まない長さゼロの文字列)
* 'type' (3 文字): 型の種類: 3 文字 (以下の表を参照)
* 'object': オブジェクト (以下の表を参照)
* _type_ (3 文字): 型の種類: 3 文字 (以下の表を参照)
* _object_: オブジェクト (以下の表を参照)
[[message_compression]]
=== 圧縮
'compression' フラグが 0x01 の場合、これ以降の*全ての* データは 'zlib'
_compression_ フラグが 0x01 の場合、これ以降の*全ての* データは _zlib_
で圧縮されているため、処理前に必ず展開してください。
[[message_identifier]]
=== 識別子
識別子 ('id') には 2 種類あります:
識別子 (_id_) には 2 種類あります:
* 'クライアント' が送信する 'id': 'リレー' は 'id' を含む受信メッセージに対して同じ 'id' を付けて応答します。
* イベントの 'id': 一部のイベントで、'リレー' は 'クライアント' に向けて特別な、アンダースコアで始まる、'id'
* _クライアント_ が送信する _id_: _リレー_ は _id_ を含む受信メッセージに対して同じ _id_ を付けて応答します。
* イベントの _id_: 一部のイベントで、_リレー_ は _クライアント_ に向けて特別な、アンダースコアで始まる、_id_
を含むメッセージを送信します (以下の表を参照)
WeeChat の予約識別子:
[width="100%",cols="5,5,3,4,7",options="header"]
|===
| 識別子 | 'sync' で受信 | 送信されるデータ |
| 識別子 | _sync_ で受信 | 送信されるデータ |
説明 | 推奨するクライアントの挙動
| _buffer_opened | buffers / buffer | hdata: buffer |
@@ -595,8 +595,8 @@ hdata として送られるデータ:
|===
| 名前 | 型 | 説明
| number | integer | バッファ番号 (1 以上)
| full_name | string | 完全な名前 (例: 'irc.freenode.#weechat')
| short_name | string | 短い名前 (例: '#weechat')
| full_name | string | 完全な名前 (例: _irc.freenode.#weechat_)
| short_name | string | 短い名前 (例: _#weechat_)
| nicklist | integer | バッファがニックネームリストを持つ場合 1、それ以外は 0
| title | string | バッファのタイトル
| local_variables | hashtable | ローカル変数
@@ -604,8 +604,8 @@ hdata として送られるデータ:
| next_buffer | pointer | 次のバッファへのポインタ
|===
例: freenode の '#weechat' チャンネルに参加、新しいバッファは
'irc.freenode.#weechat':
例: freenode の _#weechat_ チャンネルに参加、新しいバッファは
_irc.freenode.#weechat_:
[source,python]
----
@@ -638,12 +638,12 @@ hdata として送られるデータ:
|===
| 名前 | 型 | 説明
| number | integer | バッファ番号 (1 以上)
| full_name | string | 完全な名前 (例: 'irc.freenode.#weechat')
| full_name | string | 完全な名前 (例: _irc.freenode.#weechat_)
| prev_buffer | pointer | 前のバッファへのポインタ
| next_buffer | pointer | 次のバッファへのポインタ
|===
例: バッファ 'irc.freenode.#weechat' を番号 2 に移動:
例: バッファ _irc.freenode.#weechat_ を番号 2 に移動:
[source,python]
----
@@ -671,12 +671,12 @@ hdata として送られるデータ:
|===
| 名前 | 型 | 説明
| number | integer | バッファ番号 (1 以上)
| full_name | string | 完全な名前 (例: 'irc.freenode.#weechat')
| full_name | string | 完全な名前 (例: _irc.freenode.#weechat_)
| prev_buffer | pointer | 前のバッファへのポインタ
| next_buffer | pointer | 次のバッファへのポインタ
|===
例: バッファ 'irc.freenode.#weechat' をバッファ #2 とマージ:
例: バッファ _irc.freenode.#weechat_ をバッファ #2 とマージ:
[source,python]
----
@@ -704,12 +704,12 @@ hdata として送られるデータ:
|===
| 名前 | 型 | 説明
| number | integer | バッファ番号 (1 以上)
| full_name | string | 完全な名前 (例: 'irc.freenode.#weechat')
| full_name | string | 完全な名前 (例: _irc.freenode.#weechat_)
| prev_buffer | pointer | 前のバッファへのポインタ
| next_buffer | pointer | 次のバッファへのポインタ
|===
例: バッファ 'irc.freenode.#weechat' をアンマージ:
例: バッファ _irc.freenode.#weechat_ をアンマージ:
[source,python]
----
@@ -739,12 +739,12 @@ hdata として送られるデータ:
|===
| 名前 | 型 | 説明
| number | integer | バッファ番号 (1 以上)
| full_name | string | 完全な名前 (例: 'irc.freenode.#weechat')
| full_name | string | 完全な名前 (例: _irc.freenode.#weechat_)
| prev_buffer | pointer | 前のバッファへのポインタ
| next_buffer | pointer | 次のバッファへのポインタ
|===
例: バッファ 'irc.freenode.#weechat' を隠す:
例: バッファ _irc.freenode.#weechat_ を隠す:
[source,python]
----
@@ -774,12 +774,12 @@ hdata として送られるデータ:
|===
| 名前 | 型 | 説明
| number | integer | バッファ番号 (1 以上)
| full_name | string | 完全な名前 (例: 'irc.freenode.#weechat')
| full_name | string | 完全な名前 (例: _irc.freenode.#weechat_)
| prev_buffer | pointer | 前のバッファへのポインタ
| next_buffer | pointer | 次のバッファへのポインタ
|===
例: バッファ 'irc.freenode.#weechat' を隠すことを止める:
例: バッファ _irc.freenode.#weechat_ を隠すことを止める:
[source,python]
----
@@ -807,12 +807,12 @@ hdata として送られるデータ:
|===
| 名前 | 型 | 説明
| number | integer | バッファ番号 (1 以上)
| full_name | string | 完全な名前 (例: 'irc.freenode.#weechat')
| short_name | string | 短い名前 (例: '#weechat')
| full_name | string | 完全な名前 (例: _irc.freenode.#weechat_)
| short_name | string | 短い名前 (例: _#weechat_)
| local_variables | hashtable | ローカル変数
|===
例: プライベートバッファを 'FlashCode' から 'Flash2' にリネーム:
例: プライベートバッファを _FlashCode_ から _Flash2_ にリネーム:
[source,python]
----
@@ -841,11 +841,11 @@ hdata として送られるデータ:
|===
| 名前 | 型 | 説明
| number | integer | バッファ番号 (1 以上)
| full_name | string | 完全な名前 (例: 'irc.freenode.#weechat')
| full_name | string | 完全な名前 (例: _irc.freenode.#weechat_)
| title | string | バッファのタイトル
|===
例: チャンネル '#weechat' のトピックを変更:
例: チャンネル _#weechat_ のトピックを変更:
[source,python]
----
@@ -874,10 +874,10 @@ hdata として送られるデータ:
|===
| 名前 | 型 | 説明
| number | integer | バッファ番号 (1 以上)
| full_name | string | 完全な名前 (例: 'irc.freenode.#weechat')
| full_name | string | 完全な名前 (例: _irc.freenode.#weechat_)
|===
例: バッファ 'irc.freenode.#weechat' をクリア:
例: バッファ _irc.freenode.#weechat_ をクリア:
[source,python]
----
@@ -903,11 +903,11 @@ hdata として送られるデータ:
|===
| 名前 | 型 | 説明
| number | integer | バッファ番号 (1 以上)
| full_name | string | 完全な名前 (例: 'irc.freenode.#weechat')
| full_name | string | 完全な名前 (例: _irc.freenode.#weechat_)
| type | integer | バッファの種類: 0 = 書式あり (デフォルト)、1 = 自由内容
|===
例: バッファ 'script.scripts' の種類を書式あり (0) から自由内容
例: バッファ _script.scripts_ の種類を書式あり (0) から自由内容
(1) に変更:
[source,python]
@@ -935,11 +935,11 @@ hdata として送られるデータ:
|===
| 名前 | 型 | 説明
| number | integer | バッファ番号 (1 以上)
| full_name | string | 完全な名前 (例: 'irc.freenode.#weechat')
| full_name | string | 完全な名前 (例: _irc.freenode.#weechat_)
| local_variables | hashtable | ローカル変数
|===
例: 'irc.freenode.#weechat' にローカル変数 'test' を追加:
例: _irc.freenode.#weechat_ にローカル変数 _test_ を追加:
[source,python]
----
@@ -968,11 +968,11 @@ hdata として送られるデータ:
|===
| 名前 | 型 | 説明
| number | integer | バッファ番号 (1 以上)
| full_name | string | 完全な名前 (例: 'irc.freenode.#weechat')
| full_name | string | 完全な名前 (例: _irc.freenode.#weechat_)
| local_variables | hashtable | ローカル変数
|===
例: 'irc.freenode.#weechat' に含まれるローカル変数 'test' を更新:
例: _irc.freenode.#weechat_ に含まれるローカル変数 _test_ を更新:
[source,python]
----
@@ -1001,11 +1001,11 @@ hdata として送られるデータ:
|===
| 名前 | 型 | 説明
| number | integer | バッファ番号 (1 以上)
| full_name | string | 完全な名前 (例: 'irc.freenode.#weechat')
| full_name | string | 完全な名前 (例: _irc.freenode.#weechat_)
| local_variables | hashtable | ローカル変数
|===
例: 'irc.freenode.#weechat' からローカル変数 'test' を削除:
例: _irc.freenode.#weechat_ からローカル変数 _test_ を削除:
[source,python]
----
@@ -1042,7 +1042,7 @@ hdata として送られるデータ:
| message | string | メッセージ
|===
例: バッファ 'irc.freenode.#weechat' でニックネーム 'FlashCode' からの新しいメッセージ 'hello!':
例: バッファ _irc.freenode.#weechat_ でニックネーム _FlashCode_ からの新しいメッセージ _hello!_:
[source,python]
----
@@ -1075,10 +1075,10 @@ hdata として送られるデータ:
|===
| 名前 | 型 | 説明
| number | integer | バッファ番号 (1 以上)
| full_name | string | 完全な名前 (例: 'irc.freenode.#weechat')
| full_name | string | 完全な名前 (例: _irc.freenode.#weechat_)
|===
例: WeeChat がバッファ 'irc.freenode.#weechat' を閉じる:
例: WeeChat がバッファ _irc.freenode.#weechat_ を閉じる:
[source,python]
----
@@ -1099,7 +1099,7 @@ hda:
が行われた場合にクライアントに送られます。このメッセージには完全なニックネームリストが含まれます。
ニックネームリストに対して小さな更新が行われた場合 (例えばニックネームを 1
つだけ追加)、識別子 '_nicklist_diff' を含むメッセージが送信されます (以下を参照)。
つだけ追加)、識別子 __nicklist_diff_ を含むメッセージが送信されます (以下を参照)。
hdata として送られるデータ:
@@ -1115,7 +1115,7 @@ hdata として送られるデータ:
| prefix_color | string | プレフィックスの色 (ニックネーム専用)
|===
例: バッファ 'irc.freenode.#weechat' のニックネームリスト:
例: バッファ _irc.freenode.#weechat_ のニックネームリスト:
[source,python]
----
@@ -1204,7 +1204,7 @@ hdata として送られるデータ:
| prefix_color | string | プレフィックスの色 (ニックネーム専用)
|===
'_diff' のとりうる値:
__diff_ のとりうる値:
* `^`: 親グループ:
これの後に続くグループまたはニックネームに関する操作はこのグループに対して行う
@@ -1212,8 +1212,8 @@ hdata として送られるデータ:
* `-`: このグループおよびニックネームを親グループから削除
* `*`: このグループおよびニックネームを親グループで更新
例: ニックネーム 'master' を '000|o' (IRC チャンネルのチャンネルオペレータ)
グループに追加、ニックネーム 'nick1' と 'nick2' を '999|...' に追加
例: ニックネーム _master_ を _000|o_ (IRC チャンネルのチャンネルオペレータ)
グループに追加、ニックネーム _nick1_ と _nick2_ を _999|..._ に追加
(IRC チャンネルの一般ユーザ):
[source,python]
@@ -1280,7 +1280,7 @@ hda:
_WeeChat バージョン 0.4.2 以上で利用可。_
このメッセージは 'リレー' が "ping" メッセージを受信する際にクライアントに送られます。
このメッセージは _リレー_ が "ping" メッセージを受信する際にクライアントに送られます。
文字列として送られるデータ: "ping" メッセージで受信した引数。
@@ -1296,7 +1296,7 @@ _WeeChat バージョン 0.3.8 以上で利用可。_
メッセージにデータは含まれません。
クライアントは WeeChat との同期を中止するか
('desync' コマンドを送信)、WeeChat から切断することを推奨します
(_desync_ コマンドを送信)、WeeChat から切断することを推奨します
(これはアップグレードの後はすべてのポインタが変わるからです)。
[NOTE]
@@ -1314,12 +1314,12 @@ _WeeChat バージョン 0.3.8 以上で利用可。_
メッセージにデータは含まれません。
クライアントは WeeChat との同期を再開することを推奨します:
クライアントを開始して 'init' 以降に送信したすべてのコマンドを再送信。
クライアントを開始して _init_ 以降に送信したすべてのコマンドを再送信。
[[objects]]
=== オブジェクト
オブジェクトは 'type' と呼ばれる 3 文字で特定されます。以下の種類が使われます:
オブジェクトは _type_ と呼ばれる 3 文字で特定されます。以下の種類が使われます:
[width="100%",cols="^2m,5,10",options="header"]
|===
@@ -1327,7 +1327,7 @@ _WeeChat バージョン 0.3.8 以上で利用可。_
| chr | 符号付文字 | 1 バイト
| int | 符号付整数 | 4 バイト
| lon | 符号付長整数 | 1 バイト + 文字列で表現した整数の長さ
| str | 文字列 | 4 バイト + 文字列の長さ (最後の '\0' を含まない)
| str | 文字列 | 4 バイト + 文字列の長さ (最後の _\0_ を含まない)
| buf | バッファのバイト数 | 4 バイト + データの長さ
| ptr | ポインタ | 1 バイト + 文字列で表現したポインタの長さ
| tim | 時間 | 1 バイト + 文字列で表現した時間の長さ
@@ -1397,7 +1397,7 @@ length '-' '1' '2' '3' '4' '5' '6' '7' '8' '9' '0'
[[object_string]]
==== 文字列
1 つの文字列はその長さ (4 バイト表現した整数) + 文字列の内容 (最後の '\0' を除く) で表現されています。
1 つの文字列はその長さ (4 バイト表現した整数) + 文字列の内容 (最後の _\0_ を除く) で表現されています。
例:
@@ -1419,7 +1419,7 @@ length '-' '1' '2' '3' '4' '5' '6' '7' '8' '9' '0'
length
....
'NULL' 文字列 (C 言語の NULL ポインタ) を表現するにはの長さを -1 にしてください:
_NULL_ 文字列 (C 言語の NULL ポインタ) を表現するにはの長さを -1 にしてください:
....
┌────┬────┬────┬────┐
@@ -1449,7 +1449,7 @@ length '-' '1' '2' '3' '4' '5' '6' '7' '8' '9' '0'
length '1' 'a' '2' 'b' '3' 'c' '4' 'd' '5'
....
'NULL' ポインタを表現するには長さを 1 で値を 0 にしてください:
_NULL_ ポインタを表現するには長さを 1 で値を 0 にしてください:
....
┌────╥────┐
@@ -1500,7 +1500,7 @@ length '1' '3' '2' '1' '9' '9' '3' '4' '5' '6'
[[object_hdata]]
==== Hdata
1 つの 'hdata' には hdata 名を含むパス、キーのリスト、オブジェクトセットの数、オブジェクトセット
1 つの _hdata_ には hdata 名を含むパス、キーのリスト、オブジェクトセットの数、オブジェクトセット
(ポインタのパス、オブジェクト) が含まれています。
....
@@ -1513,18 +1513,18 @@ length '1' '3' '2' '1' '9' '9' '3' '4' '5' '6'
──╨────────┴─────────────────────╨─────┘
....
* 'h-path' (文字列): hdata にアクセスする際に使うパス (例:
'buffer/lines/line/line_data'); 返される hdata はパスの最後の要素です
* 'keys' (文字列): 'key:type' のリスト (コンマ区切り)
を含む文字列、例: 'number:int,name:str'
* 'count' (文字列): オブジェクトセットの数
* 'p-path': オブジェクトへのポインタを含むパス
* _h-path_ (文字列): hdata にアクセスする際に使うパス (例:
_buffer/lines/line/line_data_); 返される hdata はパスの最後の要素です
* _keys_ (文字列): _key:type_ のリスト (コンマ区切り)
を含む文字列、例: _number:int,name:str_
* _count_ (文字列): オブジェクトセットの数
* _p-path_: オブジェクトへのポインタを含むパス
(ポインタの数はパスに含まれる要素の数)
* 'values': 値のリスト (値の数は hdata
* _values_: 値のリスト (値の数は hdata
で返されるキーの数)
2 つのバッファ (weechat コアと freenode サーバ) と
2 つのキー ('number' と 'full_name') を持つ hdata の例:
2 つのキー (_number_ と _full_name_) を持つ hdata の例:
....
# コマンド
@@ -1621,7 +1621,7 @@ nicklist
[[object_info]]
==== インフォ
1 つの'インフォ' は名前と値を含んでいます (両方とも文字列)。
1 つの_インフォ_ は名前と値を含んでいます (両方とも文字列)。
....
┌──────┬───────┐
@@ -1629,10 +1629,10 @@ nicklist
└──────┴───────┘
....
* 'name' (文字列): インフォの名前
* 'value' (文字列): 値
* _name_ (文字列): インフォの名前
* _value_ (文字列): 値
'version' インフォの例:
_version_ インフォの例:
....
┌─────────┬───────────────────┐
@@ -1643,7 +1643,7 @@ nicklist
[[object_infolist]]
==== インフォリスト
1 つの'インフォリスト' は名前、要素の数、要素
1 つの_インフォリスト_ は名前、要素の数、要素
(変数のセット) を含んでいます。
....
@@ -1660,13 +1660,13 @@ nicklist
└───────╨────────┴────────┴─────────╨─────╨────────┴────────┴─────────┘
....
* 'name' (文字列): インフォリストの名前 ('buffer' 、'window' 、'bar' 、...)
* 'count' (整数): 要素の数
* 'item':
** 'count': 要素に含まれる変数の数
** 'name': 変数の名前
** 'type': 変数の型 ('int' 、'str' 、...)
** 'value': 変数の値
* _name_ (文字列): インフォリストの名前 (_buffer_ 、_window_ 、_bar_ 、...)
* _count_ (整数): 要素の数
* _item_:
** _count_: 要素に含まれる変数の数
** _name_: 変数の名前
** _type_: 変数の型 (_int_ 、_str_ 、...)
** _value_: 変数の値
2 つのバッファ (weechat コアと freenode サーバ) を持つインフォリストの例:
@@ -1725,7 +1725,7 @@ infolist buffer
456 (0x1C8) 789 (0x315)
....
'NULL' 配列:
_NULL_ 配列:
....
┌─────╥────┬────┬────┬────┐