Active +objects

diff -r 43e37759235e -r 51a74ef9ed63 Symbian3/SDK/Source/GUID-890F06C6-DE32-5EB1-BF0F-D41794F47AE1.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-890F06C6-DE32-5EB1-BF0F-D41794F47AE1.dita Wed Mar 31 11:11:55 2010 +0100 @@ -0,0 +1,65 @@ + + + + + +Active +objectsThis document describes the functionality and class membership +of active objects. +

An active object uses an asynchronous service provider class to provide +a service. The active object hides the asynchronous service provider. The +active object must provide:

a function that requests +a service from the service provider
a function that cancels +a request for service from the service provider.

All active objects are derived from CActive. This class +provides derived active objects with:

the data member iStatus. +This data member is a TRequestStatus type object. This object +is passed to the request functions of the asynchronous service provider. The +request functions of the active object do not include a TRequestStatus in +their parameters. The exception to this rule occurs when the active object +acts as a secondary supplier of asynchronous services.
the Cancel() function. +This function cancels a request to the service provider. Cancel() does +nothing if there is no outstanding request. If a request is pending, Cancel() calls DoCancel(). DoCancel() is a pure virtual function that a derived class supplies. DoCancel() must +deal with the specific cancellation behavior that the service provider requires. Cancel() waits +for the request to complete and then marks the request not active.
the TPriority enumeration. +This enumeration defines the set of priorities that an active object can take. +The priority of the active object is set during construction of the active +object. When the active scheduler's wait completes, it checks the active object +with the highest priority. Where active objects have the same priority, the +order of checking is not defined.

Classes derived from CActive must:

own an asynchronous +service provider. It may do this by containing either an instance of the required +service provider or a handle to that provider.
provide one or more +request functions, such as IssueRequest(), which pass on +the request to an asynchronous service provider.
implement a DoCancel() function +which passes on a cancel request to the asynchronous service provider
provide a RunL() function, +which is called by the active scheduler when it detects that an active object’s +request has completed.
provide a RunError() function, +which is called by the active scheduler if the active object's RunL() function +leaves. A derived class can use the default implementation but this just propagates +the leave code up to the active scheduler.