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