Public Types | Public Member Functions | Friends | Related Functions

# HStateVariableInfo Class Reference
[Common]

This class is used to contain information of a UPnP state variable found in a UPnP service description document. More...

`#include <HStateVariableInfo>`

List of all members.

## Public Types
enum | EventingType
## Public Member Functions
| HStateVariableInfo ()
| HStateVariableInfo (const QString &name, HUpnpDataTypes::DataType dataType, EventingType eventingType=NoEvents, HInclusionRequirement incReq=InclusionMandatory, QString *err=0)
| HStateVariableInfo (const QString &name, HUpnpDataTypes::DataType dataType, const QVariant &defaultValue, EventingType eventingType=NoEvents, HInclusionRequirement incReq=InclusionMandatory, QString *err=0)
| HStateVariableInfo (const QString &name, const QVariant &defaultValue, const QStringList &allowedValueList, EventingType eventingType=NoEvents, HInclusionRequirement incReq=InclusionMandatory, QString *err=0)
| HStateVariableInfo (const QString &name, HUpnpDataTypes::DataType dataType, const QVariant &defaultValue, const QVariant &minimumValue, const QVariant &maximumValue, const QVariant &stepValue, EventingType eventingType=NoEvents, HInclusionRequirement incReq=InclusionMandatory, QString *err=0)
| HStateVariableInfo (const HStateVariableInfo &)
HStateVariableInfo & | operator= (const HStateVariableInfo &)
| ~HStateVariableInfo ()
qint32 | version () const
void | setVersion (qint32 version)
QString | name () const
HInclusionRequirement | inclusionRequirement () const
void | setInclusionRequirement (HInclusionRequirement arg)
qint32 | maxEventRate () const
void | setMaxEventRate (qint32 arg)
HUpnpDataTypes::DataType | dataType () const
EventingType | eventingType () const
void | setEventingType (EventingType arg)
QStringList | allowedValueList () const
bool | setAllowedValueList (const QStringList &arg)
QVariant | minimumValue () const
QVariant | maximumValue () const
QVariant | stepValue () const
bool | setAllowedValueRange (const QVariant &minimumValue, const QVariant &maximumValue, const QVariant &stepValue, QString *err=0)
QVariant | defaultValue () const
bool | setDefaultValue (const QVariant &arg, QString *err=0)
bool | isConstrained () const
bool | isValidValue (const QVariant &value, QVariant *convertedValue=0, QString *err=0) const
bool | isValid () const
## Friends
H_UPNP_CORE_EXPORT bool | operator== (const HStateVariableInfo &, const HStateVariableInfo &)
## Related Functions
(Note that these are not member functions.)
H_UPNP_CORE_EXPORT bool | operator!= (const HStateVariableInfo &, const HStateVariableInfo &)
H_UPNP_CORE_EXPORT quint32 | qHash (const HStateVariableInfo &key)

## Detailed Description

UPnP service description documents specify the actions and state variables of the service. An instance of this class contain the information of a state variable found in a service description document, such as the name() and the dataType().

In addition to the information found in the service description document, the HService containing the HStateVariable that is depicted by the HStateVariableInfo object may have specified additional information about the state variable:

- inclusionRequirement() details whether the state variable is considered as mandatory or optional.
- maxEventRate() specifies the maximum rate at which an evented state variable may send events.

Further, the class contains a few helper methods:

- isConstrained() indicates if the state variable is restricted either by a value range or a value list.
- isValidValue() checks if a specified `QVariant` contains a value that could be inserted into the state variable taking into consideration the data types of the state variable and the specified value as well as any possible constraint set to the state variable.

Remarks:
  this class is not thread-safe.

See also:
  HStateVariable, HDeviceInfo, HServiceInfo and HActionInfo.

## Member Enumeration Documentation

enum EventingType

Specifies different types of eventing.

See also:
  Device Hosting

Enumerator:

  NoEvents | The state variable is not evented and it will never emit valueChanged() signal.
  UnicastOnly | The state variable is evented, valueChanged() signal is emitted upon value change and the HUPnP will propagate events over network to registered listeners through unicast only.
  UnicastAndMulticast | The state variable is evented, valueChanged() signal is emitted upon value change and the HUPnP will propagate events over network using uni- and multicast.

## Constructor & Destructor Documentation

HStateVariableInfo | ( |  | ) |

Creates a new, empty instance.

See also:
  isValid()

HStateVariableInfo | ( | const QString & | name,
|  | HUpnpDataTypes::DataType | dataType,
|  | EventingType | eventingType = `NoEvents`,
|  | HInclusionRequirement | incReq = `InclusionMandatory`,
|  | QString * | err = `0` |
| ) |  |  |

Creates a new instance.

Parameters:

  | name | specifies the name of the state variable.
  | dataType | specifies the UPnP data type of the state variable.
  | eventingType | specifies the type of eventing used with the state variable. This is optional.
  | incReq | specifies whether the service is required or optional. This parameter is optional.
  | err | specifies a pointer to a `QString` that will contain an error description in case the construction failed. This is optional.

See also:
  isValid()

HStateVariableInfo | ( | const QString & | name,
|  | HUpnpDataTypes::DataType | dataType,
|  | const QVariant & | defaultValue,
|  | EventingType | eventingType = `NoEvents`,
|  | HInclusionRequirement | incReq = `InclusionMandatory`,
|  | QString * | err = `0` |
| ) |  |  |

Creates a new instance.

Parameters:

  | name | specifies the name of the state variable.
  | dataType | specifies the UPnP data type of the state variable.
  | defaultValue | specifies the default value.
  | eventingType | specifies the type of eventing used with the state variable. This is optional.
  | incReq | specifies whether the service is required or optional. This parameter is optional.
  | err | specifies a pointer to a `QString` that will contain an error description in case the construction failed. This is optional.

See also:
  isValid()

HStateVariableInfo | ( | const QString & | name,
|  | const QVariant & | defaultValue,
|  | const QStringList & | allowedValueList,
|  | EventingType | eventingType = `NoEvents`,
|  | HInclusionRequirement | incReq = `InclusionMandatory`,
|  | QString * | err = `0` |
| ) |  |  |

Creates a new instance with the data type set to `HUpnpDataTypes::string`.

Parameters:

  | name | specifies the name of the state variable.
  | defaultValue | specifies the default value.
  | allowedValueList | specifies the values the state variable accepts.
  | eventingType | specifies the type of eventing used with the state variable. This is optional.
  | incReq | specifies whether the service is required or optional. This parameter is optional.
  | err | specifies a pointer to a `QString` that will contain an error description in case the construction failed. This is optional.

See also:
  isValid()

HStateVariableInfo | ( | const QString & | name,
|  | HUpnpDataTypes::DataType | dataType,
|  | const QVariant & | defaultValue,
|  | const QVariant & | minimumValue,
|  | const QVariant & | maximumValue,
|  | const QVariant & | stepValue,
|  | EventingType | eventingType = `NoEvents`,
|  | HInclusionRequirement | incReq = `InclusionMandatory`,
|  | QString * | err = `0` |
| ) |  |  |

Parameters:

  | name | specifies the name of the state variable.
  | dataType | specifies the UPnP data type of the state variable.
  | defaultValue | specifies the default value.
  | minimumValue | specifies the inclusive lower bound of an acceptable value. This cannot be larger than the `maximumValue`.
  | maximumValue | specifies the inclusive upper bound of an acceptable value. This cannot be smaller than the `minimumValue`.
  | stepValue | specifies the step value. This value cannot be larger than the subtraction of the maximum and minimum values.
  | eventingType | specifies the type of eventing used with the state variable. This is optional.
  | incReq | specifies whether the service is required or optional. This parameter is optional.
  | err | specifies a pointer to a `QString` that will contain an error description in case the construction failed. This is optional.

HStateVariableInfo | ( | const HStateVariableInfo & | other | ) |

Copy constructor.

Creates a new instance identical to the `other` object.

~HStateVariableInfo | ( |  | ) |

Destroys the instance.

## Member Function Documentation

HStateVariableInfo & operator= | ( | const HStateVariableInfo & | other | ) |

Assignment operator.

Assigns the contents of the `other` to this.

qint32 version | ( |  | ) | const

Returns the UPnP service version in which the state variable was first specified.

Returns:
  the UPnP service version in which the state variable was first specified or `-1`, if the version is not defined.

Remarks:
  It is perfectly normal that the version information is not defined.

See also:
  setVersion()

void setVersion | ( | qint32 | version | ) |

Specifies the UPnP service version in which the state variable was first specified.

Parameters:

  | version | specifies the UPnP service version in which the state variable was first specified. If a value smaller than `-1` is given, the version value will be set to `-1`, which means that the version() is not defined.

See also:
  version()

QString name | ( |  | ) | const

Returns the name of the action.

This is the name specified in the corresponding service description file.

Returns:
  the name of the action.

HInclusionRequirement inclusionRequirement | ( |  | ) | const

Returns the type of the action, i.e.

is it required or optional.

This is the name specified in the corresponding service description file.

Returns:
  the type of the action.

void setInclusionRequirement | ( | HInclusionRequirement | arg | ) |

Specifies whether the depicted state variable is required or optional.

Parameters:

  | arg | specifies whether the service is required or optional.

qint32 maxEventRate | ( |  | ) | const

Returns the maximum rate at which an evented state variable may send events.

Returns:
  the maximum rate at which an evented state variable may send events. The returned value is -1 if the state variable is not evented or the maximum rate has not been defined.

See also:
  setMaxEventRate(), eventingType()

void setMaxEventRate | ( | qint32 | arg | ) |

Sets the maximum rate at which an evented state variable may send events.

Parameters:

  | arg | specifies the maximum rate at which an evented state variable may send events. The rate is not set if the state variable is not evented.

See also:
  maxEventRate(), eventingType()

HUpnpDataTypes::DataType dataType | ( |  | ) | const

Returns the data type of the state variable.

Returns:
  the data type of the state variable.

HStateVariableInfo::EventingType eventingType | ( |  | ) | const

Returns the type of eventing the state variable supports, if any.

Returns:
  the type of eventing the state variable supports, if any.

void setEventingType | ( | HStateVariableInfo::EventingType | arg | ) |

Sets the type of eventing the state variable supports, if any.

Parameters:

  | arg | specifies the type of eventing the state variable supports, if any.

QStringList allowedValueList | ( |  | ) | const

Returns the list of allowed values.

Returns:
  the list of allowed values if the contained data type is string or empty list otherwise.

Remarks:
  this is only applicable on state variables, which data type is HUpnpDataTypes::string.

See also:
  setAllowedValueList(), dataType()

bool setAllowedValueList | ( | const QStringList & | arg | ) |

Specifies the values the state variable accepts.

Parameters:

  | arg | specifies the values the state variable accepts.

Remarks:
  this is only applicable on state variables, which data type is HUpnpDataTypes::string.

See also:
  allowedValueList(), dataType()

QVariant minimumValue | ( |  | ) | const

Returns the minimum value of the specified value range.

Returns:
  the minimum value of the specified value range.

Remarks:
  this is only applicable on state variables, which data type is numeric. In addition, it is optional and it may not be defined.

See also:
  dataType()

QVariant maximumValue | ( |  | ) | const

Returns the maximum value of the specified value range.

Returns:
  the maximum value of the specified value range.

Remarks:
  this is only applicable on state variables, which data type is numeric. In addition, it is optional and it may not be defined.

See also:
  dataType()

QVariant stepValue | ( |  | ) | const

Returns the step value of the specified value range.

Returns:
  the step value of the specified value range.

Remarks:
  this is only applicable on state variables, which data type is numeric. In addition, it is optional and it may not be defined.

See also:
  dataType()

bool setAllowedValueRange | ( | const QVariant & | minimumValue,
|  | const QVariant & | maximumValue,
|  | const QVariant & | stepValue,
|  | QString * | err = `0` |
| ) |  |  |

Sets the allowed value range.

Parameters:

  | minimumValue | specifies the inclusive lower bound of an acceptable value. This cannot be larger than the `maximumValue`.
  | maximumValue | specifies the inclusive upper bound of an acceptable value. This cannot be smaller than the `minimumValue`.
  | stepValue | specifies the step value. This value cannot be larger than the subtraction of the maximum and minimum values.
  | err | specifies a pointer to a `QString`, which contains an error description in case the any of the provided values is invalid. This parameter is optional.

Remarks:
  this is only applicable on state variables, which data type is numeric. In addition, it is optional and it may not be defined.

Returns:
  true in case the values were successfully set.

QVariant defaultValue | ( |  | ) | const

Returns the default value of the state variable.

Returns:
  the default value of the state variable. If no default has been specified, QVariant::Invalid is returned.

bool setDefaultValue | ( | const QVariant & | arg,
|  | QString * | err = `0` |
| ) |  |  |

Sets the default value.

Parameters:

  | arg | specifies the default value. If the value range has been specified the value has to be within the specified range.
  | err | specifies a pointer to a `QString`, which contains an error description in case the value is invalid. This parameter is optional.

Returns:
  true in case the default value was successfully set.

bool isConstrained | ( |  | ) | const

Indicates if the state variable's value is constrained either by minimum, maximum or by a list of allowed values.

Returns:
  true in case the state variable's value is constrained either by minimum, maximum or by a list of allowed values.

See also:
  minimumValue(), maximumValue(), allowedValueList()

bool isValidValue | ( | const QVariant & | value,
|  | QVariant * | convertedValue = `0`,
|  | QString * | err = `0` |
| ) |  |  | const

Indicates whether or not the value is valid in terms of this particular state variable.

Parameters:

  | value | specifies the value to be checked.
  | convertedValue | specifies a pointer to a `QVariant` that contains the value as a variant of the correct type. This is optional. Further, it will not be set if the value is invalid.
  | err | specifies a pointer to a `QString`, which contains an error description in case the value is invalid. This parameter is optional.

Return values:

  | \e | true in case the specified value is valid in terms of the state variable this info object depicts. In other words, setValue() will succeed with the value.
  | false | otherwise.

bool isValid | ( |  | ) | const

Indicates if the object is valid.

Returns:
  true in case the object is valid.

## Friends And Related Function Documentation

H_UPNP_CORE_EXPORT bool operator== | ( | const HStateVariableInfo & | ,
|  | const HStateVariableInfo & |  |
| ) |  |  | `[friend]`

Compares the two objects for equality.

Returns:
  true in case the object are logically equivalent.

H_UPNP_CORE_EXPORT bool operator!= | ( | const HStateVariableInfo & | ,
|  | const HStateVariableInfo & |  |
| ) |  |  | `[related]`

Compares the two objects for inequality.

Returns:
  true in case the object are not logically equivalent.

H_UPNP_CORE_EXPORT quint32 qHash | ( | const HStateVariableInfo & | key | ) | `[related]`

Returns a value that can be used as a unique key in a hash-map identifying the object.

Parameters:

  | key | specifies the HStateVariableInfo object from which the hash value is created.

Returns:
  a value that can be used as a unique key in a hash-map identifying the object.