|
|
              
QServiceManager ClassThe QServiceManager class enables the loading of service plugins and the (de)registration of services. More... #include <QServiceManager>Inherits: QObject. Public Types
Public Functions
Reimplemented Public Functions
Signals
Additional Inherited Members
Detailed DescriptionThe 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. Member Type Documentation
|
| 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.
The service manager will also ensure that a background thread is started to handle service manager requests. If you need to supress this behavior so that all requests are handled in the foreground (in the main GUI thread) export the following environment variable:
env QT_NO_SFW_BACKGROUND_OPERATION /path/to/my_sfw_app
QServiceManager::QServiceManager(QService::Scope scope, QObject * parent = 0)
Creates a service manager with the given scope and parent.
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.
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.
See also removeService() and setInterfaceDefault().
QServiceManager::Error QServiceManager::error() const
Returns the type of error that last occurred.
void QServiceManager::errorChanged() [signal]
bool QServiceManager::event(QEvent *) [virtual]
QList<QServiceInterfaceDescriptor> QServiceManager::findInterfaces(const QServiceFilter & filter = QServiceFilter()) const
Returns a list of the interfaces that match the specified filter.
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.
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.
QServiceInterfaceDescriptor QServiceManager::interfaceDefault(const QString & interfaceName) const
Returns the default interface implementation for the given interfaceName.
See also setInterfaceDefault().
bool QServiceManager::isInterfaceRunning(const QString & interfaceName)
If interfaceName is an out of process service this verifies the interface is running. If the service is in process this function always returns false.
Use this function to verify the interface requested is running. This is useful is you only want to call loadInterface when the service is already running. This call does not guarantee that the service will remain running, as such a race condition exists if the service quits between this call being made and loadInterface being called.
If the service can not be fount this returns false.
See also setInterfaceDefault(), interfaceDefault(), and loadInterface().
bool QServiceManager::isInterfaceRunning(const QServiceInterfaceDescriptor & descriptor)
If descriptor is an out of process service this verifies the service is running. If the service is in process this function always returns false.
Use this function to verify the interface requested is running. This is useful is you only want to call loadInterface when the service is already running. This call does not guarantee that the service will remain running, as such a race condition exists if the service quits between this call being made and loadInterface being called.
If the service can not be found this returns false. Error is set if an error occurs.
QObject * QServiceManager::loadInterface(const QString & interfaceName)
Loads and returns the interface specified by interfaceName.
The caller takes ownership of the returned pointer.
This function returns a null pointer if the requested service cannot be found.
See also setInterfaceDefault() and interfaceDefault().
QObject * QServiceManager::loadInterface(const QServiceInterfaceDescriptor & descriptor)
Loads and returns the interface specified by descriptor.
The caller takes ownership of the returned pointer.
This function returns a null pointer if the requested service cannot be found.
See also loadInterfaceRequest().
T * QServiceManager::loadLocalTypedInterface(const QString & interfaceName)
Loads the service object implementing interfaceName, as provided by the default service for this interface. 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.
See also setInterfaceDefault() and interfaceDefault().
T * QServiceManager::loadLocalTypedInterface(const QServiceInterfaceDescriptor & serviceDescriptor)
Loads the service object identified by serviceDescriptor. 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.
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.
See also addService().
QService::Scope QServiceManager::scope() const
Returns the scope used for registering and searching of services.
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.
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.
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.
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.