x4089.htm

Its a xmpp protocol book

></B
></TT
></P
><P
>This presence type is sent in reply to a presence subscription request, used
to accept the request.
<I
CLASS="EMPHASIS"
>(&ldquo;Okay, I accept your request; the server will send you my presence information.&rdquo;)</I
>
See <A
HREF="x4089.htm#JABTDG-CH-5-SECT-5.4.2.3"
>the section called <I
>Presence Subscription</I
></A
> for details.</P
><P
><TT
CLASS="USERINPUT"
><B
><TT
CLASS="LITERAL"
>type='unsubscribed'</TT
></B
></TT
></P
><P
>This presence type is sent in reply to a presence unsubscription request, used
to accept the request.
<I
CLASS="EMPHASIS"
>(&ldquo;Okay, I accept your unsubscription request; the server will stop sending you my presence information.&rdquo;)</I
></P
><P
>It is also used to deny a presence subscription request.
<I
CLASS="EMPHASIS"
>(&ldquo;No, I don't accept your subscription request; I don't want the server to send you my presence information.&rdquo;)</I
>
See <A
HREF="x4089.htm#JABTDG-CH-5-SECT-5.4.2.3"
>the section called <I
>Presence Subscription</I
></A
> for details.</P
></DD
></DL
></DIV
><P
></P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>from</DT
><DD
><P
><I
CLASS="EMPHASIS"
>Set by server</I
></P
><P
>Example:
<TT
CLASS="LITERAL"
>&#60;presence <TT
CLASS="USERINPUT"
><B
>from='dj@yak'</B
></TT
>/&#62;</TT
></P
><P
>Similar to the attribute of the same name in the
<TT
CLASS="LITERAL"
>&#60;message/&#62;</TT
> element,
here the <TT
CLASS="LITERAL"
>from</TT
> attribute is set by
the server and represents the JID where the availability information
originates.</P
><P
>If you are sending a presence probe
<TT
CLASS="LITERAL"
>type='probe'</TT
> you must set the
<TT
CLASS="LITERAL"
>from</TT
> attribute yourself, as mentioned
earlier.</P
></DD
><DT
>to</DT
><DD
><P
><I
CLASS="EMPHASIS"
>Optional</I
></P
><P
>Example:
<TT
CLASS="LITERAL"
>&#60;presence <TT
CLASS="USERINPUT"
><B
>to='sabine@yak'</B
></TT
>/&#62;</TT
></P
><P
>The <TT
CLASS="LITERAL"
>to</TT
> attribute is optional; if you are
just announcing availability (with the intention of having that announcement
reflected to the appropriate members of your roster), then specifying a
<TT
CLASS="LITERAL"
>to</TT
> attribute is not appropriate.

<A
NAME="TO-ATTRIBUTE"
HREF="#FTN.TO-ATTRIBUTE"
>[2]</A
>&#13;</P
><P
>If you want to send your availability to a specific entity, then do so using
this <TT
CLASS="LITERAL"
>to</TT
> attribute, specifying that entity's
JID. Why might you want to do this? See <A
HREF="x4089.htm#JABTDG-CH-5-SB-5"
>the sidebar <I
>Availability Tracker</I
></A
>
for an answer.</P
></DD
><DT
>id</DT
><DD
><P
><I
CLASS="EMPHASIS"
>Optional</I
></P
><P
>Example:
<TT
CLASS="LITERAL"
>&#60;presence <TT
CLASS="USERINPUT"
><B
>id='p1'</B
></TT
>/&#62;</TT
></P
><P
>All Jabber elements support an <TT
CLASS="LITERAL"
>id</TT
> attribute
for tracking purposes. So, the
<TT
CLASS="LITERAL"
>&#60;presence/&#62;</TT
>
packet is no different from the
<TT
CLASS="LITERAL"
>&#60;message/&#62;</TT
> packet in this
respect. As presence notification is usually a one-way thing, it is very
uncommon to see <TT
CLASS="LITERAL"
>&#60;presence/&#62;</TT
>
packets qualified with an <TT
CLASS="LITERAL"
>id</TT
> attribute.</P
></DD
></DL
></DIV
><TABLE
CLASS="SIDEBAR"
BORDER="1"
CELLPADDING="5"
><TR
><TD
><DIV
CLASS="SIDEBAR"
><A
NAME="JABTDG-CH-5-SB-5"
></A
><P
><B
>Availability Tracker</B
></P
><P
>The Jabber server (specifically, the presence handler within the JSM)
has a mechanism called the <I
CLASS="EMPHASIS"
>Availability Tracker</I
>. As its
name implies, its job is to track the availability of entities that have
previously made an availability announcement (in a 
<TT
CLASS="LITERAL"
>&#60;presence/&#62;</TT
> element).</P
><P
><A
HREF="x4089.htm#JABTDG-CH-5-SECT-5.4.2.3"
>the section called <I
>Presence Subscription</I
></A
> introduces the concept of exchange of
availability information via an exchange agreement recorded in the roster.
This mechanism covers the automatic distribution of availability notification
based upon pre-arranged presence subscriptions.</P
><P
>However, Jabber services (which are connected to the
<B
CLASS="COMMAND"
>jabberd</B
> backbone; see <A
HREF="x1234.htm"
>the section called <I
>An Overview of the Server Architecture</I
> in Chapter 4</A
>) can be connected to the Jabber backbone that
need to know an entity's availability, or more importantly, when they
suddenly become <I
CLASS="EMPHASIS"
>unavailable</I
>. These
Jabber services usually won't have a prior presence subscription agreement
recorded in anyone's roster.</P
><P
>The
<I
CLASS="EMPHASIS"
>Conferencing</I
> service, which provides group chat facilities,
allows users to join discussion &ldquo;rooms&rdquo; 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 their connection with the Jabber server&mdash;in other words when they
become unavailable&mdash;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 their Jabber server without first leaving the room?</P
><P
>The availability tracker mechanism comes to the rescue. It maintains a
list of JIDs to which an entity has sent their availability in a
<TT
CLASS="LITERAL"
>&#60;presence/&#62;</TT
> packet containing
a <TT
CLASS="LITERAL"
>to</TT
> attribute (i.e., a <I
CLASS="EMPHASIS"
>directed</I
>
<TT
CLASS="LITERAL"
>&#60;presence/&#62;</TT
> packet. When the
JSM notices that a user has ended their session by disconnecting, the
presence handler invokes the availability tracker to send an
<TT
CLASS="LITERAL"
>unavailable</TT
> <TT
CLASS="LITERAL"
>&#60;presence/&#62;</TT
>
packet (with the <TT
CLASS="LITERAL"
>type='unavailable'</TT
>
attribute) to all the JIDs to which the entity had sent directed availability
information during the lifetime of that session.</P
><P
>How does this help in the <I
CLASS="EMPHASIS"
>Conferencing</I
> 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:</P
><P
><PRE
CLASS="SCREEN"
>SEND: &#60;presence to='[e-mail]'/&#62;</PRE
></P
><P
>which would be for the <TT
CLASS="LITERAL"
>jdev</TT
> room running at the conferencing service at
<TT
CLASS="LITERAL"
>conference.jabber.org</TT
>.

<A
NAME="CONFERENCE-PROTOCOL"
HREF="#FTN.CONFERENCE-PROTOCOL"
>[3]</A
>&#13;</P
><P
>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.</P
></DIV
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="JABTDG-CH-5-SECT-5.4.2.2"
>Presence Subelements</A
></H3
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>show</DT
><DD
><P
><I
CLASS="EMPHASIS"
>Optional</I
></P
><P
>Example:</P
><P
><PRE
CLASS="SCREEN"
>&#60;presence&#62;
  <TT
CLASS="USERINPUT"
><B
>&#60;show&#62;xa&#60;/show&#62;</B
></TT
>
  &#60;status&#62;Gone home for the evening&#60;/status&#62;
&#60;/presence&#62;</PRE
></P
><P
>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 <TT
CLASS="LITERAL"
>&#60;presence/&#62;</TT
> element.
The first part of the detail is in the form of a
<TT
CLASS="LITERAL"
>&#60;show/&#62;</TT
> tag, which by
convention contains one of five possible values.
<A
HREF="x4089.htm#JABTDG-CH-5-TAB-4"
>Table 5-4</A
> lists these values, and their meaning.</P
></DD
></DL
></DIV
><DIV
CLASS="TABLE"
><A
NAME="JABTDG-CH-5-TAB-4"
></A
><P
><B
>Table 5-4. Presence 'show' values</B
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><THEAD
><TR
><TH
ALIGN="LEFT"
VALIGN="TOP"
>Value</TH
><TH
ALIGN="LEFT"
VALIGN="TOP"
>Meaning</TH
></TR
></THEAD
><TBODY
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
>away</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
>The user is available, but temporarily away from the client.</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
>chat</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
>This is similar to the <TT
CLASS="LITERAL"
>normal</TT
> value, but suggests that the user is
open to conversation.</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
>dnd</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
>&ldquo;Do Not Disturb.&rdquo; Although online and <I
CLASS="EMPHASIS"
>available</I
>, the user doesn't want
to be disturbed by anyone. Don't forget, unless the user is actually
offline (unavailable, or disconnected from the Jabber server), messages to
that user will be sent immediately and retrieved by the user when they change their status to available.</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
>normal</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
>This is the normal availability; there's nothing really special about this
qualification&mdash;the user is simply available. If no
<TT
CLASS="LITERAL"
>&#60;show/&#62;</TT
> tag is specified
in an available <TT
CLASS="LITERAL"
>&#60;presence/&#62;</TT
>
element, a value of normal is assumed.</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
>xa</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
>This is an extreme form of the <TT
CLASS="LITERAL"
>away</TT
> value&mdash;<TT
CLASS="LITERAL"
>xa</TT
> stands for <I
CLASS="EMPHASIS"
>Extended
Away</I
>, and is probably as near to an unavailable presence as you can
get.</TD
></TR
></TBODY
></TABLE
></DIV
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>status</DT
><DD
><P
><I
CLASS="EMPHASIS"
>Optional</I
></P
><P
>Example:</P
><P
><PRE
CLASS="SCREEN"
>&#60;presence&#62;
  &#60;show&#62;dnd&#60;/show&#62;
  <TT
CLASS="USERINPUT"
><B
>&#60;status&#62;working on my book!&#60;/status&#62;</B
></TT
>
&#60;/presence&#62;</PRE
></P
><P
>The other part of the detail that qualifies a user's availability is
the <TT
CLASS="LITERAL"
>&#60;status/&#62;</TT
> subelement.
It allows for a more descriptive remark that embellishes the
<TT
CLASS="LITERAL"
>&#60;show/&#62;</TT
> data.</P
><P
>The examples for this subelement and the
<TT
CLASS="LITERAL"
>&#60;show/&#62;</TT
> subelement
show how the <TT
CLASS="LITERAL"
>&#60;status/&#62;</TT
> value
is used as a textual description to explain the
<TT
CLASS="LITERAL"
>&#60;show/&#62;</TT
> value's "short-code", or
mnemonic.</P
></DD
><DT
>priority</DT
><DD
><P
><I
CLASS="EMPHASIS"
>Optional</I
></P
><P
>Example:</P
><P
><PRE
CLASS="SCREEN"
>&#60;presence&#62;
  &#60;show&#62;chat&#60;/show&#62;
  &#60;status&#62;coffee break&#60;/status&#62;
  <TT
CLASS="USERINPUT"
><B
>&#60;priority&#62;5&#60;/priority&#62;</B
></TT
>
&#60;/presence&#62;</PRE
></P
><P
>Earlier in this chapter, <A
HREF="x3795.htm"
>the section called <I
>Resources and Priority</I
></A
> describes
how a user's <I
CLASS="EMPHASIS"
>priority</I
> is used to determine the
primary session to which messages should be sent.</P
><P
>As we see here, the priority is set using the
<TT
CLASS="LITERAL"
>&#60;presence/&#62;</TT
> 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.</P
></DD
><DT
>x</DT
><DD
><P
><I
CLASS="EMPHASIS"
>Optional</I
></P
><P
>Example:</P
><P
><PRE
CLASS="SCREEN"
>&#60;presence from='dj@yak/Work' to='sabine@yak'&#62;
  &#60;status&#62;Online&#60;/status&#62;
  &#60;priority&#62;1&#60;/priority&#62;
  <TT
CLASS="USERINPUT"
><B
>&#60;x xmlns='jabber:x:delay' from='dj@yak/Work'
     stamp='20011005T10:58:28'/&#62;</B
></TT
>
&#60;/presence&#62;</PRE
></P
><P
>Just as with the <TT
CLASS="LITERAL"
>&#60;message/&#62;</TT