A class that represents a UPnP action found in a UPnP service. More...
#include <HAction>
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) |
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.
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.
~HAction | ( | ) | [virtual] |
HService * parentService | ( | ) | const |
Returns the parent service of the action.
HAction
exists, which ultimately is as long as the containing Herqq::Upnp::HDevice exists.const HActionInfo & info | ( | ) | const |
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:
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.
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. |
Unless you specified the action to be executed as fire and forget, the following remarks are important to notice:
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:
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:
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. |
Unless you specified the action to be executed as fire and forget, the following remarks are important to notice:
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.
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. |
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(); }
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. |
QString errorCodeToString | ( | qint32 | errCode | ) | [static] |
Returns a string representation of the specified error code.
errCode | specififes the 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.
asyncOp | specifies the asynchronous operation that completed. |