Herqq

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

Classes

# Device Hosting

HUPnP Core

This page explains the concept of device hosts, which encapsulate the technical details of UPnP networking. More...

## Classes
class | HControlPoint
| This is 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
| This is 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...

## Detailed Description

This page explains the concept of device hosts, which encapsulate the technical details of UPnP networking.

## A few notes about the design

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 Herqq::Upnp::HDeviceHost is the class that enables UPnP devices to be published for UPnP control points to use.
- The Herqq::Upnp::HControlPoint is the class that enables the discovery and use of UPnP devices that are available on the network.

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.

Note:
  While a Herqq::Upnp::HServerDevice published by a `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.

## Basic use

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 MyHServerDevice(); // your class derived from HServerDevice
         }

         // 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 MyHServerService();
         }
     };

     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.

See also:
  Herqq::Upnp::HDeviceHost, Herqq::Upnp::HControlPoint, Device Model