Public Member Functions | Protected Member Functions

# HDeviceConfiguration Class Reference
[Device Hosting]

This is a class for specifying a configuration to an HDevice that is to be created and hosted by an HDeviceHost. More...

`#include <HDeviceConfiguration>`

Inheritance diagram for HDeviceConfiguration:

List of all members.

## Public Member Functions
| HDeviceConfiguration ()
virtual | ~HDeviceConfiguration ()
virtual HDeviceConfiguration * | clone () const
void | setPathToDeviceDescription (const QString &pathToDeviceDescription)
QString | pathToDeviceDescription () const
void | setCacheControlMaxAge (qint32 maxAge=1800)
qint32 | cacheControlMaxAge () const
HDeviceCreator | deviceCreator () const
bool | setDeviceCreator (const HDeviceCreator &deviceCreator)
bool | isValid () const
## Protected Member Functions
virtual void | doClone (HClonable *target) const
virtual HDeviceConfiguration * | newInstance () const

## Detailed Description

A valid device configuration contains at least:

- a path to a device description file (setPathToDeviceDescription()) and
- a device creator (setDeviceCreator()).

The other options affect the runtime behavior of a HDeviceHost in regard to the HDevice that is created based on the information provided through an instance of this class.

See also:
  HDeviceHostConfiguration, HDeviceHost, HDeviceHost::init(), HDevice

## Constructor & Destructor Documentation

HDeviceConfiguration | ( |  | ) |

Default constructor.

Creates a new, empty instance.

~HDeviceConfiguration | ( |  | ) | `[virtual]`

Destroys the instance.

## Member Function Documentation

void doClone | ( | HClonable * | target | ) | const`[protected, virtual]`

Clones the contents of this to the `target` object.

Every derived class has to override this method. Further, the implementation should be something along these lines:

     void MyClonable::doClone(HClonable* target) const
     {
        MyClonable* myClonable = dynamic_cast<MyClonable*>(target);
        if (!myClonable)
        {
            return;
        }

        BaseClassOfMyClonable::doClone(target);

        // copy the variables introduced in *this* MyClonable
        // instance to "myClonable".
     }

Parameters:

  | target | specifies the target object to which the contents of `this` instance are cloned.

Implements HClonable.

HDeviceConfiguration * newInstance | ( |  | ) | const`[protected, virtual]`

Creates a new instance.

This method is used as part of object cloning. Because of that, it is important that every descendant class overrides this method:

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

Remarks:
  - the object has to be heap-allocated and
  - the ownership of the object is passed to the caller.

Implements HClonable.

HDeviceConfiguration * clone | ( |  | ) | const`[virtual]`

Returns a deep copy of the instance.

Returns:
  a deep copy of the instance.

Remarks:
  - the ownership of the returned object is transferred to the caller.

Reimplemented from HClonable.

void setPathToDeviceDescription | ( | const QString & | pathToDeviceDescription | ) |

Sets the path to the UPnP device description.

Parameters:

  | pathToDeviceDescription | specifies the path to the UPnP device description.

Remarks:
  The provided path or the device description document is not validated in anyway. The device description validation occurs during the initialization of the HDeviceHost.

QString pathToDeviceDescription | ( |  | ) | const

Returns the path to the device description.

Returns:
  the path to the device description.

void setCacheControlMaxAge | ( | qint32 | maxAge = `1800` | ) |

Sets the maximum age of presence announcements and discovery responses in seconds.

Parameters:

  | maxAge | specifies the maximum age of presence announcements and discovery messages. If a value smaller than 5 is specified, the max age is set to 5. If positive value larger than a day is specified, the max age is set to a day (60*60*24). The default is 1800 seconds, which equals to 30 minutes.

Attention:
  the UDA instructs this value to be at least 30 minutes.

qint32 cacheControlMaxAge | ( |  | ) | const

Returns the maximum age of presence announcements and discovery responses in seconds.

If the cache control max age has not been explicitly set, the return value is 1800.

Returns:
  the maximum age of presence announcements and discovery responses in seconds.

HDeviceCreator deviceCreator | ( |  | ) | const

Returns the callable entity that is used to create HDevice instances.

Returns:
  the callable entity that is used to create HDevice instances.

See also:
  setDeviceCreator()

bool setDeviceCreator | ( | const HDeviceCreator & | deviceCreator | ) |

Sets the callable entity that is used to create HDevice instances.

In any case, your callable entity must be:

- copyable by value
- callable by the operator(), with single argument of const Herqq::Upnp::HDeviceInfo& deviceInfo and that returns a pointer to a heap allocated instance of Herqq::Upnp::HDevice*.

In other words, the signature is Herqq::Upnp::HDevice* operator()(const Herqq::Upnp::HDeviceInfo&);

From this follows, that the device creator can be either a:

- functor,
- function pointer or
- member function pointer

For example, if your callable entity is a functor, it could look something like the following:

     class Creator
     {
     public:
         Herqq::Upnp::HDevice* operator()(const Herqq::Upnp::HDeviceInfo& deviceInfo)
         {
             return new MyFirstHDevice();
             // your class derived from HDevice that implements the functionality
             // advertised in the description files.
         }
     };

and you could call the method as follows:

     deviceCreator(Creator());

If your callable entity is a member function other than the operator(), the member function declaration would look like the following:

     class MyClass
     {
     private:
        Herqq:Upnp::HDevice* createMyDevice(const Herqq::Upnp::HDeviceInfo&);

     public:
         MyClass();
     };

and you could set the creator as follows (this is contrived due to the private access specifier):

     MyClass::MyClass()
     {
        HDeviceConfiguration configuration;
        configuration.deviceCreator(this, &MyClass::createMyDevice);
     }

The example above demonstrates that:

- the device creator can be any member function with a proper signature, regardless of the access specifier.

- the way you could set the device creator.

Parameters:

  | deviceCreator | specifies the callable entity that is used to create HDevice instances.

Returns:
  true in case the provided device creator is valid and it was successfully set.

Remarks:

- The objects your device creator creates will be deallocated by HUPnP when the objects are no longer needed. Do not delete them manually.

- The device creator has to be set for every device to be hosted.

See also:
  deviceCreator()

bool isValid | ( |  | ) | const

Indicates whether or not the object contains the necessary details for hosting an HDevice class in a HDeviceHost.

Return values:

  | true | in case the object contains the necessary details for hosting an HDevice class in a HDeviceHost.
  | false | otherwise. In this case, the initialization of HDeviceHost cannot succeed. Make sure you have set the device creator and path to a device description file.