[Telepathy-commits] [telepathy-spec/master] DeliveryReporting: move most of it into Messages
Simon McVittie
simon.mcvittie at collabora.co.uk
Tue Oct 28 11:10:30 PDT 2008
---
spec/Channel_Interface_Delivery_Reporting.xml | 207 ------------------------
spec/Channel_Interface_Messages.xml | 213 +++++++++++++++++++++++--
2 files changed, 203 insertions(+), 217 deletions(-)
diff --git a/spec/Channel_Interface_Delivery_Reporting.xml b/spec/Channel_Interface_Delivery_Reporting.xml
index ee4785e..c18bd42 100644
--- a/spec/Channel_Interface_Delivery_Reporting.xml
+++ b/spec/Channel_Interface_Delivery_Reporting.xml
@@ -45,213 +45,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
Channel_Text_Message_Type_Delivery_Report in the Text and Messages
interfaces. The message in the Text interface SHOULD have the
Non_Text_Content flag.</p>
-
- <p>Whenever a message of type Channel_Text_Message_Type_Delivery_Report
- is signalled for a delivery error report, Channel.Type.Text.SendError
- SHOULD also be emitted; whenever Channel.Type.Text.SendError is
- emitted by a channel which supports this interface, a message of type
- Channel_Text_Message_Type_Delivery_Report MUST also be emitted.</p>
-
- <p>The corresponding message in the Messages interface MUST contain
- "headers" for the delivery report, as specified below, in its
- first Message_Part.</p>
-
- <dl>
- <dt>interface (s - DBus_Interface, as defined in the Messages
- interface)</dt>
- <dd>MUST be the name of this interface.</dd>
-
- <dt>message-sender (u - Contact_Handle, as defined in the Messages
- interface)</dt>
- <dd>MUST be the intended recipient of the original message, if
- available (zero or omitted otherwise), even if the delivery report
- actually came from an intermediate server.</dd>
-
- <dt>message-type (u - Channel_Text_Message_Type, as defined in the
- Messages interface)</dt>
- <dd>MUST be Channel_Text_Message_Type_Delivery_Report.</dd>
-
- <dt>delivery-status (u - Delivery_Status)</dt>
- <dd>The status of the message. All delivery reports MUST contain
- this key in the first Message_Part.</dd>
-
- <dt>delivery-token (s - Sent_Message_Token)</dt>
-
- <dd>
- <p>An identifier for the message to which this delivery report
- refers. MUST NOT be an empty string. Omitted if not
- available.</p>
-
- <p>Clients may match this against the token produced by the
- SendMessage method and MessageSent signal on the Messages
- interface. A status report with no token could match any sent
- message, and a sent message with an empty token could match
- any status report. If multiple sent messages match, clients
- SHOULD use some reasonable heuristic.</p>
-
- <tp:rationale>
- In an ideal world, we could unambiguously match reports
- against messages; however, deployed protocols are not ideal,
- and not all reports and messages can be matched.
- </tp:rationale>
- </dd>
-
- <dt>delivery-error (u - Channel_Text_Send_Error)</dt>
- <dd>
- The reason for the failure. MUST be omitted if this was a
- successful delivery; SHOULD be omitted if it would be
- Channel_Text_Send_Error_Unknown.
- </dd>
-
- <dt>delivery-echo (aa{sv} - Message_Part[])</dt>
- <dd>
- <p>The message content, as defined by the Messages interface.
- Omitted if no content is available. Content MAY have been
- truncated, message parts MAY have been removed, and message
- parts MAY have had their content removed (i.e. the message part
- metadata is present, but the 'content' key is not).</p>
-
- <tp:rationale>
- Some protocols, like XMPP, echo the failing message back to
- the sender. This is sometimes the only way to match it
- against the sent message, so we include it here.
- </tp:rationale>
-
- <p>Unlike in the Messages interface, content not visible
- in the value for this key cannot be retrieved by another
- means, so the connection manager SHOULD be more
- aggressive about including (possibly truncated) message
- content in the 'content' key.</p>
-
- <tp:rationale>
- The Messages interface needs to allow all content to be
- retrieved, but in this interface, the content we provide is
- merely a hint; so some is better than none, and it doesn't
- seem worth providing an API as complex as Messages'
- GetPendingMessageContent for the echoed message.
- </tp:rationale>
- </dd>
-
- </dl>
-
- <p>The second and subsequent Message_Part dictionaries, if present,
- are a human-readable report from the IM service.</p>
-
- <p>It is an error for this interface to appear on channels of type
- other than Text, or on Text channels without the Messages interface.
- Clients MUST recover from this error by ignoring the presence
- of the DeliveryReporting interface.</p>
-
- <p>Clients MUST NOT attempt to send delivery reports using the
- SendMessage method in the Messages API, and connection managers
- MUST NOT allow this to be done. If support for sending delivery
- reports is later added, it will be part of this interface.</p>
-
- <p>Some example delivery reports in a Python-like syntax (in which
- arrays are indicated by [a, b] and dictionaries by {k1: v1, k2: v2})
- follow.</p>
-
- <dl>
- <dt>A minimal delivery report indicating permanent failure of the
- sent message whose token was
- <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code> for an unknown
- reason</dt>
- <dd><pre>
-[{
-# header
-'interface': 'org.freedesktop.Telepathy.Channel.Interface.DeliveryReporting',
-'message-sender': 123,
-'message-type': Channel_Text_Message_Type_Delivery_Report,
-'delivery-status': Delivery_Status_Permanently_Failed,
-'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
-}
-# no body
-]
-</pre></dd>
-
- <dt>A delivery report where the failed message is echoed back to the
- sender rather than being referenced by ID, and the failure reason
- is that this protocol cannot send messages to offline contacts
- such as the contact with handle 123</dt>
- <dd><pre>
-[{ # header
-'interface': 'org.freedesktop.Telepathy.Channel.Interface.DeliveryReporting',
-'message-sender': 123,
-'message-type': Channel_Text_Message_Type_Delivery_Report,
-'delivery-status': Delivery_Status_Temporarily_Failed,
-'delivery-error': Channel_Text_Send_Error_Offline,
-'delivery-echo':
- [{ # header of original message
- 'message-sender': 1,
- 'message-sent': 1210067943,
- },
- { # body of original message
- 'type': 'text/plain',
- 'content': 'Hello, world!',
- }]
- ],
-
-# no body
-]
-</pre></dd>
-
- <dt>A maximally complex delivery report: the server reports a bilingual
- human-readable failure message because the user sent a message
- "Hello, world!" with token
- <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code> to a contact
- with handle 123, but that handle represents a contact who does not
- actually exist</dt>
- <dd><pre>
-[{ # header
-'interface': 'org.freedesktop.Telepathy.Channel.Interface.DeliveryReporting',
-'message-sender': 123,
-'message-type': Channel_Text_Message_Type_Delivery_Report,
-'delivery-status': Delivery_Status_Permanently_Failed,
-'delivery-error': Channel_Text_Send_Error_Invalid_Contact,
-'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
-'delivery-echo':
- [{ # header of original message
- 'message-sender': 1,
- 'message-sent': 1210067943,
- },
- { # body of original message
- 'type': 'text/plain',
- 'content': 'Hello, world!',
- }]
- ],
-},
-{ # message from server (alternative in English)
-'alternative': '404',
-'type': 'text/plain',
-'lang': 'en',
-'content': 'I have no contact with that name',
-},
-{ # message from server (alternative in German)
-'alternative': '404'.
-'type': 'text/plain',
-'lang': 'de',
-'content', 'Ich habe keinen Kontakt mit diesem Namen',
-}
-]
-</pre></dd>
-
- <dt>A minimal delivery report indicating successful delivery
- of the sent message whose token was
- <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code></dt>
- <dd><pre>
-[{
-# header
-'interface': 'org.freedesktop.Telepathy.Channel.Interface.DeliveryReporting',
-'message-sender': 123,
-'message-type': Channel_Text_Message_Type_Delivery_Report,
-'delivery-status': Delivery_Status_Delivered,
-'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
-}
-# no body
-]
-</pre></dd>
-
- </dl>
</tp:docstring>
</interface>
diff --git a/spec/Channel_Interface_Messages.xml b/spec/Channel_Interface_Messages.xml
index e64c2d3..5b18ca6 100644
--- a/spec/Channel_Interface_Messages.xml
+++ b/spec/Channel_Interface_Messages.xml
@@ -36,10 +36,6 @@ USA.</p>
<li>any extra types of message we need in future</li>
</ul>
- <p>It also provides a hook for improved sent
- message status notification, to be used by the DeliveryReporting
- interface.</p>
-
<p>Although this specification supports formatted (rich-text)
messages with unformatted alternatives, implementations SHOULD NOT
attempt to send formatted messages until the Telepathy specification
@@ -440,6 +436,209 @@ USA.</p>
</dl>
</div>
+
+
+ <div>
+ <p>Delivery reports are also represented as messages, of type
+ Channel_Text_Message_Type_Delivery_Report, with the
+ Non_Text_Content flag in the Text interface.</p>
+
+ <p>Whenever a message of type
+ Channel_Text_Message_Type_Delivery_Report is signalled for a
+ delivery error report, Channel.Type.Text.SendError SHOULD also
+ be emitted; whenever Channel.Type.Text.SendError is emitted by a
+ channel which supports this interface, a message of type
+ Channel_Text_Message_Type_Delivery_Report MUST also be emitted.</p>
+
+ <p>The corresponding message in the Messages interface MUST contain
+ "headers" for the delivery report, as specified below, in its
+ first Message_Part.</p>
+
+ <dl>
+ <dt>message-sender (u - Contact_Handle as defined above)</dt>
+ <dd>MUST be the intended recipient of the original message, if
+ available (zero or omitted if the intended recipient is
+ unavailable or is not a contact, e.g. a chatroom), even if the
+ delivery report actually came from an intermediate server.</dd>
+
+ <dt>message-type (u - Channel_Text_Message_Type as defined
+ above)</dt>
+ <dd>MUST be Channel_Text_Message_Type_Delivery_Report.</dd>
+
+ <dt>delivery-status (u - Delivery_Status)</dt>
+ <dd>The status of the message. All delivery reports MUST contain
+ this key in the first Message_Part.</dd>
+
+ <dt>delivery-token (s - Sent_Message_Token)</dt>
+
+ <dd>
+ <p>An identifier for the message to which this delivery report
+ refers. MUST NOT be an empty string. Omitted if not
+ available.</p>
+
+ <p>Clients may match this against the token produced by the
+ SendMessage method and MessageSent signal. A status report
+ with no token could match any sent message, and a sent
+ message with an empty token could match any status report.
+ If multiple sent messages match, clients SHOULD use some
+ reasonable heuristic.</p>
+
+ <tp:rationale>
+ In an ideal world, we could unambiguously match reports
+ against messages; however, deployed protocols are not ideal,
+ and not all reports and messages can be matched.
+ </tp:rationale>
+ </dd>
+
+ <dt>delivery-error (u - Channel_Text_Send_Error)</dt>
+ <dd>
+ The reason for the failure. MUST be omitted if this was a
+ successful delivery; SHOULD be omitted if it would be
+ Channel_Text_Send_Error_Unknown.
+ </dd>
+
+ <dt>delivery-echo (aa{sv} - Message_Part[])</dt>
+ <dd>
+ <p>The message content, as defined by the Messages interface.
+ Omitted if no content is available. Content MAY have been
+ truncated, message parts MAY have been removed, and message
+ parts MAY have had their content removed (i.e. the message part
+ metadata is present, but the 'content' key is not).</p>
+
+ <tp:rationale>
+ Some protocols, like XMPP, echo the failing message back to
+ the sender. This is sometimes the only way to match it
+ against the sent message, so we include it here.
+ </tp:rationale>
+
+ <p>Unlike in the Messages interface, content not visible
+ in the value for this key cannot be retrieved by another
+ means, so the connection manager SHOULD be more
+ aggressive about including (possibly truncated) message
+ content in the 'content' key.</p>
+
+ <tp:rationale>
+ The Messages interface needs to allow all content to be
+ retrieved, but in this interface, the content we provide is
+ merely a hint; so some is better than none, and it doesn't
+ seem worth providing an API as complex as Messages'
+ GetPendingMessageContent for the echoed message.
+ </tp:rationale>
+ </dd>
+
+ </dl>
+
+ <p>The second and subsequent Message_Part dictionaries, if present,
+ are a human-readable report from the IM service.</p>
+
+ <p>Clients MUST NOT attempt to send delivery reports using the
+ SendMessage method in the Messages API, and connection managers
+ MUST NOT allow this to be done. If support for sending delivery
+ reports is later added, it will be part of this interface.</p>
+
+ <p>Some example delivery reports in a Python-like syntax (in which
+ arrays are indicated by [a, b] and dictionaries by {k1: v1, k2: v2})
+ follow.</p>
+
+ <dl>
+ <dt>A minimal delivery report indicating permanent failure of the
+ sent message whose token was
+ <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code> for an unknown
+ reason</dt>
+ <dd><pre>
+[{
+# header
+'message-sender': 123,
+'message-type': Channel_Text_Message_Type_Delivery_Report,
+'delivery-status': Delivery_Status_Permanently_Failed,
+'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
+}
+# no body
+]
+</pre></dd>
+
+ <dt>A delivery report where the failed message is echoed back to the
+ sender rather than being referenced by ID, and the failure reason
+ is that this protocol cannot send messages to offline contacts
+ such as the contact with handle 123</dt>
+ <dd><pre>
+[{ # header
+'message-sender': 123,
+'message-type': Channel_Text_Message_Type_Delivery_Report,
+'delivery-status': Delivery_Status_Temporarily_Failed,
+'delivery-error': Channel_Text_Send_Error_Offline,
+'delivery-echo':
+ [{ # header of original message
+ 'message-sender': 1,
+ 'message-sent': 1210067943,
+ },
+ { # body of original message
+ 'content-type': 'text/plain',
+ 'content': 'Hello, world!',
+ }]
+ ],
+
+# no body
+]
+</pre></dd>
+
+ <dt>A maximally complex delivery report: the server reports a
+ bilingual human-readable failure message because the user sent
+ a message "Hello, world!" with token
+ <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code> to a contact
+ with handle 123, but that handle represents a contact who does not
+ actually exist</dt>
+ <dd><pre>
+[{ # header
+'message-sender': 123,
+'message-type': Channel_Text_Message_Type_Delivery_Report,
+'delivery-status': Delivery_Status_Permanently_Failed,
+'delivery-error': Channel_Text_Send_Error_Invalid_Contact,
+'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
+'delivery-echo':
+ [{ # header of original message
+ 'message-sender': 1,
+ 'message-sent': 1210067943,
+ },
+ { # body of original message
+ 'content-type': 'text/plain',
+ 'content': 'Hello, world!',
+ }]
+ ],
+},
+{ # message from server (alternative in English)
+'alternative': '404',
+'content-type': 'text/plain',
+'lang': 'en',
+'content': 'I have no contact with that name',
+},
+{ # message from server (alternative in German)
+'alternative': '404'.
+'content-type': 'text/plain',
+'lang': 'de',
+'content', 'Ich habe keinen Kontakt mit diesem Namen',
+}
+]
+</pre></dd>
+
+ <dt>A minimal delivery report indicating successful delivery
+ of the sent message whose token was
+ <code>b9a991bd-8845-4d7f-a704-215186f43bb4</code></dt>
+ <dd><pre>
+[{
+# header
+'message-sender': 123,
+'message-type': Channel_Text_Message_Type_Delivery_Report,
+'delivery-status': Delivery_Status_Delivered,
+'delivery-token': 'b9a991bd-8845-4d7f-a704-215186f43bb4',
+}
+# no body
+]
+</pre></dd>
+
+ </dl>
+
+ </div>
</tp:docstring>
<tp:member name="Key" type="s">
@@ -474,12 +673,6 @@ USA.</p>
as matching on message content or timestamp (if available), or
assuming that the delivery report refers to the most recent message
with that ID.</p>
-
- <tp:rationale>
- <p>This is a hook for the DeliveryReporting interface,
- to avoid having to introduce a
- SendMultiPartMessageAndReturnToken method in that interface.</p>
- </tp:rationale>
</tp:docstring>
</tp:simple-type>
--
1.5.6.5
More information about the Telepathy-commits
mailing list