![[Index]](../../../stock/btn_index.gif){kind=small}
![[Glossary]](../../../stock/btn_glossary.gif){kind=small}
![[Previous]](../../../stock/btn_prev.gif){kind=small}
![[Next]](../../../stock/btn_next.gif){kind=small}
| |
|
| |
Location:
e32base.h
Link against: euser.lib
CActive
Supported from 5.0
The core class of the active object abstraction. It encapsulates both the issuing of a request to an asynchronous service provider and the handling of completed requests. An application can have one or more active objects whose processing is controlled by an active scheduler.
|
Defined in CActive:
CActive(), Cancel(), Deque(), DoCancel(), EPriorityHigh, EPriorityIdle, EPriorityLow, EPriorityStandard, EPriorityUserInput, IsActive(), IsAdded(), Priority(), RunError(), RunL(), SetActive(), SetPriority(), TPriority, iStatus, ~CActive()
Inherited from CBase:
operator new()
protected: CActive(TInt aPriority);
Constructs the active object with the specified priority.
Derived classes must define and implement a constructor through which the priority can be specified. A typical implementation calls this active object constructor through a constructor initialization list.
|
~CActive();
Frees resources prior to destruction. Specifically, it removes this active object from the active scheduler’s list of active objects.
The active object must not have an outstanding request when the destructor is called, otherwise an E32USER-CBase 40 panic is raised.
Typically, a derived class calls Cancel() in its destructor.
|
TBool IsActive() const;
Determines whether the active object has a request outstanding.
A request is outstanding when:
it has been issued
it has not been cancelled
it servicing has not yet begun.
|
protected: void SetActive();
Indicates that the active object has issued a request and that it is now outstanding. Derived classes must call this function after issuing a request.
A request is automatically marked as complete (i.e. it is no longer outstanding) by:
the active scheduler, immediately before it calls the active object’s RunL() function.
or
the active object within the implementation of the Cancel() function.
TBool IsAdded() const;
Determines whether the active object has been added to the active scheduler’s list of active objects.
If the active object has not been added to a scheduler, it cannot handle the completion of any request. No request should be issued until the active object has been added to a scheduler because completion of that request generates what appears to be a stray signal.
Use the active object function Deque() to remove the active object from the scheduler.
|
|
void SetPriority(TInt aPriority);
Sets the priority of the active object.
The function raises an E32USER-CBase 50 panic if it is called while a request is outstanding.
|
TInt Priority() const;
Returns the priority of the active object.
|
|
protected: virtual void RunL() = 0;
Handles an active object’s request completion event.
A derived class must provide an implementation to handle the completed request. If appropriate, it may issue another request.
The function is called by the active scheduler when a request completion
event occurs, i.e. after the active
scheduler’sWaitForAnyRequest()function completes.
Before calling this active object’s RunL() function,
the active scheduler has:
decided that this is the highest priority active object with a completed request
marked this active object’s request as complete (i.e. the request is no longer outstanding)
RunL() runs under a trap harness in the active scheduler. If
it leaves, then the active scheduler calls RunError() to handle
the leave.
Note that once the active scheduler’s Start()function
has been called, all user code is run under one of the program's active
object's RunL()or
RunError()functions.
|
virtual TInt RunError(TInt aError);
Supported from 6.0
Handles a leave occurring in the request completion event
handlerRunL().
The active scheduler calls this function if this active
object'sRunL() function leaves. This gives this active object the
opportunity to perform any necessary cleanup.
A derived class implementation should handle the leave and
returnKErrNone. Returning any other value results in the active
scheduler function CActiveScheduler::Error() being called.
The default implementation simply returns the leave code.
Note that if the active scheduler is to handle the error, a suitably
derived CActiveScheduler::Error() function must be
supplied.
|
|
|
void Cancel();
Cancels the wait for completion of an outstanding request. If there is no request outstanding, then the function does nothing.
If there is an outstanding request, the function:
calls the active object’s DoCancel() function,
provided by the derived class, to implement cancellation of the request.
waits for the cancelled request to complete; this must complete as fast as possible.
marks the active object’s request as complete (i.e. the request is no longer outstanding).
protected: virtual void DoCancel() =0
Implements cancellation of an outstanding request. This function is called as part of the active object’s Cancel().
It must call the appropriate cancel function offered by the active object’s asynchronous service provider. The asynchronous service provider’s cancel is expected to act immediately.
DoCancel() must not wait for event completion; this is
handled byCancel().
void Deque();
Removes the active object from the active scheduler’s list of active objects.
Before being removed from the active scheduler’s list, the function cancels any outstanding request.
|
TRequestStatus iStatus
The request status associated with an asynchronous request. This is passed as a parameter to all asynchronous service providers.
The active scheduler uses this to check whether the active object’s request has completed.
The function can use the completion code to judge the success or otherwise of the request.
|
TPriority
Defines standard priorities for active objects.
|
Copyright ©2002 Symbian Ltd. 6.1-00174 |
|
![[Top]](../../../stock/arrow_up_2.gif){kind=icon}
![[Top]](../../../stock/arrow_up.gif){kind=icon}