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.

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.

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.

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.

This enables entities other than the main UI to send messages to contacts.

The Account through which to communicate. The contact to send the message to. 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.