Herqq

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files

- Class List
- Class Hierarchy
- Class Members

Signals | Public Member Functions | Protected Member Functions

# HClientAction Class Reference
Device Model

A client-side class that represents a server-side UPnP action. More...

`#include <HClientAction>`

Inherited by HDefaultClientAction.

List of all members.

## Signals
void | invokeComplete (Herqq::Upnp::HClientAction *source, const Herqq::Upnp::HClientActionOp &operation)
## Public Member Functions
virtual | ~HClientAction ()=0
HClientService * | parentService () const
const HActionInfo & | info () const
HClientActionOp | beginInvoke (const HActionArguments &inArgs, HExecArgs *execArgs=0)
HClientActionOp | beginInvoke (const HActionArguments &inArgs, const HActionInvokeCallback &completionCallback, HExecArgs *execArgs=0)
## Protected Member Functions
| HClientAction (const HActionInfo &info, HClientService *parent)

## Detailed Description

A client-side class that represents a server-side UPnP action.

`HClientAction` is a core component of the HUPnP's client-side Device Model and it models a UPnP action. The UPnP Device Architecture specifies a UPnP action as a command, which takes one or more input and output arguments and that may have a return value.

This class is used to invoke the server-side UPnP actions from the client-side. You can get information of the action using info(), which includes the action's input and output arguments. You can dispatch an asynchronous action invocation to the server-side using beginInvoke(). Once the server responds, invokeComplete() signal is sent.

See also:
  HActionInfo, HClientService

Remarks:
  - This class has thread-affinity.

## Constructor & Destructor Documentation

HClientAction | ( | const HActionInfo & | info,
|  | HClientService * | parent
| ) |  | `[protected]`

Creates a new instance.

Parameters:

  info | specifies information of the action.
  parent | specifies the UPnP service that contains this action.

~HClientAction | ( |  | ) | `[pure virtual]`

Destroys the instance.

An `HClientAction` is always destroyed by the `HClientAction` that contains it when it is being deleted. Further, unless you hold the ownership of the `HClientAction` instance, you should never destroy it.

## Member Function Documentation

HClientService* 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 `HClientAction` exists, which ultimately is as long as the containing root device exists.

See also:
  HClientDevice

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.

HClientActionOp 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 a queue and it will be run once it's at the head of the queue.

Unless you specified the action to be executed as fire and forget, the signal invokeComplete() is emitted once the invocation is complete.

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:
  an object that identifies the asynchronous operation. This object will be sent through the invokeComplete() signal once the invocation is done.

See also:
  invokeComplete()

HClientActionOp 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 a queue and it will be run once it's at the head of the queue.

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 requested by returning true from the callback function.

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 that.
- The callback is always invoked immediately after the invocation has succeeded or failed. If the callback returns true, the invokeComplete() signal will be emitted immediately after.

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 the invokeComplete() signal is sent sent instead.
  execArgs | specifies information used to control the execution of the action invocation procedure. This is optional.

Returns:
  an object that identifies the asynchronous operation. This object will be sent through the callback and the invokeComplete() once the invocation is done.

See also:
  invokeComplete()

void invokeComplete | ( | Herqq::Upnp::HClientAction * | source,
|  | const Herqq::Upnp::HClientActionOp & | operation
| ) |  | `[signal]`

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

Parameters:

  source | identifies the HClientAction that ran the operation.
  operation | specifies information of the operation that completed.

See also:
  beginInvoke()

Remarks:
  This signal has thread affinity to the thread where the object resides. Do not connect to this signal from other threads.