From 944972bc951c03605fbd7a9fd3236e63cfd0fd6d Mon Sep 17 00:00:00 2001 From: Sebastien Helleu Date: Mon, 3 Feb 2014 15:41:33 +0100 Subject: doc: add French version of relay protocol --- doc/en/CMakeLists.txt | 22 +- doc/en/Makefile.am | 6 +- doc/en/weechat_relay_protocol.en.txt | 373 ++++---- doc/fr/CMakeLists.txt | 11 + doc/fr/Makefile.am | 6 + doc/fr/weechat_relay_protocol.fr.txt | 1704 ++++++++++++++++++++++++++++++++++ 6 files changed, 1943 insertions(+), 179 deletions(-) create mode 100644 doc/fr/weechat_relay_protocol.fr.txt (limited to 'doc') diff --git a/doc/en/CMakeLists.txt b/doc/en/CMakeLists.txt index cab89a174..a25eabb06 100644 --- a/doc/en/CMakeLists.txt +++ b/doc/en/CMakeLists.txt @@ -104,17 +104,6 @@ IF(ENABLE_DOC AND SOURCEHIGHLIGHT_FOUND) ADD_CUSTOM_TARGET(doc-tester-en ALL DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/weechat_tester.en.html) INSTALL(FILES ${CMAKE_CURRENT_BINARY_DIR}/weechat_tester.en.html DESTINATION ${SHAREDIR}/doc/${PROJECT_NAME}) - # developer's guide - ADD_CUSTOM_COMMAND( - OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/weechat_dev.en.html - COMMAND ${ASCIIDOC_EXECUTABLE} ARGS -a revision="${VERSION}" -a stylesheet=${CMAKE_CURRENT_SOURCE_DIR}/../asciidoc.css -f ${CMAKE_CURRENT_SOURCE_DIR}/../asciidoc.conf -n -o ${CMAKE_CURRENT_BINARY_DIR}/weechat_dev.en.html ${CMAKE_CURRENT_SOURCE_DIR}/weechat_dev.en.txt - DEPENDS - ${CMAKE_CURRENT_SOURCE_DIR}/weechat_dev.en.txt - COMMENT "Building weechat_dev.en.html" - ) - ADD_CUSTOM_TARGET(doc-dev-en ALL DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/weechat_dev.en.html) - INSTALL(FILES ${CMAKE_CURRENT_BINARY_DIR}/weechat_dev.en.html DESTINATION ${SHAREDIR}/doc/${PROJECT_NAME}) - # relay protocol ADD_CUSTOM_COMMAND( OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/weechat_relay_protocol.en.html @@ -126,4 +115,15 @@ IF(ENABLE_DOC AND SOURCEHIGHLIGHT_FOUND) ADD_CUSTOM_TARGET(doc-relay-protocol-en ALL DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/weechat_relay_protocol.en.html) INSTALL(FILES ${CMAKE_CURRENT_BINARY_DIR}/weechat_relay_protocol.en.html DESTINATION ${SHAREDIR}/doc/${PROJECT_NAME}) + # developer's guide + ADD_CUSTOM_COMMAND( + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/weechat_dev.en.html + COMMAND ${ASCIIDOC_EXECUTABLE} ARGS -a revision="${VERSION}" -a stylesheet=${CMAKE_CURRENT_SOURCE_DIR}/../asciidoc.css -f ${CMAKE_CURRENT_SOURCE_DIR}/../asciidoc.conf -n -o ${CMAKE_CURRENT_BINARY_DIR}/weechat_dev.en.html ${CMAKE_CURRENT_SOURCE_DIR}/weechat_dev.en.txt + DEPENDS + ${CMAKE_CURRENT_SOURCE_DIR}/weechat_dev.en.txt + COMMENT "Building weechat_dev.en.html" + ) + ADD_CUSTOM_TARGET(doc-dev-en ALL DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/weechat_dev.en.html) + INSTALL(FILES ${CMAKE_CURRENT_BINARY_DIR}/weechat_dev.en.html DESTINATION ${SHAREDIR}/doc/${PROJECT_NAME}) + ENDIF(ENABLE_DOC AND SOURCEHIGHLIGHT_FOUND) diff --git a/doc/en/Makefile.am b/doc/en/Makefile.am index 3bb2d8e99..a8817706b 100644 --- a/doc/en/Makefile.am +++ b/doc/en/Makefile.am @@ -29,8 +29,8 @@ EXTRA_DIST = CMakeLists.txt \ weechat_faq.en.txt \ weechat_quickstart.en.txt \ weechat_tester.en.txt \ - weechat_dev.en.txt \ weechat_relay_protocol.en.txt \ + weechat_dev.en.txt \ $(wildcard autogen/user/*.txt) \ $(wildcard autogen/plugin_api/*.txt) @@ -46,8 +46,8 @@ if DOC weechat_faq.en.html \ weechat_quickstart.en.html \ weechat_tester.en.html \ - weechat_dev.en.html \ - weechat_relay_protocol.en.html + weechat_relay_protocol.en.html \ + weechat_dev.en.html doc_install = install-doc doc_uninstall = uninstall-doc endif diff --git a/doc/en/weechat_relay_protocol.en.txt b/doc/en/weechat_relay_protocol.en.txt index 1640b95d3..6efbe5be8 100644 --- a/doc/en/weechat_relay_protocol.en.txt +++ b/doc/en/weechat_relay_protocol.en.txt @@ -6,7 +6,7 @@ :toclevels: 4 -This document is the specification of WeeChat relay protocol: the protocol used +This document is the specification of WeeChat Relay protocol: the protocol used to relay WeeChat data to clients, which are mostly remote interfaces. @@ -21,7 +21,7 @@ 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 + connection; in most cases, this 'client' is a remote interface. [[network_diagram]] === Network diagram @@ -49,15 +49,14 @@ 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). +'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 - (option 'relay.port.weechat' in WeeChat). -* Number of 'clients' is not limited. + 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). @@ -76,7 +75,7 @@ Fields are: ("_") (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) + spaces). List of available commands (detail in next chapters): @@ -84,10 +83,10 @@ List of available commands (detail in next chapters): |=== | Command | Description | init | Initialize connection with 'relay' -| hdata | Request hdata -| info | Request info -| infolist | Request infolist -| nicklist | Request nicklist +| 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)) @@ -113,11 +112,11 @@ Arguments: ** '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' +*** '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 hdata. +Request a 'hdata'. Syntax: @@ -149,9 +148,8 @@ Arguments: (count allowed, see below) ** '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 returned (if not - specified, all keys are returned, which is not recommended on large hdata - structures) +* '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 values are: @@ -164,21 +162,21 @@ Examples: ---- # request all buffers, hdata of type "buffer" is returned -# keys number and name are returned for each buffer +# keys "number" and "name" are returned for each buffer hdata buffer:gui_buffers(*) number,name # request all lines of all buffers, hdata of type "line_data" is returned # all keys are returned hdata buffer:gui_buffers(*)/lines/first_line(*)/data -# request full_name of first buffer +# request full name of first buffer hdata buffer:gui_buffers full_name ---- [[command_info]] === info -Request info. +Request an 'info'. Syntax: @@ -199,7 +197,7 @@ info version [[command_infolist]] === infolist -Request infolist. +Request an 'infolist'. [IMPORTANT] Content of infolist is a duplication of actual data. Wherever possible, use @@ -209,13 +207,14 @@ faster, uses less memory and returns smaller objects in message). Syntax: ---- -(id) infolist +(id) infolist [ []] ---- Arguments: * 'name': name of infolist to retrieve -* 'arguments': arguments for infolist +* 'pointer': pointer (optional) +* 'arguments': arguments (optional) Example: @@ -226,7 +225,7 @@ infolist buffer [[command_nicklist]] === nicklist -Request nicklist, for one or all buffers. +Request a 'nicklist', for one or all buffers. Syntax: @@ -284,7 +283,7 @@ Synchronize one or more buffers, to get updates. [IMPORTANT] It is recommended to send this command immediately after you asked data for buffers (lines, ...). It can be send in same message (after a new -line). +line char: "\n"). Syntax: @@ -300,14 +299,14 @@ Arguments: * '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, renamed); this can be used only with name "*" - _(new in version 0.4.1)_ + merged/unmerged); this can be used only with name "*" + _(WeeChat ≥ 0.4.1)_ ** 'upgrade': receive signals about WeeChat upgrade (upgrade, upgrade ended); this can be used only with name "*" - _(new in version 0.4.1)_ + _(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) _(updated in version 0.4.1)_ + changed, local variable added/removed, and same signals as 'buffers' for the + buffer) _(updated in version 0.4.1)_ ** 'nicklist': receive nicklist after changes Examples: @@ -340,7 +339,7 @@ Desynchronize one or more buffers, to stop updates. [NOTE] This will remove 'options' for buffers. If some options are still active for -buffers, the client will still receive updates for buffers. +buffers, the client will still receive updates for these buffers. Syntax: @@ -355,7 +354,7 @@ Arguments: specify all buffers * 'options': one of following keywords, separated by commas (default is 'buffers,upgrade,buffer,nicklist' for "*" and 'buffer,nicklist' for a buffer); - see <> for values. + see <> for values [NOTE] When using buffer "*", the other buffers synchronized (using a name) are kept. + @@ -385,11 +384,12 @@ desync irc.freenode.#weechat Test command: WeeChat will reply with various different objects. -This command is useful to test the decoding of objects returned by WeeChat. +This command is useful to test the decoding of binary objects returned by +WeeChat. [IMPORTANT] You must not use the pointer values returned by this command, they are not -valid. This command should only be used to test decoding of a message sent by +valid. This command must be used only to test decoding of a message sent by WeeChat. Syntax: @@ -422,19 +422,19 @@ Returned objects (in this order): | pointer | ptr | 0x1234abcd | pointer | ptr | NULL | time | tim | 1321993456 -| array of strings | arr str | { "abc", "de" } -| array of integers | arr int | { 123, 456, 789 } +| array of strings | arr str | [ "abc", "de" ] +| array of integers | arr int | [ 123, 456, 789 ] |=== [[command_ping]] === ping -_Added in version 0.4.2._ +_WeeChat ≥ 0.4.2._ Send a ping to WeeChat which will reply with a message "_pong" and same arguments. This command is useful to test that connection with WeeChat is still alive and -measure the network lag. +measure the response time. Syntax: @@ -483,10 +483,10 @@ Messages are sent as binary data, using following format (with size in bytes): .... * 'length' (unsigned integer): number of bytes of whole message (including - this length) + this field) * 'compression' (byte): flag: ** '0x00': following data is not compressed -** '0x01': following data is zlib-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 @@ -497,12 +497,12 @@ Messages are sent as binary data, using following format (with size in bytes): === Compression If flag 'compression' is equal to 0x01, then *all* data after is compressed -with zlib, and therefore must be uncompressed before being processed. +with 'zlib', and therefore must be uncompressed before being processed. [[message_identifier]] === Identifier -There are two different 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 @@ -512,30 +512,66 @@ WeeChat reserved identifiers: [width="100%",cols="5,5,3,4,7",options="header"] |=== -| Identifier | Description | Received with sync | Data sent | Recommended action in client -| _buffer_opened | Buffer opened | buffers / buffer | hdata: buffer | Open buffer -| _buffer_moved | Buffer moved | buffers / buffer | hdata: buffer | Move buffer -| _buffer_merged | Buffer merged | buffers / buffer | hdata: buffer | Merge buffer -| _buffer_unmerged | Buffer unmerged | buffers / buffer | hdata: buffer | Unmerge buffer -| _buffer_renamed | Buffer renamed | buffers / buffer | hdata: buffer | Rename buffer -| _buffer_title_changed | Title of buffer changed | buffers / buffer | hdata: buffer | Change title of buffer -| _buffer_type_changed | Type of buffer changed | buffer | hdata: buffer | Change type of buffer -| _buffer_localvar_added | Local variable added | buffer | hdata: buffer | Add local variable in buffer -| _buffer_localvar_changed | Local variable changed | buffer | hdata: buffer | Change local variable in buffer -| _buffer_localvar_removed | Local variable removed | buffer | hdata: buffer | Remove local variable from buffer -| _buffer_line_added | Line added in buffer | buffer | hdata: line | Display line in buffer -| _buffer_closing | Buffer closing | buffers / buffer | hdata: buffer | Close buffer -| _nicklist | Nicklist for a buffer | nicklist | hdata: nicklist_item | Replace nicklist -| _nicklist_diff | Nicklist diffs for a buffer | nicklist | hdata: nicklist_item | Update nicklist -| _pong | Answer to a "ping" | (always) | string: ping arguments | Measure network lag -| _upgrade | WeeChat is upgrading | upgrade | (empty) | Desync from WeeChat (or disconnect) -| _upgrade_ended | Upgrade of WeeChat done | upgrade | (empty) | Sync/resync with WeeChat +| Identifier | Received with sync | Data sent | + Description | Recommended action in client + +| _buffer_opened | buffers / buffer | hdata: buffer | + Buffer opened | Open buffer + +| _buffer_moved | buffers / buffer | hdata: buffer | + Buffer moved | Move buffer + +| _buffer_merged | buffers / buffer | hdata: buffer | + Buffer merged | Merge buffer + +| _buffer_unmerged | buffers / buffer | hdata: buffer | + Buffer unmerged | Unmerge buffer + +| _buffer_renamed | buffers / buffer | hdata: buffer | + Buffer renamed | Rename buffer + +| _buffer_title_changed | buffers / buffer | hdata: buffer | + Title of buffer changed | Change title of buffer + +| _buffer_type_changed | buffer | hdata: buffer | + Type of buffer changed | Change type of buffer + +| _buffer_localvar_added | buffer | hdata: buffer | + Local variable added | Add local variable in buffer + +| _buffer_localvar_changed | buffer | hdata: buffer | + Local variable changed | Change local variable in buffer + +| _buffer_localvar_removed | buffer | hdata: buffer | + Local variable removed | Remove local variable from buffer + +| _buffer_line_added | buffer | hdata: line | + Line added in buffer | Display line in buffer + +| _buffer_closing | buffers / buffer | hdata: buffer | + Buffer closing | Close buffer + +| _nicklist | nicklist | hdata: nicklist_item | + Nicklist for a buffer | Replace nicklist + +| _nicklist_diff | nicklist | hdata: nicklist_item | + Nicklist diffs for a buffer | Update nicklist + +| _pong | (always) | string: ping arguments | + Answer to a "ping" | Measure response time + +| _upgrade | upgrade | (empty) | + WeeChat is upgrading | Desync from WeeChat (or disconnect) + +| _upgrade_ended | upgrade | (empty) | + Upgrade of WeeChat done | Sync/resync with WeeChat |=== [[message_buffer_opened]] ==== _buffer_opened -It is sent to the client when the signal "buffer_opened" is sent by WeeChat. +This message is sent to the client when the signal "buffer_opened" is sent by +WeeChat. Data sent as hdata: @@ -552,7 +588,7 @@ Data sent as hdata: | next_buffer | pointer | Pointer to next buffer |=== -Example: join of channel '#weechat' on freenode, new buffer +Example: channel '#weechat' joined on freenode, new buffer 'irc.freenode.#weechat': [source,python] @@ -577,17 +613,18 @@ hda: [[message_buffer_moved]] ==== _buffer_moved -It is sent to the client when the signal "buffer_moved" is sent by WeeChat. +This message is sent to the client when the signal "buffer_moved" is sent by +WeeChat. Data sent as hdata: [width="100%",cols="3m,2,10",options="header"] |=== -| Name | Type | Description -| number | integer | Buffer number (≥ 1) -| full_name | string | Full name (example: 'irc.freenode.#weechat') -| prev_buffer | pointer | Pointer to previous buffer -| next_buffer | pointer | Pointer to next buffer +| Name | Type | Description +| number | integer | Buffer number (≥ 1) +| 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: @@ -609,17 +646,18 @@ hda: [[message_buffer_merged]] ==== _buffer_merged -It is sent to the client when the signal "buffer_merged" is sent by WeeChat. +This message is sent to the client when the signal "buffer_merged" is sent by +WeeChat. Data sent as hdata: [width="100%",cols="3m,2,10",options="header"] |=== -| Name | Type | Description -| number | integer | Buffer number (≥ 1) -| full_name | string | Full name (example: 'irc.freenode.#weechat') -| prev_buffer | pointer | Pointer to previous buffer -| next_buffer | pointer | Pointer to next buffer +| Name | Type | Description +| number | integer | Buffer number (≥ 1) +| 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: @@ -641,17 +679,18 @@ hda: [[message_buffer_unmerged]] ==== _buffer_unmerged -It is sent to the client when the signal "buffer_unmerged" is sent by WeeChat. +This message is sent to the client when the signal "buffer_unmerged" is sent by +WeeChat. Data sent as hdata: [width="100%",cols="3m,2,10",options="header"] |=== -| Name | Type | Description -| number | integer | Buffer number (≥ 1) -| full_name | string | Full name (example: 'irc.freenode.#weechat') -| prev_buffer | pointer | Pointer to previous buffer -| next_buffer | pointer | Pointer to next buffer +| Name | Type | Description +| number | integer | Buffer number (≥ 1) +| 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: @@ -673,7 +712,8 @@ hda: [[message_buffer_renamed]] ==== _buffer_renamed -It is sent to the client when the signal "buffer_renamed" is sent by WeeChat. +This message is sent to the client when the signal "buffer_renamed" is sent by +WeeChat. Data sent as hdata: @@ -706,17 +746,17 @@ hda: [[message_buffer_title_changed]] ==== _buffer_title_changed -It is sent to the client when the signal "buffer_title_changed" is sent by -WeeChat. +This message is sent to the client when the signal "buffer_title_changed" is +sent by WeeChat. Data sent as hdata: [width="100%",cols="3m,2,10",options="header"] |=== -| Name | Type | Description -| number | integer | Buffer number (≥ 1) -| full_name | string | Full name (example: 'irc.freenode.#weechat') -| title | string | Buffer title +| Name | Type | Description +| number | integer | Buffer number (≥ 1) +| full_name | string | Full name (example: 'irc.freenode.#weechat') +| title | string | Buffer title |=== Example: topic changed on channel '#weechat': @@ -737,19 +777,20 @@ hda: [[message_buffer_type_changed]] ==== _buffer_type_changed -It is sent to the client when the signal "buffer_type_changed" is sent by WeeChat. +This message is sent to the client when the signal "buffer_type_changed" is sent +by WeeChat. Data sent as hdata: [width="100%",cols="3m,2,10",options="header"] |=== -| Name | Type | Description -| number | integer | Buffer number (≥ 1) -| full_name | string | Full name (example: 'irc.freenode.#weechat') -| type | integer | Buffer type: 0 = formatted (default), 1 = free content +| Name | Type | Description +| number | integer | Buffer number (≥ 1) +| 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] @@ -768,8 +809,8 @@ hda: [[message_buffer_localvar_added]] ==== _buffer_localvar_added -It is sent to the client when the signal "buffer_localvar_added" is sent by -WeeChat. +This message is sent to the client when the signal "buffer_localvar_added" is +sent by WeeChat. Data sent as hdata: @@ -801,8 +842,8 @@ hda: [[message_buffer_localvar_changed]] ==== _buffer_localvar_changed -It is sent to the client when the signal "buffer_localvar_changed" is sent by -WeeChat. +This message is sent to the client when the signal "buffer_localvar_changed" is +sent by WeeChat. Data sent as hdata: @@ -834,8 +875,8 @@ hda: [[message_buffer_localvar_removed]] ==== _buffer_localvar_removed -It is sent to the client when the signal "buffer_localvar_removed" is sent by -WeeChat. +This message is sent to the client when the signal "buffer_localvar_removed" is +sent by WeeChat. Data sent as hdata: @@ -866,24 +907,25 @@ hda: [[message_buffer_line_added]] ==== _buffer_line_added -It is sent to the client when the signal "buffer_line_added" is sent by WeeChat. +This message is sent to the client when the signal "buffer_line_added" is sent +by WeeChat. Data sent as hdata: [width="100%",cols="3m,2,10",options="header"] |=== -| Name | Type | Description -| buffer | pointer | Buffer pointer -| date | time | Date of message -| date_printed | time | Date when WeeChat displayed message -| displayed | char | 1 if message is displayed, 0 if message is filtered (hidden) -| highlight | char | 1 if line has a highlight, otherwise 0 -| tags_array | array of strings | List of tags for line -| prefix | string | Prefix -| message | string | Message +| Name | Type | Description +| buffer | pointer | Buffer pointer +| date | time | Date of message +| date_printed | time | Date when WeeChat displayed message +| displayed | char | 1 if message is displayed, 0 if message is filtered (hidden) +| highlight | char | 1 if line has a highlight, otherwise 0 +| tags_array | array of strings | List of tags for line +| prefix | string | Prefix +| message | string | Message |=== -Example: new message 'hello!' from nick 'FlashCode' in buffer 'irc.freenode.#weechat': +Example: new message 'hello!' from nick 'FlashCode' on buffer 'irc.freenode.#weechat': [source,python] ---- @@ -907,15 +949,16 @@ hda: [[message_buffer_closing]] ==== _buffer_closing -It is sent to the client when the signal "buffer_closing" is sent by WeeChat. +This message is sent to the client when the signal "buffer_closing" is sent by +WeeChat. Data sent as hdata: [width="100%",cols="3m,2,10",options="header"] |=== -| Name | Type | Description -| number | integer | Buffer number (≥ 1) -| full_name | string | Full name (example: 'irc.freenode.#weechat') +| Name | Type | Description +| number | integer | Buffer number (≥ 1) +| full_name | string | Full name (example: 'irc.freenode.#weechat') |=== Example: buffer 'irc.freenode.#weechat' is being closed by WeeChat: @@ -935,8 +978,8 @@ hda: [[message_nicklist]] ==== _nicklist -It is sent to the client when large updates are made on a nicklist (groups/nicks -added/removed/changed). The message contains full nicklist. +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). @@ -945,14 +988,14 @@ Data sent as hdata: [width="100%",cols="3m,2,10",options="header"] |=== -| Name | Type | Description -| group | char | 1 for a group, 0 for a nick -| visible | char | 1 if group/nick is displayed, otherwise 0 -| level | integer | Level of group (0 for a nick) -| name | string | Name of group/nick -| color | string | Name color -| prefix | string | Prefix (only for a nick) -| prefix_color | string | Prefix color (only for a nick) +| Name | Type | Description +| group | char | 1 for a group, 0 for a nick +| visible | char | 1 if group/nick is displayed, otherwise 0 +| level | integer | Level of group (0 for a nick) +| name | string | Name of group/nick +| color | string | Name color +| prefix | string | Prefix (only for a nick) +| prefix_color | string | Prefix color (only for a nick) |=== Example: nicklist for buffer 'irc.freenode.#weechat': @@ -1023,25 +1066,25 @@ hda: [[message_nicklist_diff]] ==== _nicklist_diff -_New in version 0.4.1._ +_WeeChat ≥ 0.4.1._ -It is sent to the client when small updates are made on a nicklist (groups/nicks -added/removed/changed). The message contains nicklist differences (between old -nicklist and current one). +This message is sent to the client when small updates are made on a nicklist +(groups/nicks added/removed/changed). The message contains nicklist differences +(between old nicklist and current one). Data sent as hdata: [width="100%",cols="3m,2,10",options="header"] |=== -| Name | Type | Description -| _diff | char | Type of diff (see below) -| group | char | 1 for a group, 0 for a nick -| visible | char | 1 if group/nick is displayed, otherwise 0 -| level | integer | Level of group (0 for a nick) -| name | string | Name of group/nick -| color | string | Name color -| prefix | string | Prefix (only for a nick) -| prefix_color | string | Prefix color (only for a nick) +| Name | Type | Description +| _diff | char | Type of diff (see below) +| group | char | 1 for a group, 0 for a nick +| visible | char | 1 if group/nick is displayed, otherwise 0 +| level | integer | Level of group (0 for a nick) +| name | string | Name of group/nick +| color | string | Name color +| prefix | string | Prefix (only for a nick) +| prefix_color | string | Prefix color (only for a nick) |=== The value of '_diff' can be: @@ -1118,21 +1161,21 @@ hda: [[message_pong]] ==== _pong -_New in version 0.4.2._ +_WeeChat ≥ 0.4.2._ -It is sent to the client when WeeChat 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. +Data sent as string: arguments received in the "ping" message. -The recommended action in client is to measure network lag and disconnect if -network lag is high. +The recommended action in client is to measure the response time and disconnect +if it is high. [[message_upgrade]] ==== _upgrade -_New in version 0.3.8._ +_WeeChat ≥ 0.3.8._ -It is sent to the client when WeeChat is starting upgrade process. +This message is sent to the client when WeeChat is starting upgrade process. There is no data in the message. @@ -1141,15 +1184,16 @@ The recommended action in client is to desynchronize from WeeChat (send command will change). [NOTE] -During WeeChat upgrade, the socket remains opened (except if connection was made -with SSL). +During WeeChat upgrade, the socket remains opened (except if connection uses +SSL). [[message_upgrade_ended]] ==== _upgrade_ended -_New in version 0.3.8._ +_WeeChat ≥ 0.3.8._ -It is sent to the client when WeeChat has finished the upgrade process. +This message is sent to the client when WeeChat has finished the upgrade +process. There is no data in the message. @@ -1159,15 +1203,14 @@ commands sent on startup after the 'init'. [[objects]] === Objects -Objects are identified by 3 letters, called 'type'. Following types are -available: +Objects are identified by 3 letters, called 'type'. Following types are used: [width="100%",cols="^2m,5,10",options="header"] |=== | Type | Value | Length | chr | Signed char | 1 byte | int | Signed integer | 4 bytes -| lon | Signed long integer | 1 byte + length of long as string +| lon | Signed long integer | 1 byte + length of integer as string | 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 @@ -1176,13 +1219,13 @@ available: | hda | Hdata content | Variable | inf | Info: name + content | Variable | inl | Infolist content | Variable -| arr | Array of values | 3 bytes (type) + number of items + data +| arr | Array of objects | 3 bytes (type) + number of objects + data |=== [[object_char]] ==== Char -A signed char is 1 byte. +A signed char is stored as 1 byte. Example: @@ -1195,8 +1238,8 @@ Example: [[object_integer]] ==== Integer -A signed integer is 4 bytes, encoded as big-endian format (most significant byte -first). +A signed integer is stored as 4 bytes, encoded as big-endian format (most +significant byte first). Range: -2147483648 to 2147483647. @@ -1364,8 +1407,8 @@ objects, and then set of objects (path with pointers, then objects). * 'values': list of values (number of values is number of keys returned for hdata) -Example of hdata with 2 buffers (weechat core and freenode server) and two keys -('number' and 'full_name'): +Example of hdata with two buffers (weechat core and freenode server) and two +keys ('number' and 'full_name'): .... # command @@ -1509,7 +1552,7 @@ An item is: ** 'type': type of variable ('int', 'str', ...) ** 'value': value of variable -Example of infolist with 2 buffers (weechat core and freenode server): +Example of infolist with two buffers (weechat core and freenode server): .... # command @@ -1532,9 +1575,9 @@ infolist buffer [[object_array]] ==== Array -An array is a type (3 bytes) + number of items (integer on 4 bytes) + data. +An array is a type (3 bytes) + number of objects (integer on 4 bytes) + data. -Example of array with 2 strings: +Example of array with two strings: .... ┌─────╥────┬────┬────┬────╥────┬────┬────┬────╥── @@ -1544,13 +1587,13 @@ Example of array with 2 strings: type number of strings length ──╥────┬────┬────╥────┬────┬────┬────╥────┬────┐ - ... ║ 61 │ 62 │ 63 ║ 00 │ 00 │ 00 │ 02 ║ 64 │ 65 │ ────► { "abc", "de" } + ... ║ 61 │ 62 │ 63 ║ 00 │ 00 │ 00 │ 02 ║ 64 │ 65 │ ────► [ "abc", "de" ] ──╨────┴────┴────╨────┴────┴────┴────╨────┴────┘ └────────────┘ └─────────────────┘ └───────┘ 'a' 'b' 'c' length 'd' 'e' .... -Example of array with 3 integers: +Example of array with three integers: .... ┌─────╥────┬────┬────┬────╥────┬────┬────┬────╥── @@ -1560,7 +1603,7 @@ Example of array with 3 integers: type number of integers 123 (0x7B) ──╥────┬────┬────┬────╥────┬────┬────┬────┐ - ... ║ 00 │ 00 │ 01 │ C8 ║ 00 │ 00 │ 03 │ 15 │ ────► { 123, 456, 789 } + ... ║ 00 │ 00 │ 01 │ C8 ║ 00 │ 00 │ 03 │ 15 │ ────► [ 123, 456, 789 ] ──╨────┴────┴────┴────╨────┴────┴────┴────┘ └─────────────────┘ └─────────────────┘ 456 (0x1C8) 789 (0x315) @@ -1617,8 +1660,8 @@ A 'NULL' array: ║ ║ ║ ║ ◄───────────────────────────────╢ ║ measure ║ msg: id: "_pong" ... ║ ║ - lag ║ ║ ║ - ║ ........ ║ ........ ║ +response ║ ║ ║ + time ║ ........ ║ ........ ║ ║ ║ ║ ╟───────────────────────────────► ║ ║ ║ cmd: quit ║ disconnect client ║ diff --git a/doc/fr/CMakeLists.txt b/doc/fr/CMakeLists.txt index d79f085d5..a316637ae 100644 --- a/doc/fr/CMakeLists.txt +++ b/doc/fr/CMakeLists.txt @@ -104,6 +104,17 @@ IF(ENABLE_DOC AND SOURCEHIGHLIGHT_FOUND) ADD_CUSTOM_TARGET(doc-tester-fr ALL DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/weechat_tester.fr.html) INSTALL(FILES ${CMAKE_CURRENT_BINARY_DIR}/weechat_tester.fr.html DESTINATION ${SHAREDIR}/doc/${PROJECT_NAME}) + # relay protocol + ADD_CUSTOM_COMMAND( + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/weechat_relay_protocol.fr.html + COMMAND ${ASCIIDOC_EXECUTABLE} ARGS -a revision="${VERSION}" -a stylesheet=${CMAKE_CURRENT_SOURCE_DIR}/../asciidoc.css -f ${CMAKE_CURRENT_SOURCE_DIR}/../asciidoc.conf -n -o ${CMAKE_CURRENT_BINARY_DIR}/weechat_relay_protocol.fr.html ${CMAKE_CURRENT_SOURCE_DIR}/weechat_relay_protocol.fr.txt + DEPENDS + ${CMAKE_CURRENT_SOURCE_DIR}/weechat_relay_protocol.fr.txt + COMMENT "Building weechat_relay_protocol.fr.html" + ) + ADD_CUSTOM_TARGET(doc-relay-protocol-fr ALL DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/weechat_relay_protocol.fr.html) + INSTALL(FILES ${CMAKE_CURRENT_BINARY_DIR}/weechat_relay_protocol.fr.html DESTINATION ${SHAREDIR}/doc/${PROJECT_NAME}) + # developer's guide ADD_CUSTOM_COMMAND( OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/weechat_dev.fr.html diff --git a/doc/fr/Makefile.am b/doc/fr/Makefile.am index 78a4b15c1..2403e2fc8 100644 --- a/doc/fr/Makefile.am +++ b/doc/fr/Makefile.am @@ -29,6 +29,7 @@ EXTRA_DIST = CMakeLists.txt \ weechat_faq.fr.txt \ weechat_quickstart.fr.txt \ weechat_tester.fr.txt \ + weechat_relay_protocol.fr.txt \ weechat_dev.fr.txt \ $(wildcard autogen/user/*.txt) \ $(wildcard autogen/plugin_api/*.txt) @@ -45,6 +46,7 @@ if DOC weechat_faq.fr.html \ weechat_quickstart.fr.html \ weechat_tester.fr.html \ + weechat_relay_protocol.fr.html \ weechat_dev.fr.html doc_install = install-doc doc_uninstall = uninstall-doc @@ -81,6 +83,10 @@ weechat_quickstart.fr.html: weechat_quickstart.fr.txt weechat_tester.fr.html: weechat_tester.fr.txt $(ASCIIDOC) -a revision="$(VERSION)" -a stylesheet=$(abs_top_srcdir)/doc/asciidoc.css -f $(abs_top_srcdir)/doc/asciidoc.conf -n -o weechat_tester.fr.html $(abs_top_srcdir)/doc/fr/weechat_tester.fr.txt +# relay protocol +weechat_relay_protocol.fr.html: weechat_relay_protocol.fr.txt + $(ASCIIDOC) -a revision="$(VERSION)" -a stylesheet=$(abs_top_srcdir)/doc/asciidoc.css -f $(abs_top_srcdir)/doc/asciidoc.conf -n -o weechat_relay_protocol.fr.html $(abs_top_srcdir)/doc/fr/weechat_relay_protocol.fr.txt + # developer's guide weechat_dev.fr.html: weechat_dev.fr.txt $(ASCIIDOC) -a revision="$(VERSION)" -a stylesheet=$(abs_top_srcdir)/doc/asciidoc.css -f $(abs_top_srcdir)/doc/asciidoc.conf -n -o weechat_dev.fr.html $(abs_top_srcdir)/doc/fr/weechat_dev.fr.txt diff --git a/doc/fr/weechat_relay_protocol.fr.txt b/doc/fr/weechat_relay_protocol.fr.txt new file mode 100644 index 000000000..16f28fff2 --- /dev/null +++ b/doc/fr/weechat_relay_protocol.fr.txt @@ -0,0 +1,1704 @@ += Protocole Relay de WeeChat +:author: Sébastien Helleu +:email: flashcode@flashtux.org +:lang: fr +:toc: +:toclevels: 4 + + +Ce document est une spécification du protocole Relay de WeeChat : le protocole +utilisé pour relayer les données de WeeChat aux clients, qui sont surtout des +interfaces distantes. + + +[[introduction]] +== Introduction + +[[terminology]] +=== Terminologie + +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 + distante. + +[[network_diagram]] +=== Diagramme réseau + +Les 'clients' sont connectés au 'relay' comme dans le diagramme ci-dessous : + +.... + ┌──────────┐ Station de travail + ┌────────┐ ┌───┤ client 1 │ (Linux, Windows, + │ irc │◄──┐ ╔═══════════╤═══════╗ │ └──────────┘ BSD, Mac OS X ...) + └────────┘ └──╢ │ ║◄───┘ ┌──────────┐ + ...... ║ WeeChat │ Relay ║◄───────┤ client 2 │ Appareil mobile + ┌────────┐ ┌──╢ │ ║◄───┐ └──────────┘ (Android, iPhone ...) + │ jabber │◄──┘ ╚═══════════╧═══════╝ │ ...... + └────────┘ │ ┌──────────┐ + ...... └───┤ client N │ Autres appareils + └──────────┘ + + +└────────────┘ └───────────────────┘╘══════╛└────────────────────────────────┘ + serveurs interface ncurses protocole interfaces distantes + relay +.... + +[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). + +[[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 + 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 + envoyés sous forme de données binaires. + +[[commands]] +== Commandes (client → relay) + +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 + 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 + sont séparés par des espaces). + +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) +| 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' +|=== + +[[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 +première commande reçue, sans avertissement. + +Syntaxe : + +---- +init [