• DevicePlugin
  • DevicePlugin Class

    This is the base class interface for device plugins. More...

    Header: #include <DevicePlugin>
    Inherits:

    Public Functions

    DevicePlugin(QObject * parent = nullptr)
    virtual ~DevicePlugin()
    QVariant configValue(const ParamTypeId & paramTypeId) const
    ParamList configuration() const
    QList<ParamType> configurationDescription() const
    virtual DeviceManager::DeviceSetupStatus confirmPairing(const PairingTransactionId & pairingTransactionId, const DeviceClassId & deviceClassId, const ParamList & params, const QString & secret)
    virtual void deviceRemoved(Device * device)
    virtual DeviceManager::DeviceError discoverDevices(const DeviceClassId & deviceClassId, const ParamList & params)
    virtual DeviceManager::DeviceError displayPin(const PairingTransactionId & pairingTransactionId, const DeviceDescriptor & deviceDescriptor)
    virtual DeviceManager::DeviceError executeAction(Device * device, const Action & action)
    virtual void init()
    QString pluginDisplayName() const
    PluginId pluginId() const
    QString pluginName() const
    virtual void postSetupDevice(Device * device)
    DeviceManager::DeviceError setConfigValue(const ParamTypeId & paramTypeId, const QVariant & value)
    DeviceManager::DeviceError setConfiguration(const ParamList & configuration)
    bool setLocale(const QLocale & locale)
    virtual DeviceManager::DeviceSetupStatus setupDevice(Device * device)
    virtual void startMonitoringAutoDevices()
    QList<DeviceClass> supportedDevices() const
    QList<Vendor> supportedVendors() const
    QTranslator * translator()

    Signals

    void actionExecutionFinished(const ActionId & id, DeviceManager::DeviceError status)
    void autoDeviceDisappeared(const DeviceId & id)
    void autoDevicesAppeared(const DeviceClassId & deviceClassId, const QList<DeviceDescriptor> & deviceDescriptors)
    void configValueChanged(const ParamTypeId & paramTypeId, const QVariant & value)
    void deviceSetupFinished(Device * device, DeviceManager::DeviceSetupStatus status)
    void devicesDiscovered(const DeviceClassId & deviceClassId, const QList<DeviceDescriptor> & devices)
    void emitEvent(const Event & event)
    void pairingFinished(const PairingTransactionId & pairingTransactionId, DeviceManager::DeviceSetupStatus status)

    Protected Functions

    DeviceManager * deviceManager() const
    Device * findDeviceByParams(const ParamList & params) const
    HardwareManager * hardwareManager() const
    Devices myDevices() const

    Detailed Description

    This is the base class interface for device plugins.

    Member Function Documentation

    DevicePlugin::DevicePlugin(QObject * parent = nullptr)

    DevicePlugin constructor. DevicePlugins will be instantiated by the DeviceManager, its parent.

    [virtual] DevicePlugin::~DevicePlugin()

    Virtual destructor...

    [signal] void DevicePlugin::actionExecutionFinished(const ActionId & id, DeviceManager::DeviceError status)

    This signal is to be emitted when you previously have returned DeviceErrorAsync in a call of executeAction(). The id refers to the executed Action. The status of the Action execution will be described as DeviceError.

    [signal] void DevicePlugin::autoDeviceDisappeared(const DeviceId & id)

    Emit this signal when a device with the given id and which was created by DevicePlugin::autoDevicesAppeared has been removed from the system. Be careful with this, as this will completely remove the device from the system and with it all the associated rules. Only emit this if you are sure that a device will never come back. This signal should not be emitted for child auto devices when the parent who created them is removed. The system will automatically remove all child devices in such a case.

    [signal] void DevicePlugin::autoDevicesAppeared(const DeviceClassId & deviceClassId, const QList<DeviceDescriptor> & deviceDescriptors)

    This signal is emitted when a new Device of certain deviceClassId appeared. The description of the Devices will be in deviceDescriptors. This signal can only emitted from devices with the CreateMethodAuto.

    QVariant DevicePlugin::configValue(const ParamTypeId & paramTypeId) const

    Use this to retrieve the values for your parameters. Values might not be set at the time when your plugin is loaded, but will be set soon after. Listen to configurationValueChanged() to know when something changes. When implementing a new plugin, specify in configurationDescription() what you want to see here. Returns the config value of a Param with the given paramTypeId of this DevicePlugin.

    See also setConfigValue().

    [signal] void DevicePlugin::configValueChanged(const ParamTypeId & paramTypeId, const QVariant & value)

    This signal is emitted when the Param with a certain paramTypeId of a Device configuration changed the value.

    ParamList DevicePlugin::configuration() const

    Returns a map containing the plugin configuration. When implementing a new plugin, override this and fill in the empty configuration if your plugin requires any.

    See also setConfiguration().

    QList<ParamType> DevicePlugin::configurationDescription() const

    Returns the configuration description of this DevicePlugin as a list of ParamTypes.

    [virtual] DeviceManager::DeviceSetupStatus DevicePlugin::confirmPairing(const PairingTransactionId & pairingTransactionId, const DeviceClassId & deviceClassId, const ParamList & params, const QString & secret)

    Confirms the pairing of a deviceClassId with the given pairingTransactionId and params. Returns DeviceError to inform about the result. The optional paramerter secret contains for example the pin for Devices with the setup method DeviceClass::SetupMethodDisplayPin.

    [protected] DeviceManager * DevicePlugin::deviceManager() const

    Returns a pointer to the DeviceManager. When implementing a plugin, use this to find the Devices you need.

    [virtual] void DevicePlugin::deviceRemoved(Device * device)

    This will be called when a device removed. The plugin has the chance to do some teardown. The device is still valid during this call, but already removed from the system. The device will be deleted as soon as this method returns.

    [signal] void DevicePlugin::deviceSetupFinished(Device * device, DeviceManager::DeviceSetupStatus status)

    This signal is emitted when the setup of a device in this DevicePlugin is finished. The status parameter describes the DeviceError that occurred.

    [signal] void DevicePlugin::devicesDiscovered(const DeviceClassId & deviceClassId, const QList<DeviceDescriptor> & devices)

    This signal is emitted when the discovery of a deviceClassId of this DevicePlugin is finished. The devices parameter describes the list of DeviceDescriptors of all discovered Devices.

    See also discoverDevices().

    [virtual] DeviceManager::DeviceError DevicePlugin::discoverDevices(const DeviceClassId & deviceClassId, const ParamList & params)

    Reimplement this if you support a DeviceClass with createMethod CreateMethodDiscovery. This will be called to discover Devices for the given deviceClassId with the given params. This will always be an async operation. Return DeviceErrorAsync or DeviceErrorNoError if the discovery has been started successfully. Return an appropriate error otherwise. Once devices are discovered, emit devicesDiscovered().

    [virtual] DeviceManager::DeviceError DevicePlugin::displayPin(const PairingTransactionId & pairingTransactionId, const DeviceDescriptor & deviceDescriptor)

    This method will be called for Devices with the DeviceClass::SetupMethodDisplayPin right after the paring request with the given pairingTransactionId for the given deviceDescriptor.

    [signal] void DevicePlugin::emitEvent(const Event & event)

    To produce a new event in the system, create a new Event and emit it with event. Usually events are emitted in response to incoming data or other other events happening. Find a configured Device from the DeviceManager and get its EventTypes, then create a Event complying to that EventType and emit it here.

    [virtual] DeviceManager::DeviceError DevicePlugin::executeAction(Device * device, const Action & action)

    This will be called to actually execute actions on the hardware. The {Device} and the {Action} are contained in the device and action parameters. Return the appropriate DeviceError.

    It is possible to execute actions asynchronously. You never should do anything blocking for a long time (e.g. wait on a network reply from the internet) but instead return DeviceManager::DeviceErrorAsync and continue processing in an async manner. Once you have the reply ready, emit actionExecutionFinished() with the appropriate parameters.

    See also actionExecutionFinished().

    [protected] Device * DevicePlugin::findDeviceByParams(const ParamList & params) const

    Find a certain device from myDevices() by its params. All parameters must match or the device will not be found. Be prepared for nullptrs.

    [protected] HardwareManager * DevicePlugin::hardwareManager() const

    Returns the pointer to the main HardwareManager of this server.

    [virtual] void DevicePlugin::init()

    This will be called after constructing the DevicePlugin. Override this to do any initialisation work you need to do.

    [protected] Devices DevicePlugin::myDevices() const

    Returns a list of all configured devices belonging to this plugin.

    [signal] void DevicePlugin::pairingFinished(const PairingTransactionId & pairingTransactionId, DeviceManager::DeviceSetupStatus status)

    This signal is emitted when the pairing of a pairingTransactionId is finished. The status of the will be described as DeviceError.

    See also confirmPairing().

    QString DevicePlugin::pluginDisplayName() const

    Returns the displayName of this DevicePlugin, to be shown to the user, translated.

    PluginId DevicePlugin::pluginId() const

    Returns the id of this DevicePlugin. When implementing a plugin, generate a new uuid and return it here. Always return the same uuid and don't change it or configurations can't be matched any more.

    QString DevicePlugin::pluginName() const

    Returns the name of this DevicePlugin.

    [virtual] void DevicePlugin::postSetupDevice(Device * device)

    This will be called when a new device was added successfully and the device setup is finished.

    DeviceManager::DeviceError DevicePlugin::setConfigValue(const ParamTypeId & paramTypeId, const QVariant & value)

    Can be called in the DevicePlugin to set a plugin's Param with the given paramTypeId and value.

    See also configValue().

    DeviceManager::DeviceError DevicePlugin::setConfiguration(const ParamList & configuration)

    Will be called by the DeviceManager to set a plugin's configuration.

    See also configuration().

    bool DevicePlugin::setLocale(const QLocale & locale)

    Returns true if the given locale could be set for this DevicePlugin.

    [virtual] DeviceManager::DeviceSetupStatus DevicePlugin::setupDevice(Device * device)

    This will be called when a new device is created. The plugin has the chance to do some setup. Return DeviceSetupStatusFailure if something bad happened during the setup in which case the device will be disabled. Return DeviceSetupStatusSuccess if everything went well. If you can't tell yet and need more time to set up the device (note: you should never block in this method) you can return DeviceSetupStatusAsync. In that case the DeviceManager will wait for you to emit deviceSetupFinished to report the status.

    [virtual] void DevicePlugin::startMonitoringAutoDevices()

    Override this if your plugin supports Device with DeviceClass::CreationMethodAuto. This will be called at startup, after the configured devices have been loaded. This is the earliest time you should start emitting autoDevicesAppeared(). If you are monitoring some hardware/service for devices to appear, start monitoring now. If you are building the devices based on a static list, you may emit autoDevicesAppeard() in here.

    QList<DeviceClass> DevicePlugin::supportedDevices() const

    Return a list of DeviceClasses describing all the devices supported by this plugin. If a DeviceClass has an invalid parameter it will be ignored.

    QList<Vendor> DevicePlugin::supportedVendors() const

    Returns the list of Vendors supported by this DevicePlugin.

    QTranslator * DevicePlugin::translator()

    Returns the translator of this DevicePlugin.