Public Types | Signals | Public Member Functions | Static Public Member Functions

HAction Class Reference
[Device Model]

A class that represents a UPnP action found in a UPnP service. More...

#include <HAction>

List of all members.

Public Types

enum  ReturnCode {
  Success = 200, InvalidAction = 401, InvalidArgs = 402, ActionFailed = 501,
  ArgumentValueInvalid = 600, ArgumentValueOutOfRange = 601 , OutOfMemory = 603, HumanInterventionRequired = 604 ,
  UndefinedFailure = 0x0ff00000
}

Signals

void invokeComplete (Herqq::Upnp::HAsyncOp asyncOp)

Public Member Functions

virtual ~HAction ()
HServiceparentService () const
const HActionInfoinfo () const
HAsyncOp beginInvoke (const HActionArguments &inArgs, HExecArgs *execArgs=0)
HAsyncOp beginInvoke (const HActionArguments &inArgs, const HActionInvokeCallback &completionCallback, HExecArgs *execArgs=0)
bool waitForInvoke (HAsyncOp *asyncOp, HActionArguments *outArgs=0)
qint32 invoke (const HActionArguments &inArgs, HActionArguments *outArgs=0)

Static Public Member Functions

static QString errorCodeToString (qint32 errCode)

Detailed Description

HAction is a core component of the HUPnP Device Model and it models a UPnP action. The UPnP Device Architecture specifies a UPnP action as command, which takes one or more input or output arguments and that may have a return value. In a way, a UPnP action is an abstraction to a method or to a remote procedure call.

You can get the input and output arguments from info() to find out what the defined input and output arguments for the action are. In essence, when you execute an action using invoke() or beginInvoke(), you have to provide the set of input arguments the action info object defines. Otherwise, the invocation fails. Obviously the values of the arguments can be changed. On the other hand, HUPnP will fill the user provided output arguments to match output arguments defined in the action info object, if necessary.

You can invoke an HAction synchronously and asynchronously. To perform an asynchronous invocation, you have to call beginInvoke(). To perform a synchronous invocation, you can call beginInvoke() followed by waitForInvoke(), or you can call invoke(), which is a helper method that calls beginInvoke() and waitForInvoke(). It is important to note that although HAction is derived from QObject, neither the invoke() nor beginInvoke() has thread affinity. Because of this, you can perform invocation or waiting the result of invocation from any thread.

See also:
HActionInfo, HService
Remarks:
  • the methods introduced in this class are thread-safe, although the base class is largely not.

Member Enumeration Documentation

enum ReturnCode

This enumeration specifies the generic error codes that action invocation may return.

These values correspond to the values defined in the UDA, excluding NotImplemented and UndefinedFailure, which are defined for the purposes of HUPnP.

Note:
These are only the generic error codes. Many UPnP devices define and use domain specific error codes that cannot be specified here.
Enumerator:
Success 

Action invocation succeeded.

InvalidAction 

Invalid action.

The specified action was not found.

InvalidArgs 

Action invocation failed due to:

  • not enough arguments,
  • arguments in wrong order,
  • one or more arguments have wrong data type
ActionFailed 

The current state of the service prevents the action invocation.

ArgumentValueInvalid 

Action invocation failed due to an invalid argument value.

ArgumentValueOutOfRange 

Action invocation failed due to:

  • an argument value is less than the minimum of the allowed value range,
  • an argument value is more than the maximum of the allowed value range,
  • an argument value is not in the allowed value list
OptionalActionNotImplemented 

Action invocation failed due to the requested action being optional and not implemented by the device.

OutOfMemory 

Action invocation failed due to insufficient memory.

The device does not have sufficient memory available to complete the action. This MAY be a temporary condition; the control point MAY choose to retry the unmodified request again later and it MAY succeed if memory is available.

HumanInterventionRequired 

The device has encountered an error condition which it cannot resolve itself and required human intervention such as a reset or power cycle.

See the device display or documentation for further guidance.

StringArgumentTooLong 

Action invocation failed due to a string argument being too long for the device to handle properly.

UndefinedFailure 

Action invocation failed, but the exact cause could not be determined.


Constructor & Destructor Documentation

~HAction (  )  [virtual]

Destroys the instance.

An HAction is always destroyed by the containing HService when it is being deleted. You should never destroy an HAction.


Member Function Documentation

HService * parentService (  )  const

Returns the parent service of the action.

Returns:
the parent service of the action.
Warning:
the pointer is guaranteed to point to a valid object as long as the HAction exists, which ultimately is as long as the containing Herqq::Upnp::HDevice exists.
See also:
HDevice
const HActionInfo & info (  )  const

Returns information about the action that is read from the service description.

Returns:
information about the action that is read from the service description.
HAsyncOp beginInvoke ( const HActionArguments inArgs,
HExecArgs execArgs = 0 
)

Schedules the action to be invoked.

The method performs an asynchronous action invocation. The invocation is placed in queue and will be executed on a random thread pool thread as soon as possible. Therefore, the following issues are important to be noted:

  • The method is thread-safe.
  • The order of invocations is the order in which beginInvoke() methods are invoked.
  • The method returns immediately.

Unless you specified the action to be executed as fire and forget, the signal invokeComplete() is emitted once the invocation is complete. After that, you have to call waitForInvoke() with the proper action invocation id to retrieve the result of the invocation.

Parameters:
inArgs specifies the input arguments for the action invocation.
execArgs specifies information used to control the execution of the action invocation procedure. This is optional.
Returns:
the ID used to identify the asynchronous operation. Once the invokeComplete() signal is emitted, you have to call waitForInvoke() providing this ID to retrieve the result of the action invocation.
Remarks:

Unless you specified the action to be executed as fire and forget, the following remarks are important to notice:

See also:
waitForInvoke(), invoke()
HAsyncOp beginInvoke ( const HActionArguments inArgs,
const HActionInvokeCallback completionCallback,
HExecArgs execArgs = 0 
)

Schedules the action to be invoked.

The method performs an asynchronous action invocation. The invocation is placed in queue and will be executed on a random thread pool thread as soon as possible. Therefore, the following issues are important to be noted:

  • The method is thread-safe.
  • The order of invocations is the order in which beginInvoke() methods are invoked.
  • The method returns immediately.

Unless you specified the action to be executed as fire and forget, the specified callback is called when the invocation is complete. No events are sent unless that is explicitly wanted by returning true from the callback function. You have to call waitForInvoke() with the proper action invocation id to retrieve the result of the invocation.

The different semantics compared to the other beginInvoke() method are important to notice:

  • If a completion callback is valid, no event is sent unless the invoker explicitly requests so.
  • The callback is always invoked immediately after the invocation has succeeded or failed in the thread that executed the action. Note, that the time requirements to return from the callback are usually far less severe than they are with slots executed in the eventloop thread. However, the callback should still return as soon as possible. Again, this assumes that the invocation wasn't started as fire and forget.
Parameters:
inArgs specifies the input arguments for the action invocation
completionCallback specifies the callable entity that is called once the action invocation is completed or failed. If the specified callable entity is not valid and it cannot be called, the callable entity is ignored and events are sent instead.
execArgs specifies information used to control the execution of the action invocation procedure. This is optional.
Returns:
the ID used to identify the asynchronous operation. Once the callback is called and possibly the invokeComplete() signal is emitted, you have to call waitForInvoke() providing this ID to retrieve the result of the action invocation.
Remarks:

Unless you specified the action to be executed as fire and forget, the following remarks are important to notice:

See also:
waitForInvoke(), invoke()
bool waitForInvoke ( HAsyncOp asyncOp,
HActionArguments outArgs = 0 
)

Waits for the completion of an asynchronous action invocation started by beginInvoke().

You have to call this method to retrieve the result of an action invocation. In addition, you can use this method to block the current thread until the specified action invocation is complete.

If the action invocation corresponding to the specified asyncOp has completed and this is the first call to this method with the specified asyncOp, the call will return immediately. If the invocation has not been completed at the time of this call, the calling thread will be blocked until the action invocation is complete.

Note also, that you can call this method only once with a particular asyncOp. The results of the action invocation are stored until a call is made, unless the invocation was executed as fire and forget, in which case nothing is stored and no results will be available.

Parameters:
asyncOp specifies the action invocation previously started by beginInvoke(). If the parameter is invalid, the method returns immediately with an error code.
outArgs specifies a pointer to a HActionArguments object that the user has created, or null, in case the output arguments aren't wanted. In case the wait was successfully completed and a valid pointer to object was provided by the user, the object will contain the output arguments of the action invocation. If the action has no output arguments, the parameter is ignored.
Returns:
true in case both the wait and the action invocation succeeded. Otherwise you may want to check the HAsyncOp::waitCode() and HAsyncOp::returnValue() for more information about the failure.
Note:
the HAsyncOp::returnValue() will be HAction::Success on success. Any other value indicates that an error occurred.
See also:
beginInvoke(), ReturnCode
qint32 invoke ( const HActionArguments inArgs,
HActionArguments outArgs = 0 
)

Invokes the action synchronously.

This is a helper method for calling beginInvoke() and waitForInvoke().

For example,

 Herqq::Upnp::HActionArguments inArgs = action->info().inputArguments();
 inArgs["EchoInArgument"]->setValue("Ping");

 Herqq::Upnp::HActionArguments outArgs;

 qint32 retVal = action->invoke(inArgs, &outArgs);
 if (retVal == Herqq::Upnp::HAction::Success)
 {
     qDebug() << outArgs["EchoOutArgument"]->value().toString();
 }
Parameters:
inArgs specifies the input arguments for the action.
outArgs specifies a pointer to an object created by the user. This can be null in which case the output arguments will not be set even if the action has output arguments. If the parameter is specified and the action has output arguments, the values of the arguments will be set accordingly. If the action doesn't have output arguments, the parameter is ignored.
Returns:
HAction::Success on success. Any other value indicates that an error occurred.
See also:
beginInvoke(), waitForInvoke(), ReturnCode
QString errorCodeToString ( qint32  errCode  )  [static]

Returns a string representation of the specified error code.

Parameters:
errCode specififes the error code.
Returns:
a string representation of the specified error code.
void invokeComplete ( Herqq::Upnp::HAsyncOp  asyncOp  )  [signal]

Unless an invocation was started as fire and forget, this signal is emitted when the invocation has been successfully completed or the invocation failed.

After this signal is received, you have to call waitForInvoke() to retrieve the result of the action invocation.

Parameters:
asyncOp specifies the asynchronous operation that completed.