From d991507f3e551fdaf43c9b3ca7f706b79d36b4f7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Simon=20St=C3=BCrz?= Date: Mon, 16 Feb 2015 20:27:53 +0100 Subject: [PATCH] added documentation --- libguh/devicemanager.cpp | 2 + libguh/network/upnpdiscovery/upnpdevice.cpp | 41 +++++++++++++++++++ .../upnpdiscovery/upnpdevicedescriptor.cpp | 40 ++++++++++++++++++ .../network/upnpdiscovery/upnpdiscovery.cpp | 35 +++++++++++++++- libguh/network/upnpdiscovery/upnpdiscovery.h | 2 - libguh/plugin/deviceplugin.cpp | 22 ++++++---- 6 files changed, 131 insertions(+), 11 deletions(-) diff --git a/libguh/devicemanager.cpp b/libguh/devicemanager.cpp index 434e9ca8..b6144e7b 100644 --- a/libguh/devicemanager.cpp +++ b/libguh/devicemanager.cpp @@ -43,6 +43,8 @@ \value HardwareResourceTimer Refers to the global timer managed by the \l{DeviceManager}. Plugins should not create their own timers, but rather request the global timer using the hardware resources. + \value HardwareResourceUpnpDisovery + Allowes plugins to search a UPnP devices in the network. */ /*! \enum DeviceManager::DeviceError diff --git a/libguh/network/upnpdiscovery/upnpdevice.cpp b/libguh/network/upnpdiscovery/upnpdevice.cpp index beda733a..0630ae64 100644 --- a/libguh/network/upnpdiscovery/upnpdevice.cpp +++ b/libguh/network/upnpdiscovery/upnpdevice.cpp @@ -16,8 +16,21 @@ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/*! + \class UpnpDevice + \brief Describes an UPnP device. + + \ingroup types + \inmodule libguh + + This class represents a UPnP device with all parameters described in following documentation: \l{http://upnp.org/specs/arch/UPnP-arch-DeviceArchitecture-v1.1.pdf}. + +*/ + #include "upnpdevice.h" +/*! Constructs a UpnpDevice with the given \a parent and the given \a upnpDeviceDescriptor + \sa UpnpDeviceDescriptor,*/ UpnpDevice::UpnpDevice(QObject *parent, UpnpDeviceDescriptor upnpDeviceDescriptor) : QObject(parent) { @@ -37,141 +50,169 @@ UpnpDevice::UpnpDevice(QObject *parent, UpnpDeviceDescriptor upnpDeviceDescripto m_upc = upnpDeviceDescriptor.upc(); } +/*! Returns the location URL of this UPnP device. */ QUrl UpnpDevice::location() { return m_location; } +/*! Sets the \a location URL of this UPnP device. */ void UpnpDevice::setLocation(const QUrl &location) { m_location = location; } +/*! Returns the host address of this UPnP device. */ QHostAddress UpnpDevice::hostAddress() const { return m_hostAddress; } +/*! Sets the \a hostAddress of this UPnP device. */ void UpnpDevice::setHostAddress(const QHostAddress &hostAddress) { m_hostAddress = hostAddress; } +/*! Returns the port of this UPnP device. */ int UpnpDevice::port() const { return m_port; } +/*! Sets the \a port of this UPnP device. */ void UpnpDevice::setPort(const int &port) { m_port = port; } +/*! Returns the type of this UPnP device. */ QString UpnpDevice::deviceType() const { return m_deviceType; } +/*! Sets the \a deviceType of this UPnP device. */ void UpnpDevice::setDeviceType(const QString &deviceType) { m_deviceType = deviceType; } +/*! Returns the friendly name of this UPnP device. */ QString UpnpDevice::friendlyName() const { return m_friendlyName; } +/*! Sets the \a friendlyName of this UPnP device. */ void UpnpDevice::setFriendlyName(const QString &friendlyName) { m_friendlyName = friendlyName; } +/*! Returns the manufacturer of this UPnP device. */ QString UpnpDevice::manufacturer() const { return m_manufacturer; } +/*! Sets the \a manufacturer of this UPnP device. */ void UpnpDevice::setManufacturer(const QString &manufacturer) { m_manufacturer = manufacturer; } +/*! Returns the manufacturer URL of this UPnP device. */ QUrl UpnpDevice::manufacturerURL() const { return m_manufacturerURL; } +/*! Sets the \a manufacturerURL of this UPnP device. */ void UpnpDevice::setManufacturerURL(const QUrl &manufacturerURL) { m_manufacturerURL = manufacturerURL; } +/*! Returns the model description of this UPnP device. */ QString UpnpDevice::modelDescription() const { return m_modelDescription; } +/*! Sets the \a modelDescription of this UPnP device. */ void UpnpDevice::setModelDescription(const QString &modelDescription) { m_modelDescription = modelDescription; } +/*! Returns the model name of this UPnP device. */ QString UpnpDevice::modelName() const { return m_modelName; } +/*! Sets the \a modelName of this UPnP device. */ void UpnpDevice::setModelName(const QString &modelName) { m_modelName = modelName; } +/*! Returns the model number of this UPnP device. */ QString UpnpDevice::modelNumber() const { return m_modelNumber; } +/*! Sets the \a modelNumber of this UPnP device. */ void UpnpDevice::setModelNumber(const QString &modelNumber) { m_modelNumber = modelNumber; } +/*! Returns the model URL of this UPnP device. */ QUrl UpnpDevice::modelURL() const { return m_modelURL; } +/*! Sets the \a modelURL of this UPnP device. */ void UpnpDevice::setModelURL(const QUrl &modelURL) { m_modelURL = modelURL; } +/*! Returns the serial number of this UPnP device. */ QString UpnpDevice::serialNumber() const { return m_serialNumber; } +/*! Sets the \a serialNumber of this UPnP device. */ void UpnpDevice::setSerialNumber(const QString &serialNumber) { m_serialNumber = serialNumber; } +/*! Returns the uuid of this UPnP device. */ QString UpnpDevice::uuid() const { return m_uuid; } +/*! Sets the \a uuid of this UPnP device. */ void UpnpDevice::setUuid(const QString &uuid) { m_uuid = uuid; } +/*! Returns the UPC (Universal Product Code) of this UPnP device. */ QString UpnpDevice::upc() const { return m_upc; } +/*! Sets the \a upc (Universal Product Code) of this UPnP device. */ void UpnpDevice::setUpc(const QString &upc) { m_upc = upc; diff --git a/libguh/network/upnpdiscovery/upnpdevicedescriptor.cpp b/libguh/network/upnpdiscovery/upnpdevicedescriptor.cpp index 74f2187a..788960df 100644 --- a/libguh/network/upnpdiscovery/upnpdevicedescriptor.cpp +++ b/libguh/network/upnpdiscovery/upnpdevicedescriptor.cpp @@ -16,147 +16,187 @@ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/*! + \class UpnpDeviceDescriptor + \brief Holds the description of an UPnP device. + + \ingroup types + \inmodule libguh + + + \sa UpnpDevice +*/ + #include "upnpdevicedescriptor.h" +/*! Constructs an UpnpDeviceDescriptor */ UpnpDeviceDescriptor::UpnpDeviceDescriptor() { } +/*! Sets the \a location URL of this UPnP device. */ void UpnpDeviceDescriptor::setLocation(const QUrl &location) { m_location = location; } +/*! Returns the location URL of this UPnP device. */ QUrl UpnpDeviceDescriptor::location() const { return m_location; } +/*! Sets the \a hostAddress of this UPnP device. */ void UpnpDeviceDescriptor::setHostAddress(const QHostAddress &hostAddress) { m_hostAddress = hostAddress; } +/*! Returns the host address of this UPnP device. */ QHostAddress UpnpDeviceDescriptor::hostAddress() const { return m_hostAddress; } +/*! Sets the \a port of this UPnP device. */ void UpnpDeviceDescriptor::setPort(const int &port) { m_port = port; } +/*! Returns the port of this UPnP device. */ int UpnpDeviceDescriptor::port() const { return m_port; } +/*! Sets the \a deviceType of this UPnP device. */ void UpnpDeviceDescriptor::setDeviceType(const QString &deviceType) { m_deviceType = deviceType; } +/*! Returns the type of this UPnP device. */ QString UpnpDeviceDescriptor::deviceType() const { return m_deviceType; } +/*! Sets the \a friendlyName of this UPnP device. */ void UpnpDeviceDescriptor::setFriendlyName(const QString &friendlyName) { m_friendlyName = friendlyName; } +/*! Returns the friendly name of this UPnP device. */ QString UpnpDeviceDescriptor::friendlyName() const { return m_friendlyName; } +/*! Sets the \a manufacturer of this UPnP device. */ void UpnpDeviceDescriptor::setManufacturer(const QString &manufacturer) { m_manufacturer = manufacturer; } +/*! Returns the manufacturer of this UPnP device. */ QString UpnpDeviceDescriptor::manufacturer() const { return m_manufacturer; } +/*! Sets the \a manufacturerURL of this UPnP device. */ void UpnpDeviceDescriptor::setManufacturerURL(const QUrl &manufacturerURL) { m_manufacturerURL = manufacturerURL; } +/*! Returns the manufacturer URL of this UPnP device. */ QUrl UpnpDeviceDescriptor::manufacturerURL() const { return m_manufacturerURL; } +/*! Sets the \a modelDescription of this UPnP device. */ void UpnpDeviceDescriptor::setModelDescription(const QString &modelDescription) { m_modelDescription = modelDescription; } +/*! Returns the model description of this UPnP device. */ QString UpnpDeviceDescriptor::modelDescription() const { return m_modelDescription; } +/*! Sets the \a modelName of this UPnP device. */ void UpnpDeviceDescriptor::setModelName(const QString &modelName) { m_modelName = modelName; } +/*! Returns the model name of this UPnP device. */ QString UpnpDeviceDescriptor::modelName() const { return m_modelName; } +/*! Sets the \a modelNumber of this UPnP device. */ void UpnpDeviceDescriptor::setModelNumber(const QString &modelNumber) { m_modelNumber = modelNumber; } +/*! Returns the model number of this UPnP device. */ QString UpnpDeviceDescriptor::modelNumber() const { return m_modelNumber; } +/*! Sets the \a modelURL of this UPnP device. */ void UpnpDeviceDescriptor::setModelURL(const QUrl &modelURL) { m_modelURL = modelURL; } +/*! Returns the model URL of this UPnP device. */ QUrl UpnpDeviceDescriptor::modelURL() const { return m_modelURL; } +/*! Sets the \a serialNumber of this UPnP device. */ void UpnpDeviceDescriptor::setSerialNumber(const QString &serialNumber) { m_serialNumber = serialNumber; } +/*! Returns the serial number of this UPnP device. */ QString UpnpDeviceDescriptor::serialNumber() const { return m_serialNumber; } +/*! Sets the \a uuid of this UPnP device. */ void UpnpDeviceDescriptor::setUuid(const QString &uuid) { m_uuid = uuid; } +/*! Returns the uuid of this UPnP device. */ QString UpnpDeviceDescriptor::uuid() const { return m_uuid; } +/*! Sets the \a upc (Universal Product Code) of this UPnP device. */ void UpnpDeviceDescriptor::setUpc(const QString &upc) { m_upc = upc; } +/*! Returns the UPC (Universal Product Code) of this UPnP device. */ QString UpnpDeviceDescriptor::upc() const { return m_upc; diff --git a/libguh/network/upnpdiscovery/upnpdiscovery.cpp b/libguh/network/upnpdiscovery/upnpdiscovery.cpp index e07066ac..3c0c5b12 100644 --- a/libguh/network/upnpdiscovery/upnpdiscovery.cpp +++ b/libguh/network/upnpdiscovery/upnpdiscovery.cpp @@ -15,9 +15,38 @@ * along with guh. If not, see . * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/*! + \class UpnpDiscovery + \brief Allows to detect UPnP devices in the network. + + \ingroup hardware + \inmodule libguh + + This resource allows plugins to discover UPnP devices in the network and receive notification messages. The resource + will bind a UDP socket to the multicast 239.255.255.250 on port 1900. + + The communication was implementet using following documentation: \l{http://upnp.org/specs/arch/UPnP-arch-DeviceArchitecture-v1.1.pdf} + + \sa UpnpDevice, UpnpDeviceDescriptor +*/ + +/*! + \fn UpnpDiscovery::discoveryFinished(const QList &deviceDescriptorList, const PluginId & pluginId) + This signal will be emitted if the discovery call from a \l{DevicePlugin}{Plugin} with the given \a pluginId is finished. The found devices + will be passed with the \a deviceDescriptorList paramter. + \sa DevicePlugin::upnpDiscoveryFinished() + */ + +/*! + \fn UpnpDiscovery::upnpNotify(const QByteArray ¬ifyMessage) + This signal will be emitted when a UPnP NOTIFY message \a notifyMessage will be recognized. + \sa DevicePlugin::upnpNotifyReceived() + */ + #include "upnpdiscovery.h" +/*! Construct the hardware resource UpnpDiscovery with the given \a parent. */ UpnpDiscovery::UpnpDiscovery(QObject *parent) : QUdpSocket(parent) { @@ -48,10 +77,12 @@ UpnpDiscovery::UpnpDiscovery(QObject *parent) : qDebug() << "--> UPnP discovery created successfully."; } +/*! Returns false, if the \l{UpnpDiscovery} resource is not available. Returns true, if a device with + * the given \a searchTarget, \a userAgent and \a pluginId can be discovered.*/ bool UpnpDiscovery::discoverDevices(const QString &searchTarget, const QString &userAgent, const PluginId &pluginId) { if(state() != BoundState){ - qDebug() << "ERROR: UPnP not bound to port 1900"; + qWarning() << "ERROR: UPnP not bound to port 1900"; return false; } @@ -64,6 +95,7 @@ bool UpnpDiscovery::discoverDevices(const QString &searchTarget, const QString & return true; } + void UpnpDiscovery::requestDeviceInformation(const QNetworkRequest &networkRequest, const UpnpDeviceDescriptor &upnpDeviceDescriptor) { QNetworkReply *replay; @@ -71,6 +103,7 @@ void UpnpDiscovery::requestDeviceInformation(const QNetworkRequest &networkReque m_informationRequestList.insert(replay, upnpDeviceDescriptor); } +/*! This method will be called to send the SSDP message \a data to the UPnP multicast.*/ void UpnpDiscovery::sendToMulticast(const QByteArray &data) { writeDatagram(data, m_host, m_port); diff --git a/libguh/network/upnpdiscovery/upnpdiscovery.h b/libguh/network/upnpdiscovery/upnpdiscovery.h index f30ade46..50f87cd7 100644 --- a/libguh/network/upnpdiscovery/upnpdiscovery.h +++ b/libguh/network/upnpdiscovery/upnpdiscovery.h @@ -68,8 +68,6 @@ private slots: void readData(); void replyFinished(QNetworkReply *reply); void discoverTimeout(); - -public slots: }; #endif // UPNPDISCOVERY_H diff --git a/libguh/plugin/deviceplugin.cpp b/libguh/plugin/deviceplugin.cpp index 81952815..90c5cd3d 100644 --- a/libguh/plugin/deviceplugin.cpp +++ b/libguh/plugin/deviceplugin.cpp @@ -24,8 +24,7 @@ \inmodule libguh When implementing a new plugin, start by subclassing this and implementing the following - pure virtual methods: \l{DevicePlugin::pluginName()}, \l{DevicePlugin::pluginId()}, - \l{DevicePlugin::supportedDevices()} and \l{DevicePlugin::requiredHardware()} + pure virtual method \l{DevicePlugin::requiredHardware()} */ /*! @@ -47,11 +46,18 @@ */ /*! - \fn void DevicePlugin::upnpDiscoveryFinished(QList deviceList) - If the plugin has requested the upnp \a deviceList using \l{DevicePlugin::upnpDiscover(QString searchTarget)}, - this slot will be called after 3 seconds (search timeout). The list will contain all devices available on in - the network, which responded to the given search target string - \sa DevicePlugin::upnpDiscover() + \fn void DevicePlugin::upnpDiscoveryFinished(const QList &upnpDeviceDescriptorList) + If the plugin has requested the UPnP device list using \l{DevicePlugin::upnpDiscover()}, this slot will be called after 3 + seconds (search timeout). The \a upnpDeviceDescriptorList will contain the description of all UPnP devices available + in the network. + \sa upnpDiscover(), UpnpDeviceDescriptor, UpnpDiscovery::discoveryFinished() + */ + +/*! + \fn void DevicePlugin::upnpNotifyReceived(const QByteArray ¬ifyData) + If a UPnP device will notify a NOTIFY message in the network, the \l{UpnpDiscovery} will catch the + notification data and call this method with the \a notifyData. + \sa UpnpDiscovery */ /*! @@ -498,7 +504,7 @@ Device *DevicePlugin::findDeviceByParams(const ParamList ¶ms) const /*! Transmits data contained in \a rawData on the \l{Radio433} devices, depending on the hardware requested by this plugin. - Returns true if, the \a rawData with a certain \a delay (pulse length) can be sent. + Returns true if, the \a rawData with a certain \a delay (pulse length) can be sent \a repetitions times. \sa Radio433, requiredHardware() */