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 &) | |
HAsyncOp & | operator= (const HAsyncOp &) |
QString | errorDescription () const |
void | setErrorDescription (const QString &arg) |
int | returnValue () const |
void | setReturnValue (int returnValue) |
void | setUserData (void *userData) |
void * | userData () const |
unsigned int | id () const |
bool | isNull () const |
Static Public Member Functions | |
static HAsyncOp | createInvalid (int 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 &) |
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 client-side action invocation initiated with HClientAction::beginInvoke(). In cases like this, instances of this class are used to identify and describe the operations.
The component that runs an asynchronous operation provides an instance of this class when the operation is started. A copy of this instance is provided also when the component signals the operation is complete. The provided instance uniquely identifies the operation, carries information whether the operation eventually succeeded or not, may contain an error description in case of an error and can be used to pass user-defined data from instance to another.
For example:
HAsyncOp op = someObject->beginSomeAsyncOp(); // // The operation completes, after which you can: // int retVal = op.returnValue(); // retrieve a return value indicating whether the operation succeeded. QString errDescr = op.errorDescription(); // retrieve an error description if the operation 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 contents of the instance are retrievable from any copy of the object. That is, the copy constructor and assignment operator make shallow copies of the contents. So for example if an HAsyncOp
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 and you can read the returnValue() from the originally received instance.
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 and you have to ensure the memory is handled correctly in that regard.
HAsyncOp | ( | ) |
Creates a new valid instance.
Creates a new valid instance, i.e isNull() always returns false.
~HAsyncOp | ( | ) |
Destroys the instance.
Decreases the reference count or destroys the instance once the reference count drops to zero.
Copy constructor.
Creates a shallow copy of other increasing the reference count of other.
Assignment operator.
Switches this instance to refer to the contents of other increasing the reference count of other.
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. |
int returnValue | ( | ) | const |
Returns the return value of the asynchronous operation.
void setReturnValue | ( | int | returnValue ) |
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.
unsigned int id | ( | ) | const |
Returns an identifier of the asynchronous operation.
bool isNull | ( | ) | const |
Indicates whether the object identifies an asynchronous operation.
HAsyncOp createInvalid | ( | int | 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.
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. |