Herqq

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files

- Class List
- Class Hierarchy
- Class Members

Public Member Functions | Protected Member Functions

# HServerDevice Class Reference
Device Model

This is an abstract base class for server-side UPnP devices hosted by HDeviceHost. More...

`#include <HServerDevice>`

Inherited by HDefaultServerDevice.

List of all members.

## Public Member Functions
virtual | ~HServerDevice ()=0
HServerDevice * | parentDevice () const
HServerDevice * | rootDevice () const
HServerService * | serviceById (const HServiceId &serviceId) const
const HServerServices & | services () const
HServerServices | servicesByType (const HResourceType &serviceType, HResourceType::VersionMatch versionMatch=HResourceType::Inclusive) const
const HServerDevices & | embeddedDevices () const
HServerDevices | embeddedDevicesByType (const HResourceType &deviceType, HResourceType::VersionMatch versionMatch=HResourceType::Inclusive) const
const HDeviceInfo & | info () const
QString | description () const
QList< QUrl > | locations (LocationUrlType urlType=AbsoluteUrl) const
const HDeviceStatus & | deviceStatus () const
## Protected Member Functions
virtual bool | finalizeInit (QString *errDescription)
| HServerDevice ()
bool | init (const HDeviceInfo &info, HServerDevice *parentDevice=0)

## Detailed Description

This is an abstract base class for server-side UPnP devices hosted by HDeviceHost.

`HServerDevice` is a core component of the HUPnP's server-side Device Model and it models a UPnP device, both root and embedded.

Note:
  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 `HServerDevice` 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 HDeviceInfo object from which you can read all the informational elements found in the device description. Calling services() gives you a list of HServerService 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 device, which you can get by calling parentDevice().

## Sub-classing

First of all, if you want to implement a custom UPnP device using HUPnP, note that you do not have to subclass HServerDevice. But you can and there are valid reasons to do so.

Subclassing HServerDevice is extremely simple, as you are not required to override anything. However, if you choose to subclass HServerDevice, it is most likely because:

- you want HUPnP to run strict validation routines on the description documents provided by users,
- you want a custom HServerDevice type to do some additional initialization routines,
- you want to extend the HServerDevice API in some way or
- you want to create a custom type for design purposes.

See Setting Up the Device Model for more information of this topic.

Remarks:
  This class is not thread-safe.

## Constructor & Destructor Documentation

HServerDevice | ( |  | ) | `[protected]`

Creates a new instance.

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

Destroys the instance.

## Member Function Documentation

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

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

As `HServerDevice` is part of the HUPnP's server-side Device Model, its initialization process is usually driven by HUPnP. If this is the case, at the time of instantiation of a descendant `HServerDevice` the base `HServerDevice` 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 `HServerDevice` are set to their "final" values that are used once the object is fully initialized and ready to be used.

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

Parameters:

  errDescription |

Returns:
  true in case the initialization succeeded.

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

bool init | ( | const HDeviceInfo & | info,
|  | HServerDevice * | parentDevice = `0`
| ) |  | `[protected]`

Initializes the instance.

This method will succeed only once after construction. Subsequent calls will do nothing.

Parameters:

  info | specifies information of the device. This is usually read from a device description document.
  parentDevice | specifies parent UPnP device, if any.

HServerDevice * 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 be valid throughout the lifetime of this object.

HServerDevice * 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.

HServerService * 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 throughout the lifetime of this object.

const HServerServices & 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 throughout the lifetime of this object.

HServerServices servicesByType | ( | const HResourceType & | serviceType,
|  | HResourceType::VersionMatch | versionMatch = `HResourceType::Inclusive`
| ) |  | 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 throughout the lifetime of this object.

const HServerDevices & 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 throughout the lifetime of this object.

HServerDevices embeddedDevicesByType | ( | const HResourceType & | deviceType,
|  | HResourceType::VersionMatch | versionMatch = `HResourceType::Inclusive`
| ) |  | const

Returns the embedded devices of a specific UPnP device type.

Parameters:

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

Returns:
  The embedded devices of the specified type.

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

const HDeviceInfo & info | ( |  | ) | const

Returns information about the device.

Returns:
  information about the device. This is often 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.

const HDeviceStatus & deviceStatus | ( |  | ) | const

Returns: