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
HServerDeviceparentDevice () const
HServerDevicerootDevice () const
HServerServiceserviceById (const HServiceId &serviceId) const
const HServerServicesservices () const
HServerServices servicesByType (const HResourceType &serviceType, HResourceType::VersionMatch versionMatch=HResourceType::Inclusive) const
const HServerDevicesembeddedDevices () const
HServerDevices embeddedDevicesByType (const HResourceType &deviceType, HResourceType::VersionMatch versionMatch=HResourceType::Inclusive) const
const HDeviceInfoinfo () 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

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:

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:
infospecifies information of the device. This is usually read from a device description document.
parentDevicespecifies 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:
serviceIdspecifies 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:
serviceTypespecifies the UPnP service type of interest. Only services matching the type are returned.
versionMatchspecifies 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:
deviceTypespecifies the UPnP device type of interest. Only devices matching the type are returned.
versionMatchspecifies 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:
urlTypespecifies 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: