From 2e3793484f5086df0767407cb8ef464c77ab83f5 Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Thu, 10 Oct 2013 19:15:33 +0100 Subject: [PATCH 3/7] Complete CD.I.Messages1 --- spec/Channel_Dispatcher_Interface_Messages1.xml | 138 ++++++++++++++++++++++-- spec/all.xml | 1 + 2 files changed, 129 insertions(+), 10 deletions(-) diff --git a/spec/Channel_Dispatcher_Interface_Messages1.xml b/spec/Channel_Dispatcher_Interface_Messages1.xml index 61a398b..e768b55 100644 --- a/spec/Channel_Dispatcher_Interface_Messages1.xml +++ b/spec/Channel_Dispatcher_Interface_Messages1.xml @@ -1,8 +1,8 @@ - - Copyright (C) 2011 Collabora Ltd. + Copyright (C) 2011-2013 Collabora Ltd. Copyright (C) 2011 Nokia Corporation

This library is free software; you can redistribute it and/or @@ -22,9 +22,7 @@ - + name="org.freedesktop.Telepathy.ChannelDispatcher.Interface.Messages1"> @@ -44,12 +42,132 @@ - - + + + The Account + through which to communicate. + + + + + The contact to send the message to. + + - - + tp:type="Message_Part[]"> + + The parts of the message, the same as for Messages.SendMessage. + + + + + Flags influencing how to send the message, the same as for Messages.SendMessage. + + + + + An opaque token equivalent to the one returned by Messages.SendMessage. + + + +

Submit a message to the server for sending, like the + Messages.SendMessage + method.

+ +

If the Account is connected and a Text channel to the + Target_ID already exists, this method is equivalent to + sending the same message via that channel.

+ +

Otherwise, this method creates a channel (connecting the + Account if appropriate), sends the desired message, and + closes the channel as if via Channel.Close, without + acknowledging any messages received on that channel + during that time.

+ +

If any messages are received on that channel before it is + closed, a correct connection manager implementation will reopen + the channel when it is closed, resulting in those "rescued" messages + being processed by the system's normal Handler for text + channels. In particular, this deals with the situation where + a successful or failed delivery report is received + before the channel is closed.

+ + +

Expecting a trivial client (perhaps a send-only IRC bot, + or a simple SMS-sending API) to go through all those steps to + send a message seems somewhat unreasonable. Having this as a + method in the ChannelDispatcher lets it take some short-cuts if + required, and centralizes the implementation to reduce the risk of + mistakes that cause message loss.

+ + +

The ChannelDispatcher SHOULD support this method for any + connection manager that would accept channel requests of this + form:

+ + 
  {
+    …Channel.ChannelType:
+        …Channel.Type.Text,
+    …Channel.TargetHandleType:
+        Contact,
+    …Channel.TargetID:
+    Target_ID
+  }
+ +

However, if the connection manager provides additional APIs + (such as a way to open "send-only" channels), the + ChannelDispatcher MAY use those: it is not required to use + those exact request parameters.

+ +

This method may raise any error that would be raised by the + Requests.EnsureChannel + or Messages.SendMessage + methods, or signalled by the Failed + signal.

+ + + + + + + + The connection manager does not implement Text channels + that communicate with a named contact. + + + + + The Target_ID was not syntactically valid for the + Account's protocol. + + + + + The requested message is malformed and cannot be sent. + + + + + The requested channel cannot be created because the target is + offline. + + + + + The requested channel cannot be created, but in + principle, a similar request might succeed in future. + + + + diff --git a/spec/all.xml b/spec/all.xml index f41a700..616b880 100644 --- a/spec/all.xml +++ b/spec/all.xml @@ -300,6 +300,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + -- 1.8.4.rc3