Public Member Functions | Friends | Related Functions

HActionArgument Class Reference
[Device Model]

A class that represents an argument used in 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 &)
HActionArgumentoperator= (const HActionArgument &)
 ~HActionArgument ()
QString name () const
const HStateVariableInforelatedStateVariable () 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 often 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 state variable, 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 actual state variable. HStateVariableInfo is an object with value semantics that details information of a state variable.

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, setValue() returns false in case the value was not accepted. It is advised that you make sure your values are properly set before attempting to invoke an action, because the invocation may 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 valid related state variable information.

Note:
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.
Remarks:
This class is not thread-safe.
See also:
HActionArguments

Constructor & Destructor Documentation

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:
namespecifies the name of the argument
stateVariableInfospecifies 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.

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:
valuespecifies 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:
valuespecifies 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.