summaryrefslogtreecommitdiff
path: root/spec/Channel_Dispatcher_Interface_Messages1.xml
blob: 9b92acbab3828edac039a94b0c2dbd768b71b7e5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
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="im.telepathy.v1.ChannelDispatcher.Interface.Messages1">
    <tp:requires interface="im.telepathy.v1.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="imt1">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="imt1.Channel.Type">Text.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="imt1.Channel.Type">Text.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="imt1.Channel.Type">Text.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="imt1.Channel.Type">Text.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="imt1">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="imt1.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="imt1">Channel.ChannelType</tp:dbus-ref>:
        …<tp:dbus-ref namespace="imt1">Channel.Type.Text</tp:dbus-ref>,
    …<tp:dbus-ref namespace="imt1">Channel.TargetHandleType</tp:dbus-ref>:
        <tp:value-ref type="Handle_Type">Contact</tp:value-ref>,
    …<tp:dbus-ref namespace="imt1">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="imt1.Connection.Interface">Requests.EnsureChannel</tp:dbus-ref>
          or <tp:dbus-ref
            namespace="imt1.Channel.Type">Text.SendMessage</tp:dbus-ref>
          methods, or signalled by the <tp:dbus-ref
            namespace="imt1.ChannelRequest">Failed</tp:dbus-ref>
          signal.</p>
      </tp:docstring>

      <tp:possible-errors>
        <tp:error name="im.telepathy.v1.Error.Disconnected"/>
        <tp:error name="im.telepathy.v1.Error.NetworkError"/>
        <tp:error name="im.telepathy.v1.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="im.telepathy.v1.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="im.telepathy.v1.Error.InvalidHandle">
          <tp:docstring>
            The requested message is malformed and cannot be sent.
          </tp:docstring>
        </tp:error>
        <tp:error name="im.telepathy.v1.Error.Offline">
          <tp:docstring>
            The requested channel cannot be created because the target is
            offline.
          </tp:docstring>
        </tp:error>
        <tp:error name="im.telepathy.v1.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="im.telepathy.v1.Error.PermissionDenied"/>
      </tp:possible-errors>
    </method>

  </interface>
</node>