The IQ protocol has two primary participants: a query originator and a query handler. In most situations, the originator is a Jabber client.4 The query handler can be either a client or a server.
The protocol begins with a query originator sending an IQ query packet to the query handler. The IQ query packet travels between the query originator and the query handler using normal Jabber packet relaying. In other words, the packet is sent to the originator’s Jabber server. The server then handles the query if it is the recipient, or delivers it to its recipient as it would a Jabber message.
Unlike a Jabber message, the IQ packet is not stored for later delivery if the recipient is unreachable. In addition, the IQ packet must be addressed to a spe- cific recipient. You can’t address an IQ packet to a user like [email protected]. It
2 I use the term “probe” to indicate the exploration of client/server capabilities while “querying” is using
a particular capability to obtain specific information. For example, I may probe a server to see if it sup- ports a directory service. I can then query the directory service to get information on a particular user.
3 See http://www.w3c.org/xml for more information on the XML namespace specification.
4 The most common exception to this rule is a roster push generated in the server and sent to clients in
166 CHAPTER 6
Info/Query and client registration
must be sent to a resource like [email protected]/work. The one exception is IQ
packets sent to the server where you can omit the recipient Jabber ID entirely.
IQ query packets will either set or get data from the query handler. The query handler either successfully handles the IQ quer y and generates an IQ result packet, or fails and generates an IQ error packet. The IQ result or error packet is then relayed back to the query originator.
A basic IQ packet follows the format shown in listing 6.1
<iq type='set|get|result|error' to='handler_jid'
from='originator_jid' id='unique'>
<query xmlns='iq extension namespace'> <query_field1/>
<query_field2/>
</query> </iq>
The IQ “type” attribute indicates the type of query packet(s) being sent. These are detailed in table 6.1.
Table 6.1 The IQ packet types and their usage.
a. Occasionally IQ set queries are sent from handler to originator when many replies to a single query are batched. The series of set queries is terminated by a final result <iq>
packet. Results of a jabber:iq:search protocol (see appendix) query may return several set
replies containing results, and a final result reply to mark the end of the search.
Despite the fact that multiple <query> packets can occur within a single <iq>
packet, there can only be a single logical query occurring at once.5 Multiple
<query> packets are normally used to return multiple matching results, similar to the return of multiple records in an SQL result.
Listing 6.1 Basic format of an IQ packet.
IQ type Message sent from Description
get originator–to–handler Originator wishes to obtain information from handler.
set originator–to–handlera Originator wishes to update information maintained by handler.
result handler–to–originator Handler returns the results of the originator’s get/set request.
error handler–to–originator Handler encountered an error carrying out get/set request.
Info/Query: the catch-all protocol 167
It is also important to point out that the <iq> packet doesn’t have to contain a
<query> subpacket. Result <iq> packets often don’t contain any subpackets. In addition, the <iq> packet can contain other subpackets like <vCard>. We won’t be covering any of the <iq> protocols that use subpackets other than <query> but you can learn more about them in appendix A.
IQ query originators do not have to wait for a reply before sending other IQ
query packets, nor should they expect the order of IQ results or errors to come in the same order as they sent them. In order for query originators to match an IQ
query to an IQ result each should contain the standard Jabber id attribute. This is a query-originator generated identifier that the IQ query handler will copy into its
IQ result or error packet. The query originator can inspect the id on IQ results and errors to match responses to queries.
As you can see from the example, the<iq> element itself is a simple wrapper tag that contains one or more <query> tags (figure 6.2). This design allows Jabber serv- ers to generically handle IQ packets without inspecting or having any knowledge about the specific queries being performed. This is important: nonstandard queries in standard IQ packets can be sent between clients without compromising Jabber standards compliance. This opens up an entire world of extensibility to Jabber sys- tems while relying on a single, standard Jabber messaging infrastructure.
Since the IQ packet and protocols don’t define anything beyond a generic enve- lope the details of specific IQ protocols must be handled somewhere else. These details are defined as IQ extensions.