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

HServerService Class Reference
[Device Model]

This is an abstract base class for server-side UPnP services. More...

#include <HServerService>

List of all members.

Public Slots

void notifyListeners ()

Signals

void stateChanged (const Herqq::Upnp::HServerService *source)

Public Member Functions

virtual ~HServerService ()=0
HServerDeviceparentDevice () const
const HServiceInfoinfo () const
const QString & description () const
const HServerActionsactions () const
const HServerStateVariablesstateVariables () const
bool isEvented () const

Protected Types

typedef QHash< QString,
HActionInvoke
HActionInvokes

Protected Member Functions

virtual HActionInvokes createActionInvokes ()=0
virtual bool finalizeInit (QString *errDescription)
 HServerService ()
bool init (const HServiceInfo &info, HServerDevice *parentDevice)

Detailed Description

HServerService is a core component of the HUPnP's server-side Device Model and it models a UPnP service. The UPnP Device Architecture specifies a UPnP service as "Logical functional unit. Smallest units of control. Exposes actions and models the state of a physical device with state variables". In other words, a UPnP service is the entry point for accessing certain type of functionality and state of the containing device.

Using the class

You can retrieve the containing device, the parent device, using parentDevice(). You can retrieve all the actions the service contains by calling actions(), Similarly, you can retrieve all the state variables of the service by calling stateVariables().

The class exposes all the details in the device description concerning a service through info(). From the returned HServiceInfo object you can retrieve the serviceId and serviceType along with various URLs found in the device description, such as the:

However, the above URLs usually provide informational value only, since HUPnP provides a simpler interface for everything those URLs expose:

Sub-classing

Writing a custom HServerService is simple, because you only have to override createActionInvokes(), in which you provide the implementations of the actions of the service. See Tutorial for Building a UPnP Device and Setting Up the Device Model for more information about creating your own HServerServices with custom functionality.

See also:
Device Model
Remarks:
This class is not thread-safe.

Constructor & Destructor Documentation

HServerService (  ) [protected]

Creates a new instance.

You have to call init() to fully initialize the instance.

See also:
init()
~HServerService (  ) [pure virtual]

Destroys the instance.


Member Function Documentation

virtual HActionInvokes createActionInvokes (  ) [protected, pure virtual]

Creates and returns the "action implementations" of the actions the service exposes.

It is very important to note that the overrides of this method should always call the implementation of the super class too. For instance,

 void HServerService::HActionInvokes MyServiceType::createActionInvokes()
 {
     HActionInvokes retVal = SuperClass::createActionInvokes();

     // create and add the actions of this class to the "retVal" variable

     return retVal;
 }
Returns:
the implementations of the actions this HServerService exposes.
bool finalizeInit ( QString *  errDescription ) [protected, virtual]

Provides an opportunity to do post-construction initialization routines in derived classes.

As HServerService is part of the HUPnP's server-side Device Model, its initialization process is usually driven by HUPnP. If this is the case, at the time of instantiation of a descendant HServerService the base HServerService sub-object is not yet fully set up. In other words, at that time it is not guaranteed that every private or protected member of a HServerService are set to their "final" values that are used once the object is fully initialized and ready to be used.

Because of the above, descendants of HServerService should not reference or rely on values of HServerService at the time of construction. If the initialization of a HServerService descendant needs to do something that rely on HServerService being fully set up, you can override this method. This method is called once right after the base HServerService is fully initialized.

Parameters:
errDescription
Returns:
true in case the initialization succeeded.
Note:
It is advisable to keep the constructors of the descendants of HServerService small and fast, and do more involved initialization routines here.
bool init ( const HServiceInfo info,
HServerDevice parentDevice 
) [protected]

Initializes the instance.

This method will succeed only once after construction. Subsequent calls will do nothing.

Parameters:
infospecifies information of the service. This is usually read from a device description document.
parentDevicespecifies the UPnP device instance that contains this service.
HServerDevice * parentDevice (  ) const

Returns the parent HServerDevice that contains this service instance.

Returns:
the parent HServerDevice that contains this service instance.
const HServiceInfo & info (  ) const

Returns information about the service.

Returns:
information about the service. This information is usually read from a device description document.
const QString & description (  ) const

Returns the full service description.

Returns:
the full service description.
const HServerActions & actions (  ) const

Returns the actions the service contains.

Returns:
the actions the service contains.
Remarks:
The ownership of the returned objects is not transferred. Do not delete the returned objects.
const HServerStateVariables & stateVariables (  ) const

Returns the state variables of the service.

Returns:
the state variables of the service.
Remarks:
The ownership of the returned objects is not transferred. Do not delete the returned objects.
bool isEvented (  ) const

Indicates whether or not the service contains state variables that are evented.

Returns:
true in case the service contains one or more state variables that are evented.
Remarks:
In case the service is not evented, the stateChanged() signal will never be emitted and the notifyListeners() method does nothing.
void notifyListeners (  ) [slot]

Explicitly forces stateChanged() event to be emitted if the service is evented.

Otherwise this method does nothing.

void stateChanged ( const Herqq::Upnp::HServerService source ) [signal]

This signal is emitted when the state of one or more state variables has changed.

Parameters:
sourcespecifies the source of the event.
Remarks:
This signal has thread affinity to the thread where the object resides. Do not connect to this signal from other threads.