Google Talk for Developers

Jingle Server Discovery

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

  • Introduction
  • Determining Server Support
  • Requesting Server Addresses
  • Server Change Notifications
  • About Google Talk Extensions
  • Introduction

    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.

    Determining Server Support

    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' to='romeo@gmail.com' from='gmail.com'>
      <query xmlns='http://jabber.org/protocol/disco#info'>
        ...
        <feature var='google:jingleinfo'/>
        ...
      </query>
    </iq>

    Requesting Jingle Info Server Addresses

    To request the addresses of servers, a client sends an IQ get containing a <query/> element qualified by the 'google:jingleinfo' namespace, as shown here:

    Example 3. Client requests list of servers

    <iq type='get'
        from='romeo@gmail.com/orchard'
        to='romeo@gmail.com'
        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 <query/> element 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 two attributes:

    • 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'
        from='romeo@gmail.com'
        to='romeo@gmail.com/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.

    Address Change Notifications

    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 <query/> element qualified by the 'google:jingleinfo' namespace. This element contains a single <stun/> element that holds a list of <server/> elements, one for each STUN server. These elements are identical to the <server/> elements returned by the initial server address request.

    Example 5. Client receives updated list of servers

    <iq type='set'
        from='romeo@gmail.com'
        to='romeo@gmail.com/orchard'
        id='ji-update-1'>
      <query xmlns='google:jingleinfo'>
        <stun>
          <server host='host1' udp='12345'/>   
          <server host='host2' udp='12345'/>   
        </stun>
      </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.

    Authentication required

    You need to be signed in with Google+ to do that.

    Signing you in...

    Google Developers needs your permission to do that.