Publish and Subscribe

The Publish and Subscribe API enables applications to read item values, navigate through and subscribe to change notifications.

Namespace

The QtMobility APIs are placed into the QtMobility namespace. This is done to facilitate the future migration of QtMobility APIs into Qt. See the Quickstart guide for an example on how the namespace impacts on application development.

Overview

The Qt Value Space unifies various sources of hierarchical data into a single consistent model. Conceptually the Value Space is a hierarchical tree of which each node or leaf can optionally contain a QVariant value. A serialized version of a simple example Value Space might look like this.

 /Device/Buttons = 3
 /Device/Buttons/1/Name = Menu
 /Device/Buttons/1/Usable = true
 /Device/Buttons/2/Name = Select
 /Device/Buttons/2/Usable = false
 /Device/Buttons/3/Name = Back
 /Device/Buttons/3/Usable = true

Existing values within the Value Space are accessed through the QValueSpaceSubscriber class. This class provides a means to read values, receive change notifications for a given path and navigate through the Value Space.

New values are added to the Value Space via the QValueSpacePublisher class. This class allows applications to publish values and receive interest notifications when applications connect to a path. Interest notifications can be used to refrain from updating values in the Value Space when there are no interested parties.

Nodes in the Value Space can be thought of as representing schema objects. Obviously this is a conceptual differentiation and not a physical one, as internally the Value Space is treated as one large tree. By applying structured schema to the space "explore-ability" is increased. For example, the /Device/Buttons schema can be defined as containing a value representing the number of mappable buttons on a device, and a sub-item for each adhering to the MappableButton schema. The MappableButton schema itself may be defined as containing two attributes Name and Usable. Change notification is modeled in this fashion also. Were the /Device/Buttons/1/Name item to change, the /Device/Buttons/1 item would also be marked as changed, and so on up the tree. This allows, for example, subscribers to /Device/Buttons to be notified when anything "button" related changes.

Internally, the Value Space consists of an arbitrary number of data source trees, or layers, which are stacked on top of each other to form the final unified view. If a "higher" layer contains an item, it shadows the value of items in the layers below it. Consider the Value Space item /Device/Buttons. If two layers contained this item, the value in the layer with the higher layer order would shadow that with the lower layer order. However, if only the layer with the lower order contained this item, it would be visible through the QValueSpaceSubscriber class, even if the higher order layer contained sub-items such as /Device/Buttons/1. That is, layer shadowing occurs by value not by path.

Layer order is fixed and is defined in the layer implementation.

The following Value Space layers are available:

Layer	Description
Shared Memory Layer	The Shared Memory layer provides a non-permanent Value Space backing store using shared memory and local sockets. The Shared Memory layer is only available on Unix platforms. The Shared Memory layer has an order of 0x10000000.
Volatile Registry Layer	The Volatile Registry layer provides a non-permanent Value Space backing store using volatile keys stored in the Windows' registry. The Volatile Registry layer is only available on Windows platforms. The Volatile Registry layer has an order of 0x1000.
Non-volatile Registry Layer	The Non-volatile Registry layer provides a permanent Value Space backing store using keys stored in the Windows' registry. The Non-volatile Registry layer is only available on Windows platforms. The Non-volatile Registry layer has an order of 0.
ContextKit Layer	The ContextKit layer provides a non-permanent Value Space backing store using ContextKit. This layer is only available on MeeGo and Maemo platforms. The ContextKit layer has an order of 0.
Symbian Settings Layer	The Symbian Settings layer provides a permanent Value Space backing store using the Symbian OS' Properties (RProperty), Central Repository files (CRepository) and Feature Manager flags. The Symbian Settings layer has an order of 0.
GConf Layer	The GConf Layer provides a permanent Value Space backing store using the GConf configuration system designed for the GNOME desktop environment. The GConf Layer has an order of 0 and it's the only available layer in Maemo 5.

The Value Space has support for both client/server and peer-to-peer layer architectures. If a layer that uses a client/server architecture is used and a server process is not provided by the underlying system it will be necessary to start one. This can be done by calling QValueSpace::initValueSpaceServer() prior to any other use of the Value Space.

Detailed Layer Descriptions

Shared Memory Layer

The Shared Memory layer stores all values in a 10MB block of shared memory which is reserved when the Value Space server initializes. As the layer creates this region at startup, it is assumed that the operating system lazily commits memory. If this assumption is invalid, the Shared Memory layer will unnecessarily consume 10MB of memory.

Value Space clients read from the Shared Memory layer's shared memory region directly. A kernel lock is acquired for each read to prevent corruption. While the layer supports concurrent readers, it is possible that a faulty or malicious application could acquire and refuse to release this lock causing any layer updates to be delayed indefinitely.

Only the Value Space server ever writes to the shared memory region. When clients attempt to add items to the layer, their changes are transmitted via a QLocalSocket (e.g. /tmp/qt/valuespace_shmlayer domain socket on Unix systems) to the server where the update is performed. Updates are batched in-process and sent when the process re-enters the Qt event loop. Transmission and synchronization of changes can be forced manually by the QValueSpacePublisher::sync() function, although as this requires a round trip between the client and server, doing so frequently may significantly degrade performance.

Change notifications are transmitted to clients in the form of "something has changed" messages. Nodes within the shared memory region are versioned, which allows clients to quickly determine exactly what has changed without the need for a bulkier change notification protocol.

Symbian Settings Layer

Publish and Subscribe API can be used to access Symbian OS' Properties (RProperty), Central Repository files (CRepository) and Feature Manager flags.

Since Publish and Subscribe API is based on Value Space that is accessed via textual path we need to somehow specify how particular paths are turned into RProperty, CRepository and Feature Manager key definitions. There are two ways to accomplish this. The keys can be accessed using numeric uids, or the paths can be mapped to textual paths using QCRML files.

Accessing Properties, Central Repository and Feature Manager Using UIDs

Accessing Symbian OS Properties, Central Repository keys and Feature Manager flags using numeric UIDs is done with reserved paths where the first part of the path is either /ps/, /cr/ or /fm/. These denote access to Symbian OS Properties, Central Repository files and Feature Manager flags, respectively. The format of the path is as follows:

 /ps/<uid>/<key>
 /cr/<uid>/<key>
 /fm/<key>

<uid> and <key> values are either decimal numbers, or hexadecimal numbers prefixed with 0x. For example following two paths point to the same Property:

 /ps/268440235/12
 /ps/0x100012ab/0xc

When using numeric paths, it is possible to get change notifications only using full path to a specific key. I.e. key /ps/<uid> is not considered changed when any of the keys under that UID change.

Declaring Value Space Paths Using QCRML

QCRML files are XML files that can be used to declare available Value Space paths that are visible to the clients. Each path defines whether the actual value is stored in CRepository, RPropery or Feature Manager as well as needed Category/Repository/Key UIDs.

The following QCRML file defines Value Space paths for power state properties stored in Symbian OS Properties:

 <?xml version="1.0" encoding="UTF-8"?>
 <repository target="RProperty" uidValue="0x10205041">
     <key ref="/resources/battery/level" int="0x00000001"/>
     <key ref="/resources/battery/status" int="0x00000002"/>
     <key ref="/resources/charging/status" int="0x00000003"/>
 </repository>

The following QCRML file defines a Value Space path for the "current profile id" stored in Central Repository:

 <?xml version="1.0" encoding="UTF-8"?>
 <repository target="CRepository" uidValue="0x101f8798">
     <key ref="/profile/id" int="0x7e000001"/>
 </repository>

The following QCRML file defines a Value Space paths for camera and camera lens cover feature flags:

 <?xml version="1.0" encoding="UTF-8"?>
 <repository target="FeatureManager">
     <key ref="/KFeatureIdCamera" int="0x2"/>
     <key ref="/KFeatureIdCameraLensCover" int="0xd1"/>
 </repository>

The qcrmlgen tool located in the tools directory can be used to create QCRML files.

Location of QCRML Files

All the QCRML files need to be located in \resource\qt\crml directory (in any available drive) in Symbian file system.

In .pro files this means that the files need to be deployed with the SIS package.

Example .pro file section:

 symbian {
     crml.sources = resources.qcrml profile.qcrml
     crml.path = c:/resource/qt/crml
     DEPLOYMENT += crml
 }

Usage and limitations of Symbian Settings Layer

The capabilities needed for reading and writing Symbian OS Properties and Central Repository files are defined when the keys are created. Thus, the capability requirements to access existing keys vary from key to key.

When defining new Symbian OS Properties through QValueSpacePublisher, the category UID of the key must be same as the Secure ID (SID) of the process where the code is running. New properties defined through QValueSpacePublisher won't have any platform security restrictions on reading and writing the values.

The native types of the Symbian OS Properties and Central Repository keys are defined at the time of the key creation, and cannot be changed afterwards. Trying to write a value of a wrong type will fail. Only integer and bytearray native types are supported through SymbianSettingsLayer. All non-integer types are automaticallye serialized in QByteArray and stored as 8-bit byte form. The serialization/deserialization is transparent operation to the API user but may cause interoperatibility issues with native Symbian codes that access the same data directly. The maximum size of the bytearray is 65535 for RProperty backing store.

There is no way to define new Central Repository files at runtime. Generally the creation new Central Repository files is limited to device manufacturer. An application can bring its own Central Repository file at installation time, if the file is installed as an embedded upgrade SIS package. As the embedded upgrade SIS needs to install the file to Central Repository's private data cage, it needs to be separately Symbian Signed with permission from Symbian or device manufacturer.

The Symbian OS Feature Manager entries are read-only, and the type returned is QVariant boolean. The value of a Feature Manager entry is true when the feature is supported. When the feature is not supported or it does not exist, the value is false.

For more information about Symbian OS Properties, Central Repository and Feature Manager refer to Symbian Developer's Library at Forum Nokia.

Interoperability with native Symbian code

If interoperability between native Symbian code is needed for non-integer types, the values have to be converted to bytearray before writing them to RProperty or CRepository. When data stored by native Symbian code is read, it should be read as raw bytearray. This can be done by adding parameter "?raw" to the end of the path. For example:

 /ps/0x100012ab/0xc?raw

For convenience, parameter "?string" can be used to read and write UTF-16 strings to/from Properties and Central Repository in a format that is interoperable with native Symbian code. For example:

 /ps/0x100012ab/0xd?string

Discovering Symbian key ids

Symbian Value Space keys are closely tied with the related Symbian C++ APIs. The information about available keys is usually found from the native Symbian SDK documentation, or from Symbian C++ headers in the SDK (directory /epoc32/include).

Following general conventions used in Symbian OS can help in discovering the keys, in addition to above:

Publicly available feature flags are listed in Symbian SDK file epoc32/include/publicruntimeids.hrh. The feature flag key constants typically begin with "KFeature".
Central Repository keys are described on the headers of the specific API. Central Repository key constants typically begin with "KCR".
RProperty keys are described on the headers of the specific API. RProperty key constants typically begin with "KPS".

GConf Layer

Publish and Subscribe API can be used to access the GConf configuration system.

Limitations of GConf Layer

GConf can natively store only a limited set of QVariant data types. These types are Bool, Int, Double, String, StringList and List. When publishing other data types the values are automatically serialized and stored to GConf as BASE64 encoded strings. When reading these values they are automatically converted back to the original data types. The serialization/deserialization is transparent operation to the API user but may cause interoperatibility issues with native applications that access the same data directly.

ContextKit Layer

Publish and Subscribe can be used to access both "core" and "non-core" values in the MeeGo ContextKit. The backend by default will look for a "core" property in the registry first (dot-separated), and then fall back to a "non-core" property (slash-separated) if a "core" one is not found.

You can force the selection of one or the other path scheme by passing the flags QValueSpace::PermanentLayer and QValueSpace::TransientLayer to the constructors of QValueSpaceSubscriber and QValueSpacePublisher along with the path name.

Organization and application name

ContextKit requires providers to register with a valid DBus service name in order to publish values. The ContextKit Layer automatically builds this name from QCoreApplication::organizationDomain() and QCoreApplication::applicationName(). In order to publish, you will need to set these values in your application. They are not necessary if your application only subscribes and does not publish.

 QCoreApplication::setOrganizationDomain("example.com");
 QCoreApplication::setApplicationName("Test Application");
 // will register with 'com.example.Test-Application'

Declaring Value Space Paths Using Property Declaration Files

ContextKit also requires that an entry be present in the ContextKit Registry on the system before subscribers will be able to find an advertised property. The Registry is a set of XML files, normally saved in /usr/share/contextkit/providers with the .context file extension.

For example, the following .context file describes a simple example service:

 <?xml version="1.0"?>
 <provider bus="session" service="com.example.Test-Application">
   <key name="/com/example/test/value" />
 </provider>

Note: 1) The service attribute must match the organization domain and application name set above. 2) The bus attribute must be "session", i.e. you can only use the session bus.

Example qmake snippet to deploy the .context file

 meego {
     contextreg.sources = example.context
     contextreg.path = /usr/share/contextkit/providers
     INSTALLS += contextreg
 }

Additionally, it is common on ContextKit platforms to make use of a database cache of the registry, which can usually be regenerated with the command update-contextkit-providers. This is the case on Maemo, where the command should be appended to the bottom of the debian/postinst script during packaging.

For more detailed information on this, please refer to How to provide context properties.

Limitations of ContextKit Layer

Similar to both the Symbian and Gconf backends, ContextKit supports only a limited range of QVariant data types. Types not supported are serialized in a manner transparent to the API user, but interoperatibility with native ContextKit subscribers may be impacted as a result.

Examples