Shared Status Messages

This document describes the XMPP extension used by Google Talk to enable multiple applications signed in as the same user to report the same status message.

Note: This extension is not intended to become a standard and is subject to change.

Table of Contents

Introduction

Determining Server Support

Requesting Current Status and Message Lists

Changing the Current Status or Message

How the Server Broadcasts Presence

About Google Talk Extensions

Introduction

Google Talk, like many chat clients, lets a user display a custom status message to other users. The Google Talk server stores lists of recently used status messages, and you can request and modify these values. This XEP extension enables a client to retrieve and modify these stored message lists, and also provides notifications so that all resources can report the same status and message. Whenever any resource changes its status or message, all other resources will be notified with the new values.

Determining Server Support

A client must first learn whether a server supports this extension by using service discovery. A client should send the following IQ stanza to discover what features the server supports..

Example 1. Client service discovery request

<iq type='get' to='gmail.com'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>

If the server supports the user settings extension, the reply will include the 'google:shared-status' feature as shown here:

Example 2. Client service discovery response

<iq type='result' to='romeo@gmail.com' from='gmail.com'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    ...
    <feature var='google:shared-status'/>
    ...
  </query>
</iq>

Requesting Current Status and Message Lists

A client can query the server for the current lists of status messages stored by the user. Sending this query also registers the client to receive notifications whenever any instance of that user changes the displayed status message, or if the stored list values change.

To query for the current list, send an IQ query qualified by the 'google:shared-status' namespace, as shown here:

Example 3. Client requests status lists.

<iq type='get' to='romeo@gmail.com' id='ss-1' >
  <query xmlns='google:shared-status'/>
</iq>

The server will respond with the lists of stored messages, as well as information about its message-storing capabilities. Each response includes several lists; each list is associated with one status value. Google Talk servers only recognize lists associated with two <show> values: dnd and default. If other show values are used, there is no guarantee that a client will understand or display them. The following code shows an example query response.

Example 4. Server responds to a shared status message response with messages and capabilities.

<iq type='result' to='romeo@gmail.com/orchard' id='ss-1'>
  <query xmlns='google:shared-status' 
      status-max='512' status-list-max='3' status-list-contents-max='5'>
    <status>Pining away</status>
    <show>default</show>
    <status-list show='default'>
        <status>Wherefore indeed</status>
        <status>Thinking about the sun</status>
    </status-list>
    <status-list show='dnd'>
        <status>Chilling with Mercutio</status>
        <status>Visiting the monk</status>
    </status-list>
  </query>
</iq>

The previous stanza includes two lists, once for the default status (available), and one for the busy status ("dnd"). Each status list is enclosed in a <status-list> element with a show element describing the status associated with it. It also includes the current status (default) and message ("Pining away").

The following table describes the <elements> and attributes in this query response.

Element or Attribute	Description
<query>	Outer wrapper element for the response. Attributes of this element describe the server's status message capabilities.
status-max	The maximum length in characters for any individual status message.
status-list-max	The maximum number of status lists the server can store.
status-list-contents-max	The maximum number of messages that the server can store in a list.
<status>	The current message displayed on the clients.
<show>	The current status of the user.
<status-list>	Holds a number of messages to associate with the status value described by the show attribute.
show	The status to associate with these lists. The following two values are supported by Google Talk; other values are not supported by the Google Talk client. (The idle <show> value is supported by Google Talk, but not as a shared status value.) dnd User is busy. default Maps to the default, available state; user is able to chat.
<status>	The message to display in the client.

Changing the Current Status or Message

Once you have registered as a shared-status-aware client, the server will rewrite your presence stanzas and you must use shared-status to change your status or the status message. To change your shared-status, send an IQ set of the same form as the IQ result returned by the server when you queried for the current status. Include the new status and message values in the top-level <status> and <show> elements.

The lists you send in your IQ set will replace the lists currently stored by the server. You should therefore resend the existing lists unless you want to clear these messages from the server. If the message that you are replacing is not in the appropriate status list, you should add it to the top of the appropriate status message list. If the list length then exceeds the server's maximum list length, remove the oldest message from that list to make room.

Note: Because Google Talk interprets the 'away' status as idle, and idleness is a per-connection property, you cannot set an 'away' status using this method. To set an idle status message, send a standard <presence> stanza.

To report a status change, send an IQ query qualified by the 'google:shared-status' namespace. Place the new status and message values in the top level <status> and <show> elements. You must include both these elements, even if you are only changing one of them.

The following stanza demonstrates a request to change the status message from "Pining away" to "Juliet's here" Note that "Pining away" was added to the list for the active status.

Example 5. Changing the current message.

<iq type='set' to='romeo@gmail.com/orchard' id='ss-2'>
  <query xmlns='google:shared-status'>
    <status>Juliet's here</status>
    <show>default</status>
    <status-list show='default'>
        <status>Pining away</status>
        <status>Wherefor indeed</status>
        <status>Thinking about the sun</status>
    </status-list>
    <status-list show='dnd'>
        <status>Chilling with Mercutio</status>
        <status>Visiting the monk</status>
    </status-list>
  </query>
</iq>

In response to your request, the server will send the following IQ set to all registered clients for this user. It will also send a standard <presence> stanza to all the subscribed contacts for this user.

Example 6. Server sends status message notification to all registered clients for this user.

<iq type='set' to='romeo@gmail.com/orchard' id='ss-3'>
  <query xmlns='google:shared-status'>
    <status>Juliet's here</status>
    <show>default</status>
    <status-list show='default'>
        <status>Pining away</status>
        <status>Wherefore indeed</status>
        <status>Thinking about the sun</status>
    </status-list>
    <status-list show='dnd'>
        <status>Chilling with Mercutio</status>
        <status>Visiting the monk</status>
    </status-list>
  </query>
</iq>

How the Server Broadcasts Presence

Whenever a shared-status client sends a google:shared-status IQ set, the server stores the <show> and <status> values and rewrites that clients last-sent presence stanza to include the new values. The server then broadcasts the new presence stanza to all subscribed contacts.

Whenever a client sends a presence stanza the server will rewrite the 'show' and 'status' values according to these rules before broadcasting.

• <show> The server will broadcast the presence stanza's 'show' unless the current shared show value is dnd. In that case, the server broadcasts dnd. (You must reset the dnd <show> value using shared status.)
• <status> The server will rewrite the presence stanza with the last shared status value.

The following example is a simple presence stanza sent by a shared-status-aware client when the resource sends an "away" presence notification. The server will ignore the <status> value.

Example 7. Client sends a request to change the capabilities and <show> value.

<presence>
  <show>away</show>
  <status>A far, far better thing</status>
  <c xmlns='http://jabber.org/protocol/caps'
       node='http://www.google.com/xmpp/client/caps'
       ver='0.92'/>
</presence>

The server rewrites and sends out the following value to all subscribed contacts and other instances. Note that the <status> value used is the current shared value, not the value just sent by the <presence> stanza.

Example 8. Server rewrites the <show> value and sends a notification to all clients and subscribed contacts.

<presence>
  <show>away</show>
  <status>Juliet's here</status>
  <c xmlns='http://jabber.org/protocol/caps'
     node='http://www.google.com/xmpp/client/caps'
     ver='0.92'/>
</presence>

About Google Talk Extensions

Extensibility is one of the greatest strengths of XMPP, the IETF standard protocol on which Google Talk is built. While XMPP itself defines a bare set of features, the protocol encourages third parties to develop their own extensions. During the development of Google Talk, we found it useful to define extensions to implement features not already found in XMPP or any of its currently defined extensions.The protocol defined in this document is currently used by the Google Talk clients and servers. However, note that it is not currently part of a proposed standardized extension, and therefore may change as we work to standardize these features.