x4089.htm

Its a xmpp protocol book

ALIGN="LEFT"
VALIGN="TOP"
>Text</TH
></TR
></THEAD
><TBODY
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
>400</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
>Bad Request</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
>401</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
>Unauthorized</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
>402</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
>Payment Required</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
>403</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
>Forbidden</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
>404</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
>Not Found</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
>405</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
>Not Allowed</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
>406</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
>Not Acceptable</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
>407</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
>Registration Required</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
>408</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
>Request Timeout</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
>409</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
>Conflict</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
>500</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
>Internal Server Error</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
>501</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
>Not Implemented</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
>502</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
>Remove Server Error</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
>503</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
>Service Unavailable</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
>504</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
>Remove Server Timeout</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
>510</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
>Disconnected</TD
></TR
></TBODY
></TABLE
></DIV
></DIV
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="JABTDG-CH-5-SECT-5.4.2"
>The Presence Element</A
></H2
><P
>The <TT
CLASS="LITERAL"
>&#60;presence/&#62;</TT
> element is
that which is used to convey a Jabber entity's availability. An entity
can be <I
CLASS="EMPHASIS"
>available</I
>, which means that it's connected and
any packets sent to it will be delivered immediately, or it can be
<I
CLASS="EMPHASIS"
>unavailable</I
>, which means that it's not connected, and
any packets sent to it will be stored and delivered the next time a connection
is made.</P
><P
>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 <I
CLASS="EMPHASIS"
>unavailability</I
>
if that entity disconnects from the server, but will only do that if the
entity has communicated its <I
CLASS="EMPHASIS"
>availability</I
> beforehand.</P
><P
>Availability information isn't a free-for-all. Presence in Jabber
is usually exchanged within a subscription mechanism.
See <A
HREF="x4089.htm#JABTDG-CH-5-SECT-5.4.2.3"
>the section called <I
>Presence Subscription</I
></A
> for an explanation.</P
><TABLE
CLASS="SIDEBAR"
BORDER="1"
CELLPADDING="5"
><TR
><TD
><DIV
CLASS="SIDEBAR"
><A
NAME="JABTDG-CH-5-SB-3"
></A
><P
><B
>Presence is a <TT
CLASS="LITERAL"
>jabber:client</TT
> thing</B
></P
><P
>It's worth noting that the <I
CLASS="EMPHASIS"
>entities</I
> referred to here are
<I
CLASS="EMPHASIS"
>client</I
> entities. That is, clients (and therefore the
users using those clients) connected to the Jabber server over
an XML stream qualified by the <TT
CLASS="LITERAL"
>jabber:client</TT
>
namespace (see <A
HREF="x3837.htm"
>the section called <I
>XML Streams</I
></A
>, earlier). Presence
is a feature made available within the Jabber Session Manager (JSM).
External components that connect to the Jabber server backbone are separate
from the JSM and therefore don't have any concept of presence. They are
either connected to the backbone, or they're not.</P
></DIV
></TD
></TR
></TABLE
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="JABTDG-CH-5-SECT-5.4.2.1"
>Presence Attributes</A
></H3
><P
>The attributes of the <TT
CLASS="LITERAL"
>&#60;presence/&#62;</TT
>
element are similar to those of the
<TT
CLASS="LITERAL"
>&#60;message/&#62;</TT
> element.</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>type</DT
><DD
><P
><I
CLASS="EMPHASIS"
>Optional</I
></P
><P
>Example:
<TT
CLASS="LITERAL"
>&#60;presence <TT
CLASS="USERINPUT"
><B
>type='unavailable'</B
></TT
>&#62;</TT
></P
><P
>The <TT
CLASS="LITERAL"
>type</TT
> attribute of the
<TT
CLASS="LITERAL"
>&#60;presence/&#62;</TT
> element is
used for many purposes. The basic usage is to convey availability.
Two values are used: <TT
CLASS="LITERAL"
>available</TT
> and <TT
CLASS="LITERAL"
>unavailable</TT
>. Another value is
to signify that
<TT
CLASS="LITERAL"
>&#60;presence/&#62;</TT
> packet
is being used to query the packet recipient's presence (value is <TT
CLASS="LITERAL"
>probe</TT
>).
The rest of the values (<TT
CLASS="LITERAL"
>subscribe</TT
>, <TT
CLASS="LITERAL"
>unsubscribe</TT
>, <TT
CLASS="LITERAL"
>subscribed</TT
>,
<TT
CLASS="LITERAL"
>unsubscribed</TT
>) are used in the subscription structure which is described in <A
HREF="x4089.htm#JABTDG-CH-5-SECT-5.4.2.3"
>the section called <I
>Presence Subscription</I
></A
>.</P
><P
></P
><P
><TT
CLASS="USERINPUT"
><B
><TT
CLASS="LITERAL"
>type='available'</TT
></B
></TT
></P
><P
>The <TT
CLASS="LITERAL"
>available</TT
> presence type is used by entities to announce their
availability. This announcement is usually made to the Jabber server which
manages the presence subscription mechanism (see <A
HREF="x4089.htm#JABTDG-CH-5-SECT-5.4.2.3"
>the section called <I
>Presence Subscription</I
></A
> for more
details). However it can also be directed to a particular JID if the entity
wants to control presence information itself.</P
><P
>The <TT
CLASS="LITERAL"
>available</TT
> presence isn't a simple binary &ldquo;on/off&rdquo;, there are varying
degrees of availability which are specified using subelements of the
<TT
CLASS="LITERAL"
>&#60;presence/&#62;</TT
> packet. These include
<TT
CLASS="LITERAL"
>&#60;show/&#62;</TT
> and
<TT
CLASS="LITERAL"
>&#60;status/&#62;</TT
>. These subelements
are described next.&#13;</P
><P
>If no <TT
CLASS="LITERAL"
>type</TT
> attribute is specified, then
this value of <TT
CLASS="LITERAL"
>available</TT
> is assumed. It makes sense, as the most common
type of
<TT
CLASS="LITERAL"
>&#60;presence/&#62;</TT
> packet sent by
entities is usually the <TT
CLASS="LITERAL"
>available</TT
> type, optionally qualified
with the <TT
CLASS="LITERAL"
>&#60;show/&#62;</TT
> and
<TT
CLASS="LITERAL"
>&#60;status/&#62;</TT
> subelements, as the
user of the connected client changes his circumstances over time (off for a
break, back, out to lunch, and so on).</P
><P
><TT
CLASS="USERINPUT"
><B
><TT
CLASS="LITERAL"
>type='unavailable'</TT
></B
></TT
></P
><P
>The <TT
CLASS="LITERAL"
>unavailable</TT
> presence type is the antithesis of the <TT
CLASS="LITERAL"
>available</TT
>
presence type. It is used to qualify an entity's unavailability. An
entity is unavailable when its client has disconnected from the Jabber
server.</P
><P
>So how can the client send an <TT
CLASS="LITERAL"
>unavailable</TT
> presence packet if it's
disconnected? Furthermore, how can we make sure that clients actually
<I
CLASS="EMPHASIS"
>send</I
> such a packet when
they disconnect (to keep the presence information equilibrium)?
Well, it can't, and we don't, respectively. It is the Jabber server that
sends out <TT
CLASS="LITERAL"
>unavailable</TT
> presence packets on behalf of the entity once it
disconnects. This is part of the presence service of the JSM and closely
related to the presence subscription mechanism. See <A
HREF="x4089.htm#JABTDG-CH-5-SB-5"
>the sidebar <I
>Availability Tracker</I
></A
> for more details.</P
><P
>While the <TT
CLASS="LITERAL"
>&#60;show/&#62;</TT
> and
<TT
CLASS="LITERAL"
>&#60;status/&#62;</TT
> subelements
qualify the <TT
CLASS="LITERAL"
>available</TT
> presence packet, there's no point in any
embellishment of the fact that the entity is
<I
CLASS="EMPHASIS"
>unavailable</I
>, so no subelements are used when
the packet is of the <TT
CLASS="LITERAL"
>unavailable</TT
> type.</P
><P
>When a user is <TT
CLASS="LITERAL"
>unavailable</TT
>, any packets
(<TT
CLASS="LITERAL"
>&#60;message/&#62;</TT
>,
<TT
CLASS="LITERAL"
>&#60;presence/&#62;</TT
> or
<TT
CLASS="LITERAL"
>&#60;iq/&#62;</TT
>) sent to that user
are stored offline and delivered when he comes online and establishes
his availability.</P
><P
><TT
CLASS="USERINPUT"
><B
><TT
CLASS="LITERAL"
>type='probe'</TT
></B
></TT
></P
><P
>The <TT
CLASS="LITERAL"
>probe</TT
> 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&mdash;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:</P
><P
></P
><UL
><LI
><P
>Information will only be returned 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&mdash;only those who have previously given you permission to
be informed of their availability. See <A
HREF="x4089.htm#JABTDG-CH-5-SECT-5.4.2.3"
>the section called <I
>Presence Subscription</I
></A
> for more details.</P
></LI
><LI
><P
>The <TT
CLASS="LITERAL"
>&#60;presence/&#62;</TT
> packet must
be specified with a <TT
CLASS="LITERAL"
>from</TT
> attribute specifying
the sender's JID in the form <TT
CLASS="LITERAL"
>username@hostname</TT
>
before it is sent. The Jabber server does not add this attribute. The presence mechanism will use the full JID (including any
<TT
CLASS="LITERAL"
>resource</TT
>) when working out whether the
prober has permission. This will ultimately fail because permission is
determined on a <TT
CLASS="LITERAL"
>username@hostname</TT
> basis,
not a <TT
CLASS="LITERAL"
>username@hostname/resource</TT
> basis.</P
></LI
></UL
><P
><TT
CLASS="USERINPUT"
><B
><TT
CLASS="LITERAL"
>type='subscribe'</TT
></B
></TT
></P
><P
>This presence type is a request to subscribe to an entity's presence.
<I
CLASS="EMPHASIS"
>(&ldquo;Will you allow me to be sent your presence information by the server?&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='unsubscribe'</TT
></B
></TT
></P
><P
>This presence type is a request to unsubscribe from an entity's presence.
<I
CLASS="EMPHASIS"
>(&ldquo;I don't want to be sent your presence information anymore, please
have the server stop sending it to me.&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='subscribed'</TT