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 &)
HAsyncOpoperator= (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)

Detailed Description

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.

Usage

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.

Remarks:
this class is thread-safe.

Constructor & Destructor Documentation

HAsyncOp (  )

Creates a new valid instance.

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

See also:
isNull(), createInvalid()
~HAsyncOp (  )

Destroys the instance.

Decreases the reference count or destroys the instance once the reference count drops to zero.

HAsyncOp ( const HAsyncOp op )

Copy constructor.

Creates a shallow copy of other increasing the reference count of other.


Member Function Documentation

HAsyncOp & operator= ( const HAsyncOp op )

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.

Returns:
a human readable error description, if any.
See also:
setErrorDescription()
void setErrorDescription ( const QString &  arg )

Sets a human readable error description.

Parameters:
argspecifies the human readable error description.
See also:
errorDescription()
int returnValue (  ) const

Returns the return value of the asynchronous operation.

See also:
setReturnValue()
void setReturnValue ( int  returnValue )

Sets the return value of the asynchronous operation.

Parameters:
returnValuespecifies the return value of the asynchronous operation.
See also:
returnValue()
void setUserData ( void *  userData )

Associates arbitrary user provided data with the asynchronous operation.

Parameters:
userDatais 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()
unsigned int id (  ) const

Returns an identifier of the asynchronous operation.

Returns:
an identifier of the asynchronous operation. The identifier is "unique" within the process where the library is loaded. More specifically, the ID is monotonically incremented and it is allowed to overflow.
bool isNull (  ) const

Indicates whether the object identifies an asynchronous operation.

Returns:
true in case 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.

Parameters:
returnCodespecifies the return code.
errorDescrspecifies 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.
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:
keyspecifies 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.