Herqq
Public Member Functions | Friends | Related Functions

HActionArgument Class Reference

This is 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, QString *err=0)
 HActionArgument (const HActionArgument &)
HActionArgumentoperator= (const HActionArgument &)
 ~HActionArgument ()
void detach ()
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

This is a class that represents an argument used in a UPnP action invocation.

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.

Basic Use

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.

Copy Semantics

HActionArgument is designed to be used by value. However, the class uses explicit sharing, which essentially means that every copy of an HActionArgument instance accesses and modifies the same data until detach() is called. The detach() function effectively modifies an HActionArgument instance to use a "private" copy of the underlying data until the instance is copied via a copy constructor or an assignment operator.

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,
QString *  err = 0 
)

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

Parameters:
namespecifies the name of the argument.
stateVariableInfospecifies the related state variable.
errspecifies a pointer to a QString, which will contain an error description in case the provided arguments were not valid. This is optional
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()

Copy constructor.

Creates a copy of other.

Destroys the instance.


Member Function Documentation

HActionArgument& operator= ( const HActionArgument )

Assignment operator.

Copies the contents of other to this.

void detach ( )

Creates a deep copy of the instance, if necessary.

If the underlying reference count of this instance is greater than one, this function creates a deep copy of the shared data and modifies this instance to refer to the copied data.

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. An empty string is returned if the object is invalid.
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 objects are not logically equivalent.