QIviAbstractFeature Class
The QIviAbstractFeature is the base class for all QtIvi Features. More...
| Header: | #include <QIviAbstractFeature> |
| qmake: | QT += ivicore |
| Instantiated By: | AbstractFeature |
| Inherits: | QObject and QQmlParserStatus |
| Inherited By: | QIviAbstractZonedFeature, QIviAmFmTuner, QIviMediaIndexerControl, and QIviMediaPlayer |
Public Types
| enum | DiscoveryMode { NoAutoDiscovery, AutoDiscovery, LoadOnlyProductionBackends, LoadOnlySimulationBackends } |
| enum | DiscoveryResult { NoResult, ErrorWhileLoading, ProductionBackendLoaded, SimulationBackendLoaded } |
| enum | Error { NoError, PermissionDenied, InvalidOperation, Timeout, InvalidZone, Unknown } |
Properties
|
|
Public Functions
| QIviAbstractFeature(const QString &interface, QObject *parent = nullptr) | |
| QIviAbstractFeature::DiscoveryMode | discoveryMode() const |
| QIviAbstractFeature::DiscoveryResult | discoveryResult() const |
| QIviAbstractFeature::Error | error() const |
| QString | errorMessage() const |
| bool | isInitialized() const |
| bool | isValid() const |
| QIviServiceObject * | serviceObject() const |
Public Slots
| void | setDiscoveryMode(QIviAbstractFeature::DiscoveryMode discoveryMode) |
| bool | setServiceObject(QIviServiceObject *so) |
| QIviAbstractFeature::DiscoveryResult | startAutoDiscovery() |
Signals
| void | discoveryModeChanged(QIviAbstractFeature::DiscoveryMode discoveryMode) |
| void | discoveryResultChanged(QIviAbstractFeature::DiscoveryResult discoveryResult) |
| void | errorChanged(QIviAbstractFeature::Error error, const QString &message) |
| void | isInitializedChanged(bool isInitialized) |
| void | isValidChanged(bool arg) |
| void | serviceObjectChanged() |
Protected Functions
| virtual bool | acceptServiceObject(QIviServiceObject *serviceObject) |
| virtual void | clearServiceObject() = 0 |
| virtual void | connectToServiceObject(QIviServiceObject *serviceObject) |
| virtual void | disconnectFromServiceObject(QIviServiceObject *serviceObject) |
| QString | errorText() const |
| QString | interfaceName() const |
| void | setError(QIviAbstractFeature::Error error, const QString &message = QString()) |
Reimplemented Protected Functions
| virtual void | componentComplete() override |
Protected Slots
| virtual void | onErrorChanged(QIviAbstractFeature::Error error, const QString &message = QString()) |
Detailed Description
QIviAbstractFeature is the base class for the front facing API towards the developer. The QIviAbstractFeature provides you with a way to automatically connect to a backend implementing the interface needed. This discovery is started by using the startAutoDiscovery() function.
Once the auto discovery is done, it can be checked whether a backend has been found by using the isValid function.
The auto discovery gives you an easy way to automatically connect to the right backend implementation. If you don't want to use the auto discovery, it's also possible to use QIviServiceManager to retrieve all Backends and search manually for the right one and connect it to the QIviAbstractFeature by calling setServiceObject().
The type of backend to be loaded can be controlled by setting the auto discovery mode. By default, it is set to AutoDiscovery, which indicates that a production backend will be preferred over a simulation backend.
QIviAbstractFeature is an abstract base class that needs to be subclassed to create an API for your Feature.
Subclassing
When subclassing QIviAbstractFeature, you must provide implementations of the following functions:
Once a QIviServiceObject has been set, either by auto discovery or by manually setting it, the acceptServiceObject() function will be called to make sure the QIviServiceObject provides everything needed by the Feature.
If the interface provides signals, you need to do all the connect statements in connectToServiceObject() and disconnect them again in disconnectFromServiceObject().
clearServiceObject() will be called once the Feature doesn't have a connection to a ServiceObject anymore and should reset its state to sane defaults.
Member Type Documentation
enum QIviAbstractFeature::DiscoveryMode
| Constant | Value | Description |
|---|---|---|
QIviAbstractFeature::NoAutoDiscovery | 0 | No auto discovery is done and the ServiceObject needs to be set manually |
QIviAbstractFeature::AutoDiscovery | 1 | Tries to first find a production backend with a matching interface and falls back to a simulation backend if not found |
QIviAbstractFeature::LoadOnlyProductionBackends | 2 | Only tries to load a production backend with a matching interface |
QIviAbstractFeature::LoadOnlySimulationBackends | 3 | Only tries to load a simulation backend with a matching interface |
enum QIviAbstractFeature::DiscoveryResult
| Constant | Value | Description |
|---|---|---|
QIviAbstractFeature::NoResult | 0 | Indicates that no auto discovery was started because the feature has already assigned a valid ServiceObject |
QIviAbstractFeature::ErrorWhileLoading | 1 | An error has happened while searching for a backend with a matching interface |
QIviAbstractFeature::ProductionBackendLoaded | 2 | As a result of the auto discovery a production backend was loaded |
QIviAbstractFeature::SimulationBackendLoaded | 3 | As a result of the auto discovery a simulation backend was loaded |
enum QIviAbstractFeature::Error
| Constant | Value | Description |
|---|---|---|
QIviAbstractFeature::NoError | 0 | No error |
QIviAbstractFeature::PermissionDenied | 1 | Permission for the operation is denied |
QIviAbstractFeature::InvalidOperation | 2 | Operation is invalid |
QIviAbstractFeature::Timeout | 3 | Operation timeout |
QIviAbstractFeature::InvalidZone | 4 | Zone is not available for the operation |
QIviAbstractFeature::Unknown | 5 | Unknown error |
Property Documentation
discoveryMode : QIviAbstractFeature::DiscoveryMode
Holds the mode that is used for the autoDiscovery
Note: If you change this property after the Feature is instantiated you need to call startAutoDiscovery() to search for a new Service Object
Access functions:
| QIviAbstractFeature::DiscoveryMode | discoveryMode() const |
| void | setDiscoveryMode(QIviAbstractFeature::DiscoveryMode discoveryMode) |
Notifier signal:
| void | discoveryModeChanged(QIviAbstractFeature::DiscoveryMode discoveryMode) |
discoveryResult : const QIviAbstractFeature::DiscoveryResult
This property holds the result of the last autoDiscovery
Access functions:
| QIviAbstractFeature::DiscoveryResult | discoveryResult() const |
Notifier signal:
| void | discoveryResultChanged(QIviAbstractFeature::DiscoveryResult discoveryResult) |
See also startAutoDiscovery().
error : const QString
Last error message of the feature. Empty if no error.
Access functions:
| QString | errorMessage() const |
Notifier signal:
| void | errorChanged(QIviAbstractFeature::Error error, const QString &message) |
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 QIviFeatureInterface::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 QIviFeatureInterface::initializationDone.
isValid : const bool
Indicates whether the feature is ready to use.
The property is true if the feature is ready to be used, otherwise false. Not being ready 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 QIviServiceObject, discoveryMode, and isInitialized.
serviceObject : QIviServiceObject*
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 Service Object is already set to exactly this instance or the Service Object doesn't get accepted by the feature.
Access functions:
| QIviServiceObject * | serviceObject() const |
| bool | setServiceObject(QIviServiceObject *so) |
Notifier signal:
| void | serviceObjectChanged() |
See also discoveryMode.
Member Function Documentation
QIviAbstractFeature::QIviAbstractFeature(const QString &interface, QObject *parent = nullptr)
Constructs an abstract feature.
The parent argument is passed on to the QObject constructor.
The interface argument is used to locate suitable service objects.
[virtual protected slot] void QIviAbstractFeature::onErrorChanged(QIviAbstractFeature::Error error, const QString &message = QString())
Updates error and message from the backend.
This slot can be used when implementing a new Feature to report generic errors.
[slot] QIviAbstractFeature::DiscoveryResult QIviAbstractFeature::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 QIviAbstractFeature::NoAutoDiscovery this function will do nothing and return QIviAbstractFeature::NoResult.
See also discoveryMode() and Dynamic Backend System.
[virtual protected] bool QIviAbstractFeature::acceptServiceObject(QIviServiceObject *serviceObject)
This method is expected to be implemented by any class subclassing QIviAbstractFeature.
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 QIviAbstractFeature::clearServiceObject()
This method is expected to be implemented by any class subclassing QIviAbstractFeature.
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.
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 QIviAbstractFeature::componentComplete()
Reimplements: QQmlParserStatus::componentComplete().
Invoked automatically when used from QML. Calls startAutoDiscovery().
[virtual protected] void QIviAbstractFeature::connectToServiceObject(QIviServiceObject *serviceObject)
This method is expected to be implemented by any class subclassing QIviAbstractFeature.
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 QIviFeatureInterface and calls QIviFeatureInterface::initialize() afterwards.
When reimplementing please keep in mind to connect all signals before calling this function. e.g.
/code void SimpleFeature::connectToServiceObject(QIviServiceObject *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() QIviAbstractFeature::connectToServiceObject(serviceObject);
// Additional initialization functions can be added here } /endcode
See also acceptServiceObject(), disconnectFromServiceObject(), and clearServiceObject().
[virtual protected] void QIviAbstractFeature::disconnectFromServiceObject(QIviServiceObject *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().
QIviAbstractFeature::Error QIviAbstractFeature::error() const
Returns the last error code.
See also setError() and QIviAbstractFeature::Error.
[protected] QString QIviAbstractFeature::errorText() const
Returns the current error code converted from QIviAbstractFeature::Error to QString
See also error.
[protected] QString QIviAbstractFeature::interfaceName() const
Returns the interface name this Feature is implementing.
When the Feature discovers a matching backend, this interface name needs to be supported by the Service Object the Feature is connecting to.
See Extending Qt IVI for more information.
[protected] void QIviAbstractFeature::setError(QIviAbstractFeature::Error error, const QString &message = QString())
Sets error with the message.
Emits errorChanged() signal.
See also error() and QIviAbstractZonedFeature::Error.
© 2020 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.