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
255
|
# Service Profiles
## Synopsis
Service Profiles are intended to describe variants of the basic protocols supported by telepathy CMs (Connection Managers): An example of this would be Google Talk vs Facebook chat vs Jabber/XMPP - Google Talk is a specific case of XMPP with well-known capabilities, quirks and settings, and Facebook chat is a subset of the standard XMPP offering.
Since there is a lot of common content/use overlap between Telepathy profiles and libaccounts services, the intention here is to describe a single file format that can and will be shared by both.
A service is uniquely identified by its name: When there is more than one possible choice of CM for a protocol, the preferred CM on any given platform is allowed to name its service profile based on the name of the service alone, and any other CMs profiles that represent the service should be named by prepending the CM name to the service name, separated by a dash '-'.
---
## Details
### XMLNS Namespace
The XMLNS for service profiles is [[http://telepathy.freedesktop.org/wiki/service-profile-v1|http://telepathy.freedesktop.org/wiki/service-profile-v1]] A parser/reader/user of a service profile is expected to ignore (for telepathy purposes) any attributes or tags not in this namespace - other users of the file (such as libaccounts) which have their own information storage requirements should use a different namespace for any tags or attributes they add to the service profile file.
A service profile is expected to provide the following information:
### service
[[!format txt """
<service xmlns="http://telepathy.freedesktop.org/wiki/service-profile-v1"
id="google-talk"
type="IM"
provider="google"
manager="gabble"
protocol="jabber"
icon="gtalk-icon">
"""]]
#### id
**mandatory**
The unique name of the service. The preferred CM on a given platform is allowed to have a profile identified by service alone (eg "google-talk").
Any other CMs on the platform should be named <CM-name>-<service>
Examples: google-talk, haze-google-talk
#### type
**mandatory**
The type of the service: In general, services of interest to both libaccounts and telepathy should be of type 'IM': Other service types exist but are unlikely to affect telepathy in any way
#### manager
**mandatory**
The name of the CM (connection manager)
Examples: gabble, haze
#### protocol
**mandatory**
The standard telepathy name for the protocol over which this service is provided.
Examples: jabber
#### provider
**optional**
The name of the vendor/organisation/provider who actually runs the service to which this profile applies.
Examples: google, facebook
#### icon
**optional**
The base of the icon name for this service (to be looked for in the standard locations for icons used by the rest of the framework). Not explected to include either the type extension or the XxY size information, as these are considered to be entirely the domain of the UI.
Examples: gtalk-icon, fb-icon
### name
**mandatory**
Human-readable name (possibly including required branding and so forth) for the service in question
[[!format txt """
<name>Google``Talk™</name>
"""]]
### parameters
**optional**
The CM parameters which describe the service: These can be mandatory, in which case the user shold not be allowed to alter them by the UI, as they define the service (google talk accounts _must_ connect to the actual google server, for example) or optional, in which case they merely specify defaults ehich may differ from the CM's defaults.
These parameters are typed (with dbus types), so that libaccounts and telepathy can share the information. It is considered an error for the type of a parameter to differ from the type specified by the CM, although parsers are not required to enforce this (as they may be used in a context where the CM is unavailable and cannot be queried)
Examples:
* server, port, old-ssl (facebook, mandatory)
* fallback-conference-server (google, optional)
[[!format txt """
<parameters>
<parameter name="server" type="s" mandatory="1">talk.google.com</parameter>
<parameter name="port" type="u" mandatory="1">5223</parameter>
<parameter name="old-ssl" type="b" mandatory="1"
label="Use old-style SSL">1</parameter>
<parameter name="fallback-conference-server">conference.jabber.org</parameter>
</parameters>
"""]]
The parameter tag has the following defined attributes:
* name
* string: The CM's name for this is (necessarily) canonical
* type
* string: (generally one character): the DBus type of the parameter
* label
* string: the human-readable label (if any) for the parameter
* mandatory
* boolean: (0 or 1, default 0): whether the value is fixed for this particular service
### presences
**optional**
A service can support a subset of the presences supported by a given protocol, and/or have service specific names for the standard presences.
A specified presence in this section is considered to override any properties (label, icon, [default] extended message) of the standard entry for said presence in the CM.
A presence may also be disabled, in which case the UI should not offer it as a choice to the user at all, as the service is not considered to support it.
Examples:
[[!format txt """
<presences allow-others="1">
<presence id="available" label="Online" icon="gtalk-online"/>
<presence id="offline" label="Offline"/>
<presence id="away" label="Gone"/>
<presence id="hidden" disabled="1"/>
</presences>
"""]]
The presences tag has the following attributes:
* allow-others
* boolean (0 or 1, default 0): whether the any standard CM presences not mentioned here are still supported
The presence tag supports the following attributes:
* id
* string: the telepathy presence id string
* label
* string: the label for this presence, if it differs from the CM default
* icon
* string: the service specific icon for this presence, if any
* message
* boolean: (0 or 1, default 0): if true, a user-defined text message can be attached to this presence
* disabled
* boolean (0 or 1, default 0): if true, this presence is not supported
### unsuported channel classes
**optional**
Some services do not support the full range of channels that the protocol & CM are (in general) capable of: This item lists those channel classes which are not available on the service.
Classes are defined (as in an ensure channel or create channel request) by a list of property/value pairs (an a{sv} in DBus terms):
Example:
[[!format txt """
<unsupported-channel-classes>
<!-- this service doesn't support text roomlists -->
<channel-class>
<property name="org.freedesktop.Telepathy.Channel.TargetHandleType"
type="u">3</property>
<property name="org.freedesktop.Telepathy.Channel.ChannelType"
type="s">org.freedesktop.Telepathy.Channel.Type.Text</property>
</channel-class>
<channel-class>
⋮
</channel-class>
</unsupported-channel-classes>
"""]]
The property tag has the following attributes:
* name
* string: the telepathy DBus property of the channel
* type
* string (generally one character): the [DBus] type of the property
## Example
[[!format txt """
<service xmlns="http://telepathy.freedesktop.org/wiki/service-profile-v1"
id="google-talk"
type="IM"
provider="google"
manager="gabble"
protocol="jabber"
icon="gtalk-icon">
<name>Google``Talk™</name>
<parameters>
<parameter name="server" type="s" mandatory="1">talk.google.com</parameter>
<parameter name="port" type="u" mandatory="1">5223</parameter>
<parameter name="old-ssl" type="b" mandatory="1"
label="Use old-style SSL">1</parameter>
<parameter name="fallback-conference-server">conference.jabber.org</parameter>
</parameters>
<parameters>
<parameter name="server" type="s" mandatory="1">profile.com</parameter>
<parameter name="port" type="u" mandatory="1">1111</parameter>
</parameters>
<presences allow-others="1">
<presence id="available" label="Online" icon="online"/>
<presence id="offline" label="Offline"/>
<presence id="away" label="Gone"/>
<presence id="hidden" disabled="1"/>
</presences>
<unsupported-channel-classes>
<!-- this service doesn't support text roomlists -->
<channel-class>
<property name="org.freedesktop.Telepathy.Channel.TargetHandleType"
type="u">3</property>
<property name="org.freedesktop.Telepathy.Channel.ChannelType"
type="s">org.freedesktop.Telepathy.Channel.Type.Text</property>
</channel-class>
</unsupported-channel-classes>
</service>
"""]]
|
