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
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
|
<?xml version="1.0" ?>
<node name="/Connection_Interface_Capabilities" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
<tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright>
<tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright>
<tp:copyright> Copyright (C) 2006 INdT </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.Connection.Interface.Capabilities">
<tp:requires interface="org.freedesktop.Telepathy.Connection"/>
<tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities"/>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>An interface for connections where it is possible to know what channel
types may be requested before the request is made to the connection
object. Each capability represents a commitment by the connection
manager that it will ordinarily be able to create a channel when given
a request with the given type and handle.</p>
<p>Capabilities pertain to particular contact handles, and represent
activities such as having a text chat or a voice call with the user.
The activities are represented by the D-Bus interface name of the
channel type for that activity.</p>
<p>The generic capability flags are defined by
<tp:type>Connection_Capability_Flags</tp:type>.</p>
<p>In addition, channel types may have type specific capability flags of
their own, which are described in the documentation for each channel
type.</p>
<p>This interface also provides for user interfaces notifying the
connection manager of what capabilities to advertise for the user. This
is done by using the
<tp:member-ref>AdvertiseCapabilities</tp:member-ref> method, and deals
with the
interface names of channel types and the type specific flags pertaining
to them which are implemented by available client processes.</p>
</tp:docstring>
<tp:changed version="0.17.8">Previously, this interface
also expressed capabilities of the connection itself, indicating what
sorts of channels could be requested (for instance, the ability to
open chatroom lists or chatrooms). However, this was never very
well-defined or consistent, and as far as we know it was never
implemented correctly. This usage is now deprecated.</tp:changed>
<tp:deprecated version="0.19.8">Client implementations SHOULD use <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Connection.Interface">ContactCapabilities</tp:dbus-ref>
instead.</tp:deprecated>
<tp:changed version="0.19.8">Connection managers implementing
Capabilities MUST implement ContactCapabilities too.</tp:changed>
<tp:flags name="Connection_Capability_Flags"
value-prefix="Connection_Capability_Flag" type="u">
<tp:flag suffix="Create" value="1">
<tp:docstring>
The given channel type and handle can be given to <tp:dbus-ref
namespace="org.freedesktop.Telepathy.Connection">RequestChannel</tp:dbus-ref>
to create a new channel of this type.
</tp:docstring>
</tp:flag>
<tp:flag suffix="Invite" value="2">
<tp:docstring>
The given contact can be invited to an existing channel of this type.
</tp:docstring>
</tp:flag>
</tp:flags>
<tp:struct name="Capability_Pair" array-name="Capability_Pair_List">
<tp:docstring>A pair (channel type, type-specific flags) as passed to
<tp:member-ref>AdvertiseCapabilities</tp:member-ref> on the
Capabilities interface.</tp:docstring>
<tp:member type="s" tp:type="DBus_Interface" name="Channel_Type"/>
<tp:member type="u" name="Type_Specific_Flags"/>
</tp:struct>
<tp:struct name="Contact_Capability" array-name="Contact_Capability_List">
<tp:docstring>A struct (contact handle, channel type, generic flags,
type-specific flags) representing a capability posessed by a contact,
as returned by <tp:member-ref>GetCapabilities</tp:member-ref> on the
Capabilities interface.</tp:docstring>
<tp:member type="u" tp:type="Contact_Handle" name="Handle"/>
<tp:member type="s" tp:type="DBus_Interface" name="Channel_Type"/>
<tp:member type="u" tp:type="Connection_Capability_Flags"
name="Generic_Flags"/>
<tp:member type="u" name="Type_Specific_Flags"/>
</tp:struct>
<tp:struct name="Capability_Change" array-name="Capability_Change_List">
<tp:docstring>A struct (contact handle, channel type, old generic flags,
new generic flags, old type-specific flags, new type-specific flags)
representing a change to one of a contact's capabilities, as seen in the
<tp:member-ref>CapabilitiesChanged</tp:member-ref> signal on the
Capabilities interface.</tp:docstring>
<tp:member type="u" tp:type="Contact_Handle" name="Handle"/>
<tp:member type="s" tp:type="DBus_Interface" name="Channel_Type"/>
<tp:member type="u" tp:type="Connection_Capability_Flags"
name="Old_Generic_Flags"/>
<tp:member type="u" tp:type="Connection_Capability_Flags"
name="New_Generic_Flags"/>
<tp:member type="u" name="Old_Type_Specific_Flags"/>
<tp:member type="u" name="New_Type_Specific_Flags"/>
</tp:struct>
<method name="AdvertiseCapabilities"
tp:name-for-bindings="Advertise_Capabilities">
<arg direction="in" name="Add" type="a(su)" tp:type="Capability_Pair[]">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
An array of structures containing:
<ul>
<li>a string channel type</li>
<li>a bitwise OR of type specific capability flags</li>
</ul>
</tp:docstring>
</arg>
<arg direction="in" name="Remove" type="as" tp:type="DBus_Interface[]">
<tp:docstring>
An array of D-Bus interface names of channel types to remove
</tp:docstring>
</arg>
<arg direction="out" type="a(su)" tp:type="Capability_Pair[]"
name="Self_Capabilities">
<tp:docstring>
An array of structures describing the current capabilities containing:
<ul>
<li>a string channel type</li>
<li>a bitwise OR of type specific capability flags</li>
</ul>
</tp:docstring>
</arg>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Used by user interfaces to indicate which channel types they are able
to handle on this connection. Because these may be provided by
different client processes, this method accepts channel types to add
and remove from the set already advertised on this connection. The type
of advertised capabilities (create versus invite) is protocol-dependent
and hence cannot be set by the this method. In the case of a client
adding an already advertised channel type but with new channel type
specific flags, the connection manager should simply add the new flags
to the set of advertised capabilities.</p>
<p>Upon a successful invocation of this method, the
<tp:member-ref>CapabilitiesChanged</tp:member-ref>
signal will be emitted for the user's own handle ( <tp:dbus-ref
namespace="org.freedesktop.Telepathy">Connection.GetSelfHandle</tp:dbus-ref>)
by the connection manager to indicate the changes
that have been made. This signal should also be monitored to ensure
that the set is kept accurate - for example, a client may remove
capabilities or type specific capability flags when it exits
which are still provided by another client.</p>
<p>On connections managed by the <tp:dbus-ref
namespace="org.freedesktop.Telepathy">ChannelDispatcher</tp:dbus-ref>,
this method SHOULD NOT be used by clients other than the
ChannelDispatcher itself.</p>
</tp:docstring>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
</tp:possible-errors>
</method>
<signal name="CapabilitiesChanged"
tp:name-for-bindings="Capabilities_Changed">
<arg name="Caps" type="a(usuuuu)" tp:type="Capability_Change[]">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
An array of structures containing:
<ul>
<li>an integer handle representing the contact</li>
<li>a string channel type</li>
<li>a bitwise OR of the contact's old generic capability flags</li>
<li>a bitwise OR of the contact's new generic capability flags</li>
<li>a bitwise OR of the contact's old type specific capability flags</li>
<li>a bitwise OR of the contact's new type specific capability flags</li>
</ul>
</tp:docstring>
</arg>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Announce that there has been a change of capabilities on the
given handle.</p>
<p>If the handle is zero, the capabilities refer to the connection
itself, in some poorly defined way. This usage is deprecated and
clients should ignore it.</p>
</tp:docstring>
</signal>
<method name="GetCapabilities" tp:name-for-bindings="Get_Capabilities">
<arg direction="in" name="Handles" type="au" tp:type="Contact_Handle[]">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>An array of contact handles for this connection.</p>
<p>This may include zero, which originally meant a query for
capabilities available on the connection itself. This usage
is deprecated; clients SHOULD NOT do this, and connection managers
SHOULD proceed as though zero had not been present in this
list.</p>
</tp:docstring>
</arg>
<arg direction="out" type="a(usuu)" tp:type="Contact_Capability[]"
name="Contact_Capabilities">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
An array of structures containing:
<ul>
<li>an integer handle representing the contact</li>
<li>a string channel type</li>
<li>a bitwise OR of generic capability flags for the type</li>
<li>a bitwise OR of type specific capability flags for the type</li>
</ul>
</tp:docstring>
</arg>
<tp:docstring>
Returns an array of capabilities for the given contact handles.
</tp:docstring>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
<tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
<tp:docstring>
The handle does not represent a contact and is not zero
</tp:docstring>
</tp:error>
<tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
</tp:possible-errors>
</method>
<tp:contact-attribute name="caps"
type="a(usuu)" tp:type="Contact_Capability[]">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The same structs that would be returned by
<tp:member-ref>GetCapabilities</tp:member-ref>
(all of them will redundantly have the contact's handle as the
first member). Omitted from the result if the contact's capabilities
are not known; present in the result as an empty array if the
contact is known to have no capabilities at all.</p>
</tp:docstring>
</tp:contact-attribute>
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
|
