On 10/16/10 1:19 AM, Kevin Smith wrote: > On Thu, Oct 14, 2010 at 3:12 PM, Leon Roy <[email protected]> wrote: >> We're coding new XMPP clients which report to each other the time a message >> is read by the far party. > > At the moment, XEP-0184 is worded ambiguously about whether it deals > with delivery notifications, or read notifications. It's been my > intention for a while to submit a patch that makes it clear that it's > delivery receipts (list discussion had consensus that this was the > intent), and to write a very similar XEP that deals with read receipts > - I think this is what you want, rather than using 184. As always with > these intentions, I've not gotten around to it yet.
Done in version 1.2rc2: http://xmpp.org/extensions/tmp/xep-0184-1.2.html Diff from 1.2rc1 attached. Clear enough for everyone? Peter -- Peter Saint-Andre https://stpeter.im/
diff --git a/extensions/xep-0184.xml b/extensions/xep-0184.xml
index 6828f94..2e5ded7 100644
--- a/extensions/xep-0184.xml
+++ b/extensions/xep-0184.xml
@@ -6,8 +6,8 @@
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
- <title>Message Receipts</title>
- <abstract>This specification defines an XMPP protocol extension for message
receipts, whereby the sender of a message can request notification that it has
been received by the intended recipient.</abstract>
+ <title>Message Delivery Receipts</title>
+ <abstract>This specification defines an XMPP protocol extension for message
delivery receipts, whereby the sender of a message can request notification
that the message has been delivered to a client controlled by the intended
recipient.</abstract>
&LEGALNOTICE;
<number>0184</number>
<status>Draft</status>
@@ -29,10 +29,10 @@
&stpeter;
&hildjj;
<revision>
- <version>1.2rc1</version>
- <date>2011-02-16</date>
+ <version>1.2rc2</version>
+ <date>2011-02-22</date>
<initials>psa</initials>
- <remark><p>Clarified terminology and several points of
implementation.</p></remark>
+ <remark><p>Clarified terminology and several points of implementation;
explicitly stated that this protocol notifies the sender only that a message
has been delivered to a client, not that it has been read or understood by a
human user (if any); changed title from Message Receipts to Message Delivery
Receipts to make this 100% clear.</p></remark>
</revision>
<revision>
<version>1.1</version>
@@ -41,7 +41,7 @@
<remark>
<ul>
<li>Clarified the level of reliability that this protocol provides
and, most importantly, does not provide.</li>
- <li>Explicitly discouraged dependence on receipts unless some other
protocol is used to negotiate the use of message receipts.</li>
+ <li>Explicitly discouraged dependence on receipts unless some other
protocol is used to negotiate the use of message delivery receipts.</li>
<li>Provided explicit recommendations about when and when not to
request receipts.</li>
<li>Relaxed the business rules to allow inclusion of receipt requests
even to the bare JID and even if the sender does not yet know whether the
intended recipient supports this protocol.</li>
<li>Added 'id' attribute to <received/> element for tracking
purposes.</li>
@@ -94,47 +94,48 @@
</header>
<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. <note>Naturally, message
receipts can be combined with the rules specified in <cite>Advanced Message
Processing</cite> for more complete reporting.</note> 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>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 user clients and intermediate routers.</p>
+ <p>While &xep0079; provides message acknowledgements at the server level, it
does not extend that model all the way to the client. <note>Naturally, message
delivery receipts can be combined with the rules specified in <cite>Advanced
Message Processing</cite> for more complete reporting.</note> However,
sometimes client-level acknowledgements are needed, for example to provide
"receipts". This document defines a mechanism for XMPP message delivery
receipts, which are functionally equivalent to the "delivered" or "displayed"
event in &xep0022;, which this specification in part obsoletes.</p>
+ <p>Note well that this specification does not distinguish between delivery
and display, as was done in the message events protocol, in part because no
implementations of XEP-0022 made that distinction. However, in the absence of
such a distinction, readers need to understand that this protocol can provide
only a notification that a message has been received at a client, i.e.
delivered to a client, not that the message has been actively read or
understood by a human user (if any). Therefore this extension is functionally
equivalent to an <cite>Advanced Message Processing</cite> rule of "receipt",
although it uses a dedicated namespace to simplify processing by clients and
intermediate routers.</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<p>This document addresses the following requirements:</p>
<ol>
- <li>Enable a sender to request notification that an XMPP message stanza
has been received.</li>
- <li>Enable a recipient to provide message receipts if desired.</li>
+ <li>Enable a sender to request notification that an XMPP message stanza
has been received (i.e., delivered to a client, but not necessarily read or
understood by a human user, if any).</li>
+ <li>Enable a recipient to provide message delivery receipts if
desired.</li>
</ol>
</section1>
<section1 topic='Terminology' anchor='terms'>
<p>The term "content message" refers to the stanza for which the original
sender would like to receive a receipt.</p>
- <p>The term "ack message" refers to the stanza by which the recipient
acknowledges receipt of the content message.</p>
+ <p>The term "ack message" refers to the stanza by which the recipient
acknowledges receipt of the content message at a client (i.e., delivery to a
client).</p>
</section1>
<section1 topic='What This Protocol Provides' anchor='what'>
- <p>This document defines a protocol that enables a sender to ask the
recipient to acknowledge receipt of a content message by returning an ack
message. Although the return of an ack message lets the sender know that the
content message has been delivered, there are many reasons why the sender might
not receive an ack message immediately or at all, including but not limited to
the following:</p>
+ <p>This document defines a protocol that enables a sender to ask the
recipient to acknowledge receipt of a content message by returning an ack
message. Although the return of an ack message lets the sender know that the
content message has been delivered to a client controlled by the intended
recipient, there are many reasons why the sender might not receive an ack
message immediately or at all, including but not limited to the following:</p>
<ul>
- <li>The sender addressed the content message to the recipient's bare JID
&LOCALBARE; and therefore does not know if the recipient even supports the
Message Receipts protocol.</li>
- <li>The sender has not bothered to determine whether the recipient
supports the Message Receipts protocol.</li>
- <li>The recipient (or the particular intended resource to which the sender
addressed the content message) does not in fact support the Message Receipts
protocol.</li>
- <li>The intended resource supports the Message Receipts protocol but the
recipient's server delivers the content message to another resource that does
not support the Message Receipts protocol.</li>
+ <li>The sender addressed the content message to the recipient's bare JID
&LOCALBARE; and therefore does not know if the recipient even supports the
Message Delivery Receipts protocol.</li>
+ <li>The sender has not bothered to determine whether the recipient
supports the Message Delivery Receipts protocol.</li>
+ <li>The recipient (or the particular intended resource to which the sender
addressed the content message) does not in fact support the Message Delivery
Receipts protocol.</li>
+ <li>The intended resource supports the Message Delivery Receipts protocol
but the recipient's server delivers the content message to another resource
that does not support the Message Delivery Receipts protocol.</li>
<li>The recipient's client receives the content message but experiences a
malfunction before generating an ack message.</li>
<li>The recipient returns an ack message but the ack message is lost on
the way back from the recipient to the sender (e.g., because of connectivity
issues or software failures at any hop).</li>
<li>The recipient simply does not wish to return a receipt for the content
message.</li>
</ul>
<p>Because of these significant limitations, this protocol does not provide
complete or even partial reliability or guaranteed delivery. Therefore, the
sender SHOULD NOT impute any meaning to the fact that it has not received an
ack message, unless it has established with the recipient that receipt requests
will be honored; however, methods for doing so are out of scope for this
specification and it is NOT RECOMMENDED to take any particular action (such as
resending the content message) without such methods. <note>This protocol merely
provides a building block that could be used in conjunction with other
protocols to asymptotically approach the eventual goal of messaging reliability
and guaranteed delivery.</note></p>
<p>Because it is possible for a given content message to be delivered to
multiple XMPP resources controlled by the recipient, the sender of the content
message needs to be prepared to receive multiple ack messages.</p>
+ <p>Finally, this protocol does not enable the sender to know that the
intended recipient has read the message or understood the message (if the
intended recipient is a human being), that the intended recipient has processed
the message (if the intended recipient is a bot or other automated system),
that an end user client has presented the message to a human user (if any),
etc. This protocol provides delivery receipts only, not notifications about
presentation, processing, reading, understanding, or any other action related
to a message other than delivery to a client of some kind.</p>
</section1>
<section1 topic='When to Request Receipts' anchor='when'>
<p>A sender <em>could</em> request receipts on any non-error content message
(chat, groupchat, headline, or normal) no matter if the recipient's address is
a bare JID &LOCALBARE; or a full JID &LOCALFULL;. Whether it is
<em>appropriate</em> or <em>advisable</em> to do so it another question. This
section provides recommendations about when and when not to request receipts,
and what results to expect in each scenario.</p>
<section2 topic='Bare JID' anchor='when-bare'>
- <p>If the sender knows only the recipient's bare JID, it cannot cannot
determine (via &xep0030; or &xep0115;) whether the intended recipient supports
the Message Receipts protoocl. In this case, the sender MAY request a receipt
when sending a content message of type "chat", "headline", or "normal" to the
recipient's bare JID. However, the sender MUST NOT depend on receiving an ack
message in reply.</p>
+ <p>If the sender knows only the recipient's bare JID, it cannot cannot
determine (via &xep0030; or &xep0115;) whether the intended recipient supports
the Message Delivery Receipts protoocl. In this case, the sender MAY request a
receipt when sending a content message of type "chat", "headline", or "normal"
to the recipient's bare JID. However, the sender MUST NOT depend on receiving
an ack message in reply.</p>
</section2>
<section2 topic='Full JID' anchor='when-full'>
- <p>If the sender knows a full JID for the recipient (e.g., via presence),
it SHOULD attempt to determine (via service disco or entity capabilities)
whether the client at that full JID supports the Message Receipts protocol
before attempting to request receipts.</p>
- <p>If the sender determines that the recipient's client does not support
the Message Receipts protocol then it SHOULD NOT request a receipt when sending
a content message to that full JID and MUST NOT depend on receiving an ack
message.</p>
- <p>If the sender determines that the recipient's client supports the
Message Receipts protocol then it MAY request a receipt when sending a content
message of type "chat", "headline", or "normal" to that full JID. However, even
in this case the sender SHOULD NOT depend on receiving an ack message.</p>
+ <p>If the sender knows a full JID for the recipient (e.g., via presence),
it SHOULD attempt to determine (via service disco or entity capabilities)
whether the client at that full JID supports the Message Delivery Receipts
protocol before attempting to request receipts.</p>
+ <p>If the sender determines that the recipient's client does not support
the Message Delivery Receipts protocol then it SHOULD NOT request a receipt
when sending a content message to that full JID and MUST NOT depend on
receiving an ack message.</p>
+ <p>If the sender determines that the recipient's client supports the
Message Delivery Receipts protocol then it MAY request a receipt when sending a
content message of type "chat", "headline", or "normal" to that full JID.
However, even in this case the sender SHOULD NOT depend on receiving an ack
message.</p>
</section2>
<section2 topic='Groupchat' anchor='when-groupchat'>
<p>It is NOT RECOMMENDED to request a receipt when sending a content
message of type "groupchat" in a &xep0045; room because the logic for
determining when a content message is truly "received" by all of the room
occupants is complex, and because the sender would receive one ack message from
each occupant of the room, thus significantly increasing the number of stanzas
sent through the room.</p>
@@ -148,7 +149,7 @@
</section1>
<section1 topic='Determining Support' anchor='disco'>
- <p>If an entity supports message receipts, it MUST report that by including
a &xep0030; feature of "urn:xmpp:receipts" in response to disco#info
requests:</p>
+ <p>If an entity supports the Message Delivery Receipts protocol, it MUST
report that by including a &xep0030; feature of "urn:xmpp:receipts" in response
to disco#info requests:</p>
<example caption="Initial Service Discovery information request"><![CDATA[
<iq from='[email protected]/westminster'
id='disco1'
@@ -171,13 +172,13 @@
</section1>
<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 dedicated protocol extension qualified
by the 'urn:xmpp:receipts' namespace.</p>
+ <p>In order to make it possible for senders to request and for recipients to
generate message delivery receipts, we define a dedicated protocol extension
qualified by the 'urn:xmpp:receipts' namespace.</p>
<p>There are two allowable elements in this namespace:</p>
<ul>
- <li><request/> -- included in a content message by a sending entity
that wishes to know if the content message has been received.</li>
- <li><received/> -- included in an ack message by a receiving entity
that wishes to inform the sending entity that the content message has been
received.</li>
+ <li><request/> -- included in a content message by a sending entity
that wishes to know if the content message has been received, i.e., delivered
to a client controlled by the intended recipient.</li>
+ <li><received/> -- included in an ack message by a receiving entity
that wishes to inform the sending entity that the content message has been
received, i.e., delivered to a client controlled by the intended recipient.</li>
</ul>
- <p>Specifically, the receiving entity shall return an ack message containing
the <received/> extensino if it has received and processed the content
message. The term "processed" is to be understood as including 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 content message cannot be handled.</p>
+ <p>Specifically, the receiving entity shall return an ack message containing
the <received/> extensino if the content message has been delivered to a
client controlled by the intended recipient. In general, a client will return a
receipt only if the client has processed the content message (e.g., if the
client has presented the content message to a human user or has completed any
automated processing of the content message, such as generation of an error
response if the application determines that the content message cannot be
handled). However, the Message Delivery Receipts protocol does not provide
notification that a human user has read or understood the content message, that
an automated system has completed processed or acted upon the message, etc.</p>
<p>The following is an example of a content message that includes a request
for return receipt.</p>
<example caption='A content message with receipt requested'><![CDATA[
<message
@@ -189,8 +190,8 @@
</message>
]]></example>
<p class='box'>Note: A sender MUST include an 'id' attribute on every
content message that requests a receipt, so that the sender can properly track
ack messages.</p>
- <p>The recipient shall generate an ack message 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>
- <example caption='A message receipt'><![CDATA[
+ <p>The recipient shall generate an ack message if and only if (1) it
supports the Message Delivery Receipts protocol and (2) 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>
+ <example caption='A message delivery receipt'><![CDATA[
<message
from='[email protected]/throne'
id='bi29sg183b4v'
@@ -202,7 +203,7 @@
</section1>
<section1 topic='Security Considerations' anchor='security'>
- <p>It is possible for a recipient to leak its presence when returning
message receipts; therefore, a recipient SHOULD NOT return message receipts to
senders who are not otherwise authorized to view its presence.</p>
+ <p>It is possible for a recipient to leak its presence when returning
message delivery receipts; therefore, a recipient SHOULD NOT return message
delivery receipts to senders who are not otherwise authorized to view its
presence.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
smime.p7s
Description: S/MIME Cryptographic Signature
