Public Types | Public Member Functions | Protected Member Functions

# HDevice Class Reference
[Device Model]

An abstract base class that represents a UPnP device hosted by the HUPnP library. More...

`#include <HDevice>`

Inheritance diagram for HDevice:

List of all members.

## Public Types
enum | DeviceVisitType
## Public Member Functions
virtual | ~HDevice ()=0
HDevice * | parentDevice () const
HDevice * | rootDevice () const
HService * | serviceById (const HServiceId &serviceId) const
HServices | services () const
HServices | servicesByType (const HResourceType &serviceType, HResourceType::VersionMatch versionMatch=HResourceType::InclusiveVersionMatch) const
HDevices | embeddedDevices () const
const HDeviceInfo & | info () const
QString | description () const
QList< QUrl > | locations (LocationUrlType urlType=AbsoluteUrl) const
## Protected Member Functions
virtual HServicesSetupData * | createServices ()
virtual HDevicesSetupData * | createEmbeddedDevices ()
virtual bool | finalizeInit (QString *errDescription)
| HDevice ()

## Detailed Description

`HDevice` is a core component of the HUPnP Device Model and it models a UPnP device, both root and embedded. As detailed in the UPnP Device Architecture specification, a UPnP device is essentially a container for services and possibly for other (embedded) UPnP devices.

## Using the class

The most common uses of `HDevice` involve reading the various device information elements originally set in the device description file and enumerating the exposed services. By calling info() you get an Herqq::Upnp::HDeviceInfo object from which you can read all the informational elements found in the device description. Calling services() gives you a list of Herqq::Upnp::HService instances the device exposes. Note that it is the services that contain the functionality and runtime status of the device.

Some devices also contain embedded devices, which you can get by calling embeddedDevices().

You can retrieve the device's description file by calling description() or you can manually read it from any of the locations returned by locations(). If the device is an embedded device, it always has a parent defined, which you can get by calling parentDevice().

## Sub-classing

First of all, you only need to subclass HDevice when your custom UPnP device defines UPnP services. Second, if your device defines UPnP services, the only thing you need to do is to override the HDevice::createServices(). This virtual method is used to create HService instances that represent the service types defined in the device description document.

As an example, consider the following snippet in which is shown the createServices() method from a fictional device named `DimmableLight:`

     #include "switchpowerimpl.h" // this would be your code
     #include "dimmingimpl.h"     // this would be your code

     Herqq::Upnp::HServicesSetupData* DimmableLight::createServices()
     {
       Herqq::Upnp::HServicesSetupData* retVal = new HServicesSetupData();

       retVal->insert(
           new Herqq::Upnp::HServiceSetup(
               Herqq::Upnp::HServiceId("urn:schemas-upnp-org:serviceId:SwitchPower"),
               Herqq::Upnp::HResourceType("urn:schemas-upnp-org:service:SwitchPower:1"),
               new SwitchPowerImpl())); // your type

       retVal->insert(
           new Herqq::Upnp::HServiceSetup(
               Herqq::Upnp::HServiceId("urn:schemas-upnp-org:serviceId:Dimming"),
               Herqq::Upnp::HResourceType("urn:schemas-upnp-org:service:Dimming:1"),
               new DimmingImpl())); // your type

       return retVal;
     }

The above code maps your types, namely `SwitchPowerImpl` and `DimmingImpl` to the UPnP service types identified by the service IDs `urn:schemas-upnp-org:serviceId:SwitchPower` and `urn:schemas-upnp-org:serviceId:Dimming` respectively. Normally, only HUPnP calls HDevice::createServices() and HUPnP does that once when the device type is being initialized. If any of those service types are not in the device description file or you didn't map a type to a service type found in the device description, the device creation will fail.

Remarks:
  the methods introduced in this class are thread-safe, but the `QObject` base class is largely not.

## Member Enumeration Documentation

enum DeviceVisitType

This enumeration specifies how a device tree should be traversed given a starting node.

HUPnP Device Model is organized into a tree in which there's a root HDevice and it may contain embedded HDevices as its children and they may contain embedded HDevices as their children recursively.

This enumeration is used to specify how a device and its children are traversed.

Enumerator:

  VisitThisOnly | This value is used to indicate that only the HDevice in question is visited.
  VisitThisAndDirectChildren | This value is used to indicate that this HDevice and its embedded HDevices are visited.
  VisitThisRecursively | This value is used to indicate that this HDevice and all of its child devices are visited recursively.

enum TargetDeviceType

This enumeration specifies the device types that are considered as targets of an operation.

Enumerator:

  AllDevices | This value is used to indicate that all devices, both root and embedded are the targets of an operation.
  EmbeddedDevices | This value is used to indicate that only embedded devices are the targets of an operation.
  RootDevices | This value is used to indicate that only root devices are the targets of an operation.

enum LocationUrlType

This enumeration specifies the type of a device location URL.

Enumerator:

  AbsoluteUrl | The absolute URL for the device description.
  BaseUrl | The base URL of the device. This is the URL with which the various other URLs found in a device description are resolved.

## Constructor & Destructor Documentation

HDevice | ( |  | ) | `[protected]`

Creates a new instance.

Default constructor for derived classes.

~HDevice | ( |  | ) | `[pure virtual]`

Destroys the instance.

## Member Function Documentation

HServicesSetupData * createServices | ( |  | ) | `[protected, virtual]`

Creates the services that this UPnP device provides.

It is very important to note that every descendant that specifies services has to override this. In addition, the override of this method should always call the implementation of the super class too. For instance,

     void Herqq::Upnp::HServicesSetupData* MyDeviceType::createServices()
     {
         Herqq::Upnp::HServicesSetupData* retVal = SuperClass::createServices();

         // create and add the services of this device to the "retVal" variable

         return retVal;
     }

Most commonly this method is called only once when the instance is being initialized by the managing host (HDeviceHost or HControlPoint).

Returns:
  the services that this HDevice provides.

Remarks:
  The HDevice base class takes the ownership of the created objects and will delete them upon its destruction. Because of that, you can store the addresses of the created objects and use them safely throughout the lifetime of this device. However, you cannot delete them.

Reimplemented in HDeviceProxy.

HDevicesSetupData * createEmbeddedDevices | ( |  | ) | `[protected, virtual]`

Creates the embedded devices that this UPnP device provides.

It is important to note that every descendant that specifies embedded devices should override this. In case it is overridden, the override of this method should always call the implementation of the super class too. For instance,

     void Herqq::Upnp::HDevicesSetupData* MyDeviceType::createEmbeddedDevices()
     {
         Herqq::Upnp::HDevicesSetupData* retVal = SuperClass::createEmbeddedDevices();

         // create and add the embedded devices of this device to the
         // "retVal" variable

         return retVal;
     }

Most commonly this method is called only once when the instance is being initialized by the managing host (HDeviceHost or HControlPoint).

Returns:
  the services that this HDevice provides.

Remarks:
  The HDevice base class takes the ownership of the created objects and will delete them upon its destruction. Because of that, you can store the addresses of the created objects and use them safely throughout the lifetime of this device. However, you cannot delete them.

bool finalizeInit | ( | QString * | errDescription | ) | `[protected, virtual]`

Provides the opportunity to do post-construction initialization routines in derived classes.

As `HDevice` is part of the HUPnP's Device Model the object creation process is driven by HUPnP. At the time of instantiation of a descendant `HDevice` the base `HDevice` sub-object is not yet fully set up. In other words, at that time it is not guaranteed that every private or protected member of a `HDevice` is set to its "final" value that is used once the object is fully initialized and ready to be used.

Because of the above, descendants of `HDevice` should not reference or rely on values of `HDevice` at the time of construction. If the initialization of a `HDevice` descendant needs to do things that rely on `HDevice` being fully set up, you can override this method. This method is called once right after the base `HDevice` is fully initialized.

Parameters:

  | errDescription |

Returns:
  true in case the initialization succeeded.

Note:
  It is advisable to keep the constructors of the descendants of `HDevice` small and fast, and do more involved initialization routines here.

HDevice * parentDevice | ( |  | ) | const

Returns the parent device of this device, if any.

Returns:
  the parent device of this device, if any, or a null pointer in case the device is a root device.

Remarks:
  the pointer is guaranteed to point to the parent object throughout the lifetime of this object.

HDevice * rootDevice | ( |  | ) | const

Returns the root device of the device tree to which this device belongs.

Returns:
  the root device of the device tree to which this device belongs.

Remarks:
  this device could be the root device of the device tree in question, in which case a pointer to this instance is returned.

HService * serviceById | ( | const HServiceId & | serviceId | ) | const

Returns the service that has the specified service ID.

Parameters:

  | serviceId | specifies the service to be returned.

Returns:
  the service that has the specified service ID or a null pointer in case there is no service with the specified ID.

Remarks:
  the pointer is guaranteed to be valid only throughout the lifetime of this object.

HServices services | ( |  | ) | const

Returns the services this device exports.

Returns:
  the services this device exports. The collection is empty if the device has no services.

Remarks:
  the pointers are guaranteed to be valid only throughout the lifetime of this object.

HServices servicesByType | ( | const HResourceType & | serviceType,
|  | HResourceType::VersionMatch | versionMatch = `HResourceType::InclusiveVersionMatch` |
| ) |  |  | const

Returns the services of a specific UPnP service type.

Parameters:

  | serviceType | specifies the UPnP service type of interest. Only services matching the type are returned.
  | versionMatch | specifies how the version information in argument `serviceType` should be used. The default is inclusive match, which essentially means that any service with a service type version that is less than or equal to the version specified in argument `serviceType` is successfully matched.

Returns:
  the services of the specified type.

Remarks:
  the pointers are guaranteed to be valid only throughout the lifetime of this object.

HDevices embeddedDevices | ( |  | ) | const

Returns the embedded devices of this device.

Returns:
  the embedded devices of this device. The collection is empty if the device has no embedded devices.

Remarks:
  the pointers are guaranteed to be valid only throughout the lifetime of this object.

const HDeviceInfo & info | ( |  | ) | const

Returns information about the device that is read from the device description.

Returns:
  information about the device that is read from the device description.

QString description | ( |  | ) | const

Returns the UPnP device description of this device.

Returns:
  the UPnP device description that is associated to this device.

Remarks:
  an embedded device returns the same device description as its root device.

QList< QUrl > locations | ( | LocationUrlType | urlType = `AbsoluteUrl` | ) | const

Returns a list of locations where the device is currently available.

Parameters:

  | urlType | specifies whether the returned location URLs are absolute URLs for retrieving the device description. By default absolute URLs are returned and from these URLs the device description should be retrievable.

Returns:
  a list of locations where the device is currently available.