User Settings

This document describes the XMPP extension used by Google Talk to make server-side changes that affect the client environment.

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

Table of Contents

Introduction

Determining Server Support

Requesting Current Settings

Modifying User Settings

Receiving Settings Updates

About Google Talk Extensions

Introduction

Users can customize some settings on the Google Talk server to customize their client experience. For example, a client can request that the server archive chat sessions. To enable setting these server-side values, the Google Talk server supports a custom XMPP extension to query values, request changes, and request notification of changes made by other clients. This document describes this XMPP 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:setting' 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:setting'/>
    ...
  </query>
</iq>

Requesting Current Settings

To request the user's current settings from the Google Talk server, a client sends an IQ get containing a <usersetting/> element qualified by the 'google:setting' namespace as shown here:

Example 3. Client requests user settings

<iq type='get'
    from='romeo@gmail.com/orchard'	
    to='romeo@gmail.com'
    id='user-setting-1'>
  <usersetting xmlns='google:setting' />
</iq>

The first time this request is sent, in addition to returning the current user settings, the server will subscribe the client to receive updates whenever user settings are changed.

After receiving the request for settings, the server returns an IQ result containing a <usersetting/> stanza qualified by the 'google:setting' namespace.

Example 4. Server responds with stored settings

<iq type='result'
    from='romeo@gmail.com'
    to='romeo@gmail.com/orchard'
    id='user-setting-1'>
  <usersetting xmlns='google:setting'>
    <autoacceptsuggestions value='true' />
    <mailnotifications value='true' />
    <archivingenabled value='true' />
  </usersetting>
</iq>

This stanza contains one element describing each user setting stored on the server. If an element is not included, the value has not yet been set, and the setting remains in a default state. Here are the elements that the Google Talk Server currently supports:

• <autoacceptsuggestions/> - If set to "true", the server will automatically add people emailed often to the user's roster.
• <mailnotifications/> - If set to "true", the server will send notifications of unread email. To ensure better compatibility with other clients, rather than setting this value to "false" to turn off notifications, it is recommended that a client set this to "true" and filter incoming email notifications itself.
• <archivingenabled/> - If set to "true", the server will save Google Talk chats on the server; if set to "false", no conversations will be logged. This is a global setting; if false, it will block any chats from being logged. You can control chat logging in a more fine-grained manner by setting this value to true and turning off logging for individual conversations. See Off the Record Chats to learn how to turn off logging for individual connections.

Modifying User Settings

When a client wishes to change settings on the server, it sends an IQ set containing a <usersetting/> stanza qualified by the "google:setting" namespace, containing an element for each setting it wants to store.

Example 5. Client changes the chat archiving setting

<iq type='set'
    from='romeo@gmail.com/orchard'
    to='romeo@gmail.com'
    id='user-setting-3'>
  <usersetting xmlns='google:setting'>
    <archivingenabled value='false'/>
  </usersetting>
</iq>

If the request fails, the server will send an IQ error. If it succeeds, it will send an empty IQ result similar to the following:

Example 6. Server response to a setting change

<iq type='result'
    to='romeo@gmail.com/orchard'
    from='romeo@gmail.com'
    id='user-setting-3' />

The server then broadcasts the new setting to all resources subscribed to receive user setting updates, as described in Section 5. (Clients that previously requested settings as described in Section 3 are subscribed to receive updates.)

Receiving Settings Updates

When the server-stored settings change, the server broadcasts the new value of the setting to all resources that have previously queried settings, as described in Requesting Current Settings. The server sends an IQ set containing a <usersetting/> element qualified by the "google:setting" namespace. This stanza contains one element for each setting that has been updated. These elements are the same ones you get back with a request for a user setting as described in Requesting Current Settings.

Example 7. Server sends a user setting update

<iq type='set'
    to='romeo@gmail.com/party'
    type='set'>
  <usersetting xmlns='google:setting'>
      <archivingenabled value='true'/>
  </usersetting>
</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 stanzardized extension, and therefore may change as we work to standardize these features.