guh - Developer documentation

DevicePlugin Class

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

Header: #include <DevicePlugin>
Inherits:

Public Functions

DevicePlugin(QObject * parent = 0)
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 guhTimer()
virtual void init()
virtual void networkManagerReplyReady(QNetworkReply * reply)
PluginId pluginId() const
QString pluginName() const
virtual void postSetupDevice(Device * device)
virtual void radioData(const QList<int> & rawData)
virtual DeviceManager::HardwareResources requiredHardware() const = 0
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()
virtual void upnpDiscoveryFinished(const QList<UpnpDeviceDescriptor> & upnpDeviceDescriptorList)
virtual void upnpNotifyReceived(const QByteArray & notifyData)

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

QtAvahiServiceBrowser * avahiServiceBrowser() const
DeviceManager * deviceManager() const
Device * findDeviceByParams(const ParamList & params) const
QList<Device *> myDevices() const
QNetworkReply * networkManagerGet(const QNetworkRequest & request)
QNetworkReply * networkManagerPost(const QNetworkRequest & request, const QByteArray & data)
QNetworkReply * networkManagerPut(const QNetworkRequest & request, const QByteArray & data)
bool transmitData(int delay, QList<int> rawData, int repetitions = 10)
void upnpDiscover(QString searchTarget = "ssdp:all", QString userAgent = QString())

Detailed Description

This is the base class interface for device plugins.

When implementing a new plugin, start by subclassing this and implementing the following pure virtual method DevicePlugin::requiredHardware()

Member Function Documentation

DevicePlugin::DevicePlugin(QObject * parent = 0)

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 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.

[protected] QtAvahiServiceBrowser * DevicePlugin::avahiServiceBrowser() const

Returns the pointer to the central service browser.

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, such as DevicePlugin::radioData() or DevicePlugin::guhTimer(). 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.

[virtual] void DevicePlugin::guhTimer()

If the plugin has requested the timer using DevicePlugin::requiredHardware(), this slot will be called on timer events.

[virtual] void DevicePlugin::init()

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

[protected] QList<Device *> DevicePlugin::myDevices() const

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

[protected] QNetworkReply * DevicePlugin::networkManagerGet(const QNetworkRequest & request)

Posts a request to obtain the contents of the target request and returns a new QNetworkReply object opened for reading which emits the replyReady() signal whenever new data arrives. The contents as well as associated headers will be downloaded.

Note: The plugin has to delete the QNetworkReply with the function deleteLater().

See also NetworkAccessManager::get().

[protected] QNetworkReply * DevicePlugin::networkManagerPost(const QNetworkRequest & request, const QByteArray & data)

Sends an HTTP POST request to the destination specified by request and returns a new QNetworkReply object opened for reading that will contain the reply sent by the server. The contents of the data will be uploaded to the server.

Note: The plugin has to delete the QNetworkReply with the function deleteLater().

See also NetworkAccessManager::post().

[protected] QNetworkReply * DevicePlugin::networkManagerPut(const QNetworkRequest & request, const QByteArray & data)

Uploads the contents of data to the destination request and returnes a new QNetworkReply object that will be open for reply.

Note: The plugin has to delete the QNetworkReply with the function deleteLater().

See also NetworkAccessManager::put().

[virtual] void DevicePlugin::networkManagerReplyReady(QNetworkReply * reply)

This method will be called whenever a pending network reply for this plugin is finished.

Note: Only if if the plugin has requested the DeviceManager::HardwareResourceNetworkManager resource using DevicePlugin::requiredHardware(), this slot will be called.

See also NetworkAccessManager::replyReady().

[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().

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.

[virtual] void DevicePlugin::radioData(const QList<int> & rawData)

If the plugin has requested any radio device using DevicePlugin::requiredHardware(), this slot will be called when there is rawData available from that device.

[pure virtual] DeviceManager::HardwareResources DevicePlugin::requiredHardware() const

Return flags describing the common hardware resources required by this plugin. If you want to use more than one resource, you can combine them ith the OR operator.

See also DeviceManager::HardwareResource.

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.

[protected] bool DevicePlugin::transmitData(int delay, QList<int> rawData, int repetitions = 10)

Transmits data contained in rawData on the Radio433 devices, depending on the hardware requested by this plugin. Returns true if, the rawData with a certain delay (pulse length) can be sent repetitions times.

See also Radio433 and requiredHardware().

[protected] void DevicePlugin::upnpDiscover(QString searchTarget = "ssdp:all", QString userAgent = QString())

Starts a SSDP search for a certain searchTarget (ST). Certain UPnP devices need a special ST (i.e. "udap:rootservice" for LG Smart Tv's), otherwise they will not respond on the SSDP search. Each HTTP request to this device needs sometimes also a special userAgent, which will be written into the HTTP header.

See also DevicePlugin::requiredHardware() and DevicePlugin::upnpDiscoveryFinished().

[virtual] void DevicePlugin::upnpDiscoveryFinished(const QList<UpnpDeviceDescriptor> & upnpDeviceDescriptorList)

If the plugin has requested the UPnP device list using DevicePlugin::upnpDiscover(), this slot will be called after 3 seconds (search timeout). The upnpDeviceDescriptorList will contain the description of all UPnP devices available in the network.

See also upnpDiscover(), UpnpDeviceDescriptor, and UpnpDiscovery::discoveryFinished().

[virtual] void DevicePlugin::upnpNotifyReceived(const QByteArray & notifyData)

If a UPnP device will notify a NOTIFY message in the network, the UpnpDiscovery will catch the notification data and call this method with the notifyData.

Note: Only if if the plugin has requested the DeviceManager::HardwareResourceUpnpDisovery resource using DevicePlugin::requiredHardware(), this slot will be called.

See also UpnpDiscovery.