Commit 4256042b authored by Simon McVittie's avatar Simon McVittie
parent 0f705e0f
<?xml version="1.0" ?>
<node name="/Channel_Dispatcher_Interface_Messages_Draft"
<node name="/Channel_Dispatcher_Interface_Messages1"
<tp:copyright>Copyright (C) 2011 Collabora Ltd.</tp:copyright>
<tp:copyright>Copyright (C) 2011-2013 Collabora Ltd.</tp:copyright>
<tp:copyright>Copyright (C) 2011 Nokia Corporation</tp:copyright>
<tp:license xmlns="">
<p>This library is free software; you can redistribute it and/or
......@@ -22,9 +22,7 @@
tp:causes-havoc="not yet final">
<tp:requires interface="org.freedesktop.Telepathy.ChannelDispatcher"/>
<tp:docstring xmlns="">
......@@ -44,12 +42,132 @@
<method name="SendMessage" tp:name-for-bindings="Send_Message">
<arg direction="in" name="Account" type="o"/>
<arg direction="in" name="TargetID" type="s"/>
<arg direction="in" name="Account" type="o">
The <tp:dbus-ref namespace="ofdT">Account</tp:dbus-ref>
through which to communicate.
<arg direction="in" name="Target_ID" type="s">
The contact to send the message to.
<arg direction="in" name="Message" type="aa{sv}"
<arg direction="in" name="Flags" type="u"/>
<arg direction="out" name="Token" type="s"/>
The parts of the message, the same as for <tp:dbus-ref
<arg direction="in" name="Flags" type="u">
Flags influencing how to send the message, the same as for <tp:dbus-ref
<arg direction="out" name="Token" type="s">
An opaque token equivalent to the one returned by <tp:dbus-ref
<tp:docstring xmlns="">
<p>Submit a message to the server for sending, like the
<tp:dbus-ref namespace="ofdT.Channel.Interface">Messages.SendMessage</tp:dbus-ref>
<p>If the <var>Account</var> is connected and a Text channel to the
<var>Target_ID</var> already exists, this method is equivalent to
sending the same message via that channel.</p>
<p>Otherwise, this method creates a channel (connecting the
Account if appropriate), sends the desired message, and
closes the channel as if via <tp:dbus-ref
namespace="ofdT">Channel.Close</tp:dbus-ref>, without
acknowledging any messages received on that channel
during that time.</p>
<p>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 <tp:dbus-ref
namespace="ofdT.Client">Handler</tp:dbus-ref> for text
channels. In particular, this deals with the situation where
a successful or failed delivery report is received
before the channel is closed.</p>
<p>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.</p>
<p>The ChannelDispatcher SHOULD support this method for any
connection manager that would accept channel requests of this
<pre> {
<tp:dbus-ref namespace="ofdT">Channel.ChannelType</tp:dbus-ref>:
<tp:dbus-ref namespace="ofdT">Channel.Type.Text</tp:dbus-ref>,
<tp:dbus-ref namespace="ofdT">Channel.TargetHandleType</tp:dbus-ref>:
<tp:value-ref type="Handle_Type">Contact</tp:value-ref>,
<tp:dbus-ref namespace="ofdT">Channel.TargetID</tp:dbus-ref>:
<p>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.</p>
<p>This method may raise any error that would be raised by the
or <tp:dbus-ref
methods, or signalled by the <tp:dbus-ref
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
<tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
<tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
The connection manager does not implement Text channels
that communicate with a named contact.
<tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
<tp:docstring xmlns="">
The <var>Target_ID</var> was not syntactically valid for the
<var>Account</var>'s protocol.
<tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
The requested message is malformed and cannot be sent.
<tp:error name="org.freedesktop.Telepathy.Error.Offline">
The requested channel cannot be created because the target is
<tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
The requested channel cannot be created, but in
principle, a similar request might succeed in future.
<tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
......@@ -300,6 +300,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
<xi:include href="Channel_Dispatcher.xml"/>
<xi:include href="Channel_Dispatcher_Interface_Messages1.xml"/>
<xi:include href="Channel_Dispatcher_Interface_Operation_List.xml"/>
<xi:include href="Channel_Dispatch_Operation.xml"/>
<xi:include href="Channel_Request.xml"/>
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment