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

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.