Public Member Functions | Static Public Member Functions | Friends | Related Functions

# HAsyncOp Class Reference
[Device Model]

This class is used to identify an asynchronous operation and detail information of it. More...

`#include <HAsyncOp>`

List of all members.

## Public Member Functions
| HAsyncOp ()
| ~HAsyncOp ()
| HAsyncOp (const HAsyncOp &)
QString | errorDescription () const
void | setErrorDescription (const QString &arg)
qint32 | waitTimeout () const
void | setWaitTimeout (qint32 timeout)
AsyncWaitCode | waitCode () const
void | setWaitCode (AsyncWaitCode waitCode)
qint32 | returnValue () const
void | setReturnValue (qint32 returnValue)
void | setUserData (void *userData)
void * | userData () const
QUuid | id () const
bool | isNull () const
## Static Public Member Functions
static HAsyncOp | createInvalid (qint32 returnCode, const QString &errorDescr)
## Friends
H_UPNP_CORE_EXPORT bool | operator== (const HAsyncOp &, const HAsyncOp &)
## Related Functions
(Note that these are not member functions.)
H_UPNP_CORE_EXPORT bool | operator!= (const HAsyncOp &, const HAsyncOp &)
H_UPNP_CORE_EXPORT quint32 | qHash (const HAsyncOp &key)

## Detailed Description

Some HUPnP components provide an asynchronous interface for running possible long-standing operations. A most notable example of this is the action invocation (HAction::beginInvoke()). In these cases this class is used to identify, describe and control some aspects of the execution and the wait for the completion of the operation.

## Usage

The component that runs an asynchronous operation always provides an instance of this class when the operation is started and when it signals the operation is complete. The provided instance identifies the operation and it, or any copy of it is provided to the runner of the asynchronous operation when the result of the operation is retrieved or waited upon.

For example:

     HAsyncOp op = someObject->beginSomeAsyncOp();

     // if you do not know the operation is complete, the following wait could be
     // indefinite, unless you specify it not to be:
     op.setWaitTimeout(5000); // 5 seconds
     someObject->waitForSomeAsyncOp(&op);

     // after the wait you can check what happened with the wait by calling
     HAsyncOp::WaitCode wcode = op.waitCode();

     // and if the operation uses an integer as a return value, you can query it
     // by calling:
     qint32 retVal = op.returnValue();

The above example highlights two different return codes that have two different purposes, the wait code and the return value of the asynchronous operation. The wait code specifies the result of the wait operation; it tells whether the wait operation succeeded. A wait can be successful even if the asynchronous operation failed and vice versa; a wait can fail even if the asynchronous operation eventually succeeds.

All the HUPnP's waitFor() methods used to retrieve the results of asynchronous operations use `bool` as a return value to indicate if both the wait and the asynchronous operation succeeded. For instance,

     HAsyncOp op = someObject->beginSomeAsyncOp();
     if (!someObject->waitForSomeAsyncOp(&op))
     {
         // Either the wait or the asynchronous operation failed. You can check
         // the wait code to see if it was the wait that failed:
         if (op.waitCode() != HAsyncOp::WaitSuccess)
         {
             // It was the wait that failed. This means that the operation is
             // still running and it may still succeed normally.
         }
         else if (op.returnValue() != SomeErrorCodeThatIndicatesSuccess)
         {
            // It was the asynchronous operation that failed.
         }
     }

In some scenarios it is useful to pass custom data within an HAsyncOp. For example,

     void MyQObject::slotToBeCalledWhenAsyncOpCompletes(HAsyncOp op)
     {
         SomeClass* someObject = reinterpret_cast<SomeClass*>(op.userData());
         someObject->waitForSomeAsyncOp(&op);
     }

     void MyQObject::someMethod()
     {
         HAsyncOp op = someObject->beginSomeAsyncOp();
         op.setUserData(reinterpret_cast<void*>(someObject));
         // call executes and the above slot gets called once the operation completes
         // (or fails)
     }

Note, the user data is retrievable from any copy of the object that was used to set the data. If an instance is created by the runner of an asynchronous operation, setting the userData of that instance will associate the userData with all the copies the runner uses too. From this follows that when the runner informs the user an operation is finished, the provided HAsyncOp object contains the previously set userData.

Note also that the user data is never referenced by the runner of an asynchronous operation. This also means that the ownership of the data is never transferred.

Remarks:
  this class is thread-safe.

## Member Enumeration Documentation

enum AsyncWaitCode

This enumeration specifies the values the waiting for the completion of an asynchronous operation can return.

Enumerator:

  WaitSuccess | The asynchronous operation was successfully completed.
  WaitTimeout | A timeout elapsed before the asynchronous operation was completed.
  WaitInvalidId | The specified asynchronous operation ID is invalid.
  WaitListenerRegisteredAlready | The result of an asynchronous operation can be waited by a single listener and the operation in question already has a listener.
  WaitAborted | The wait for the completion of an asynchronous operation was aborted.
  WaitInvalidObjectState | The object in question cannot execute the specified asynchronous operation at the moment.
  WaitInvalidOperation | The asynchronous operation cannot be waited upon. For instance, this is the case when the operation is launched with fire and forget semantics (HExecArgs::FireAndForget).

## Constructor & Destructor Documentation

HAsyncOp | ( |  | ) | `[explicit]`

Creates a new valid instance.

Creates a new valid instance, i.e isNull() always returns false.

See also:
  isNull(), createInvalid()

~HAsyncOp | ( |  | ) |

Destroys the instance.

HAsyncOp | ( | const HAsyncOp & | other | ) |

Copy constructor.

## Member Function Documentation

QString errorDescription | ( |  | ) | const

Returns a human readable error description.

Returns:
  a human readable error description, if any. This is never set when waitCode() is HAsyncOp::WaitSuccess or isNull() returns false, but it may not be set even when isNull() returns true.

See also:
  setErrorDescription()

void setErrorDescription | ( | const QString & | arg | ) |

Sets a human readable error description.

Parameters:

  | arg | specifies the human readable error description.

See also:
  errorDescription()

qint32 waitTimeout | ( |  | ) | const`[inline]`

Returns the wait timeout in milliseconds -if any- associated with the operation.

Returns:
  the wait timeout in milliseconds -if any- associated with the operation.

See also:
  setWaitTimeout()

void setWaitTimeout | ( | qint32 | timeout | ) | `[inline]`

Sets the wait timeout in milliseconds for the operation.

Parameters:

  | timeout | specifies the wait timeout in milliseconds. A negative value means that the timeout isn't set.

See also:
  waitTimeout()

AsyncWaitCode waitCode | ( |  | ) | const`[inline]`

Returns the return value of the wait of operation completion.

Returns:
  the return value of the wait of operation completion.

See also:
  setWaitCode()

void setWaitCode | ( | AsyncWaitCode | waitCode | ) | `[inline]`

Sets the return value of the wait of operation completion.

Parameters:

  | waitCode | specifies the return value of the wait of operation completion.

See also:
  waitCode()

qint32 returnValue | ( |  | ) | const`[inline]`

Returns the return value of the asynchronous operation.

See also:
  setReturnValue()

void setReturnValue | ( | qint32 | returnValue | ) | `[inline]`

Sets the return value of the asynchronous operation.

Parameters:

  | returnValue | specifies the return value of the asynchronous operation.

See also:
  returnValue()

void setUserData | ( | void * | userData | ) |

Associates arbitrary user provided data with the asynchronous operation.

Parameters:

  | userData | is the pointer to arbitrary user data.

Remarks:
  the instance never references the provided data.

See also:
  userData()

void * userData | ( |  | ) | const

Returns the user provided data if set.

Returns:
  a pointer to user provided data or null if the user data isn't set.

See also:
  setUserData()

QUuid id | ( |  | ) | const`[inline]`

Returns universally unique identifier of the asynchronous operation.

Returns:
  universally unique identifier of the asynchronous operation.

bool isNull | ( |  | ) | const`[inline]`

Indicates whether the object identifies an asynchronous operation.

Returns:
  true in case the object identifies an asynchronous operation.

HAsyncOp createInvalid | ( | qint32 | returnCode,
|  | const QString & | errorDescr |
| ) |  |  | `[static]`

Creates a new invalid instance.

An invalid HAsyncOp represents an asynchronous operation that failed to begin. Note, isNull() returns true always.

Parameters:

  | returnCode | specifies the return code.
  | errorDescr | specifies the human readable error description.

See also:
  returnCode(), errorDescription(), isNull()

## Friends And Related Function Documentation

H_UPNP_CORE_EXPORT bool operator== | ( | const HAsyncOp & | ,
|  | const HAsyncOp & |  |
| ) |  |  | `[friend]`

Compares the two objects for equality.

Returns:
  true in case the object are logically equivalent.

H_UPNP_CORE_EXPORT bool operator!= | ( | const HAsyncOp & | ,
|  | const HAsyncOp & |  |
| ) |  |  | `[related]`

Compares the two objects for inequality.

Returns:
  true in case the object are not logically equivalent.

H_UPNP_CORE_EXPORT quint32 qHash | ( | const HAsyncOp & | key | ) | `[related]`

Returns a value that can be used as a unique key in a hash-map identifying the object.

Parameters:

  | key | specifies the HAsyncOp object from which the hash value is created.

Returns:
  a value that can be used as a unique key in a hash-map identifying the object.