Public Types | Public Slots | Signals | Public Member Functions | Protected Types | Protected Member Functions | Private Member Functions

HControlPoint Class Reference
[Device Hosting]

A class for discovering and interacting with UPnP devices in the network. More...

#include <HControlPoint>

List of all members.

Public Types

enum  SubscriptionStatus { Unsubscribed, Subscribing, Subscribed }

Public Slots

void quit ()

Signals

void authenticationRequired (QNetworkReply *reply, QAuthenticator *authenticator)
void subscriptionSucceeded (Herqq::Upnp::HClientService *service)
void subscriptionFailed (Herqq::Upnp::HClientService *service)
void subscriptionCanceled (Herqq::Upnp::HClientService *service)
void rootDeviceOnline (Herqq::Upnp::HClientDevice *device)
void rootDeviceOffline (Herqq::Upnp::HClientDevice *device)
void rootDeviceInvalidated (Herqq::Upnp::HClientDevice *device)
void rootDeviceRemoved (const Herqq::Upnp::HDeviceInfo &deviceInfo)

Public Member Functions

 HControlPoint (QObject *parent=0)
 HControlPoint (const HControlPointConfiguration &configuration, QObject *parent=0)
virtual ~HControlPoint ()
bool init ()
ControlPointError error () const
QString errorDescription () const
bool isStarted () const
HClientDevicedevice (const HUdn &udn, TargetDeviceType deviceType=RootDevices) const
HClientDevices rootDevices () const
HClientDevices devices (const HResourceType &deviceType, HResourceType::VersionMatch versionMatch=HResourceType::Inclusive, TargetDeviceType deviceTypes=RootDevices)
bool removeRootDevice (HClientDevice *rootDevice)
bool subscribeEvents (HClientDevice *device, DeviceVisitType visitType)
bool subscribeEvents (HClientService *service)
SubscriptionStatus subscriptionStatus (const HClientService *service) const
bool cancelEvents (HClientDevice *device, DeviceVisitType visitType)
bool cancelEvents (HClientService *service)
bool scan (const HDiscoveryType &discoveryType, qint32 count=1)
bool scan (const HDiscoveryType &discoveryType, const HEndpoint &destination, qint32 count=1)

Protected Types

enum  DeviceDiscoveryAction { IgnoreDevice, AddDevice, AddDevice_SubscribeEventsIfConfigured, AddDevice_SubscribeAllEvents }

Protected Member Functions

const HControlPointConfigurationconfiguration () const
void setError (ControlPointError error, const QString &errorDescr)

Private Member Functions

virtual bool doInit ()
virtual void doQuit ()
virtual DeviceDiscoveryAction acceptRootDevice (HClientDevice *device)
virtual bool acceptResource (const HDiscoveryType &usn, const HEndpoint &source)

Detailed Description

According to the UPnP Device Architecture specification, a control point is an entity, which "retrieves device and service descriptions, sends actions to services, polls for service state variables, and receives events from services" . In other words, a UPnP control point discovers UPnP devices, queries their state, listens their asynchronous events and invokes them to perform actions. A control point is the client in the UPnP architecture, whereas a UPnP device is the server.

HControlPoint does all of the above, but mostly hiding it from the user if the user wishes so. To discover UPnP devices all you need to do is create an instance of HControlPoint, initialize it by calling init() and check if devices are already found by calling rootDevices(), devices() or device(). You can also listen for a number of events, such as:

Consider an example:

 // myclass.h

 #include <HUpnpCore/HControlPoint>

 class MyClass :
     public QObject
 {
 Q_OBJECT

 private:

     Herqq::Upnp::HControlPoint* m_controlPoint;

 private slots:

     void rootDeviceOnline(Herqq::Upnp::HClientDevice*);
     void rootDeviceOffline(Herqq::Upnp::HClientDevice*);

 public:

     MyClass(QObject* parent = 0);
 };

 // myclass.cpp

 #include "myclass.h"
 #include <HUpnpCore/HClientDevice>

 MyClass::MyClass(QObject* parent) :
     QObject(parent), m_controlPoint(new Herqq::Upnp::HControlPoint(this))
 {
     connect(
         m_controlPoint,
         SIGNAL(rootDeviceOnline(Herqq::Upnp::HClientDevice*)),
         this,
         SLOT(rootDeviceOnline(Herqq::Upnp::HClientDevice*)));

     connect(
         m_controlPoint,
         SIGNAL(rootDeviceOffline(Herqq::Upnp::HClientDevice*)),
         this,
         SLOT(rootDeviceOffline(Herqq::Upnp::HClientDevice*)));

     if (!m_controlPoint->init())
     {
         // the initialization failed, perhaps you should do something?
         // for starters, you can call error() to check the error type and
         // errorDescription() for a human-readable description of
         // the error that occurred.
         return;
     }

     // the control point is running and any standard-compliant UPnP device
     // on the same network should now be discoverable.

     // remember also that the current thread has to have an event loop
 }

 void MyClass::rootDeviceOnline(Herqq::Upnp::HClientDevice* newDevice)
 {
     // device discovered, should something be done with it? Perhaps we want
     // to learn something from it:
     Herqq::Upnp::HDeviceInfo info = newDevice->info();
     // do something with the info object
 }

 void MyClass::rootDeviceOffline(Herqq::Upnp::HClientDevice* rootDevice)
 {
     // device announced that it is going away and the control point sends
     // a notification of this. However, the device isn't removed from the
     // control point until explicitly requested:

     m_controlPoint->removeRootDevice(rootDevice);
 }

Once you have obtained a pointer to a HClientDevice you can enumerate its services, invoke its actions, listen for events of changed state and so on. Basically, a root HClientDevice object at the control point side is an entry point to a very accurate object model depicting the real root UPnP device that has been discovered. For more information about the HClientDevice and the object model, see the page detailing the HUPnP Device Model.

You can call quit() to stop an initialized control point instance from listening the network and to clear its state.

Remarks:
  • This class has thread affinity. You have to use it and destroy it in the thread in which it is located.
  • You can use QObject::moveToThread() on the HControlPoint, which causes the control point and every object managed by it to be moved to the chosen thread. However, you cannot move individual objects managed by HControlPoint.
  • a control point never transfers the ownership of the HClientDevice objects it manages.
  • HControlPoint always destroys every HClientDevice it manages when it is being destroyed.
Warning:
See notes about object deletion in ~HControlPoint().
See also:
HClientDevice, HClientDevices, Device Model

Member Enumeration Documentation

enum DeviceDiscoveryAction [protected]

This enumeration specifies the actions to take when a device has been discovered.

See also:
acceptRootDevice()
Enumerator:
IgnoreDevice 

Ignores the device.

In case the discovered device is a new device this value instructs the control point to ignore and delete it.

In case the discovered device is already in the control of the control point this value instructs the control point to ignore it. However, the device is not removed from the control point. To do that you have to call removeRootDevice().

AddDevice 

Adds a new device into the control point and retains an existing device in the control point.

In case the discovered device is a new device the new device is added into the HControlPoint. Otherwise the device is already in the control point and nothing is done.

The control point will not subscribe to events.

AddDevice_SubscribeEventsIfConfigured 

Adds the device into the control point and subscribes to evented services according to the configuration of the control point.

In case the discovered device is a new device the new device is added into the HControlPoint. Otherwise the device is already in the control point and nothing is done in this regard.

The control point determines whether to subscribe to events based on its configuration. Default configuration instructs the control point to subscribe to all events. The same is done if no configuration was provided.

AddDevice_SubscribeAllEvents 

Adds the device into the control point and subscribes to all evented services.

In case the discovered device is a new device the new device is added into the HControlPoint. Otherwise the device is already in the control point and nothing is done in this regard.

The control points subscribes to all evented services contained by the device and its embedded devices.

This enumeration specifies error types some of the methods of HControlPoint may return.

Enumerator:
UndefinedError 

General failure or no error.

This error code is used to indicate that either:

  • the exact cause for an error could not be determined or
  • no error has occurred.
NotInitializedError 

Control point is not initialized.

This error code is used to indicate that the control point has not been initialized.

AlreadyInitializedError 

Control point is already initialized.

This error code is used to indicate that the control point is already initialized.

CommunicationsError 

Networking error.

This error code is used to indicate that an error occurred in some networking component, such as in HTTP server or in SSDP module.

InvalidArgumentError 

Argument error.

This error code is used to indicate that a member function was called with an invalid argument and the call was aborted.

This enumeration is used to describe the status of an event subscription.

See also:
subscriptionStatus()
Enumerator:
Unsubscribed 

No subscription exists for the specified service.

This value is used when there is no subscription or subscription attempt being made to a specified service.

Subscribing 

A subscription attempt is in progress.

This value is used when a subscription attempt to the events of the specified service is in progress.

See also:
subscriptionSucceeded(), subscriptionFailed()
Subscribed 

A subscription is active.

This value is used when the control point has successfully subscribed to the events of the specified service.


Constructor & Destructor Documentation

HControlPoint ( QObject *  parent = 0 )

Creates a new instance.

Parameters:
parentspecifies the parent QObject, if any.
See also:
HControlPointConfiguration
Remarks:
the created control point creates and uses a default configuration.
HControlPoint ( const HControlPointConfiguration configuration,
QObject *  parent = 0 
)

Creates a new instance.

Parameters:
configurationspecifies information that can be used to modify the default behavior of the control point instance. If you want to use the default configuration, you should use the default constructor.
parentspecifies the parent QObject, if any.
See also:
HControlPointConfiguration
~HControlPoint (  ) [virtual]

Destroys the control point and every hosted device.

Warning:
When a control point is being destroyed the control point destroys all of its child objects. You should discard any pointers retrieved from the control point to prevent accidental dereference.
Remarks:
An HControlPoint instance has to be destroyed in the thread in which it is located.

Member Function Documentation

bool doInit (  ) [private, virtual]

Performs the initialization of a derived class.

The HControlPoint uses two-phase initialization in which the user first constructs an instance and then calls init() in order to ready the object for use. This method is called by the HControlPoint during its private initialization after all the private data structures are constructed but before any network activity. At this point, no HTTP or SSDP requests are served.

You can override this method to perform any further initialization of a derived class.

Returns:
true if and only if the initialization succeeded. If false is returned the initialization of the control point is aborted. In addition, it is advised that you call setError() before returning.
Remarks:
the default implementation does nothing.
See also:
init()
void doQuit (  ) [private, virtual]

Performs the de-initialization of a derived class.

Since it is possible to shutdown a control point without actually destroying the instance by calling quit(), derived classes have the possibility to run their own shutdown procedure by overriding this method. This method is called before the HControlPoint cleans its private data structures but after it has stopped listening requests from the network.

Remarks:
the default implementation does nothing.
See also:
quit()
HControlPoint::DeviceDiscoveryAction acceptRootDevice ( HClientDevice device ) [private, virtual]

This method specifies the actions to take when a device has been discovered.

A discovered device may be a new device to the control point or a device that is already in the control point. The latter scenario is true when a device goes offline, is not removed from the control point and later comes back online with the same UPnP configuration (see UDA for more information about a UPnP device configuration).

If you have derived a class from HControlPoint you have the option of choosing whether a discovered device should be managed by the control point, and whether the control point should subscribe to the events published by the services of the device. To do this you have to override this method.

Note:
  • This method takes precedence over any configuration options provided to the control point at the time of its construction
  • This method is called when:
    • a new root HClientDevice has been built and
    • a previously known device comes back online with the same UPnP device configuration value it had before it went offline.
Parameters:
devicespecifies the discovered device.
Returns:
value indicating what should be done with the specified device.

By default every successfully built device will be added to the control point and its events are subscribed according to the control point configuration.

See also:
DeviceDiscoveryAction()
bool acceptResource ( const HDiscoveryType usn,
const HEndpoint source 
) [private, virtual]

This method is called whenever a new a device has been detected on the network.

Override this method in case you want to control which devices get built.

Every UPnP resource belongs to a UPnP device tree, and every advertisement and notification of a resource contains all the information needed to build a full model of the device tree. An advertisement is sent by a UPnP device to advertise itself, its embedded devices or any of the services contained within the device tree. A notification is the response from a UPnP device to a discovery sent by a control point.

If an advertisement or a notification is received that identifies a resource belonging to a device that is currently not in the control of this control point, this method is called. If you accept the specified resource the control point will retrieve all the information from the target UPnP device to build a device model of the device tree the UPnP device represents.

Note:
once you have accepted a resource from a particular UPnP device, this method will not be called again for other resource advertisements or notifications from the UPnP device. On the other hand, if you do not accept a resource and the same UPnP device sends another notification or advertisement, this method will be called again.
Parameters:
usncontains information about the resource.
sourcespecifies the source of the advertisement.
Returns:
true when the resource is accepted and a device model should be built for the UPnP device that sent the notification / advertisement. If the device is built successfully the acceptRootDevice() will be called. By default every new device is accepted, built and added into an HControlPoint.
const HControlPointConfiguration * configuration (  ) const [protected]

Returns the configuration used to initialize the control point.

Returns:
the configuration used to initialize the control point.
Note:
If no configuration was provided at the time of object construction the control point creates a default configuration and uses that. This method always returns a pointer to a valid object, even if the control point is not initialized.
Remarks:
the returned object is not a copy and the ownership of the object is not transferred. Do not delete the object.
void setError ( ControlPointError  error,
const QString &  errorDescr 
) [protected]

Sets the type and description of the last occurred error.

Parameters:
errorspecifies the error type.
errorDescrspecifies a human readable description of the error.
See also:
error(), errorDescription()
bool init (  )

Initializes the control point.

This has to be called for the control point to start monitoring the network for UPnP devices. To stop an initialized control point instance from listening network events you can call quit() or delete the object.

Note:
By default an HControlPoint instance performs a device discovery upon initialization. However, you can override this in the configuration.
Returns:
true if the initialization of the control point succeeded. If false is returned you can call error() to get the type of the error, and you can call errorDescription() to get a human-readable description of the error.
See also:
quit(), error(), errorDescription()

Returns the type of the last error occurred.

Returns:
the type of the last error occurred.
QString errorDescription (  ) const

Returns a human readable description of the last error occurred.

Returns:
a human readable description of the last error occurred.
bool isStarted (  ) const

Indicates whether or not the host is successfully started.

Returns:
true in case the host is successfully started.
HClientDevice * device ( const HUdn udn,
TargetDeviceType  deviceType = RootDevices 
) const

Returns a device with the specified Unique Device Name that the control point is currently managing.

Parameters:
udnspecifies the Unique Device Name of the desired device.
deviceTypespecifies whether the search should consider root devices only. The default is to search root devices only.
Returns:
the device with the specified Unique Device Name, or a null pointer in case no currently managed device has the specified UDN.
Warning:
the returned device will be deleted at the latest when the control point is being destroyed. In addition, you can call removeRootDevice() to remove and delete a root device. However, the call will fail if you pass it an embedded device. Moreover, do not delete a device object directly. The ownership of an HClientDevice is never transferred.
Remarks:
this method does not perform a network scan. The search is run against the devices that are already in the control of the control point. You can call scan() to perform an explicit network scan.
HClientDevices rootDevices (  ) const

Returns a list of UPnP root devices the control point is currently managing.

The returned list contains pointers to root HClientDevice objects that are currently managed by this instance.

Returns:
a list of pointers to root HClientDevice objects the control point is currently managing.
Warning:
the returned devices will be deleted at the latest when the control point is being destroyed. In addition, you can call removeRootDevice() to remove and delete a root device. However, do not delete the device objects directly. The ownership of an HClientDevice is never transferred.
Remarks:
this method does not perform a network scan.
HClientDevices devices ( const HResourceType deviceType,
HResourceType::VersionMatch  versionMatch = HResourceType::Inclusive,
TargetDeviceType  deviceTypes = RootDevices 
)

Returns a list of UPnP devices the control point is currently managing and that match the provided search criteria.

The returned list contains pointers to HClientDevice objects that are currently managed by this instance. It is important to note that unlike the method rootDevices() this method may return pointers to both root and embedded devices.

Parameters:
deviceTypespecifies the UPnP device type to be searched.
versionMatchspecifies how the version information in argument deviceType should be used. The default is inclusive match, which essentially means that any device with a device type version that is less than or equal to the version specified in argument deviceType is successfully matched.
deviceTypesspecifies whether the search should consider root devices only. The default is to search root devices only.
Returns:
a list of pointers to HClientDevice objects the control point is currently managing.
Warning:
the returned devices will be deleted at the latest when the control point is being destroyed. In addition, you can call removeRootDevice() to remove and delete a root device. However, the call will fail if you pass it an embedded device. Moreover, do not delete the device objects directly. The ownership of an HClientDevice is never transferred.
Remarks:
this method does not perform a network scan. The search is run against the devices that are already in the control of the control point. You can call scan() to perform an explicit network scan.
bool removeRootDevice ( HClientDevice rootDevice )

Removes the root device from the control point and deletes it.

Parameters:
rootDevicespecifies the root device to be removed. Nothing is done if the device is not in the control of this control point or the device is not a root device.
Return values:
truein case the device was successfully removed and deleted.
falsein case:

  • the specified argument was null,
  • the specified device is not managed by this control point or
  • the specified device is not a root device.
Remarks:
the specified object is deleted if and only if the method returns true.
See also:
error(), errorDescription()
bool subscribeEvents ( HClientDevice device,
DeviceVisitType  visitType 
)

Subscribes to events of the specified services contained by the specified device.

You can use this method to subscribe to events of multiple evented services contained by the specified device at once.

Parameters:
devicespecifies the device that contains the services, which events are subscribed.
visitTypespecifies how the device tree is traversed. A subscription is sent to every service of every visited device.
Return values:
truein case the subscriptions were successfully dispatched. Note, any subscription may still fail. You can connect to subscriptionSucceeded() and subscriptionFailed() signals to be notified upon subscription success and failure.
falsein case the specified argument is null or it does not belong to a device held by the control point.
Remarks:
  • services which events are already subscribed to are skipped.
  • the method returns immediately. Every successful subscription results in subscriptionSucceeded() signal sent. Every failed subscription results in subscriptionFailed() signal sent.
  • every subscription is maintained until:
    • an error occurs
    • it is explicitly canceled

Thus, a subscription is automatically renewed before expiration until an error occurs or it is canceled.

See also:
error(), errorDescription()
bool subscribeEvents ( HClientService service )

Subscribes to the events of the service.

Parameters:
servicespecifies the service
Return values:
truein case the subscription request was successfully dispatched. Note, the subscription may still fail. You can connect to subscriptionSucceeded() and subscriptionFailed() signals to be notified upon subscription success and failure.
falsein case the specified argument:

  • is null,
  • it does not belong to a device held by the control point,
  • is not evented or
  • there already exists a subscription for the specified service.
Remarks:
  • the method returns immediately. A successful subscription results in subscriptionSucceeded() signal sent. A failed subscription results in subscriptionFailed() signal sent.
  • a subscription is maintained by the control point until:
    • an error occurs
    • it is explicitly canceled

Thus, a subscription is automatically renewed before expiration until an error occurs or it is canceled.

See also:
error(), errorDescription()
HControlPoint::SubscriptionStatus subscriptionStatus ( const HClientService service ) const

Checks if there exists a subscription to the events of the specified service.

Parameters:
servicespecifies the service to be checked.
Return values:
HControlPoint::Unsubscribedwhen the service is not evented or there is no active susbcription or subscription attempt going on to the specified service.
HControlPoint::Subscribingwhen the service is evented and an subscription attempt is being made to the specified service.
HControlPoint::Subscribedwhen there exists an active subscription to the specified service.
bool cancelEvents ( HClientDevice device,
DeviceVisitType  visitType 
)

Cancels the event subscriptions of every service contained by the device.

Any services which events are not subscribed are skipped.

Parameters:
devicespecifies the device that contains the services, which subscriptions are canceled.
visitTypespecifies how the device tree is traversed. A subscription cancellation request is sent to every service of every visited device.
Return values:
truein case the cancellation request of a subscription was successfully dispatched. Note, this does not mean that the cancellation was successfully received and handled by the UPnP device in question. Upon success the state of the control point instance is modified appropriately, but it is never guaranteed that the target UPnP device receives or processes the cancellation request.
falsein case

  • the specified argument is null,
  • the device is not managed by this control point or
  • there were no active subscriptions matching the search criteria to cancel.
Remarks:
this method returns immediately.
See also:
error(), errorDescription()
bool cancelEvents ( HClientService service )

Cancels the event subscription of the service.

Parameters:
servicespecifies the service, which event subscription is to be canceled.
Return values:
truein case the cancellation request of a subscription was successfully dispatched. Note, this does not mean that the cancellation was successfully received and handled by the UPnP device in question. Upon success the state of the control point instance is modified appropriately, but it is never guaranteed that the target UPnP device receives or processes the cancellation request.
falsein case

  • the specified argument is null,
  • the service does not belong to a device held by the control point or
  • there is no active subscription to the specified service.
Remarks:
this method returns immediately.
See also:
error(), errorDescription()
bool scan ( const HDiscoveryType discoveryType,
qint32  count = 1 
)

Scans the network for resources of interest.

Using the default configuration HControlPoint automatically searches and adds every device it finds. In that case the device list returned by rootDevices() usually reflects the UPnP device status of the network. However, there are situations where you may want to explicitly ask the HControlPoint to update its status and you can call this method to do that.

Parameters:
discoveryTypespecifies the type of the discovery to perform.
countspecifies how many times the discovery should be performed. The number translates directly to the number of SSDP messages send. The default is 1.
Remarks:
  • This method returns immediately.
  • As a result of this call there may be any number of rootDeviceOnline() signals emitted as a consequence of newly found devices.
  • The call will not affect the expiration of existing devices. More specifically, any device that does not respond to the scan will not be considered as expired and no rootDeviceOffline() signals will be sent consequently.
bool scan ( const HDiscoveryType discoveryType,
const HEndpoint destination,
qint32  count = 1 
)

Scans the network for resources of interest.

Using the default configuration HControlPoint automatically searches and adds every device it finds. In that case the device list returned by rootDevices() usually reflects the UPnP device status of the network. However, there are situations where you may want to explicitly ask the HControlPoint to perform a discovery on a specific TCP/IP endpoint. In other words, you can perform a unicast device discovery using this method.

Parameters:
discoveryTypespecifies the type of the discovery to perform.
destinationspecifies the location where the discovery is sent. If the port of the specified endpoint is set to zero the message is sent to the specified host address using the default port 1900.
countspecifies how many times the discovery should be performed. The number translates directly to the number of SSDP messages send. The default is 1.
Remarks:
  • This method returns immediately.
  • As a result of this call there may be any number of rootDeviceOnline() signals emitted as a consequence of newly found devices.
  • The call will not affect the expiration of existing devices. More specifically, any device that does not respond to the scan will not be considered as expired and no rootDeviceOffline() signals will be sent consequently.
void quit (  ) [slot]

Shuts down the control point.

The control point stops listening for network events, deletes all the devices it is hosting and cancels all event subscriptions. In essence, the control point purges it state. You can re-initialize the control point by calling init() again.

Attention:
Every pointer to object retrieved from this instance will be deleted. Be sure not to use any such pointer after calling this method.
See also:
init()
void authenticationRequired ( QNetworkReply *  reply,
QAuthenticator *  authenticator 
) [signal]

This signal is emitted whenever a final server requests authentication before it delivers the requested contents.

This signal is relayed from the underlying QNetworkAccessManager, which is used by the HControlPoint to run HTTP messaging. As specified in the reference documentation of QNetworkAccessManager, the slot connected to this signal should fill the credentials for the contents (which can be determined by inspecting the reply object) in the authenticator object. QNetworkAccessManager will cache the credentials internally and will send the same values if the server requires authentication again, without emitting the authenticationRequired() signal. If it rejects the credentials, this signal will be emitted again.

Parameters:
replyspecifies the requested contents.
authenticatorspecifies the authenticator object to which the user should fill in the credentials.
void subscriptionSucceeded ( Herqq::Upnp::HClientService service ) [signal]

This signal is emitted when the initial subscription to the specified service succeeded.

Parameters:
servicespecifies the target service of the event subscription.
See also:
subscriptionFailed()
void subscriptionFailed ( Herqq::Upnp::HClientService service ) [signal]

This signal is emitted when an event subscription to the specified service failed.

Note:
this signal may be emitted in three different scenarios:
  • the initial subscription failed
  • an automatic subscription renewal failed
  • a re-subscription failed If you want to try to re-subscribe to the service you can call subscribe() again.
Parameters:
servicespecifies the service, which event subscription failed.
See also:
subscriptionSucceeded()
void subscriptionCanceled ( Herqq::Upnp::HClientService service ) [signal]

This signal is emitted when an event subscription to the specified service has been canceled.

Parameters:
servicespecifies the service, which subscription was canceled.
void rootDeviceOnline ( Herqq::Upnp::HClientDevice device ) [signal]

This signal is emitted when a device has been discovered.

Parameters:
deviceis the discovered device.
Remarks:
the discovered device may already be managed by this instance. This is the case when a device goes offline and comes back online before it is removed from the control point.
See also:
rootDeviceOffline(), removeRootDevice()
void rootDeviceOffline ( Herqq::Upnp::HClientDevice device ) [signal]

This signal is sent when a root device has announced that it is going offline or the expiration timeout associated with the device tree has elapsed.

After a device has gone offline you may want to remove the device from the control point using removeRootDevice(). Alternatively, if you do not remove the device and the device comes back online later:

  • a rootDeviceOnline() signal is emitted in case the device uses the same configuration as it did before going offline or
  • a rootDeviceInvalidated() signal is emitted in case the device uses a different configuration as it did before going offline. If this is the case you should remove the device as it no longer reflects the real device accurately.
Parameters:
deviceis the device that went offline and is not reachable at the moment.
See also:
rootDeviceOnline(), rootDeviceInvalidated(), removeRootDevice()
void rootDeviceInvalidated ( Herqq::Upnp::HClientDevice device ) [signal]

This signal is emitted when a previously discovered device has changed its configuration and must be discarded.

The UDA v1.1 specifies the configuration of a root device to consist of the device description documents of all the devices in the device tree and all the service description documents of the services in the device tree. If the configuration changes the old device tree has to be discarded in place of the new one.

After this signal is emitted the specified HClientDevice object has become invalid and should be discarded and removed immediately. In addition, rootDeviceOnline() signal may be emitted shortly after this signal, but only when the new configuration of the device is accepted by this instance.

Parameters:
deviceis the device that has been invalidated.
void rootDeviceRemoved ( const Herqq::Upnp::HDeviceInfo deviceInfo ) [signal]

This signal is emitted when a root device has been removed from the control of this control point and deleted.

Parameters:
deviceInfospecifies information about the device that was removed and deleted.
See also:
rootDeviceOffline()