Commit 7d3781bb authored by Brian Tarricone's avatar Brian Tarricone
Browse files

WIP

parent f7effe69
......@@ -40,6 +40,11 @@ configuration keys with the same names.
</para>
<!-- ##### ARG XfconfChannel:is-singleton ##### -->
<para>
</para>
<!-- ##### ARG XfconfChannel:property-base ##### -->
<para>
......
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<article id="xfconf-backends" lang="en">
<sect1 id="xfconf-backends-s">
<title>Configuration Backends</title>
<para>
Xfconf backends act as the actual configuration store. A backend might
write flat files to disk, XML files to disk, rows to a relational
database, entries to an LDAP server, or any other possible mechanism
desired to persistently store the data.
</para>
<para>
A backend must implement the <link linkend="XfconfBackendInterface">XfconfBackend
interface</link>, which is described in the API documentation.
</para>
<para>
The backend will have to deal with a variety of data types. While some
of these types are wrapped directly in the client library (e.g.,
xfconf_channel_set_uint64()), users of the library can also set other,
semi-arbitrary types, as well as array types.
</para>
<para>
So, the backend must be able to understand the following GTypes:
<programlisting>
G_TYPE_STRING
G_TYPE_UCHAR
G_TYPE_CHAR
G_TYPE_UINT
G_TYPE_INT
G_TYPE_UINT64
G_TYPE_INT64
G_TYPE_FLOAT
G_TYPE_DOUBLE
G_TYPE_BOOLEAN
</programlisting>
Note about 16-bit values: dbus-glib does not support sending 16-bit signed
and unsigned integers over D-Bus, even though libdbus does. For convenience,
libxfconf will take any 16-bit values it receives and convert them into
32-bit values before sending them to the daemon. From the daemon/backend
point of view, 16-bit values are simply not supported.
</para>
<para>
In addition, the backend must be able to handle arrays of arbitrary
types from the above list. A single array may hold multiple values
of the same type, or of different types. Because of this, an array is
sent over the bus as a GValue which holds a GPtrArray which holds an
array of GValues (which of course hold the actual values). The GType
of each value in the array must be checked, of course, as the array
elements may be of different types.
</para>
</sect1>
<sect1 id="xfconf-backend-perchannel-xml">
<title>Xfconf Perchannel-XML Backend</title>
<para>
The Per-channel XML configuration store backend is a simple
file-based backend that stores the properties and values for
each channel in its own file. The file is hierarchical and may
look something like this:
<informalexample>
<programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<channel name="HappyApp" version="1.0">
<property name="main" type="empty">
<property name="allow-editing" type="bool" value="true"/>
<property name="last-document" type="string" value="foo.txt"/>
</property>
<property name="history" type="array">
<value type="string" value="foo.txt"/>
<value type="string" value="bar.txt"/>
<value type="string" value="baz.txt"/>
</property>
<property name="random-stuff" type="array">
<value type="int" value="345"/>
<value type="double" value="42.4"/>
<value type="string" value="cheese"/>
</property>
</channel>]]></programlisting>
</informalexample>
</para>
<sect2 id="xbpx-file-locations">
<title>File Locations</title>
<para>
Per-channel XML files can be located in any of the <envar>$XDG_CONFIG_DIRS</envar>,
under the subdirectory "xfce4/xfconf/xfce-perchannel-xml/". The
user's own settings are saved in <envar>$XDG_CONFIG_HOME</envar>, under the same
subdirectory.
</para>
</sect2>
<sect2 id="xbpx-elements">
<title>Elements</title>
<itemizedlist>
<listitem>
<emphasis>&lt;channel&gt;</emphasis>: Only one &lt;channel&gt; element per file; must
be the top-level element. Attributes:
<itemizedlist>
<listitem>
<emphasis>name</emphasis>(string): The name of the channel (required).
</listitem>
<listitem>
<emphasis>version</emphasis>(string): The current file version. Right now that's
"1.0". In general, files with the same 'major version' are
compatible with each other (required).
</listitem>
<listitem>
<emphasis>locked</emphasis>(userlist): A list of users/groups who cannot modify
any properties in this channel (only allowed in config files
in non-user-writable locations; mutually exclusive with the
"unlocked" attribute; optional, defaults to empty).
</listitem>
<listitem>
<emphasis>unlocked</emphasis>(userlist): A list of users/groups who can modify
properties in this channel (only allowed in config files
in non-user-writable locations; mutually exclusive with the
"locked" attribute; optional, defaults to "*").
</listitem>
</itemizedlist>
</listitem>
<listitem>
<emphasis>&lt;property&gt;</emphasis>: Allowed as a child of the &lt;channel&gt; element
or another &lt;property&gt; element. Attributes:
<itemizedlist>
<listitem>
<emphasis>name</emphasis>(string): The name of the property (required).
</listitem>
<listitem>
<emphasis>type</emphasis>(string): The type of property. Must be one of: "string",
"uchar", "char", "uint16", "int16", "uint", "int", "uint64",
"int64", "float", "double", "bool", "array", or "empty" (required).
Note that due to a limitation in dbus-glib, uint16 and int16 aren't
actually used, but they are supported in the backend in case
support for 16-bit values becomes supported in the future.
</listitem>
<listitem>
<emphasis>value</emphasis>(string): The value of the property (required except for
type="array" and type="empty").
</listitem>
<listitem>
<emphasis>locked</emphasis>(userlist): A list of users/groups who cannot modify
this property (only allowed in config files in non-user-writable
locations; mutually exclusive with the "unlocked" attribute;
optional, defaults to empty).
</listitem>
<listitem>
<emphasis>unlocked</emphasis>(userlist): A list of users/groups who can modify
this property (only allowed in config files in non-user-writable
locations; mutually exclusive with the "locked" attribute;
optional, defaults to "*").
</listitem>
</itemizedlist>
</listitem>
<listitem>
<emphasis>&lt;value&gt;</emphasis>: Only allowed inside &lt;property&gt; elements where
type="array", and indicates an array element value. Attributes:
<itemizedlist>
<listitem>
<emphasis>type</emphasis>(string): The type of value. All values for type= on
&lt;property&gt; are supported except for "array" and "empty" (required).
</listitem>
<listitem>
<emphasis>value</emphasis>(string): The element's value, encoded as a string (required).
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="xbpx-nesting">
<title>Nesting</title>
<para>
&lt;property&gt; elements can be nested inside other &lt;property&gt;
elements to create a hierarchical tree of properties. If you were
to write the properties out without a tree (using the above example),
including the channel name, you'd have:
<informalexample>
<programlisting>/HappyApp/main/allow-editing
/HappyApp/main/last-document
/HappyApp/history</programlisting>
</informalexample>
</para>
<note>
These strings, minus the channel name part at the beginning, are what
you'd look up if using libxfconf to retrieve property values.
</note>
</sect2>
<sect2 id="xbpx-locking">
<title>Locking/Kiosk Mode</title>
<para>
System administrators can lock certain values or entire channels to
prevent users from changing them. In this case, the administrator
may provide default values that will be used regardless of what may
appear in a user-writable configuration file. If the sysadmin does
not wish to provide values, but only wants to lock a channel/property,
the application's default fallback value will be used instead.
</para>
<para>
Locking a channel or property is as simple as creating a configuration
file and setting either (and only either) the "locked" or "unlocked"
attribute on &lt;channel&gt; or &lt;property&gt; elements that should be
restritcted. This configuration file should be placed in a system
location that is read by the daemon (see "File Locations" above).
</para>
<para>
Both the "locked" and "unlocked" attributes take a semicolon-separated
list of system user and group names. User names should be entered
as-is, and group names should be entered with an "@" symbol prepended
to the group name.
</para>
<para>
The "locked" attribute specifies users and groups who may not modify
the property. The "unlocked" attribute specifies users and groups
who may modify the property, with other users locked out. Only
one of the two attributes may be specified for a particular channel
or property. If both are present, the "unlocked" attribute is used,
and the "locked" attribute is ignored.
</para>
<para>
Note that &lt;lchannel&gt; locking locks all properties under that channel,
but &lt;property&gt; locking locks only the property with the "locked" or
"unlocked" attribute; none of the sub-properties are locked unless
they also contain a "locked" or "unlocked" attribute.
</para>
</sect2>
</sect1>
</article>
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY xfconf-General SYSTEM "xfconf-general.xml">
]>
<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
<bookinfo>
<title>Xfconf Reference Manual</title>
</bookinfo>
<chapter>
<title>Xfconf Usage</title>
&xfconf-General;
<xi:include href="xfconf-general.xml"/>
<xi:include href="xfconf-lockdown.xml"/>
<xi:include href="xfconf-backends.xml"/>
</chapter>
<chapter>
<title>Xfconf Core Functionality</title>
<xi:include href="xml/xfconf-types.xml"/>
......
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<article id="xfconf-general" lang="en">
<sect1 id="xfconf-general-s">
<title>General</title>
<para>
Xfconf is a hierarchical (tree-like) configuration system where the
immediate child nodes of the root are called "channels". All settings
beneath the channel nodes are called "properties."
</para>
<para>
Valid channel and property names are composed of the ASCII US-English
uppercase characters A-Z, lowercase characters a-z, numerals 0-9, the
dash (-), and underscore (_). No other characters are allowed for
channel names. The less than (&lt;) and greater than (&gt;) characters
(aka "angle brackets") are also allowed in property names, but not
in channel names.
</para>
<para>
Property names are referenced by their "full path" underneath their
channel, for example: "/main/history-window/last-accessed". Of course,
when querying a particular property, the channel must be specified
separately as well.
</para>
<para>
Both channel and property names are case-insensitive. For example,
the following four all refer to the same property:
<programlisting>
Channel: ExampleApp, property: /main/history-window/last-accessed
Channel: EXAMPLEAPP, property: /main/history-window/last-accessed
Channel: ExampleApp, property: /Main/History-Window/Last-Accessed
Channel: exampleapp, property: /MAIN/history-window/last-accessed
</programlisting>
</para>
</sect1>
</article>
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<article id="xfconf-lockdown" lang="en">
<sect1 id="xfconf-lockdown-s">
<title>Property Lockdown (Kiosk Mode)</title>
<para>
The Xfconf daemon supports a so-called "kiosk mode" or "lockdown mode"
such that certain configuration properties or certain channels can be
locked from user modification. In this case, the locked values are
provided by a system administrator in the form of a settings file (in
the same format as the user's settings files) in a system read-only
location.
</para>
<para>
Not all backends may support kiosk/lockdown mode. Please see the
documentation corresponding to your configuration backend for
information on how to lock down user configuration values.
</para>
<para>
(If you're unsure which backend, you're probably using the
"Per-channel XML" backend.)
</para>
</sect1>
</article>
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment