QIfAbstractFeature Class

The QIfAbstractFeature is the base class for all QtInterfaceFramework Features. More...

Header: #include <QIfAbstractFeature>
qmake: QT += interfaceframework
Instantiated By: AbstractFeature
Inherits: QObject and QQmlParserStatus
Inherited By:

QIfAbstractZonedFeature, QIfAmFmTuner, QIfMediaIndexerControl, and QIfMediaPlayer

Public Types

enum DiscoveryMode { InvalidAutoDiscovery, NoAutoDiscovery, AutoDiscovery, LoadOnlyProductionBackends, LoadOnlySimulationBackends }
enum DiscoveryResult { NoResult, ErrorWhileLoading, ProductionBackendLoaded, SimulationBackendLoaded }
enum Error { NoError, PermissionDenied, InvalidOperation, Timeout, InvalidZone, Unknown }

Properties

Public Functions

QIfAbstractFeature(const QString &interfaceName, QObject *parent = nullptr)
QString configurationId() const
QIfAbstractFeature::DiscoveryMode discoveryMode() const
QIfAbstractFeature::DiscoveryResult discoveryResult() const
QIfAbstractFeature::Error error() const
QString errorMessage() const
bool isInitialized() const
bool isValid() const
QStringList preferredBackends() const
QIfServiceObject *serviceObject() const

Public Slots

void setConfigurationId(const QString &configurationId)
void setDiscoveryMode(QIfAbstractFeature::DiscoveryMode discoveryMode)
void setPreferredBackends(const QStringList &preferredBackends)
bool setServiceObject(QIfServiceObject *so)
QIfAbstractFeature::DiscoveryResult startAutoDiscovery()

Signals

void configurationIdChanged(const QString &configurationId)
void discoveryModeChanged(QIfAbstractFeature::DiscoveryMode discoveryMode)
void discoveryResultChanged(QIfAbstractFeature::DiscoveryResult discoveryResult)
void errorChanged(QIfAbstractFeature::Error error, const QString &message)
void isInitializedChanged(bool isInitialized)
void isValidChanged(bool arg)
void preferredBackendsChanged(const QStringList &preferredBackends)
void serviceObjectChanged()

Protected Functions

virtual bool acceptServiceObject(QIfServiceObject *serviceObject)
virtual void clearServiceObject() = 0
virtual void connectToServiceObject(QIfServiceObject *serviceObject)
virtual void disconnectFromServiceObject(QIfServiceObject *serviceObject)
QString errorText() const
QString interfaceName() const
void setError(QIfAbstractFeature::Error error, const QString &message = QString())

Reimplemented Protected Functions

virtual void componentComplete() override

Protected Slots

virtual void onErrorChanged(QIfAbstractFeature::Error error, const QString &message = QString())

Detailed Description

QIfAbstractFeature is the base class for the front-facing API towards the developer. Subclass QIfAbstractFeature to create an API for your feature.

QIfAbstractFeature provides you with auto discovery: a way to automatically connect to a backend that implements the required interface. To discover a backend, use the startAutoDiscovery() function. Once auto discovery is complete, use the isValid() function to check whether a suitable backend was found.

The auto discovery gives you an easy way to automatically connect to the correct backend implementation and can be controlled by the discoveryMode property. The discoveryMode is set to AutoDiscovery by default, which indicates that a production backend is always preferred over a simulation backend.

Alternatively, it's also possible to use QIfServiceManager to retrieve all backends. Then, manually search for the right backend and call setServiceObject() to connect it to the QIfAbstractFeature.

Write a Subclass

Your QIfAbstractFeature subclass must provide implementations for the following functions:

Once a QIfServiceObject has been set, either via startAutoDiscovery() or setServiceObject(), call the acceptServiceObject() function to make sure that the feature you've implemented can work with the QIfServiceObject and, in turn, the QIfServiceObject provides the required interface.

If the interface provides signals, you need to make all the connect statements in connectToServiceObject(); then disconnect them in disconnectFromServiceObject().

clearServiceObject() is called once the feature doesn't have a connection to a ServiceObject anymore and needs to reset its state to feasible defaults.

Member Type Documentation

enum QIfAbstractFeature::DiscoveryMode

ConstantValueDescription
QIfAbstractFeature::InvalidAutoDiscovery-1An invalid value. This value is used when the enum is created from a string value (e.g. when parsed from a ini file) and it failed to parse the string.
QIfAbstractFeature::NoAutoDiscovery0No auto discovery is done and the ServiceObject needs to be set manually.
QIfAbstractFeature::AutoDiscovery1The feature first tries to find a production backend with a matching interface. If it's not available, then the feature falls back to a simulation backend.
QIfAbstractFeature::LoadOnlyProductionBackends2The feature tries to load a production backend with a matching interface only.
QIfAbstractFeature::LoadOnlySimulationBackends3The feature tries to load a simulation backend with a matching interface only.

enum QIfAbstractFeature::DiscoveryResult

ConstantValueDescription
QIfAbstractFeature::NoResult0Indicates that no auto discovery was started because the feature already has a valid ServiceObject assigned.
QIfAbstractFeature::ErrorWhileLoading1An error has occurred while searching for a backend with a matching interface.
QIfAbstractFeature::ProductionBackendLoaded2A production backend was loaded, as a result of auto discovery.
QIfAbstractFeature::SimulationBackendLoaded3A simulation backend was loaded, as a result of auto discovery.

enum QIfAbstractFeature::Error

ConstantValueDescription
QIfAbstractFeature::NoError0No error
QIfAbstractFeature::PermissionDenied1Permission for the operation is denied
QIfAbstractFeature::InvalidOperation2Operation is invalid
QIfAbstractFeature::Timeout3Operation timeout
QIfAbstractFeature::InvalidZone4Zone is not available for the operation
QIfAbstractFeature::Unknown5Unknown error

Property Documentation

configurationId : QString

Holds the id to determine which configuration this feature belongs to.

Once the id has been set, it is possible to change certain values using the QIfConfiguration API.

Note: Values set in the matching QIfConfiguration can override the initial values set during the component creation.

Access functions:

QString configurationId() const
void setConfigurationId(const QString &configurationId)

Notifier signal:

void configurationIdChanged(const QString &configurationId)

See also QIfConfiguration.

discoveryMode : QIfAbstractFeature::DiscoveryMode

Holds the mode that is used for the autoDiscovery

Note: If you change this property after the feature is instantiated, make sure to call startAutoDiscovery() to search for a new service object.

Access functions:

QIfAbstractFeature::DiscoveryMode discoveryMode() const
void setDiscoveryMode(QIfAbstractFeature::DiscoveryMode discoveryMode)

Notifier signal:

void discoveryModeChanged(QIfAbstractFeature::DiscoveryMode discoveryMode)

[read-only] discoveryResult : const QIfAbstractFeature::DiscoveryResult

This property holds the result of the last autoDiscovery

Access functions:

QIfAbstractFeature::DiscoveryResult discoveryResult() const

Notifier signal:

void discoveryResultChanged(QIfAbstractFeature::DiscoveryResult discoveryResult)

See also startAutoDiscovery().

[read-only] error : const QString

Last error message of the feature. Empty if no error.

Access functions:

QString errorMessage() const

Notifier signal:

void errorChanged(QIfAbstractFeature::Error error, const QString &message)

[read-only] isInitialized : const bool

Indicates whether the feature has been initialized with all the values from the backend.

The property is true once the backend sends the QIfFeatureInterface::initializationDone signal to indicate that all values have now been initialized with values from the backend.

Access functions:

bool isInitialized() const

Notifier signal:

void isInitializedChanged(bool isInitialized)

See also isValid and QIfFeatureInterface::initializationDone.

[read-only] isValid : const bool

Indicates whether the feature is ready to use.

The property is true if the feature has an associated service object, otherwise false. Not being valid usually indicates that no suitable service object could be found, or that automatic discovery has not been triggered.

The backend still might not have sent all properties yet and is not fully initialized. Use isInitialized instead to know when the feature holds all correct values.

Access functions:

bool isValid() const

Notifier signal:

void isValidChanged(bool arg)

See also QIfServiceObject, discoveryMode, and isInitialized.

preferredBackends : QStringList

Holds a list of wildcards to load the preferred backend during auto discovery.

The auto discovery mechanism will automatically search for backends which provide a matching interface for this feature implementation. See startAutoDiscovery() for more information.

In case multiple backends implement the same interface, the list of wildcards can be used to determine the correct one to load.

The wildcards are applied in order to the found backends. If the wildcard matches some backends those backends will be loaded, otherwise the next wildcard is used.

For example: Given an AbstractFeature with two backends, backend_mqtt.so and backend_qtro.so, the property can be set to "*_mqtt*" to always select the backend_mqtt.so backend when available.

Access functions:

QStringList preferredBackends() const
void setPreferredBackends(const QStringList &preferredBackends)

Notifier signal:

void preferredBackendsChanged(const QStringList &preferredBackends)

serviceObject : QIfServiceObject*

Sets the service object for the feature.

As Features only expose the front API facing the developer, a service object implementing the actual function is required. This is usually retrieved through the auto discovery mechanism.

The setter for this property returns false if the QIfServiceObject is already set to this particular instance or the QIfServiceObject isn't accepted by the feature.

Access functions:

QIfServiceObject *serviceObject() const
bool setServiceObject(QIfServiceObject *so)

Notifier signal:

void serviceObjectChanged()

See also discoveryMode.

Member Function Documentation

[explicit] QIfAbstractFeature::QIfAbstractFeature(const QString &interfaceName, QObject *parent = nullptr)

Constructs an abstract feature.

The parent argument is passed on to the QObject constructor.

The interfaceName argument is used to locate suitable service objects.

[virtual protected] bool QIfAbstractFeature::acceptServiceObject(QIfServiceObject *serviceObject)

This method is expected to be implemented by any class subclassing QIfAbstractFeature.

The method should return true if the given serviceObject is accepted and can be used, otherwise false.

If the object is accepted, connectToServiceObject is called to actually connect to the service object.

The default implementation accepts the serviceObject if it implements the interface returned by interfaceName();

See also connectToServiceObject(), disconnectFromServiceObject(), and clearServiceObject().

[pure virtual protected] void QIfAbstractFeature::clearServiceObject()

This method is expected to be implemented by any class subclassing QIfAbstractFeature.

Called when no service object is available. The implementation is expected to set all properties to safe defaults and forget all links to the previous service object.

Note: You must emit the corresponding change signals for these properties, so that the feature is informed about the state change. This makes it possible for the implemented class to connect to a new service object afterwards.

There is no need to disconnect from the service object. If it still exists, it is guaranteed that disconnectFromServiceObject is called first.

See also acceptServiceObject(), connectToServiceObject(), and disconnectFromServiceObject().

[override virtual protected] void QIfAbstractFeature::componentComplete()

Reimplements: QQmlParserStatus::componentComplete().

Invoked automatically when used from QML. Calls startAutoDiscovery().

[virtual protected] void QIfAbstractFeature::connectToServiceObject(QIfServiceObject *serviceObject)

This method is expected to be implemented by any class subclassing QIfAbstractFeature.

The implementation should connect to the serviceObject, and set up all properties to reflect the state of the service object.

There is no previous service object connected, as this function call is always preceded by a call to disconnectFromServiceObject or clearServiceObject.

It is safe to assume that the serviceObject, has always been accepted through the acceptServiceObject method prior to being passed to this method.

The default implementation connects to the signals offered by QIfFeatureInterface and calls QIfFeatureInterface::initialize() afterwards.

When reimplementing please keep in mind to connect all signals before calling this function. e.g.

/code void SimpleFeature::connectToServiceObject(QIfServiceObject *serviceObject) { SimpleFeatureBackendInterface *backend = backend(serviceObject); if (!backend) return;

// connect your signals connect(backend, &SimpleFeatureBackendInterface::propertyChanged, this, &SimpleFeature::onPropertyChanged);

// connects the base signals and call initialize() QIfAbstractFeature::connectToServiceObject(serviceObject);

// Additional initialization functions can be added here } /endcode

See also acceptServiceObject(), disconnectFromServiceObject(), and clearServiceObject().

[virtual protected] void QIfAbstractFeature::disconnectFromServiceObject(QIfServiceObject *serviceObject)

This method disconnects all connections to the serviceObject.

There is no need to reset internal variables to safe defaults. A call to this function is always followed by a call to connectToServiceObject or clearServiceObject.

The default implementation disconnects all signals from the serviceObject to this instance.

Most of the times you don't have to reimplement this method. A reimplementation is only needed if multiple interfaces have been connected before or special cleanup calls need to be done to the backend before disconnecting as well. If you need to reimplement this function, please make sure to use the interfaceName() method to retrieve the backend instance and not hardcode it to a particular interfaceName, as otherwise the disconnect calls don't work anymore with derived interfaces.

See also acceptServiceObject(), connectToServiceObject(), and clearServiceObject().

QIfAbstractFeature::Error QIfAbstractFeature::error() const

Returns the last error code.

See also setError() and QIfAbstractFeature::Error.

[protected] QString QIfAbstractFeature::errorText() const

Returns the current error code converted from QIfAbstractFeature::Error to QString

See also error.

[protected] QString QIfAbstractFeature::interfaceName() const

Returns the interface name this feature is implementing.

When the feature discovers a matching backend, this interface's name needs to be supported by the service object that the feature is connecting to.

See Extending Qt Interface Framework for more information.

[virtual protected slot] void QIfAbstractFeature::onErrorChanged(QIfAbstractFeature::Error error, const QString &message = QString())

Updates error and message from the backend.

Use this slot when you implement a new feature to report generic errors.

[protected] void QIfAbstractFeature::setError(QIfAbstractFeature::Error error, const QString &message = QString())

Sets error with the message.

Emits errorChanged() signal.

See also error() and QIfAbstractZonedFeature::Error.

[slot] QIfAbstractFeature::DiscoveryResult QIfAbstractFeature::startAutoDiscovery()

Performs an automatic discovery attempt.

The feature will try to locate a single service object implementing the required interface.

If no service object is found, the feature will stay invalid. If more than one service object is found, the first instance is used.

Either the type of the backend which was loaded or an error is returned.

If the discoveryMode is set to QIfAbstractFeature::NoAutoDiscovery this function will do nothing and return QIfAbstractFeature::NoResult.

See also discoveryMode() and Dynamic Backend System.

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.