guh - Developer documentation

DeviceManager Class

The main entry point when interacting with Devices More...

Header: #include <DeviceManager>
Inherits:

Public Types

enum DeviceError { DeviceErrorNoError, DeviceErrorPluginNotFound, DeviceErrorVendorNotFound, DeviceErrorDeviceNotFound, ..., DeviceErrorParameterNotWritable }
enum DeviceSetupStatus { DeviceSetupStatusSuccess, DeviceSetupStatusFailure, DeviceSetupStatusAsync }
enum HardwareResource { HardwareResourceNone, HardwareResourceRadio433, HardwareResourceTimer, HardwareResourceNetworkManager, HardwareResourceUpnpDisovery, HardwareResourceBluetoothLE }
flags HardwareResources

Public Functions

DeviceManager(const QLocale & locale, QObject * parent = 0)
~DeviceManager()
DeviceError addConfiguredDevice(const DeviceClassId & deviceClassId, const QString & name, const ParamList & params, const DeviceId id = DeviceId::createDeviceId())
DeviceError addConfiguredDevice(const DeviceClassId & deviceClassId, const QString & name, const DeviceDescriptorId & deviceDescriptorId, const DeviceId & deviceId = DeviceId::createDeviceId())
QList<Device *> configuredDevices() const
DeviceError confirmPairing(const PairingTransactionId & pairingTransactionId, const QString & secret = QString())
DeviceError discoverDevices(const DeviceClassId & deviceClassId, const ParamList & params)
DeviceError editDevice(const DeviceId & deviceId, const QString & name)
QList<Device *> findChildDevices(const DeviceId & id) const
Device * findConfiguredDevice(const DeviceId & id) const
QList<Device *> findConfiguredDevices(const DeviceClassId & deviceClassId) const
DeviceClass findDeviceClass(const DeviceClassId & deviceClassId) const
DeviceError pairDevice(const PairingTransactionId & pairingTransactionId, const DeviceClassId & deviceClassId, const QString & name, const ParamList & params)
DeviceError pairDevice(const PairingTransactionId & pairingTransactionId, const DeviceClassId & deviceClassId, const QString & name, const DeviceDescriptorId & deviceDescriptorId)
DevicePlugin * plugin(const PluginId & id) const
QList<DevicePlugin *> plugins() const
DeviceError reconfigureDevice(const DeviceId & deviceId, const ParamList & params, bool fromDiscovery = false)
DeviceError reconfigureDevice(const DeviceId & deviceId, const DeviceDescriptorId & deviceDescriptorId)
DeviceError removeConfiguredDevice(const DeviceId & deviceId)
void setLocale(const QLocale & locale)
DeviceError setPluginConfig(const PluginId & pluginId, const ParamList & pluginConfig)
QList<DeviceClass> supportedDevices(const VendorId & vendorId = VendorId()) const
QList<Vendor> supportedVendors() const
DeviceError verifyParam(const QList<ParamType> paramTypes, const Param & param)
DeviceError verifyParam(const ParamType & paramType, const Param & param)
DeviceError verifyParams(const QList<ParamType> paramTypes, ParamList & params, bool requireAll = true)

Public Slots

DeviceError executeAction(const Action & action)
void timeTick()

Signals

void actionExecutionFinished(const ActionId & actionId, DeviceManager::DeviceError status)
void deviceAdded(Device * device)
void deviceChanged(Device * device)
void deviceDisappeared(const DeviceId & deviceId)
void deviceReconfigurationFinished(Device * device, DeviceError status)
void deviceRemoved(const DeviceId & deviceId)
void deviceSetupFinished(Device * device, DeviceError status)
void deviceStateChanged(Device * device, const QUuid & stateTypeId, const QVariant & value)
void devicesDiscovered(const DeviceClassId & deviceClassId, const QList<DeviceDescriptor> & devices)
void eventTriggered(const Event & event)
void languageUpdated()
void loaded()
void pairingFinished(const PairingTransactionId & pairingTransactionId, DeviceError status, const DeviceId & deviceId = DeviceId())
void pluginConfigChanged(const PluginId & id, const ParamList & config)

Static Public Members

QStringList pluginSearchDirs()
QList<QJsonObject> pluginsMetadata()

Detailed Description

The main entry point when interacting with Devices

The DeviceManager hold s all information about supported and configured Devices in the system.

It is also responsible for loading Plugins and managing common hardware resources between device plugins.

Member Type Documentation

enum DeviceManager::DeviceError

This enum type specifies the errors that can happen when working with Devices.

ConstantValueDescription
DeviceManager::DeviceErrorNoError0No Error. Everything went fine.
DeviceManager::DeviceErrorPluginNotFound1Couldn't find the Plugin for the given id.
DeviceManager::DeviceErrorVendorNotFound2Couldn't find the Vendor for the given id.
DeviceManager::DeviceErrorDeviceNotFound3Couldn't find a Device for the given id.
DeviceManager::DeviceErrorDeviceClassNotFound4Couldn't find a DeviceClass for the given id.
DeviceManager::DeviceErrorActionTypeNotFound5Couldn't find the ActionType for the given id.
DeviceManager::DeviceErrorStateTypeNotFound6Couldn't find the StateType for the given id.
DeviceManager::DeviceErrorEventTypeNotFound7Couldn't find the EventType for the given id.
DeviceManager::DeviceErrorDeviceDescriptorNotFound8Couldn't find the DeviceDescriptor for the given id.
DeviceManager::DeviceErrorMissingParameter9Parameters do not comply to the template.
DeviceManager::DeviceErrorInvalidParameter10One of the given parameter is not valid.
DeviceManager::DeviceErrorSetupFailed11Error setting up the Device. It will not be functional.
DeviceManager::DeviceErrorDuplicateUuid12Error setting up the Device. The given DeviceId already exists.
DeviceManager::DeviceErrorCreationMethodNotSupported13Error setting up the Device. This CreateMethod is not supported for this Device.
DeviceManager::DeviceErrorSetupMethodNotSupported14Error setting up the Device. This SetupMethod is not supported for this Device.
DeviceManager::DeviceErrorHardwareNotAvailable15The Hardware of the Device is not available.
DeviceManager::DeviceErrorHardwareFailure16The Hardware of the Device has an error.
DeviceManager::DeviceErrorAsync18The response of the Device will be asynchronously.
DeviceManager::DeviceErrorDeviceInUse19The Device is currently bussy.
DeviceManager::DeviceErrorPairingTransactionIdNotFound22Couldn't find the PairingTransactionId for the given id.
DeviceManager::DeviceErrorAuthentificationFailure17The device could not authentificate with something.
DeviceManager::DeviceErrorDeviceIsChild21The device is a child device and can not be deleted directly.
DeviceManager::DeviceErrorDeviceInRule20The device is in a rule and can not be deleted withou guhserver::RuleEngine::RemovePolicy.
DeviceManager::DeviceErrorParameterNotWritable23One of the given device params is not writable.

enum DeviceManager::DeviceSetupStatus

This enum type specifies the setup status of a Device.

ConstantValueDescription
DeviceManager::DeviceSetupStatusSuccess0No Error. Everything went fine.
DeviceManager::DeviceSetupStatusFailure1Something went wrong during the setup.
DeviceManager::DeviceSetupStatusAsync2The status of the Device setup will be emitted asynchronous.

enum DeviceManager::HardwareResource
flags DeviceManager::HardwareResources

This enum type specifies hardware resources which can be requested by DevicePlugins.

ConstantValueDescription
DeviceManager::HardwareResourceNone0No Resource required.
DeviceManager::HardwareResourceRadio4331Refers to the 433 MHz radio.
DeviceManager::HardwareResourceTimer2Refers to the global timer managed by the DeviceManager. Plugins should not create their own timers, but rather request the global timer using the hardware resources.
DeviceManager::HardwareResourceNetworkManager4Allows to send network requests and receive replies.
DeviceManager::HardwareResourceUpnpDisovery8Allows to search a UPnP devices in the network.
DeviceManager::HardwareResourceBluetoothLE16Allows to interact with bluetooth low energy devices.

The HardwareResources type is a typedef for QFlags<HardwareResource>. It stores an OR combination of HardwareResource values.

Member Function Documentation

DeviceManager::DeviceManager(const QLocale & locale, QObject * parent = 0)

Constructs the DeviceManager with the given locale and parent. There should only be one DeviceManager in the system created by guhserver::GuhCore. Use guhserver::GuhCore::instance()->deviceManager() instead to access the DeviceManager.

DeviceManager::~DeviceManager()

Destructor of the DeviceManager. Each loaded DevicePlugin will be deleted.

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

The DeviceManager will emit a this signal when the Action with the given actionId is finished. The status of the Action execution will be described as DeviceError.

DeviceError DeviceManager::addConfiguredDevice(const DeviceClassId & deviceClassId, const QString & name, const ParamList & params, const DeviceId id = DeviceId::createDeviceId())

Add a new configured device for the given DeviceClass, the given parameters, name and id. deviceClassId must refer to an existing {DeviceClass} and params must match the parameter description in the DeviceClass. Optionally you can supply an id yourself if you must keep track of the added device. If you don't supply it, a new one will be generated. Only devices with CreateMethodUser can be created using this method. Returns DeviceError to inform about the result.

DeviceError DeviceManager::addConfiguredDevice(const DeviceClassId & deviceClassId, const QString & name, const DeviceDescriptorId & deviceDescriptorId, const DeviceId & deviceId = DeviceId::createDeviceId())

Add a new configured device for the given DeviceClass the given DeviceDescriptorId and deviceId. Only devices with CreateMethodDiscovery can be created using this method. The deviceClassId must refer to an existing DeviceClass and the deviceDescriptorId must refer to an existing DeviceDescriptorId from the discovery. The name parameter should contain the device name. Returns DeviceError to inform about the result.

QList<Device *> DeviceManager::configuredDevices() const

Returns all configured {Device}{Devices} in the system.

DeviceError DeviceManager::confirmPairing(const PairingTransactionId & pairingTransactionId, const QString & secret = QString())

Confirms the pairing of a Device with the given pairingTransactionId and secret. Returns DeviceError to inform about the result.

[signal] void DeviceManager::deviceAdded(Device * device)

This signal is emitted when a device was added to the system. This signal will create the Devices.DeviceAdded notification.

[signal] void DeviceManager::deviceChanged(Device * device)

This signal is emitted when a device was changed in the system (by edit or rediscover). This signal will create the Devices.DeviceParamsChanged notification.

[signal] void DeviceManager::deviceDisappeared(const DeviceId & deviceId)

[signal] void DeviceManager::deviceReconfigurationFinished(Device * device, DeviceError status)

This signal is emitted when the edit process of a device is finished. The status parameter describes the DeviceError that occurred.

[signal] void DeviceManager::deviceRemoved(const DeviceId & deviceId)

This signal is emitted when the Device with the given deviceId was removed from the system. This signal will create the Devices.DeviceRemoved notification.

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

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

[signal] void DeviceManager::deviceStateChanged(Device * device, const QUuid & stateTypeId, const QVariant & value)

This signal is emitted when the State of a device changed. The stateTypeId parameter describes the StateType and the value parameter holds the new value.

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

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

See also discoverDevices().

DeviceError DeviceManager::discoverDevices(const DeviceClassId & deviceClassId, const ParamList & params)

Returns a certain DeviceError and starts the discovering process of the Device with the given deviceClassId and the given params.

DeviceError DeviceManager::editDevice(const DeviceId & deviceId, const QString & name)

Edit the name of the Device with the given deviceId. Returns DeviceError to inform about the result.

[signal] void DeviceManager::eventTriggered(const Event & event)

The DeviceManager will emit a Event described in event whenever a Device creates one. Normally only guhserver::GuhCore should connect to this and execute actions after checking back with the {guhserver::RulesEngine}. Exceptions might be monitoring interfaces or similar, but you should never directly react to this in a DevicePlugin.

[slot] DeviceError DeviceManager::executeAction(const Action & action)

Execute the given Action. This will find the Device action refers to the deviceId() and its DevicePlugin. Then will dispatch the execution to the DevicePlugin.

QList<Device *> DeviceManager::findChildDevices(const DeviceId & id) const

Returns all child Devices of the given device.

Device * DeviceManager::findConfiguredDevice(const DeviceId & id) const

Returns the Device with the given id. Null if the id couldn't be found.

QList<Device *> DeviceManager::findConfiguredDevices(const DeviceClassId & deviceClassId) const

Returns all Devices matching the DeviceClass referred by deviceClassId.

DeviceClass DeviceManager::findDeviceClass(const DeviceClassId & deviceClassId) const

For conveninece, this returns the DeviceClass with the id given by deviceClassId. Note: The returned DeviceClass may be invalid.

[signal] void DeviceManager::languageUpdated()

[signal] void DeviceManager::loaded()

The DeviceManager will emit this signal when all Devices are loaded.

DeviceError DeviceManager::pairDevice(const PairingTransactionId & pairingTransactionId, const DeviceClassId & deviceClassId, const QString & name, const ParamList & params)

Initiates a pairing with a Device with the given pairingTransactionId, deviceClassId, name and params. Returns DeviceError to inform about the result.

DeviceError DeviceManager::pairDevice(const PairingTransactionId & pairingTransactionId, const DeviceClassId & deviceClassId, const QString & name, const DeviceDescriptorId & deviceDescriptorId)

Initiates a pairing with a Device with the given pairingTransactionId, deviceClassId, name and deviceDescriptorId. Returns DeviceError to inform about the result.

[signal] void DeviceManager::pairingFinished(const PairingTransactionId & pairingTransactionId, DeviceError status, const DeviceId & deviceId = DeviceId())

The DeviceManager will emit a this signal when the pairing of a Device with the deviceId and pairingTransactionId is finished. The status of the pairing will be described as DeviceError.

DevicePlugin * DeviceManager::plugin(const PluginId & id) const

Returns the DevicePlugin with the given id. Null if the id couldn't be found.

[signal] void DeviceManager::pluginConfigChanged(const PluginId & id, const ParamList & config)

[static] QStringList DeviceManager::pluginSearchDirs()

Returns the list of search direcorys where DevicePlugin will be searched.

QList<DevicePlugin *> DeviceManager::plugins() const

Returns all the DevicePlugins loaded in the system.

[static] QList<QJsonObject> DeviceManager::pluginsMetadata()

Returns the list of json objects containing the metadata of the installed plugins.

DeviceError DeviceManager::reconfigureDevice(const DeviceId & deviceId, const ParamList & params, bool fromDiscovery = false)

Edit the Params of a configured device with the given deviceId to the new given params. The given parameter fromDiscovery specifies if the new params came from a discovery or if the user set them. If it came from discovery not writable parameters (readOnly) will be changed too.

Returns DeviceError to inform about the result.

DeviceError DeviceManager::reconfigureDevice(const DeviceId & deviceId, const DeviceDescriptorId & deviceDescriptorId)

Edit the Params of a configured device to the Params of the DeviceDescriptor with the given deviceId to the given DeviceDescriptorId. Only devices with CreateMethodDiscovery can be changed using this method. The deviceDescriptorId must refer to an existing DeviceDescriptorId from the discovery. This method allows to rediscover a device and update it's Params.

Returns DeviceError to inform about the result.

DeviceError DeviceManager::removeConfiguredDevice(const DeviceId & deviceId)

Removes a Device with the given deviceId from the list of configured Devices. This method also deletes all saved settings of the Device. Returns DeviceError to inform about the result.

void DeviceManager::setLocale(const QLocale & locale)

Set the locale of all plugins and reload the translated strings.

DeviceError DeviceManager::setPluginConfig(const PluginId & pluginId, const ParamList & pluginConfig)

Returns a certain DeviceError and sets the configuration of the plugin with the given pluginId and the given pluginConfig.

QList<DeviceClass> DeviceManager::supportedDevices(const VendorId & vendorId = VendorId()) const

Returns all the supported DeviceClasses by all DevicePlugins loaded in the system. Optionally filtered by vendorId.

QList<Vendor> DeviceManager::supportedVendors() const

Returns all the Vendors loaded in the system.

[slot] void DeviceManager::timeTick()

Centralized time tick for the GuhTimer resource. Ticks every second.

DeviceError DeviceManager::verifyParam(const QList<ParamType> paramTypes, const Param & param)

Verify if the given param matches one of the given paramTypes. Returns DeviceError to inform about the result.

DeviceError DeviceManager::verifyParam(const ParamType & paramType, const Param & param)

Verify if the given param matches the given paramType. Returns DeviceError to inform about the result.

DeviceError DeviceManager::verifyParams(const QList<ParamType> paramTypes, ParamList & params, bool requireAll = true)

Verify if the given params matche the given paramTypes. Ith requireAll is true, all Params has to be valid. Returns DeviceError to inform about the result.