Herqq

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files

- Class List
- Class Hierarchy
- Class Members

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
HServerDevice * | parentDevice () const
const HServiceInfo & | info () const
const QString & | description () const
const HServerActions & | actions () const
const HServerStateVariables & | stateVariables () const
bool | isEvented () const
QVariant | value (const QString &stateVarName, bool *ok=0) const
bool | setValue (const QString &stateVarName, const QVariant &value)
## Protected Types
typedef QHash< QString, HActionInvoke > | HActionInvokes
## Protected Member Functions
virtual HActionInvokes | createActionInvokes ()
virtual bool | finalizeInit (QString *errDescription)
| HServerService ()
bool | init (const HServiceInfo &info, HServerDevice *parentDevice)

## Detailed Description

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

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

- scpdUrl, which returns the URL for fetching the service description,
- controlUrl, which returns the URL to be used in action invocation and
- eventSubUrl, which returns the URL used in event (un)subscriptions.

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

- You can retrieve the service description of a service using description().
- Action invocation is abstracted into the HServerAction class.
- You can receive all the event notifications from a UPnP service by connecting to the stateChanged() signal.

## Sub-classing

Writing a custom `HServerService` is simple, because you only have to provide the implementations of the actions the service exposes. You can do this by overriding createActionInvokes() in which you create the callable entities that will be called upon action invocation. You can also mark member functions implementing actions of a service as `Q_INVOKABLE`, which enables HUPnP to automatically create the previsously mentioned callable entities for you. See Tutorial for Building a UPnP Device and Setting Up the Device Model for more information about creating your own HServerService types 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

HServerService::HActionInvokes createActionInvokes | ( |  | ) | `[protected, 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:

  info | specifies information of the service. This is usually read from a device description document.
  parentDevice | specifies 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.

QVariant value | ( | const QString & | stateVarName,
|  | bool * | ok = `0`
| ) |  | const

Returns the value of the specified state variable, if such exists.

This is a convenience method for retrieving a state variable by name and getting its value.

Parameters:

  stateVarName | specifies the name of the state variable.
  ok | specifies a pointer to a `bool`, which will contain true if the specified state variable was found and its value was returned. This is optional.

Returns:
  The value of the specified state variable, if such exists. If this service does not contain the specified state variable, an invalid `QVariant` is returned.

Remarks:
  The value of the state variable may be represented by an invalid `QVariant`. Because of this, if you want to be sure that the specified state variable was found and its value was returned, you should use the ok parameter.

bool setValue | ( | const QString & | stateVarName,
|  | const QVariant & | value
| ) |  |

Sets the value of the specified state variable, if such exists.

This is a convenience method for retrieving a state variable by name and setting its value.

Parameters:

  stateVarName | specifies the name of the state variable.
  value | specifies the new value of the state variable.

Returns:
  true in case the specified state variable was found and its value was changed.

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:

  source | specifies 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.