Public Member Functions | Friends | Related Functions

# HActionArgument Class Reference
[Device Model]

A class that represents an argument for a UPnP action invocation. More...

`#include <HActionArgument>`

List of all members.

## Public Member Functions
| HActionArgument ()
| HActionArgument (const QString &name, const HStateVariableInfo &stateVariableInfo)
| HActionArgument (const HActionArgument &)
HActionArgument & | operator= (const HActionArgument &)
| ~HActionArgument ()
QString | name () const
const HStateVariableInfo & | relatedStateVariable () const
HUpnpDataTypes::DataType | dataType () const
QVariant | value () const
bool | setValue (const QVariant &value)
bool | isValid () const
bool | operator! () const
QString | toString () const
bool | isValidValue (const QVariant &value)
## Friends
H_UPNP_CORE_EXPORT bool | operator== (const HActionArgument &, const HActionArgument &)
## Related Functions
(Note that these are not member functions.)
H_UPNP_CORE_EXPORT bool | operator!= (const HActionArgument &, const HActionArgument &)

## Detailed Description

A UPnP argument is defined in the UPnP service description within an action. If you picture a UPnP action as a function, then an action argument is a parameter to the function. In that sense, a UPnP input argument is a single constant parameter that provides input for the function. An input argument is never modified during action invocation. On the other hand, a UPnP output argument relays information back from the callee to the caller and thus it is modified during action invocation.

A UPnP argument has an unique name() within the definition of the action that contains it. A UPnP argument contains a value, which you can retrieve using value() and which you can set using setValue(). Note, the value of a UPnP argument is bound by its dataType().

A somewhat unusual aspect of a UPnP argument is the concept of a related state variable. According to the UDA specification, a UPnP argument is always associated with a HStateVariable, even if the state variable does not serve any other purpose besides that. This type of a state variable is used to describe the data type of a UPnP argument and thus the value of a UPnP argument is bound by the data type of its related state variable. The dataType() method introduced in this class is equivalent for calling

    relatedStateVariable()->dataType()

Note:
  relatedStateVariable() returns a const reference to an HStateVariableInfo object, rather than a reference or a pointer to an HStateVariable. HStateVariableInfo is an object with value semantics that describes an HStateVariable.

Since it is common for actions to use both input and output arguments that are defined only for the duration of the action invocation, there are bound to be numerous state variables that exist only for UPnP action invocation. It is defined in the UDA specification that these types of state variables have to have a name that includes the prefix A_ARG_TYPE.

Due to the strict typing of UPnP arguments, HUPnP attempts to make sure that invalid values are not entered into a UPnP argument. Because of this, you can call isValidValue() to check if a value you wish to set using setValue() will be accepted. In addition, the setValue() returns false in case the value was not accepted. It is advised that you make sure your values are properly set before attempting action invocation, since the invocation is likely to fail in case any of the provided arguments is invalid.

Finally, you can use isValid() to check if the object itself is valid, which is true if the object was constructed with a proper name and a related state variable.

Remarks:
  the class is not thread-safe.

See also:
  HActionArguments, HAction

## Constructor & Destructor Documentation

HActionArgument | ( |  | ) |

Constructs a new, empty instance.

Remarks:
  Object constructed using this method is always invalid.

See also:
  isValid()

HActionArgument | ( | const QString & | name,
|  | const HStateVariableInfo & | stateVariableInfo |
| ) |  |  |

Initializes a new instance with the specified name and related state variable.

Parameters:

  | name | specifies the name of the argument
  | stateVariableInfo | specifies the related state variable.

Remarks:
  in case the name parameter fails the criteria specified for UPnP action arguments in UPnP Device Architecture 1.1 specification or the stateVariable is null, the object is constructed as "invalid"; isValid() always returns false.

See also:
  isValid()

HActionArgument | ( | const HActionArgument & | other | ) |

Copy constructor.

Creates a copy of `other`.

~HActionArgument | ( |  | ) |

Destroys the instance.

## Member Function Documentation

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

Assignment operator.

Copies the contents of `other` to this.

QString name | ( |  | ) | const

Returns the name of the argument.

Returns:
  the name of the argument. The return value is an empty string in case the object is invalid.

See also:
  isValid()

const HStateVariableInfo & relatedStateVariable | ( |  | ) | const

Returns information about the state variable that is associated with this action argument.

Returns:
  information about the state variable that is associated with this action argument or a null pointer in case the object is invalid.

See also:
  isValid()

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

Helper method for accessing the data type of the related state variable info object directly.

Returns:
  the data type of the state variable. The data type is HUpnpDataTypes::Undefined in case the object is invalid.

See also:
  isValid()

QVariant value | ( |  | ) | const

Returns the value of the argument.

Returns:
  the value of the argument. The returned `QVariant` has a type of `QVariant::Invalid` in case the object is invalid.

See also:
  isValid()

bool setValue | ( | const QVariant & | value | ) |

Sets the value of the argument if the object is valid and the new value is of right type.

Parameters:

  | value | specifies the new value of the argument.

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

bool isValid | ( |  | ) | const

Indicates if the object is constructed with a proper name and a state variable.

Returns:
  true in case the object has a proper name and the object refers to a valid state variable.

bool operator! | ( |  | ) | const

Indicates whether or not the object is considered as invalid.

This is the opposite for calling isValid().

Returns:
  true in case the object is invalid.

See also:
  isValid()

QString toString | ( |  | ) | const

Returns a string representation of the object.

The format of the return value is `"name: theValue"`.

Returns:
  a string representation of the object.

bool isValidValue | ( | const QVariant & | value | ) |

Indicates if the provided value can be set into this input argument successfully.

A value is considered valid, when:

- the argument object is valid, i.e. isValid() returns true and
- the data type of the provided value matches the data type of the argument or
- the data type of the provided value can be converted to the data type of the argument.

Parameters:

  | value | specifies the value to be checked.

Returns:
  true in case the provided value can be set into this input argument successfully.

## Friends And Related Function Documentation

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

Compares the two objects for equality.

Returns:
  true in case the object are logically equivalent.

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

Compares the two objects for inequality.

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