[standards-jig] cvs commit: standards jabber-x-event.sgml

stpeter at lor.jeremie.com stpeter at lor.jeremie.com
Tue Oct 9 03:00:13 UTC 2001


stpeter     01/10/08 22:00:13

  Added:       .        jabber-x-event.sgml
  Log:
  Initial version from DJ Adams.
  
  Revision  Changes    Path
  1.1                  standards/jabber-x-event.sgml
  
  Index: jabber-x-event.sgml
  ===================================================================
  <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
  ]>
  <?stylesheet href="/usr/local/sgml/dsssl/docbook/html/docbook.dsl" type="text/dsssl"?>
  
  <section id='JDP-JABBER-X-EVENT'>
  <title><literal>jabber:x:event</literal></title>
  
  <para>
  The <literal>jabber:x:event</literal> is a standard Jabber namespace
  that qualifies extensions
  used to request and respond to events relating to the
  delivery, display, and composition of <emphasis>messages</emphasis>.
  The original description for this namespace is at
  <ulink url='http://http://docs.jabber.org/draft-proto/html/events.html'>http://docs.jabber.org/draft-proto/html/events.html</ulink>.
  </para>
  
  <para>
  By attaching a <literal>jabber:x:event</literal> extension to a 
  <literal><![CDATA[<message/>]]></literal> element, the sender can track stages
  in the delivery of that element to its recipient.
  </para>
  
  <para>
  There are four message events currently defined in this namespace:
  </para>
  
  <variablelist>
  
  <varlistentry>
  <term><literal>offline</literal></term>
  <listitem>
  <para>
  Indicates that the message has been stored offline by the server, because the
  intended recipient is not available. This event is to be raised by the Jabber
  server. 
  <footnote>
  <para>
  In the current open source server, this is done by the <literal>mod_offline</literal>
  module within the JSM.
  </para>
  </footnote>
  </para>
  </listitem>
  </varlistentry>
  
  <varlistentry>
  <term><literal>delivered</literal></term>
  <listitem>
  <para>
  Indicates that the message has been delivered to the recipient. This signifies
  that the message has reached the Jabber client, but does not necessarily mean
  that the message has been displayed. This event is to be raised by the Jabber 
  client.
  </para>
  </listitem>
  </varlistentry>
  
  <varlistentry>
  <term><literal>displayed</literal></term>
  <listitem>
  <para>
  Once the message has been received by the Jabber client, it may be displayed to 
  the user. This event indicates that the message has been displayed, and is to be
  raised by the Jabber client. Even if a message is displayed multiple times, this
  event should only be raised once.
  </para>
  </listitem>
  </varlistentry>
  
  <varlistentry>
  <term><literal>composing</literal></term>
  <listitem>
  <para>
  In threaded chat conversations, this indicates that the recipient is composing a
  reply to a message that was just sent. The event is to be raised by the Jabber
  client. A Jabber client is allowed to raise this event multiple times in response
  to the same request, providing that a specific sequence is followed. See 
  <xref linkend='JDP-JABBER-X-EVENT-USAGE'> for details.
  </para>
  </listitem>
  </varlistentry>
  
  </variablelist>
  
  
  <section id='JDP-JABBER-X-EVENT-SCHEMA'>
  <title>Schema</title>
  
  <para>
  
  </para>
  
  </section>
  
  
  <section id='JDP-JABBER-X-EVENT-USAGE'>
  <title>Usage</title>
  
  <para>
  Extensions qualified by 
  the <literal>jabber:x:event</literal> namespace may only be used in the
  context of <literal><![CDATA[<message/>]]></literal> elements. That is,
  event information should be only requested, and given in response, in 
  relation to <literal><![CDATA[<message/>]]></literal> elements, and not 
  <literal><![CDATA[<presence/>]]></literal> or 
  <literal><![CDATA[<iq/>]]></literal> elements.
  </para>
  
  <para>
  Event information should only be sent in response to a request for that information.
  Unsollicited event information is illegal.
  </para>
  
  <para>
  Any request for the <literal>offline</literal> event in a message that has been
  stored offline must be removed by the server before the message is forwarded to 
  the Jabber client. This means that any <literal><![CDATA[<offline/>]]></literal>
  tag should be removed from the extension.
  </para>
  
  <section id='JDP-JABBER-X-EVENT-USAGE-REQ'>
  <title>Requesting an event</title>
  
  <para>
  An event is requested by attaching an extension qualified by the 
  <literal>jabber:x:event</literal> namespace to a <literal><![CDATA[<message/>]]></literal>
  element. A tag representing each event requested for that message should be placed
  within the extension. Only one <literal>jabber:x:event</literal>
  extension may be attached to a <literal><![CDATA[<message/>]]></literal> element, 
  but multiple events may be requested within that one extension.
  The tags representing each of the events are
  <literal><![CDATA[<offline/>]]></literal>,
  <literal><![CDATA[<delivered/>]]></literal>,
  <literal><![CDATA[<displayed/>]]></literal>, and
  <literal><![CDATA[<composing/>]]></literal>. 
  </para>
  
  <para>
  An example of a <literal><![CDATA[<message/>]]></literal> element with a
  <literal>jabber:x:event</literal> extension is shown in
  <xref linkend='JDP-JABBER-X-EVENT-EX-1'>.
  </para>
  
  <example id='JDP-JABBER-X-EVENT-EX-1'>
  <title>Requesting notification of offline storage and delivery for a message</title>
  
  <para>
  <screen>
  <![CDATA[
  <message to='dj at gnu.mine.nu' id='M22'>
    <subject>Just testing</subject>
    <body>I'm just testing</body>
    <x xmlns='jabber:x:event'>
      <offline/>
      <delivered/>
    </x>
  </message>
  
  ]]>
  </screen>
  </para>
  
  </example>
  
  <para>
  In <xref linkend='JDP-JABBER-X-EVENT-EX-1'> we see the sender wants to be notified
  if the message is stored offline (by the server), and when the message is 
  delivered (to the client). In this case, the sender will potentially receive two events
  based on this request. The first, if the recipient is offline and the message is stored
  on the server, and the second when the recipient becomes available and the message is
  delivered. 
  </para>
  
  <para>
  Note that the <literal><![CDATA[<message/>]]></literal> element contains an
  <literal>id</literal> attribute. While these attributes are not mandatory on
  elements in the Jabber protocol, it is recommended that messages to which a
  <literal>jabber:x:event</literal> extension is to be attached (to request
  notification for an event or events) contain
  an <literal>id</literal> attribute. This is to be able to match up the receipt
  of raised events with their original requests, and is described next.
  </para>
  
  </section>
  
  
  <section id='JDP-JABBER-X-EVENT-USAGE-RES'>
  <title>Responding to an event</title>
  
  <para>
  If the message is stored by the server, the server must raise the requested event
  (<literal>offline</literal>) by sending a message to the sender as shown in 
  <xref linkend='JDP-JABBER-X-EVENT-EX-2'>.
  </para>
  
  <example id='JDP-JABBER-X-EVENT-EX-2'>
  <title>Raising the <literal>offline</literal> event</title>
  
  <para>
  <screen>
  <![CDATA[
  <message from='dj at gnu.mine.nu' to='dj at qmacro.dyndns.org/cellar'>
    <x xmlns='jabber:x:event'>
      <offline/>
      <id>M22</id>
    </x>
  </message>
  
  ]]>
  </screen>
  </para>
  
  </example>
  
  <para>
  When raising an event, the raiser must send a <literal><![CDATA[<message/>]]></literal>
  element composed according to the following rules:
  </para>
  
  <itemizedlist>
  
  <listitem>
  <para>
  the element must contain <emphasis>only</emphasis> a 
  <literal>jabber:x:event</literal> extension. No standard message elements
  such as <literal><![CDATA[<subject/>]]></literal>, 
  <literal><![CDATA[<body/>]]></literal>, and so on, may be included.
  </para>
  </listitem>
  
  <listitem>
  <para>
  The extension must contain one tag representing the event being raised. For example,
  if the <literal>offline</literal> event is being raised, an 
  <literal><![CDATA[<offline/>]]></literal> tag must be included.
  (The events are temporally exclusive, thus only one event tag should ever be included.)
  </para>
  </listitem>
  
  <listitem>
  <para>
  The extension must also contain an <literal><![CDATA[<id/>]]></literal> tag. The
  contents of this tag must be the value of the <literal>id</literal> attribute of
  the original message to which this event pertains. If there was no 
  <literal>id</literal> attribute value in the original message, then the 
  <literal><![CDATA[<id/>]]></literal> tag must still be included, with no contents.
  </para>
  </listitem>
  
  <listitem>
  <para>
  The message's <literal>from</literal> attribute should be set to the recipient of
  the original message for which the event is being raised. (This an issue more 
  relevant for the server, in responding to the <literal>offline</literal> event,
  because clients should rely on the server to stamp the elements that they send out
  with a <literal>from</literal> attribute.)
  </para>
  </listitem>
  
  <listitem>
  <para>
  The link between the original message for which the event is being raised, and the
  message containing that raised event, is the <literal><![CDATA[<x/>]]></literal>
  tag in the <literal>jabber:x:event</literal> extension of the message containing that
  raised event, that points to the <literal>id</literal> attribute of the original message.
  </para>
  
  <para>
  The <literal>id</literal> attribute of the <literal><![CDATA[<message/>]]></literal>
  element containing the raised event is, like all <literal>id</literal> attributes,
  optional, and does not have to reflect the <literal>id</literal> attribute of the
  original message. (Indeed, when one considers that multiple events could be requested
  and raised for a single message, it becomes clear that the <literal>id</literal>
  attributes in the messages containing those raised events cannot all refer to the
  original message, as each element's <literal>id</literal> value must be unique.)
  </para>
  </listitem>
  
  </itemizedlist>
  
  </section>
  
  
  <section id='JDP-JABBER-X-EVENT-USAGE-COMPOSING'>
  <title>The <literal>composing</literal> event</title>
  
  <para>
  The <literal>composing</literal> event is slightly different from the other events
  in that it can be raised and cancelled, multiple times. This is to allow the 
  reflection of what actually is happening when a user replies to a message; he may
  start composing a reply, which would trigger the <literal>composing</literal> event,
  get halfway through, and stop. At this stage the event is no longer valid, or at
  least doesn't make much sense. So the client may send a cancellation for the
  <literal>composing</literal> event just raised.
  </para>
  
  <para>
  The cancellation is raised according to the same rules as how other events are
  raised, as described in <xref linkend='JDP-JABBER-X-EVENT-USAGE-RES'>, with one
  exception:
  </para>
  
  <itemizedlist>
  <listitem>
  <para>
  The <literal>jabber:x:event</literal> extension should contain a single 
  <literal><![CDATA[<composing/>]]></literal> tag, but <emphasis>no</emphasis>
  <literal><![CDATA[<id/>]]></literal> tag.
  </para>
  </listitem>
  
  </itemizedlist>
  
  <para>
  The lack of an <literal><![CDATA[<id/>]]></literal> tag signifies that the 
  <literal>composing</literal> event has been cancelled. 
  After cancelling a <literal>composing</literal> event, a new one may be raised,
  following the same rules as before, when the typing of the reply is resumed.
  </para>
  
  <note>
  <para>
  This also implies that only one <literal>composing</literal> event can be exchanged
  between two particular users, regardless of how many chat threads they may have.
  <footnote>
  <para>
  <emphasis>Is this correct?</emphasis>
  </para>
  </footnote>
  </para>
  </note>
  
  </section>
  
  </section>
  
  
  <section>
  <title>Examples</title>
  
  <para>
  This section contains a number of examples from one user's perspective.
  </para>
  
  <example id='JDP-JABBER-X-EVENT-EX-3'>
  <title>Requesting all events</title>
  
  <para>
  <screen>
  <![CDATA[
  SEND: <message to='dj at gnu.mine.nu' id='442'>
          <subject>Progress</subject>
          <body>Charting the progress of this message</body>
          <x xmlns='jabber:x:event'>
            <offline/>
            <delivered/>
            <displayed/>
            <composing/>
          </x>
        </message>
  
  ]]>
  </screen>
  </para>
  
  </example>
  
  
  <example id='JDP-JABBER-X-EVENT-EX-4'>
  <title>Receiving the <literal>offline</literal> event</title>
  
  <para>
  <screen>
  <![CDATA[
  RECV: <message from='dj at gnu.mine.nu' to='dj at qmacro.dyndns.org/cellar' id='x_19'>
          <x xmlns='jabber:x:event'>
            <offline/>
            <id>442</id>
          </x>
        </message>
  
  ]]>
  </screen>
  </para>
  
  </example>
  
  
  <example id='JDP-JABBER-X-EVENT-EX-5'>
  <title>Receiving the <literal>delivered</literal> event</title>
  
  <para>
  <screen>
  <![CDATA[
  RECV: <message from='dj at gnu.mine.nu/home' to='dj at qmacro.dyndns.org/cellar' id='M09'>
          <x xmlns='jabber:x:event'>
            <delivered/>
            <id>442</id>
          </x>
        </message>
  
  ]]>
  </screen>
  </para>
  
  </example>
  
  
  <example id='JDP-JABBER-X-EVENT-EX-6'>
  <title>Receiving the <literal>composing</literal> event</title>
  
  <para>
  <screen>
  <![CDATA[
  RECV: <message from='dj at gnu.mine.nu/home' to='dj at qmacro.dyndns.org/cellar' id='M31'>
          <x xmlns='jabber:x:event'>
            <composing/>
            <id>442</id>
          </x>
        </message>
  
  ]]>
  </screen>
  </para>
  
  </example>
  
  
  <example id='JDP-JABBER-X-EVENT-EX-7'>
  <title>Receiving cancellation of the <literal>composing</literal> event</title>
  
  <para>
  <screen>
  <![CDATA[
  RECV: <message from='dj at gnu.mine.nu/home' to='dj at qmacro.dyndns.org/cellar' id='M35'>
          <x xmlns='jabber:x:event'>
            <composing/>
          </x>
        </message>
  
  ]]>
  </screen>
  </para>
  
  </example>
  
  
  <example id='JDP-JABBER-X-EVENT-EX-8'>
  <title>Receiving a new <literal>composing</literal> event</title>
  
  <para>
  <screen>
  <![CDATA[
  RECV: <message from='dj at gnu.mine.nu/home' to='dj at qmacro.dyndns.org/cellar' id='M39'>
          <x xmlns='jabber:x:event'>
            <composing/>
            <x>442</x>
          </x>
        </message>
  
  ]]>
  </screen>
  </para>
  
  </example>
  
  </section>
  
  </section>
  
  
  
  



More information about the Standards mailing list