added documentation

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

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;

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;

libguh/network/upnpdiscovery/upnpdiscovery.cpp

@@ -15,9 +15,38 @@
  *  along with guh. If not, see <http://www.gnu.org/licenses/>.            *
  *                                                                         *
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
+/*!
+  \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<UpnpDeviceDescriptor> &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 &notifyMessage)
+ 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);

libguh/network/upnpdiscovery/upnpdiscovery.h

@@ -68,8 +68,6 @@ private slots:
     void readData();
     void replyFinished(QNetworkReply *reply);
     void discoverTimeout();
-
-public slots:
 };
 
 #endif // UPNPDISCOVERY_H

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()},
+  pure virtual method \l{DevicePlugin::requiredHardware()}
-  \l{DevicePlugin::supportedDevices()} and \l{DevicePlugin::requiredHardware()}
 */
 
 /*!
@@ -47,11 +46,18 @@
  */
 
 /*!
- \fn void DevicePlugin::upnpDiscoveryFinished(QList<UpnpDevice> deviceList)
+ \fn void DevicePlugin::upnpDiscoveryFinished(const QList<UpnpDeviceDescriptor> &upnpDeviceDescriptorList)
- If the plugin has requested the upnp \a deviceList using \l{DevicePlugin::upnpDiscover(QString searchTarget)},
+ If the plugin has requested the UPnP device list using \l{DevicePlugin::upnpDiscover()}, this slot will be called after 3
- this slot will be called after 3 seconds (search timeout). The list will contain all devices available on in
+ seconds (search timeout). The \a upnpDeviceDescriptorList will contain the description of all UPnP devices available
- the network, which responded to the given search target string
+ in the network.
- \sa DevicePlugin::upnpDiscover()
+ \sa upnpDiscover(), UpnpDeviceDescriptor, UpnpDiscovery::discoveryFinished()
+ */
+
+/*!
+ \fn void DevicePlugin::upnpNotifyReceived(const QByteArray &notifyData)
+ 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 &params) 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()
  */