This document describes the XMPP extension that enables clients to query the Google Talk server for servers used to create Jingle peer-to-peer sessions.
Note: This extension is not intended to become a standard and is subject to change.
Table of Contents
When a Jingle client is behind a NAT device, it uses various techniques to create a direct connection with its peer. Some of these techniques require the use of external servers. The Google Talk Service uses a custom extension to XMPP to provide client applications with the addresses of these.
Before attempting to query for servers, 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 Jingle information extension, the reply will include the 'google:jingleinfo' feature, as shown here:
Example 2. Client service discovery response
<iq type='result' firstname.lastname@example.org' from='gmail.com'> <query xmlns='http://jabber.org/protocol/disco#info'> ... <feature var='google:jingleinfo'/> ... </query> </iq>
To request the addresses of servers, a client sends an IQ get containing
<query/> element qualified by the 'google:jingleinfo'
namespace, as shown here:
Example 3. Client requests list of servers
<iq type='get' email@example.com/orchard' firstname.lastname@example.org' id='ji-request-1'> <query xmlns='google:jingleinfo'/> </iq>
The first time this request is sent, in addition to returning the server addresses, the service will also subscribe the client to receive updates when the servers change as described below.
The server will respond to the request with a
qualified by the 'google:jingleinfo' namespace. Among other information,
this element contains one
<stun/> element that contains
a list of
<server/> elements, each of which describes
one STUN server. Each
<server/> element has the following
- host Gives the DNS name or IP address of the STUN server
- udp Gives the port on the STUN server
Example 4. Client receives list of STUN servers
<iq type='result' email@example.com' firstname.lastname@example.org/orchard' id='ji-request-1'> <query xmlns='google:jingleinfo'> <stun> <server host='host1' udp='12345'/> <server host='host2' udp='12345'/> </stun> </query> <iq>
The client application should try the servers in the order listed in the query result.
The result may contain other elements not documented here. The client should ignore these elements. Notably, this protocol includes information about relay servers; this protocol is not currently supported for discovering relay servers.
After the client requests the server addresses the first time, the server will automatically send updates of any changes to the client.
Whenever any value in any server changes, the Google Talk server will send an updated list of all the current server values. Upon receiving this notification, the client should discard all previous values and replace them with new values.
An update is an IQ set stanza containing a
qualified by the 'google:jingleinfo' namespace. This element contains
<stun/> element that holds a list of
one for each STUN server. These elements are identical to the
returned by the initial server address request.
Example 5. Client receives updated list of servers
<iq type='set' email@example.com' firstname.lastname@example.org/orchard' id='ji-update-1'> <query xmlns='google:jingleinfo'> <stun> <server host='host1' udp='12345'/> <server host='host2' udp='12345'/> </stun> </query> <iq>
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.