Update doc/Protocol.txt for IRCv3 WEBIRC extension

[ngircd-alex.git] / doc / Protocol.txt

diff --git a/doc/Protocol.txt b/doc/Protocol.txt
index 354b814b05888b0198868c2e0c7bee3f3b27697c..b6ead9dfdbe5ef6078236dff1e1e60829a715413 100644 (file)
--- a/doc/Protocol.txt
+++ b/doc/Protocol.txt
@@ -1,9 +1,8 @@
 
                      ngIRCd - Next Generation IRC Server
 
                      ngIRCd - Next Generation IRC Server

+                           http://ngircd.barton.de/

 
 

-                        (c)2001-2008 Alexander Barton,
-                    alex@barton.de, http://www.barton.de/
-
+               (c)2001-2012 Alexander Barton and Contributors.

                ngIRCd is free software and published under the
                    terms of the GNU General Public License.
 
                ngIRCd is free software and published under the
                    terms of the GNU General Public License.
 


@@ -82,11 +81,17 @@ The following <serverflags> are defined at the moment:
 - H: The server supports the "enhanced server handshake", see section II.2
      for a detailed description.
 
 - H: The server supports the "enhanced server handshake", see section II.2
      for a detailed description.
 

+- M: Changing client "metadata" (hostname, real name, ...) using the
+     METADATA command is supported.
+

 - o: IRC operators are allowed to change channel- and channel-user-modes
      even if they aren't channel-operator of the affected channel.
 
 - S: The server supports the SERVICE command (on this link).
 
 - o: IRC operators are allowed to change channel- and channel-user-modes
      even if they aren't channel-operator of the affected channel.
 
 - S: The server supports the SERVICE command (on this link).
 

+- X: Server supports XOP channel modes (owner, admin, halfop) and supports
+     these user prefixes in CHANINFO commands, for example.
+

 - Z: Compressed server links are supported by the server.
 
 Example for a complete <flags> string: "ngircd|0.7.5:CZ".
 - Z: Compressed server links are supported by the server.
 
 Example for a complete <flags> string: "ngircd|0.7.5:CZ".


@@ -134,18 +139,24 @@ protocol which allows at max 15 arguments per command).
 Please see <http://www.irc.org/tech_docs/005.html> for details.
 
 The information exchanged using ISUPPORT can be used to detect configuration
 Please see <http://www.irc.org/tech_docs/005.html> for details.
 
 The information exchanged using ISUPPORT can be used to detect configuration

-incompatibilities (different maximum nick name length, for example) and
+incompatibilities (different maximum nickname length, for example) and

 therefore to disconnect the peer prior to registering it in the network.
 
 
 II.3 Exchange channel-modes, topics, and persistent channels
 
      Command: CHANINFO
 therefore to disconnect the peer prior to registering it in the network.
 
 
 II.3 Exchange channel-modes, topics, and persistent channels
 
      Command: CHANINFO

-  Parameters: <channel> +<modes> <key> <limit> [<topic>]
+  Parameters: <channel> +<modes> [[<key> <limit>] <topic>]

      Used by: servers only
 
 CHANINFO is used by servers to inform each other about a channel: its
      Used by: servers only
 
 CHANINFO is used by servers to inform each other about a channel: its

-modes, channel key, user limits and its topic. <topic> is optional.
+modes, channel key, user limits and its topic. The parameter combination
+<key> and <limit> is optional, as well as the <topic> parameter, so that
+there are three possible forms of this command:
+
+  CHANINFO <channel> +<modes>
+  CHANINFO <channel> +<modes> <topic>
+  CHANINFO <channel> +<modes> <key> <limit> <topic>

 
 If the channel already exists on the server receiving the CHANINFO command,
 it only adopts the <modes> (or the <topic>) if there are no modes (or topic)
 
 If the channel already exists on the server receiving the CHANINFO command,
 it only adopts the <modes> (or the <topic>) if there are no modes (or topic)


@@ -161,3 +172,88 @@ and therefore can't be omitted. The parameter <limit> must be ignored when
 a channel has no user limit (the parameter <modes> doesn't list the "l"
 channel mode). In this case <limit> should be "0".
 
 a channel has no user limit (the parameter <modes> doesn't list the "l"
 channel mode). In this case <limit> should be "0".
 

+
+II.4 Update webchat/proxy client information
+
+     Command: WEBIRC
+  Parameters: <password> <username> <hostname> <ip-address> [<ignored>]
+     Used by: unregistered clients only
+
+The WEBIRC command is used by some Web-to-IRC gateways to set the correct
+user name and host name of users instead of their own. It must be the very
+first command sent to the server, even before USER and NICK commands!
+
+The <password> must be set in the server configuration file to prevent
+unauthorized clients to fake their identity; it is an arbitrary string.
+
+Optionally, a 5th parameter is accepted to comply with an IRCv3 extension,
+see <https://github.com/ircv3/ircv3-ideas/issues/12>, but ignored.
+
+
+II.5 Client character encoding conversion
+
+     Command: CHARCONV
+  Parameters: <client-charset>
+     Used by: registered clients
+     Replies: RPL_IP_CHARCONV, ERR_IP_CHARCONV
+
+A client can set its character set encoding using the CHARCONV command:
+after receiving such a command, the server translates all message data
+received from the client using the set <client-charset> to the server
+encoding (UTF-8), and all message data which is to be sent to the client
+from the server encoding (UTF-8) to <client-charset>.
+
+The list of supported client character sets is implementation dependent.
+
+If a client sets its <client-charset> to the server encoding (UTF-8),
+it disables all conversions; the connection behaves as if no CHARCONV
+command has been sent at all in this session.
+
+
+II.6 Update client "metadata"
+
+     Command: METADATA
+  Parameters: <target> <key> <value>
+     Used by: servers only
+
+The METADATA command is used on server-links to update "metadata" information
+of clients, like the hostname, the info text ("real name"), or the user name.
+
+The server updates its client database according to the received <key> and
+<value> parameters, and passes the METADATA command on to all the other
+servers in the network that support this command (see section II.1 "Register
+new server link", <serverflag> "M"), even if it doesn't support the given
+<key> itself: unknown <key> names are ignored silently!
+
+The following <key> names are defined:
+
+ - "accountname": the account name of a client (can't be empty)
+ - "certfp": the certificate fingerprint of a client (can't be empty)
+ - "cloakhost": the cloaked hostname of a client
+ - "host": the hostname of a client (can't be empty)
+ - "info": info text ("real name") of a client
+ - "user": the user name of a client (can't be empty)
+
+
+III. Numerics used by IRC+ Protocol
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The IRC+ protocol uses numerics in the range 800-899 which aren't used by
+RFC 2812 and hopefully don't clash with other implementations ...
+
+Numerics 800-849 are used for status and success messages, and numerics
+850-899 are failure and error messages.
+
+
+III.1 IRC+ status and success numerics
+
+801 - RPL_IP_CHARCONV
+       %1 :Client encoding set"
+
+               %1      client character set
+
+
+III.2 IRC+ failure and error numerics
+
+851 - ERR_IP_CHARCONV
+       :Can't initialize client encoding