ETM-Schurig/powersync-core
Archived
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update docs

Browse Source
This commit is contained in:
Michael Zanetti 2019-10-11 12:36:23 +02:00
parent 0c7a810366
commit 40cbb9fe0a
1 changed files with 107 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

192
libnymea/devices/deviceplugin.cpp
View File

@ -31,50 +31,25 @@
*/ */
/*! \fn void DevicePlugin::devicesDiscovered(const DeviceClassId &deviceClassId, const QList<DeviceDescriptor> &devices);
Emit this signal when the discovery of a \a deviceClassId of this DevicePlugin is finished. The \a devices parameter describes the
list of \l{DeviceDescriptor}{DeviceDescriptors} of all discovered \l{Device}{Devices}.
Note: During a discovery a plugin should always return the full result set. So even if a device is already known to the system and
a later discovery finds the device again, it should be included in the result set but the DeviceDescriptor's deviceId should be set
to the device ID.
\sa discoverDevices()
*/
/*! \fn void DevicePlugin::pairingFinished(const PairingTransactionId &pairingTransactionId, Device::DeviceSetupStatus status);
This signal is emitted when the pairing of a \a pairingTransactionId is finished.
The \a status of the will be described as \l{Device::DeviceError}{DeviceError}.
\sa confirmPairing()
*/
/*! \fn void DevicePlugin::deviceSetupFinished(Device *device, Device::DeviceSetupStatus status);
This signal is emitted when the setup of a \a device in this DevicePlugin is finished. The \a status parameter describes the
\l{Device::DeviceError}{DeviceError} that occurred.
*/
/*! \fn void DevicePlugin::configValueChanged(const ParamTypeId &paramTypeId, const QVariant &value); /*! \fn void DevicePlugin::configValueChanged(const ParamTypeId &paramTypeId, const QVariant &value);
This signal is emitted when the \l{Param} with a certain \a paramTypeId of a \l{Device} configuration changed the \a value. This signal is emitted when the \l{Param} with a certain \a paramTypeId of a \l{Device} configuration changed the \a value.
*/ */
/*! \fn void DevicePlugin::actionExecutionFinished(const ActionId &id, Device::DeviceError status) /*! \fn void DevicePlugin::autoDevicesAppeared(const DeviceDescriptors &deviceDescriptors)
This signal is to be emitted when you previously have returned \l{DeviceManager}{DeviceErrorAsync} A plugin emits this signal when new \l{Device} appeared. For instance a plugin connected to a bridge might detect
in a call of executeAction(). The \a id refers to the executed \l{Action}. The \a status of the \l{Action} that new devices have been connected to the bridge. Emitting this signal will cause those devices to be added
execution will be described as \l{Device::DeviceError}{DeviceError}. to the nymea system and setupDevice will be called for them.
*/
/*! \fn void DevicePlugin::autoDevicesAppeared(const DeviceClassId &deviceClassId, const QList<DeviceDescriptor> &deviceDescriptors)
This signal is emitted when a new \l{Device} of certain \a deviceClassId appeared. The description of the \l{Device}{Devices}
will be in \a deviceDescriptors. This signal can only emitted from devices with the \l{DeviceClass}{CreateMethodAuto}.
*/ */
/*! \fn void DevicePlugin::autoDeviceDisappeared(const DeviceId &id) /*! \fn void DevicePlugin::autoDeviceDisappeared(const DeviceId &id)
Emit this signal when a device with the given \a id and which was created by \l{DevicePlugin::autoDevicesAppeared} has been removed from the system. A plugin emits this signal when a device with the given \a id and which was created by \l{DevicePlugin::autoDevicesAppeared}
Be careful with this, as this will completely remove the device from the system and with it all the associated rules. Only has been removed from the system. When emitting this signal, nymea will remove the device from the system and with it all the
emit this if you are sure that a device will never come back. This signal should not be emitted for child auto devices associated rules and child devices. Because of this, this signal should only be emitted when it's certain that the given device
when the parent who created them is removed. The system will automatically remove all child devices in such a case. will never return to be available any more.
*/ */
/*! \fn void DevicePlugin::emitEvent(const Event &event) /*! \fn void DevicePlugin::emitEvent(const Event &event)
To produce a new event in the system, create a new \l{Event} and emit it with \a event. To produce a new event in the system, a plugin creates a new \l{Event} and emits this signal it with that \a event.
Usually events are emitted in response to incoming data or other other events happening. Find a configured Usually events are emitted in response to incoming data or other other events happening. Find a configured
\l{Device} from the \l{DeviceManager} and get its \l{EventType}{EventTypes}, then \l{Device} from the \l{DeviceManager} and get its \l{EventType}{EventTypes}, then
create a \l{Event} complying to that \l{EventType} and emit it here. create a \l{Event} complying to that \l{EventType} and emit it here.
@ -170,30 +145,40 @@ void DevicePlugin::startMonitoringAutoDevices()
} }
/*! Reimplement this if you support a DeviceClass with createMethod \l{DeviceManager}{CreateMethodDiscovery}. /*! A plugin must reimplement this if it supports a DeviceClass with createMethod \l{DeviceManager}{CreateMethodDiscovery}.
This will be called to discover Devices for the given \a deviceClassId with the given \a params. This will always When the nymea system needs to discover available devices, this will be called on the plugin. The plugin implementation
be an async operation. Return \l{DeviceManager}{DeviceErrorAsync} or \l{DeviceManager}{DeviceErrorNoError} is set to discover devices for the \l{DeviceClassId} given in the \a info object.
if the discovery has been started successfully. Return an appropriate error otherwise. When devices are discovered, they should be added to the info object by calling \l{DeviceDiscoveryInfo::addDeviceDescriptor}.
Once devices are discovered, emit devicesDiscovered(). Once the discovery is complete a plugin must finish it by calling \l{DeviceDiscoveryInfo::finish} using \l{Device::DeviceErrorNoError}
in case of success, or a matching error code otherwise. An optional display message can be passed optionally which might be shown
to the user, indicating more details about the error. The displayMessage must be made translatable by wrapping it in a QT_TR_NOOP()
statement.
A discovery might be cancelled by nymea. In which case the \l{DeviceDiscoveryInfo::aborted} signal will be emitted.
The info object must not be accessed after \l{DeviceDiscoveryInfo::destroyed} is emitted.
*/ */
void DevicePlugin::discoverDevices(DeviceDiscoveryInfo *info) void DevicePlugin::discoverDevices(DeviceDiscoveryInfo *info)
{ {
info->finish(Device::DeviceErrorUnsupportedFeature); info->finish(Device::DeviceErrorUnsupportedFeature);
} }
/*! This will be called when a new device is created. The plugin has the chance to do some setup. /*! This will be called when a new device is created. The plugin can do a setup of the device by reimplementing this method.
Return \l{DeviceManager}{DeviceSetupStatusFailure} if something bad happened during the setup in which case the \a device The passed \a info object will contain the information about the new \l{Device}. When the setup is completed, a plugin
will be disabled. Return \l{DeviceManager}{DeviceSetupStatusSuccess} if everything went well. If you can't tell yet and must finish it by calling \l{DeviceSetupInfo::finish} on the \a info object. In case of success, \{Device::DeviceErrorNoError}
need more time to set up the \a device (note: you should never block in this method) you can must be used, or an appropriate \l{Device::DeviceError} in case of failure. An optional display message can be passed optionally which might be shown
return \l{DeviceManager}{DeviceSetupStatusAsync}. In that case the \l{DeviceManager} will wait for you to emit to the user, indicating more details about the error. The displayMessage must be made translatable by wrapping it in a QT_TR_NOOP()
\l{DevicePlugin}{deviceSetupFinished} to report the status. statement.
A setup might be cancelled by nymea. In which case the \{DeviceSetupInfo::aborted} signal will be emitted.
The info object must not be accessed after \l{DeviceSetupInfo::destroyed} is emitted.
*/ */
void DevicePlugin::setupDevice(DeviceSetupInfo *info) void DevicePlugin::setupDevice(DeviceSetupInfo *info)
{ {
info->finish(Device::DeviceErrorUnsupportedFeature); info->finish(Device::DeviceErrorNoError);
} }
/*! This will be called when a new \a device was added successfully and the device setup is finished.*/ /*! This will be called when a new \a device was added successfully and the device setup is finished. A plugin can optionally
trigger additional code to operate on the device by reimplementing this method.*/
void DevicePlugin::postSetupDevice(Device *device) void DevicePlugin::postSetupDevice(Device *device)
{ {
Q_UNUSED(device) Q_UNUSED(device)
@ -214,7 +199,7 @@ void DevicePlugin::deviceRemoved(Device *device)
SetupMethodOAuth should generate the OAuthUrl which will be opened on the client to allow the user logging in and obtain SetupMethodOAuth should generate the OAuthUrl which will be opened on the client to allow the user logging in and obtain
the OAuth code. the OAuth code.
SetupMethodEnterPin, SetupMethodPushButton and SetupMethodUserAndPassword will typically not require to do anything here. SetupMethodEnterPin, SetupMethodPushButton and SetupMethodUserAndPassword will typically not require to do anything here.
It is not required to reimplement this method for those setup methods, however, a Plugin reimplementing it should call It is not required to reimplement this method for those setup methods, however, a Plugin reimplementing it must call
\l{DevicePairingInfo::finish}{finish()} on the \l{DevicePairingInfo} object and can provide an optional displayMessage which \l{DevicePairingInfo::finish}{finish()} on the \l{DevicePairingInfo} object and can provide an optional displayMessage which
might be presented to the user. Those strings need to be wrapped in QT_TR_NOOP() in order to be translatable for the client's might be presented to the user. Those strings need to be wrapped in QT_TR_NOOP() in order to be translatable for the client's
locale. locale.
@ -259,33 +244,48 @@ void DevicePlugin::confirmPairing(DevicePairingInfo *info, const QString &userna
info->finish(Device::DeviceErrorUnsupportedFeature); info->finish(Device::DeviceErrorUnsupportedFeature);
} }
/*! This will be called to actually execute actions on the hardware. The \{Device} and /*! This will be called to execute actions on the device. The given \a info object contains
the \{Action} are contained in the \a device and \a action parameters. information about the target \l{Device} and the \l{Action} to be executed.
Return the appropriate \l{Device::DeviceError}{DeviceError}.
It is possible to execute actions asynchronously. You never should do anything blocking for When the execution is completed, a plugin must finish it by calling \l{DeviceActionInfo::finish} on the \a info
a long time (e.g. wait on a network reply from the internet) but instead return object. In case of success, \l{Device::DeviceErrorNoError} must be used, or an appropriate \l{Device::DeviceError}
Device::DeviceErrorAsync and continue processing in an async manner. Once in case of failure. An optional display message can be passed which might be shown
you have the reply ready, emit actionExecutionFinished() with the appropriate parameters. to the user, indicating more details about the error. The displayMessage must be made translatable by wrapping it in a QT_TR_NOOP()
statement.
\sa actionExecutionFinished() An action execution might be cancelled by nymea. In which case the \l{DeviceActionInfo::aborted} signal will be emitted.
The info object must not be accessed after \l{DeviceActionInfo::destroyed} is emitted.
*/ */
void DevicePlugin::executeAction(DeviceActionInfo *info) void DevicePlugin::executeAction(DeviceActionInfo *info)
{ {
info->finish(Device::DeviceErrorUnsupportedFeature); info->finish(Device::DeviceErrorUnsupportedFeature);
} }
/*! Implement this if your devices support browsing (set "browsable" to true in the metadata). /*! A plugin must implement this if devices support browsing ("browsable" being true in the metadata JSON).
* When the system calls this method, fill the \a result object's items list with entries from the browser. When the system calls this method, the \a result must be filled with entries from the browser using
* If \a itemId is empty it means that the root node of the file system should be returned. Each item in \l{BrowseResult::addItems}. The \a info object will contain information about which device and which item/node
* the result set shall be uniquely identifiable using its \l{BrowserItem::id}{id} property. should be browsed. If the itemId is empty it means that the root node of the file system should be returned otherwise
* The system might call this method again, with an \a itemId returned in a previous query, provided all the children of the given item/node should be returned.
* that item's \l{BrowserItem::browsable} property is true. In this case all children of the given
* item shall be returned. All browser \l {BrowserItem::displayName} properties shall be localized
* using the given \a locale. Each item in the result set shall be uniquely identifiable using its \l{BrowserItem::id}{id} property.
* When done, set the \l{BrowserResult::status}{result's status} field approprietly. Set the result's The system might call this method again, with an itemId returned in a previous query, provided
* status to Device::DeviceErrorAsync if this operation requires async behavior and emit that item's \l{BrowserItem::browsable} property is true. In this case all children of the given
* \l{browseRequestFinished} when done. item shall be returned. All browser \l{BrowserItem::displayName} properties shall be localized
using the given locale in the \a info object.
If a returned item's \l{BrowserItem::executable} property is set to true, the system might call \l{DevicePlugin::executeBrowserAction}
for this itemId.
An item might have additional actions which must be defined in the plugin metadata JSON as "browserItemActionTypes". Such actions
might be context actions to items in a browser. For instance, a file browser might add copy/cut/paste actions to an item. The
system might call \l{DevicePlugin::executeBrowserItemAction} on such items.
When done, the browse result must be completed by calling \l{BrowserResult::finish} with \l{Device::DeviceErrorNoError}
in case of success or an appropriate \l{Device::DeviceError} otherwise. An optional display message can be passed which might be shown
to the user, indicating more details about the error. The displayMessage must be made translatable by wrapping it in a QT_TR_NOOP()
statement.
*/ */
void DevicePlugin::browseDevice(BrowseResult *result) void DevicePlugin::browseDevice(BrowseResult *result)
{ {
@ -293,12 +293,21 @@ void DevicePlugin::browseDevice(BrowseResult *result)
result->finish(Device::DeviceErrorUnsupportedFeature); result->finish(Device::DeviceErrorUnsupportedFeature);
} }
/*! Implement this if your devices support browsing (set "browsable" to true in the metadata). /*! A plugin must implement this if devices support browsing ("browsable" being true in the metadata JSON).
* When the system calls this method, fetch the item details required to create a BrowserItem When the system calls this method, the \a result must be filled with a single item identified by the \l{DeviceItemResult::itemId}
* for the item with the given \a id and append that one item to the \a result. using \l{BrowseResult::addItem}. The \a result object will contain information about which device and which item/node
* When done, set the \l{BrowserResult::status}{result's status} field approprietly. Set the result's should be browsed. If the itemId is empty it means that the root node of the file system should be returned.
* status to Device::DeviceErrorAsync if this operation requires async behavior and emit
* \l{browserItemRequestFinished} when done. Each item in the result set shall be uniquely identifiable using its \l{BrowserItem::id}{id} property. The system might
call this method again, with an itemId returned in a previous query, provided that item's \l{BrowserItem::browsable}
property is true. In this case all children of the given item shall be returned. All browser \l{BrowserItem::displayName} properties shall be localized
using the given locale in the \a info object.
When done, the browse result must be completed by calling \l{BrowserItemResult::finish} with \l{Device::DeviceErrorNoError}
in case of success or an appropriate \l{Device::DeviceError} otherwise. An optional display message can be passed which might be shown
to the user, indicating more details about the error. The displayMessage must be made translatable by wrapping it in a QT_TR_NOOP()
statement.
*/ */
void DevicePlugin::browserItem(BrowserItemResult *result) void DevicePlugin::browserItem(BrowserItemResult *result)
{ {
@ -306,21 +315,37 @@ void DevicePlugin::browserItem(BrowserItemResult *result)
result->finish(Device::DeviceErrorUnsupportedFeature); result->finish(Device::DeviceErrorUnsupportedFeature);
} }
/*! Implement this if your devices support browsing and execute the itemId defined in \a browserAction. /*! This will be called to execute browser items on the device. For instance, a file browser might execute a file here.
* Return Device::DeviceErrorAsync if this operation requires async behavior and emit The given \a info object contains information about the target \l{Device} and the \l{BrowserAction} to be executed.
* \l{browserItemExecutionFinished} when done.
*/ When the execution is completed, a plugin must finish it by calling \l{BrowserActionInfo::finish} on the \a info
object. In case of success, \{Device::DeviceErrorNoError} must be used, or an appropriate \l{Device::DeviceError}
in case of failure. An optional display message can be passed which might be shown
to the user, indicating more details about the error. The displayMessage must be made translatable by wrapping it in a QT_TR_NOOP()
statement.
An action execution might be cancelled by nymea. In which case the \{BrowserActionInfo::aborted} signal will be emitted.
The info object must not be accessed after \l{BrowsereActionInfo::destroyed} is emitted.
*/
void DevicePlugin::executeBrowserItem(BrowserActionInfo *info) void DevicePlugin::executeBrowserItem(BrowserActionInfo *info)
{ {
qCWarning(dcDevice()) << "Device claims" << info->device()->deviceClass().name() << "to be browsable but plugin does not reimplement browserItem!"; qCWarning(dcDevice()) << "Device claims" << info->device()->deviceClass().name() << "to be browsable but plugin does not reimplement browserItem!";
info->finish(Device::DeviceErrorUnsupportedFeature); info->finish(Device::DeviceErrorUnsupportedFeature);
} }
/*! Implement this if your devices support browsing and execute the item's action for the itemId defined /*! This will be called to execute browser item actions on the device. For instance a file browser might have
* in \a browserItemAction. "browserItemActionTypes" defined in the JSON in order to support context options like copy/cut/paste.
* Return Device::DeviceErrorAsync if this operation requires async behavior and emit The given \a info object contains information about the target \l{Device} and the \l{BrowserItemAction} to be executed.
* \l{browserItemActionExecutionFinished} when done.
*/ When the execution is completed, a plugin must finish it by calling \l{BrowserItemActionInfo::finish} on the \a info
object. In case of success, \l{Device::DeviceErrorNoError} must be used, or an appropriate \l{Device::DeviceError}
in case of failure. An optional display message can be passed which might be shown
to the user, indicating more details about the error. The displayMessage must be made translatable by wrapping it in a QT_TR_NOOP()
statement.
An action execution might be cancelled by nymea. In which case the \{BrowserItemActionInfo::aborted} signal will be emitted.
The info object must not be accessed after \l{BrowserItemActionInfo::destroyed} is emitted.
*/
void DevicePlugin::executeBrowserItemAction(BrowserItemActionInfo *info) void DevicePlugin::executeBrowserItemAction(BrowserItemActionInfo *info)
{ {
qCWarning(dcDevice()) << "Device claims" << info->device()->deviceClass().name() << "to be browsable but plugin does not reimplement browserItemAction!"; qCWarning(dcDevice()) << "Device claims" << info->device()->deviceClass().name() << "to be browsable but plugin does not reimplement browserItemAction!";
@ -333,9 +358,6 @@ ParamTypes DevicePlugin::configurationDescription() const
return m_metaData.pluginSettings(); return m_metaData.pluginSettings();
} }
/*! This will be called when the DeviceManager initializes the plugin and set up the things behind the scenes.
When implementing a new plugin, use \l{DevicePlugin::init()} instead in order to do initialisation work.
The \l{DevicePlugin::init()} method will be called once the plugin configuration has been loaded. */
void DevicePlugin::initPlugin(const PluginMetadata &metadata, DeviceManager *deviceManager, HardwareManager *hardwareManager) void DevicePlugin::initPlugin(const PluginMetadata &metadata, DeviceManager *deviceManager, HardwareManager *hardwareManager)
{ {
m_metaData = metadata; m_metaData = metadata;