Herqq
Signals | Public Member Functions | Protected Member Functions

HClientAction Class Reference

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
HClientServiceparentService () const
const HActionInfoinfo () 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:
infospecifies information of the action.
parentspecifies 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:
inArgsspecifies the input arguments for the action invocation.
execArgsspecifies 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:
inArgsspecifies the input arguments for the action invocation
completionCallbackspecifies 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.
execArgsspecifies 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:
sourceidentifies the HClientAction that ran the operation.
operationspecifies 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.