moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2025-02-17 15:40:30 -05:00
Code Issues Releases Wiki Activity

0.4

Browse Source 
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@893 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre 2007-05-30 22:39:09 +00:00
parent a99dd27e95
commit e03ef70c49
1 changed files with 31 additions and 70 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

101
xep-0184.xml
View File

@ -24,6 +24,12 @@
<shortname>TO BE ASSIGNED</shortname> <shortname>TO BE ASSIGNED</shortname>
&stpeter; &stpeter;
&hildjj; &hildjj;
<revision>
<version>0.4</version>
<date>2007-05-30</date>
<initials>psa</initials>
<remark><p>Per Council feedback, modified to use dedicated namespace (not AMP).</p></remark>
</revision>
<revision> <revision>
<version>0.3</version> <version>0.3</version>
<date>2006-11-06</date> <date>2006-11-06</date>
@ -56,8 +62,8 @@
</revision> </revision>
</header> </header>
<section1 topic='Introduction' anchor='intro'> <section1 topic='Introduction' anchor='intro'>
<p>While &xep0079; provides message acknowledgements at the server level, it does not extend that model all the way to the client. However, sometimes client-level acknowledgements are needed, for example to provide "receipts". This document defines a mechanism for XMPP message receipts, which are functionally equivalent to the "delivered" or "displayed" event in &xep0022;, which this specification in part obsoletes. <note>This specification does not distinguish between delivery and presentation, as was done in the message events protocol, in part because no existing clients make the distinction.</note> <p>While &xep0079; provides message acknowledgements at the server level, it does not extend that model all the way to the client. However, sometimes client-level acknowledgements are needed, for example to provide "receipts". This document defines a mechanism for XMPP message receipts, which are functionally equivalent to the "delivered" or "displayed" event in &xep0022;, which this specification in part obsoletes. <note>This specification does not distinguish between delivery and presentation, as was done in the message events protocol, in part because no existing clients make the distinction.</note></p>
</p> <p>Note: This extension is functionally equivalent to an <cite>Advanced Message Processing</cite> rule of "receipt" but uses a dedicated namespace to simplify processing by end clients and intermediate routers.</p>
</section1> </section1>
<section1 topic='Requirements' anchor='reqs'> <section1 topic='Requirements' anchor='reqs'>
<p>This document addresses the following requirements:</p> <p>This document addresses the following requirements:</p>
@ -68,14 +74,13 @@
<p>Note: This document explicitly does not define a protocol for "guaranteed delivery", since that term (like "security") means different things to different people. Instead, we define a more focused protocol that addresses the need for message receipts, thus solving one problem that falls under the heading of "guaranteed delivery".</p> <p>Note: This document explicitly does not define a protocol for "guaranteed delivery", since that term (like "security") means different things to different people. Instead, we define a more focused protocol that addresses the need for message receipts, thus solving one problem that falls under the heading of "guaranteed delivery".</p>
</section1> </section1>
<section1 topic='Protocol Format' anchor='format'> <section1 topic='Protocol Format' anchor='format'>
<p>In order to make it possible for senders to request and for recipients to generate message receipts, we define a new <cite>Advanced Message Processing</cite> rule: "receipt". In accordance with <cite>XEP-0079</cite>, we provide the following information about the receipt rule:</p> <p>In order to make it possible for senders to request and for recipients to generate message receipts, we define a dedicated protocol extension qualified by the 'http://www.xmpp.org/extensions/xep-0184.html#ns' namespace &NSNOTE;.</p>
<p>There are two allowable elements in this namespace:</p>
<ul> <ul>
<li>The namespace shall be "http://jabber.org/protocol/amp?condition=receipt".</li> <li>&lt;request/&gt; -- included by a sending entity that wishes to know if the message has been received.</li>
<li>The condition applies only to final receipt by the intended recipient; therefore, the per-hop flag does not apply.</li> <li>&lt;received/&gt; -- included by a receiving entity that wishes to inform the sending the entity that the message has been received.</li>
<li>The only defined value of the receipt rule is "received".</li>
<li>This condition is met if a message processing application (client) controlled by the intended recipient has received and processed the message; the term "processed" is understood to include presentation to a human user if appropriate or any other application-specific client-side processing, including generation of an error response if the application determines that the message contents cannot be handled.</li>
<li>Although any defined action may be triggered, the only action needed in order to support message receipts is the "notify" action.</li>
</ul> </ul>
<p>Specifically, the receiving entity shall return a &lt;received/&gt; notice if it has received and processed the message. The term "processed" is understood to include presentation to a human user if appropriate or any other application-specific client-side processing, including generation of an error response if the application determines that the message contents cannot be handled.</p>
<p>The following is an example of a message that includes a request for return receipt.</p> <p>The following is an example of a message that includes a request for return receipt.</p>
<example caption='A message with receipt requested'><![CDATA[ <example caption='A message with receipt requested'><![CDATA[
<message <message
@ -83,40 +88,31 @@
id='richard2-4.1.247' id='richard2-4.1.247'
to='kingrichard@royalty.england.lit/throne'> to='kingrichard@royalty.england.lit/throne'>
<body>My lord, dispatch; read o'er these articles.</body> <body>My lord, dispatch; read o'er these articles.</body>
<amp xmlns='http://jabber.org/protocol/amp'> <request xmlns='http://www.xmpp.org/extensions/xep-0184#ns'/>
<rule condition='receipt' action='notify' value='received'/>
</amp>
</message> </message>
]]></example> ]]></example>
<p>The recipient MUST generate a receipt if and only if it meets all of the following criteria:</p> <p>The recipient shall generate a receipt if and only if it supports the protocol defined herein and it is configured to return receipts, either globally or for this recipient (otherwise it MUST NOT return a receipt and SHOULD NOT return an error).</p>
<ol>
<li>It supports Advanced Message Processing.</li>
<li>It supports the "receipt" rule.</li>
<li>It is configured to return receipts, either globally or for this recipient.</li>
</ol>
<example caption='A message receipt'><![CDATA[ <example caption='A message receipt'><![CDATA[
<message <message
from='kingrichard@royalty.england.lit/throne' from='kingrichard@royalty.england.lit/throne'
id='richard2-4.1.247' id='richard2-4.1.247'
to='northumberland@shakespeare.lit/westminster'> to='northumberland@shakespeare.lit/westminster'>
<amp xmlns='http://jabber.org/protocol/amp' status='notify'> <received xmlns='http://www.xmpp.org/extensions/xep-0184#ns'/>
<rule condition='receipt' action='notify' value='received'/>
</amp>
</message> </message>
]]></example> ]]></example>
<p>If the recipient does not meet all of the foregoing criteria, it MUST NOT return a receipt and MUST NOT return an error.</p> <p>The &lt;received/&gt; element SHOULD be the only child of the &MESSAGE; stanza and MUST mirror the 'id' of the sent message.</p>
</section1> </section1>
<section1 topic='Business Rules' anchor='rules'> <section1 topic='Business Rules' anchor='rules'>
<p>The general business rules specified for Advanced Message Processing in <cite>XEP-0079</cite> apply to any rule; in addition, the following business rules apply specifically to the receipt rule:</p> <p>The following business rules apply:</p>
<ol start='1'> <ol start='1'>
<li><p>A sender SHOULD NOT include a request for message receipts when sending a message to the bare JID (&BAREJID;) of the recipient, only when sending to a full JID (&FULLJID;).</p></li> <li><p>A sender SHOULD NOT include a request for message receipts when sending a message to the bare JID (&BAREJID;) of the recipient, only when sending to a full JID (&FULLJID;).</p></li>
<li><p>A sender SHOULD NOT include a request for message receipts unless it knows (via &xep0030; or &xep0115;) that the intended recipient supports the protocol described herein or unless the use of message receipts is negotiated via &xep0155;.</p></li> <li><p>A sender SHOULD NOT include a request for message receipts unless it knows (via &xep0030; or &xep0115;) that the intended recipient supports the protocol described herein or unless the use of message receipts is negotiated via &xep0155;.</p></li>
</ol> </ol>
<p>Naturally, the receipt rule can be combined wiith rules specified in <cite>XEP-0079</cite> (e.g., the deliver rule) for more complete reporting.</p> <p>Naturally, message receipts can be combined with the rules specified in <cite>Advanced Message Processing</cite> (e.g., the deliver rule) for more complete reporting.</p>
</section1> </section1>
<section1 topic='Service Discovery' anchor='disco'> <section1 topic='Service Discovery' anchor='disco'>
<p>If a sender wishes to request message receipts, it SHOULD first discover whether the intended recipient supports message receipts. Support can be discovered indirectly via <cite>Entity Capabilities</cite> or directly via <cite>Service Discovery</cite>.</p> <p>If a sender wishes to request message receipts, it SHOULD first discover whether the intended recipient supports message receipts. Support can be discovered indirectly via <cite>Entity Capabilities</cite> or directly via <cite>Service Discovery</cite>.</p>
<p>If an entity supports Advanced Message Processing, it MUST report that by including a service discovery feature of "http://jabber.org/protocol/amp" as described in <cite>XEP-0079</cite>:</p> <p>If an entity supports message receipts, it MUST report that by including a service discovery feature of "http://www.xmpp.org/extensions/xep-0184.html#ns" in response to disco#info requests &NSNOTE;:</p>
<example caption="Initial Service Discovery information request"><![CDATA[ <example caption="Initial Service Discovery information request"><![CDATA[
<iq from='northumberland@shakespeare.lit/westminster' <iq from='northumberland@shakespeare.lit/westminster'
to='kingrichard@royalty.england.lit/throne' to='kingrichard@royalty.england.lit/throne'
@ -130,35 +126,14 @@
type='result'> type='result'>
<query xmlns='http://jabber.org/protocol/disco#info'> <query xmlns='http://jabber.org/protocol/disco#info'>
... ...
<feature var='http://jabber.org/protocol/amp'/> <feature var='http://www.xmpp.org/extensions/xep-0184.html#ns'/>
...
</query>
</iq>
]]></example>
<p>An entity that supports Advanced Message Processing SHOULD also maintain a service discovery node named "http://jabber.org/protocol/amp", at which it advertises the individual actions and conditions it supports. If an entity supports message receipts, it SHOULD respond to service discovery information requests sent to that node with a reply that includes the 'http://jabber.org/protocol/amp?condition=receipt' condition:</p>
<example caption="Request for information about individual actions and conditions"><![CDATA[
<iq from='northumberland@shakespeare.lit/westminster'
to='kingrichard@royalty.england.lit/throne'
type='get'>
<query xmlns='http://jabber.org/protocol/disco#info'
node='http://jabber.org/protocol/amp'/>
</iq>
]]></example>
<example caption="Response for individual actions and conditions"><![CDATA[
<iq from='kingrichard@royalty.england.lit/throne'
to='northumberland@shakespeare.lit/westminster'
type='result'>
<query xmlns='http://jabber.org/protocol/disco#info'
node='http://jabber.org/protocol/amp'>
...
<feature var='http://jabber.org/protocol/amp?condition=receipt'/>
... ...
</query> </query>
</iq> </iq>
]]></example> ]]></example>
</section1> </section1>
<section1 topic='Negotiation' anchor='neg'> <section1 topic='Negotiation' anchor='neg'>
<p>Two entities MAY negotiate the use of message receipts for a given session using <cite>Chat Session Negotiation</cite>. The parameter to be negotiated is named "http://jabber.org/protocol/amp?condition=receipt". Its use is illustrated in the following examples.</p> <p>Two entities MAY negotiate the use of message receipts for a given session using <cite>Stanza Session Negotiation</cite>. The parameter to be negotiated is named "http://www.xmpp.org/extensions/xep-0184.html#ns". Its use is illustrated in the following examples.</p>
<example caption="User requests chat session"><![CDATA[ <example caption="User requests chat session"><![CDATA[
<message type='normal' <message type='normal'
from='northumberland@shakespeare.lit/westminster' from='northumberland@shakespeare.lit/westminster'
@ -168,7 +143,7 @@
<feature xmlns='http://jabber.org/protocol/feature-neg'> <feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data' type='form'> <x xmlns='jabber:x:data' type='form'>
<field var='FORM_TYPE' type='hidden'> <field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/chatneg</value> <value>urn:xmpp:ssn</value>
</field> </field>
<field label='Accept this chat?' <field label='Accept this chat?'
type='boolean' type='boolean'
@ -178,7 +153,7 @@
</field> </field>
<field label='Enable Message Receipts?' <field label='Enable Message Receipts?'
type='boolean' type='boolean'
var='http://jabber.org/protocol/amp?condition=receipt'> var='http://www.xmpp.org/extensions/xep-0184.html#ns'>
<value>0</value> <value>0</value>
</field> </field>
</x> </x>
@ -194,12 +169,12 @@
<feature xmlns='http://jabber.org/protocol/feature-neg'> <feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data' type='submit'> <x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE' type='hidden'> <field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/chatneg</value> <value>urn:xmpp:ssn</value>
</field> </field>
<field var='accept'> <field var='accept'>
<value>true</value> <value>true</value>
</field> </field>
<field var='http://jabber.org/protocol/amp?condition=receipt'> <field var='http://www.xmpp.org/extensions/xep-0184.html#ns'>
<value>1</value> <value>1</value>
</field> </field>
</x> </x>
@ -217,30 +192,16 @@
<p>No interaction with &IANA; is necessary as a result of this document.</p> <p>No interaction with &IANA; is necessary as a result of this document.</p>
</section1> </section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'> <section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<section2 topic='Rule Conditions Registry' anchor='registrar-conditions'> <section2 topic='Protocol Namespaces' anchor='ns'>
<p>The &REGISTRAR; maintains a registry of Advanced Message Processing &lt;rule/&gt; conditions (see &AMPCONDITIONS;). The Registrar shall add the following condition to the registry:</p> <p>Until this specification advances to a status of Draft, its associated namespace shall be "http://www.xmpp.org/extensions/xep-0184.html#ns"; upon advancement of this specification, the &REGISTRAR; shall issue a permanent namespace in accordance with the process defined in Section 4 of &xep0053;.</p>
<code><![CDATA[
<condition>
<name>receipt</name>
<ns>http://jabber.org/protocol/amp?condition=receipt</ns>
<per-hop>false</per-hop>
<value>received</value>
<processing>
The condition is met if a message processing application (client)
controlled by the intended recipient has received and processed
the message, including presentation to a human user if appropriate.
</processing>
<doc>XEP-0184</doc>
</condition>
]]></code>
</section2> </section2>
<section2 topic='Field Standardization' anchor='registrar-formtype'> <section2 topic='Field Standardization' anchor='registrar-formtype'>
<p>&xep0068; defines a process for standardizing the fields used within Data Forms qualified by a particular namespace and the XMPP Registrar maintains a registry of such fields (see &FORMTYPES;). The Registrar shall add the following field for use in Chat Session Negotiation forms:</p> <p>&xep0068; defines a process for standardizing the fields used within Data Forms qualified by a particular namespace, and the XMPP Registrar maintains a registry of such fields (see &FORMTYPES;). The Registrar shall add the following field for use in Stanza Session Negotiation forms:</p>
<code caption='Registry Submission'><![CDATA[ <code caption='Registry Submission'><![CDATA[
<form_type> <form_type>
<name>http://jabber.org/protocol/chatneg</name> <name>urn:xmpp:ssn</name>
<field <field
var='http://jabber.org/protocol/amp?condition=receipt' var='http://www.xmpp.org/extensions/xep-0184.html#ns'
type='boolean' type='boolean'
label='Whether to enable Message Receipts per XEP-0184'/> label='Whether to enable Message Receipts per XEP-0184'/>
</form_type> </form_type>