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:
HClonable

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:

See also:
HControlPoint
Remarks:
this class is not thread-safe.

Constructor & Destructor Documentation

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:

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()