QRemoteServiceRegister Class

The QRemoteServiceRegister class manages instances of remote service objects. More...

Header: #include <QRemoteServiceRegister>

Public Types

class Entry
enum InstanceType { GlobalInstance, PrivateInstance }
flags SecurityAccessOptions

Properties

Public Functions

QRemoteServiceRegister(QObject *parent = Q_NULLPTR)
virtual ~QRemoteServiceRegister()
Entry createEntry(const QString &serviceName, const QString &interfaceName, const QString &version)
qintptr getBaseGroupIdentifier() const
qintptr getBaseUserIdentifier() const
void publishEntries(const QString &ident)
bool quitOnLastInstanceClosed() const
void setBaseGroupIdentifier(qintptr gid)
void setBaseUserIdentifier(qintptr uid)
void setQuitOnLastInstanceClosed(const bool quit)
void setSecurityAccessOptions(SecurityAccessOptions options)
SecurityFilter setSecurityFilter(SecurityFilter filter)

Signals

void allInstancesClosed()
void instanceClosed(const QRemoteServiceRegister::Entry &entry)

Detailed Description

This class registers and publishes IPC based service objects. It owns the service's objects and uses the platform specific IPC mechanism to publish the service.

In order for the remote services to be discoverable by QServiceManager each QRemoteServiceRegister::Entry must be registered with the same information in the XML description, otherwise no corresponding QServiceInterfaceDescriptor can be found.

The following XML descriptor is used for subsequent examples.

 <SFW version="1.1">
 <service>
     <name>MyService</name>
     <ipcaddress>my_executable</ipcaddress>
     <description>My service example</description>
     <interface>
         <name>com.nokia.qt.example.myService</name>
         <version>1.0</version>
         <description>My private service</description>
         <capabilities></capabilities>
     </interface>
 </service>
 </SFW>

The snippet belows demonstrates how an application can register the class MyClass as a remote service, which is published and accessible to clients who wish to load service object instances.

 int main(int argc, char** argv)
 {
     QCoreApplication app(argc, argv);

     QRemoteServiceRegister *serviceRegister = new QRemoteServiceRegister();

     QRemoteServiceRegister::Entry myService;
     myService = serviceRegister->createEntry<MyClass>(
         "MyService", "com.nokia.qt.example.myservice", "1.0");

     serviceRegister->publishEntries("my_service");

     return app.exec();
     delete serviceRegister;
 }

By default all entries are created as QRemoteServiceRegister::PrivateInstance types. This can be changed by calling QRemoteServiceRegister::Entry::setInstantiationType() on the entry. Once the service register has been published the associated service entries can no longer be changed.

See also QRemoteServiceRegister::Entry.

Member Type Documentation

enum QRemoteServiceRegister::InstanceType

Defines the two types of instances for a registration entry

ConstantValueDescription
QRemoteServiceRegister::GlobalInstance0New requests for a service gets the same service instance
QRemoteServiceRegister::PrivateInstance1New requests for a service gets a new service instance

Property Documentation

quitOnLastInstanceClosed : bool

Terminate the service when all clients have closed all objects. Default value is true.

Access functions:

bool quitOnLastInstanceClosed() const
void setQuitOnLastInstanceClosed(const bool quit)

Member Function Documentation

QRemoteServiceRegister::QRemoteServiceRegister(QObject *parent = Q_NULLPTR)

Creates a service register instance with the given parent.

[signal] void QRemoteServiceRegister::allInstancesClosed()

This signal is emitted whenever all service instances have been closed. This indicates that the last connected client has either shutdown or released the loaded service object.

See also instanceClosed().

[signal] void QRemoteServiceRegister::instanceClosed(const QRemoteServiceRegister::Entry &entry)

This signal is emitted whenever a created instance has been closed. This indicates that a connected client has either shutdown or released the loaded service object.

entry is supplied to identify which registered service entry the closed instance belonged to.

See also allInstancesClosed().

[virtual] QRemoteServiceRegister::~QRemoteServiceRegister()

Destroys the service register instance

template <typename T> Entry QRemoteServiceRegister::createEntry(const QString &serviceName, const QString &interfaceName, const QString &version)

Creates an entry on our remote instance manager. The serviceName, interfaceName and version must match the service XML descriptor in order for the remote service to be discoverable.

See also publishEntries().

qintptr QRemoteServiceRegister::getBaseGroupIdentifier() const

Get the group id set on the socket or pipe.

This function was introduced in Qt 5.0.

qintptr QRemoteServiceRegister::getBaseUserIdentifier() const

Get the user id set on the socket or pipe.

This function was introduced in Qt 5.0.

void QRemoteServiceRegister::publishEntries(const QString &ident)

Publishes every service QRemoteServiceRegister::Entry that has been created using createEntry(). The ident is the service specific IPC address under which the service can be reached.

This address must match the address provided in the services XML descriptor, otherwise the service will not be discoverable. In some cases this may also cause the IPC rendezvous feature to fail.

See also createEntry().

void QRemoteServiceRegister::setBaseGroupIdentifier(qintptr gid)

Set the group id for the socket or pipe. For backends that use sockets or pipes and provide filesystem based access control.

This function was introduced in Qt 5.0.

void QRemoteServiceRegister::setBaseUserIdentifier(qintptr uid)

Set the user id for the socket or pipe. For backends that use sockets or pipes and provide filesystem based access control.

This function was introduced in Qt 5.0.

void QRemoteServiceRegister::setSecurityAccessOptions(SecurityAccessOptions options)

Set the socket access control. This sets the file system permissions on that socket.

This function was introduced in Qt 5.0.

SecurityFilter QRemoteServiceRegister::setSecurityFilter(SecurityFilter filter)

Allows a security filter to be set which can access QRemoteServiceRegister::QRemoteServiceRegisterCredentials.

The filter is a function pointer where the function code implements possible permission checks and returns true or false. If a connecting client fails the security filter it will be denied access and unable to obtain a valid service instance.

The following snippet is an example of how to use the security filter feature.

 bool myFunction(const void *p)
 {
     const QRemoteServiceRegisterCredentials *cred =
         (const struct QRemoteServiceRegisterCredentials *)p;

     // allow the superuser
     if (cred->uid == 0)
         return true;

     return false;
 }

 int main(int argc, char** argv)
 {
     ...

     QRemoteServiceRegister* serviceRegister = new QRemoteServiceRegister();
     service->setSecurityFilter(myFunction);

     ...
 }