Public Slots | Public Member Functions | Protected Member Functions | Private Member Functions

HDeviceHost Class Reference
[Device Hosting]

A class for creating and hosting HServerDevice instances on the network. More...

#include <HDeviceHost>

List of all members.

Public Slots

void quit ()

Public Member Functions

 HDeviceHost (QObject *parent=0)
HServerDevicedevice (const HUdn &udn, TargetDeviceType target=RootDevices) const
HServerDevices rootDevices () const
bool init (const HDeviceHostConfiguration &configuration)
DeviceHostError error () const
QString errorDescription () const
bool isStarted () const

Protected Member Functions

const HDeviceHostConfigurationconfiguration () const
const HDeviceHostRuntimeStatusruntimeStatus () const
void setError (DeviceHostError error, const QString &errorDescr)

Private Member Functions

virtual bool doInit ()
virtual void doQuit ()
virtual bool acceptSubscription (HServerService *targetService, const HEndpoint &source, bool isNew)

Detailed Description

As the name implies, this is the class in the HUPnP library used to expose UPnP devices to UPnP control points. The class hosts instances of HServerDevice, which means that the class takes care of all of the UPnP mechanics detaching the HServerDevice from it. This separation leaves the HServerDevice to model the UPnP device structure and to focus on the functionality of the specific device type. This is what the HUPnP Device Model is all about.

Hosting a device is simple, assuming you have the necessary device and service descriptions ready and the HUPnP device and service classes implemented. Basically, you only need to:

As an example, consider the following:

 // myclass.h

 #include "my_hdevice.h" // your code containing the type MyHDevice

 #include <HUpnpCore/HDeviceHost>
 #include <HUpnpCore/HDeviceModelCreator>

 #include <QtCore/QObject>

 class MyClass :
     public QObject
 {
 Q_OBJECT

 private:
     Herqq::Upnp::HDeviceHost* m_deviceHost;

 public:
     MyClass(QObject* parent = 0);
 };

 class MyCreator : public Herqq::Upnp::HDeviceModelCreator
 {

 private:

   // overridden from HDeviceModelCreator
   virtual MyCreator* newInstance() const;

 public:

   // overridden from HDeviceModelCreator
   virtual MyHServerDevice* createDevice(
       const Herqq::Upnp::HDeviceInfo& info) const;

   // overridden from HDeviceModelCreator
   virtual MyHServerService* createService(
       const Herqq::Upnp::HServiceInfo& serviceInfo,
       const Herqq::Upnp::HDeviceInfo& parentDeviceInfo) const;
 };

 // myclass.cpp

 MyCreator* MyCreator::newInstance() const
 {
     return new MyCreator();
 }

 MyHServerDevice* MyCreator::createDevice(const Herqq::Upnp::HDeviceInfo& info) const
 {
     if (info.deviceType().toString() == "urn:herqq-org:device:MyDevice:1")
     {
         return new MyHServerDevice();
     }

     return 0;
 }

 MyHServerService* MyCreator::createService(
     const Herqq::Upnp::HServiceInfo& serviceInfo,
     const Herqq::Upnp::HDeviceInfo& parentDeviceInfo) const
 {
     if (serviceInfo.serviceType().toString() == "urn:herqq-org:service:MyService:1")
     {
         return new HMyServerService();
     }

     // Note, parentDeviceInfo is not needed in this case, but there are
     // scenarios when it is mandatory to know information of the parent
     // device to create the correct HServerService type.

     return 0;
 }

 MyClass::MyClass(QObject* parent) :
     QObject(parent),
         m_deviceHost(new Herqq::Upnp::HDeviceHost(this))
 {
     Herqq::Upnp::HDeviceHostConfiguration hostConf;
     hostConf.setDeviceModelCreator(MyCreator());

     Herqq::Upnp::HDeviceConfiguration deviceConf;
     deviceConf.setPathToDeviceDescription("my_hdevice_devicedescription.xml");

     hostConf.add(deviceConf);

     if (!m_deviceHost->init(hostConf))
     {
         // The initialization failed, perhaps you should do something?
         // for starters, you can call error() to check the error type and
         // errorDescription() for a human-readable description of
         // the error that occurred.
         return;
     }

     // The host is running and your device should now be accessible to
     // UPnP Control points until the host is destroyed (assuming the current
     // thread has an event loop).
 }

There are a few noteworthy issues in the example above.

  1. The device host will fail to initialize if your HDeviceHostConfiguration instance is invalid; for instance, the device model creator is not specified or any of the paths to your UPnP device or service description documents are invalid. The point is, you should always check the return value.
  2. Your HServerDevice is accessible only as long as your HDeviceHost is alive. When the device host is destroyed every UPnP device it hosted are destroyed as well.
  3. HDeviceHost requires an event loop to function.
  4. The example above uses an HDeviceHost instance to host a single UPnP root device, but the same host could be used to host multiple UPnP root devices. Certainly you can create multiple HDeviceHost instances that each host a single root HServerDevice within a thread, even sharing an event loop. However, using a single HDeviceHost for multiple root HServerDevice instances reduces resource usage in various ways and makes all the configured UPnP root devices accessible to you from the same HDeviceHost instance.
Remarks:
See also:
Device Hosting, HServerDevice, HDeviceHostConfiguration, HDeviceConfiguration

Member Enumeration Documentation

Specifies return values that some of the methods of the class may return.

Enumerator:
UndefinedError 

Return value signifying general failure.

This return code is used when an operation could not be successfully completed, but the exact cause for the error could not be determined.

NoError 

No error has occurred.

AlreadyInitializedError 

Return value signifying that the device host is already successfully initialized.

InvalidConfigurationError 

Return value signifying that the provided host configuration was incorrect.

InvalidDeviceDescriptionError 

Return value signifying that a provided device description document was invalid.

InvalidServiceDescriptionError 

Return value signifying that a provided service description document was invalid.

CommunicationsError 

Return value used to indicate one or more more problems in communications layer.

For instance, perhaps the HTTP server or could the SSDP listener could not be initialized.


Constructor & Destructor Documentation

HDeviceHost ( QObject *  parent = 0 ) [explicit]

Creates a new instance.

Parameters:
parentspecifies the parent QObject.

Member Function Documentation

bool doInit (  ) [private, virtual]

Performs the initialization of a derived class.

The HDeviceHost uses two-phase initialization in which the user first constructs an instance and then calls init() in order to ready the object for use. This method is called by the HDeviceHost during its private initialization after all the private data structures are constructed, but before any network operations are performed. At this point no HTTP or SSDP requests are served.

You can override this method to perform any further initialization of a derived class.

Returns:
true if and only if the initialization succeeded. If false is returned the initialization of the device host is aborted. In addition, it is advised that you call setError() before returning.
Remarks:
the default implementation does nothing.
See also:
init()
void doQuit (  ) [private, virtual]

Performs the de-initialization of a derived class.

Since it is possible to shutdown a device host without actually destroying the instance by calling quit(), derived classes have the possibility to run their own shutdown procedure by overriding this method. This method is called before the HDeviceHost cleans its private data structures but after it has stopped listening requests from the network.

Remarks:
the default implementation does nothing.
See also:
quit()
bool acceptSubscription ( HServerService targetService,
const HEndpoint source,
bool  isNew 
) [private, virtual]

Checks if a (re-)subscription should be accepted.

Derived classes can opt to override this method to decide what event subscriptions are accepted and what are not.

Parameters:
targetServicespecifies the target of the subscription.
sourcespecifies the location where the subscription came.
isNewindicates the type of the subscription. The value is true in case the subscription is new and false in case the subscription is a renewal to an existing subscription.
Returns:
true in case the subscription should be accepted.
Remarks:
by default all subscriptions are accepted.
const HDeviceHostConfiguration * configuration (  ) const [protected]

Returns the configuration used to initialize the device host.

Returns:
the configuration used to initialize the device host or null in case the device host is not initialized.
Remarks:
the returned object is not a copy and the ownership of the object is not transferred. Do not delete it.
const HDeviceHostRuntimeStatus * runtimeStatus (  ) const [protected]

Returns the object that details information of the status of a device host.

Returns:
the object that details information of the status of a device host.
Remarks:
  • A device host creates a single HDeviceHostRuntimeStatus object during its construction and deletes it when the device host is being deleted.
  • The returned object is always owned by the device host.
void setError ( DeviceHostError  error,
const QString &  errorDescr 
) [protected]

Sets the type and description of the last error occurred.

Parameters:
errorspecifies the error type.
errorDescrspecifies a human readable description of the error.
See also:
error(), errorDescription()
HServerDevice * device ( const HUdn udn,
TargetDeviceType  target = RootDevices 
) const

Returns a root device with the specified Unique Device Name.

Parameters:
udnspecifies the Unique Device Name of the desired root device.
targetspecifies the type of devices that are included in the search.
Returns:
the root device with the specified Unique Device Name, or a null pointer in case no currently managed root device has the specified UDN.
Warning:
the returned device will be deleted when the device host is being destroyed. However, do not delete the device object directly. The ownership of an HServerDevice is never transferred.
HServerDevices rootDevices (  ) const

Returns a list of UPnP root devices the host is currently managing.

The returned list contains pointers to root HServerDevice objects that are currently hosted by this instance.

Returns:
a list of pointers to root HServerDevice objects that are currently managed by the device host.
Warning:
the returned HServerDevice instances will be deleted when the device host is being destroyed. However, do not delete the device objects directly. The ownership of an HServerDevice is never transferred.
bool init ( const HDeviceHostConfiguration configuration )

Initializes the device host and the devices it is supposed to host.

Parameters:
configurationspecifies the configuration for the instance. The object has to contain at least one device configuration.
Returns:
true if the initialization of the device host succeeded. If false is returned you can call error() to get the type of the error, and you can call errorDescription() to get a human-readable description of the error.
See also:
quit()
HDeviceHost::DeviceHostError error (  ) const

Returns the type of the last error occurred.

Returns:
the type of the last error occurred.
QString errorDescription (  ) const

Returns a human readable description of the last error occurred.

Returns:
a human readable description of the last error occurred.
bool isStarted (  ) const

Indicates whether or not the host is successfully started.

Returns:
true in case the host is successfully started.
void quit (  ) [slot]

Quits the device host and destroys the UPnP devices it is hosting.

Note that this is automatically called when the device host is destroyed.

Attention:
Every pointer to object retrieved from this instance will be deleted. Be sure not to use any such pointer after calling this method.
See also:
init()