/**************************************************************************** ** ** Copyright (C) 2017 The Qt Company Ltd and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. ** ** $QT_BEGIN_LICENSE:FDL$ ** Commercial License Usage ** Licensees holding valid commercial Qt licenses may use this file in ** accordance with the commercial license agreement provided with the ** Software or, alternatively, in accordance with the terms contained in ** a written agreement between you and The Qt Company. For licensing terms ** and conditions see https://www.qt.io/terms-conditions. For further ** information use the contact form at https://www.qt.io/contact-us. ** ** GNU Free Documentation License Usage ** Alternatively, this file may be used under the terms of the GNU Free ** Documentation License version 1.3 as published by the Free Software ** Foundation and appearing in the file included in the packaging of ** this file. Please review the following information to ensure ** the GNU Free Documentation License version 1.3 requirements ** will be met: https://www.gnu.org/licenses/fdl-1.3.html. ** $QT_END_LICENSE$ ** ****************************************************************************/ /*! \group servicefw \title Service Frameworks Classes A set of APIs to that allows clients to discover and instantiate arbitrary services. */ /*! \page service-frameworks.html \title Qt Service Framework \brief A set of Qt APIs to that allows clients to discover and instantiate arbitrary services. \ingroup technology-apis The Qt Service Framework allows clients to discover and instantiate arbitrary services. \tableofcontents \section1 Introduction The Qt Service Framework defines a unified way of finding, implementing and accessing services across multiple platforms. Due to the service frameworks knowledge of service interfaces, their versions, and QObject-based introspection, it may even be used to unify and access multiple platform specific service implementations via the same Qt-based client application. \section1 Getting Started To load the Qt Service Framework module into your .qml files, add the following \qml import QtServiceFramework 5.0 \endqml For C++ files you will need to add the directive \code #include \endcode And for linking against the module add this to your qmake .pro file \code QT += serviceframework \endcode \section1 Overview A service is an independent component that allows a client to perform a well-defined operation. Clients can find services based on their name and version as well as the interface that is implemented by the service object. Once the service has been identified the framework starts the service and returns a pointer to it. QServiceManager is the main interface through which clients can access the mentioned framework functionality. In addition services themselves may also act as clients to the service framework by requesting other services installed on the system. Service provider are implemented via plug-ins. QServicePluginInterface defines the main interface for each plug-in. In order to avoid that clients have to link against service specific libraries each service object must be derived from QObject. Therefore the QMetaObject system can be used to dynamically discover and invoke the service's capabilities. To achieve the best level of access via the Qt meta object system services should be implemented in such a way that their entire functionality is accessible via signals, slots, properties or invokable functions (see Q_INVOKABLE macro for more details). Each service plug-in implements one service only but can provide multiple implementations for multiple interfaces. Therefore a service (plug-in) can retain a certain level of backwards compatibility even if the main service interface breaks in such a way that a new interface name has to be used. Existing clients can still use the previous version of service interface whereas new clients can utilize the new interface. Services can also include remote processes. By registering with the service manager processes can communicate via signals, slots, invokable functions and properties as if they were local objects. Services can choose to be either shared between all clients, or unique to that client. \section1 Using the Framework This section assumes that the user wants to access the \e FileStorage service which offers an implementation for the \e com.nokia.qt.examples.FileStorage interface The service framework enables multiple ways of accessing those implementations. QServiceManager is the main class to lookup and instantiate services. Services can be found by constraining the search via service meta data or by using the default lookup mechanism. \section2 Verbose Lookup The client code has precise knowledge of the service and its interfaces. \code QServiceManager manager; QServiceFilter filter("com.nokia.qt.examples.FileStorage"); filter.setServiceName("FileStorage"); // find services complying with filter QList foundServices; foundServices = manager.findInterfaces(filter); Q_ASSERT(foundServices.count()); // instantiate the FileStorage object QObject *fileStorage; fileStorage = manager.loadInterface(foundServices.at(0)); \endcode \section2 Default Lookup It is assumed that the client has knowledge of the interface but does not really care about the specific type or version of the service implementing the interface. In such cases the default service lookup can be utilized to create a service object instance. \code QServiceManager manager; manager.setInterfaceDefault("FileStorageService", "com.nokia.qt.examples.FileStorage"); \endcode The above call to \l QServiceManager::setInterfaceDefault() registers the \e FileStorageService as default implementation. Whenever a client asks for an implementation of \e com.nokia.qt.examples.FileStorage the \e FileStorageService service will be loaded. If (at the time of this call) the \e FileStorageService provides multiple registered implementations/versions for the same interface the latest version becomes the default. Therefore subsequent versions of the same interface must always be binary compatible to previous versions. The current scope of the service manager object determines whether the default assignment is valid for all users or whether it is valid for the current user only. The system default is used if the user scope has not been defined. This enables users to customize their personal preferences. By default the first service installing a so far unknown interface becomes the system wide default selection. \section3 \b{QObject based services} This is the most common way of interacting with services. \code storage = manager.loadInterface("com.nokia.qt.examples.FileStorage"); if (storage) QMetaObject::invokeMethod(storage, "deleteFile", Q_ARG(QString, "/tmp/readme.txt")); \endcode The above invocation of the file storage object's deleteFile() function is done via the service's QMetaObject. The client does not require any knowledge of the objects actual type and therefore does not have to link against a service specific library. \section3 \b{Typed services} So far all lookup mechanism returned a QObject pointer. This pointer can be utilized by introspecting the object, using Qt's meta object system. However in some use cases it may be more convenient to directly interact with the service object by including the service header and/or linking against the service provider. The main advantage is compile time checking. Its disadvantage is that client and service must share the implementation of the service object via a library they link against or via a common header file. Note that such sharing breaks the fundamental ServiceFramework principle of separating clients from service as changes of the service type may require changes to both, services and clients. The subsequent code snippet demonstrates how this may look like: \code #include ... QServiceManager manager; FileStorage *storage = 0; ... storage = manager.loadLocalTypedInterface("com.nokia.qt.examples.FileStorage"); if (storage) storage->deleteFile("/tmp/readme.txt"); \endcode \section1 Service Scope The QServiceManager operates in either \l{QService::UserScope}{User scope} or \l{QService::SystemScope}{System scope}. By default, it operates in user scope. The choice of scope affects whether registered services are available system-wide or only to the current user, and whether service and interface lookups are limited to system-wide service or whether the current user's together with system service configurations are considered. \section2 User Scope In user scope, services are registered in a storage location specific to the current user. When a default service is set for an interface using \l{QServiceManager::setInterfaceDefault()}{setInterfaceDefault()}, the referenced service can be either a user-specific or system-wide service. For service and interface lookups, a manager will first search the user-specific services; if the requested component is not found, the manager then searches the system-wide services, if the user has sufficient permissions to do so. The \l{QServiceManager::serviceAdded()} and \l{QServiceManager::serviceRemoved()} notifications are emitted when services are added or removed from either the user-specific or system-wide services. These signals have a \c scope parameter to indicate the scope in which the service was added or removed. (Note the system-wide service notifications are only available if the user has sufficient permissions to access the system-wide service storage.) \section2 System Scope In system scope, services are registered in a system-wide storage location. The manager does not access user-specific services for any operations. Service and interface lookups fail if the requested services are not found in the system-wide service storage. Service registration is performed in the system-wide storage. If \l{QServiceManager::setInterfaceDefault()}{setInterfaceDefault()} is called for a user-specific service, the operation fails. Also, the \l{QServiceManager::serviceAdded()} and \l{QServiceManager::serviceRemoved()} notifications are only emitted for system-wide services. \section1 Adding and Removing of Services New services can be installed and removed at runtime. An XML file is used to describe the service meta data and links the service code to its meta description. \section2 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: \code \endcode The elements and attributes have the following meanings: \table \header \li Element \li SubElement \li Description \row \li SFW \li \li The service framework XML version tag that encapsulates the service XML. Must provide the version attribute that follows the \e major.minor notation and must equate to supported Qt Service Framework versions. This means the minimum version is 1.0 however users are recommended to always specify the highest available version. \row \li service \li \li The \e service tag can contain an arbitrary number of \e interface tags and one description tag. \row \li " \li description \li A user readable description of the purpose of the service. \row \li " \li filepath \li The absolute path and name of the plug-in to be loaded when this service is requested. Alternatively if the plug-in name only is provided the standard library paths (see QCoreApplication::libraryPaths()) are used to find the plug-in. Note that if the plugin name is given only, platform specific parts such as the suffix ".dll" and ".so" or plugin prefix "lib" should be removed to enable cross platform resolution. QLibrary is used to determine the platform specific parts of the plugin. \row \li " \li ipcaddress \li The socket name or path that the inter-process service will be published on that will provide clients with remote access. Should be the same name as the executable for the service without any suffix such as ".exe" etc. \row \li " \li name \li The name of the service. \row \li interface \li \li The \e interface describes the properties of the interface. \row \li " \li capabilities \li This property is a list of arbitrary strings which are interpreted as permissions/capabilities. The list elements are comma-separated and spaces after commas are not permitted. This list can be empty. \row \li " \li name \li The name of the interface using the Java class name notation. (e.g. com.nokia.qt.TestService) \row \li " \li version \li This property contains the interface and implementation version. The version tag follows the \e major.minor notation. The major version indicates the interface version the minor version the implementation version. The version number \b must be greater than 1.0. The version cannot be less than 1.0 because the Service Framework is dependent on the fact that services must be binary compatible between major versions, and services with versions less than 1.0 are unlikely to be binary compatible with later versions. \row \li " \li description \li A user readable description of the purpose of the interface. \row \li " \li customproperty \li An implementation specific key value pair which can be used for filtering or as description. \endtable An example for a valid XML service description could be the following \e TestService: \code TestService testserviceplugin Test service description com.nokia.qt.ILocation 1.4 Interface that provides location support com.nokia.qt.ILocation 1.5 Interface that provides location support com.nokia.qt.ISysInfo ReadUserData 2.3 Interface that provides system information support value1 value2 \endcode \section1 Tools for XML Generation The framework includes a GUI tool under \tt 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 plugin or IPC based service. It can also be used to load and inspect existing service XML files. Note that the tool will default to the highest known existing Qt Service Framework version as the XML version attribute and subsequent saves on loaded files will enforce this default version. Here is a screenshot of the application, loaded with the \e TestService XML description provided above. \image servicexmlgen.png \section1 Installing the Service at Runtime New services can be added and removed at any time via QServiceManager::addService() and QServiceManager::removeService(). \section1 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 \e com.nokia.qt.ILocation: \code QServiceManager mgr; QServiceFilter filter; filter.setInterface("com.nokia.qt.ILocation"); QList 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); } \endcode \section2 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. \section1 Out of Process Services Qt Service Framework provides a mechanism for out of process services so that clients can remotely load interfaces. These inter-process services are deployed similarly to local services, using the IPC address tag from the XML description and calling QRemoteServiceRegister::publishEntries() to add the service to the remote services manager. Clients access services via the metaobject similarly to in-process services and each remote service is represented as a QRemoteServiceRegister::Entry by using QRemoteServiceRegister::createEntry(). The remote dialer service example demonstrates using a out of process service. Inter-process services are deployed using a variety of different IPC mechanisms available on the current platform and as such may inherit several limitations. For some linux environments services can published using QtDBus otherwise it falls back on QLocalSocket for inter-process communication. \section2 D-Bus Services The QtDBus module is used to provide IPC in correspondence to the Qt Service Framework architecture and provides access to signals, slots, invokable methods and properties. The D-Bus protocol requires concept identifiers that represent D-Bus objects: service names, object paths, and interfaces. D-Bus objects are registered using a combination of the service description supplied in the service XML file. An example of this, using the previous sample XML description, is provided below. \table 90% \header \li D-Bus Concept \li Derived Name \row \li Service Name \li "com.qtmobility.sfw.TestService" \row \li Object Path \li "/com/nokia/qt/ILocation/1/4/" \row \li Interface \li "" \endtable \section3 Limitations When using integer types for arguments to signals and slots, bass types as defined by http://doc.qt.nokia.com/4.7/qdbustypesystem.html. For example, quint64 is generally equivalent to qulonglong, but all unsigned 64 bit values must be defined as qulonglong or they will not work with the dbus implementation. For more details and the current state of the limitation please refer to bug \l {http://bugreports.qt.io/browse/QTMOBILITY-1694}{QTMOBILITY-1694}. A current known limitation for Qt Service Framework using QtDBus for IPC is that enumerators cannot be read due to lack of support on D-Bus. This will be added in future versions once the QtDBus module enables enumerator support. A current known workaround is to manually define and use integers as demonstrated in the \l{Service Framework using QML Example}{Declarative Serviceframework Dialer} example. Furthermore, due to the nature of IPC, pointers to objects cannot be passed between services and clients. Unfortunately, this also means that anything wrapped in a typedef macro cannot be communicated effectively between processes. \section3 Service Autostart D-Bus services inherit automatic start support by providing .service files to the D-Bus daemon search paths. Aside from producing these files manually, the servicefw tool provides an option to generate the corresponding files inside the local user D-Bus folder for convenience. This will allow all client requests to automatically startup the service if it isn't already running. Consequently, once every client has closed its service instance the service will be automatically terminated after invoking any slots connected to notification signals. Running the following command will enable rendezvous for D-Bus IPC. \code ./servicefw dbusservice \endcode The .service files will typically be generated in the $home/.local/share/dbus-1/services directory unless the $$XDG_DATA_HOME environment variable is set. If the --system option is used the tool will generate the file inside /usr/share/dbus-1/services if the user permissions are met. Note that in order for the autostart feature to function correctly, the service needs to be either pre-registered or registered at run-time so that clients can use a QServiceManager to discover the IPC interfaces that invoke the D-Bus service files. This is usually done on deployment by adding services through the servicefw tool. \section2 Local Socket On platforms that do not provide D-Bus or do not use it, the underlying IPC mechanism utilized is a local socket based protocol. \section3 Limitations Similar to the other IPC mechanisms, passing object pointers or typedefs will not work on local socket. Local socket also requires the executable for the service to be installed somewhere in your PATH for autostart to work. Not all platforms support all fields on the QRemoteServiceRegisterCredentials and will return -1 in unsupported fields. \section3 Service Autostart This mechanism provides automatic service startup. The tag must be set to the executable filename. For example xyzabc must be used if the executable is xyzabc, or xyzabc.exe on windows systems. The PATH is searched for the executable. If the executable is not found, or the service does not start, then the error is reported to the client. \section3 Service Registration All services must be registered. The 'servicefw' tool registers xml files. It must be run before a service can be used. For example: \code servicefw add \endcode \section3 Service Security Service objects can filter the clients that are allowed to connect to them. This is done by creating an invokable constructor that has a QServiceClientCredentials as its first and only paramter. For example: \code class ExampleService : public QObject { Q_OBJECT public: ExampleService(QObject* parent = 0) : QObject(parent) { // this constructor will not be called } Q_INVOKABLE ExampleService(QServiceClientCredentials *creds) : QObject(0) { if (creds->getUserIdentifier() == 0) creds->setClientAccepted(true); else creds->setClientAccepted(false); } }; \endcode The new invokable constructor will be called instead of the default constructor. Client credentials are passed in via the QServiceClientCredetials class. If the client wishes to authorize the connection it must call either setClientAccepted(true) or call setClientAccepted(false) to reject the client. If the client is rejected the constructor should return immediatly, and object will be destroyed. If the object is a global object multiple clients can connect to the same object. On construction the secure constructor will be called. For subsequent client connections the invokable method "void verifyNewServiceClientCredentials(QServiceClientCredentials *creds)" will be called to authenticate new client connections. For example a global class maybe defined as: \code class GlobalService : public QObject { Q_OBJECT public: GlobalService(QObject* parent = 0) : QObject(parent) { // this constructor will not be called } Q_INVOKABLE GlobalService(QServiceClientCredentials *creds) : QObject(0) { if (creds->getUserIdentifier() == 0) creds->setClientAccepted(true); else creds->setClientAccepted(false); } Q_INVOKABLE void verifyNewServiceClientCredentials(QServiceClientCredentials *creds) { if (creds->getUserIdentifier() == 0) creds->setClientAccepted(true); else creds->setClientAccepted(false); } }; \endcode For global objects, when the first client connects the secure constructor is called. Subsequent connections will result in the verifyNewServiceClientCredentials being called. When the last client disconnected the object will be destroyed, and the constructor will be called when the next client connects. \section3 Service Security Filters The service can install a security filter to reject connections from some clients on initial connection. Service security described above allows this to be controlled per object. This is implemented on D-Bus and local socket implementations of IPC. \code void securityFilter(QServiceClientCredentials *creds) { if (creds->getUserIdentifier() == 0) { creds->setClientAccepted(true); // accept the connection } else { creds->setClientAccepted(false); // reject the connection } } \endcode By calling QServiceClientCredentials::setClientAccepted the connection can be terminated or accepted. Certain platforms do not provide all the results, and undefined values are set to -1. Registration of the filter is done by calling QRemoteServiceRegister::setSecurityFilter(). Only 1 filter maybe installed at one time. \section2 Error handling Out of process services behave similarly to local services, with one exception. There can be IPC errors, or the remote service can terminate unexpectedly. QObjects returned by the service manager for out of process services have an additional signal created, errorUnrecoverableIPCFault(QService::UnrecoverableIPCError) which the client must connect to. If an error occurs the object must be destroyed; no further calls can be made. The error recovery is left up to the client application. \section1 Main Classes \annotatedlist servicefw \section1 QML Elements The Qt Service Framework offers discovery and selection of services through declarative UI by providing service and service list elements. Detailed information can be found at \l{QML Service Framework Plugin}. \annotatedlist qml-serviceframework \section1 Examples \list \li \l{dialer}{Declarative Serviceframework Dialer} \endlist */