Public Member Functions | Protected Member Functions

# HControlPointConfiguration Class Reference
[Device Hosting]

Class for specifying initialization information to HControlPoint instances. More...

`#include <HControlPointConfiguration>`

Inheritance diagram for HControlPointConfiguration:

List of all members.

## Public Member Functions
| HControlPointConfiguration ()
virtual | ~HControlPointConfiguration ()
virtual HControlPointConfiguration * | clone () const
HDeviceProxyCreator | deviceCreator () const
bool | subscribeToEvents () const
qint32 | desiredSubscriptionTimeout () const
bool | autoDiscovery () const
QList< QHostAddress > | networkAddressesToUse () const
bool | setDeviceCreator (const HDeviceProxyCreator &deviceCreator)
void | setSubscribeToEvents (bool subscribeAutomatically)
void | setDesiredSubscriptionTimeout (qint32 timeout)
void | setAutoDiscovery (bool arg)
bool | setNetworkAddressesToUse (const QList< QHostAddress > &addresses)
## Protected Member Functions
virtual void | doClone (HClonable *target) const
virtual HControlPointConfiguration * | newInstance () const

## Detailed Description

This class is used to pass initialization information for HControlPoint instances. The use of this is optional and an HControlPoint instance is perfectly functional with the default configuration.

However, you can configure an HControlPoint in following ways:

- Define whether an HControlPoint should subscribe to events when a device has been discovered by using setSubscribeToEvents(). By default an HControlPoint instances subscribes to all events.
- Set the timeout request for event subscriptions with setDesiredSubscriptionTimeout(). The default is 30 minutes.
- Specify whether an HControlPoint should perform initial discovery upon startup using setAutoDiscovery(). The default is yes.
- Specify the network addresses an HControlPoint should use in its operations with setNetworkAddressesToUse(). The default is the first found interface that is up. Non-loopback interfaces have preference, but if none are found the loopback is used. However, in this case UDP multicast is not available.
- Specify an object creator that can be used to create custom HDeviceProxy and HServiceProxy objects during run-time when new devices are discovered with setDeviceCreator().

See also:
  HControlPoint

Remarks:
  this class is not thread-safe.

## Constructor & Destructor Documentation

HControlPointConfiguration | ( |  | ) |

Creates a new instance.

Creates a new instance with default values.

~HControlPointConfiguration | ( |  | ) | `[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.

HControlPointConfiguration * 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.

HControlPointConfiguration * 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.

HDeviceProxyCreator deviceCreator | ( |  | ) | const

Returns the user-defined callable entity that is used to create HDeviceProxy instances.

Returns:
  the user-defined callable entity that is used to create HDeviceProxy instances.

See also:
  setDeviceCreator()

bool subscribeToEvents | ( |  | ) | const

Indicates whether to automatically subscribe to all events on all services of a device when a new device is added into the control of an HControlPoint.

Returns:
  true in case the HControlPoint instance should subscribe to all events of all services of a newly added device.

See also:
  setSubscribeToEvents()

qint32 desiredSubscriptionTimeout | ( |  | ) | const

Returns the subscription timeout a control point requests when it subscribes to an evented service.

The default value is 30 minutes.

Returns:
  the subscription timeout in seconds a control point requests when it subscribes to an evented service.

See also:
  setDesiredSubscriptionTimeout()

bool autoDiscovery | ( |  | ) | const

Indicates whether the control point should perform discovery upon initialization.

Returns:
  true in case the the control point should perform discovery upon initialization. This is the default value.

Remarks:
  if the discovery is not performed the control point will be unaware of UPnP devices that are already active in the network until they re-advertise themselves.

See also:
  setAutoDiscovery()

QList< QHostAddress > networkAddressesToUse | ( |  | ) | const

Returns the network addresses a control point should use in its operations.

Returns:
  the network addresses a control point should use in its operations.

See also:
  setNetworkAddressesToUse()

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

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

Setting the device creator is useful when you want to create the types that will be used later as HDeviceProxy instances. However, this is purely optional. If the device creator is not set, `HControlPoint` will create and use default types. Most often custom types provide value only when the custom types contain additional functionality, finer-grained API or something else that the base classes of Device Model do not.

In any case, your callable entity must be:

- copyable by value
- callable with a signature `Herqq::Upnp::HDeviceProxy* function_name(const Herqq::Upnp::HDeviceInfo&);`

Note, the return value must be a pointer to a heap allocated instance of Herqq::Upnp::HDeviceProxy* and the ownership of the created device will be transferred to the `HControlPoint` after returning.

From this follows that the device creator can be 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 MyProxyCreator
     {
         public:
             MyProxyCreator();
             ~MyProxyCreator();

             HDeviceProxy* operator()(const Herqq::Upnp::HDeviceInfo&) const
             {
                 return new MyProxyClass();
             }
     };

and you could call the method as follows:

     setDeviceCreator(MyProxyCreator());

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::HDeviceProxy* 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.setDeviceCreator(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 HDeviceProxy instances.

Remarks:
  - The objects your device creator creates will be deallocated by the HUPnP library when the objects are no longer needed. Do not delete them manually.
  - Setting a device creator is optional and unless you really want to define custom HDeviceProxy types to be used, you should not set this at all.

void setSubscribeToEvents | ( | bool | subscribeAutomatically | ) |

Defines whether a control point should automatically subscribe to all events on all services of a device when a new device is added into the control of an HControlPoint.

Parameters:

  | subscribeAutomatically | when true an HControlPoint instance should by default subscribe to all events of all services of a newly added device.

See also:
  subscribeToEvents()

void setDesiredSubscriptionTimeout | ( | qint32 | timeout | ) |

Sets the subscription timeout a control point requests when it subscribes to an evented service.

Values less than or equal to zero are rejected and instead the default value is used. The default value is 30 minutes.

Parameters:

  | timeout | specifies the requested timeout in seconds.

See also:
  desiredSubscriptionTimeout()

void setAutoDiscovery | ( | bool | arg | ) |

Defines whether the control point should perform discovery upon initialization.

Parameters:

  | arg | when true an HControlPoint instance will perform discovery when it is initialized. This is the default.

Remarks:
  if the discovery is not performed the control point will be unaware of UPnP devices that are already active in the network until they re-advertise themselves.

See also:
  autoDiscovery()

bool setNetworkAddressesToUse | ( | const QList< QHostAddress > & | addresses | ) |

Defines the network addresses the control point should use in its operations.

Parameters:

  | addresses | specifies the network addresses the control point should use in its operations.

Returns:
  true in case the provided addresses are valid and can be used.

See also:
  networkAddressesToUse()