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 libcontextprovider library.
The name of the property declaration file must be "bus-name.context".
The property declaration file contains XML and must follow this XML schema. A simple example for the Example.Random property looks like this:
<?xml version="1.0"?>
<provider bus="session"
service="com.example.RandomProvider">
<key name="com.example.Random">
<type>double</type>
<doc>
A random number between 0 and 1 that changes every now and then.
</doc>
</key>
</provider>
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 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.
ContextKit uses the experimental 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:
<key name="Economy">
<type>
<int-enum>
<up val="1" doc="Getting better"/>
<down val="2" doc="Getting worse"/>
<even val="3" doc="Getting boring"/>
</int-enum>
</type>
<doc>
The current economic trend, as an enumerated value.
</doc>
</key>
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:
<key name="SoundedLikeAGoodIdea"
type="string">
<deprecated/>
<doc>
Don't use this property, use ABetterIdeaByFar instead.
</doc>
</key>
Context property names can contain any character except "/".
Only core property names are allowed to start with a capital ASCII letter ("A" to "Z").
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, 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.".
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 version="1.0"?>
<provider bus="session"
service="com.example.RandomProvider">
<key name="Example.Random"/>
</provider>
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.