Public Member Functions | Protected Member Functions

# HDeviceHostConfiguration Class Reference
[Device Hosting]

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 HDevice. More...

`#include <HDeviceHostConfiguration>`

Inheritance diagram for HDeviceHostConfiguration:

List of all members.

## Public Member Functions
| HDeviceHostConfiguration ()
| HDeviceHostConfiguration (const HDeviceConfiguration &)
virtual | ~HDeviceHostConfiguration ()
virtual HDeviceHostConfiguration * | clone () const
bool | add (const HDeviceConfiguration &deviceConfiguration)
QList< const HDeviceConfiguration * > | deviceConfigurations () const
qint32 | individualAdvertisementCount () const
QList< QHostAddress > | networkAddressesToUse () const
qint32 | subscriptionExpirationTimeout () const
ThreadingModel | threadingModel () const
void | setIndividualAdvertisementCount (qint32 count)
void | setSubscriptionExpirationTimeout (qint32 timeout)
bool | setNetworkAddressesToUse (const QList< QHostAddress > &addresses)
void | setThreadingModel (ThreadingModel arg)
bool | isEmpty () const
## Protected Member Functions
virtual void | doClone (HClonable *target) const
virtual HDeviceHostConfiguration * | newInstance () const

## Detailed Description

The initialization of an HDeviceHost requires a valid configuration. A valid host configuration contains at least one device configuration, as otherwise the host would have nothing to do. Because of this the initialization of an HDeviceHost follows roughly these steps:

- Create an HDeviceHostConfiguration instance.
- Create and setup one or more HDeviceConfiguration instances.
- Add the device configurations to the HDeviceHostConfiguration instance using add().
- Modify the behavior of the HDeviceHost by setting other variables in this class.
- Create an HDeviceHost and initialize it by passing the HDeviceHostConfiguration to its HDeviceHost::init() method.

Besides specifying the device configurations, you can configure an HDeviceHost in following ways:

- Specify the threading model an HDeviceHost should use in regard to invoking user code with setThreadingModel(). The default is HDeviceHostConfiguration::MultiThreaded, which means that the user provided action implementations have to be thread-safe.
- Specify how many times each resource advertisement is sent with setIndividualAdvertisementCount(). The default is 2.
- Specify the timeout for event subscriptions with setSubscriptionExpirationTimeout(). The default is 0, which means that an HDeviceHost respects the subscription timeouts requested by control points as long as the requested values are less than a day.
- Specify the network addresses an HDeviceHost 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.

See also:
  HDeviceConfiguration, HDeviceHost

## Member Enumeration Documentation

enum ThreadingModel

This enumeration specifies the threading models the HDeviceHost may use in its operations in regard to user code invocation.

Enumerator:

  SingleThreaded | User code is invoked only from the thread in which the HDeviceHost lives. This value is often used in situations where an HDevice being run by the device host has thread affinity. For instance, this is the case with `HDevices` that need to interact with GUIs.
  MultiThreaded | User code may be invoked from an arbitrary thread. This value should be used in situations where the HDevices run by the device host are thread-safe.

## Constructor & Destructor Documentation

HDeviceHostConfiguration | ( |  | ) |

Default constructor.

Creates a new, empty instance.

HDeviceHostConfiguration | ( | const HDeviceConfiguration & | arg | ) |

Creates a new instance.

Creates an instance with a single device configuration. This is a convenience method.

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

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

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

bool add | ( | const HDeviceConfiguration & | deviceConfiguration | ) |

Adds a device configuration.

Parameters:

  | deviceConfiguration | specifies the device configuration to be added. The configuration is added only if it is valid (

See also:
  HDeviceConfiguration::isValid()).

Returns:
  true in case the configuration was added. A configuration that is invalid, i.e. HDeviceConfiguration::isValid() returns false will not be added and false is returned.

QList< const HDeviceConfiguration * > deviceConfigurations | ( |  | ) | const

Returns the currently stored device configurations.

Returns:
  the currently stored device configurations. The returned list contains pointers to const device configuration objects this instance owns. The ownership of the objects is not transferred. You should never delete these, as that would eventually result in double deletion.

qint32 individualAdvertisementCount | ( |  | ) | const

Indicates how many times the device host sends each individual advertisement / announcement.

The default value is 2.

Returns:
  how many times the device host sends each individual advertisement / announcement.

See also:
  setIndividualAdvertisementCount()

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

Returns the network addresses a device host should use in its operations.

Returns:
  the network addresses a device host should use in its operations.

See also:
  setNetworkAddressesToUse()

qint32 subscriptionExpirationTimeout | ( |  | ) | const

Returns the timeout the device host uses for subscriptions.

The default value is zero, which means that the device host honors the timeouts requested by control points up to a day. Larger values are set to a day.

Returns:
  the timeout in seconds the device host uses for subscriptions.

Remarks:
  this is a low-level detail, which you shouldn't modify unless you know what you are doing.

See also:
  setSubscriptionExpirationTimeout()

HDeviceHostConfiguration::ThreadingModel threadingModel | ( |  | ) | const

Returns the user code threading model the HDeviceHost uses in its operations.

Returns:
  the user code threading model the HDeviceHost uses in its operations.

void setIndividualAdvertisementCount | ( | qint32 | count | ) |

Specifies how many times the device host sends each individual advertisement / announcement.

By default, each advertisement is sent twice.

Parameters:

  | count | specifies how many times the device host sends each individual advertisement / announcement. If the provided value is smaller than 1 the advertisement count is set to 1.

Remarks:
  this is a low-level detail, which you shouldn't modify unless you know what you are doing.

See also:
  individualAdvertisementCount()

void setSubscriptionExpirationTimeout | ( | qint32 | timeout | ) |

Specifies the timeout the device host uses for subscriptions.

The default value is zero, which means that the device host honors the timeouts requested by control points.

Parameters:

  | timeout | specifies the desired timeout in seconds. If timeout is greater than zero the device host will use the timeout as such for subscriptions. If timeout is zero the device host will honor the timeout requested by control points. If timeout is negative the subscription timeout is set to a day.

Note:
  the maximum expiration timeout value is a day. Larger values are set to a day. This applies to the timeout requests made by control points as well.

See also:
  subscriptionExpirationTimeout()

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

Defines the network addresses the device host should use in its operations.

Parameters:

  | addresses | specifies the network addresses the device host should use in its operations.

See also:
  networkAddressesToUse()

void setThreadingModel | ( | ThreadingModel | arg | ) |

Sets the user code threading model the HDeviceHost should use in its operations.

This value specifies how an HDeviceHost invokes user code in regard to thread safety. If the value is HDeviceHostConfiguration::SingleThreaded user code is invoked only from the thread in which the HDeviceHost instance is run. If the value is HDeviceHostConfiguration::MultiThreaded user code may be invoked from any thread at any time. The default is HDeviceHostConfiguration::MultiThreaded.

Parameters:

  | arg | specifies the user code threading model the HDeviceHost should use in its operations.

bool isEmpty | ( |  | ) | const

Indicates if the instance contains any device configurations.

Returns:
  true in case the instance contains no device configurations. In this case the object cannot be used to initialize an HDeviceHost.