Qt Service Framework

XML Format

Services are installed via an XML file which describes the meta data and location of the service. The xml file can be described via the following DTD:

        <!ELEMENT service ( name, filepath, description?, interface+ ) >
        <!ELEMENT description ( #CDATA ) >
        <!ELEMENT filepath ( #PCDATA ) >
        <!ELEMENT interface ( name, version, description?, capabilities?, customproperty* ) >
        <!ELEMENT capabilities ( #PCDATA ) >
        <!ELEMENT name ( #PCDATA ) >
        <!ELEMENT version ( #PCDATA ) >
        <!ELEMENT customproperty ( #CDATA ) >
        <!ATTLIST customproperty key NMTOKEN #REQUIRED >

The elements and attributes have the following meanings:

An example for a valid XML service description could be the following TestService:

        <?xml version="1.0" encoding="utf-8" ?>
        <service>
            <name>TestService</name>
            <filepath>testserviceplugin</filepath>
            <description>Test service description</description>
            <interface>
                <name>com.nokia.qt.ILocation</name>
                <version>1.4</version>
                <capabilities></capabilities>
                <description>Interface that provides location support</description>
            </interface>
            <interface>
                <name>com.nokia.qt.ILocation</name>
                <version>1.5</version>
                <capabilities></capabilities>
                <description>Interface that provides location support</description>
            </interface>
            <interface>
                <name>com.nokia.qt.ISysInfo</name>
                <capabilities>ReadUserData</capabilities>
                <version>2.3</version>
                <description>Interface that provides system information support</description>
                <customproperty key="key1">value1</customproperty>
                <customproperty key="key2">value2</customproperty>
            </interface>
        </service>

Tools for XML Generation

The framework includes a GUI tool under tools/servicexmlgen for generating and inspecting service XML files. This makes it easy to enter service metadata and interface details and generate the appropriate XML to describe the service. It can also be used to load and inspect existing service XML files.

Here is a screenshot of the application, loaded with the TestService XML description provided above.

Installing the Service at Runtime

New services can be added and removed at any time via QServiceManager::addService() and QServiceManager::removeService().

On Symbian devices a service can be installed using the Symbian package installer. More details about this process can be found in the Qt Service Framework on Symbian documentation.

Identifying Services

Each implementation is identified by a service name, an interface name and its version. This information is encapsulated by QServiceInterfaceDescriptor which can be used to request references to service objects.

QServiceFilter simplifies the lookup of already installed services. Developers specifies the criteria used during the meta data lookup. The subsequent example demonstrates the interaction between QServiceInterfaceDescriptor and QServiceFilter by creating references to all services that implement the interface com.nokia.qt.ILocation:

        QServiceManager mgr;
        QServiceFilter filter;
        filter.setInterfaceName("com.nokia.qt.ILocation");
        QList<QServiceInterfaceDescriptor> list = mgr.findInterfaces(filter);
        for(int i = 0; i < list.size(); i++) {
            QObject *serviceObject;
            serviceObject = mgr.loadInterface(list[i]);

            // returned object owned by client
            if (serviceObject)
                serviceObject->setParent(this);
        }

Upgrading Services

There are two ways in which to upgrade a service. The first is an incremental approach whereby QServiceManager::addService() is used to register an XML descriptor whose service name already exists but defines new interface implementations. For example an already existing service, "ovi" may define version 1.0 of interface,"IDownload". QServiceManager::addService() is then called with an XML descriptor that declares itself as belonging the "ovi" service, but implements version 1.1 of the interface "IDownload". Both implementation versions will be available for use.

The second method is a replacement approach whereby an existing service is completely removed and replaced by a new service.

As an example the already existing "ovi" service may implement interface "IDownload" version 1.0, the new "ovi" service may implement "IDownload" version 1.0 and version 1.1. In this case the old service implementation must be first be removed using QServiceManager::removeService() to make way for the new service implementation.

Examples

• File Manager Plugin Example
• Bluetooth Transfer Plugin Example
• Service Browser Example

Main Classes

QAbstractSecuritySession	Generic mechanism to enable permission checks for services
QServiceContext	Context information to services
QServiceFilter	Defines criteria for defining a sub-set of all available services
QServiceInterfaceDescriptor	Identifies a service implementation
QServiceManager	Enables the loading of service plugins and the (de)registration of services
QServicePluginInterface	Defines the interface that every plug-in based service must implement