<?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>

