diff options
Diffstat (limited to 'spec/Channel_Dispatcher_Interface_Messages1.xml')
| -rw-r--r-- | spec/Channel_Dispatcher_Interface_Messages1.xml | 175 |
1 files changed, 175 insertions, 0 deletions
diff --git a/spec/Channel_Dispatcher_Interface_Messages1.xml b/spec/Channel_Dispatcher_Interface_Messages1.xml new file mode 100644 index 000000000..e768b5549 --- /dev/null +++ b/spec/Channel_Dispatcher_Interface_Messages1.xml @@ -0,0 +1,175 @@ +<?xml version="1.0" ?> +<node name="/Channel_Dispatcher_Interface_Messages1" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + + <tp:copyright>Copyright (C) 2011-2013 Collabora Ltd.</tp:copyright> + <tp:copyright>Copyright (C) 2011 Nokia Corporation</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version.</p> + + <p>This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details.</p> + + <p>You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, + USA.</p> + </tp:license> + + <interface + name="org.freedesktop.Telepathy.ChannelDispatcher.Interface.Messages1"> + <tp:requires interface="org.freedesktop.Telepathy.ChannelDispatcher"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p> + This interface allows DBus clients to use the ChannelDispatcher to + send one-off text messages to a contact, identified by account and + target ID, without requiring the caller to handle channels or be + the primary message UI. + </p> + + <tp:rationale> + <p> + This enables entities other than the main UI to send messages + to contacts. + </p> + </tp:rationale> + </tp:docstring> + + <method name="SendMessage" tp:name-for-bindings="Send_Message"> + <arg direction="in" name="Account" type="o"> + <tp:docstring> + The <tp:dbus-ref namespace="ofdT">Account</tp:dbus-ref> + through which to communicate. + </tp:docstring> + </arg> + <arg direction="in" name="Target_ID" type="s"> + <tp:docstring> + The contact to send the message to. + </tp:docstring> + </arg> + <arg direction="in" name="Message" type="aa{sv}" + tp:type="Message_Part[]"> + <tp:docstring> + The parts of the message, the same as for <tp:dbus-ref + namespace="ofdT.Channel.Interface">Messages.SendMessage</tp:dbus-ref>. + </tp:docstring> + </arg> + <arg direction="in" name="Flags" type="u"> + <tp:docstring> + Flags influencing how to send the message, the same as for <tp:dbus-ref + namespace="ofdT.Channel.Interface">Messages.SendMessage</tp:dbus-ref>. + </tp:docstring> + </arg> + <arg direction="out" name="Token" type="s"> + <tp:docstring> + An opaque token equivalent to the one returned by <tp:dbus-ref + namespace="ofdT.Channel.Interface">Messages.SendMessage</tp:dbus-ref>. + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Submit a message to the server for sending, like the + <tp:dbus-ref namespace="ofdT.Channel.Interface">Messages.SendMessage</tp:dbus-ref> + method.</p> + + <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> + + <tp:rationale> + <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> + </tp:rationale> + + <p>The ChannelDispatcher SHOULD support this method for any + connection manager that would accept channel requests of this + form:</p> + + <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>: + <var>Target_ID</var> + }</pre> + + <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 + <tp:dbus-ref + namespace="ofdT.Connection.Interface">Requests.EnsureChannel</tp:dbus-ref> + or <tp:dbus-ref + namespace="ofdT.Channel.Interface">Messages.SendMessage</tp:dbus-ref> + methods, or signalled by the <tp:dbus-ref + namespace="ofdT.ChannelRequest">Failed</tp:dbus-ref> + signal.</p> + </tp:docstring> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented"> + <tp:docstring> + The connection manager does not implement Text channels + that communicate with a named contact. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + The <var>Target_ID</var> was not syntactically valid for the + <var>Account</var>'s protocol. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"> + <tp:docstring> + The requested message is malformed and cannot be sent. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.Offline"> + <tp:docstring> + The requested channel cannot be created because the target is + offline. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The requested channel cannot be created, but in + principle, a similar request might succeed in future. + </tp:docstring> + </tp:error> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + </tp:possible-errors> + </method> + + </interface> +</node> + |