2
<node name="/Connection_Interface_Capabilities" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
3
<tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright>
4
<tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright>
5
<tp:copyright> Copyright (C) 2006 INdT </tp:copyright>
6
<tp:license xmlns="http://www.w3.org/1999/xhtml">
7
<p>This library is free software; you can redistribute it and/or
8
modify it under the terms of the GNU Lesser General Public
9
License as published by the Free Software Foundation; either
10
version 2.1 of the License, or (at your option) any later version.</p>
12
<p>This library is distributed in the hope that it will be useful,
13
but WITHOUT ANY WARRANTY; without even the implied warranty of
14
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15
Library General Public License for more details.</p>
17
<p>You should have received a copy of the GNU Lesser General Public
18
License along with this library; if not, write to the Free Software
19
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA</p>
21
<interface name="org.freedesktop.Telepathy.Connection.Interface.Capabilities">
22
<tp:requires interface="org.freedesktop.Telepathy.Connection"/>
23
<method name="AdvertiseCapabilities">
24
<arg direction="in" name="add" type="a(su)">
25
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
26
An array of structures containing:
28
<li>a string channel type</li>
29
<li>a bitwise OR of type specific capability flags</li>
33
<arg direction="in" name="remove" type="as">
35
An array of D-Bus interface names of channel types to remove
38
<arg direction="out" type="a(su)">
40
An array of structures describing the current capabilities containing:
42
<li>a string channel type</li>
43
<li>a bitwise OR of type specific capability flags</li>
47
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
48
<p>Used by user interfaces to indicate which channel types they are able
49
to handle on this connection. Because these may be provided by
50
different client processes, this method accepts channel types to add
51
and remove from the set already advertised on this connection. The type
52
of advertised capabilities (create versus invite) is protocol-dependent
53
and hence cannot be set by the this method. In the case of a client
54
adding an already advertised channel type but with new channel type
55
specific flags, the connection manager should simply add the new flags
56
to the set of advertised capabilities.</p>
58
<p>Upon a successful invocation of this method, the CapabilitiesChanged
59
signal will be emitted for the user's own handle (as returned by
60
GetSelfHandle) the by the connection manager to indicate the changes
61
that have been made. This signal should also be monitored to ensure
62
that the set is kept accurate - for example, a client may remove
63
capabilities or type specific capability flags when it exits
64
which are still provided by another client.</p>
67
<tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
68
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
71
<signal name="CapabilitiesChanged">
72
<arg name="caps" type="a(usuuuu)">
73
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
74
An array of structures containing:
76
<li>an integer handle representing the contact</li>
77
<li>a string channel type</li>
78
<li>a bitwise OR of the contact's old generic capability flags</li>
79
<li>a bitwise OR of the contact's new generic capability flags</li>
80
<li>a bitwise OR of the contact's old type specific capability flags</li>
81
<li>a bitwise OR of the contact's new type specific capability flags</li>
86
Announce that there has been a change of capabilities on the
87
given handle, or on the connection itself if the handle is zero.
90
<method name="GetCapabilities">
91
<arg direction="in" name="handles" type="au">
93
An array of contact handles for this connection, or zero to query capabilities available on the connection itself
96
<arg direction="out" type="a(usuu)">
98
An array of structures containing:
100
<li>an integer handle representing the contact</li>
101
<li>a string channel type</li>
102
<li>a bitwise OR of generic capability flags for the type</li>
103
<li>a bitwise OR of type specific capability flags for the type</li>
108
Returns an array of capabilities for the given contact handles, or
109
the connection itself (where handle is zero).
112
<tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
113
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
114
<tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
116
The handle does not represent a contact
119
<tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
120
</tp:possible-errors>
122
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
123
<p>An interface for connections where it is possible to know what channel
124
types may be requested before the request is made to the connection object.
125
Each capability represents a commitment by the connection manager that it
126
will ordinarily be able to create a channel when given a request with the
127
given type and handle.</p>
129
<p>Capabilities can pertain to a certain contact handle, representing
130
activities such as having a text chat or a voice call with the user, or can
131
be on the connection itself (where the handle will be zero), where they
132
represent the ability to create channels for chat rooms or activities such
133
as searching and room listing. The activities are represented by the D-Bus
134
interface name of the channel type for that activity.</p>
136
<p>The generic capability flags are defined by ConnectionCapabilityFlag.</p>
138
<p>In addition, channel types may have type specific capability flags of their
139
own, which are described in the documentation for each channel type.</p>
141
<p>This interface also provides for user interfaces notifying the connection
142
manager of what capabilities to advertise for the user. This is done by
143
using the AdvertiseCapabilities method, and deals with the interface names
144
of channel types and the type specific flags pertaining to them which are
145
implemented by available client processes.</p>
148
<tp:flags name="Connection_Capability_Flags" value-prefix="Connection_Capability_Flag">
149
<tp:flag suffix="Create" value="1">
151
The given channel type and handle can be given to RequestChannel to
152
create a new channel of this type.
155
<tp:flag suffix="Invite" value="2">
157
The given contact can be invited to an existing channel of this type.
162
<!-- vim:set sw=2 sts=2 et ft=xml: -->
added
removed
spec/Connection_Interface_Capabilities.xml
