Active -objects

diff -r 4816d766a08a -r f345bda72bc4 Symbian3/PDK/Source/GUID-890F06C6-DE32-5EB1-BF0F-D41794F47AE1.dita --- a/Symbian3/PDK/Source/GUID-890F06C6-DE32-5EB1-BF0F-D41794F47AE1.dita Tue Mar 30 11:42:04 2010 +0100 +++ b/Symbian3/PDK/Source/GUID-890F06C6-DE32-5EB1-BF0F-D41794F47AE1.dita Tue Mar 30 11:56:28 2010 +0100 @@ -1,65 +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.