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
|
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/doxbook/xml/4.3/docbookx.dtd">
<section id="service-file-format" xreflabel="service descriptions files">
<title>Service description file format</title>
<para>
Services for libaccounts-glib providers are described with a simple XML file.
An example for a hypothetical <literal>CoolProvider</literal> chat service is
shown below:
</para>
<example>
<title>Service description for CoolProvider chat service</title>
<programlisting><?xml version="1.0" encoding="UTF-8"?>
<service id="coolprovider-chat">
<type>IM</type>
<name>CoolProvider Chat</name>
<description>Chat with your cool friends</description>
<icon>coolprovider</icon>
<provider>coolprovider</provider>
<translations>coolprovider</translations>
<tags>
<tag>chat</tag>
</tags>
<template>
<group name="telepathy">
<setting name="manager">gabble</setting>
<setting name="protocol">jabber</setting>
</group>
<group name="auth">
<setting name="method">oauth2</setting>
<setting name="mechanism">user_agent</setting>
<group name="oauth2/user_agent">
<setting name="ClientId">ABCDEclient.ID</setting>
</group>
</group>
</template>
</service></programlisting>
</example>
<para>
The example service description describes a service called
<literal>coolprovider-chat</literal>, indicated by the
<sgmltag class="attribute" role="xml">id</sgmltag> attribute on the
<sgmltag class="element" role="xml">service</sgmltag> element. The
<sgmltag class="element" role="xml">type</sgmltag> element corresponds to the
service type. The <sgmltag class="element" role="xml">name</sgmltag> element
contains a human-readable version of the service name. The
<sgmltag class="element" role="xml">description</sgmltag> is a string that
describes the service in general. The
<sgmltag class="element" role="xml">icon</sgmltag> element specifies a themed
icon to represent the service. The
<sgmltag class="element" role="provider">provider</sgmltag> element must point
to the identifier of the provider which supports this service. The
<sgmltag class="element" role="xml">translations</sgmltag> element is used to
indicate the gettext translation domain for the name and description elements,
to be used by applications when showing those elements in a UI. The
<sgmltag class="element" role="xml">tags</sgmltag> element is a container of
<sgmltag class="element" role="xml">tag</sgmltag> elements, which are used to
describe the service in abstract terms. Finally, a
<sgmltag class="element" role="xml">template</sgmltag> element is a container
for <sgmltag class="element" role="xml">group</sgmltag> elements, which
themselves are containers of
<sgmltag class="element" role="xml">setting</sgmltag> elements. Settings stored
within the template are default settings for the service, which the
applications using the account may need in order to function correctly. The
default settings can be overriden, typically at run time during the account
configuration phase.
</para>
<section>
<title>Installation</title>
<para>
Service description filenames should end in
<filename class="extension">.service</filename> and be installed to
<filename class="directory">${prefix}/share/accounts/services</filename>,
which normally expands to
<filename class="directory">/usr/share/accounts/services</filename>. The path
can be queried with <command>pkg-config</command> by checking the
<varname>servicefilesdir</varname> variable of the libaccounts-glib
pkg-config file, for example:
</para>
<informalexample>
<programlisting>pkg-config --variable=servicefilesdir libaccounts-glib</programlisting>
</informalexample>
</section>
</section>
|
