An abstract base class that represents a UPnP device hosted by the HUPnP library. More...
#include <HDevice>
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 () |
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.
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().
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.
QObject
base class is largely not. 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.
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.
enum LocationUrlType |
HDevice | ( | ) | [protected] |
Creates a new instance.
Default constructor for derived classes.
~HDevice | ( | ) | [pure virtual] |
Destroys the instance.
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).
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).
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.
errDescription |
HDevice
small and fast, and do more involved initialization routines here. HDevice * parentDevice | ( | ) | const |
Returns the parent device of this device, if any.
HDevice * rootDevice | ( | ) | const |
Returns the root device of the device tree to which this device belongs.
HService * serviceById | ( | const HServiceId & | serviceId | ) | const |
Returns the service that has the specified service ID.
serviceId | specifies the service to be returned. |
HServices services | ( | ) | const |
Returns the services this device exports.
HServices servicesByType | ( | const HResourceType & | serviceType, | |
HResourceType::VersionMatch | versionMatch = HResourceType::InclusiveVersionMatch | |||
) | const |
Returns the services of a specific UPnP service type.
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. |
HDevices embeddedDevices | ( | ) | const |
Returns the embedded devices of this device.
const HDeviceInfo & info | ( | ) | const |
Returns information about the device that is read from the device description.
QString description | ( | ) | const |
Returns the UPnP device description of this device.
QList< QUrl > locations | ( | LocationUrlType | urlType = AbsoluteUrl |
) | const |
Returns a list of locations where the device is currently available.
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. |