[Telepathy-commits] [telepathy-spec/master] Messages, Text: explain the intended behaviour of Send vs Sent
Simon McVittie
simon.mcvittie at collabora.co.uk
Wed Oct 22 04:03:48 PDT 2008
If we allow Sent to be delayed (as implemented in Gabble MUCs) this allows
clients to see what actually happened (what other users saw) as opposed to
what we tried to make happen. If we need the other possible semantic we can
add a Sending signal later.
---
spec/Channel_Interface_Messages.xml | 61 ++++++++++++++++++++++++++--------
spec/Channel_Type_Text.xml | 39 ++++++++++++++++++----
2 files changed, 77 insertions(+), 23 deletions(-)
diff --git a/spec/Channel_Interface_Messages.xml b/spec/Channel_Interface_Messages.xml
index 570c90b..1c43e4d 100644
--- a/spec/Channel_Interface_Messages.xml
+++ b/spec/Channel_Interface_Messages.xml
@@ -490,6 +490,17 @@ USA.</p>
to the server and the MessageSent signal is emitted. A corresponding
Sent signal on the Text interface MUST also be emitted.</p>
+ <p>This method MUST return before the MessageSent signal is
+ emitted.</p>
+
+ <tp:rationale>
+ <p>This means that the process sending the message is the first
+ to see the <tp:type>Sent_Message_Token</tp:type>, and can
+ relate the message to the corresponding
+ <tp:member-ref>MessageSent</tp:member-ref> signal by comparing
+ message tokens (if supported by the protocol).</p>
+ </tp:rationale>
+
<p>If this method fails, message submission to the server has failed
and no signal on this interface (or the Text interface) is
emitted.</p>
@@ -550,28 +561,48 @@ USA.</p>
</tp:flags>
<signal name="MessageSent" tp:name-for-bindings="Message_Sent">
- <tp:docstring>
- Signals that a message has been submitted for sending. This
- MUST be emitted exactly once per emission of the Sent signal on the
- Text interface.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Signals that a message has been submitted for sending. This
+ MUST be emitted exactly once per emission of the Sent signal on the
+ Text interface.</p>
+
+ <tp:rationale>
+ <p>This signal allows a process that is not the caller of
+ SendMessage to log sent messages. The double signal-emission
+ means that clients can safely follow the following rule:
+ if the channel has the Messages interface, listen for
+ Messages.MessageSent only; otherwise, listen for Text.Sent
+ only.</p>
+ </tp:rationale>
+
+ <p>Emission of this signal MAY be delayed until some time after
+ SendMessage returns, in order to reflect more accurately how
+ other contacts will see the message.</p>
<tp:rationale>
- This signal allows a process that is not the caller of
- SendMessage to log sent messages. The double signal-emission
- means that clients can safely follow the following rule:
- if the channel has the Messages interface, listen for
- Messages.MessageSent only; otherwise, listen for Text.Sent only.
+ <p>For instance, XMPP multi-user chat imposes a total ordering
+ on messages, and echoes a user's own messages back to them
+ so they can see where the message appears in that ordering.
+ An XMPP connection manager might delay emission of MessageSent
+ until the echo arrives.</p>
</tp:rationale>
</tp:docstring>
<arg type="aa{sv}" tp:type="Message_Part[]" name="Content">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
- The message content (see <tp:type>Message_Part</tp:type> for full
- details). If the message that was passed to SendMessage has a
- formatted text part that the connection manager recognises, but no
- text/plain alternative, the CM MUST use the formatted text part to
- generate a text/plain alternative which is also included in this
- signal argument.
+ <p>The message content (see <tp:type>Message_Part</tp:type> for full
+ details). If the message that was passed to SendMessage has a
+ formatted text part that the connection manager recognises, but no
+ text/plain alternative, the CM MUST use the formatted text part to
+ generate a text/plain alternative which is also included in this
+ signal argument.</p>
+
+ <p>If the connection manager can predict that the message will be
+ altered during transmission, this argument SHOULD reflect what
+ other contacts will receive, rather than being a copy of the
+ argument to SendMessage (if the message is truncated,
+ formatting or alternatives are dropped, etc., then the edited
+ version SHOULD appear in this signal).</p>
</tp:docstring>
</arg>
diff --git a/spec/Channel_Type_Text.xml b/spec/Channel_Type_Text.xml
index 205dbc0..5820274 100644
--- a/spec/Channel_Type_Text.xml
+++ b/spec/Channel_Type_Text.xml
@@ -168,11 +168,19 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
The message to send
</tp:docstring>
</arg>
- <tp:docstring>
- Request that a message be sent on this channel. When the message has
- been submitted for delivery, this method will return and the Sent
- signal will be emitted. If the message cannot be submitted for
- delivery, the method returns an error and no signal is emitted.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Request that a message be sent on this channel. When the message has
+ been submitted for delivery, this method will return and the Sent
+ signal will be emitted. If the message cannot be submitted for
+ delivery, the method returns an error and no signal is emitted.</p>
+
+ <p>This method SHOULD return before the Sent signal is
+ emitted.</p>
+
+ <tp:rationale>
+ <p>When a Text channel implements the Messages interface, that
+ "SHOULD" becomes a "MUST".</p>
+ </tp:rationale>
</tp:docstring>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
@@ -265,11 +273,26 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</arg>
<arg name="Text" type="s">
<tp:docstring>
- The text of the message
+ The text of the message. If the message was, or will be, altered
+ during transmission, this argument SHOULD reflect what other
+ contacts will receive rather than being a copy of the argument
+ to Send.
</tp:docstring>
</arg>
- <tp:docstring>
- Signals that a message has been submitted for sending.
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>Signals that a message has been submitted for sending.</p>
+
+ <p>Emission of this signal MAY be delayed until some time after
+ SendMessage returns, in order to reflect more accurately how
+ other contacts will see the message.</p>
+
+ <tp:rationale>
+ <p>For instance, XMPP multi-user chat imposes a total ordering
+ on messages, and echoes a user's own messages back to them
+ so they can see where the message appears in that ordering.
+ An XMPP connection manager might delay emission of MessageSent
+ until the echo arrives.</p>
+ </tp:rationale>
</tp:docstring>
</signal>
--
1.5.6.5
More information about the Telepathy-commits
mailing list