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:
HDeviceProxy

List of all members.

Public Types

enum  DeviceVisitType

Public Member Functions

virtual ~HDevice ()=0
HDeviceparentDevice () const
HDevicerootDevice () const
HServiceserviceById (const HServiceId &serviceId) const
HServices services () const
HServices servicesByType (const HResourceType &serviceType, HResourceType::VersionMatch versionMatch=HResourceType::InclusiveVersionMatch) const
HDevices embeddedDevices () const
const HDeviceInfoinfo () const
QString description () const
QList< QUrl > locations (LocationUrlType urlType=AbsoluteUrl) const

Protected Member Functions

virtual HServicesSetupDatacreateServices ()
virtual HDevicesSetupDatacreateEmbeddedDevices ()
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

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.

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.

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.