This document describes the XMPP extension used by Google Talk to expose additional information about members of a user's roster.
Note: This extension is not intended to become a standard and is subject to change.
Table of Contents
Introduction
The Google Talk Service stores additional information not specified in the XMPP standard about members of a user's roster. These extended values include a count of emails and instant messages sent to this contact, and other useful information. You can set and retrieve these values using this extension.
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:roster' 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:roster'/>
...
</query>
</iq>
Retrieving Extended Contact Attribute Values
A client can query the server for extended attribute values stored for each roster member. These values are stored by the server. You cannot query for specific values or specific contacts; you can only query for all extended values for all contacts. To query for these values, a client does a standard roster request, which includes a ext attribute that is qualified by the 'google:roster' namespace. This attribute specifies which version of the extended attributes to retrieve. This document describes attributes in the Version 2 attribute set.
Querying for extended roster member attributes registers the client to receive notifications whenever these values (other than message count attributes mc and emc) change. The following snippet shows a request for extended attribute values.
Example 3. Client requests Version 2 extended attributes.
<iq type='get'
from='romeo@gmail.com/orchard'
id='google-roster-1'>
<query xmlns='jabber:iq:roster' xmlns:gr='google:roster' gr:ext='2'/>
</iq>
The server responds to this request with a roster list containing one <item> element
per roster member. Each <item> element includes all
of the extended attribute values stored for that member. (All attributes
are qualified by the google:roster namespace).
The following shows one item in a query response.
Example 4. Server responds with extended roster member attributes.
<iq type='result'
to='romeo@gmail.com/orchard'
id='google-roster-1'>
<query xmlns='jabber:iq:roster' xmlns:gr='google:roster' gr:ext='2'>
...
<item jid='hamlet@denmark.lit' name='Hamlet' subscription='both'
gr:t='B' gr:mc='82' gr:emc='5' gr:w='9'/>
...
</usersetting>
</iq>
The following table shows the attributes defined in Version 2 of the extended
contact attribute set. An <item> element does not
need to have values specified for all attributes.
| Attribute Name | Description |
|---|---|
| mc | [read, limited-write] The number of messages sent to and from this contact. You can increment this value using a special syntax described in Incrementing the Message Count. This and emc are used to sort the members returned to a query. |
| emc | [read-only] The number of emails sent to and from this contact. Emails must be sent through Gmail for the Google Talk server to be counted in this tally. This and mc are used by the client to sort the contacts on the roster. |
| w | [deprecated, read-only] A weight assigned to this contact. Superceded by mc and emc. |
| rejected | [read-only] A boolean value indicating whether a subscription request from this client was ever rejected by the user. "true" indicates that it has. This is provided so that a client can block repeated subscription requests. |
| t | [optional, read-write] A description for this contact.
It can be one of the following values. If this attribute is not
returned by the server, you should assume that the contact should
not be blocked and should be displayed normally.
|
| autosub | [deprecated, read-only] A boolean value indicating whether the server added this contact automatically. "true" indicates that it did. Missing or "false" indicates that it did not. |
| alias-for | [optional, read-only] If this contact was superseded by another contact, this attribute will be present and set to the new contact JID. This happens when a user invites a Gmail contact to use Google Talk, and the invited user then creates a new Google Talk JID. The original email address of the invitee will be superseded by the Google Talk JID. If this value is present, the client should hide this contact in favor of the newer contact identified by this value. |
| inv | [optional, read-only] If present, it will have the value "A" indicating that the user invited this contact to create a Google Talk account. If absent, this was not an invited contact. |
Setting Extended Contact Attribute Values
You can set the values of read-write extended attributes by sending a IQ set to the server. Currently you can only set the t extended attribute, but you can also increment the mc and emc values as described in Incrementing the Message Counts.
To set a read-write attribute, send a roster set with an 'ext' attribute qualified by
the 'google:roster' namespace, containing
an <item> element for each contact to update.
The item should have the attribute (qualified by the google:roster namespace)
and new value for that contact. The following code demonstrates how
to block a roster member.
Example 5. Setting the t attribute value to block a roster member.
<iq type='set'
id='google-roster-2'
type='set'>
<query xmlns='jabber:iq:roster' xmlns:gr='google:roster' gr:ext='2'>
<item jid='hamlet@denmark.lit' gr:t='B'/>
</query>
</iq>
In response to your request, the server sends an acknowledgment to the sender
(for example, <iq type='result' id='google-roster-2'/>),
and sends a roster update to all connected resources, as described in Getting
Roster Update Notifications.
Incrementing the Message Count
The mc message count value is tracked for you by the server. Although you cannot directly modify the mc attribute, you can increment it by sending one of two types of IQ set messages. You might want to increment the message count yourself when the user initiates a voice chat with another client, because the server does not currently include voice connections in its message count.
Incrementing the mc attribute causes an update notification the same as for any other attribute updates.
You can increase the message count in two ways: by a number, or up to a specific number:
To increase the message count by a number, send
a IQ set containing an <increment-mc> element, with
a jid attribute set to the contact to increment, and a numerical value attribute
to add to the current count.
Example 6. Client increments the message count by two
<iq type='set'
id='google-roster-4'>
<increment-mc xmlns='google:roster' jid='hamlet@denmark.lit' value='2'/>
</iq>
To increase the message count up to a specific number, send
a IQ set containing an <boost-mc> element, with a jid attribute
set to the contact to increment, and a numerical value attribute
of the new value. The new value must be greater than the current message
count or the server will return an error.
Example 7. Client increases the message count to twelve
<iq type='set'
id='google-roster-4'>
<boost-mc xmlns='google:roster' jid='hamlet@denmark.lit' value='12'/>
</iq>
Getting Attribute Update Notifications
If a client sends a query for extended contact attribute values, it will a roster update whenever any of those values change. The notification will a roster item containing all of the modified attributes (qualified by the 'google:roster' namespace).
The following IQ set will be sent to all connected resources if one of them blocks the user "hamlet@denmark.lit".
Example 8. Server sends attribute update notification to all registered clients for this user.
<iq type='set'
id='google-roster-3'>
<query xmlns='google:setting' xmlns:gr='google:roster' gr:ext='2'>
<item jid='hamlet@denmark.lit' gr:t='B'/>
</query>
</iq>
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.