projects / solanum.git / blame
| Commit | Line | Data |
|---|---|---|
| c5bbc603 KB |
1 | away-notify client capability specification |
| 2 | ---------------------------------------------- | |
| 3 | ||
| 4 | Copyright (c) 2012 Keith Buck <mr_flea@esper.net>. | |
| 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 away-notify client capability allows a client to specify that it | |
| 11 | would like to be notified when users are marked/unmarked as away. This | |
| 12 | capability is referred to as 'away-notify' at capability negotiation | |
| 13 | time. | |
| 14 | ||
| 15 | This capability is designed to replace polling of WHO as a more | |
| 16 | efficient method of tracking the away state of users in a channel. The | |
| 17 | away-notify capability both conserves bandwidth as WHO requests are | |
| 18 | not continually sent and allows the client to be notified immediately | |
| 19 | upon a user setting or removing their away state (as opposed to when | |
| 20 | WHO is next polled). | |
| 21 | ||
| 22 | When this capability is enabled, clients will be sent an AWAY message | |
| 23 | when a user sharing a channel with them sets or removes their away | |
| 24 | state, as well as when a user joins and has an away message set. | |
| 25 | (Note that AWAY will not be sent for joining users with no away | |
| 26 | message set.) | |
| 27 | ||
| 28 | The format of the AWAY message is as follows: | |
| 29 | ||
| 30 | :nick!user@host AWAY [:message] | |
| 31 | ||
| 32 | If the message is present, the user (specified by the nick!user@host | |
| 33 | mask) is going away. If the message is not present, the user is | |
| 34 | removing their away message/state. | |
| 35 | ||
| 36 | To fully track the away state of users, clients should: | |
| 37 | ||
| 38 | 1) Enable the away-notify capability at negotiation time. | |
| 39 | ||
| 40 | 2) Execute WHO when joining a channel to capture the current away | |
| 41 | state of all users in that channel. | |
| 42 | ||
| 43 | 3) Update state appropriately upon receiving an AWAY message. |