Note:This document is out of date. For complete information about Jabber protocols and technologies, refer to the XMPP RFCs as well as to JSF-approved protocols. --stpeter

 

The Jabber Programmers Guide

A Comprehensive Snapshot of Jabber

Thomas "temas" Muldowney

temas@box5.net

Eliot "e-t" Landrum

eliot@landrum.cx

Peter
Millard
Technology Overview

Max
"Fingolfin"
Horn

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 their Web site or by writing to: The Free Software Foundation, Inc.; 59 Temple Place - Suite 330; Boston, MA 02111-1307; USA.


Table of Contents
1. Preface
What is Jabber?
Who Should Read This Book
Organization of this Book
Conventions Used in This Book
Comments and Questions
How to Contact Us
Acknowledgements
Eliot Landrum
2. Cast of Characters
3. Technology Overview
Introduction
Basic Concepts
XML
Distributed Architecture
Jabber Architecture
Jabber Clients
Jabber Servers
Transports
Etherx "Router" Component
How it All Works
XML Protocols
User Identification, Accounts, etc.
User Accounts
Jabber IDs
Clients
Simple Clients
Extensible Feature Sets
Online Presence, Rosters, Subscriptions
4. Entity Identification
Three Tier
Host (server)
Node (user)
Resource
URI
5. Connecting to the Server
XML Streams DTD
6. Group Chat Overview
The Basics
Introduction
Identification
Presence
Messages
Subscribing to Groups
Privacy Note
Examples
7. Auto Update
Introduction
Process
8. Core Protocol Elements
Jabber DTD
9. IQ Namespaces
jabber:iq:autoupdate — application version updates
jabber:iq:agent — interactive server component properties
jabber:iq:agents — method to query interactive server components
jabber:iq:auth — simple client authentication
jabber:iq:oob — out of band data
jabber:iq:private — method to store private data on the server
jabber:iq:register — method for interactive registration
jabber:iq:roster — client roster management
jabber:iq:search — method for searching a user database
jabber:iq:time — method for requesting the current time
jabber:iq:version — method for requesting version
Temporary vCard — electronic business card exchange
10. X Namespaces
jabber:x:autoupdate — client update notification
jabber:x:delay — mark object as delayed
jabber:x:oob — out of band data (attachment)
jabber:x:roster — roster items within a message
11. Protocol Elements
address — the address of a Jabber user
agent — wrapper element used to describe a server agent
beta — indicates a beta software release
body — the body of a message
city — the home city of a Jabber user
date — a date related to a Jabber user
desc — element used to describe a URL
description — element used to describe a server agent
dev — indicates a development software release
digest — secure method of passing a password
display — used to specify the current time in a friendly format
email — the email address of a Jabber user
error — element used to communicate an error
first — the first name of a Jabber user
group — a roster group that an item belongs to
groupchat — indicates that a service has groupchat capabilities
instructions — used to give instructions to the user
item — a roster item
iq — structured wrapper around anonymous XML data
key — IQ spoof protection
last — the last name of a Jabber user
message — element used for all messages
misc — wrap misc information an agent needs for registration
name — element used for a descriptive name
nick — friendly name of a user
os — the operating system of an entity
password — element used in conjunction with username
phone — the phone number of a Jabber user
presence — control over user availability and subscriptions
priority — the ability to rank a user's presence
query — place holder for iq structures
register — element used to indicate that a service can be registered with
registered — element used to indicate that one is already registered with a service.
release — indicates a stable software release
remove — element used to indicate to a service that the specified account should be removed
resource — element used to set resource
search — indicates that a service has user searching capabilities
service — element used to classify server agents
show — exact user availability
state — the home country of a Jabber user
status — availability message
subject — the subject of a message
text — wrap any text an agent needs for registration
thread — an id representing the thread of a message
transport — element used to describe the native title of a username
truncated — element used to indicate that search results were prematuraly ended
tz — used to specify the timezone of the sending party
url — element used to wrap a Universal Resource Locator (URL)
utc — used to specify the current time
username — element used to user identification
version — the version of a Jabber entity's application
x — place holder for extension structures
zip — the zip code of a Jabber user
Glossary
12. About
Eliot Landrum
List of Tables
11-1. Error Codes
11-1. Service Types
List of Examples
5-1. Opening the Stream
5-2. Server Response
5-3. End of Stream
6-1. Initial Presence
6-2. Join Message
6-3. Participant's Presence
6-4. Group Message (from)
6-5. Presence Change
6-6. Presence Change (quit)
6-7. Quit Message
6-8. Group Message (to)
6-9. Private Message (to)
6-10. Private Message (from)
6-11. Presence Change (quit - send)
6-12. Presence Change (quit - received)
7-1. Current Information
7-2. New Version Available
7-3. Client Requests New Information
7-4. Server Sends New Information
9-1. Client Request For Agent
9-2. Agent Reply
9-1. Request Agents List From Server
9-2. Agents Reply From Server
9-1. Client Authentication (plain password)
9-2. Client Authentication (digest password)
9-3. Successful Client Authentication
9-4. Unsuccessful Client Authentication
9-1. Sending the initial URL.
9-1. Client Storing Private Data
9-2. Server Response (successful)
9-3. Client Retrieval
9-4. Server Response
9-1. Client Request
9-2. Server Response (unregistered)
9-3. Client Registration
9-4. Server Response (already registered)
9-5. Client Request for Removal
9-1. Server Push of New Subscription
9-2. Request for Entire Roster
9-3. Result of Roster Request
9-4. Removing a User from Roster
9-5. Server Response to User Remove
9-1. Client Request
9-2. Server Response
9-3. Client Query
9-4. Search Results
9-5. Search Results (no results)
9-1. Request from client for time information.
9-2. Queried client response.
9-1. Client Request
9-2. Queried Client Response
9-1. Setting the vCard
9-2. Fetching a vCard
9-3. Server Response to Query
10-1. Delayed Presence
10-2. Delayed Message
10-1. Sending a Web URL
10-1. Sending Roster Items in a Message
11-1. Error In a Message
11-2. Error In an IQ
11-1. Client Request For Agent
11-2. Agent Reply
11-1. Simple Query
11-2. Result to Previous Example
11-3. Setting Information
11-4. Result to IQ Set
11-1. Basic Jabber Message
11-2. Basic Jabber Message Using XHTML Basic
11-3. Complete Jabber Message
11-4. Reply to Complete Jabber Message
11-1. Initial Presence
11-2. Request to Subscribe
11-3. Response to Subscribe Request
11-4. Complete Presence Information
11-1. Remove account from the Jabber AIM service (notice that the key must be returned to the server).

Chapter 1. Preface

What is Jabber?

Give an overview of what Jabber is, how it started, how it works, how it's based on existing protocols and standards, etc.


Who Should Read This Book

Define the audience - programmers doing what?


Organization of this Book

Guides the reader through the contents of the book, with a chapter listing and brief explanation of what the reader can expect to learn from each chapter.


How to Contact Us

Provide contact info for yourselves, and possibly information on how people can submit changes to the text, seeing as how your book will be under an open license.


Acknowledgements

A huge thanks goes to the entire Jabber.org community. Through their continued hacking, discussion and using Jabber, the project has been sucessful beyond our dreams. Special thanks goes out to Max Horn for his fantastic edits and improvements to this text, Peter Millard for streching the protocol to its limit (and often beyond!) and Julian Missig for his commitment to clean UI and beautiful XML (not to mention his outstanding Jabber XML Schema's used in this book).


Eliot Landrum

Above anyone else, my parents Delhi and Linda Landrum must be thanked for the incredible amount of support and guidance throughtout my life. My mother gave of herself tremendously by home schooling my entire family, this has allowed me to spend an unusual amount of time with open source projects like Jabber as well as develop my english skills. My high school English teacher Mrs. Pat McFarlane contributed greatly to my love of classic literature and writing well. I have been blessed again and again with wonderful people who have encouraged and inspired me. Among those that have contributed greatly to my persona include Nathan Nix, Peter Saint-Andre, Justin Mecham and Mike Comiskey. An acknowledgements list would not be complete without expressing complete gratitude for my Lord and Savior, Jesus Christ. Soli deo gloria.


Chapter 2. Cast of Characters

Throughout the examples in the Jabber Programmers Guide, fictional characters are used for sending and receiving protocol. The characters in this guide are based on the play Hamlet by Shakespeare.

The character "Hamlet" is used as the main character that packets are sent from or to (from other characters). The server "denmark" represents the character's main Jabber server.


Chapter 3. Technology Overview

Introduction

To gain a complete picture of the Jabber landscape, a broad technical overview is necessary. With this overview comes details of the technology (e.g. XML) and architecture that makes Jabber happen. By providing a broad overview of the technologies in play, developers can easily see where how the many pieces of the puzzle fit together and work together.


Basic Concepts

XML

XML is an integral part of the Jabber architecture. XML is used throughout the design and communications of Jabber to provide a common, unified way of expressing any type of structured data. All components of the Jabber architecture must be able to understand XML on some level to communicate to other components.


Distributed Architecture

The Jabber instant messaging architechture is modeled after the Internet email system. There can exist any number of independent Jabber servers which accept connections from clients as well as communicate to other Jabber servers. Each server functions independent of others, and maintains its own user list. Any Jabber server can talk to any other Jabber server that is accessable via the Internet.


Jabber Architecture

The Jabber system is made up of four basic components. Each component has the ability to talk to one or more other components in the system.


Jabber Clients

Each end user will connect to the Jabber "architecture" using some kind of Jabber client. Any number of clients can exist and use simple TCP socket communication to talk directly to a Jabber server. The client establishes a connection to the server and uses XML for all communication. The Jabber Server is the only other component that a client would normally communicate with (except for special cases).


Jabber Servers

The Jabber server has two primary functions:

  • It listens for client connections and communicates directly with client applications. Part of communicating with the clients is providing basic services such as user authentication, offline message storage, and roster (contact list) storage for all of the registered users of this server.

  • It communicates with the Etherx component (provided by the libetherx shared library) to allow the server to talk to other remote servers and transports.

Jabber servers can be extended in functionality by using two different APIs built into the core server. Details about extending the Jabber server functionality exceed the scope of this chapter and will be discussed in future revisions of this document


Transports

Transports are one of the two unique components that make up the Jabber architecture. Transports are programs running on a server that communicate with other (non-Jabber) instant messaging systems. These transports allow Jabber users to login to other IM systems, and at least send and receive messages. Some transports may have additional functionality depending on the target IM system for which it is designed. The Transports are responsible for "transforming" messages and packets from one instant messaging network into legal XML packets which conform to the Jabber XML protocol (see Chapter 9, Chapter 10 and Chapter 11). Note that transports do not talk directly to Jabber clients, but talk to the Etherx component and the outside IM network. Transports are like translators between some "foreign" IM system and Jabber.


Etherx "Router" Component

The Etherx component is the other unique, but key, component in the whole Jabber architecture. Etherx communicates with Jabber servers and transports and allows all of these components to talk to each other. Etherx communicates with "remote" (other servers) Etherx instances, as well as the local Jabber server, and any transports running locally. Note that Etherx is now entirely a shared library and is no longer a seperate daemon.


How it All Works

Jabber User to Jabber User

For Jabber users to talk to other Jabber users, the system works just like the Internet email system does. The client sends a message to the Jabber server which examines the XML packet. If the destination user is on the same server, then the message is forwarded directly to that user. Otherwise, the packet is handed off to Etherx for further processing or redirection.

Etherx is responsible for all of the Jabber server to Jabber server communication. So in this case, Etherx would connect to the instance of Etherx running on the host specifed by the destination user. Once the remote Etherx has received the XML packet, it hands the packet to its Jabber server which either delivers the message immediately to the user or stores it offline for the user.


Jabber User to Foreign IM Networks

When a Jabber user sends a message to a user on a foreign system, the transport components get involved. The client application sends a message to the Jabber server. Jabber server then passes the client data to Etherx (since it's not destined for another Jabber user on this server). Etherx passes the packet onto the matching transport application. If the transport is local (running on the same machine), Etherx communicates directly to it. If the transport is running remotely (on another machine), then the local Etherx passes the packet to the remote Etherx, which then passes it to the appropriate transport.

Once the transport receives the XML packet, it "transforms" the message (or instructions) into a native packet which is readable by the other IM network, and passes it to that IM network.


XML Protocols

All of the Jabber components communicate by passing XML fragments (sometimes called XML packets) over TCP connections. The details of the protocol exceed the scope of the chapter and are covered in Chapter 9, Chapter 10 and Chapter 11.


User Identification, Accounts, etc.

User Accounts

All user authentication and creation is handled by the Jabber server which the client connects to. Normally, user information is stored in a spool directory in XML files for each user. This information may be stored in databases or other locations using additional XDB modules. Additional information for each user is stored on the server including that user's roster (contact list). Note that since the roster is stored on the server, this roster "follows" the user from machine to machine as long as that user logs in with the same username and password.


Jabber IDs

Jabber users are identified using a Jabber ID (JID) which is very similar in look and usage to an email address. A simple JID would be:

hamlet@denmark
				

This is the address that would be used to send a message to this user by any other Jabber user on any Jabber server. These JIDs are used throughout the Jabber protocol and are used by the Jabber server and Etherx to determine where the XML packet must be routed to.

See the section called Node (user) in Chapter 4 for detailed information on the exact JID format.


Transports

When XML packets are destined for an "other" IM system, the transport is pre-pended to the domain of the server. For example, a message being sent to an ICQ user using the ICQ transport on the denmark server would be sent to:

1234567@icq.denmark
					

This domain would tell the Etherx running at denmark to route the XML packet to the ICQ transport.

When a message is received from outside the Jabber system, a compliant JID is constructed by the Transport and used in all XML packets to and from that user.


Resources

The Jabber Architecture allows for a single user to log into a Jabber Server multiple times. To allow the other Jabber components to distinguish between multiple connections, the "Resource" is used. The resource is appended to the JID to form a "complete" JID. Each resource must be unique for that user. For example, two different users may both have a "home" resource, but the same user can not have two "home" resources online. A front slash and the resource is appended to the JID after the domain name. So a single user may be logged on three times as follows:

hamlet@denmark/castle
hamlet@denmark/gate
hamlet@denmark/courtyard
					

Note that in some circumstances messages may be sent directly to a specific resource, but in general, a message destined for hamlet@denmark are routed based on some rules in the Jabber Server. Each "instance" of this user can have a different priority setting. Thus, if a message is just sent to hamlet@denmark (i.e. without specifying a resource), the message is routed to the instance (client) which has the highest priority.

the section called Resource in Chapter 4 provides an exact definition of resources .


Clients

The design of the Jabber architecture has several significant ramifications on client designs. The following section provides a brief overview of what clients are responsible for.


Simple Clients

Jabber clients communicate only to Jabber servers (except in rare cases, see below). This means that once a Jabber client implements the basic Jabber XML protocol, the client is "dumb" to the source and destination of any specific message. In other words, clients just send and receive messages always conforming to the Jabber XML protocol. It doesn't matter if those messages are destined for other Jabber users, or users on some other IM network. When messages travel to outside of the Jabber system, the transport is the mechanism which "translates" the XML message into the destination native format (and vice-a-versa). This means that the only thing that must change or be updated when that "other" system changes their protocol is the transport. None of the clients will ever be impacted, or will need to be changed.


Extensible Feature Sets

The Jabber Architecture imposes very few restrictions on clients. The only features which a client MUST have are:

  • Communicate to the Jabber server via TCP sockets.

  • Parse and interpret well-formed XML packets.

  • Understand message data types.

The lack of rigorous restrictions means that a variety of client feature sets may exist. This also means that a client can "build" its feature set as it goes and still be able to communicate and operate with Jabber servers.


Online Presence, Rosters, Subscriptions

All Jabber "entities" can have a "presence". This presence tells other entities that it is either "available" or "unavailable". Jabber clients should set the user's presence to "available" after they login. The user can then allow other entities (users, transports) to see their presence information via a method of "subscriptions". See presence for actual protocol regarding presence.

The subscription system allows hamlet@denmark to authorize some people to "see" him online, while refusing others. This process is called "subscribing to someone's presence". So horatio@denmark might send a subscription request to hamlet@denmark. Jsmith receives the request, and authorizes it, so then jdoe can see when jsmith comes online or offline. Jsmith might then decide to also request to the jdoe's presence, so he would send a subscription request back to jdoe.

Jabber server maintains a list of these subscriptions and other users. This list is called a Roster.

The Roster is always stored on the server and thus, can "follow" the user from location to location and computer to computer. The Jabber server automatically adjusts subscription types when people authorize or refuse your requests.

The Roster can also store other information about specific users. This information includes nicknames for each user and "groups" which that user belongs to. This information can be used by the client to display the roster in some kind of treeview.


Chapter 4. Entity Identification

Three Tier

The basic concept behind all identity within Jabber is a three-tier structure: the host, node, and resource. This allows a host to manage its nodes, and each node to have independent addressable resources. The most common use of this structure is as a server, user, and connection identifier.


Host (server)

The basic required component of every ID is a Host. The Host is a standard DNS hostname and not case sensitive.


Node (user)

Each Host can be addressed with individual Nodes, or users. Each user is specific to the Host it is associated with, similar to email. Usernames are restricted to 255 characters, and the following ASCII characters are invalid:

  • Any ASCII character less than 33 (including a space, 32).

  • Any character in the set [:@'"].

  • Whitespace (\r\n\t).

  • Control characters.

Case is preserved, but not used when comparing/matching. A Node address looks similar to email: node@host. Node addresses are intended to be human readable/usable in the same manner that email addresses are used today.


Resource

Resources are specific to a Node. All characters are allowed and there are no restrictions. It is case sensitive. Resource addresses are similar to the path part of a URL. Resources are used to address specific connections (since a Jabber server allows a user to be connected from multiple resources simultaneously), devices, or inboxes. An example Resource address: node@host/resource. Resource addresses are intended to be hidden from a user and only used at the software/protocol level.


URI

A Jabber identifier conforms to RFC 2396, "Uniform Resource Identifiers (URI): Generic Syntax" by prepending a "jabber://" to any address. When compared to other URIs, it acts like a hybrid mailto: and http:// URI, offering both a user identity and an optional path/resource specification.

Originally the abstraction layer used a Jabber URI within the protocol, but this was dropped until that use could undergo further review. Some of the reasoning was that the protocol was not capable of handling any other URI, in the sense that SMTP does not directly handle mailto: URIs within the protocol. Also, there was a tendency to want to create proprietary custom URIs (such as 'icq:' or 'talk:') within the protocol. Enabling the abstraction layer to use full URIs directly was deferred until such a use could be standardized and agreed upon.


Chapter 5. Connecting to the Server

To connect to the server, clients simply use a standard XML stream to the server on TCP port 5222. Before any protocol is exchanged, the client must notify the server what type of connection is being made. The jabber:client namespace (see the section called Jabber DTD in Chapter 8) is used for regular client communication. A sample XML stream exchange is shown in the examples below. Once the stream is successfully opened, it must be upheld during the continuuation of the session.

Example 5-1. Opening the Stream

To open the connection, the client sends a standard XML prolog along with the initial stream element.

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

<stream:stream 
  to="denmark" 
  xmlns="jabber:client" 
  xmlns:stream="http://etherx.jabber.org/streams">
		

Example 5-2. Server Response

Similarly, the server sends an opening stream to the client.

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

<stream:stream 
  from="denmark" 
  xmlns="jabber:client" 
  xmlns:stream="http://etherx.jabber.org/streams">
  		

Example 5-3. End of Stream

To properly close the stream, the client or server simply ends the stream element. The receiving entity should send a closing stream element in response.

</stream:stream>
		

XML Streams DTD

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

<!ELEMENT stream (error?)>

  <!ATTLIST stream
    to CDATA #REQUIRED
    from CDATA #IMPLIED
    id CDATA #IMPLIED
    xmlns CDATA #REQUIRED
    xmlns:stream CDATA #REQUIRED
	  'http://etherx.jabber.org/streams'
  >
  
  <!ELEMENT error (#PCDATA)>
		


Chapter 6. Group Chat Overview

The Basics

Introduction

Group chat is used when more than two people are participating in a single conversation. The GUI is often IRC-ish: a list of participants on one side, the main window for the messages, and a small entry box at the bottom. A group chat is indicated by message type "groupchat".

Users may participate in multiple independent group chats at any given time, so the client must maintain a list of the group chats the user is participating in.

When any message of type="groupchat" is received, it should be checked against the list of existing group chats. If no existing group chat is found, the user should be prompted to join the group (the initial message is considered an invite, and the body is the text of the invite message).


Identification

Within Jabber, a group chat participant is identified via the format:

[group name]@[group chat server]/[user nickname]
					

A single room is identified as:

[group name]@[group chat server]
					

Each participant is identified with a unique resource representing their nickname.


Presence

Participation in a group chat is based on presence. To join any group the client sends presence to the group id (groupname@groupchatserver), and specifies the user's nickname in the resource (see Example 6-1). After sending presence, the client will receive presence from each participant in the group (see Example 6-3). This presence is a standard available presence, and may contain the status/show elements which can optionally be supported in the group chat display (see Example 6-5). Each time a new participant joins, their presence will be broadcast to the existing participants already in the group. To leave a group and stop receiving messages from it's participants, simply send an unavailable presence.

To change the user's nickname, another presence packet should be sent to the group with the new nickname as the resource. This will cause the group chat server to broadcast an unavailable presence to the participants for the old nickname, and then broadcast the new presence and nickname. The server will also send a message back, indicating the changed nicknames.


Messages

Normal Group Messages

Normal messages within the group chat will arrive from:

[group name]@[group chat server]/[user nickname]
						

See Example 6-8 for a complete example.


Server Messages

Server messages will arrive as from:

[group name]@[group chat server]
						

Server messages can be displayed differently representing that they are from the server. See Example 6-2 and Example 6-7 for complete examples.


Private Messages

Private messages may also be sent between individual participants in the room simply by specifying that participant in the to attribute and using a different type attribute other than "groupchat" in the message element (see Example 6-9 and Example 6-10).


Inviting Users

Anyone can ask the group chat server to invite someone else into the group by sending a message to just the groupname@groupchatserver with a special subject in the format:

invite:[user to invite]@[user server]
						

with a custom invite message placed within the message body.

A complete example of Hamlet's father's ghost inviting Hamlet to a group chat:

<message to="act1@gc.denmark" from="ghost@denmark">
  <subject>invite:hamlet@denmark</subject>
  <body>
    Pity me not, but lend thy serious hearing
    To what I shall unfold.
  </body>
</message>
					


Subscribing to Groups

Groups can be subscribed to and exist in the user's roster. The address that should be subscribed to is the same as the address for sending presence:

[group name]@[group chat server]/[default nickname]
					

so that as soon as the user becomes available, it is notified and the user is immediately participating in the group.


Privacy Note

As might have been noticed, the Jabber group chat model provides a very secure way for users to interact with others in a group setting. A user's true Jabber ID is never displayed or exchanged, yet complete Jabber functionality is attainable.


Examples

The following examples combine to show a complete group chat session from the viewpoint of Hamlet's client. Note that this example is not entirely accurate as it shows Polonius and Claudius leaving after Hamlet arrives, when in fact, Polonius and Claudius leave the scene before Hamlet joins.

Example 6-1. Initial Presence

The client sends an initial presence to the server to notify other participants of arrival and to tell the server that the client should begin receiving groupchat presence and messages.

<presence to="act3@gc.denmark/Hamlet"/>
			

Example 6-2. Join Message

Server generated message sent to all participants in the groupchat. This is simply for the benefit of the participants and should not dictate the behaviour of the group chat roster (clients should add/remove users according to their presence, not server generated messages).

<message type="groupchat" from="act3@gc.denmark">
  <body>Hamlet has arrived.</body>
</message>
			

Example 6-3. Participant's Presence

The server sends all current presence information from participants in the group chat. Everyone happens to be online and available at this point, so no detailed status information is sent (unlike Example 6-5). Note that this now includes Hamlet.

<presence from="act3@gc.denmark/Hamlet"/>
<presence from="act3@gc.denmark/Claudius"/>
<presence from="act3@gc.denmark/Gertrude"/>
<presence from="act3@gc.denmark/Polonius"/>
<presence from="act3@gc.denmark/Rosencrantz"/>
<presence from="act3@gc.denmark/Guildenstern"/>
<presence from="act3@gc.denmark/Ophelia"/>
			

Example 6-4. Group Message (from)

A simple message (with optional subject) sent from Polonius, a group chat participant.

<message type="groupchat" from="act3@gc.denmark/Polonius">
  <subject>Scene I</subject>
  <body>
    I hear him coming: let's withdraw, my lord.
  </body>
</message>
			

Example 6-5. Presence Change

Instead of going offline like King Claudius is about to do (Example 6-6), Polonius changes his status to Not Available (see presence).

<presence from="act3@gc.denmark/Polonius">
  <show>na</show>
  <status>Withdrawn</status>
<presence>
			

Example 6-6. Presence Change (quit)

Claudius decided to just quit the group (probably wanted to save some valuable screen real estate), so he sent an unavailable presence to the server. The server then sent the result (shown here) to the other participants in the group chat.

<presence type="unavailable" from="act3@gc.denmark/Claudius"/>
			

Example 6-7. Quit Message

Like Example 6-2, this server generated message notifies participants that that the user has left.

<message type="groupchat" from="act3@gc.denmark/Claudius">
  <body>Claudius has left.</body>
</message>
			

Example 6-8. Group Message (to)

Hamlet decides to speak to the entire group, this message is broadcast to all participants, including Hamlet (broadcast back to Hamlet is not shown).

<message type="groupchat" to="act3@gc.denmark">
  <subject>Scene I</subject>
  <body>
    To be, or not to be: that is the question:
    Whether 'tis nobler in the mind to suffer
    The slings and arrows of outrageous fortune,
    Or to take arms against a sea of troubles,
    And by opposing end them?
  </body>
</message>
			

Example 6-9. Private Message (to)

A private message to Ophelia from Hamlet.

<message type="chat" to="act3@gc.denmark/Ophelia">
  <body>
    Soft you now!
    The fair Ophelia! Nymph, in thy orisons
    Be all my sins remember'd
  </body>
</message>
			

Example 6-10. Private Message (from)

A private message from Ophelia to Hamlet.

<message type="chat" from="act3@gc.denmark/Ophelia">
  <body>
    Good my lord,
    How does your honour for this many a day?
  </body>
</message>
			

Example 6-11. Presence Change (quit - send)

Done with his chat in Scene I, Hamlet decides to send an unavailable presence to leave the group chat.

<presence to="act3@gc.denmark/Hamlet" type="unavailable"/>
			

Example 6-12. Presence Change (quit - received)

The server confirms Hamlet's actions in Example 6-11 and tells Hamlet's client that he has been disconnected from the channel. No further group chat messages or presence will be received.

<presence from="act3@gc.denmark/Hamlet" type="unavailable"/>
			

Chapter 7. Auto Update

Introduction

Client update notification is a simple process to allow a way for client applications (servers, user clients, etc.) to be notified of new revisions of software or to manually query for version information. The entire auto update process requires use of the message, x, iq and presence elements.


Process

All of the update process is handled discretly between the querying application and the update server with little interaction necessary by the user. The typical process of communicating with the update server is as follows:

Example 7-1. Current Information

To notify the server of the client application's version, the client sends a presence packet to [client]@[server]/[current version]. Current version at this point refers to the client's installed version, not the latest available version.

<presence to="winjab@update.denmark/0.9.1.0"/>
			

Example 7-2. New Version Available

The server then compares the client's installed version against a database of client information to determine if there is an update available for the client. If there is, the server sends a message using jabber:x:autoupdate.

<message from="winjab@update.denmark to="hamlet@denmark">
  <subject>Upgrade available for WinJab</subject>
  <body>Please check the attachment.</body>
  <x xmlns="jabber:x:autoupdate">winjab@update.jabber.org</x>
</message>
			

Example 7-3. Client Requests New Information

When the client receives an update notification via jabber:x:autoupdate, it can then request more detailed information using jabber:iq:autoupdate.

<iq type="get" id="1001" to="winjab@update.denmark">
  <query xmlns="jabber:iq:autoupdate"/>
</iq>
			

Example 7-4. Server Sends New Information

Upon receiving jabber:iq:autoupdate get request, the server responds with current download information so that the client can immediatly begin downloading (or notify the user to a download address).

<iq type="result" from="winjab@update.denmark" id="1001">
  <query xmlns="jabber:iq:autoupdate">
    <release priority="optional">
      <ver>0.9.1.1</ver>
      <desc/>
      <url>http://update.denmark/winjab/winjab_setup.exe</url>
    </release>
    <beta priority="optional">
      <ver>0.9.2.16</ver>
      <desc/>
      <url>http://update.denmark/winjab/winjab_beta.exe</url>
    </beta>
  </query>
</iq>
			

Chapter 8. Core Protocol Elements

While many elements exist within the Jabber XML protocol, several elements form the central core of the protocol. Of these core elements, three (iq, message, and presence) form the most basic packet types upon which all other data is built. The other two common elements are x and error. The x element provides a simple way to extend any of the core elements beyond their original use. The error element is used throughout the protocol for a standard error method. For more information about these core elements, see their respective reference page in Chapter 11.


Jabber DTD

The following DTD represents the structure of the main Jabber protocol. Nearly all of these main elements can be expanded using IQ Namespaces, X Namespaces or any normal XML namespace. The Jabber DTD is referenced from other XML documents and streams with the identifier jabber:client.

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

<!-- The root of it all. -->

<!ELEMENT jabber ((
  presence | 
  iq | 
  message
)*)>

  <!ELEMENT presence ((
    status? | 
    priority? | 
    show? | 
    x*
  )*)>

    <!ATTLIST presence
      to CDATA #IMPLIED
      from CDATA #IMPLIED
      type (
        subscribe | 
        subscribed | 
        unsubscribe | 
        unsubscribed | 
        available | 
        unavailable | 
        probe
      ) #IMPLIED
    >

    <!ELEMENT status (#PCDATA)>

    <!ELEMENT priority (#PCDATA)>

    <!-- standard options of show are:
      chat, away, xa and dnd -->
    <!ELEMENT show (#PCDATA)>

  <!ELEMENT message ((
    body? | 
    x* | 
    error* | 
    subject? | 
    thread?
  )*)>

    <!ATTLIST message
      to CDATA #IMPLIED
      from CDATA #IMPLIED
      id ID
      type (
        normal | 
        error | 
        chat | 
        groupchat | 
        headline
      ) #IMPLIED
    >

    <!ELEMENT body (#PCDATA)>

    <!ELEMENT subject (#PCDATA)>

    <!ELEMENT thread (#PCDATA)>

  <!ELEMENT iq (#PCDATA)>
  
    <!ATTLIST iq
      to CDATA #IMPLIED
      from CDATA #IMPLIED
      id CDATA #IMPLIED
      type (
        get | 
        set | 
        result | 
        error
      ) #IMPLIED
    >

<!-- Common elements. -->

  <!ELEMENT error (#PCDATA)>
  
    <!ATTLIST error
      code (
        400 |
        401 |
        402 |
        403 |
        404 |
        405 |
        406 |
        407 |
        408 |
        500 |
        501 |
        502 |
        503 | 
        504
      ) #IMPLIED
    >

  <!-- the infamous x element -->

  <!ELEMENT x (#PCDATA)>
			


Chapter 9. IQ Namespaces

The primary namespaces used by Jabber give the server its core functionality and power. Implementation of these on the client side is vital to ensure that all pieces work together correctly. If not implemented properly on the client side, many unexpected results may occur for the user.

jabber:iq:autoupdate

Name

jabber:iq:autoupdate -- application version updates

Description

This IQ allows entities to query for release information about a registered software item.

Methods

  • get

    Sent with a blank query to retrieve the latest version information in the database. The query must be sent to the proper JID that is provided by jabber:x:autoupdate.

  • set

    Not used in this context.

  • result

    The result query contains specific information (version, download location, etc.) about the requested application.

  • error

    There was an error processing the request. The exact error can be found in the child error element.

Elements

The root element of this namespace is query, the children include release, beta, and dev. Each of the main elements have version, url, and desc.

See Also

For detailed information about the entire auto update process, see Chapter 7.

Examples

See jabber:iq:autoupdate for complete examples.

DTD

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

<!ENTITY % verelements "(ver | url | desc)*">
<!ENTITY % priatts "priority (optional | mandatory) #REQUIRED">

<!ELEMENT query (
  release?,
  beta?,
  dev?
)>

  <!ELEMENT release &verelements;>
  <!ATTLIST release &priatts;>

  <!ELEMENT beta &verelements;>
  <!ATTLIST beta &priatts;>

  <!ELEMENT dev &verelements;>
  <!ATTLIST dev &priatts;>

<!ELEMENT ver (#PCDATA)>
<!ELEMENT url (#PCDATA)>
			

jabber:iq:agent

Name

jabber:iq:agent -- interactive server component properties

Description

This IQ allows for the retrieval of the specific abilities of a single server agent.

Methods

  • get

    Sent with a blank query to retrieve the agent properties from a server.

  • set

    Not used in this context.

  • result

    The result query contains the abilities of the requested agent. A description of what is returned can be found in jabber:iq:agent.

  • error

    There was an error processing the request. The exact error can be found in the child error element.

Elements

The root element of this namespace is query, the children include groupchat, name, description, service, register, search, transport, and url.

Notes

All the information necessary to interact with a transport is returned in this query. The information is sent in seperate child elements of the query itself. The exact meaning of each child element can be found on their respective element pages.

Examples

Example 9-1. Client Request For Agent

<iq type="get" id="1001" to="icq.denmark">
  <query xmlns="jabber:iq:agent"/>
</iq>
			

Example 9-2. Agent Reply

<iq type="result" id="1001">
  <query xmlns="jabber:iq:agent">
    <name>ICQ Service</name>
    <url>http://denmark/services/icq/</url>
    <description>
      This is the ICQ Service for
      connecting to ICQ users.
    </description>
    <transport>ICQ #</transport>
    <register/>
    <service>icq</service>
    <search/>
  </query>
</iq>
			

DTD

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

<!ELEMENT query (agent)?>

  <!ELEMENT agent (
    name | 
    description | 
    transport | 
    service | 
    register
  )?>

    <!ATTLIST agent
      jid CDATA #IMPLIED
    >

    <!ELEMENT name (#PCDATA)>

    <!ELEMENT description (#PCDATA)>

    <!ELEMENT transport (#PCDATA)>

    <!ELEMENT service (#PCDATA)>

    <!ELEMENT register (#PCDATA)>
			

jabber:iq:agents

Name

jabber:iq:agents -- method to query interactive server components

Description

The method to query a server for its complete list of agents.

Methods

  • get

    Sent with a blank query to retrieve the available agents from a server.

  • set

    Not used in this context.

  • result

    The result query contains multiple items representing the servers available agents.

  • error

    There was an error processing the request. The exact error can be found in the child error element.

Elements

The root element of this namespace is query, the children include groupchat, name, description, service, register, search, transport, and url.

Notes

Any server or transport may be queried for an agents list. The result from a get request can best be understood after reviewing the jabber:iq:agent namespace.

Examples

Example 9-1. Request Agents List From Server

<iq type="get" id="1001">
    <query xmlns="jabber:iq:agents"/>
</iq>
			

Example 9-2. Agents Reply From Server

<iq type="result" id="1001">
  <query xmlns="jabber:iq:agents">
    <agent jid="users.denmark">
      <name>Jabber 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.denmark">
      <name>AIM Transport</name>
      <description>
        This service allows you to communicate transparently to
        AOL Instant Messenger users.
      </description>
      <transport>AIM/AOL Screen Name</transport>
      <service>aim</service>
      <register/>
    </agent>
  </query>
</iq>
			

DTD

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

<!ELEMENT query (agent)+>

  <!ELEMENT agent (
    name | 
    description | 
    transport | 
    service | 
    register
  )?>

    <!ATTLIST agent
      jid CDATA #IMPLIED
    >

    <!ELEMENT name (#PCDATA)>

    <!ELEMENT description (#PCDATA)>

    <!ELEMENT transport (#PCDATA)>

    <!ELEMENT service (#PCDATA)>

    <!ELEMENT register (#PCDATA)>
			

jabber:iq:auth

Name

jabber:iq:auth -- simple client authentication

Description

This IQ is a simple mechanism for the clients to authenticate and create a resource representing their connection to the server.

Methods

  • get

    Not used in this context.

  • set

    Sent containing the login information.

  • result

    The auth operation completed succesfully.

  • error

    There was an error processing the auth request. The exact error can be found in the child error element.

Elements

The root element of this namespace is query, the children include username, password, resource, and digest.

Examples

Example 9-1. Client Authentication (plain password)

<iq type="set" id="1001">
  <query xmlns="jabber:iq:auth">
    <username>hamlet</username>
    <password>gertrude</password>
    <resource>Castle</resource>
  </query>
</iq>
			

Example 9-2. Client Authentication (digest password)

<iq type="set" id="1002">
  <query xmlns="jabber:iq:auth">
    <username>hamlet</username>
    <digest>77073f10e7ef9e22eead3609b9c00813d1a9e8c0</digest>
    <resource>WarPath</resource>
  </query>
</iq>
			

Example 9-3. Successful Client Authentication

<iq type="result" id="1001"/>
			

Example 9-4. Unsuccessful Client Authentication

<iq type="error" id="1001">
  <error code="400">Wrong Password</error>
</iq>
			

DTD

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

<!ELEMENT query ((
  username? | 
  (password | digest)? | 
  resource
)*)>

  <!ELEMENT username (#PCDATA)>

  <!ELEMENT password (#PCDATA)>

  <!ELEMENT digest (#PCDATA)>

  <!ELEMENT resource (#PCDATA)>
			

jabber:iq:oob

Name

jabber:iq:oob -- out of band data

Description

This iq namespace allows clients to exchange information about a data transfer and either accept or reject it. This namespace does not allow clients to pass files through a firewall. By providing the IP address to a local file, clients essentially setup a mini-web server to allow the other party to fetch the file.

If no confirmation is required of receipt, (for example, sending a favorite URL to a friend) use jabber:x:oob.

Methods

  • get

    Not used in this context. ???

  • set

    Sent to the receipent to notify of the URI and describe the item.

  • result

    Sent as a "return receipt" to notify the sender that the item has been received and is being fetched (or that an HTTP connection may then insue).

  • error

    There was an error processing the request. The exact error can be found in the child error element.

Elements

The root element of this namespace is query, the children include url and desc.

Examples

Example 9-1. Sending the initial URL.

<iq type="set" from="sailor@denmark" to="horatio@denmark">
  <query xmlns="jabber:iq:oob">
    <url>http://denmark/act4/letter-1.html</url>
    <desc>
      There's a letter for you sir: it comes from
      the ambassador that was bound for England:
      if your name be Horatio, as I am let to know it is.
    </desc>
  </query>
</iq>
			

DTD

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

<!ELEMENT query ((url? | desc?)*)>

  <!ELEMENT url (#PCDATA)>

  <!ELEMENT desc (#PCDATA)>
			

jabber:iq:private

Name

jabber:iq:private -- method to store private data on the server

Description

Using this method, Jabber entities can store private data on the server. The data stored might be anything, as long as it is valid XML. Typical usage for this namespace might be server-side client preferences.

Methods

  • get

    Sent with a blank query to retrieve the private data from the server.

  • set

    Sent with the private XML data contained inside of a query.

  • result

    Returns the private data from the server.

  • error

    There was an error processing the request. The exact error can be found in the child error element.

Elements

The root element of this namespace is query. At least one child element with a proper namespace must be included -- otherwise the server will respond with error 406. Only one element can be queried for in a single IQ request. However, multiple elements, each containing data, can be stored independently on the server.

Examples

Example 9-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 9-2. Server Response (successful)

<iq type="result" id="1001"/>
			

Example 9-3. Client Retrieval

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

Example 9-4. Server Response

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

DTD

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

<!ELEMENT query EMPTY>
			

jabber:iq:register

Name

jabber:iq:register -- method for interactive registration

Description

Using this method, clients can register new accounts or remove accounts with the server and services.

Methods

  • get

    Sent with a blank query to retrieve registration information from a server. Retrieves a key for use on future registration pushes.

  • set

    Used to send new or updated user information to the server. Also used to send remove requests.

  • result

    The result query either confirms pushes or sends the client the required registration fields.

  • error

    There was an error processing the request. The exact error can be found in the child error element.

Elements

The root element of this namespace is query, the children elements include query, username, nick, password, name, first, last, email, address, city, state, zip, phone, url, date, misc, text, instructions, key, and registered.

Notes

Any server or transport may be queried for registration information.

Examples

Example 9-1. Client Request

<iq type="get" id="1001" to="aim.denmark">
  <query xmlns="jabber:iq:register"/>
</iq>
			

Example 9-2. Server Response (unregistered)

<iq type="result"
  from="aim.denmark" 
  to="hamlet@denmark" 
  id="1001">
  <query xmlns="jabber:iq:register">
    <username/>
    <password/>
    <key>
      106c0a7b5510f192a408a1d054150ed1065e255a
    </key>
    <instructions>
      Enter your AIM screen
      name and password.
    </instructions>
  </query>
</iq>
			

Example 9-3. Client Registration

In a client registration with the service, the key must be kept throughout the exchange.

<iq type="set" to="aim.denmark" id="1001">
  <query xmlns="jabber:iq:register">
    <username>Hamlet</username>
    <password>gertrude</password>
    <key>106c0a7b5510f192a408a1d054150ed1065e255a</key>
  </query>
</iq>
			

Example 9-4. Server Response (already registered)

If the user is already registered with this service, the server would respond back with the currently set information and an empty registered element.

<iq
  type="result" 
  from="aim.denmark" 
  to="hamlet@denmark" 
  id="1001">
  <query xmlns="jabber:iq:register">
    <registered/>
    <username>Hamlet</username>
    <password>gertrude</password>
    <key>
      106c0a7b5510f192a408a1d054150ed1065e255a
    </key>
    <instructions>
      Enter your AIM screen
      name and password.
    </instructions>
  </query>
</iq>
			

Example 9-5. Client Request for Removal

<iq type="set" to="aim.denmark" id="1001">
  <query xmlns="jabber:iq:register">
    <remove/>
    <key>
      106c0a7b5510f192a408a1d054150ed1065e255a
    </key>
  </query>
</iq>
			

DTD

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


<!ELEMENT query ((
  instructions? |
  username? | 
  nick? | 
  password? | 
  name? | 
  first? | 
  last? | 
  email? | 
  address? | 
  city? | 
  state? | 
  zip? | 
  phone? | 
  url? | 
  date? | 
  misc? | 
  text? | 
  key? | 
  registered? | 
  remove?
)*)>

  <!ELEMENT instructions (#PCDATA)>
  <!ELEMENT username (#PCDATA)>
  <!ELEMENT nick (#PCDATA)>
  <!ELEMENT password (#PCDATA)>
  <!ELEMENT name (#PCDATA)>
  <!ELEMENT first (#PCDATA)>
  <!ELEMENT last (#PCDATA)>
  <!ELEMENT email (#PCDATA)>
  <!ELEMENT address (#PCDATA)>
  <!ELEMENT city (#PCDATA)>
  <!ELEMENT state (#PCDATA)>
  <!ELEMENT zip (#PCDATA)>
  <!ELEMENT phone (#PCDATA)>
  <!ELEMENT url (#PCDATA)>
  <!ELEMENT date (#PCDATA)>
  <!ELEMENT misc (#PCDATA)>
  <!ELEMENT text (#PCDATA)>
  <!ELEMENT key (#PCDATA)>
  <!ELEMENT registered (#PCDATA)>
  <!ELEMENT remove (#PCDATA)>
			

jabber:iq:roster

Name

jabber:iq:roster -- client roster management

Description

This IQ allows for basic management of the roster items, and retrieving items from the server.

Methods

  • get

    Sent with a blank query to retrieve the roster.

  • set

    Sent with a new roster item to replace the old. The client program is allowed to control the JID and name attributes, the group elements, and the ability to create or remove items. All other aspects of the item are handled by the server. The client is sent a set if the server is pushing roster data after a subscription event has taken place (refer to the examples below).

  • result

    The result query contains the requested items from the get.

  • error

    There was an error processing the request. The exact error can be found in the child error element.

Elements

The root element of this namespace is query, the children include item and group.

Examples

Example 9-1. Server Push of New Subscription

<iq type="set">
  <query xmlns="jabber:iq:roster">
    <item 
      jid="fortinbras@norway" 
      subscription="to" 
      name="Prince Fortinbras"/>
  </query>
</iq>
			

Example 9-2. Request for Entire Roster

<iq type="get" id="1001">
  <query xmlns="jabber:iq:roster"/>
</iq>
			

Example 9-3. Result of Roster Request

<iq type="result" id="1001">
  <query xmlns="jabber:iq:roster">
    <item
      jid="claudius@denmark" 
      name="King" 
      subsciption="both">
      <group>Family</group>
    </item>
    <item 
      jid="horatio@denmark" 
      name="Horatio" 
      subscription="from">
      <group>Friends</group>
    </item>
    <item 
      jid="fortinbras@norway" 
      name="Prince Fortinbras" 
      subscription="none" 
      ask="subscribe"/>
  </query>
</iq>
			

Example 9-4. Removing a User from Roster

<iq type="set" id="1002">
  <query xmlns="jabber:iq:roster">
    <item 
      jid="claudius@denmark" 
      name="King" 
      subscription="remove"/>
  </query>
</iq>
			

Example 9-5. Server Response to User Remove

<iq type="set">
  <query xmlns="jabber:iq:roster">
    <item 
      jid="claudius@denmark" 
      name="King" 
      subscription="remove"/>
  </query>
</iq>
<iq type="result" id="1002"/>
			

DTD

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

<!ELEMENT query ((item)*)>

  <!ELEMENT item ((group)*)>

  <!ATTLIST item
    jid PCDATA #IMPLIED
    name PCDATA #IMPLIED
    subscription ( 
      to |
      from | 
      both | 
      none
    ) #IMPLIED
    ask (subscribe | unsubscribe) #IMPLIED
  >

  <!ELEMENT group (#PCDATA)>
			

jabber:iq:search

Name

jabber:iq:search -- method for searching a user database

Description

Using this method, clients can provide an interactive search to locate users on a server.

Methods

  • get

    Sent with a blank query to retrieve search fields from a server. Retrieves a key for use on future search queries.

  • set

    Used to query server for users matching the information provided.

  • result

    Several results may be returned:

    • An empty result indicates that there were no matches for the query.

    • A result to a blank query will provide fields for the client to use for searching.

    • The complete results of a user search (a set).

  • error

    There was an error processing the request. The exact error can be found in the child error element.

Elements

The root element of this namespace query. The children of this namespace is dependent on the server being queried.

Notes

Each agent will specify with the search flag in jabber:iq:agent whether or not searching is available for each individual service.

jabber:iq:register is used to register user information with the database.

Examples

Example 9-1. Client Request

<iq type="get" id="1001" to="users.denmark">
  <query xmlns="jabber:iq:search"/>
</iq>
			

Example 9-2. Server Response

<iq
  type="result" 
  from="users.denmark" 
  id="1001">
  <query xmlns="jabber:iq:search">
    <first/>
    <last/>
    <nick/>
    <email/>
    <key>
      106c0a7b5510f192a408a1d054150ed1065e255a
    </key>
    <instructions>
      Fill in a field to search for
      any matching Jabber users.
    </instructions>
  </query>
</iq>
			

Example 9-3. Client Query

Client search for users, using any of the fields that were given in the previous response from the server. The key is not necessary for searches.

<iq type="set" to="users.denmark" id="1002">
  <query xmlns="jabber:iq:search">
    <first>Hamlet</first>
    <key>
      106c0a7b5510f192a408a1d054150ed1065e255a
    </key>
  </query>
</iq>
			

Example 9-4. Search Results

Search results that the server has ended with a blank query (if the server decided there were too many item's, it could signal an incomplete list with truncated).

<iq
  type="result" 
  from="users.denmark" 
  id="1002">
  <query xmlns="jabber:iq:search">
    <item jid="king@denmark">
      <first>Hamlet</first>
      <last/>
      <nick>King</nick>
      <email>king@denmark</email>
    </item>
    <item jid="hamlet@denmark">
      <first>Hamlet</first>
      <last/>
      <nick>Ham</nick>
      <email>hamlet@denmark</email>
    </item>
  </query>
</iq>
		

Example 9-5. Search Results (no results)

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

jabber:iq:time

Name

jabber:iq:time -- method for requesting the current time

Description

Using this method, Jabber entities can request for current time information to be queried from another entity.

Methods

  • get

    Sent with a blank query to retrieve time information from an entity.

  • set

    Not used in this context.

  • result

    Returns the time results.

  • error

    There was an error processing the request. The exact error can be found in the child error element.

Elements

The root element of this namespace is query, the children include utc, tz and display.

Examples

Example 9-1. Request from client for time information.

<iq type="get" id="1001" to="hamlet@denmark">
  <query xmlns="jabber:iq:time"/>
</iq>
			

Example 9-2. Queried client response.

<iq 
  type="result" 
  from="hamlet@denmark" 
  to="horatio@denmark" 
  id="1001">
  <query xmlns="jabber:iq:time">
    <utc>20000106T06:35:29</utc>
    <tz>Central European Time</tz>
    <display>2000/01/06 6:35:29 AM</display>
  </query>
</iq>
			

DTD

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

<!ELEMENT query ((utc | tz? | display?)*)>

  <!ELEMENT utc (#PCDATA)>

  <!ELEMENT tz (#PCDATA)>

  <!ELEMENT display (#PCDATA)>
			

jabber:iq:version

Name

jabber:iq:version -- method for requesting version

Description

Using this method, Jabber entities can request version information (operating system, client version, etc.) from another entity.

Methods

  • get

    Sent with a blank query to retrieve version information from an entity. Note that the query should be sent to a specific resource for proper handling.

  • set

    Not used in this context.

  • result

    Returns the version results.

  • error

    There was an error processing the request. The exact error can be found in the child error element.

Elements

The root element of this namespace is query, the children include name, version and os.

Examples

Example 9-1. Client Request

<iq type="get" id="1001" to="hamlet@denmark/castle">
  <query xmlns="jabber:iq:version"/>
</iq>
			

Example 9-2. Queried Client Response

<iq
  type="result" 
  from="hamlet@denmark/castle" 
  to="horatio@denmark" 
  id="1001">
  <query xmlns="jabber:iq:version">
    <name>WinJab</name>
    <version>0.9.1.1</version>
    <os>NT 4.0</os>
  </query>
</iq>
			

DTD

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

<!ELEMENT query ((name | version | os)?)>

  <!ELEMENT name (#PCDATA)>

  <!ELEMENT version (#PCDATA)>

  <!ELEMENT os (#PCDATA)>
			

Temporary vCard

Name

Temporary vCard -- electronic business card exchange

Description

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."

As the XML vCard format has not been standardized as of this writing, Jabber.org has put forth a temporary namespace for use asva temporary XML vCards standard. Until such time as an organization comes forth to standardize XML vCards, Jabber will use this temporary namespace.

The latest DTD for the XML vCard format is available here.

Methods

  • get

    Sent with an empty vCard element to the JID of the user querying for. Note that even though the IQ is sent to a user's JID, the server intercepts the request and responds. Clients do not need to know how to respond to requests.

  • set

    Sent from the client to set the user's own vCard information.

  • result

    The result of the vCard query.

  • error

    There was an error processing the request. The exact error can be found in the child error element.

Elements

The root element of this namespace is vCard. The children are shown in the DTD, below.

Note: Each vCard element is not documented within the Jabber Programmers Guide as they are not integral parts of the Jabber protocol and are referenced using a third-party DTD.

Examples

Example 9-1. Setting the vCard

<iq type="set" id="1001">
  <vCard 
    xmlns="vcard-temp">
    <FN>Hamlet</FN>
    <N>
      <FAMILY>??</FAMILY>
      <GIVEN>Hamlet</GIVEN>
      <MIDDLE/>
    </N>
    <NICKNAME>Ham</NICKNAME>
    <URL>??</URL>
    <BDAY>??</BDAY>
    <ORG>
      <ORGNAME>Holland Monarchy</ORGNAME>
      <ORGUNIT/>
    </ORG>
    <TITLE>Prince</TITLE>
    <ROLE>Royal Family</ROLE>
    <TEL><VOICE/><HOME/></TEL>
    <TEL><FAX/><HOME/></TEL>
    <TEL><MSG/><HOME/></TEL>
    <ADR>
      <HOME/>
      <EXTADD/>
      <STREET/>
      <LOCALITY>Denmark</LOCALITY>
      <REGION>??</REGION>
      <PCODE>??</PCODE>
      <COUNTRY>Holland</COUNTRY>
    </ADR>
    <TEL><VOICE/><WORK/></TEL>
    <TEL><FAX/><WORK/></TEL>
    <TEL><MSG/><WORK/></TEL>
    <ADR>
      <WORK/>
       <EXTADD/>
       <STREET/>
       <LOCALITY>Denmark</LOCALITY>
       <REGION>??</REGION>
       <PCODE>??</PCODE>
       <COUNTRY>Holland</COUNTRY>
     </ADR>
     <EMAIL><INTERNET/><PREF/>hamlet@denmark</EMAIL>
  </vCard>
</iq>
			

Example 9-2. Fetching a vCard

<iq 
  type="get" 
  to="hamlet@denmark" 
  id="1002">
  <vCard xmlns="vcard-temp"/>
</iq>
			

Example 9-3. Server Response to Query

<iq 
  type="result" 
  from="horatio@denmark" 
  id="1002">
  <vCard 
    xmlns="vcard-temp">
    <FN>Hamlet</FN>
    <N>
      <FAMILY>??</FAMILY>
      <GIVEN>Hamlet</GIVEN>
      <MIDDLE/>
    </N>
    <NICKNAME>Ham</NICKNAME>
    <URL>??</URL>
    <BDAY>??</BDAY>
    <ORG>
      <ORGNAME>Holland Monarchy</ORGNAME>
      <ORGUNIT/>
    </ORG>
    <TITLE>Prince</TITLE>
    <ROLE>Royal Family</ROLE>
    <TEL><VOICE/><HOME/></TEL>
    <TEL><FAX/><HOME/></TEL>
    <TEL><MSG/><HOME/></TEL>
    <ADR>
      <HOME/>
      <EXTADD/>
      <STREET/>
      <LOCALITY>Denmark</LOCALITY>
      <REGION>??</REGION>
      <PCODE>??</PCODE>
      <COUNTRY>Holland</COUNTRY>
    </ADR>
    <TEL><VOICE/><WORK/></TEL>
    <TEL><FAX/><WORK/></TEL>
    <TEL><MSG/><WORK/></TEL>
    <ADR>
      <WORK/>
       <EXTADD/>
       <STREET/>
       <LOCALITY>Denmark</LOCALITY>
       <REGION>??</REGION>
       <PCODE>??</PCODE>
       <COUNTRY>Holland</COUNTRY>
     </ADR>
     <EMAIL><INTERNET/><PREF/>hamlet@denmark</EMAIL>
  </vCard>
</iq>
			

DTD

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

<!--
Copyright (C) The Internet Society (2000). All Rights Reserved.

This document and translations of it may be copied and
furnished to others, and derivative works that comment
on or otherwise explain it or assist in its implmentation 
may be prepared, copied, published and distributed, in whole
or in part, without restriction of any kind, provided that
the above copyright notice and this paragraph are included
on all such copies and derivative works.

However, this document itself may not be modified in any
way, such as by removing the copyright notice or references
to the Internet Society or other Internet organizations,
except as needed for the purpose of developing Internet
standards in which case the procedures for copyrights
defined in the Internet Standards process MUST be followed,
or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will
not be revoked by the Internet Society or its successors or
assigns.

This document and the information contained herein is provided
on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET
ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE
USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR
ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A
PARTICULAR PURPOSE.
-->

<!-- ==== -->

<!-- Root element and container for one
  or more vCard objects -->
<!ELEMENT XCARD (VCARD)+>

<!-- Individual vCard container -->
<!ELEMENT VCARD (
  (VERSION, FN, N),
  (NICKNAME?,
  PHOTO?, 
  BDAY?, 
  ADR?, 
  LABEL?, 
  TEL?, 
  EMAIL?, 
  MAILER?, 
  TZ?, 
  GEO?, 
  TITLE?, 
  ROLE?,  
  LOGO?, 
  AGENT?, 
  ORG?, 
  CATEGORIES?, 
  NOTE?, 
  PRODID?, 
  REV?, 
  SORT-STRING?, 
  SOUND?, 
  UID?, 
  URL?, 
  CLASS?, 
  KEY?
)*)>

  <!-- vCard specification version property. 
    This MUST be 2.0, if the document conforms to RFC 2426. -->
  <!ELEMENT VERSION (#PCDATA)>

  <!-- Formatted or display name property. -->
  <!ELEMENT FN (#PCDATA)>

  <!-- Structured name property. Name components with multiple
    values must be specified as a comma separated
	list of values. -->
  <!ELEMENT N ( FAMILY?, GIVEN?, MIDDLE?, PREFIX?, SUFFIX?)>
  
    <!ELEMENT FAMILY (#PCDATA)>
    <!ELEMENT GIVEN (#PCDATA)>
    <!ELEMENT MIDDLE (#PCDATA)>
    <!ELEMENT PREFIX (#PCDATA)>
    <!ELEMENT SUFFIX (#PCDATA)>

  <!-- Nickname property. Multiple nicknames must be
    specified as a comma separated list value. -->
  <!ELEMENT NICKNAME (#PCDATA)>

  <!-- Photograph property. Value is either a BASE64 encoded
    binary value or a URI to the external content. -->
  <!ELEMENT PHOTO ((TYPE, BINVAL) | EXTVAL)>

  <!-- Birthday property. Value must be an ISO 8601 formatted
    date or date/time value. -->
  <!ELEMENT BDAY (#PCDATA)>

  <!-- Structured address property. Address components with
    multiple values must be specified as a comma separated list
    of values. -->
  <!ELEMENT ADR (
    HOME?, 
    WORK?, 
    POSTAL?, 
    PARCEL?, 
    (DOM | INTL)?, 
    PREF?, 
    POBOX?, 
    EXTADR?, 
    STREET?, 
    LOCALITY?, 
    REGION?, 
    PCODE?, 
    CTRY?
  )>
  
    <!ELEMENT POBOX (#PCDATA)>
    <!ELEMENT EXTADR (#PCDATA)>
    <!ELEMENT STREET (#PCDATA)>
    <!ELEMENT LOCALITY (#PCDATA)>
    <!ELEMENT REGION (#PCDATA)>
    <!ELEMENT PCODE (#PCDATA)>
    <!ELEMENT CTRY (#PCDATA)>

  <!-- Address label property. -->
  <!ELEMENT LABEL (
    HOME?, 
    WORK?, 
    POSTAL?, 
    PARCEL?, 
    (DOM | INTL)?, 
    PREF?, 
    LINE+
  )>

    <!-- Individual label lines. -->
    <!ELEMENT LINE (#PCDATA)>

  <!-- Telephone number property. -->
  <!ELEMENT TEL (
    HOME?, 
    WORK?, 
    VOICE?, 
    FAX?, 
    PAGER?, 
    MSG?, 
    CELL?, 
    VIDEO?, 
    BBS?, 
    MODEM?, 
    ISDN?, 
    PCS?, 
    PREF?, 
    NUMBER
  )>

    <!-- Phone number value. -->
    <!ELEMENT NUMBER (#PCDATA)>

  <!-- Email address property. Default type is INTERNET. -->
  <!ELEMENT EMAIL (
    HOME?, 
    WORK?, 
    INTERNET?, 
    X400?, 
    USERID
  )>

    <!ELEMENT USERID (#PCDATA)>
  
  <!-- Mailer (e.g., Mail User Agent Type) property. -->
  <!ELEMENT MAILER (#PCDATA)>
  
  <!-- Time zone's Standard Time UTC offset. Value must be an
    ISO 8601 formatted UTC offset. -->
  <!ELEMENT TZ (#PCDATA)>
  
  <!-- Geographical position. Values are the decimal degress of
    LATitude and LONgitude. The value should be specified to six decimal places.-->
  <!ELEMENT GEO (LAT, LON)>
  
    <!-- Latitude value. -->
    <!ELEMENT LAT (#PCDATA)>
	
    <!-- Longitude value. -->
    <!ELEMENT LON (#PCDATA)>
	
  <!-- Title property. -->
  <!ELEMENT TITLE (#PCDATA)>

  <!-- Role property. -->
  <!ELEMENT ROLE (#PCDATA)>
  
  <!-- Organization logo property. -->
  <!ELEMENT LOGO ((TYPE, BINVAL) | EXTVAL)>
  
  <!-- Administrative agent property. -->
  <!ELEMENT AGENT (VCARD | EXTVAL)>
  
  <!-- Organizational name and units property. -->
  <!ELEMENT ORG (ORGNAME, ORGUNIT*)>
  
    <!ELEMENT ORGNAME (#PCDATA)>
  
    <!ELEMENT ORGUNIT (#PCDATA)>
  
  <!-- Application specific categories property. -->
  <!ELEMENT CATEGORIES (KEYWORD+)>
  
    <!ELEMENT KEYWORD (#PCDATA)>
  
  <!-- Commentary note property. -->
  <!ELEMENT NOTE (#PCDATA)>
  
  <!-- Identifier of product that generated the vCard property. -->
  <!ELEMENT PRODID (#PCDATA)>
  
  <!-- Last revised property. The value must be an ISO 8601 formatted UTC date/time. -->
  <!ELEMENT REV (#PCDATA)>
  
  <!-- Sort string property. -->
  <!ELEMENT SORTSTR (#PCDATA)>
  
  <!-- Formatted name pronunciation property. The value is either a textual phonetic
    pronunciation, a BASE64 encoded binary digital audio pronunciation or a URI to
    an external binary digital audio pronunciation.-->	
  <!ELEMENT SOUND (PHONETIC | BINVAL | EXTVAL)>
  
    <!-- Textual phonetic pronunciation. -->
    <!ELEMENT PHONETIC (#PCDATA)>
   
  <!-- Unique identifier property. -->
  <!ELEMENT UID (#PCDATA)>
  
  <!-- Directory URL property. -->
  <!ELEMENT URL (#PCDATA)>
  
  <!-- Privacy classification property. -->
  <!ELEMENT CLASS (PUBLIC | PRIVATE | CONFIDENTIAL)>
  
    <!ELEMENT PUBLIC EMPTY>
	
    <!ELEMENT PRIVATE EMPTY>
	
    <!ELEMENT CONFIDENTIAL EMPTY>
	
  <!-- Authentication credential or encryption  key property. -->
  <!ELEMENT KEY (TYPE?, CRED)>
  
    <!ELEMENT CRED (#PCDATA)>

<!-- ==== -->

<!-- Common elements. -->

<!-- Addressing type indicators. -->
<!ELEMENT HOME EMPTY>
<!ELEMENT WORK EMPTY>
<!ELEMENT POSTAL EMPTY>
<!ELEMENT PARCEL EMPTY>
<!ELEMENT DOM EMPTY>
<!ELEMENT INTL EMPTY>
<!ELEMENT PREF EMPTY>
<!ELEMENT VOICE EMPTY>
<!ELEMENT FAX EMPTY>
<!ELEMENT PAGER EMPTY>
<!ELEMENT MSG EMPTY>
<!ELEMENT CELL EMPTY>
<!ELEMENT VIDEO EMPTY>
<!ELEMENT BBS EMPTY>
<!ELEMENT MODEM EMPTY>
<!ELEMENT ISDN EMPTY>
<!ELEMENT PCS EMPTY>
<!ELEMENT INTERNET EMPTY>
<!ELEMENT X400 EMPTY>

<!-- Format type parameter. -->
<!ELEMENT TYPE (#PCDATA)>

<!-- Base64 encoded binary value. -->
<!ELEMENT BINVAL (#PCDATA)>

<!-- URI to external binary value -->
<!ELEMENT EXTVAL (#PCDATA)>

<!-- ==== -->
			


Chapter 10. X Namespaces

Jabber x namespaces allow any Jabber entity to expand upon the Jabber protocol to create a new namespace for exchanging information.

jabber:x:autoupdate

Name

jabber:x:autoupdate -- client update notification

Description

This extension allows the update server to notify clients that a new version of the application is available.

Context

This namespace is only valid in a x element. Should be used within a message.

Elements

No elements are usually used with this namespace. An address should be provided for the client to query for more information.

See Also

For detailed information about the entire auto update process, see Chapter 7.

Examples

See Chapter 7 for examples.

DTD

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

<!ELEMENT x (#PCDATA)>
			

jabber:x:delay

Name

jabber:x:delay -- mark object as delayed

Description

If a message or presence is sent to an offline Jabber entity, the server stores it. When the entity comes online, the data is deliverd. This extension allows the receiving Jabber entity to see when the message was originally sent (as opposed to when it is received).

Context

This namespace is only valid in an x element. It is normally used within a message or a presence.

Attributes

  • stamp

    The stamp attribute specifies when the parent was stored offline. The time and date are expressed using a standard date format. The format is specified in ISO 8601 (available in PDF from ftp://ftp.qsl.net/pub/g1smd/8601v03.pdf). The format can be summarized as:

    [4 digit year][2 digit month][2 digit day]T[2 digit 24-hour]:[2 digit minute]:[2 digit second]
    					

  • from

    The from attribute denotes who caused the parent to be stamped. If you are confused by this, consider the following:

    • In the case of a message, the from attribute is equal to the JID of the recipient. Reason: The filter rules of the recipient caused the message to be stored offline, and thus it was stamped. Since the user controls his filter rules, he is responsible for the stamping.

    • In the case of presence, the from attribute is equal to the JID of the sender. Reason: Sending presence causes the server to stamp it and then store it. Thus, the entity broadcasting the presence caused it to be stamped.

Elements

No elements are used within this namespace.

Examples

Example 10-1. Delayed Presence

<presence from="hamletdenmark" to="horatio@denmark">
  <x
  xmlns="jabber:x:delay" 
  from="hamlet@denmark" 
  stamp="20000106T06:35:29"/>
</presence>
			

Example 10-2. Delayed Message

<message from="hamlet@denmark" to="horatio@denmark">
  <body>
    Let the King have the letters I sent; and 
    repair thou to me with as much speed as
    thou wouldst fly death. I have words
    to speak in thine ear will make thee 
    dumb; yet they are much too light for 
    the bore of the matter.
  </body>
  <x
    xmlns="jabber:x:delay" 
    from="horatio@denmark" 
    stamp="20000106T06:35:29"/>
</message>
			

DTD

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

<!ELEMENT x (#PCDATA)>

  <!ATTLIST x
    stamp PCDATA #IMPLIED
    from PCDATA #IMPLIED
  >
			

jabber:x:oob

Name

jabber:x:oob -- out of band data (attachment)

Description

This extension allows clients to exchange a standard URL with a description. URL's exchanged using jabber:x:oob can be included with any message, and act as an "attachment" in the email sense. Multiple "attachments" using this namespace can be included in a message.

Sending parties receive no confirmation of reciept, if a confirmation is required (for example, for a file transfer), use jabber:iq:oob.

Context

This namespace is only valid in a x element. While usually an out of band transfer would only be appropriate in a message, there is no server or client limit on where this namespace could appear in a stream.

Elements

The elements used for jabber:x:oob include: url and desc.

Examples

Example 10-1. Sending a Web URL

<message from="sailor@denmark" to="horatio@denmark">
  <body>
    URL Attached.
  </body>
  <x xmlns="jabber:x:oob">
    <url>
      http://denmark/act4/letter-1.html
    </url>
    <desc>
      There's a letter for you sir: it comes from
      the ambassador that was bound for England:
      if your name be Horatio, as I am let to know it is.
    </desc>
  </x>
</message>
			

DTD

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

<!ELEMENT x ((url? | desc?)*)>

  <!ELEMENT url (#PCDATA)>

  <!ELEMENT desc (#PCDATA)>
			

jabber:x:roster

Name

jabber:x:roster -- roster items within a message

Description

This extension namespace allows roster items to be sent as an attachement to a message. Clients may implement this for sending contacts to other users.

Context

This namespace is only valid in a x element. While usually found in a message, there is no server or client limit on where this namespace could appear in a stream.

Elements

The elements used in this namespace include: item, and group.

Examples

Example 10-1. Sending Roster Items in a Message

<message to="hamlet@denmark">
  <subject>Roster Items</subject>
  <body>
    Here are some new Jabber users
    to add to your Roster!
  </body>
  <x xmlns="jabber:x:roster">
    <item jid="claudius@denmark" name="King">
      <group>Royalty</group>
    </item>
    <item jid="horatio@denmark" name="Horatio">
      <group>Friends</group>
    </item>
    <item jid="fortinbras@norway" name="Prince Fortinbras"/>
  </x>
</message>
			

DTD

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

<!ELEMENT x ((item)*)>

  <!ELEMENT item ((group)*)>

    <!ATTLIST item
      jid PCDATA #IMPLIED
      name PCDATA #IMPLIED
    >

    <!ELEMENT group (#PCDATA)>
			


Chapter 11. Protocol Elements

Because Jabber uses XML to form its protocol it is imperative that an understanding of the elements and their usage is found. The following is a comprehensive breakdown of the elements used in the Jabber protocol and implementation notes from the early Jabber client authors.

address

Name

address -- the address of a Jabber user

Description

The address element is used to specify the address of a Jabber user during registration.

Body

The element contains a PCDATA address.

Attributes

No required attributes.

Children

There are currently no children.

Implementation

The address element is used during a jabber:iq:register conversation to send the server the address of the Jabber user being registered. This information is used for server use only and is not passed back to other clients.

Examples

See jabber:iq:register for examples of use in jabber:iq:register.

agent

Name

agent -- wrapper element used to describe a server agent

Description

The agent element is used to wrap textual information sent to the client about an agent.

Attributes

  • jid

    The JID of the agent. Must be a FQDN.

Children

May contain one or more of the following: name, description, service, register, search, transport.

Implementation

The agent wrapper is sent to clients in a jabber:iq:agent response after the client requests for specific agent information. Similarly, a jabber:iq:agents response will be sent with multiple agent information.

Examples

See jabber:iq:agent and jabber:iq:agents for examples.

beta

Name

beta -- indicates a beta software release

Desciption

A wrapper element used to indicate that the software described is a beta release.

Body

This is an element wrapper.

Attributes

  • priority

    Indicates priority of the software update.

    • optional

      Not a critical update and user should be given a choice of updating or not.

    • mandatory

      A critical update that all clients should be required to download and install. Often indicates a severe security fix.

Children

May contain version, url, and desc as children.

Implementation

Used in jabber:iq:autoupdate to provide release information about a beta software update.

Examples

See jabber:iq:autoupdate for examples.

body

Name

body -- the body of a message

Desciption

The body contains the actual message sent to a user for a message element.

Body

PCDATA of the actual message text to show a user.

Attributes

No required attributes

Children

There are currently no children

Implementation

The body element will only be found as a child of a message element. This element is sender generated.

Examples

See the message element for an example.

city

Name

city -- the home city of a Jabber user

Description

The city element is used to specify the home city of a Jabber user during registration.

Body

The element contains a PCDATA city name.

Attributes

No required attributes.

Children

There are currently no children.

Implementation

The city element is used during a jabber:iq:register conversation to send the server the name of the home city of the Jabber user being registered. This information is used for server use only and is not passed back to other clients.

Examples

See jabber:iq:register for examples of use in jabber:iq:register.

date

Name

date -- a date related to a Jabber user

Description

The date element is used to specify related to a Jabber user during registration.

Body

The element contains a PCDATA date.

Attributes

No required attributes.

Children

There are currently no children.

Implementation

The date element is used during a jabber:iq:register conversation to send the server some date related to the Jabber user being registered. This information is used for server use only and is not passed back to other clients.

Examples

See jabber:iq:register for examples of use in jabber:iq:register.

desc

Name

desc -- element used to describe a URL

Description

The desc element is used to give a friendly description of a URL.

Body

A free-form PCDATA string.

Attributes

No required attributes.

Implementation

Used within jabber:x:oob and jabber:iq:autoupdate.

Examples

See jabber:x:oob and jabber:iq:autoupdate for appropriate examples.

description

Name

description -- element used to describe a server agent

Description

The description element is used to describe precisely what a server agent provides for the user.

Body

The element contains a string that describes the server agent.

Attributes

No required attributes.

Children

There are currently no children.

Implementation

The description element is sent to clients along with other textual agent information wrapped within an agent element.

Examples

See jabber:iq:agent for an examples.

dev

Name

dev -- indicates a development software release

Desciption

A wrapper element used to indicate that the software described is a development release.

Body

This is an element wrapper.

Attributes

  • priority

    Indicates priority of the software update.

    • optional

      Not a critical update and user should be given a choice of updating or not.

    • mandatory

      A critical update that all clients should be required to download and install. Often indicates a severe security fix.

Children

May contain version, url, and desc as children.

Implementation

Used in jabber:iq:autoupdate to provide release information about a development software update.

Examples

See jabber:iq:autoupdate for examples.

digest

Name

digest -- secure method of passing a password

Description

The digest element is used in place of password to send a SHA1 hash of the password instead of sending the password in plain text.

Body

The element contains a PCDATA string of the user's password in a standard HEX SHA1 hash using the password and the session ID.

Attributes

No required attributes.

Children

There are currently no children.

Implementation

This element is a child element used in jabber:iq:auth for sending an encrypted password for authentication.

Examples

See jabber:iq:auth for an example of use within jabber:iq:auth.

display

Name

display -- used to specify the current time in a friendly format

Description

The display element encloses the current time and date information in a friendly format that the sending party accepts as a standard way to display the time and date. For date information that requires a true standard, use the utc element.

Body

The element contains a PCDATA string of the current date and time in free form text.

Attributes

No required attributes.

Children

There are currently no children.

Implementation

This element is used during a jabber:iq:time conversation to send the current date and time.

Examples

See jabber:iq:time for examples of use in jabber:iq:time.

email

Name

email -- the email address of a Jabber user

Description

The email element is used to specify the email address of a Jabber user during registration.

Body

The element contains a PCDATA email address.

Attributes

No required attributes.

Children

There are currently no children.

Implementation

The email element is used during a jabber:iq:register conversation to send the server the email address of the Jabber user being registered. This information is used for server use only and is not passed back to other clients.

Examples

See jabber:iq:register for examples of use in jabber:iq:register.

error

Name

error -- element used to communicate an error

Desciption

The error element is used to display error information resulting from a malfunction somewhere. The predefined error codes can be used to intepret the error messages if they are not sent with a body further describing what occured.

Body

The element contains a string that describes the error that occurred.

Attributes

  • code

    Table 11-1. Error Codes

    CodeDescription
    400Bad Request
    401Unauthorized
    402Payment Required
    403Forbidden
    404Not Found
    405Not Allowed
    406Not Acceptable
    407Registration Required
    408Request Timeout
    409Username Not Available
    500Internal Server Error
    501Not Implemented
    502Remote Server Error
    503Service Unavailable
    504Remote Server Timeout

Implementation

The error message conveys both a generic and specific error message to a user. The error element can be found as a child of either the iq or the message elements. The error code conveys a more general description of the error that occured, as described in the above table. The 500 series error messages indicate that the attempted service has been dropped.

Examples

Example 11-1. Error In a Message

<message type="error" id="1001">
  <error code="500">Could not process request</error>
</message>
			

Example 11-2. Error In an IQ

<iq type="error" id="1002">
  <error code="400">Invalid Password</error>
</iq>
			

first

Name

first -- the first name of a Jabber user

Description

The first element is used to specify the first name of a Jabber user during registration.

Body

The element contains a PCDATA first name of a user.

Attributes

No required attributes.

Children

There are currently no children.

Implementation

The first element is used during a jabber:iq:register conversation to send the server the first name of the Jabber user being registered. This information is used for server use only and is not passed back to other clients.

Examples

See jabber:iq:register for examples of use in jabber:iq:register.

group

Name

group -- a roster group that an item belongs to

Description

The group element is used to segregate a user's roster items into seperate and distinct groups. The various groups of users should be seperated in the client with a tree or some other visual grouping mechanism. Each group is user definable.

Body

May contain a PCDATA string to indicate the group that this item belongs to. This information is usually from the user and may be a string like "Friends" or "Work Associates." If the body is empty (group/group or more appropriatly, group/), then this user will not be associated with any group.

Attributes

This element has no attributes.

Children

No children.

Implementation

This element is used within jabber:iq:roster and jabber:x:roster as a child of item.

Examples

See jabber:iq:roster and jabber:x:roster for examples.

groupchat

Name

Groupchat -- indicates that a service has groupchat capabilities

Description

This element is a flag sent from a server service to indicate support groupchat support.

Body

No body.

Attributes

No required attributes.

Children

There are currently no children.

Implementation

The groupchat flag is sent as a child of agent (jabber:iq:agent).

Notes

Some transports both have flag register/> and groupchat/>. In this case, you might or might not need to be registered with the agent to use its groupchat capability. Currently, the only way to determine what is the case, is to try to a group via this agent. If you get error 407, you have to register first.

Examples

Example 11-1. Client Request For Agent

<iq type="get" id="1001" to="gc.denmark">
  <query xmlns="jabber:iq:agent"/>
</iq>
			

Example 11-2. Agent Reply

<iq type="result" id="1001">
  <query xmlns="jabber:iq:agent">
    <name>Conference Server</name>
    <description>
      You can create and participate 
      in private group conferences.
    </description>
    <service>conference</service>
    <groupchat/>
    <register/>
  </query>
</iq>
			

instructions

Name

instructions -- used to give instructions to the user

Description

The instructions element is used to give directions to the user to make a certain task easier or more understandable.

Body

The element contains an instructive string pertaining to the current task.

Attributes

No required attributes.

Children

There are currently no children.

Implementation

The instructions element is sent to clients along with other information wrapped in a query result from jabber:iq:register.

Examples

See jabber:iq:register for examples.

item

Name

item -- a roster item

Description

The item element provides clients with detailed information about a roster item.

Body

No PCDATA is usually sent within this element.

Attributes

  • jid

    A complete JID of the user that this item represents.

  • subscription

    The current status of the subscription related to this item.The server sets this attribute and the client has no direct control over this value. May be one of:

    • none

      No subscription.

    • from

      They have a subscription to us.

    • to

      We have a subscription to this item.

    • both

      Subscription is to and from.

  • ask

    The current status of a request to this item. May be one of:

    • subscribe

      A request for a subscription from the entity is pending.

    • unsubscribe

      A request for unsubscription from the entity is pending.

Children

This element may contain one more more group elements.

Implementation

This element is used within jabber:iq:roster and jabber:x:roster.

Note: When used within jabber:x:roster, the attributes subscription and ask should not be present.

Examples

See jabber:iq:roster and jabber:x:roster for examples.

iq

Name

iq -- structured wrapper around anonymous XML data

Desciption

Info/Query is a simple "client/server" framework within Jabber. It structures a rudimentary conversation between any two entities in Jabber and allows them to pass XML formatted queries and responses back and forth.

Attributes

  • to

    The JID of who the iq is bound for.

  • from

    The JID of who the iq is from.

  • id

    A unique identifier for the iq. Sender of the iq sets this attribute.

  • type

    Describes the type of message so that different GUI styles may be supported by the clients. Allowable types are:

    • get

      Default, assumed if no type="" attribute is given.

    • error

      The query failed. The actual error is described in an error element inside the iq.

    • set

      This query contains data intended to set values or replace existing values.

    • result

      This is a successful response to a get/set query.

Children

The iq element may contain query and error.

Implementation

IQ is one of the must fundamental building blocks of the Jabber protocol. IQ elements may be sent or received at any point in the stream, although their success is dependant on the xmlns definition of their child element (most commonly query). IQ is never sent without a child element unless the type is a "result". To better track results with queries the ID attribute is echoed back to the sender with the resulting type.

Examples

Fictional Namespaces: The namespaces used in the following examples are fictional. The format of the IQ conversations is, however, very similar to actual IQ conversations with existing namespaces.

Example 11-1. Simple Query

<iq type="get" to="horatio@denmark" id="1001">
    <query xmlns="jabber:iq:info">
		<name/>
		<email/>
	</query>
</iq>
			

Example 11-2. Result to Previous Example

<iq type="result" from="horatio@denmark" id="1001">
    <query xmlns="jabber:iq:info">
		<name>Horatio</name>
		<email>horatio@denmark</email>
	</query>
</iq>
			

Example 11-3. Setting Information

<iq type="set" to="fortinbras@norway" id="1002">
    <query xmlns="jabber:iq:notepad">
		<reminder>Don't forget to meet me on your way to Poland.</reminder>
	</query>
</iq>
			

Example 11-4. Result to IQ Set

<iq type="result" from="fortinbras@norway" id="1002"/>
			

key

Name

key -- IQ spoof protection

Description

The key element is designed to verify the sender in iq set methods. A server entity sends a random string in the key elements that the client must use to return information back to the server in a set method. If the key is missing or is not exactly the same, the server will ignore the set request.

Body

A random string generated by the server.

Attributes

No required attributes.

Children

There are currently no children.

Implementation

Used within various IQ namespaces.

Examples

See the appropriate IQ namespace for examples.

last

Name

last -- the last name of a Jabber user

Description

The last element is used to specify the last name of a Jabber user during registration.

Body

The element contains a PCDATA last name of a user.

Attributes

No required attributes.

Children

There are currently no children.

Implementation

The last element is used during a jabber:iq:register conversation to send the server the last name of the Jabber user being registered. This information is used for server use only and is not passed back to other clients.

Examples

See jabber:iq:register for examples of use in jabber:iq:register.

message

Name

message -- element used for all messages

Desciption

The message is the basis for passing messages in the Jabber world.

Body

This is an element wrapper.

Attributes

  • to

    The JID of who the message is bound for.

  • from

    The JID of who the message is from. The server automatically adds and fills this attribute.

  • id

    A unique identifier for the message. Sender of the message sets this attribute.

  • type

    Describes the type of message so that different GUI styles may be supported by the clients. Allowable types are:

    • normal

      Default type, is assumed when no type is given.

    • error

      A special type to define error messages. The actual error message is found in the error element.

    • chat

      Line by line chat interface.

    • groupchat

      GUI hint for a group style chat interface. Also notes that a message will be sent out to a group of people, not a single user.

    • headline

      News headlines.

Children

The message element may contain body, subject, thread, error, or x.

Implementation

General

The message element is one of the most primary elements in Jabber, and can be sent or received at any time after the initial jabber:iq:auth transaction has occured. For more information regarding correctly generating and processing messages please see the children elements.

Rich Text

To extend messages for more "rich" text, the Jabber protocol encourages use of XHTML Basic. A plain text copy of the message should be included in the standard body so that clients that do not support XHTML Basic can still view the message. An example of using XHTML Basic is provided in the examples below.

IRC Action Command

Clients and transports should automatically interpret the IRC "action" command to an appropriatly formatted block. A simple example:

/me is hungry
					

Would be rendered as:

* Nickname is hungry
					

Where Nickname would equal the user's username or nickname (depending on implementation -- the ICQ transport for example would use the user's nickname).

Examples

Example 11-1. Basic Jabber Message

<message to="horatio@denmark">
  <body>Angels and Ministers of Grace, defend us!</body>
</message>
			

Example 11-2. Basic Jabber Message Using XHTML Basic

<message to="horatio@denmark">
  <body>Angels and Ministers of Grace, defend us!</body>
  <html xmlns="http://www.w3.org/TR/xhtml-basic">
    <body>
      <div style="font-size: medium;
        color: red;
        text-align: center">
        Angels and Ministers of Grace, defend us!
      </div>
    </body>
  </html>
</message>
			

Example 11-3. Complete Jabber Message

<message to="hamlet@denmark" type="chat" from="horatio@denmark">
  <subject>Plotting</subject>
  <body>
    Here, sweet lord, at your service.
  </body>
  <thread>2001</thread>
</message>
			

Example 11-4. Reply to Complete Jabber Message

<message to="horatio@denmark" type="chat" from="hamlet@denmark">
  <subject>Plotting</subject>
  <body>
    Horatio, thou art e'en as just a man
    As e'er my conversation coped withal.
  </body>
  <thread>2001</thread>
</message>
  			

misc

Name

misc -- wrap misc information an agent needs for registration

Description

The misc element can be used by an agent during registration for any purpose it needs.

Body

The element contains any PCDATA.

Attributes

No required attributes.

Children

There are currently no children.

Implementation

The misc element can be used by an agent during registration for any purpose it needs.

Examples

See jabber:iq:register for examples of use in jabber:iq:register.

name

Name

name -- element used for a descriptive name

Description

The name element is used in several namespaces to give a descriptive title of a server agent, a Jabber user or the name of a client application.

Body

The element contains a PCDATA free-form string that describes the user, agent or client application.

Attributes

No required attributes.

Children

There are currently no children.

Implementation

The name element is sent to clients along with other textual agent information wrapped within an agent element.

The name element is used during a jabber:iq:register conversation to send the server the full name of the Jabber user being registered. This information is used for server use only and is not passed back to other clients.

Within jabber:iq:version, this element is used to describe the client application.

Examples

See jabber:iq:agent for examples of use in agent properties.

See jabber:iq:register for examples of use in jabber:iq:register.

See jabber:iq:register for examples of use in jabber:iq:version.

nick

Name

nick -- friendly name of a user

Description

The nick element is used with some foreign instant messanging systems to give a friendly name for a user. Jabber does not use this information for any purposes.

Body

The element contains a PCDATA string representing a user's nick name.

Attributes

No required attributes.

Children

There are currently no children.

Implementation

The nick element is used with some agents for registration in jabber:iq:register.

Examples

See jabber:iq:register for examples of use in jabber:iq:register.

os

Name

os -- the operating system of an entity

Description

Describes the operating system of a Jabber entity.

Body

The element contains a free-form PCDATA string with the operating system name and version.

Attributes

No required attributes.

Children

There are currently no children.

Implementation

The os element is used during a jabber:iq:version conversation to send the requesting entity the operating system and version of the queried entity.

Examples

See jabber:iq:version for examples of use in jabber:iq:version.

password

Name

password -- element used in conjunction with username

Description

The password element is used in situations like authentication or registration to send the server a password for logging in.

Body

The element contains a PCDATA string of a password.

Attributes

No required attributes.

Children

There are currently no children.

Implementation

This element is a child element used in jabber:iq:auth for sending a password for authentication.

When used in jabber:iq:register, this element registers a password with the server or an agent for future authentications.

Examples

See jabber:iq:auth for an example of use within jabber:iq:auth.

jabber:iq:register has examples of usage with jabber:iq:register.

phone

Name

phone -- the phone number of a Jabber user

Description

The phone element is used to specify the phone number of a Jabber user during registration.

Body

The element contains a PCDATA phone number.

Attributes

No required attributes.

Children

There are currently no children.

Implementation

The phone element is used during a jabber:iq:register conversation to send the server the phone number of the Jabber user being registered. This information is used for server use only and is not passed back to other clients.

Examples

See jabber:iq:register for examples of use in jabber:iq:register.

presence

Name

presence -- control over user availability and subscriptions

Desciption

Presence is the system for expressing availability and subscriptions to other users availability.

Attributes

  • to

    The JID of who the presence is bound for. If none is specified the server receives the presence.

  • from

    The JID of who the presence is from. The server puts this attribute into presences to prevent spoofing.

  • id

    A unique identifier for the presence. Sender of the presence sets this attribute.

  • type

    Describes the type of presence so that different GUI styles may be supported by the clients. Allowable types are:

    • available

      Default. Signals that you are online.

    • unavailable

      You are no longer available. Allows for offline options to be set.

    • suscribe

      An attempt to subscribe to the users presence

    • subscribed

      The subscribe attempt was successful.

    • unsubscribe

      A user is unsubscribing from your presence. The server handles the actual unsubscription, as is sent just for notification.

    • unsubscribed

      A presence unsubscribe completed succesfully.

    • probe

      A query to a users presence. The server processes these requests. Note that clients do not need to handle this type - it is server only.

Children

The presence element may contain show, status, priority, or x.

Implementation

Like other primary elements this one may be sent any time after successfully logging in to a Jabber account.

To enable an account to receive any messages or other notifications it must send an available presence to the server.

Whenever a subscription event takes place that results in a modified roster, the Jabber server will push the new roster item to you (more information in jabber:iq:roster).

Examples

Example 11-1. Initial Presence

<presence/>
			

Example 11-2. Request to Subscribe

<presence to="horatio@denmark" type="subscribe"/>
			

Example 11-3. Response to Subscribe Request

<presence to="hamlet@denmark" type="subscribed"/>
			

Example 11-4. Complete Presence Information

<presence from="hamlet@denmark">
    <show>na</show>
    <status>Gone to England</status>
</presence>
			

priority

Name

priority -- the ability to rank a user's presence

Description

Using prioritized presence clients can tell the server which resources should receive messages bound to an account.

Body

A numerical value representing the priority.

Attributes

There are no required attributes.

Children

Currently has no children.

Implementation

When a resource is given higher priority than previous resources, all messages and other events bound for the user (user@host) will be sent to that resource. If two resources have the same priority the most recent to login will receive the events. It should be noted that messages sent directly to a resource (user@host/resource) will always go directly to that resource if it is available.

Examples

See the presence element for examples.

query

Name

query -- place holder for iq structures

Description

The body of this element is variable based upon the xmlns. This is used as a child of iq and primarily used to bring extra functionality and extensibility to jabber.

Body

Elements as defined by the queries xmlns attribute.

Attributes

  • xmlns

    The namespace for the query.

Children

There are currently no children.

Implementation

A query element is never used without a parent element.

Examples

See iq for examples.

register

Name

register -- element used to indicate that a service can be registered with

Description

The register element is a flag that indicates to Jabber entities that the particular server agent can be registered with. Lack of this flag indicates that no registration is possible.

Body

No body.

Attributes

No required attributes.

Children

There are currently no children.

Implementation

The register element is sent to clients along with other textual agent information wrapped within an agent element.

Examples

See jabber:iq:agent for an example.

registered

Name

registered -- element used to indicate that one is already registered with a service.

Description

The registered element is a flag that indicates to Jabber entities that they are registered with a particular server agent. Lack of this flag indicates that no registration has taken place yet.

Body

No body.

Attributes

No required attributes.

Children

There are currently no children.

Implementation

The registered element is used in jabber:iq:register.

Examples

See jabber:iq:register for an example.

release

Name

release -- indicates a stable software release

Desciption

A wrapper element used to indicate that the software described is a stable release.

Body

This is an element wrapper.

Attributes

  • priority

    Indicates priority of the software update.

    • optional

      Not a critical update and user should be given a choice of updating or not.

    • mandatory

      A critical update that all clients should be required to download and install. Often indicates a severe security fix.

Children

May contain version, url, and desc as children.

Implementation

Used in jabber:iq:autoupdate to provide release information about a stable software update.

Examples

See jabber:iq:autoupdate for examples.

remove

Name

remove -- element used to indicate to a service that the specified account should be removed

Description

The remove element is a flag sent to any server service to indicate that the specified account should be removed.

Body

No body.

Attributes

No required attributes.

Children

There are currently no children.

Implementation

The remove element is used within jabber:iq:register to be sent from a client to a service. A key must be received and passed back to the server with the removal request.

Examples

Example 11-1. Remove account from the Jabber AIM service (notice that the key must be returned to the server).

<iq type="set" to="aim.denmark" id="1001">
	<query xmlns="jabber:iq:register">
		<remove/>
		<key>106c0a7b5510f192a408a1d054150ed1065e255a</key>
	</query>
</iq>
			

resource

Name

resource -- element used to set resource

Description

The resource element is used during authentication to set the resource for the current session.

Body

The element contains a PCDATA string of a resource.

Attributes

No required attributes.

Children

There are currently no children.

Implementation

This element is a child element used in jabber:iq:auth for sending the desired resource.

Examples

See jabber:iq:auth for an example of use within jabber:iq:auth.

search

Name

search -- indicates that a service has user searching capabilities

Description

The search element is a flag sent from a server service to indicate to clients that the service supports jabber:iq:search.

Body

No body.

Attributes

No required attributes.

Children

There are currently no children.

Implementation

The search flag is sent within agent (jabber:iq:agent). To use the search capabilities of a service, jabber:iq:search must be used.

Examples

See jabber:iq:agent for examples of this flag being used.

service

Name

service -- element used to classify server agents

Description

The service element is used to give a standard descriptive string to a server agent. With this standard string, entities can search the server for a specific service without knowing the agent's JID.

Body

The element contains a short string that associates the service to its functionality. The following list of types are currently being used, more can be created as needed:

Table 11-1. Service Types

ValueDescription
aimAmerica Online Instant Messenger Transport
icqICQ Transport
conferenceGroup Chat (conference) Agent
oobproxyOut-of-Band File Transfers for Firewall Users

Attributes

No required attributes.

Children

There are currently no children.

Implementation

The service element is sent to clients along with other textual agent information wrapped within an agent element.

Examples

See jabber:iq:agent for an examples.

show

Name

show -- exact user availability

Desciption

Tells client applications how to display a user's online presence using a fixed set of options. The available options represent "away from the computer," "free for chat," "away from the computer for an extended period," and "do not disturb."

Body

One of away, chat, xa, or dnd.

Attributes

No required attributes.

Children

There are currently no children.

Implementation

This is primarily used for UI hints to show an icon next to a user's name.

Examples

See presence for an example.

state

Name

state -- the home country of a Jabber user

Description

The state element is used to specify the home country of a Jabber user during registration.

Body

The element contains a PCDATA home country.

Attributes

No required attributes.

Children

There are currently no children.

Implementation

The state element is used during a jabber:iq:register conversation to send the server the home country of the Jabber user being registered. This information is used for server use only and is not passed back to other clients.

Examples

See jabber:iq:register for examples of use in jabber:iq:register.

status

Name

status -- availability message

Desciption

Used in conjunction with show to give a custom description of a users availability. Also used with presence packets of type="subscribe" to indicate the reason for the subscription request.

Body

PCDATA to be displayed as presence status.

Attributes

No required attributes.

Children

There are currently no children.

Implementation

This element may only be a child of a presence element.

Examples

See presence for examples.

subject

Name

subject -- the subject of a message

Desciption

The subject for a message element.

Body

PCDATA of the message subject.

Attributes

No required attributes.

Children

There are currently no children

Implementation

This element may only be a child of a message element.

Examples

See message for examples.

text

Name

text -- wrap any text an agent needs for registration

Description

The text element can be used by an agent during registration for any purpose it needs.

Body

The element contains PCDATA text.

Attributes

No required attributes.

Children

There are currently no children.

Implementation

The text element is used during a jabber:iq:register conversation if specified by an agent. It can be used to store any information needed by that agent.

Examples

See jabber:iq:register for examples of use in jabber:iq:register.

thread

Name

thread -- an id representing the thread of a message

Body

Random CDATA.

Attributes

No required attributes.

Children

There are currently no children.

Desciption

The thread for a message element allows for precise tracking of a conversation. The recipient is required to always return the same identical contents when the message is directly replied to, so that the sender and recipient can identify replies and thread a conversation.

Implementation

This element may only be a child of a message element.

Examples

See message for examples.

transport

Name

Transport -- element used to describe the native title of a username

Description

The transport element is used to describe the native title of a username for a specific transport.

Body

The element contains a string that describes the title of a transport's native username.

Attributes

No required attributes.

Children

There are currently no children.

Implementation

The transport element is sent to clients along with other textual agent information wrapped within an agent element.

Examples

See jabber:iq:agent for an examples.

truncated

Name

truncated -- element used to indicate that search results were prematuraly ended

Description

The truncated element is a flag sent at the end of a jabber:iq:search to indicate that the search results were prematuraly ended and may not contain the complete results.

Body

No body.

Attributes

No required attributes.

Children

There are currently no children.

Implementation

The truncated element is used within jabber:iq:search.

Examples

See jabber:iq:search for complete examples.

tz

Name

tz -- used to specify the timezone of the sending party

Description

The tz element is used to signal the current timezone of the sending party (entity).

Body

The element contains a PCDATA string to specify the timezone (not abbreviated).

Attributes

No required attributes.

Children

There are currently no children.

Implementation

This element is used during a jabber:iq:time conversation.

Examples

See jabber:iq:time for examples of use in jabber:iq:time.

url

Name

URL -- element used to wrap a Universal Resource Locator (URL)

Description

The url element is used to exchange a Universal Resource Locator (URL).

Body

A PCDATA string that is a complete, standard URL (according to RFC1738).

Attributes

No required attributes.

Examples

See jabber:iq:agent, jabber:iq:register, jabber:iq:autoupdate, and jabber:x:oob for appropriate examples.

utc

Name

utc -- used to specify the current time

Description

The utc element is used to enclose the current time and date using a standard date format. The format is specified in ISO 8601 (available in PDF from ftp://ftp.qsl.net/pub/g1smd/8601v03.pdf). The format can be summarized as:

[4 digit year][2 digit month][2 digit day]T[2 digit 24-hour]:[2 digit minute]:[2 digit second]
			

Body

The element contains PCDATA in ISO 8601 format.

Attributes

No required attributes.

Children

There are currently no children.

Implementation

This element is used during a jabber:iq:time conversation to send the current date and time.

Examples

See jabber:iq:time for examples of use in jabber:iq:time.

username

Name

username -- element used to user identification

Description

The username element is used in situations like authentication or registration to send the server a distinct username for logging in.

Body

The element contains a PCDATA string of a user name. Standard JID rules apply. LINK LINK LINK

Attributes

No required attributes.

Children

There are currently no children.

Implementation

This element is a child element used in jabber:iq:auth for sending the desired user name for authentication.

jabber:iq:register uses this element for registering a user name with the server or an agent.

Examples

See jabber:iq:auth for an example of use within jabber:iq:auth.

See jabber:iq:register for an example of use within jabber:iq:register.

version

Name

version -- the version of a Jabber entity's application

Description

The version element is used to specify the exact version of a Jabber entity's application.

Body

The element contains a PCDATA string with a version number.

Attributes

No required attributes.

Children

There are currently no children.

Implementation

The version element is used during a jabber:iq:version conversation to send the version of a Jabber entity's client.

When used within jabber:iq:autoupdate, the version element notifies the reciever of the current version of the queried application.

Examples

See jabber:iq:version and jabber:iq:autoupdate for examples of use.

x

Name

x -- place holder for extension structures

Description

The body of this element is variable based upon the xmlns. This is used to bring extra functionality and extensibility to Jabber.

Body

Elements as defined by the extension xmlns attribute.

Attributes

  • xmlns

    The namespace for the extension.

Children

There are currently no children.

Implementation

A x element is never used without a parent element.

Examples

See Chapter 10 for examples of specific namespaces.

zip

Name

zip -- the zip code of a Jabber user

Description

The zip element is used to specify the zip code of a Jabber user during registration.

Body

The element contains a PCDATA zip code.

Attributes

No required attributes.

Children

There are currently no children.

Implementation

The zip element is used during a jabber:iq:register conversation to send the server the zip code of the Jabber user being registered. This information is used for server use only and is not passed back to other clients.

Examples

See jabber:iq:register for examples of use in jabber:iq:register.

Glossary

A

Agent

A server-side program designed to provide extra functionality to Jabber users. May be nearly any type of server-side automated entity, examples include language translations, stock market server, news server, and a calendar sharing server.

See Also: Transport.

E

Extensible Markup Language
(XML)

A universal format for structured documents and data on the Web. The entire Jabber protocol is based on XML and XML Namespaces. The XML standard is developed and maintained by the W3C.

See Also: XML Namespaces.

F

Fully Qualified Domain Name
(FQDN)

A fully qualified domain name is used to locate a machine on a network.

P

Presence

A Jabber entity's status. Includes the basics like online and offline and extends to more exact status information like Away, Do Not Disturb and Gone For Coffee.

See Also: Roster, Subscription.

R

Roster

The list of a user's contacts. The server stores this list on the server to keep track of the current state of subscriptions and to send out presence updates.

See Also: Presence, Subscription.

S

Subscription

A request to receive presence updates by another Jabber entity. Entity's may refuse subscriptions to dissalow the requesting party to see presence updates or aprove the subscription to let the requesting party to see presence updates.

See Also: Roster, Subscription.

T

Transport

A Jabber transport is a program running on the server that communicates to non-Jabber instant messaging systems. A transport acts as a "gateway" to other networks for Jabber users. A transport is a subset of the agents category.

See Also: Agent.

X

XHTML Basic

A subset of XHTML 1.1 (XML-based HTML) designed for web clients such as mobile phones, PDAs, pagers and television settop boxes. Currently a "Last Call Working Draft" of the W3C.

XML

See: Extensible Markup Language

XML Namespaces

XML namespaces provide a simple method for qualifying element and attribute names used in XML documents by associating them with namespaces identified by URI references. Currently a W3C recommendation.

See Also: Extensible Markup Language.


Chapter 12. About

Eliot Landrum

Currently a student at LeTourneau University in Longview, Texas, Eliot Landrum has been a member of the Jabber.org project since near its conception. Having always enjoyed writing, Eliot has found a satisfying position in the Open Source community. Jabber.com, Inc.'s continued support of Eliot has been a tremendous help in supporting the documentation needs of such a large open source project.