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 ()
HService * | parentService () const
const HActionInfo & | info () 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:

- The invokeComplete() signal is always emitted, even if you have called waitForInvoke() before that.
- waitForInvoke() with a proper ID will complete before the invokeComplete() signal is sent.

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:

- the completion callback is always called, even if you have called waitForInvoke()
- waitForInvoke() with a proper ID will complete before the callback is called and possibly the invokeComplete() signal is sent.

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.