Jabber Protocol Overview

Peter Saint-Andre

stpeter@jabber.org

Revision History
Revision 1.12001-10-02Revised by: psa
Added details about error codes (Appendix A) as well as the section for use cases.
Revision 1.02001-04-25Revised by: psa
Initial release

An overview of the Jabber protocol as of server version 1.4.

Introduction

Jabber is an instant messaging and presence system that originated in and continues to be developed by the open-source community. One of the features that distinguishes the Jabber system from existing instant messaging (IM) services is its open XML protocol. While the core messaging and presence protocol has remained virtually unchanged since the 1.0 release of Jabber, certain extensions have been added over time. (The protocol was submitted as an RFC to the IETF's Instant Messaging and Presence Protocol working group on 2000-06-15.) This document describes the Jabber protocol as of version 1.4 of the Jabber server.

Within the context of XML streams, Jabber's open XML protocol contains three top-level XML elements:

Each of these can contain a wide variety of data through the attributes and namespaces that are part of the Jabber protocol (not to mention the opportunity for custom namespaces applying to specific applications). The full Jabber protocol is described below. For information regarding the architecture of Jabber, please refer to the companion document entitled Jabber Technology Overview.

XML Streams

A Jabber session consists of two parallel XML streams, one from the client to the server and one from the server to the client. On connecting to a Jabber server, a Jabber client initiates the client-to-server XML stream and the server responds by initiating the server-to-client XML stream. All <message/>, <presence/>, and <iq/> elements are sent within the context of these XML streams. Here is an example:

SEND:<?xml version="1.0" encoding="UTF-8" ?>

SEND:<stream:stream
SEND:to='jabber.org'
SEND:xmlns='jabber:client'
SEND:xmlns:stream='http://etherx.jabber.org/streams'>
RECV:<stream:stream
RECV:xmlns:stream='http://etherx.jabber.org/streams'
RECV:id='39ABA7D2'
RECV:xmlns='jabber:client'
RECV:from='jabber.org'>
(XML for user session goes here) *
SEND:</stream:stream>
RECV:</stream:stream>

* Note: the user session does not actually begin until the authentication information sent in an <iq/> element (specifically, a <query/> element within the 'jabber:iq:auth' namespace) has been recognized by the server.

The <message/> Element

The <message/> element is one of three top-level elements in Jabber's open XML protocol. It is used to contain messages that are sent between two Jabber users, or more generally between two Jabber IDs (since, through the magic of transports, a Jabber ID can stand for a user of another IM system, such as 70902454@icq.jabber.org).

Message types -- the 'type' attribute

Jabber supports several different kinds of message, which are specified using the 'type' attribute of <message/>. The following are the valid values of the 'type' attribute:

[default] (no 'type' attribute set)

Indicates that the message is a normal message. By default, the client assigns this type if no other type attribute is specified.

Example:

<message to="romeo@montague.net/orchard">

  <body>Wherefore art though Romeo?</body>
</message>

type="chat"

Indicates that the message should be displayed in a one-to-one chat interface (generally a line-by-line interface, although the exact interface is determined by the client).

Example:

<message to="romeo@montague.net/orchard" type="chat">
  <body>Wherefore art though Romeo?</body>
</message>

type="error"

Indicates that the message describes an error condition. The actual error is described in an <error/> element within the message. A <message/> element can contain both a <body/> and an <error/>. This is demonstrated in the following example, which shows the packet that Juliet would receive if she sent a message "hi" to a non-existent user:

Example:

<message 
    to="juliet@capulet.com" 
    from="flomeo@montague.net" 
    type="error">
  <body>hi</body>

  <error code="404">Not Found</error>
</message>

type="groupchat"

Indicates that the message should be displayed in a chat room interface.

Example:

<message to="cauldron@conference.witches.org" type="groupchat">
  <body>Double, double toil and trouble</body>
</message>

Other attributes of <message/>

In addition to setting the 'type' attribute, one may also modify the <message/> element using the following attributes:

The 'from' attribute

Identifies the sender of the message. In general the Jabber ID for the 'from' attribute must be of the form user@host/resource. From an XML perspective, this attribute is required for all <message/> elements, however in practice this attribute is added or replaced by the server (to prevent certain kinds of spoofing), so it's not something that client developers need to worry about.

Example:

<message from="juliet@capulet.com/balcony">
  <body>Wherefore art thou Romeo?</body>
</message>

The 'id' attribute

Applies a unique identifier to the message. The 'id' attribute is generated by the Jabber client or client library (e.g., WinJab or JabberCOM), and is used by the client to identify the message for tracking purposes (e.g., to correlate messages sent to a groupchat room with messages received from the room, or to connect a sent message with any errors it might generate). The 'id' attribute is optional and is not used elsewhere in the system.

Example:

<message to="romeo@montague.net/orchard" id="JCOM_85">
  <body>Wherefore art thou Romeo?</body>

</message>

The 'to' attribute

Identifies the recipient of the message. In general the Jabber ID for the 'to' attribute is of the form user@host/resource, although the form user@host is acceptable and will either resolve to user@host/resource if the recipient is online or be directed to offline storage if the user is not online. This attribute is required for all <message/> elements.

Example:

<message to="romeo@montague.net/orchard">
  <body>Wherefore art thou Romeo?</body>
</message>

Sub-elements within <message/>

The following sub-elements are used to define the content or metadata of a Jabber message.

<body/>

This element contains the main text of the message. The <body/> element may exist only once within a <message/> element and may contain only plain text. However, it may be combined with other sub-lements (such as <error/> and <x/>).

<error/>

This element is included when the message type attribute is set to "error". The error code is defined by a 'type' attribute that contains the code number, with the <error/> element itself containing a textual description of the error. The <error/> element may be combined with the <body/> element of the original message. This is demonstrated in the following example, which shows the packet that Juliet would receive if she sent a message "hi" to a non-existent user:

Example:

<message 
    to="juliet@capulet.com" 
    from="flomeo@montague.net" 
    type="error">

  <body>hi</body>
  <error code="404">Not Found</error>
</message>

The valid error codes and their canonical descriptions are shown in the Appendix.

<html/>

New in 1.4 (draft protocol!)

The <html/> element, when associated with the XHTML namespace (http://www.w3.org/1999/xhmtl), provides an alternate namespace for the body of a message, similar to the convention in the email world of sending both a plaintext and an HTML version of an email message. This functionality makes use of the XHTML Basic spec developed by the W3C, although please see the draft Jabber message formatting spec for details regarding Jabber's implementation of XHTML in messages. The root element for all XHTML markup must be <html xmlns="http://www.w3.org/1999/xhmtl"></html>. Within that root element, support for any of the elements defined in the XHTML Basic spec is allowed, although not all of those elements make sense in the context of instant messaging.

<subject/>

This optional element contains the subject of the message.

<thread/>

When a Jabber client sends a message of type "chat", it generates a unique thread ID (usually a hash of the sender's Jabber ID and the current time). Each subsequent message in the chat between the sender and recipient will include a <thread/> sub-element that contains the original thread ID. This enables the sender and recipient to identify replies and create a conversation thread. Here is an example:

<message 
    from="juliet@capulet.com/balcony" 
    to="romeo@montague.net/orchard" 
    type="chat">

  <thread>AAC96FEFDE226C2C04BE8F2E19A2151B</thread>
  <body>Art thou not Romeo and a Montague?</body>
</message>
<message 
    from="romeo@montague.net/orchard" 
    to="juliet@capulet.com/balcony" 
    type="chat">
  <thread>AAC96FEFDE226C2C04BE8F2E19A2151B</thread>

  <body>Neither, fair saint, if either thee dislike.</body>
</message>

<x/>

The <x/> element is used as an extension mechanism, or to send commands from server to client or from one client to another. Each time the element is used, a relevant XML namespace must be specified. A single message may contain multiple instances of the <x/> sub-element. The namespaces defined for use with the <x/> sub-element are as follows:

  • jabber:x:autoupdate

  • jabber:x:delay

  • jabber:x:encrypted

  • jabber:x:oob

  • jabber:x:roster

These namespaces are described more fully under Jabber namespaces below.

Here is an example, which uses the jabber:x:delay namespace to show the context of a groupchat room that one has just joined:

<message 
    type='groupchat' 
    from='cauldron@conference.witches.org'>

  <body>Thrice the brinded cat hath mew'd.</body>
  <x xmlns='jabber:x:delay' 
     stamp='10541031T21:43:40'>Cached In GC History</x>
</message>

The <presence/> Element

The <presence/> element provides availability information about a Jabber entity. Any entity identified by a Jabber ID can communicate its presence to any other entity, most commonly through a subscription to that presence.

All entities expressing presence are either available or unavailable. The 'available' state implies that the sender can immediately receive information. The 'unavailable' state indicates that the sender cannot receive any data at the current time. By default, all <presence> elements express availability unless they contain the type="unavailable" attribute. More particular forms of availability are specified using the <status/> and <show/> sub-elements.

The 'type' attribute

The 'type' attribute of the <presence/> element is used for several different purposes. In addition to the "normal" use of informing others of one's availability status, these include subscribing, unsubscribing, and probing for presence. The following are the valid values of the 'type' attribute:

type="available"

If no 'type' attribute is included, the presence packet is assumed to be of type="available". This is used to provide information about one's status while online. A presence packet of type="available" usually contains a <show/> element specifying the Jabber entity's availability type and (optionally) a <status/> element containing a human-readable description of that availability type. The presence packet may also contain a <priority/> element denoting the priority of the Jabber ID that is connected.

Example:

<presence 
    from="juliet@capulet.com/balcony" 
    to="romeo@montague.net/orchard"/>

  <show>away</show>
  <status>Stay but a little, I will come again.</status>
</presence>

The valid values of the <show/> element are:

  • away -- the Jabber user or entity is online but cannot be contacted immediately

  • chat -- the Jabber user or entity is online and is interested in chatting

  • dnd -- the Jabber user or entity is online but does not want to be interrupted ('dnd' stands for "do not disturb")

  • xa -- the Jabber user or entity is online but is away for an extended period ('xa' stands for "extended away")

The <status/> can contain any character data, and when included usually contains a description of the user's status, for example, "In a meeting" for a show value of 'away' or "Busy coding" for a show value of 'dnd'.

type="error"

If a presence packet is sent to a JID that does not exist or if an error occurs in sending the presence request, the server will return a presence packet of type="error".

Here is an example (note the type in the domain name):

<presence 
    type="subscribe" 
    to="romeo@montague.nett"/>

Example of reply:

<presence 
    from="romeo@montague.nett"
    to="juliet@capulet.com/balcony" 
    type="error">
  <error code='504'>Remote server timeout. Unable to deliver packet.</error>
</presence>

type="probe"

Make a special request for the presence information of a specific entity (i.e., without waiting for that entity to send presence information on its own). The server, not the client, processes a probe request. In fact, it is usually the server that sends a probe request, however a Jabber client could send a probe request to determine the availability of a certain Jabber user. Note that this works only if the 'from' user is on the 'to' user's roster with a subscription type of 'from' or 'both'. In the following examples, we see our hero Romeo sending a probe request to Juliet, and Juliet's server replying with a "status report" (including information in the jabber:x:delay namespace indicating the timestamp of the last presence update).

Example of probe request:

<presence 
    from="romeo@montague.net" 
    to="juliet@capulet.com"
    type="probe"/>

Example of probe reply:

<presence 
    from="juliet@capulet.com/." 
    to="romeo@montague.net">

  <status>Stay but a little, I will come again.</status>
  <show>away</show>
  <x 
      xmlns="jabber:x:delay" 
      from="juliet@capulet.com/." 
      stamp="15310309T23:47:15"/>
</presence>

type="subscribe"

Send a request that the recipient automatically send presence information to the sender whenever it changes.

Example:

<presence 
    from="romeo@montague.net" 
    to="juliet@capulet.com" 
    type="subscribe"/>

type="subscribed"

Send notice that the sender accepts the recipient's request for presence subscription. The server will now send the recipient the sender's presence information whenever it changes.

Example:

<presence 
    from="juliet@capulet.com" 
    to="romeo@montague.net" 
    type="subscribed"/>

type="unavailable"

Example:

<presence 
    from="juliet@capulet.com" 
    to="romeo@montague.net" 
    type="unavailable">

  <status>Disconnnected</status>
</presence>

type="unsubscribe"

Send a request that the recipient stop sending presence information to the sender.

Example:

<presence 
    from="juliet@capulet.com" 
    to="romeo@montague.net" 
    type="unsubscribe"/>

type="unsubscribed"

This type of presence packet has two uses:

  1. Send notice that the sender accepts the recipient's request for unsubscribing to presence information. The server will no longer send the sender's presence information to the recipient.

  2. Deny a subscription request. The server will not send the sender's presence information to person who attempted to subscribe.

Example:

<presence 
    from="romeo@montague.net" 
    to="juliet@capulet.com" 
    type="unsubscribed"/>

Other attributes of <presence/>

In addition to setting the 'type' attribute, one may also modify the <presence/> element using the following attributes:

The 'from' attribute

Identifies the sender of the presence packet. In general the Jabber ID for the 'from' attribute must be of the form user@host/resource. From an XML perspective, this attribute is required for all <presence/> elements, however in practice this attribute is added or replaced by the server (to prevent certain kinds of spoofing), so it's not something that client developers need to worry about.

Example:

<presence from="juliet@capulet.com/balcony"/>

The 'id' attribute

Applies a unique identifier to the presence packet. The 'id' attribute is generated by the Jabber client or client library (e.g., Gabber or JabberCOM), and is used by the client to identify the presence packet for tracking purposes. The 'id' attribute is optional and is not used elsewhere in the system.

Example:

<presence to="romeo@montague.net/orchard" id="JCOM_86"/>

The 'to' attribute

Identifies the recipient of the presence packet. In general the Jabber ID for the 'to' attribute is of the form user@host/resource, although the form user@host is acceptable and will either resolve to user@host/resource if the recipient is online. In normal usage within Jabber, a Jabber client sends presence packets to the server, which then sends them to all items on the user's roster. So a Jabber client will send a <presence> element without a 'to' attribute, which the server will then convert into presence packets that are sent to specific Jabber entities. This process is shown in the following examples.

Example of presence sent to server:

<presence>
  <status>Stay but a little, I will come again.</status>

  <show>away</show>
</presence>

Example of presence sent from server to specific user:

<presence 
    to="romeo@montague.net/orchard"
    from="juliet@capulet.com/balcony">
  <status>Stay but a little, I will come again.</status>
  <show>away</show>

</presence>

Sub-elements within <presence/>

The following elements are used within the <presence/> protocol.

<priority/>

In Jabber, a user can be connected to the same account (e.g., juliet@capulet.com) from multiple locations or devices, which in Jabber are known as resources. A user can assign a numerical priority to each resource (by setting a preference in the Jabber client associated with that resource), which is communicated by means of the <priority/> sub-element of the <presence/> element.

When these presence packets are sent to the server, the server is able to determine which of the connected resources associated with a single Jabber ID will receive a message sent to that Jabber ID, since the resource with the highest number is the default or primary resource. If the highest priority resource becomes unavailable, messages and other Jabber communications are sent to the resource with the next highest priority. (A client with no priority defaults to 0, and can still be the primary resource if no other resources are available.

For example, Juliet may be connected to her account juliet@capulet.com from two different resources: the balcony and the chamber. If the 'balcony' resource is set to priority="2" and the 'chamber' resource is set to priority="1" and both resources are connected, messages will go to juliet@capulet.com/balcony instead of juliet@capulet.com/chamber.

<show/>

The optional <show/> element tells other Jabber clients how to display an available user's online status. The <show> tag is typically accompanied by a <status> tag which contains a more descriptive reason for the presence change. If the <show/> element is not included in a <presence/> element, the receiving Jabber client will indicate that the user is in a "normal" state. The following four options are available:

TagMeaning
<show>chat</show>

The client is available for immediate contact.

<show>away</show>

The client is online, but is momentarily away (e.g., at lunch or a meeting).

<show>xa</show>

The client is online, but has been inactive for a long time.

<show>dnd</show>

The client is in Do Not Disturb mode.

<status/>

The <status/> element contains a more particular description of the user's online status. Most Jabber clients contain some default settings for the <status/> element; in addition, they usually allow the user to provide a personalized description such as "I'm at lunch" or "Gone fishing".

<x/>

The <x/> element is used as an extension mechanism, or to send commands from server to client or from one client to another. Each time the element is used, a relevant XML namespace must be specified. A single <presence/> element may contain multiple instances of the <x/> sub-element. The namespaces defined for use with the <x/> sub-element are as follows:

  • jabber:x:autoupdate

  • jabber:x:delay

  • jabber:x:oob

  • jabber:x:roster

  • jabber:x:signed

These namespaces are described more fully under Jabber namespaces below.

The <iq/> Element

Info/Query (IQ) structures a rudimentary conversation between any two entities in Jabber and allows them to pass XML-formatted queries and responses back and forth. The primary use is for fetching or setting common user information such as name, email, and address. However, its flexible design permits any kind of structured conversation to occur. Any entity identified by a Jabber ID can participate in an IQ conversation with any other entity.

The 'type' attribute

The 'type' attribute of the <iq/> element is used to determine the purpose of the info/query request or response. The following are the valid values of the 'type' attribute:

type="error"

Indicates that the query failed. The actual error is described in an <error/> sub-element within the <iq/> element.

Example:

<iq type="error" to="romeo@montague.net">

  <error code="403">Forbidden</error>
</iq>

type="get"

Retrieves information associated with a query namespace. This attribute is included in the query by default if no type attribute is set. An <iq/> element of type="get" is always completed by the inclusion of a sub-element, often <query> but also <vcard/> or another yet-to-be-determined sub-element. However, the appropriate sub-element may be left empty in order to retrieve a list of fields for which the client needs to provide information. The result of a successful get query is an <iq/> element of type="result" within which is nested the appropriate sub-element (e.g., <query> or <vcard/>) containing the information requested.

Example:

<iq type="get">

    <vCard xmlns="vcard-temp"/>
</iq>

type="result"

Indicates that the <iq/> packet is a successful response to an <iq/> query of type="get" or type="set". The result of a successful get query is an <iq/> element of type="result" within which is nested the appropriate sub-element (e.g., <query> or <vcard/>) containing the information requested. The result of a successful set query is an empty <iq/> element of type="result". The result of an unsuccessful get or set query is an <iq/> element of type="error". The <iq type="result"/> is usually correlated with the get or set query using the 'id' attribute.

Example:

<iq type="result">

  <vCard version="3.0" xmlns="vcard-temp">
  vCard data goes here
  </vCard>
</iq>

type="set"

Indicates that the <iq/> packet is intended to set values or replace existing values. An <iq/> element of type="set" is always completed by the inclusion of an appropriate sub-element, often <query> but also <vcard/> or another yet-to-be-determined sub-element. The result of a successful set query is an empty <iq/> element of type="result".

Example:

<iq type="set">
  <vCard version="3.0">
  vCard data goes here
  </vCard>
</iq>

Other attributes of <iq/>

In addition to the 'type' attribute, the following attributes can be used to modify the IQ element.

The 'from' attribute

Identifies the sender of the iq packet. From an XML perspective, this attribute is required for all <iq/> elements, however in practice this attribute is added or replaced by the server (to prevent certain kinds of spoofing), so it's not something that client developers need to worry about.

Example:

<iq from="romeo@montague.net"/>

The 'id' attribute

Applies a unique identifier to the iq packet. The 'id' attribute is generated by the Jabber client or client library (e.g., Gabber or JabberCOM), and is used by the client to identify the <iq/> packet for tracking purposes (e.g., to coordinate a type="result" with a type="get" or type="set"). The 'id' attribute is optional and is not used elsewhere in the system.

Example:

<iq type="get" from="juliet@capulet.com/balcony" id="JCOM_87"/>

<iq type="result" to="juliet@capulet.com/balcony" id="JCOM_87"/>

The 'to' attribute

Identifies the recipient of the iq packet. In the case of Jabber client, the Jabber ID for the 'to' attribute is of the form user@host/resource, although the form user@host is acceptable and will either resolve to user@host/resource if the recipient is online or be directed to an offline module if the user is not online. (Things are different for non-user entities such as server-side gateways, which don't have resources and are identified simply by the "server" part of a Jabber ID; an example would be jud.jabber.org, the Jabber User's Directory.) If the 'to' attribute is not included, the <iq/> packet is handled by the server.

Example:

<iq to="juliet@capulet.com/balcony">

Sub-elements of <iq/>

The following are the sub-elements of the <iq/> element.

<error/>

This element is included when the iq type attribute is set to "error". The error code is defined by a 'type' attribute that contains the code number, with the <error/> element itself containing a textual description of the error. For example, a bad request would have the following format:

<error code="400">Bad Request</error>

The valid error codes and their canonical descriptions are shown in the Appendix.

<key/>

The <key/> element provides a layer of security to client-server interactions. It is used with the jabber:iq:register and jabber:iq:search namespaces.

When a client initiates an interaction with the server, the server sends the client a <key> tag containing a unique value. When the client returns information for the <iq type="set"/>, it echoes back the unique value in the <key/> sub-element. In this way, the server can verify that the client is the same entity that received the original key.

<query/>

The <query/> sub-element within an <iq/> element defines the type of query to perform. Specifically, the query is associated with a particular namespace as defined with the 'xmlns' attribute of the <query/> sub-element. Only one <query/> sub-element may exist within an <iq/> element.

For example, here is the XML that I might send when I log onto the server using the Gabber client from my Linux machine.

<iq type="set">
<query xmlns="jabber:iq:auth">
<username>stpeter</username>

<resource>Gabber</resource>
<digest>f1e881517e9917bb815fed112d81d32b4e4b3aed</digest>
</query>
</iq>

As you can see, this authentication query uses the client authentication namespace (jabber:iq:auth) to send authentication information to the server. In general, the jabber:iq:* namespaces are reserved for the core Jabber protocols. However, developers can expand upon the core Jabber info/query functionality by adding jabber:iq:* namespaces. These issues are described more fully under Namespaces below.

An empty <query/> sub-element can be sent with an <iq type="get"/> in order to retrieve a Jabber entity's information related to the namespace specified in the <query/> sub-element. For example, to retrieve a client's roster (a.k.a. "contact list"), the following XML could be sent:

<iq to="juliet@capulet.com/balcony" type="get">

<query xmlns="jabber:iq:roster"/>
</iq>

Namespaces

The following are the standard namespaces in Jabber:

Detailed information about each of these namespaces is provided below.

jabber:iq:agent -- Agent Properties

The Agent Properties namespace obtains the properties of one agent. This is usually done after a jabber:iq:agents query (see below), to register with a specific service, agent or transport.

It might also be used to examine the detailed properties of a specific agent. For example, the client can determine if open registration is allowed.

Example:

<iq id="wjAgent" type="result" from="Jabber.org">

  <query xmlns="jabber:iq:agent">
    <agent jid="aim.jabber.org">
      <name>AIM Transport</name>
      <description>This is the AIM Transport</description>
      <transport>AIM/AOL ScreenName</transport>

      <service>aim</service>
      <register/>
    </agent>
  </query>
</iq>

jabber:iq:agents -- Available Agents List

Deprecated in 1.4 (draft protocol!)

The Available Agents List namespace obtains a list of entities that have special properties and can perform functions for another entity. Most commonly, this is used to show the list of transports available on a server.

Note: This namespace is now deprecated in favor of jabber:iq:browse.

Example:

<iq id="wjAgents" type="result" from="jabber.org">

  <query xmlns="jabber:iq:agents">
    <agent jid="users.jabber.org">
      <name>User Directory</name>
      <description>
        You may register and create a public searchable 
        profile, and search for other registered Jabber 
        users.
      </description>

      <service>jud</service>
      <register/>
      <search/>
    </agent>
    <agent jid="aim.jabber.org">

      <name>AIM Transport</name>
      <description>This is the AIM Transport</description>
      <transport>AIM/AOL ScreenName</transport>
      <service>aim</service>

      <register/>
    </agent>
  </query>
</iq>

jabber:iq:auth -- Simple Client Authentication

The Simple Client Authentication namespace is a simple mechanism for the clients to authenticate and create a resource representing their connection to the server.

Successful authentication results in an IQ type="result" response. Errors are returned in the IQ error element.

If no username or password is sent, the server will create an anonymous resource if it is supported.

Example:

<iq type="set" id="JCOM_0">

  <query xmlns="jabber:iq:auth">
    <username>juliet</username>
    <password>secret</password>
    <resource>balcony</resource>

  </query>
</iq>
<iq type="set" id="JCOM_0">
  <query xmlns="jabber:iq:auth">
    <username>juliet</username>
    <digest>a5e052c48c455bf21d937ccf17225916d9486b09</digest>

    <resource>balcony</resource>
  </query>
</iq>
<iq type="set" id="JCOM_0">
  <query xmlns="jabber:iq:auth">
    <username>juliet</username>

    <hash499>secret</hash499>
    <resource>balcony</resource>
  </query>
</iq>

jabber:iq:autoupdate -- Application Version Updates

The Application Version Update namespace enables clients to query applications about any software updates that may be available.

Example:

<iq type="get" to="jabber.org" id="1">

  <query xmlns="jabber:iq:autoupdate"/>
</iq>

jabber:iq:browse -- Jabber Browsing

New in 1.4 (draft protocol!)

The Jabber Browsing namespace provides a way to (1) add some structure to the evolving mix of Jabber IDs that exist in the world of Jabber, and (2) discover the services or applications offered by various Jabber entities. One of the basic concepts in Jabber browsing is that of a jid-type (similar to the concept of a mime-type for files). The basic top-level jid-types are envisioned to be as follows, although additional categories may be added over time:

  • application

  • conference

  • headline

  • keyword

  • render

  • service

  • user

Each of these categories may have a list of sub-types, such as user/client or user/device (where 'client'or 'device' is similar to the concept of a 'resource'), conference/irc, service/icq, and headline/stock. In general, to use the jabber:iq:browse namespace you will have an element that corresponds to one of the jid-type categories shown above, often with a 'type' attribute specifying the sub-type.

One use of jabber:iq:browse is to supplant the jabber:iq:agents namespace for listing agents or other services associated with a server. Here is an example of browsing to a server...

Jabber client sends:

<iq type="get" to="jabber.org">

  <query xmlns="jabber:iq:browse"/>
</iq>

Jabber server returns:

<iq type="result" from="jabber.org">
  <service 
      type="jabber" 
      jid="jabber.org" 
      xmlns="jabber:iq:browse>
    <service 
        type="jud"
        jid="users.jabber.org"
        name="Jabber User Directory">
      <ns>jabber:iq:register</ns>

      <ns>jabber:iq:search</ns>
    </service>
    <service 
        type="aim"
        jid="aim.jabber.org"
        name="AIM Transport">
      <ns>jabber:iq:register</ns>
      <ns>jabber:iq:search</ns>

    </service>
    <conference 
        type="private"
        jid="conference.jabber.org"
        name="Private Chatrooms">
    </service>
  </service>
</iq>

Example of use in conferencing...

<iq type="set" to="room@server">
  <conference xmlns="jabber:iq:browse" name="Room Name">

    <user jid="room@server/jidhash" name="nick1"/>
    <user jid="room@server/jidhash" name="nick2"/>
  </conference>
</iq>

jabber:iq:conference -- Generic Conferencing

New in 1.4 (draft protocol!)

The Generic Conferencing namespace provides a mechanism for discovering the features of, and negotiating entrance to, a conference room (a.k.a. groupchat room). This namespace is used in conjunction with the <iq/> element to get information about a conference room, including the information required to join that conference room, as well as to set information for the conference room (normally in order to join the room). The normal order of entering a room would therefore be as follows:

  1. Submit an iq request of type="get" to the desired room. The XML for this is as follows:

    <iq type="get" to="room@server">

  <query xmlns="jabber:iq:conference"/>
</iq>

  2. Receive an iq response of type="result" from the desired room, describing the parameters required for entrance to the room. The XML for this is as follows:

    <iq type="result" from="room@server">
  <query xmlns="jabber:iq:conference">
    <nick/>
    <secret/>
    <privacy/>

    <name>Room Name</name>
  </query>
</iq>

    All of the sub-elements of the query element here are optional. The nick element indicates that a nickname is required for entrance to the room. The secret element indicates that the user must provide a password in order to enter the room. The privacy element indicates that the conferencing server supports hiding of the user's actual Jabber ID if the user provides that element in the iq packet of type="set" (see below). The name element is the name of the room (the same name that would be shown when browsing the room using jabber:iq:browse).

  3. Send presence to the desired room. The XML for this is as follows:

    <presence to="room@server"/>

  4. Submit an iq packet of type="set" to the desired room with the information required for entrance. The XML for this is as follows:

    <iq type="set" to="room@server">
  <query xmlns="jabber:iq:conference">

    <nick>mynick</nick>
    <nick>mysecondnick</nick>
    <secret>thesecret</secret>
  </query>

</iq>

    Note that multiple nicks can be provided in case the user's first choice is taken. If no nick element is provided, the server will assign a nick.

  5. Receive notification from the room that you have joined, in the form of an iq result:

    <iq type="result" from="room@server">
  <query xmlns="jabber:iq:conference">
    <id>room@server/uniqueidnumber</id>
    <nick>mynick</nick>

  </query>
</iq>

    The unique ID number here is a hash of the user's Jabber ID.

jabber:iq:gateway -- Gateway User Address

New in 1.4 (draft protocol!)

Communications with users of non-Jabber networks are normally handled through a gateway or transport (e.g., the AIM Transport), yet each non-Jabber network may have unique user addressing, which may not be compatible with the structure of Jabber IDs. The Gateway User Address namespace makes it easier for Jabber clients to provide correct Jabber IDs when subscribing to such users. It does this by providing a structured way of negotiating and prompting the user for the information that is needed to construct a correct Jabber ID. The interaction will usually occur in the following order:

  1. Client sends an iq get to the gateway with a query for the jabber:iq:gateway namespace:

    <iq type="get" to="aim.jabber.org">
  <query xmlns="jabber:iq:gateway"/>
</iq>

  2. Server returns an iq result containing the desired prompt and descriptive text:

    <iq type="result" from="aim.jabber.org">

  <query xmlns="jabber:iq:gateway">
    <desc>
      Please enter the AOL Screen Name of the person
      you would like to contact.
    </desc>
    <prompt>Screen Name</prompt>
  </query>

</iq>

  3. Client sends an iq set to the gateway containing the appropriate information:

    <iq type="set" to="aim.jabber.org">
  <query xmlns="jabber:iq:gateway">
    <prompt>Joe Cool</prompt>
  </query>
</iq>

  4. Server returns an iq result containing the correct Jabber ID:

    <iq type="result" from="aim.jabber.org">

  <query xmlns="jabber:iq:gateway">
    <jid>JoeCool@aim.jabber.org</jid>
  </query>
</iq>

jabber:iq:last -- Last Time

New in 1.4 (draft protocol!)

The Last Time namespace provides a standard way to query a Jabber entity about the uptime of a server or service, or the last time that a client was connected to (or active on) a server. In each case, the returned value is a number of seconds. This information can be interpreted by the querying entity according to the following rules:

  • user@server/resource -- time since client was last actively used

  • user@server -- time since user was last connected

  • server -- time since server was last started

Example (server):

<iq type="get" to="jabber.org">

  <query xmlns="jabber:iq:last"/>
</iq>

<iq type="result" to="stpeter@jabber.org/Gabber" from="jabber.org">
  <query xmlns="jabber:iq:last" seconds="124933"/>
</iq>

Example (client):

<iq type="get" to="jer@jabber.org">
  <query xmlns="jabber:iq:last"/>

</iq>

<iq type="result" to="stpeter@jabber.org/Gabber" from="jer@jabber.org">
  <query xmlns="jabber:iq:last" seconds="5024">
    Disconnected
  </query>
</iq>

jabber:iq:oob -- Out of Band Data

The Out of Band Data namespace gives clients a standard way to do client-to-client file transfers. A distinct namespace will be implemented for server passthrough/proxy transfer.

Example:

<iq type="set" to="horatio@denmark.com" id="file_1">

  <query xmlns="jabber:iq:oob">
    <url>http://denmark.com/act4/letter-1.html</url>
    <desc>There's a letter for you sir.</desc>
  </query>
</iq>

jabber:iq:private -- Private Data Storage

Updated in 1.4 (draft protocol!)

The Private Data Storage namespace provides a mechanism for storing private data on the Jabber server. The data stored can be anything, as long as it is valid XML. The typical usage for this namespace might be to store client preferences on the server-side.

Example 1 (Client Storing Private Data):

<iq type="set" id="1001">

  <query xmlns="jabber:iq:private">
    <winjab xmlns="winjab:prefs">
    <defaultnick>Hamlet</defaultnick>
    </winjab>
  </query>

</iq>

Example 2 (Client Retrieving Private Data):

<iq type="get" id="1002">
  <query xmlns="jabber:iq:private">
    <winjab xmlns="winjab:prefs"/>
  </query>
</iq>

In addition to Private Data Storage, the 1.4 server includes the capability to store publicly-accessible XML on the server in any valid namespace (namespaces beginning with "jabber:" are reserved for use by the Jabber system). This data is stored in the roster of the user who sends the iq type="set" packet to the server.

Example 1 (Client Storing Public Data):

<iq type="set" id="1003">

  <query xmlns="stpeter:public:favorites">
    <fav_things>
    <food>Thai</food>
    <color>blue</color>
    <composer>Bach</composer>

    </fav_things>
  </query>
</iq>

Example 2 (Client Retrieving Public Data):

<iq type="get" id="1004">
  <query xmlns="stpeter:public:favorites">
    <fav_things/>
  </query>

</iq>

jabber:iq:register -- Registration Requests

The Registration Requests namespace registers with a server or service. The Registration namespace is also used to update or remove a registration.

Example:

<query xmlns="jabber:iq:register">
  <instructions>
      Some instructions to be displayed when the 
      user is filling out the form.
  </instructions>
  <username/>
  <password/>

  <email/>
  <date/>
  <key/>
</query>

jabber:iq:roster -- Contact List Management

The Contact List Management namespace is used by clients to manage their roster, which is stored on the server so that the user can access it from any location. The roster is the authoritative list of subscription information for this account, including the user's nickname and contact list. When the user logs in from any resource, the roster is sent from the server to the client.

The roster consists of a list of items. Each item element may have attributes describing it. Each item element may contain group elements for each group of which it is a part. The attribute descriptions for the <item/> element are as follows:

  • "jid" is the Jabber ID of the item.

  • "subscription" is the current status of the subscription related to this item. It can be 'none' (no subscription), 'to' (we have a subscription to this item), 'from' (they have a subscription to us), 'both' (to and from), or 'remove' (for requests to remove a item from the roster).

  • "ask" is the current status of a request to this item. It can be Subscribe or Unsubscribe indicating that a request is being sent to this item for a subscription or a subscription cancellation.

  • "name" is a nickname.

Using an <iq type="set"/>, a Jabber client can control the user's JabberID, name attributes, and group elements, and can create or remove items from the contact list. All other attributes are managed by the server depending on how a client responds to presence subscription requests.

Example of a Subscription Request:

<iq type="set" id="uniquevalue">

  <query xmlns="jabber:iq:roster">
    <item jid="romeo@montague.net" 
        name="Romeo" 
        subscription="none" 
        ask="subscribe">
      <group>friends</group>
    </item>
  </query>

</iq>

Whenever a roster item changes in any way on the server, it is pushed to a client. This push is a normal <iq type="set"/> packet sent from the server to the client. Here is an example:

<iq type="set">
  <query xmlns="jabber:iq:roster">
    <item jid="romeo@montague.net" subscription="both"/>
  </query>
</iq>

In the above example, the server sends a roster push to a client to express that the client has a subscription to the presence of romeo@montague.net. A roster push can happen at any time during the connection as a result of another connection modifying the resource or the server modifying the subscription attribute. The client only uses roster pushes to modify the display of the roster. It does not react or prompt the user for every roster push.

jabber:iq:search -- User Database Searching

Any agent can be a search agent. For example, JUD searches for Jabber users, and the ICQ transport searches for ICQ users.

To initiate a search, the client sends a Get query to obtain the searchable fields:

<iq 
    type="get" 
    id="1001" 
    to="users.jabber.org" 
    from="romeo@montague.net/orchard">

  <query xmlns="jabber:iq:search"/>
</iq>

The search agent returns the fields that can be searched:

<iq type="result" id="1001" from="users.jabber.org">
  <query xmlns="jabber:iq:search">
    <instructions>Fill in a field to search for any 
        matching Jabber User
    </instructions>
    <name/>

    <first/>
    <last/>
    <nick/>
    <email/>
    <key>067941fd96a6a2752a21abcb6d737130dd51dd50</key>

  </query>
</iq>

Notice that the fields are returned in a form with instructions. A key is included to provided security to the transaction (see below). The user can now enter search criteria into the form based on the available fields. The client sends a Set query back to the agent to have it actually perform the search:

<iq 
    type="set" 
    id="1002" 
    to="users.jabber.org" 
    from="romeo@montague.net/orchard">
  <query xmlns="jabber:iq:search">
    <last>Capulet</last>
    <key>11b830e604215c3a2a24652c69fd4efa2a7a5746</key>

  </query>
</iq>

The server returns the results from the query:

<iq type="result" id="1002" from="users.jabber.org">
  <query xmlns="jabber:iq:search">
    <item jid="juliet@capulet.com">
      <name>Juliet Capulet</name>

      <first>Juliet</first>
      <last>Capulet</last>
      <nick>juliC</nick>
      <email></email>

    </item>
    <item jid="sampson@capulet.com>
      <name>Sampson Capulet</name>
      <first>Sampson</first>
      <last>Capulet</last>

      <nick>sammy</nick>
      <email></email>
    </item>
  </query>
</iq>

Notice that there are two sets of items tags containing identical information. This is because there are two ways for agents to send results:

  • A single result tag

  • Multiple results "pushed" to the client, similar to roster pushes, i.e., one record at a time.

The manner in which the results are sent is a property of the search agent. For example:

<iq type="set" from="icq.jabber.org" id="1003">

  <query xmlns="jabber:iq:search">
    <item jid="7090245@icq.jabber.org">
      <email>juliet@capulet.com</email>
      <nick>juliC</nick>
      <given>Juliet</given>

      <family>Capulet</family>
    </item>
  </query>
</iq>

Multiple results can be pushed by the server. When all data has been sent, the server sends the following result:

<iq type="result" from="icq.jabber.org" id="1003">
  <query xmlns="jabber:iq:search"/>

</iq>

The client receives multiple "sets", one per record, and then a final "result" indicating the "end of data". In each <item> tag, the JID attribute is mandatory.

Example:

<iq 
    type="get" 
    id="1001"
    to="users.jabber.org" 
    from="juliet@capulet.com">
  <query xmlns="jabber:iq:search"/>
</iq>

jabber:iq:time -- Client Time

The Client Time namespace gives clients a standard way to exchange local time.

Example:

<iq type="result" from="stpeter@jabber.org">

  <query xmlns="jabber:iq:time">
    <utc>20010214T18:55:06</utc>
    <display>2/15/00 4:55:06 PM</display>
  </query>
</iq>

jabber:iq:version -- Client Version

The Client Version namespace gives clients a standard way to find out version information for another user's client.

Example:

<iq type="result" from="stpeter@jabber.org/Gabber">

  <query xmlns="jabber:iq:version">
    <name>Gabber</name>
    <version>0.8.1 (Powered by: jabberoo 1.0.0</version>
    <os>Linux 2.2.16-22 i686</os>

  </query>
</iq>

jabber:x:autoupdate -- Application Version Notifications

The Application Version Notifications namespace enables the update server to notify clients that a new version of the application is available.

Example:

<message from="winjab.sourceforge.net">
  <x xmlns="jabber:x:autoupdate">A new version of WinJab 
    is available, see http://winjab.sourceforge.net/
  </x>
</message>

jabber:x:conference -- Conferencing Invitations

New in 1.4 (draft protocol!)

The Conferencing Invitations namespace enables users to invite other Jabber users to a specific conference room. The relevant information, specifically the Jabber ID of the conference room, is embedded within the <x/> element of a message.

Example:

<message to="romeo@montague.net" from="juliet@capulet.com">

  <body>Wherefore art thou Romeo?</body>
  <x xmlns="jabber:x:conference" jid="balcony@conference.capulet.com/>
</message>

jabber:x:delay -- Mark Object as Delayed

The Mark Object as Delayed namespace is used to provide timestamp information about messages and presence information that is stored for later delivery when sent to a Jabber entity that is not online. When the entity comes online, this namespace includes information that enables the Jabber client to display the time when the packet was originally sent, not when it was delivered to the Jabber entity.

Example:

<message 
    type='groupchat' 
    from='cauldron@conference.witches.org'>
  <body>Thrice the brinded cat hath mew'd.</body>

  <x xmlns='jabber:x:delay' 
     stamp='10541031T21:43:40'>Cached In GC History</x>
</message>

jabber:x:encrypted -- Encrypted Message

New in 1.4 (draft protocol!)

The Encrypted Message namespace is used to support the exchange of messages that are encrypted using the public key infrastructure (normally implemented using PGP or GPG on the client side, although server-side encryption could also use this namespace). A related namespace, jabber:x:signed, is used to support the encryption of presence information.

Example:

<message from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard'>
  <body>This Message is Encrypted</body>

  <x xmlns='jabber:x:encrypted'>
hQEOA7ucqu53AhlPEAP/ZbU6oPnRAbIcUxMK1XRVnkgZ/Agtq1tcTQuEZxbpZLl4
C/4psQGLgBU5h5Y3/khxtJTPXKn1izyc+DRZ8hqn2p4mwC8ioKTBJ6P6dfEpQEyt
a4bimM5fqdeh4gRkMhwThRSJxBCJBVVWFEViu+0KlHHB5AeeL4qwRGb2dhGjIgQD
/R9x0D0qtgBGwf/TVnRGZYRX7epxCNuNDEYKZSs4LEoTPL8CVsAWOzS2QgS0GBqt
tFDKId6XaNu36dB2D8VHdxQnI8RtHo9pfTYDaXWB3dMGTt896iEO/sTuucYObf3s
K5Kygg0uWpBpvQPj8Y041FhnUBz8DRGCnuFLQxCI6ch4ybauXfOKNOGDQwmsnJZm
6OaeVFUwdsedI3c6VdQtodnWVutckR5BOjnn0VqnhrVTu7cp6VXrrRK4g9atPEe6
C4R/MilBjzIJBcET0jhWuAyiBo3gN/6IqYRZNSXL9ZqGPJwNTlYim1EHN3qBqiUw
zUMamEoRzcusn80Z7kylve5ujIeSD/pVwoawHHvLp92kO2hd0yGD0UrWSfKU1o6y
EY8yhZ5P1v02pIKigAUI2c6LTDxt/KhSxQ==
=fijN
  </x>
</message>

jabber:x:envelope -- Message Envelope

New in 1.4 (draft protocol!)

The Message Envelope namespace provides a way to express richer addressing of messages, such as those normally associated with email. The supported elements in this namespace are as follows:

  • to

  • cc

  • replyto

  • from

  • forwardedby

Each of these elements carries a 'jid' attribute to identify the Jabber entity that is sending, forwarding, or receiving the message.

Example:

<message from='juliet@capulet.com/tomb' to='romeo@montague.net/tomb'>

  <body>And there I am. Where is my Romeo?</body>
  <x xmlns='jabber:x:envelope'>
    <to jid='romeo@heaven.org>Romeo</to>
    <forwardedby jid='root@heaven.org>God</forwardedby>

  </x>
</message>

jabber:x:event -- Message Events

New in 1.4 (draft protocol!)

The Message Events namespace provides a mechanism for identifying the status of a message. Currently, the events associated with a message are as follows:

  • <composing/> -- a user is currently composing a reply to a message

  • <delivered/> -- the message has been delivered to the intended recipient

  • <displayed/> -- the message has been displayed to the intended recipient

  • <offline/> -- the message has been stored offline

Support for these message events is optional at the client level, and message events should be sent only if the other client in the conversation requests them. Different Jabber clients will present message event information in different ways.

Example of request for event notification:

<message 
    from="juliet@capulet.com/balcony" 
    to="romeo@montague.net/orchard"
    id="1001">

  <body>By whose direction found'st thou out this place?</body>
  <x xmlns="jabber:x:event">
    <composing/>
  </x>
</message>

Example of sending event notification:

<message from="romeo@montague.net/orchard" to="juliet@capulet.com/balcony">

  <body>By whose direction found'st thou out this place?</body>
  <x xmlns="jabber:x:event">
    <composing/>
    <id>1001<id/>
  </x>

</message>

Multiple messaging events can be requested simultaneously.

jabber:x:expire -- Message Expiration

New in 1.4 (draft protocol!)

The Message Expiration namespace provides a simple extension to indicate that a message has a limited lifetime. If the message is stored offline and the expiration date has passed, the server will not deliver the message. Alternatively, if the message has been delivered but not yet viewed, a Jabber client has the option of not showing the message. The 'seconds' attribute dentifies a time relative to the moment when the message was sent.

Example:

<message from="sailor@denmark.com" to="horatio@denmark.com">
  <body>There's a letter for you sir</body>
  <x xmlns="jabber:x:expire" seconds="3600"/>
</message>

jabber:x:oob -- Out of Band Data

The Out of Band Data namespace enables clients to exchange a standard URI with a description for the purpose of file transfers. URIs exchanged using jabber:x:oob can be included with any message (inside an <x/> sub-element) and act as an attachment in the sense familiar from email. Multiple attachments can be included in one message.

Example:

<message from="sailor@denmark.com" to="horatio@denmark.com">
  <body>URL Attached.</body>
  <x xmlns="jabber:x:oob">
    <url>http://denmark.com/act4/letter-1.html</url>

    <desc>There's a letter for you sir</desc>
  </x>
</message>

jabber:x:roster -- Embedded Roster Items

The Embedded Roster Items namespace enables a user to include roster items within a message, thus making it easy to send contacts from one user to another. Each roster item is contained in an <item/> sub-element within an <x/> element. In normal usage, the <x/> element is included in a <message/> element, but this is not required.

Example:

<message to="hamlet@denmark.com">

  <body>
      Here are some new Jabber users 
      to add to your contact list!
  </body>
  <x xmlns="jabber:x:roster">
    <item jid="claudius@denmark.com" name="King">
      <group>Royalty</group>

    </item>
    <item jid="horatio@denmark.com" name="Horatio">
      <group>Friends</group>
    </item>
    <item jid="fortinbras@norway" name="Prince Fortinbras"/>

  </x>
</message>

jabber:x:signed -- Signed Presence

New in 1.4 (draft protocol!)

The Signed Presence namespace is used to support the exchange of presence information that is encrypted using the public key infrastructure (normally implemented using PGP or GPG on the client side, although server-side encryption could also use this namespace). A related namespace, jabber:x:encrypted, is used to support the encryption of messages.

Example:

<presence from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard'>
  <show>away</show>

  <status>be back later</status>
  <x xmlns='jabber:x:signed'>
  iD8DBQA6kasv0xpc2/POfPkRAnz0AJ9UEYYWWSReddIKk3AYMfTFtqQDJwCfbcLd
  JcSUOR0FlS+rDFjAPaSMgSM+iNaNm
  </x>
</presence>

vcard-temp -- Temporary vCard

The vCard format is a "standard format for electronic business card data, useful for exchange of personal directory data across the Internet, as well as in non-Internet environments." Since the XML vCard format has not been standardized as of this writing, the Jabber.org Project has put forth a temporary namespace for use within Jabber until the establishment of an XML vCard standard. Because no progress has been made on an official vCard XML standard in several years, the Jabber.org developers have created a dedicated website for this project in hopes of garnering attention from developers outside the Jabber community. Therefore the latest DTD for the XML vCard format may always be found at the following URL:

http://www.vcard-xml.org/

Example 1 (Client queries for vCard):

<iq type="get">

  <vCard xmlns="vcard-temp"/>
</iq>

Example 2 (Client receives vCard data):

<iq type="result">
  <vCard version="3.0" xmlns="vcard-temp">
    vCard data goes here
  </vCard>
</iq>

Example 3 (Client sends vCard to server):

<iq type="set">

  <vCard version="3.0">
    vCard data goes here
  </vCard>
</iq>

Use Cases

This section provides a slightly different perspective on the Jabber protocol: that of use cases. Each of the following scenarios shows the flow of messages sent and received in order for a Jabber user to complete a task such as register with a server, log in, change presence, or send a message. I will be building this section out further as time allows.

Jabber user registers

This use case also shows the Jabber user opening a socket to the server and the server responding (i.e., the <stream:stream> tags).

  1. The Jabber User requests a socket on the server by opening an XML stream from the client to the server.

    SEND: <stream:stream 
        to='capulet.com' 
        xmlns='jabber:client' 
        xmlns:stream='http://etherx.jabber.org/streams'>

  2. The server replies by opening an XML stream from the server to the client.

    RECV: <stream:stream 
        from='capulet.com' 
        id='180763465' 
        xmlns='jabber:client' 
        xmlns:stream='http://etherx.jabber.org/streams'>

  3. The Jabber User provides the information required to register an account (in theory, this would require a different sequence: first askign the server what information is required, then being informed regarding what information is required; however, in practice it is assumed that the required information is username, resource, and password).

    SEND: <iq id='1' type='set'>

        <query xmlns='jabber:iq:register'>
          <username>juliet</username>
          <resource>balcony</resource>
          <password>r0m30</password>

        </query>
      </iq>

  4. The server responds with an empty iq element of type "result", indicating that the registration was successful.

    RECV: <iq id='1' type='result'/>

Jabber user logs in

  1. The Jabber User queries the server to discover what information is required in order to log in.

    SEND: <iq id='2 type='get'>
        <query xmlns='jabber:iq:auth'>
          <username>juliet</username>

        </query>
      </iq>

  2. The server informs the Jabber User what information is required in order to log in.

    RECV: <iq id='2' type='result'>
        <query xmlns='jabber:iq:auth'>
          <username>juliet</username>

          <password/>
          <digest/>
          <sequence>500</sequence>
          <token>3B905BFD</token>
          <resource/>

        </query>
      </iq>

  3. The Jabber User provides the required information -- in this case, the <hash/> element, which is a hash of the information required for zero-knowledge authentication (for details, see http://docs.jabber.org/draft-proto/html/zerok.html).

    SEND: <iq id='3' type='set'>
        <query xmlns='jabber:iq:auth'>

          <username>juliet</username>
          <resource>balcony</resource>
          <hash>77d7eacde5e56b9622d0a075cb88361b110fb9d7</hash>
        </query>

      </iq>

  4. The server responds with an empty iq element of type "result", indicating that the registration was successful.

    RECV: <iq id='3' type='result'/>

  5. The Jabber User sends presence to the server announcing that she is online.

    SEND: <presence>
        <status>Online</status>
      </presence>

Jabber user adds a contact

  1. The Jabber client adds the contact to the roster (this is only preliminary).

    SEND: <iq type='set'>

        <query xmlns='jabber:iq:roster'>
          <item 
	    jid='romeo@montague.net' 
	    name='romeo'/>
        </query>
      </iq>

  2. The Jabber User sends a subscription request to the contact.

    SEND: <presence to='romeo@montague.net' type='subscribe'>
        <status>Wherefore art thou?</status>

      </presence>

  3. The server sends a roster push to the client with the new item and a subscription type of "none" (this is really a placeholder state).

    RECV: <iq type='set'>
        <query xmlns='jabber:iq:roster'>
          <item 
	    jid='romeo@montague.net' 
	    name='romeo' 
	    subscription='none'/>
        </query>
      </iq>

  4. The server sends an iq packet of type result indicating the success of the roster push (somewhat confusingly, this packet is sent from the Jabber User to the Jabber User!).

    RECV: <iq 
        from='juliet@capulet.com/balcony' 
        to='juliet@capulet.com/balcony' 
        type='result'/>

  5. The server sends another roster push, this time with the attribute ask='subscribe' to indicate the pending state of the subscription.

    RECV: <iq type='set'>

        <query xmlns='jabber:iq:roster'>
          <item 
	    ask='subscribe' 
	    jid='romeo@montague.net' 
	    name='romeo' 
	    subscription='none'/>
        </query>
      </iq>

  6. What happens next depends on how Romeo replies to the subscription request. For now we'll assume that the subscription is "consummated" by having Romeo accept the subscription request:

    RECV: <presence 
        from='romeo@montague.net' 
        to='juliet@capulet.com'
	type='subscribed'/>

  7. The server sends one more roster push to the client, this time with the subscription='to' in order to indicate that the subscription request has been accepted (Juliet is now subscribed TO Romeo's presence).

    RECV: <iq type='set'>

        <query xmlns='jabber:iq:roster'>
          <item 
	    jid='romeo@montague.net' 
	    name='romeo' 
	    subscription='to'/>
        </query>
      </iq>

Jabber user gets roster

SEND: <iq type='get'>
        <query xmlns='jabber:iq:roster'/>

      </iq>

RECV: <iq from='juliet@capulet.com/balcony' type='result'>
        <query xmlns='jabber:iq:roster'>
          <item 
	    jid='romeo@montague.net' 
	    name='romeo' 
	    subscription='both'/>
        </query>
      </iq>

Jabber user sends a message

SEND: <message to='romeo@montague.net'>

        <body>Wherefore art thou?</body>
      </message>

Note: the server adds a from address based on the session information of the Jabber User, so that when the intended recipient receives the message it contains the from address.

Jabber user changes availability

SEND: <presence>
        <status>stepped away...</status>

        <show>away</show>
      </presence>

Jabber user logs off

Logging off is easy, just close the <stream>...

SEND: </stream:stream>

RECV: </stream:stream>

References

The following materials were used in putting together this protocol guide:

Conclusion

This document has provided a detailed overview of Jabber's XML protocol. If you have any questions about this document, feel free to contact its author (Peter Saint-Andre) via email or Jabber at stpeter@jabber.org.

Copyright Information

This document is copyright 2001 by Peter Saint-Andre.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation, with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy of the GNU Free Documentation License from the Free Software Foundation by visiting http://www.fsf.org/ or by writing to:

The Free Software Foundation, Inc.
59 Temple Place - Suite 330
Boston, MA 02111-1307
USA

Appendix A. Standard Error Codes

What follows is a brief description of the error codes defined in Jabber. These error codes are generated by Jabber servers when various error conditions are met. In general the Jabber error codes are based on those defined in the HTTP spec, RFC 2616 (http://www.ietf.org/rfc/rfc2616.txt). However, Jabber does not use the full range of HTTP error codes, and the Jabber error codes, while related to the HTTP codes, often have Jabber-specific meanings. Note that this Appendix covers the Jabber error codes only as they are generated by Jabber servers, and not by server-side components such as gateways to other instant messaging systems.

Error CodeDescriptionNotes

302

Redirect

Whereas the HTTP spec contains eight different codes for redirection, Jabber contains only one (which is intended to stand for any redirection error). However, Jabber code 302 is being reserved for future functionality and is not currently in use.

400

Bad Request

Jabber code 400 is used to inform Jabber clients that a request could not be understood by the server because of malformed syntax. This might be generated when, for example, a Jabber client sends a subscription request to itself or sends a message that does not have a 'to' attribute.

401

Unauthorized

Jabber code 401 is used to inform Jabber clients that they have provided incorrect authorization information, e.g., an incorrect password or unknown username when attempting to log in to a Jabber server.

402

Payment Required

Jabber code 402 is being reserved for future use and is not implemented at this time.

403

Forbidden

Jabber code 403 is used by a Jabber server to inform a Jabber client that the client's request was understood but that the server is refusing to fulfill it. This is currently used only when password storage fails during registration.

404

Not Found

Jabber code 404 is used when the Jabber server has not found anything matching the JabberID to which a Jabber client's packet was sent. E.g., a user has attempted to send a message to a JabberID that does not exist. If the Jabber server of the intended recipient cannot be reached, an error code from the 500 series will be sent.

405

Not Allowed

Jabber code 405 is used when the action is not allowed for the JabberID identified by the 'from' address. This might be generated when, for example, a non-admin user attempts to send an administrative message on the server, or when a user attempts to set the time or version of a Jabber server, or to set the vCard of a different JabberID.

406

Not Acceptable

Jabber code 406 is used when a packet is for some reason not acceptable to the server. This might be generated when, for example, a Jabber client attempts to store information on the server using jabber:iq:private, but the custom namespace for storage begins with "jabber:" (a reserved start to XML namespaces in Jabber). Another situation that might generate a 406 error is when a Jabber client attempts to register with a Jabber server using an empty password.

407

Registration Required

Jabber code 407 is not currently in use.

408

Request Timeout

Jabber code 408 is returned by a Jabber server when a Jabber client did not produce a request within the time that the server was prepared to wait. This code is currently used only by the zero-knowledge authentication module with the Jabber Session Manager.

409

Conflict

Jabber code 408 is returned by a Jabber server when a Jabber client did not produce a request within the time that the server was prepared to wait. This code is currently used only by the zero-knowledge authentication module with the Jabber Session Manager.

500

Internal Server Error

Jabber code 500 is used when a Jabber server encountered an unexpected condition which prevented it from handling a packet from a Jabber client. Right now the only event that triggers a 500 error code is when a Jabber client attempts to authenticate with the server and that authentication request is not handled for some reason (e.g., the password could not be stored).

501

Not Implemented

Jabber code 501 is used when the server does not support the functionality being requested by a Jabber client. For example, this code is sent only when a Jabber client sends an authentication request that does not contain the elements defined by at least one of the authentication methods defined in the server configuration. This code is also used only when a Jabber client attempts to register with a Jabber server that does not allow registration.

502

Remote Server Error

Jabber code 502 is used when delivery of a packet fails because of an inability to reach the intended remote server. Specific examples of why this code is sent include a failure to connect to the remote server, an inability to resolve the hostname of the remote server, and an internal timeout caused by problems with the remote server.

503

Service Unavailable

Jabber code 503 is used when a Jabber client requests a service that a Jabber server is currently unable to handle, usually for temporary reasons. E.g., if a Jabber client attempts to send a message to a user who is offline but the recipient's server is not running an offline message storage service, the server would return a 503 error code to the sending JabberID. This error code is also sent if there are errors in writing to data storage via xdb when setting information in the vcard-temp and jabber:iq:private namespaces.

504

Remote Server Timeout

Jabber code 504 is used when attempts to contact a server timeout, e.g., when an incorrect server name is specified.

510

Disconnected

Jabber code 510 is not yet in use.


  © Copyright 2000 Jabber.org - All Rights Reserved
Legal Notices   /   Credits   /   Contact Us