<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
  <!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
  <title>Attention</title>
  <abstract>This document defines an XMPP protocol extension for getting the attention of another user.</abstract>
  &LEGALNOTICE;
  <number>0224</number>
  <status>Draft</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XMPP IM</spec>
    <spec>XEP-0030</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>attention</shortname>
  <schemaloc>
    <url>http://xmpp.org/schemas/attention.xsd</url>
  </schemaloc>
  <author>
    <firstname>Andreas</firstname>
    <surname>Monitzer</surname>
    <email>andy@monitzer.com</email>
    <jid>andy@monitzer.com</jid>
  </author>
  <revision>
    <version>1.0</version>
    <date>2008-11-13</date>
    <initials>psa</initials>
    <remark><p>Per a vote of the XMPP Council, advanced specification to Draft.</p></remark>
  </revision>
  <revision>
    <version>0.2</version>
    <date>2008-10-01</date>
    <initials>psa</initials>
    <remark><p>Modified namespace to incorporate namespace versioning.</p></remark>
  </revision>
  <revision>
    <version>0.1</version>
    <date>2007-08-08</date>
    <initials>psa</initials>
    <remark><p>Initial published version.</p></remark>
  </revision>
  <revision>
    <version>0.0.1</version>
    <date>2007-07-03</date>
    <initials>am</initials>
    <remark><p>Initial version.</p></remark>
  </revision>
</header>
<section1 topic='Introduction' anchor='intro'>
  <p>Even though a client might be available (as stated in the most recent presence stanza), the user this client belongs to might not be focused on the client currently. &xep0132; defines a method for a physical test of user presence. Since this requires special hardware that cannot be assumed to be available, this XEP defines a software-only implementation where no direct feedback is expected. This feature is known as 'nudge' or 'buzz' in some non-XMPP IM protocols.</p>
  <p>It was discussed whether this feature belongs in &xep0085;. However, the semantics are inherently different, since Chat State Notifications describe the sender's state, not a request to change the receiver's. Thus, a separate extension is desirable.</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
  <p>The specification addresses remotely getting the user's attention in a more assertive way than simple text messages.</p>
</section1>
<section1 topic='Protocol' anchor='protocol'>
  <p>In the following conversation, a user talks to somebody, but this user doesn't respond. The second inquiry includes an attention extension.</p>
  <example caption="User sends a regular message"><![CDATA[
<message from='calvin@usrobots.lit/lab'
         to='herbie@usrobots.lit/home'
         type='chat'>
  <body>All right, then, Herbie, give! We're waiting.</body>
</message>
]]></example>
  <p>When no reply is received, the sending user might want to grab the other's attention. This is done by sending a message that includes an &lt;attention/&gt; element qualified by the 'urn:xmpp:attention:0' namespace &VNOTE;. Note: The message MAY include a &BODY; element.</p>
  <example caption="User tries to capture the other's attention"><![CDATA[
<message from='calvin@usrobots.lit/lab'
         to='herbie@usrobots.lit/home'
         type='headline'>
  <attention xmlns='urn:xmpp:attention:0'/>
  <body>Why don't you answer, Herbie?</body>
</message>
]]></example>
  <p>Finally, the receiving user notices the urgency of the message and responds.</p>
  <example caption="The user whose attention has been captured responds."><![CDATA[
<message from='herbie@usrobots.lit/home'
         to='calvin@usrobots.lit/lab'
         type='chat'>
  <body>I cannot. You know I cannot! Dr. Bogert and Dr. Lanning don't want me to.</body>
</message>
]]></example>
</section1>
<section1 topic='Business Rules' anchor='rules'>
  <p>The following rules apply to generating and processing of the attention extension.</p>
  <ol>
    <li>Before sending an attention message stanza, the client SHOULD confirm support for it in the other client as described under <link url='#disco'>Determining Support</link>.</li>
    <li>The message stanza containing the attention extension MAY contain a body and/or other extensions, which is to be displayed along with executing the attention event.</li>
    <li>In message stanzas containing either &xep0203; data, attention extensions MUST be ignored, since the attention request is an instant event which SHOULD NOT be replayed after a delay.</li>
    <li>Messages containing an attention extension SHOULD use the headline message type to avoid offline storage.</li>
    <li>The attention extension MUST NOT be sent in &IQ; stanzas, since use of this feature is part of a messaging conversation.</li>
  </ol>
</section1>
<section1 topic='Determining Support' anchor='disco'>
  <p>If an entity wishes to receive the attention extension, it MUST advertise that fact in its responses to &xep0030; information ("disco#info") requests by returning a feature of "urn:xmpp:attention:0":</p>
  <example caption='A disco#info query'><![CDATA[
<iq type='get'
    from='calvin@usrobots.lit/lab'
    to='herbie@usrobots.lit/home'
    id='disco1'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
  <example caption='A disco#info response'><![CDATA[
<iq type='result'
    from='herbie@usrobots.lit/home'
    to='calvin@usrobots.lit/lab'
    id='disco1'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <feature var='urn:xmpp:attention:0'/>
  </query>
</iq>
]]></example>
  <p>In order for an application to determine whether an entity supports this protocol, where possible it SHOULD use the dynamic, presence-based profile of service discovery defined in &xep0115;. However, if an application has not received entity capabilities information from an entity, it SHOULD use explicit service discovery instead.</p>
</section1>
<section1 topic='Implementation Notes' anchor='impl'>
  <p>The implementation of the alert is up to the developer. Possible behavior includes:</p>
  <ul>
    <li>Shaking the window.</li>
    <li>Playing a specific sound not used for any other event.</li>
    <li>Flashing the screen.</li>
    <li>Enabling external hardware such as flashing lights.</li>
    <li>Let it be user customizable.</li>
  </ul>
  <p>Because some users might not want this feature to disturb them, a client MUST either (1) allow the user to disable support or (2) disable the feature by default and process attention requests only if the user has explicitly enabled support. When the feature is disabled, it MUST NOT be advertised in disco#info.</p>
  <p>Rate-limiting might be desirable in some implementations.</p>
  <p>Formal feedback in response to the attention request to the requesting user is not specified, and so the request might be silently dropped.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
  <p>It is RECOMMENDED that a client accept message stanzas containing the attention extension only contacts that are in the user's roster or with whom the user's client is currently sharing directed presence, mainly to prevent the user from being annoyed by attention requests from random entities on the network. A client could implement finer-grained control if desired (e.g., allow attention requests only from entities in a particular roster group).</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
  <p>This document requires no interaction with &IANA;.</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
    <p>This specification defines the following XML namespace:</p>
    <ul>
      <li>urn:xmpp:attention:0</li>
    </ul>
    <p>The &REGISTRAR; includes this namespace in the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
  </section2>
  <section2 topic='Protocol Versioning' anchor='registrar-versioning'>
    &NSVER;
  </section2>
</section1>
<section1 topic='XML Schema' anchor='schema'>
  <code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='urn:xmpp:attention:0'
    xmlns='urn:xmpp:attention:0'
    elementFormDefault='qualified'>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-0224: http://www.xmpp.org/extensions/xep-0224.html
    </xs:documentation>
  </xs:annotation>

  <xs:element name='attention' type='empty'/>

  <xs:simpleType name='empty'>
    <xs:restriction base='xs:string'>
      <xs:enumeration value=''/>
    </xs:restriction>
  </xs:simpleType>

</xs:schema>
]]></code>
</section1>
<section1 topic='Acknowledgements' anchor='ack'>
  <p>The quotes have been taken from Isaac Asimov's short story "Liar!" as published in the book <cite>The Complete Robot</cite>.</p>
</section1>
</xep>
