Interface ChannelDispatcher.Interface.Messages1

Interface Index (Compact) | Summary | Description | Methods

Methods

SendMessage (o: Account, s: Target_ID, aa{sv}: Message, u: Flags) → s: Token
Objects implementing this interface must also implement:

Description

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.

Rationale:

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

Methods

(Permalink)

SendMessage (o: Account, s: Target_ID, aa{sv}: Message, u: Flags) → s: Token

Parameters

  • Account — o
    • The Account through which to communicate.
  • Target_ID — s
    • The contact to send the message to.
  • Message — aa{sv} (Message_Part_List)
    • The parts of the message, the same as for Text.SendMessage.
  • Flags — u
    • Flags influencing how to send the message, the same as for Text.SendMessage.

Returns

  • Token — s
    • An opaque token equivalent to the one returned by Text.SendMessage.

Submit a message to the server for sending, like the Text.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.

Rationale:

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.TargetEntityType:
        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 Text.SendMessage methods, or signalled by the Failed signal.

Possible Errors

  • Disconnected
    • The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
    Rationale:
    The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  • Network Error
    • Raised when there is an error reading from or writing to the network.
  • Not Implemented
    • The connection manager does not implement Text channels that communicate with a named contact.
  • Invalid Handle
    • The Target_ID was not syntactically valid for the Account's protocol.
  • Invalid Handle
    • The requested message is malformed and cannot be sent.
  • Offline
    • The requested channel cannot be created because the target is offline.
  • Not Available
    • The requested channel cannot be created, but in principle, a similar request might succeed in future.
  • Permission Denied
    • The user is not permitted to perform the requested operation.