This class is used to identify an asynchronous operation and detail information of it. More...
#include <HAsyncOp>
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) |
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.
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.
enum AsyncWaitCode |
This enumeration specifies the values the waiting for the completion of an asynchronous operation can return.
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). |
HAsyncOp | ( | ) | [explicit] |
Creates a new valid instance.
Creates a new valid instance, i.e isNull() always returns false.
~HAsyncOp | ( | ) |
Destroys the instance.
QString errorDescription | ( | ) | const |
Returns a human readable error description.
void setErrorDescription | ( | const QString & | arg | ) |
Sets a human readable error description.
arg | specifies the human readable error description. |
qint32 waitTimeout | ( | ) | const [inline] |
Returns the wait timeout in milliseconds -if any- associated with the operation.
void setWaitTimeout | ( | qint32 | timeout | ) | [inline] |
Sets the wait timeout in milliseconds for the operation.
timeout | specifies the wait timeout in milliseconds. A negative value means that the timeout isn't set. |
AsyncWaitCode waitCode | ( | ) | const [inline] |
Returns the return value of the wait of operation completion.
void setWaitCode | ( | AsyncWaitCode | waitCode | ) | [inline] |
Sets the return value of the wait of operation completion.
waitCode | specifies the return value of the wait of operation completion. |
qint32 returnValue | ( | ) | const [inline] |
Returns the return value of the asynchronous operation.
void setReturnValue | ( | qint32 | returnValue | ) | [inline] |
Sets the return value of the asynchronous operation.
returnValue | specifies the return value of the asynchronous operation. |
void setUserData | ( | void * | userData | ) |
Associates arbitrary user provided data with the asynchronous operation.
userData | is the pointer to arbitrary user data. |
void * userData | ( | ) | const |
Returns the user provided data if set.
QUuid id | ( | ) | const [inline] |
Returns universally unique identifier of the asynchronous operation.
bool isNull | ( | ) | const [inline] |
Indicates whether 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.
returnCode | specifies the return code. | |
errorDescr | specifies the human readable error description. |
Compares the two objects for equality.
Compares the two objects for inequality.
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.
key | specifies the HAsyncOp object from which the hash value is created. |