[solanum.git] / doc / features / account-notify.txt

account-notify client capability specification
----------------------------------------------

Copyright (c) 2010 Ariadne Conill <ariadne@dereferenced.org>.

Unlimited redistribution and modification of this document is allowed
provided that the above copyright notice and this permission notice
remains in tact.

The account-notify client capability allows a client to be notified
when another client's accountname changes.  This capability MUST be
referred to as 'account-notify' at capability negotiation time.

When enabled, clients will get the ACCOUNT message to designate the
accountname changes for clients on common channels with them.

The ACCOUNT message is one of the following:

   :nick!user@host ACCOUNT accountname

This message represents that the user identified by nick!user@host has
logged into a new account.  The last parameter is the display name of
that account.

   :nick!user@host ACCOUNT *

This message represents that the user identified by nick!user@host has
logged out of their account.  As the last parameter is an asterisk, this
means that an asterisk is not a valid account name (which it is not in P10
or TS6 or ESVID).

In order to take full advantage of the ACCOUNT message, WHOX must be
supported by the ircd.  In this case, the appropriate strategy to ensuring
you always have the accountname to display is to do the following:

1) Enable the account-notify capability at capability negotiation time during
   the login handshake.

2) When joining a channel, query the channel using WHO and ensure that you
   include the 'a' format token in your WHOX token request.  When you get
   a reply, do appropriate caching.

3) If the extended-join capability is available, enable it at client capability
   negotiation time during the login handshake, and then set the accountname
   based on what is sent in the extended JOIN command.

   Otherwise, if extended-join is unavailable:
   When new users join a channel that your client does not know the accountname
   for yet, do a WHO query against that client, again including the 'a' format
   token in your WHOX token request field.  When you get a reply, do appropriate
   caching.

4) In the event of a netsplit, the client should query the channel again using
   WHO with the 'a' format token in the WHOX request field.

5) When the client receives an ACCOUNT message, update the accountname for the
   client in question in your accountname cache.
Commit	Line	Data
4f943f99 AC	1	account-notify client capability specification
	2	----------------------------------------------
	3
3fc0499e	4	Copyright (c) 2010 Ariadne Conill <ariadne@dereferenced.org>.
4f943f99 AC	5
	6	Unlimited redistribution and modification of this document is allowed
	7	provided that the above copyright notice and this permission notice
	8	remains in tact.
	9
	10	The account-notify client capability allows a client to be notified
	11	when another client's accountname changes. This capability MUST be
	12	referred to as 'account-notify' at capability negotiation time.
	13
	14	When enabled, clients will get the ACCOUNT message to designate the
	15	accountname changes for clients on common channels with them.
	16
	17	The ACCOUNT message is one of the following:
	18
	19	:nick!user@host ACCOUNT accountname
	20
	21	This message represents that the user identified by nick!user@host has
	22	logged into a new account. The last parameter is the display name of
	23	that account.
	24
	25	:nick!user@host ACCOUNT *
	26
	27	This message represents that the user identified by nick!user@host has
	28	logged out of their account. As the last parameter is an asterisk, this
	29	means that an asterisk is not a valid account name (which it is not in P10
	30	or TS6 or ESVID).
	31
	32	In order to take full advantage of the ACCOUNT message, WHOX must be
	33	supported by the ircd. In this case, the appropriate strategy to ensuring
	34	you always have the accountname to display is to do the following:
	35
	36	1) Enable the account-notify capability at capability negotiation time during
	37	the login handshake.
	38
	39	2) When joining a channel, query the channel using WHO and ensure that you
	40	include the 'a' format token in your WHOX token request. When you get
	41	a reply, do appropriate caching.
	42
f56b4e3c AC	43	3) If the extended-join capability is available, enable it at client capability
	44	negotiation time during the login handshake, and then set the accountname
	45	based on what is sent in the extended JOIN command.
	46
	47	Otherwise, if extended-join is unavailable:
	48	When new users join a channel that your client does not know the accountname
4f943f99 AC	49	for yet, do a WHO query against that client, again including the 'a' format
	50	token in your WHOX token request field. When you get a reply, do appropriate
	51	caching.
	52
a8df2896 AC	53	4) In the event of a netsplit, the client should query the channel again using
	54	WHO with the 'a' format token in the WHOX request field.
	55
	56	5) When the client receives an ACCOUNT message, update the accountname for the
4f943f99	57	client in question in your accountname cache.