MeeGo 1.2 Harmattan Developer Documentation Develop for the Nokia N9

QServiceManager Class Reference

The QServiceManager class enables the loading of service plugins and the (de)registration of services. More...

 #include <QServiceManager>

Inherits: QObject.

This class was introduced in Qt Mobility 1.0.

Public Types

enum Error { NoError, StorageAccessError, InvalidServiceLocation, InvalidServiceXml, ..., UnknownError }

Public Functions

QServiceManager ( QObject * parent = 0 )
QServiceManager ( QService::Scope scope, QObject * parent = 0 )
~QServiceManager ()
bool addService ( const QString & xmlFilePath )
bool addService ( QIODevice * device )
Error error () const
QList<QServiceInterfaceDescriptor> findInterfaces ( const QServiceFilter & filter = QServiceFilter() ) const
QList<QServiceInterfaceDescriptor> findInterfaces ( const QString & serviceName ) const
QStringList findServices ( const QString & interfaceName = QString() ) const
QServiceInterfaceDescriptor interfaceDefault ( const QString & interfaceName ) const
QObject * loadInterface ( const QString & interfaceName, QServiceContext * context = 0, QAbstractSecuritySession * session = 0 )
QObject * loadInterface ( const QServiceInterfaceDescriptor & descriptor, QServiceContext * context = 0, QAbstractSecuritySession * session = 0 )
T * loadLocalTypedInterface ( const QString & interfaceName, QServiceContext * context = 0, QAbstractSecuritySession * session = 0 )
T * loadLocalTypedInterface ( const QServiceInterfaceDescriptor & serviceDescriptor, QServiceContext * context = 0, QAbstractSecuritySession * session = 0 )
bool removeService ( const QString & serviceName )
QService::Scope scope () const
bool setInterfaceDefault ( const QString & service, const QString & interfaceName )
bool setInterfaceDefault ( const QServiceInterfaceDescriptor & descriptor )
  • 29 public functions inherited from QObject

Signals

void serviceAdded ( const QString & serviceName, QService::Scope scope )
void serviceRemoved ( const QString & serviceName, QService::Scope scope )

Additional Inherited Members

  • 1 property inherited from QObject
  • 1 public slot inherited from QObject
  • 1 public variable inherited from QObject
  • 4 static public members inherited from QObject
  • 7 protected functions inherited from QObject
  • 2 protected variables inherited from QObject

Detailed Description

The QServiceManager class enables the loading of service plugins and the (de)registration of services.

A service is a stand-alone component that can be used by multiple clients. Each service implementation must derive from QObject. Clients request a reference to a service via loadInterface() or loadLocalTypedInterface().

Services are separate deliveries in the form of plug-ins. New services can be (de)registered at any time via addService() and removeService() respectively. Such an event is published via the serviceAdded() and serviceRemoved() signal. Each service plug-in must implement QServicePluginInterface.

Each plug-in may support multiple interfaces and may even provide multiple implementations for the same interface. Individual implementations are identified via QServiceInterfaceDescriptor. For a more detailed explanation of services and how they relate to interface and their implementations please see QServiceInterfaceDescriptor.

See also QServicePluginInterface, QServiceContext, and QAbstractSecuritySession.

Member Type Documentation

enum QServiceManager::Error

Defines the possible errors for the service manager.

Constant Value Description
QServiceManager::NoError 0 No error occurred.
QServiceManager::StorageAccessError 1 The service data storage is not accessible. This could be because the caller does not have the required permissions.
QServiceManager::InvalidServiceLocation 2 The service was not found at its specified location.
QServiceManager::InvalidServiceXml 3 The XML defining the service metadata is invalid.
QServiceManager::InvalidServiceInterfaceDescriptor 4 The service interface descriptor is invalid, or refers to an interface implementation that cannot be accessed in the current scope.
QServiceManager::ServiceAlreadyExists 5 Another service has previously been registered with the same location.
QServiceManager::ImplementationAlreadyExists 6 Another service that implements the same interface version has previously been registered.
QServiceManager::PluginLoadingFailed 7 The service plugin cannot be loaded.
QServiceManager::ComponentNotFound 8 The service or interface implementation has not been registered.
QServiceManager::ServiceCapabilityDenied 9 The security session does not permit service access based on its capabilities.
QServiceManager::UnknownError 100 An unknown error occurred.

Member Function Documentation

QServiceManager::QServiceManager ( QObject * parent = 0 )

Creates a service manager with the given parent.

The scope will default to QService::UserScope.

QServiceManager::QServiceManager ( QService::Scope scope, QObject * parent = 0 )

Creates a service manager with the given scope and parent.

This function was introduced in Qt Mobility 1.0.

QServiceManager::~QServiceManager ()

Destroys the service manager.

bool QServiceManager::addService ( const QString & xmlFilePath )

Registers the service defined by the XML file at xmlFilePath. Returns true if the registration succeeded, and false otherwise.

If a previously unkown interface is added the newly registered service automatically becomes the new default service provider for the new interface.

A service plugin cannot be added if another service is already registered with the same plugin file path. A service plugin also cannot be added if the service is already registered and implements any of the same interface versions that the new plugin implements.

This function was introduced in Qt Mobility 1.0.

See also removeService() and setInterfaceDefault().

bool QServiceManager::addService ( QIODevice * device )

Registers the service defined by the XML data from the given device. Returns true if the registration succeeded, and false otherwise. If a previously unkown interface is added the newly registered service automatically becomes the new default service provider for the new interface.

Registering a service also causes QServicePluginInterface::installService() to be called on the service. If the service plugin is not accessible (e.g. if the plugin file is not found) and installService() cannot be invoked on the service, the registration fails and this method returns false.

A service plugin cannot be added if another service is already registered with the same plugin file path. A service plugin also cannot be added if the service is already registered and implements any of the same interface versions that the new plugin implements.

Services are always added based on the scope() of the current service manager instance.

This function was introduced in Qt Mobility 1.0.

See also removeService() and setInterfaceDefault().

Error QServiceManager::error () const

Returns the type of error that last occurred.

This function was introduced in Qt Mobility 1.0.

QList<QServiceInterfaceDescriptor> QServiceManager::findInterfaces ( const QServiceFilter & filter = QServiceFilter() ) const

Returns a list of the interfaces that match the specified filter.

This function was introduced in Qt Mobility 1.0.

QList<QServiceInterfaceDescriptor> QServiceManager::findInterfaces ( const QString & serviceName ) const

Returns a list of the interfaces provided by the service named serviceName. If serviceName is empty, this function returns a list of all available interfaces in this manager's scope.

This function was introduced in Qt Mobility 1.0.

QStringList QServiceManager::findServices ( const QString & interfaceName = QString() ) const

Returns a list of the services that provide the interface specified by interfaceName. If interfaceName is empty, this function returns a list of all available services in this manager's scope.

This function was introduced in Qt Mobility 1.0.

QServiceInterfaceDescriptor QServiceManager::interfaceDefault ( const QString & interfaceName ) const

Returns the default interface implementation for the given interfaceName.

This function was introduced in Qt Mobility 1.0.

See also setInterfaceDefault().

QObject * QServiceManager::loadInterface ( const QString & interfaceName, QServiceContext * context = 0, QAbstractSecuritySession * session = 0 )

Loads and returns the interface specified by interfaceName, as provided by the default service for this interface, using the given context and session. context and session object are owned by the caller of this function.

The caller takes ownership of the returned pointer.

This function returns a null pointer if the requested service cannot be found.

The security session object is not mandatory. If the session pointer is null, the service manager will not perform any checks. Therefore it is assumed that the service manager client is trusted as it controls whether service capabilities are enforced during service loading.

This function was introduced in Qt Mobility 1.0.

See also setInterfaceDefault() and interfaceDefault().

QObject * QServiceManager::loadInterface ( const QServiceInterfaceDescriptor & descriptor, QServiceContext * context = 0, QAbstractSecuritySession * session = 0 )

Loads and returns the interface specified by descriptor using the given context and session. context and session object are owned by the caller of this function.

The caller takes ownership of the returned pointer.

This function returns a null pointer if the requested service cannot be found.

The security session object is not mandatory. If the session pointer is null, the service manager will not perform any checks. Therefore it is assumed that the service manager client is trusted as it controls whether service capabilities are enforced during service loading.

This function was introduced in Qt Mobility 1.0.

T * QServiceManager::loadLocalTypedInterface ( const QString & interfaceName, QServiceContext * context = 0, QAbstractSecuritySession * session = 0 )

Loads the service object implementing interfaceName, as provided by the default service for this interface, using the given context and session. context and session object are owned by the caller of this function. The template class must be derived from QObject.

If interfaceName is not a known interface the returned pointer will be null.

Note that using this function implies that service and client share the implementation of T which means that service and client become tightly coupled. This may cause issue during later updates as certain changes may require code changes to the service and client.

The caller takes ownership of the returned pointer.

The security session object is not mandatory. If the session pointer is null, the service manager will not perform any checks. Therefore it is assumed that the service manager client is trusted as it controls whether service capabilities are enforced during service loading.

This function was introduced in Qt Mobility 1.0.

See also setInterfaceDefault() and interfaceDefault().

T * QServiceManager::loadLocalTypedInterface ( const QServiceInterfaceDescriptor & serviceDescriptor, QServiceContext * context = 0, QAbstractSecuritySession * session = 0 )

Loads the service object identified by serviceDescriptor using the given context and session. context and session object are owned by the caller of this function. The template class must be derived from QObject.

If the serviceDescriptor is not valid the returned pointer will be null.

Note that using this function implies that service and client share the implementation of T which means that service and client become tightly coupled. This may cause issue during later updates as certain changes may require code changes to the service and client.

The caller takes ownership of the returned pointer.

The security session object is not mandatory. If the session pointer is null, the service manager will not perform any checks. Therefore it is assumed that the service manager client is trusted as it controls whether service capabilities are enforced during service loading.

This function was introduced in Qt Mobility 1.0.

bool QServiceManager::removeService ( const QString & serviceName )

Unregisters the service specified by serviceName.

Returns true if the unregistration succeeded, and false otherwise.

If a default service implementation is removed and there are other implementations for the same interface, the service manager chooses the implementation with the highest version number as the new default. If there is more than one serivce with the same version number, the service manager makes a random choice with regards to the new default implementation. If this is not the desired behaviour the default selection should be updated via setInterfaceDefault().

Services are always removed based on the scope() of the current service manager instance.

This function was introduced in Qt Mobility 1.0.

See also addService().

QService::Scope QServiceManager::scope () const

Returns the scope used for registering and searching of services.

This function was introduced in Qt Mobility 1.0.

void QServiceManager::serviceAdded ( const QString & serviceName, QService::Scope scope ) [signal]

This signal is emited whenever a new service with the given serviceName has been registered with the service manager. scope indicates where the service was added.

If the manager scope is QService::SystemScope, it will not receive notifications about services added in the user scope.

This function was introduced in Qt Mobility 1.0.

See also addService().

void QServiceManager::serviceRemoved ( const QString & serviceName, QService::Scope scope ) [signal]

This signal is emited whenever a service with the given serviceName has been deregistered with the service manager. scope indicates where the service was added.

If the manager scope is QService::SystemScope, it will not receive notifications about services removed in the user scope.

This function was introduced in Qt Mobility 1.0.

See also removeService().

bool QServiceManager::setInterfaceDefault ( const QString & service, const QString & interfaceName )

Sets the default interface implementation for interfaceName to the matching interface implementation provided by service.

If service provides more than one interface implementation for interfaceName, the newest version of the interface is set as the default.

Returns true if the operation succeeded, and false otherwise.

Note: When in system scope, the service must be a system-wide service rather than a user-specific service; otherwise, this will fail.

This function was introduced in Qt Mobility 1.0.

See also interfaceDefault().

bool QServiceManager::setInterfaceDefault ( const QServiceInterfaceDescriptor & descriptor )

This is an overloaded function.

Sets the interface implementation specified by descriptor to be the default implementation for the particular interface specified in the descriptor.

Returns true if the operation succeeded, and false otherwise.

Note: When in system scope, the descriptor must refer to a system-wide service rather than a user-specific service; otherwise, this will fail.

This function was introduced in Qt Mobility 1.0.