This page explains the concept of device hosts, which encapsulate the technical details of UPnP networking. More...
Classes | |
class | HControlPoint |
A class for discovering and interacting with UPnP devices in the network. More... | |
class | HControlPointConfiguration |
Class for specifying initialization information to HControlPoint instances. More... | |
class | HDeviceHost |
A class for creating and hosting HServerDevice instances on the network. More... | |
class | HDeviceHostRuntimeStatus |
This is a class for detailing information of the runtime status of an HDeviceHost instance. More... | |
class | HDeviceConfiguration |
This is a class for specifying a configuration to an HServerDevice that is to be created and hosted by an HDeviceHost. More... | |
class | HDeviceHostConfiguration |
This class is used to specify one or more device configurations to an HDeviceHost instance and to configure the functionality of the HDeviceHost that affect every hosted HServerDevice. More... |
The logical core of HUPnP is divided into two major modules; a collection of classes that enable the hosting of UPnP device model and the collection of classes that form up the Device Model. The separation is very distinct. The device hosts provide the technical foundation for the UPnP networking. They encapsulate and implement the protocols the UPnP Device Architecture specification details. The device model, on the other hand, is about the logical structure of the UPnP core concepts, which is clearly independent of the technical details of communication. Because of this HUPnP uses highly similar device models both at the server and client side.
HUPnP introduces two types of hosts.
The difference between these two classes is important to notice. You could picture an HDeviceHost as a server and an HControlPoint as a client. The HDeviceHost
publishes instances of HServerDevice for UPnP control points to use and the HControlPoint
uses instances of HClientDevice to communicate with UPnP devices. But as implied, the APIs of client and server side device models are very similar and once you get familiar either one, using the other should be simple as well.
HDeviceHost
is always usable by UPnP control points over the network, the same device can also be accesed and used simultaneously in process. See HDeviceHost for more information.The basic use of the HDeviceHost
is straightforward. You only need to initialize it by providing information that enables one or more UPnP devices to be created and hosted.
In other words, you could create and initialize an HDeviceHost like this:
#include <HUpnpCore/HDeviceHost> #include <HUpnpCore/HDeviceModelCreator> #include "my_hserverdevice.h" // your code namespace { class MyDeviceModelCreator : public Herqq::Upnp::HDeviceModelCreator { private: // overridden from HDeviceModelCreator virtual MyDeviceModelCreator* newInstance() const { return new MyDeviceModelCreator(); } public: // overridden from HDeviceModelCreator virtual Herqq::Upnp::HServerDevice* createDevice( const Herqq::Upnp::HDeviceInfo& info) const { // You should check the info object to see what object HUPnP wants // created and return null if your creator cannot create it. return new MyHDevice(); // your class derived from HDevice } // overridden from HDeviceModelCreator virtual HServerService* createService( const Herqq::Upnp::HServiceInfo& serviceInfo, const Herqq::Upnp::HDeviceInfo& parentDeviceInfo) const { // You should check the info objects to see what object HUPnP wants // created and return null if your creator cannot create it. return new MyHService(); } }; Herqq::Upnp::HDeviceHost* createDeviceHost() { Herqq::Upnp::HDeviceHostConfiguration hostConf; hostConf.setDeviceModelCreator(MyDeviceModelCreator()); // This specifies the factory type that the HDeviceHost uses to create // HServerDevice and HServerService instances. Herqq::Upnp::HDeviceConfiguration deviceConf; deviceConf.setPathToDeviceDescription("my_hdevice_devicedescription.xml"); // This is the device description for our custom UPnP device type // the device host uses this file to build the device tree. hostConf.add(deviceConf); // The same HDeviceHost can host multiple UPnP root devices at the same time. // To do that you only need to create and add other HDeviceConfiguration // objects to the HDeviceHostConfiguration instance as shown above. Herqq::Upnp::HDeviceHost* deviceHost = new HDeviceHost(); if (!deviceHost->init(hostConf)) { // The initialization failed. Perhaps something should be done? // You can call error() to check the type of the error and errorDescription() // to get a human-readable description of the error. } return deviceHost; } }
and an HControlPoint like this:
#include <HUpnpCore/HControlPoint> Herqq::Upnp::HControlPoint* createControlPoint() { Herqq::Upnp::HControlPoint* controlPoint = new HControlPoint(); if (!controlPoint->init()) { // The initialization failed. Perhaps something should be done? // You can call error() to check the type of the error and errorDescription() // to get a human-readable description of the error. } return controlPoint; } }
The above shows the simplest way to initialize an HControlPoint instance. However, you can configure the behavior of an HControlPoint
instance in various ways by providing it an HControlPointConfiguration instance upon construction.