One of Jabber's strengths is its simplicity. Neither the technology
employed to build Jabber networks nor the protocol used to facilitate
conversations within those networks is complicated.
The aim of this chapter is to give you a good grounding in the technology
and the protocol. In the Preface we likened Jabber to chess: a small set of
rules but boundless possibilities. And, indeed, that is the case. In this
chapter we cover identification within Jabber -- how entities are addressed.
Related to identity is the concept of resources; we
look at how that relates to addressing, as well as its relationship to presence and priority.
The Jabber protocol is in XML, which is streamed between endpoints. We look
at the details of these XML streams and see how they're constructed. Comprised
of surprisingly few basic elements, the Jabber protocol is small but perfectly
formed. Each element of Jabber's protocol will be reviewed in detail.
With this chapter under your belt, your understanding of Jabber
fundamentals should be complete. Everything else is strategy, planning, and
The username is separated from the hostname with an @ symbol, and the
resource is separated from the hostname with a slash (/).
It's quite likely that the JIDs you may have encountered so far are those
representing users' connections, such as the firstname.lastname@example.org/Laptop example. This is not the only
sort of entity that JIDs are used to represent. As a Uniform Resource Locator
(URL) is fundamental to the HyperText Transport Protocol (HTTP), so a JID is
fundamental in Jabber. JIDs are used to represent not only users connected to
Jabber via their clients, but also every single entity in the Jabber universe
that is to be addressed -- in other words, that is to be the potential
recipient of a message. Before looking at the restrictions that govern how a
JID might be constructed (these restrictions are described in "Rules
and Regulations"), let's first look at some examples in which a JID is
employed to give entities their addressability:
In the previous section, we saw how the resource is used to "qualify"
certain queries to a servername, to hold information such as version numbers,
and to represent users in a conference room. However, the resource is
traditionally seen as a way of making a distinction between simultaneous
connections by a user to the same Jabber server. For example, if you connect
to a Jabber server using the same username and password on three different
machines (or resources), the Jabber server will look
at the resource part of the JID to determine which client to route messages
For the purpose of this example, let's say that the three resources are a
workstation, a laptop, and a PDA. Each client is connected to the same Jabber
server, so the resource part of the JID can be used to distinguish between the
three connections. They could also be used to differentiate between the three
connections coming from the same client host.
The classic explanation serves us well here: In a work situation, I might
be connected to my Jabber server using a client on my workstation. I might
also be connected, with the same username, to my Jabber server on my laptop
that's sitting next to my workstation. Furthermore, I might have a handheld
device that runs a small Jabber client that I'm connected with, too.
On each client machine, I'm connecting using the same credentials (username
and password) to the same Jabber server. So the resource part of a JID can be
used to distinguish between my three connections. In this example, the three
"resources" are my workstation, laptop, and handheld.
Figure 5-1 shows priority in action. In this example, Sabine's message is
sent to the Jabber client on the Desktop, as it has a higher priority. Note
that with Jabber priority, 1 has a lower priority than,
say, 5. The higher the number, the higher the priority.
In the event that there's a priority tie, the most recent connection to the
Jabber server wins. For example, if DJ connects to the server first from a
client running on his Laptop and then again later with a client running on his
Desktop system, and both clients have their priority set to a value of 1, the client running on his Desktop would win and receive
the incoming messages.
By now, you should already know that Jabber relies heavily on XML. XML
courses through Jabber's veins; data sent and received between entities, and
internally within the server itself, is formatted in XML packets.
However, the XML philosophy goes further than this. A connection between
two Jabber endpoints, say, a client and a server, is made via a TCP socket,
and XML is transferred between these endpoints. However, it's not just random
fragments of XML flowing back and forth. There is a structure, a choreography,
imposed upon that flow. The entire conversation that takes place between these
two endpoints is embodied in a pair of XML documents.
But what do we mean when we say that the conversation is an XML document?
To answer this, consider this simple XML document:
which is immediately followed by the opening root tag. This root tag is
significant because there can be only one (and, of course, its corresponding
closing tag) in the whole document. In effect, it wraps and contextualizes the
content of the document:
The real content of the document is made up of the XML fragments that come
after the opening root tag:
So, taking a connection between a Jabber client and a Jabber server as an
example, this is exactly what we have. The server is listening on port 5222
for incoming client-initiated connections. Once a client has successfully
connected to the Jabber server, it sends an XML declaration and the opening
root tag to announce its intentions to the server, which in turn responds by
sending an XML declaration and opening root tag of its own.
From then on, every subsequent piece of data that the client sends to the
server over the lifetime of the connection is an XML fragment (<fragmentN/>). The connection can be closed by the client by
sending the matching closing root tag. Of course, the connection can be also
closed by the server by sending the closing root tag of its XML document.
The fragments sent within the body of the XML document are the XML building
blocks on which Jabber solutions are based. These XML building blocks are
introduced and examined later in the chapter in "Jabber's
Suffice it to say here that these fragments can come in any order within
the body of the XML document, precisely because they're in the body. As long as an XML document has a root tag,
and the fragments themselves are well-defined, then it doesn't matter what the content is. Because of the way the document is
parsed -- in chunks, as it appears -- it doesn't matter if the fragments
appear over a long period, which is the case in a client/server connection
where messages and data are passed back and forth over time.
It should be fairly easy now to guess why this section (and the technique)
is called XML Streams. XML is streamedover a connection in the form of a document and is
parsed and acted upon by the recipient in fragments, as they appear.
The from attribute
The from attribute is fairly straightforward; it
normally serves to confirm to the client that the requested logical host is
available. For example:
If the host is available, the value of the from
attribute from the server will match the value of the to attribute from the client. However, in some
circumstances, the value can be different. The value sent in the from attribute is a redirection, or
respecification, of the logical host by which the
Jabber server (or more specifically the JSM component within the Jabber
server) is actually known.
Let's say that you're running a Jabber server on an internal network that
doesn't have an available DNS server. The host where the Jabber server runs is
called apollo, and its IP address is 192.168.1.4. Some people will connect to the host via the
hostname because they have it defined in a local /etc/hosts file; others will connect via the IP address.
Normally, the hostname (or IP address) specified in the connection parameters
given to a Jabber client will be:
If the JSM section of the Jabber server is defined to have a hostname of
then we need to make sure that the Jabber client uses that name when
forming any JIDs for that Jabber server (e.g., the JID apollo used as an addressee for an IQ browse request).
in our c2s instance configuration would mean that
any incoming XML stream header with a value of 192.168.1.4 in the to attribute:
would elicit the following response:
which effectively says: "OK, you requested 192.168.1.4, but please use apollo
instead." The client should use the value "confirmed" in the from attribute when referring to that Jabber server in all
subsequent stream fragments. That is to say, when wanting to address the
server, instead of sending something like this:
SEND <iq type='get' to='192.168.1.4'>
it should address it like this:
SEND <iq type='get' to='apollo'>
Not specifying an <alias/> tag in this example
would result in problems for the client. Without any way of checking and
converting incoming hostnames, the c2s component will
by default simply transfer the value from the to
attribute to the from attribute in its stream header
Following this thread to its natural conclusion, it's worth pointing out
that if we have an alias specification like this:
then the value of the from attribute in the reply
will always be set to apolloregardless of what's specified in the to attribute. This means that the to
attribute could be left out of the opening stream tag. Although this serves
well to illustrate the point, it is not good practice.
Simply point telnet to a Jabber server, specifying
port 5222, and send an opening tag. You will receive an opening tag, from the
server, in response:
yak:~$ telnet localhost 5222
Connected to localhost.
Escape character is '^]'.
<stream:stream xmlns:stream='http://etherx.jabber.org/streams' to='yak'
<?xml version='1.0'?><stream:stream xmlns:stream='http://etherx.jabber.org/streams'
id='3AFD839E' xmlns='jabber:client' from='yak'>
If you don't have a Jabber server to experiment with, see Chapter 3 on how
to set one up.
Using telnet is a great way to find out more about
the way the Jabber protocol works. Perhaps the next thing to do is try out the
user registration and authentication steps described in Chapter 7. But watch
out -- send some invalid XML and the server will close the connection on you!
At this stage we've got a good impression of the structure of Jabber: what
different elements make up a Jabber system, how entities in Jabber are
addressed, and how communication between these entities is carried.
Now it's time to look at what gets carried -- the
fragments that we touched upon in the previous section. These fragments are
the heart and soul of Jabber -- the lifeblood that
courses through Jabber's veins carrying information back and forth -- these
fragments in many ways define what Jabber is, what it stands for.
Surprisingly, when we look closely at these fragments, with Jabber's
capabilities as a messaging platform in mind, we see that there are only three
basic elements involved -- <message/>, <presence/>, and <iq/>.
Three different types of XML fragments, each with a different purpose. But
with these three fragment types -- these elements -- all that Jabber promises,
and more, can be achieved.
Now let's look at each of these Jabber elements in greater detail. But
before we do, let's dive into the XML stream and pull out a handful of XML
fragments to get us in the mood. Example 5-3 shows a chunk of conversation
between a Jabber client and a Jabber server, which occurred immediately after
the connection and authentication stages.
NOTE: Although any conversation between two
Jabber entities is contained within two XML documents exchanged in streams,
the traditional way to represent both documents at the same time is to use
prefixes to show whether a fragment is being sent (SEND:) or received (RECV:), by one
of the two entities. When appropriate, the perspective is taken from the
viewpoint of the entity that's not the Jabber
server; in the case of Example 5-3, the viewpoint is of the Jabber client.
The Message Element
It's obvious that in a messaging architecture such as Jabber, sending
messages is fundamental. The <message/> element
provides us with this facility. Any data, other than availability information
or structured requests and responses (which are handled by the other two
element types) sent from one Jabber entity to another, is sent in a <message/> element.
All things considered, the key word in that last sentence is "in." It's a
good idea to regard Jabber elements as containers; the
simile fits well as the elements themselves remain relatively static (save for
the attributes) but the content can change to reflect
When a message is sent, and a reply is expected, it is often useful to give
the outbound message an identifier. When the recipient responds, the
identifier is included in the response. In this way, the originator of the
message can work out which reply corresponds to which original message.
At the Jabber server, this works because a reply is usually built from a
copy of the original message, with the from and to attributes switched around. So the id attribute remains untouched and in place.
NOTE: Each id value
within a session, represented by one streamed XML document, must be unique
within that session, that is, within that one document.
Note that the content of the message must also be repeated in a normal <body/> subelement without formatting, to comply with
the "lowest common denominator" support for different Jabber clients -- not
all of them will be able to interpret the XHTML formatting, so they will need
to receive the message content in a way that they can understand.
The <html/> subelement effectively is a
wrapper around a second, alternative, <body/>
The <thread/> subelement is used by clients to
group together snippets of conversations (between users) so that the whole
conversation can be visually presented in a meaningful way. Typically a
conversation on a particular topic -- a thread -- will
be displayed in a single window. Giving each conversation thread an identity
enables a distinction to be made when more than one conversation is being held
at once and chat type messages, which are component
parts of these conversations, are being received (possibly from the same
correspondent) in an unpredictable sequence.
Only when a new topic or branch of conversation is initiated must a client
generate a thread value. At all other times, the correspondent client must
simply include the <thread/> tag in the response.
Here the thread value is generated from a hash of the message originator's JID
and the current time.
The information attached to a message is often called the payload. Multiple anchor points can be used to convey
multiple payloads, and each one must be qualified
using a namespace.
Just as the content of XML streams is qualified by a namespace (one from
the list in Table 5-2 earlier in this chapter), so the content of the <x/> attachment must be
qualified. There are a number of Jabber-standard namespaces that are defined
for various purposes. One of these, jabber:x:delay, is
used in the example. These standard namespaces are described in Chapter 6. But
there's nothing to stop you defining your own namespace to describe (and
qualify) the data that you wish to transport in a <message/>. Namespaces beginning jabber: are reserved; anything else is OK.
Briefly, you can see how payloads are attached from the example. For every
<x/> subelement, there's an xmlns attribute that qualifies it, and the data contained
within the <x/> tag is formatted depending on the
In the example, the payload is carried in addition to the <body/> subelement. However, as the <body/> is actually optional
in a message, it is possible to transmit structured payloads between Jabber
entities without the need for "conventional" message content.
The <presence/> element is used to convey a
Jabber entity's availability. An entity can be available, which means that it's connected and any
messages sent to it will be delivered immediately, or it can be unavailable, which means that it's not connected, and any
messages sent to it will be stored and delivered the next time a connection is
For the large part, it is the entity itself, not the Jabber server to which
it connects, that controls the availability information. The Jabber server
will communicate an entity's unavailabilityif that
entity disconnects from the server but will do that only if the entity has
communicated its availability beforehand.
Availability information isn't a free-for-all. Presence in Jabber is
usually exchanged within a subscription mechanism. See "Presence
subscription" for an explanation.
Just as with the <message/> element, extra
information can be attached to the <presence/>
element by means of the <x/> tag. In the same
way, each <x/> tag must be qualified with a
While there aren't many external uses for payloads in a <presence/> packet, the Jabber server uses this
facility to add information. In this example, we see that dj@yak's notification of availability (remember, type='available' is assumed for <presence/> packets without an explicit type attribute) is being sent to sabine@yak. While dj@yak connected
to the Jabber server and sent his availability (which was stamped on receipt
by the Jabber server) just before 11 a.m., sabine@yak
is just logging on now (say, 30 minutes later). When she receives dj@yak's presence, she knows how long that presence status
has been valid for.
See the section "The X Namespaces" in Chapter 6 to find out what namespaces
are available to qualify <x/>-included payloads.
Presence subscription is the name given to the
mechanism that allows control over how entity presence information is made
available to other entities. By default, the availability of an entity is
unknown to other entities.
Let's put this into more concrete terms. For example, let's assume that you
and I are both Jabber users. I'm registered with the Jabber server running at
jabber.org, my JID is email@example.com, and you are registered with a Jabber
server running at your company, and your JID is firstname.lastname@example.org.
If you want to know whether I'm available, you have to subscribe to my presence. This is
done by sending a <presence/> packet to me with
the type attribute set to subscribe. In the example that follows, the XML fragments
are sent and received from your perspective:
SEND: <presence type='subscribe' email@example.com'/>
I receive the <presence/> packet, and when I
receive it, it's been stamped (by your Jabber server) with a from attribute with the value firstname.lastname@example.org. So, based upon who it is, I decide to
accept the subscription request and send back a reply, which you receive:
RECV: <presence type='subscribed'
This lets you know that I've accepted your subscription request. From now
on, every time my availability changes (when I send a <presence/> packet or when I disconnect and the
server generates an unavailable <presence/> packet on my behalf), that availability
information will be relayed to you.
But how does this work? How does the Jabber server know that you've
subscribed to my presence and I've accepted that subscription?
Enter the roster, stage right. The roster is a list
of JIDs maintained for each user, stored server-side. A roster is similar to
an AOL Buddy List; one could say that it's a sort of personal address book,
but it's more than that. The presence subscription and roster mechanisms are
tightly intertwined. We'll be examining the roster in more detail in the
section "jabber:iq:roster" in Chapter 6. Here, we'll just look at the
characteristics of the roster that are relevant for the presence subscription
mechanism. The roster is managed using the third basic Jabber element -- <iq/> -- which will be explained in more detail later
in this section. Ignore the tags that you aren't yet familiar with; it's just
important to get the basic drift of what's going on.
While the roster is stored and maintained server-side, any changes to it
made by the server are reflected in (pushed to) the client so it can be
synchronized with a local copy.
Let's expand the simple exchange of <presence/> packets from earlier and see how the
roster is used to record presence subscription information.
If you wish to subscribe to my presence and add my JID to your roster at
the same time, these two actions are linked for obvious and practical reasons.
Many Jabber clients use the roster as a basis for displaying availability
information, and with the exception of an entity sending presence information
directly to another entity regardless of roster membership, presence
subscription information is stored by the user in the roster. Here's the order
in which the subscription would take place:
A request is sent to the server to update your roster, adding my JID to
SEND: <iq id="adduser1" type="set">
<item jid="email@example.com" name="DJ Adams"/>
You add an id attribute to be able to track the
request and match up the response when it comes.
The server responds with a push of the updated (new) roster item:
RECV: <iq type='set'>
<item firstname.lastname@example.org' name='DJ Adams'
Note that in the update an additional attribute subscription='none' is sent, reflecting the presence
subscription relationship between you and me. At this stage, the
relationship is that I don't have a subscription to your presence and you
don't have a subscription to my presence, hence the value none.
It also acknowledges the original update request, confirming its success:
RECV: <iq id='adduser1' type='result'
Note the id='adduser1' identity is passed back so
we can track the original request and find out where this response is being
Meanwhile, you send the subscription request:
SEND: <presence to="email@example.com" type="subscribe"/>
The server notes the subscription request going through and once more
updates your roster and pushes the item out to you:
RECV: <iq type='set'>
<item firstname.lastname@example.org' name='DJ Adams'
The current subscription relationship is reflected with the subscription='none' attribute. In addition, we have a
subscription request status, with ask='subscribe'.
This request status shows that there is an outstanding presence subscription
request to the JID in that roster item. If you've ever seen the word
"Pending" next to a username in a Jabber roster, this is where that comes
from. Don't forget that a subscription request might not get an immediate
response, so we need to remember that the request is still outstanding.
Your subscription request is received and accepted, and a subscribed type is sent back to you as part of a <presence/> packet:
RECV: <presence email@example.com'
The server also notices the subscription request acceptance and yet again
updates your roster to keep track of the presence subscription. Again, it
pushes the subscription information out to you so your client can keep its
RECV: <iq type='set'>
<item firstname.lastname@example.org' name='DJ Adams'
This time, the subscription attribute in the
roster item has been set to to. This means that the
roster owner (you) has a presence subscription to
the JID in the roster item (i.e., me).
The server knows you've just subscribed to my presence; it generates a
presence probe on your behalf that causes my presence information to be
retrieved and sent to you:
RECV: <presence email@example.com/Work'
Of course, at this stage, our relationship is a little unbalanced, in that
you have a subscription request to me, but I don't have a subscription request
to you. So you are aware of my availability, but not the other way around. In
order to rectify this situation, I can repeat the process in the opposite
direction, asking for a subscription to your presence information.
The only difference to the sequence that we've just seen is that you will
already exist on my roster because the server will have maintained an item for
your JID to record the presence subscription relationship. While the item in
your roster that represents my JID has a subscription
attribute value of to (the roster owner has a presence
subscription to this JID) -- we've seen this in Step 7
-- the item in my roster that represents your JID has a subscription attribute value of from
(the roster owner has a presence subscription from
Once I repeat this sequence to subscribe to your presence (and you accept
the request), the value for the subscription attribute
in the items in each of our rosters will be set to both.
The upshot of all this is that when an entity announces its presence, it
does so using a single <presence/> packet, with
no to attribute specified. All the members in that
entity's roster who have a subscription to that entity's presence will receive
a copy of that <presence/> packet and thereby be
The Jabber server (specifically, the presence handler within the JSM) has a
mechanism called the Availability Tracker. As its name
implies, its job is to track the availability of entities that have previously
made an availability announcement (in a <presence/> element).
The concept of exchange of availability information via an exchange
agreement recorded in the roster was introduced in "Presence
subscription." This mechanism covers the automatic distribution of
availability notification based upon prearranged presence subscriptions.
However, Jabber services (which are connected to the jabberd backbone; see the section "An Overview of the
Server Architecture" in Chapter 4) may need to know an entity's availability
or, more importantly, when they suddenly become unavailable. These Jabber services usually won't have a
prior presence subscription agreement recorded in anyone's roster.
The Conferencing service, which provides group chat facilities, allowing
users to join discussion "rooms" and chat, is one of these services. The
service maintains data for each room's participants, and, so that it can
manage its memory usage effectively, needs to know when a user ends his
connection with the Jabber server -- in other words, when he becomes
unavailable -- so it can free that user's data. Normally, a user leaving a
room is information enough for the service to know that data can be freed. But
what if the user disconnects (or is disconnected) from his Jabber server
without first leaving the room?
The availability tracker mechanism comes to the rescue. It maintains a list
of JIDs to which an entity has sent his availability in a <presence/> packet containing a to attribute (i.e., a directed<presence/> packet). When the JSM notices that a user
has ended his session by disconnecting, the presence handler invokes the
availability tracker to send an unavailable <presence/> packet (with the type='unavailable' attribute) to all the JIDs to which the
entity had sent directed availability information during the lifetime of that
How does this help in the Conferencing service case? Well, one of the
requirements to enter a room is that presence must be sent to that room. Each
room has its own JID, so a typical presence packet in room entry negotiation
might look like this:
SEND: <presence firstname.lastname@example.org'/>
Earlier in this chapter, we saw various elements in action in Example 5-3.
The first two were <iq/> elements and showed a
retrieval request and response for roster information.
First comes the request:
SEND: <iq id='roster_0' type='get'>
Then the response:
RECV: <iq id='roster_0' type='result' from='dj@yak/Work'>
<item jid='sabine@yak' name='sabine' subscription='both'>
This snippet shows a number of things:
The type of each info/query activity is identified by the type attribute.
Each info/query activity contains a subelement (here, <query/>), which is qualified by a namespace.
The subelement is used to carry the information being retrieved.
The response (type='result') can be matched up to
the request (type='get') via the id tracking attribute.
So, if we look at the first <iq/> element:
<iq id='roster_0' type='get'>
we can see that this "request" <iq/> doesn't
contain a to attribute. This is because the request is
being made of the Jabber server (specifically the
JSM), instead of a particular user. Next we see the response from the server:
<iq id='roster_0' type='result'
This "response" <iq/> contains a from attribute stating that the result is coming back from
the original requester! This is simply because the from
attribute is a hangover from the original request to the Jabber server, which
is stamped with its origin (dj@yak/Work) in the form
of the from attribute. Here, as in many other places in
the Jabber server, the response is simply built by turning the incoming
request packet around and adding whatever was required to it before sending it
OK, let's examine the details of the <iq/>
This attribute is used to specify the intended recipient of the info/query
action or response. If no to attribute is specified,
the delivery of the packet is set to the sender, as is the case for <message/> packets. However, unlike the case for <message/> packets, <iq/> packets are usually dealt with en route and
handled by the JSM.
What does that mean? Packets sent from a client travel over a jabber:client XML stream and reach the Jabber server, where
they're routed to the JSM.
A large part of the JSM consists of a series of packet handlers, in the
form of modules, whose job it is to review packets as they pass through and
act upon them as appropriate; some of these actions may cause a packet to be
deemed to have been "delivered" to its intended destination (thus causing the
packet routing to end for that packet) before it gets there.
So in the case of <iq/> packets without a to attribute, the default destination is the sender's JID,
as we've already seen with the <message/>
element. But because JSM handlers that receive a packet may perform some
action to handle it and cause that packet's delivery to be terminated (marked
complete) prematurely, the effect is that something sensible will happen to
the <iq/> packet that doesn't have a to attribute and it won't appear to act like a boomerang.
Here's an example:
The namespace jabber:iq:browse represents a powerful
browsing mechanism that pervades much of the Jabber
server's services and components. Sending a simple browse request without
specifying a destination (no to attribute):
SEND: <iq type='get'>
will technically be determined to have a destination of the sender's JID. However, a JSM handler called mod_browse that performs browsing services gets a look-in
at the packet before it reaches the sender and handles
the packet to the extent that the query is deemed to have been answered and
thereby the delivery completed. The packet stops traveling in the sender's
direction, having been responded to by mod_browse:
RECV: <iq type='result' to='dj@yak/sjabber' from='dj@yak'>
<user name='DJ Adams' xmlns='jabber:iq:browse' jid='dj@yak'/>
And while we're digressing, here's a meta-digression: we see from this
example that a browse to a particular JID is handled at
the server. The client doesn't even get a chance to respond. So, as one of
browsing's roles is to facilitate resource discovery, how is this going to
work if the client doesn't see the request and can't respond. The answer lies
in the distinction of specifying the recipient JID with or without a resource. The idea is that you can query someone's client
to find out what that client supports; for example, whiteboarding or XHTML
text display. As a resource is per client connection and in many ways represents that client, it makes sense to send a browse
request to a JID including a specific resource:
SEND: <iq type='get' email@example.com/sjabber'>
This time the destination JID is resource-specific and the packet passes by
the mod_browse handler to reach the client (sjabber), where a response can be returned:
RECV: <iq type='result' firstname.lastname@example.org/WinJab
<user type='client' xmlns='jabber:iq:browse'
If we're going to rank the elements in terms of the importance of their
being tracked, <iq/> would arguably come out on
top, as it inherently describes a request/response mechanism. So this element
also has an id attribute for tracking purposes.
For an IQ-get, the subelement usually just contains a qualifying
namespace that in turn defines the essence of the get activity. This is evident in the example here, where
the <iq/> element is a retrieval of the server
(yak) version information.
For an IQ-set, it contains the qualifying namespace and also child tags
that hold the data to be set, as in this example, in
which a vCard (an electronic "business card") is being updated:
SEND: <iq type='set'>
<vCard xmlns='vcard-temp' version='3.0'>
... [vCard information] ...
When result information is returned, it is
enclosed within a <query/> subelement qualified
with the appropriate namespace, as in this IQ-result response to the earlier
request for server version information:
RECV: <iq type='result' to='dj@yak/Work' from='yak'>
Of course, there are some results that don't carry any further
information -- the so-called Boolean results. When there's no information to
return in a result, the <query/> subelement
isn't necessary. A typical case in which a Boolean result is returned is on
successfully authenticating to the Jabber server (where the credentials are
sent in an IQ-set request in the jabber:iq:auth
namespace); the IQ-result element would look like this:
RECV: <iq type='result' id='auth_0'/>
And for an error situation, while the actual error
information is carried in an <error/>
subelement, any context in which the error occurred is returned too in a <query/> subelement. This is usually because the
service returning the error just turns around the IQ-set packet -- which
already contains the context as the data being set
-- and adds the <error/> subelement before returning it.
Here we see that the authentication step of connecting to the Jabber
server failed because Sabine mistyped her password:
RECV: <iq type='error' id='auth_0'>
Whoa! Hold on a minute, what's that <vCard xmlns='vcard-temp'
version='3.0'> doing up there in the IQ-set example? Shouldn't it be
<query xmlns='vcard-temp' version='3.0'>?
Actually, no. What it should be is defined, in each case, by the namespace
specified in the xmlns attribute in the tag. It's
important to note that while we specified the <query/> subelement as being required, it's actually the presence of the container
itself that is required. Its name, while commonly query, really depends on the namespace qualifying it. So,
while all of the containers qualified by the namespaces listed in the section
"The IQ Namespaces" and the section "The X Namespaces," both in Chapter 6,
have the tag name query, others, qualified by the
namespaces in the section "Miscellaneous Namespaces," do not.
The critical part of the subelement is the namespace specification with the
xmlns attribute. And we've seen this somewhere before
-- in the definition of component instance configuration in the section
"Server Configuration" in Chapter 4, we learned that the tag wrapping the
component instance's configuration, like that for the c2s service:
... [configuration here] ...
which is pthcsock here, is irrelevant, while the
namespace defining that tag (jabber:config:pth-csock)
is important, because it's what is used by the component to retrieve the
We've seen this feature in this chapter too; remember the <iq/> examples in the jabber:iq:browse namespace? The result of a browse request
that returned user information looked like this:
RECV: <iq type='result' to='dj@yak/sjabber' from='dj@yak'>
<user name='DJ Adams' xmlns='jabber:iq:browse' jid='dj@yak'/>
Again, the query tag is actually <user/>. In fact, in browsing, the situation is
extreme, as the <iq/> response's subelement tag
name will be different, depending on what was being browsed. But what is
always consistent is the namespace qualifying the subelement; in this example,
it's jabber:iq:browse. See the section
"jabber:iq:browse" in Chapter 6 for more details.