How to provide context properties
=================================
Any component can provide its own key/value pairs and make them appear
as a +ContextProperty+ for C++ (and in other forms for other
languages).
As a provider of context properties, you need to drop one or more
_property declaration_ files into +/usr/share/contextkit/providers/+
to register your properties with the context framework. This file
follows a format described below and is used by +libcontextsubscriber+
and others to find you when someone subscribes to your properties.
The file is also used by the Context Commander to show descriptions of
your properties and to learn about the possible values that a property
can legally have.
The property declaration files also inform the context framework how
you want to be contacted. Right now, you have to implement the
+org.freedesktop.ContextKit+ D-Bus interface, and register yourself on
either the system or the session D-Bus with a suitable bus name. The
choice of system or session bus and your bus name go into the property
declaration file.
The only supported way right now to implement the
+org.freedesktop.ContextKit+ interface is to use the
link:../../libcontextprovider-doc/html/index.html[+libcontextprovider+] library.
The name of the property declaration file must be
"__bus-name__++.context++".
The property declaration file
-----------------------------
The property declaration file contains XML and must follow
link:context-provider-schema.html[this XML schema]. A simple example
for the +Example.Random+ property looks like this:
[xml]
------------------
double
A random number between 0 and 1 that changes every now and then.
------------------
This file declares the single property +com.example.Random+ and
instructs the Content Framework to connect to the
+com.example.RandomProvider+ bus name on the session D-Bus. It would
be stored as
+/usr/share/contextkit/providers/com.example.RandomProvider.context+
You need to be careful when choosing property name; see the
"Guidelines for property providers" section for how to avoid
conflicts.
When providing properties from the link:context-properties.html[core
list], you need to follow additional rules to make sure that your
property declarations and the centrally maintained core list do not
fall out of synch. See the "Providing core properties" section for
more about them.
After installing a property declaration file into a directory +$dir+,
you should usually execute +update-contextkit-providers+. This will
update the various caches that clients like the +libcontextsubscriber+
library use.
But, if a property declaration file is installed via a Debian package,
you should not call +update-contextkit-providers+ in your maintainer
scripts. Triggers in the relevant packages take care of running
update-contextkit-providers at the right time and only as often as
necessary.
The XML element tree in the property declaration file simply consists
of a list of +key+ elements.
A +key+ element in the property declaration tree can have a +doc+
child element. The contents of this element should be plain text
without any additional markup.
Types
~~~~~
ContextKit uses the experimental link:context-types.html[Desktop Type
System]. A property declaration should have a +type+ element that
conforms to the Desktop Type System.
For example, a property that is a enumeration would be declared like
this:
[xml]
------------------
The current economic trend, as an enumerated value.
------------------
Deprecating properties
~~~~~~~~~~~~~~~~~~~~~~
You can add a +deprecated+ element to your property declaration to
mark it as deprecated. Run-time warnings will be emitted when
applications connect to a deprecated property, and documentation that
is generated from your property declarations will mark them as
deprecated.
Example:
[xml]
------------------
Don't use this property, use ABetterIdeaByFar instead.
------------------
Guidelines for property providers
---------------------------------
Names
~~~~~
Context FW maintains a list of core properties. If you are providing a core property, you need to name it as it is described in the core property list (e.g., Screen.TopEdge).
Only core property names are allowed to start with a capital ASCII letter ("A" to "Z").
If you want to provide a non-core property, its name must be a valid name for a D-Bus object path (e.g., /com/mycompany/screen/topedge). A valid D-Bus object path starts with "/" and contains zero or more elements separated by "/" . Each element must only contain the following characters: [A-Z][a-z][0-9]_
When defining a new non-core property, you need to choose a unique
prefix. Start with a reversed fully qualified domainname that you
control, such as "/com/nokia/" or "/org/gnome/". Then, if the first
component is "org" and the second component is not a top-level domain (e.g. fi, com),
drop "org". Then convert the first character of the prefix to
lower-case if it is one of "A" to "Z".
For example, the GNOME project can use "/gnome/" as their prefix, KDE
can use "/kde/", and Nokia can use "/com/nokia/".
Providing core properties
-------------------------
The Context Framework project maintains a list of _core properties_.
These core properties are intended to cover the needs of most
applications and be meaningful for many different devices.
When you are implementing a provider for some of the core properties,
you must of course make sure that you follow the specification of that
property. You can not redefine its type or description in your
property declaration file, obviously.
Thus, for core properties, you should not include any +type+ or +doc+
elements in your key declarations, just a +name+ element. The list of
core properties is also known to context subcribers at run-time and
will be used to fill in the missing details.
For example, a property declaration file for core properties could
look like this:
[xml]
------------------
------------------
This just declares that the +Example.Random+ property can be
subscribed to by contacting +com.example.RandomProvider+ on the
session bus. It's type and documentation are found elsewhere.