Rules and Regulations

A JID must contain a hostname part to be valid. The username and resource parts are optional; circumstance and usage dictates when either of these parts is necessary. A username is specific to the hostname that it's paired up with. For example: [email protected] is not the same as [email protected].

There are some restrictions on how each JID part is composed; Table 5-1 details these restrictions. Although you can be particular about the case of letters in a username, any operations (such as comparisons) at the Jabber server are case-insensitive. For example, if a user has registered dj as his username, then another user cannot register with the username DJ. However, the person who registered as dj can connect and send DJ when he authenticates, and for the duration of that session will be known as DJ not dj.

On the other hand, resources are case-sensitive.

Table 5-1. JID restrictions

[2]That is, it may not contain spaces or those considered to be control characters.

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

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.

The resource part of a JID allows a user to be connected to Jabber (specifically the JSM, which manages users and sees user sessions as separate entities) multiple times.

Then the question becomes, what happens when someone sends you a message? To which client is the message sent?

This is where the concept of connection prioritycomes to our aid. Each Jabber client connection can be given a priority. When a user has more than one concurrent connection to a Jabber server, the priority is used to determine to which connection any messages intended for that user should be sent. IQ elements are resource-bound, that is, they are addressed to specific resources. In that sense, they are not affected by priority. (See "

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.

It is also possible to direct messages to a particular client. Taking the example from Figure 5-1, if sabine@yakwere to specify dj@yak/Laptop instead of dj@yak as the recipient for a message, her message would go to Client 1 (Laptop), not Client 2 (Desktop), despite Client 1's lower priority value.

NOTE: In the upcoming server Version 1.4.2, this resource-based routing facility has been made more flexible. Rather than relying upon exact matches (such as Laptop or Desktop), messages will be routed based on a subset of the resource value. For example, if logged in with the JID sabine@yak/Laptop, sabine would receive messages addressed to sabine@yak/Laptop/foo, sabine@yak/Laptop/bar, and so on. This allows clients to do flexible routing and delivery, based on the resource detail, once they've received the messages.

Priorities are specified when a user sends presence information. We will see this later in "

type='groupchat'

The groupchat message type is to alert the receiving client that the message being carried is one from a conference (groupchat) room. The user can participate in many conference rooms and receive messages sent by other participants in those rooms. The groupchat type signifies to the receiving client that the address specified in the from attribute (see later in this section) is not the sending user's real JID but the JID representing the sending user, via her nickname, in the conference room from where the groupchat message originates.[4]

[4]Also, groupchat type messages, such as those announcing entrances or exits of room participants, can be received from the room itself.

type='headline'

This is a special message type designed to carry news style information, often accompanied by a URL and description in an attachment qualified by the jabber:x:oob namespace. Messages with their type set to headline can be handled by clients in such a way that their content is placed in a growing list of entries that can be used as reference by the user.

type='error'

The error message type signifies that the message is conveying error information to the client. Errors can originate in many places and under many circumstances. Refer to the description of the <error/> subelement in the next section for more details.

<message from='dj@yak/Desktop'>

The from attribute of the <message/> element shows the message originator's JID. In many cases this is the JID of a user, but with the message type groupchat, for example, it can be the JID of the conference room in the place where the message was originally sent.

The from attribute should not be set by the client. It is the Jabber server, to which the client from where the message originated is connected, that sets the attribute value. This is to prevent spoofing of JIDs. If a from attribute is set, it will be overriden by the server.

The to attribute is used to specify the intended recipient of the message and is a JID. The recipient may be another Jabber user, in which case the JID will usually be in the form username@hostname (with an optional /resource if a message should be sent to a specific client connection), or it could be a Jabber server identity, in which case the JID will be in the form hostname> with an optional /resource depending on the situation.

If no to attribute is specified, then the message will be directed back to the sender, or the server, depending on the circumstances. This may or may not be what you want.

This is also the case with the to attribute for the <iq/> element; however, it is not the case with the <presence/> element.[5]See the sidebar titled "Element Handling by the Jabber Server" for an explanation.

[5]Actually, it is, internally, but the effect is that it isn't. The packet is swallowed on its final delivery stage by the presence handler.

When elements (packets) make their way over the jabber:client XML stream and arrive at the Jabber server, they're delivered to the JSM that provides many of the services associated with Jabber's IM features, such as roster management, presence subscription, offline storage, and so on. Each packet received runs a gauntlet of handlers before being delivered to its ultimate destination specified by the value of the to attribute.

In some cases, a packet has no "ultimate destination" and is deemed to have been handled without reaching a final delivery point.

For example, in the case of a simple <message/> packet with a JID specified in the to attribute, the packet will not be swallowed by a handler but will be delivered to that JID destination. On the other hand, in the case of a simple <presence/> packet without a to attribute (a normal notification of availability), the packet will reach the mod_presence module in the JSM and be handled by that module, where the availability information will be distributed according to presence subscriptions. The <presence/> packet itself, in its original form, will go no further.

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.

Message subelements

While the <message/> element itself is a container for the information being carried, the subelements are used to hold and describe the information being carried. Depending on the circumstances and the message type, different subelements can be used.

The <subject/> subelement is used to set a message subject. Message subjects are not that common in chat type messages but are more appropriate in normal type messages in which the subject can be displayed in the style of a list of inbox items. This subelement is also used in groupchat type messages to set the subject (or "topic") of a conference room.

<message to='qmacro@yak' from='john@yak' type='chat'>
  <body>Hey - got a minute?</body>
</message>

The <body/> subelement carries the body of the message.

The <error> subelement is for carrying error information in a problem situation. In this example, the original message sent by [email protected]was a simple "Are you there?" to what he thought was qmacro's JID on the Jabber server at jabber.org. However, the to attribute was specified incorrectly (jaber.org), and the Jabber server on pipetree.com wasn't able to resolve the hostname. So Piers receives his message back with an additional <error/> subelement, and the message type has been switched to error (the type='error' attribute).

The <error/> subelement carries two pieces of related information: an error number, specified in the code attribute, and the error text. Table 5-3 lists standard error codes and texts. The entity generating the error can specify a custom error text to go with the error code; if none is specified, the standard text as shown is used.

Table 5-3. Standard error codes and texts

<message id="3" to="dj@yak" type="chat">
  <html xmlns="http://www.w3.org/1999/xhtml">
    <body>
      <span style="font-family: Arial; font-size: 10pt">
        This is really <em>nice!</em>
      </span>
      <br/>
    </body>
  </html>
  <body>This is really nice!</body>
</message>

The <html/> tag is for support of messages formatted in Extensible HyperText Markup Language (XHTML). The normal <body/> tag carries plain text; text formatted with XHTML markup can be carried in <message/> elements inside the <html/> subelement.

The markup must be qualified by the XHTML namespace http://www.w3.org/1999/xhtml (as shown in the example) and conform to the markup described in the XHTML-Basic specification defined at

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/> subelement.

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 <x/> subelement is special. While the other subelements like <body/> and <thread/> are fixed into the Jabber building blocks design, the <x/> subelement allows <message/> elements to be extended to suit requirements. What the <x/> subelement does is provide an anchor point for further information to be attached to messages in a structured way.

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

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

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

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 attributes

The attributes of the <presence/> element are similar to those of the <message/> element.

The type attribute of the <presence/> element is used for many purposes. The basic usage is to convey availability. Two values are used: available and unavailable.[6] Another value is to signify that the <presence/> packet is being used to query the packet recipient's presence (value is probe). The rest of the values (subscribe, unsubscribe, subscribed, unsubscribed) are used in the subscription structure, which is described in "

Attribute Values

type='available'

The available presence type is used by entities to announce their availability. This announcement is usually made to the Jabber server that manages the presence subscription mechanism (see "

Presence subscription

If no type attribute is specified, then this value of available is assumed. It makes sense, as the most common type of <presence/> packet sent by entities is usually the available type, optionally qualified with the <show/> and <status/> subelements, as the user of the connected client changes her circumstances over time (off for a break, back, out to lunch, and so on).

type='unavailable'

The unavailable presence type is the antithesis of the available presence type. It is used to qualify an entity's unavailability. An entity is unavailable when its client has disconnected from the Jabber server. An unavailable presence type should be sent by clients before they disconnect.

How can we make sure that clients actually send such a packet when they disconnect (to keep the presence information equilibrium)? Well, we can't. If a client disconnects without sending an unavailable presence type, the Jabber server will send one out on its behalf when it disconnects. This is part of the presence service of the JSM and closely related to the presence subscription mechanism. See "

Availability Tracker

While the <show/> and <status/> subelements qualify the available presence packet, there's no point in any embellishment of the fact that the entity is unavailable, so no subelements are used when the packet is of the unavailable type.

type='probe'

The probe presence type is a query, or probe, on another entity's availability. This probe is used by the Jabber server to determine the presence of entities in its management of the presence subscription mechanism. Under normal circumstances, this presence probe should not be used directly by a client -- availability information is always pushed to the client by the server. Regardless, if a client insists on using a probe, there are two things to bear in mind:

• Information will be returned only in response to an availability probe if the probing entity already has a subscription to the entity being probed. This means that you can't bypass the subscription model and probe random entities for availability information; you can probe only those who have previously given you permission to be informed of their availability. See "

Presence subscription" for more details.

• The <presence/> packet must be specified with a from attribute specifying the sender's JID in the form username@hostnamebefore it is sent. The Jabber server does not add this attribute. The presence mechanism will use the full JID (including any resource) when working out whether the prober has permission. This will ultimately fail because permission is determined on a username@hostname basis, not a username@hostname/resource basis.

WARNING: Although possible right now, you should really avoid using the probe presence type in clients. Future versions of the Jabber server may block such packets.

type='subscribe'

This presence type is a request to subscribe to an entity's presence. ("Will you allow me to be sent your presence information by the server?") See "

Presence subscription

type='unsubscribe'

This presence type is a request to unsubscribe from an entity's presence. ("I don't want to be sent your presence information anymore; please have the server stop sending it to me.") See "

Presence subscription

type='subscribed'

This presence type is sent in reply to a presence subscription request, used to accept the request. ("OK, I accept your request; the server will send you my presence information.") See "

Presence subscription

type='unsubscribed'

This presence type is sent in reply to a presence unsubscription request, used to accept the request. ("OK, I accept your unsubscription request; the server will stop sending you my presence information.")

It is also used to deny a presence subscription request. ("No, I don't accept your subscription request; I don't want the server to send you my presence information.")

These presence types are described in more detail in "

Presence subscription

<presence from='dj@yak'/>

Similar to the attribute of the same name in the <message/> element, here the from attribute is set by the server and represents the JID from which the availability information originates.

If you are sending a presence probe, type='probe', you must set the from attribute yourself, as mentioned earlier.

The to attribute is optional; if, as a user, you are just announcing availability (with the intention of having that announcement reflected to the appropriate members of your roster), then specifying a to attribute is not appropriate.[8] If you want to send your availability to a specific entity, then do so using this to attribute, specifying that entity's JID. Why might you want to do this? See "

All Jabber elements support an id attribute for tracking purposes. So, the <presence/> packet is no different from the <message/> packet in this respect. As presence notification is usually a one-way thing, it is very uncommon to see <presence/> packets qualified with an id attribute.

Presence subelements

When an available presence is sent, it can be qualified with more detail. The detail comes in two parts and is represented by two subelements of the <presence/> element. The first part of the detail is in the form of a <show/> tag, which by convention contains one of five possible values. Table 5-4 lists these values and their meaning.

Table 5-4. Presence <show> values

The other part of the detail that qualifies a user's availability is the <status/> subelement. It allows for a more descriptive remark that embellishes the <show/> data.

The examples for this subelement and the <show/> subelement show how the <status/> value is used as a textual description to explain the <show/> value's "short code," or mnemonic.

<presence>
  <show>chat</show>
  <status>coffee break</status>
  <priority>5</priority>
</presence>

Earlier in this chapter, "

As we see here, the priority is set using the <presence/> element. In this example, we see that the user has set the priority high to make sure that messages are routed to him on the Jabber client running on this machine.

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

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

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 protected], and you are registered with a Jabber server running at your company, and your JID is [email protected].

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' to='[email protected]'/>

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 [email protected]. 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'
                from='[email protected]/home'
                to='[email protected]/work'/>

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.[9]

[9]The local copy would exist only for the duration of the user's session and should always be regarded as a slave 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:

1. A request is sent to the server to update your roster, adding my JID to it:

   SEND: <iq id="adduser1" type="set">
           <query xmlns="jabber:iq:roster">
             <item jid="[email protected]" name="DJ Adams"/>
           </query>
         </iq>
   

   You add an id attribute to be able to track the request and match up the response when it comes.

2. The server responds with a push of the updated (new) roster item:

   RECV: <iq type='set'>
            <query xmlns='jabber:iq:roster'>
              <item jid='[email protected]' name='DJ Adams'
                    subscription='none'/>
            </query>
          </iq>
   

   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.

3. It also acknowledges the original update request, confirming its success:

   RECV: <iq id='adduser1' type='result'
             from='[email protected]/Work'
             to='[email protected]/Work'/>
   

   Note the id='adduser1' identity is passed back so we can track the original request and find out where this response is being made.

4. Meanwhile, you send the subscription request:

   SEND: <presence to="[email protected]" type="subscribe"/>
   

5. 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'>
           <query xmlns='jabber:iq:roster'>
             <item jid='[email protected]' name='DJ Adams'
                   subscription='none' ask='subscribe'/>
           </query>
         </iq>
   

   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.

6. Your subscription request is received and accepted, and a subscribed type is sent back to you as part of a <presence/> packet:

   RECV: <presence to='[email protected]'
                   type='subscribed' from='[email protected]'/>
   

7. 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 copy up-to-date:

   RECV: <iq type='set'>
            <query xmlns='jabber:iq:roster'>
              <item jid='[email protected]' name='DJ Adams'
                    subscription='to'/>
            </query>
          </iq>
   

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

8. 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 from='[email protected]/Work'
                   to='[email protected]'>
           <status>Available</status>
           <priority>1</priority>
           <x xmlns='jabber:x:delay'
              from='[email protected]/Work'
              stamp='20010515T11:37:40'/>
         </presence>
   

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 this JID).

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 informed.[10]

[10]That is, where there's a value of to or both in the roster item's subscription attribute.

Availability Tracker

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 "

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

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 to='[email protected]'/>

which would be for the jdev room running at the conferencing service at conference.jabber.org.[11]

[11]The example here contains a room JID with no resource specified; this is taken from the 0.4 version of the Conferencing protocol. An earlier version of the protocol (Groupchat 1.0) required that the nickname for the person entering the room be specified as a resource to the room's JID, for example, [email protected]/dj.

So, the availability tracker would have recorded this directed presence and will send an unavailable presence to the same JID if the user's session ends.

The IQ Element

The third and final element in the Jabber building block set is the <iq/> element ("iq" stands for "info/query"), which represents a mechanism for sending and receiving information. What the <iq/> element has over the <message/> element for this purpose is structure and inherent meaning. It is useful to liken the info/query mechanism to the request/response model of HTTP using GET and POST.

The <iq/> element allows a structured conversation between two Jabber entities. The conversation exists to exchange data, to retrieve or set it, and to notify the other party as to the success (or not) of that retrieve or set action. There are four states that an <iq/> element can be in, each reflecting one of the activities in this conversation:

get

Get information.

set

Set information.

result

Show the result when the get or set was successful.

error

Specify an error if the get or set was not successful.

These states are reflected in the type attribute of <iq/> elements. The relationship between two entities in such a structured conversation that convey these states is shown in Figure 5-4.

NOTE: As you can see, the combination of the <iq/> element specification and the type attribute is written like this:

IQ-type

For example, "IQ-get" refers to an <iq/> element with type='get', and so on.

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'>
        <query xmlns='jabber:iq:roster'/>
      </iq>

Then the response:

RECV: <iq id='roster_0' type='result' from='dj@yak/Work'>
        <query xmlns='jabber:iq:roster'>
          <item jid='sabine@yak' name='sabine' subscription='both'>
            <group>Family</group>
          </item>
        </query>
      </iq>

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' from='dj@yak/Work'>

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

OK, let's examine the details of the <iq/> element.

IQ attributes

The attributes of the <iq/> element are the same as those of the <presence/> and <message/> elements and used pretty much in the same way.

As mentioned already, the from attribute is used to specify the activity.

Attribute Values

type='get'

This is used to specify that the <iq/> element is being used in request mode, to retrieve information. The actual subject of the request is specified using the namespace qualification of the <query/> subelement; see later in this section for details.

Using the HTTP parallel, this is the equivalent of the GET verb.

type='set'

While IQ-get is used to retrieve data, the corresponding set type is used to send data and is the equivalent of the POST verb in the HTTP parallel.

Very often, an IQ-get request will be made of an entity, to discover fields that are to be completed to interact with that entity. The Jabber User Directory (JUD) is a component that plugs into the jabberd backbone and provides simple directory services; users can register an entry in the JUD address book, on which searches can be performed.

Let's look at how IQ elements are used to interact with the JUD.

The registration conversation with the JUD starts with an IQ-get to discover the fields that can be used for registration, followed by an IQ-set filling those fields in the act of registration. Note how, each time, the JUD responds with an IQ-result to confirm each action's success.

Here we are requesting registration information from the JUD. Note the namespace that qualifies the <query/> subelement (and hence the <iq/>):

SEND: <iq type='get' to='jud.yak'
                   id='judreg_ask'>
        <query xmlns='jabber:iq:register'/>
      </iq>

The JUD responds with the fields to fill in. The response is basically a copy of the request, with new attributes and tags:

RECV: <iq type='result' to='dj@yak/Work'
          from='jud.yak' id='judreg_ask'>
        <query xmlns='jabber:iq:register'>
          <instructions>
            Complete the form to submit your details
            to the User Directory
          </instructions>
          <name/>
          <first/>
          <last/>
          <nick/>
          <email/>
        </query>
      </iq>

Now we know what to send:

SEND: <iq type='set' to='jud.yak' id='judreg_do'>
        <query xmlns='jabber:iq:register'>
          <name>DJ Adams</name>
          <first>DJ</first>
          <last>Adams</last>
          <nick>qmacro</nick>
          <email>[email protected]</email>
        </query>
      </iq>

And the JUD responds, saying the IQ-set request was successful:

RECV: <iq type='result' to='dj@yak/Work'
                   from='jud.yak' id='judreg_do'/>

type='result'

As shown in the JUD conversation, the result type <iq/> packet is used to convey a result. Whether that result is Boolean (it worked, as opposed to it didn't work) or conveys information (such as the registration fields that were requested), each IQ-get or IQ-set request is followed by an IQ-result response, if successful.

type='error'

If not successful, the IQ-get or IQ-set request is followed not by an IQ-result response, but by an error type response. In the same way that a subelement <error/> carries information about what went wrong in a <message type='error'/> element, so it also provides the same service for IQ-error elements.[12]

[12]Table 5-3 lists the standard Jabber error codes and their default descriptions.

Let's look at an IQ-error in action. A user, who is trying to join a conference room, is notified that his entrance is barred because he hasn't supplied a required password.

First, the user requests information on the room he wishes to join:

SEND: <iq type="get" id="conf1" to="[email protected]">
        <query xmlns="jabber:iq:conference"/>
      </iq>

The conference component instance, to which the IQ-get was addressed (with the to='cellar@conference.yak' attribute), responds with information about the cellar room, including the fact that a nickname and passwordmust be specified to gain entrance:

RECV: <iq type='result' id='conf1' to='dj@yak/winjab'
                            from='[email protected]'>
        <query xmlns='jabber:iq:conference'>
          <name>Dingy Cellar</name>
          <nick/>
          <secret/>
        </query>
      </iq>

After sending availability to the room, to have the availability tracker kick in for that room's JID (see "

Availability Tracker

Similar to the from attribute in the <message/> and <presence/> elements, this is set by the server and represents the JID where the <iq/> originated.

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.[13]

[13]They're routed with the internal <route/> element; see the section "Component Types" in Chapter 4 for more details.

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'>
        <query xmlns='jabber:iq:browse'/>
      </iq>

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'/>
      </iq>

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.[14] 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:

[14] Whiteboarding is collaborative sketching, not a form of surfing atop wave crests.

SEND: <iq type='get' to='[email protected]/sjabber'>
        <query xmlns='jabber:iq:browse'/>
      </iq>

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' to='[email protected]/WinJab
                      from='[email protected]/sjabber'>
        <user type='client' xmlns='jabber:iq:browse'
                         jid='[email protected]/sjabber'>
          <whiteboard/>
          <videochat/>
          <PGP/>
        </user>
      </iq>

<iq type='get' id='roster1'/>

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.

Don't forget that the pair of XML streams that represent the two-way traffic between Jabber client and server are independent, and any related packets such as a request (traveling in one XML stream) and the corresponding response (traveling in the other) are asynchronous. So a tracking mechanism like the id attribute is essential to be able to match packets up.

IQ subelements

We've seen these two subelements of the <iq/> element already in earlier examples -- <query/> and <error/>. Here's a review of them.

We've already seen the <query/> subelement performing the task of container for the info/query activity.

• 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] ...
          </vCard>
        </iq>
  

• 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'>
          <query xmlns='jabber:iq:version'>
            <name>jsm</name>
            <version>1.4.1</version>
            <os>Linux 2.2.12-45SAP</os>
          </query>
        </iq>
  

  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'>
          <query xmlns='jabber:iq:auth'>
            <username>sabine</username>
            <password>geheimnix</password>
            <resource>pavilion</resource>
          </query>
          <error code='401'>Unauthorized</error>
        </iq>
  

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:

<service id="c2s">
  ...
  <pthcsock xmlns='jabber:config:pth-csock'>
    ... [configuration here] ...
  </pthcsock>
</service>

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

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'/>
      </iq>

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.

The error subelement carries error information back in the response to a request that could not be fulfilled. Table 5-3 showed the standard error codes and default accompanying texts.

The example here shows the response to a browse request, but why might the request have been erroneous? Because the <iq/> type attribute had been specified as set instead of get. Browsing is a read-only mechanism.