This is an explanation of the say2 client-server protocol for subscribing to presence status (ie "notify list" in IRC jargon, or "buddy list" in AOL jargon). Last update: 20-aug-2001 C: client making request S: say2 server T: target client C>S: sent from client to server *** RECEIVING STATUS UPDATES (See 'status' description in protocol.txt.) These messages are sent asynchronously for any user you are subscribed to (for receiving presence info). They are also echoed back when you change your own status information, or request your own status information (with an empty 'status' request). *** SUBSCRIBING C>S: subscribe:{ id text? } id: unique ID of the user to subscribe to text: optional text displayed to the target user The server will ask the target user to let you subscribe to their presence information. Unlike IRC or Yahoo! Messenger, you are not actually subscribed until/if the target user specifically confirms it. If the target user is not currently online, your request (with the optional text) will be stored, and delivered on each subsequent login of the target user until they respond. Subscription requests that are unconfirmed will be listed as "pending" in the subscription lists (see below). If you are already subscribed to the target user's presense information, the server will respond with a 'subscription-accepted' message (see below) with the 'already' flag present. If there is no such user on the say2 server, the server will respond with a 'no-such-client' message. If you have made a large (system-defined) number of denied requests to this user, the server will respond with a 'subscription-denied' message, with the 'patience-exceeded' flag set. On jenova, this limit is currently 5. FIXME: Should the server confirm the subscription-request to the client by echoing it back? S>T: subscription-request:{ id to-id text? } id: unique ID of the user making the request to-id: unique ID of the target user text: optional text from the requesting user This is the message the target user will receive for a subscription request. On login, any unhandled (pending) subscription requests will be sent again, in the hopes that the target user will eventually notice and respond. The correct response to a 'subscription-request' is either 'subscription-denied' or 'subscription-accepted' (see below). *** ACCEPTING A SUBSCRIPTION T>S: subscription-accepted:{ id text? } id: unique ID of the user who made the original request text: optional text to be displayed to the requesting user If no subscription request exists from the user specified in 'id', the server will respond with: S>T: no-subscription-request:{ id } id: unique ID of the user who did NOT make a subscription request Otherwise, the server will send this to the requesting client: S>C: subscription-accepted:{ id text? already? } id: unique ID of the user who accepted the subscription request text: optional text from the target user already: flag that's present if you were already subscribed to presence information for this user And the server will send the target client a 'subscriptions-from' message (see below) to refresh the target client's list of subscribed users. If the requesting user is not online, the 'subscription-accepted' message (and its optional text) will be stored and displayed the next time they login. *** DENYING A SUBSCRIPTION T>S: subscription-denied:{ id text? } id: unique ID of the user who made the original request text: optional text to be displayed to the requesting user If no subscription or subscription request exists from the user specified in 'id', the server will respond with 'no-subscription-request' (see above). Otherwise, the server will send this to the requesting client: S>C: subscription-denied:{ id text? patience-exceeded? } id: unique ID of the user who denied the subscription request text: optional text from the target user patience-exceeded: flag that's present if the subscription request was automatically denied by the server because too many requests to this user have already been denied And the server will send the target client a 'subscription-from' message (see below) to refresh the target client's list of subscribed users. If the requesting user is not online, the 'subscription-denied' message (and its optional text) will be stored and displayed the next time they login. A target client may also revoke a user's existing subscription by sending a 'subscription-denied' message, and it will work the same way described above. *** UNSUBSCRIBING C>S: unsubscribe:{ id } id: unique ID of the user to stop subscribing to If no subscription exists for the target user, the server will send: S>C: no-subscription:{ id } id: unique ID of the user you aren't subscribed to Otherwise, the server will immediately send a 'subscriptions' message (see below) to refresh the client's subscription list. The target user does not have to confirm an unsubscribe request. If the target user is online, they will receive: S>T: unsubscribed-from:{ id } id: unique ID of the user who unsubscribed Otherwise, the target user will receive no message -- the user will just not be in their 'subscriptions-from' list the next time they login. *** REQUESTING THE SUBSCRIPTION LISTS C>S: list-subscriptions S>C: subscriptions:{ approved:[ ] pending:[ ] } approved: list of IDs of users that this user is subscribed to pending: list of IDs of users that this user has pending requests to subscribe to (not accepted or denied yet) S>C: subscriptions-from:{ approved:[ ] blocked:[ ] pending:[ ] } approved: list of IDs of users that are subscribed to this user's presence information blocked: list of IDs of users who are approved, but are currently being blocked [FIXME: not supported yet] pending: list of IDs of users who have requested a subscription to this user's presence information, but this user has not accepted or denied yet Occasionally, the server will send 'subscriptions' or 'subscriptions-from' messages in response to other requests (see above). FIXME: The 'blocked' list is currently nonfunctional (needs more protocol support.) *** REFRESHING THE STATUS OF BUDDIES C>S: refresh-status S>C: status:{ ... } ... The server will re-transmit the 'status' message for each user you are subscribed to (the ones in your "approved" list). Users who are blocking you will appear offline.