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
|
<?xml version="1.0" ?>
<node name="/Connection_Interface_Resources"
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
<tp:copyright>Copyright © 2010 Collabora Ltd.</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.Resources.DRAFT"
tp:causes-havoc="experimental">
<tp:added version="0.21.1">(draft 1)</tp:added>
<tp:requires interface="org.freedesktop.Telepathy.Connection"/>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>An interface on connections to show contact attributes for
specific resources of a contact, if the protocol supports
multiple resources. Resources are most common in XMPP, hence the
name of this interface, but they are also present in MSN, where
they are called points of presence.</p>
<p>When a client requests some attribute of a contact using its
handle on the connection, the CM uses an algorithm to choose the
most appropriate resource for the job. If there is only one
resource, then the choice is obvious. If, however, there is more
than one resource connected at any one time, the CM either
aggregates all appropriate information to return (in the case of
capabilities), or chooses one specific resource (in the case of
presence).</p>
<p>Resources in XMPP have names, and it can be extremely useful
for the user to be able to know which resources of a contact are
online, providing the names are human-readable. Before now,
resources have not been exposed in Telepathy, but this interface
attempts to change this.</p>
<p>When using this interface, it is a little like using the
<tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface"
>Contacts</tp:dbus-ref> interface, but only resource-specific
attributes are ever returned. The resource-specific contact
attributes are decided on by the CM, but XMPP's are listed
below:</p>
<ul>
<li><tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence/presence</tp:dbus-ref></li>
<li><tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">ContactCapabilities/capabilities</tp:dbus-ref></li>
<li><tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">ClientTypes/client-types</tp:dbus-ref></li>
</ul>
</tp:docstring>
<method name="GetResources" tp:name-for-bindings="Get_Resources">
<tp:docstring>
Return the resource information of the given contacts. If any
of the contact attributes for specific resources of the given
contacts' are not known return immediately without waiting for
a reply.
</tp:docstring>
<arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]">
<tp:docstring>
The contacts whose resource attributes should be returned.
</tp:docstring>
</arg>
<arg direction="out" name="Resources" type="a{ua{sa{sv}}}"
tp:type="Resources_Attributes_Map">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The contacts' resources and the contact attributes specific
to each resource. If contact attributes are not immediately
known, the behaviour is defined by the interface; the
attribute should either be omitted from the result or
replaced with a default value.</p>
<p>For every contact handle passed into this method, it is
guaranteed that there will be a key in the returned map
that corresponds to said handle. If there is no information
regarding the contact the resource information map will be
empty.</p>
</tp:docstring>
</arg>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
<tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
</tp:possible-errors>
</method>
<tp:enum name="Resources_Human_Readability" type="u">
<tp:enumvalue suffix="Never" value="0">
<tp:docstring>
The resource string is never human-readable.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Maybe" value="1">
<tp:docstring>
The resource string might be human-readable.
</tp:docstring>
</tp:enumvalue>
</tp:enum>
<property name="ResourcesHumanReadable" type="u" access="read"
tp:type="Resources_Human_Readability"
tp:name-for-bindings="Resources_Human_Readable">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Whether the resources returned from <tp:member-ref>GetResources</tp:member-ref>
are human readable or not.</p>
<p>If the connection manager knows that all resource names are
automatically generated, then the resource strings mean
nothing to the user. Showing these strings in the UI would
be confusing, so by setting this to
Resources_Human_Readability_Never, the UI is advised not to
show resources.</p>
<p>If on the other hand, all resources are set to nice names
(such as "office" or "home") then it might be wise to expose
these strings in the UI, so this property would be set to
Resources_Human_Readability_Maybe. This is the case in XMPP --
most resources are set in a way that the user can deduce some
information from them. The absence of an Always enum value is
because in the case of XMPP, the resource string could be
partially human-readable (as on Google Talk, where a resource
of "home" is changed by the server to a unique string like
"home_1234fdec") or not at all human-readable.</p>
</tp:docstring>
</property>
<signal name="ResourcesUpdated" tp:name-for-bindings="Resources_Updated">
<tp:docstring>
Emitted when a contact has a resource added or removed, or any
contact attribute for any resource changes.
</tp:docstring>
<arg name="Contact" type="u" tp:type="Contact_Handle">
<tp:docstring>
The contact.
</tp:docstring>
</arg>
<arg name="Resources" tp:type="Resource_Information_Map"
type="a{sa{sv}}">
<tp:docstring>
The contact's resource information. All resource information
is given, not just the details which have changed.
</tp:docstring>
</arg>
</signal>
<tp:mapping name="Resource_Information_Map">
<tp:docstring>
A map of a contact's resources to their resource-specific
information.
</tp:docstring>
<tp:member name="Key" type="s">
<tp:docstring>
<p>The name of the resource.</p>
</tp:docstring>
</tp:member>
<tp:member name="Contact_Attributes" type="a{sv}"
tp:type="Single_Contact_Attributes_Map">
<tp:docstring>
A map of contact attributes whose data is specific to this
resource.
</tp:docstring>
</tp:member>
</tp:mapping>
<tp:mapping name="Resources_Attributes_Map">
<tp:docstring>Mapping returned by
<tp:member-ref>GetResources</tp:member-ref>, representing a
collection of Contacts, their resources, and their
resource-specific contact attributes.</tp:docstring>
<tp:member type="u" tp:type="Contact_Handle" name="Contact">
<tp:docstring>
A contact.
</tp:docstring>
</tp:member>
<tp:member type="a{sa{sv}}" tp:type="Resource_Information_Map"
name="Resources">
<tp:docstring>
A map of the contact's resources to their resource-specific
information.
</tp:docstring>
</tp:member>
</tp:mapping>
<tp:contact-attribute name="resources" type="a{sa{sv}}"
tp:type="Resource_Information_Map">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The same mapping that would be returned by
<tp:member-ref>GetResources</tp:member-ref> for this contact.</p>
</tp:docstring>
</tp:contact-attribute>
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
|
