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
|
<?xml version="1.0" ?>
<node name="/Connection_Interface_Client_Types"
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
<tp:copyright>Copyright (C) 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.ClientTypes">
<tp:added version="0.21.1">(as stable API)</tp:added>
<tp:requires interface="org.freedesktop.Telepathy.Connection"/>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>An interface on connections to support protocols which allows users to
subscribe to the client types of their contacts.</p>
<p>One can connect to instant messaging networks on a huge variety of
devices, from PCs, to phones to consoles. It can be useful for users
to know what kind of device a contact is using so that he or she
can decide not to send that big file or start a video chat. This
interface exposes exactly this information for clients to display.</p>
<p>The client types are represented in strings, using the values
<a href="http://xmpp.org/registrar/disco-categories.html#client">
documented by the XMPP registrar</a> with some additional types
added for other protocols. A contact can set one or more client types
so this interface returns a list of strings to denote client types
for a contact. The well-known client types to be used are:</p>
<ul>
<li>bot</li>
<li>console (minimal non-GUI client used on dumb terminals or
text-only screens, <strong>not</strong> a games console)</li>
<li>handheld</li>
<li>pc</li>
<li>phone</li>
<li>web</li>
<!-- Excluding these two because there's been no conclusion regarding my mail
to standards@xmpp.org about adding these two to their list:
<li>sms (the client is not actually an instant messaging client
but all messages sent to this contact will be delivered as SMSs)</li>
<li>game (a gaming device)</li>
-->
</ul>
<p>If the empty list is given as the client types, this means that
details about the contact's client types are unknown. If there are
multiple resources of a contact online at one point in time, the
client types of the most available resource will be returned. In
other words, the returned client types are those for the resource whose
presence will be retreived using the
<tp:dbus-ref namespace="ofdT.Connection.Interface">SimplePresence</tp:dbus-ref>
interface.</p>
<p>For example, if a contact has two resources:</p>
<ul>
<li>their phone, with presence "available"; and</li>
<li>their pc, with presence "busy";</li>
</ul>
<p>then the methods in this interface will return an array (with
one element: "phone") as the client types because that is the more
available resource. If at some later time the contact's phone's presence
changes to "away", the
<tp:member-ref>ClientTypesUpdated</tp:member-ref> signal will
notify that the contact's client types attribute has changed from
["phone"] to ["pc"],
because "busy" is a more available presence than "away".</p>
</tp:docstring>
<tp:mapping name="Contact_Client_Types">
<tp:docstring>
A mapping from contact handle to client types.
</tp:docstring>
<tp:member type="u" tp:type="Contact_Handle" name="Contact">
<tp:docstring>
A contact.
</tp:docstring>
</tp:member>
<tp:member type="as" name="Client_Types" tp:type="Contact_Client_Type[]">
<tp:docstring>
The contact's client types as documented earlier in this interface.
</tp:docstring>
</tp:member>
</tp:mapping>
<method name="GetClientTypes" tp:name-for-bindings="Get_Client_Types">
<tp:docstring>
Return the client types of the given contacts, if they are
already known. If any of the given contacts' client types are
not known, request their current client types, but return
immediately without waiting for a reply; if a reply with a
non-empty client type array is later received for those
contacts, the
<tp:member-ref>ClientTypesUpdated</tp:member-ref> signal will
be emitted for them.
<tp:rationale>
This method is appropriate for "lazy" client type finding, for instance
displaying the client types (if available) of everyone in your contact
list.
</tp:rationale>
</tp:docstring>
<arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]">
<tp:docstring>
The contacts whose client types should be returned or signalled.
</tp:docstring>
</arg>
<arg direction="out" name="Client_Types" type="a{uas}"
tp:type="Contact_Client_Types">
<tp:docstring>
The contacts' client types, if already known. Contacts whose client
types are not already known are omitted from the mapping; contacts known
to have no client type information appear in the mapping with an empty
list.
</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>
<method name="RequestClientTypes" tp:name-for-bindings="Request_Client_Types">
<tp:docstring>
Return the current client types of the given contact. If necessary, make
a request to the server for up-to-date information, and wait for a
reply.
<tp:rationale>
This method is appropriate for use in a "Contact Information..."
dialog; it can be used to show progress information (while waiting
for the method to return), and can distinguish between various error
conditions.
</tp:rationale>
</tp:docstring>
<arg direction="in" name="Contact" type="u" tp:type="Contact_Handle">
<tp:docstring>
The contact whose client types should be returned.
</tp:docstring>
</arg>
<arg direction="out" name="Client_Types" type="as"
tp:type="Contact_Client_Type[]">
<tp:docstring>
The contact's client types. It MAY be empty, indicating that no client
type information was found.
</tp:docstring>
</arg>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
<tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
<tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
<tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied">
<tp:docstring>
The requested contact does not allow the local user to see their
client type information.
</tp:docstring>
</tp:error>
</tp:possible-errors>
</method>
<signal name="ClientTypesUpdated" tp:name-for-bindings="Client_Types_Updated">
<tp:docstring>
Emitted when a contact's client types change or become known.
</tp:docstring>
<arg name="Contact" type="u" tp:type="Contact_Handle">
<tp:docstring>
The contact.
</tp:docstring>
</arg>
<arg name="Client_Types" type="as" tp:type="Contact_Client_Type[]">
<tp:docstring>
The contact's client types, or an empty list to indicate that nothing
is known about the contact's client types.
</tp:docstring>
</arg>
</signal>
<tp:contact-attribute name="client-types" type="as"
tp:type="Contact_Client_Type[]">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The same mapping that would be returned by
<tp:member-ref>GetClientTypes</tp:member-ref> for this contact.
Omitted from the result if the contact's client types are not
known.</p>
</tp:docstring>
</tp:contact-attribute>
<tp:simple-type name="Contact_Client_Type" type="s"
array-name="Contact_Client_Type_List">
<tp:docstring>A string representing a single client type of a
contact.</tp:docstring>
</tp:simple-type>
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
|
