The Context Framework maintains a registry defining which context properties are currently provided and by whom. The introspection API of libcontextsubscriber allows you to inspect the current state of the registry and observe its changes.

Overview

The introspection is provided via two classes: ContextRegistryInfo and ContextPropertyInfo.

ContextRegistryInfo provides a high-level view to the registry contents. You can use it to obtain info about the list of currently available keys or e.g. get a list of keys for one particular provider. ContextRegistryInfo is a singleton instance which is created on the first access.

ContextPropertyInfo is used to obtain metadata about one particular key. Once created, it can be used to retrieve the type and provider information (DBus bus type and name) of the introspected key. It also provides a signal to listen for changes happening to a key.

Usage

    // To get a list of all keys in the registry
    ContextRegistryInfo *context = ContextRegistryInfo::instance();
    QStringList currentKeys = context->listKeys();

Using the ContextPropertyInfo is even more straight-forward.

    // To check the type of a particular key
    ContextPropertyInfo propInfo("Battery.ChargeLevel");
    QString propType = propInfo.type();

The introspection API in general never asserts (never fails). It'll return empty strings on errors or if data is missing. For example:

    ContextPropertyInfo propInfo("Something.That.Doesnt.Exist");
    propInfo.type();     //  ...returns empty string
    propInfo.doc();      //  ...returns empty string

You can use this functionality to wait for keys to become available in the registry. Just create a ContextPropertyInfo for a key that you're expecting to become present and connect to the changed signal.

    ContextPropertyInfo propInfo("Something.That.Doesnt.Exist");
    propInfo.declared(); // false
    // Connect something to the changed signal, keep checking it

XML vs.CDB

When the introspection API is first used, a backend choice is being made. CDB backend (reading data from 'cache.cdb' ) is used if the tiny database cache file exists in the registry. The standard (slower) XML backend is used in other cases.

It's possible to force a usage of a particular backend. This can be done by calling the instance method with a string name of the backend:

    ContextRegistryInfo::instance("cdb"); // or "xml"

This needs to be done early enough before the introspection API is first used. For more information about the xml and backends read the UpdatingContextProviders page.


Generated on Thu Feb 21 18:31:19 2013 for libcontextsubscriber by  doxygen 1.5.6