CActive Class Reference

The core class of the active object abstraction. More...

#include <e32base.h>

Inheritance diagram for CActive:

Public Types
enum	TPriority {   EPriorityIdle =-100 , EPriorityLow =-20 , EPriorityStandard =0 , EPriorityUserInput =10 ,   EPriorityHigh =20 }
	Defines standard priorities for active objects. More...

Public Member Functions
IMPORT_C	~CActive ()
	Frees resources prior to destruction.
IMPORT_C void	Cancel ()
	Cancels the wait for completion of an outstanding request.
IMPORT_C void	Deque ()
	Removes the active object from the active scheduler's list of active objects.
IMPORT_C void	SetPriority (TInt aPriority)
	Sets the priority of the active object.
TBool	IsActive () const
	Determines whether the active object has a request outstanding.
TBool	IsAdded () const
	Determines whether the active object has been added to the active scheduler's list of active objects.
TInt	Priority () const
	Gets the priority of the active object.
Public Member Functions inherited from CBase
	CBase ()
	Default constructor.
virtual IMPORT_C	~CBase ()
	Virtual destructor.
TAny *	operator new (TUint aSize, TAny *aBase) __NO_THROW
	Initialises the object to binary zeroes.
TAny *	operator new (TUint aSize) __NO_THROW
	Allocates the object from the heap and then initialises its contents to binary zeroes.
TAny *	operator new (TUint aSize, TLeave)
	Allocates the object from the heap and then initialises its contents to binary zeroes.
TAny *	operator new (TUint aSize, TUint aExtraSize) __NO_THROW
	Allocates the object from the heap and then initialises its contents to binary zeroes.
TAny *	operator new (TUint aSize, TLeave, TUint aExtraSize)
	Allocates the object from the heap and then initialises its contents to binary zeroes.

Public Attributes
TRequestStatus	iStatus
	The request status associated with an asynchronous request.

Protected Member Functions
IMPORT_C	CActive (TInt aPriority)
	Constructs the active object with the specified priority.
IMPORT_C void	SetActive ()
	Indicates that the active object has issued a request and that it is now outstanding.
virtual void	DoCancel ()=0
	Implements cancellation of an outstanding request.
virtual void	RunL ()=0
	Handles an active object's request completion event.
virtual IMPORT_C TInt	RunError (TInt aError)
	Handles a leave occurring in the request completion event handler RunL().
virtual IMPORT_C TInt	Extension_ (TUint aExtensionId, TAny *&a0, TAny *a1)
	Extension function.

Friends
class	CActiveScheduler
class	CServer
class	CServer2

Additional Inherited Members
Static Public Member Functions inherited from CBase
static IMPORT_C void	Delete (CBase *aPtr)
	Deletes the specified object.

Detailed Description

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.

API status

Published to all clients. Released API.

Definition at line 1625 of file e32base.h.

Member Enumeration Documentation

TPriority

enum CActive::TPriority

Defines standard priorities for active objects.

Enumerator
EPriorityIdle	A low priority, useful for active objects representing background processing.
EPriorityLow	A priority higher than EPriorityIdle but lower than EPriorityStandard.
EPriorityStandard	Most active objects will have this priority.
EPriorityUserInput	A priority higher than EPriorityStandard; useful for active objects handling user input.
EPriorityHigh	A priority higher than EPriorityUserInput.

Definition at line 1644 of file e32base.h.

Constructor & Destructor Documentation

~CActive()

IMPORT_C CActive::~CActive

(

)

Frees resources prior to destruction.

Specifically, it removes this active object from the active scheduler's list of active objects.

Typically, a derived class calls Cancel() in its destructor.

Panic condition: E32USER-CBase 40 if the active object has an outstanding request when the destructor is called,

(generated from Symbian Developer Library)

CActive()

IMPORT_C CActive::CActive ( TInt  aPriority )

protected

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.

Parameters

aPriority

An integer specifying the priority of this active object. CActive::TPriority defines a standard set of priorities.

(generated from Symbian Developer Library)

Member Function Documentation

Cancel()

IMPORT_C void CActive::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:

1. calls the active object's DoCancel() function, provided by the derived class to implement cancellation of the request.
2. waits for the cancelled request to complete; this must complete as fast as possible.
3. marks the active object's request as complete (i.e. the request is no longer outstanding).

CActive::DoCancel CActive::IsActive CActive::~CActive User::WaitForRequest

(generated from Symbian Developer Library)

Deque()

IMPORT_C void CActive::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.

CActive::Cancel

(generated from Symbian Developer Library)

DoCancel()

virtual void CActive::DoCancel ( )

protectedpure virtual

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 by Cancel().

See also

CActive::Cancel

Implemented in CIdle, CAsyncOneShot, CTimer, and CServer2.

Extension_()

IMPORT_C TInt CActive::Extension_ ( TUint  aExtensionId, TAny *&  a0, TAny *  a1  )

protectedvirtual

Extension function.

(generated from Symbian Developer Library)

Reimplemented from CBase.

Reimplemented in CServer2, and CPolicyServer.

IsActive()

TBool CActive::IsActive ( ) const

inline

Determines whether the active object has a request outstanding.

A request is outstanding when:

1. it has been issued
2. it has not been cancelled
3. it servicing has not yet begun.

(generated from Symbian Developer Library)

IsAdded()

TBool CActive::IsAdded ( ) const

inline

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.

CActive::Deque

(generated from Symbian Developer Library)

Priority()

TInt CActive::Priority ( ) const

inline

Gets the priority of the active object.

(generated from Symbian Developer Library)

RunError()

IMPORT_C TInt CActive::RunError ( TInt  aError )

protectedvirtual

Handles a leave occurring in the request completion event handler RunL().

The active scheduler calls this function if this active object's RunL() function leaves. This gives this active object the opportunity to perform any necessary cleanup.

A derived class implementation should handle the leave and return KErrNone. 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.

CActiveScheduler::Error

Parameters

aError

The leave code

(generated from Symbian Developer Library)

Reimplemented in CServer2.

RunL()

virtual void CActive::RunL ( )

protectedpure virtual

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's WaitForAnyRequest() function completes.

Before calling this active object's RunL() function, the active scheduler has:

1. decided that this is the highest priority active object with a completed request
2. 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.

See also

CActiveScheduler::Start

CActiveScheduler::Error

CActiveScheduler::WaitForAnyRequest

TRAPD

Implemented in CIdle, CAsyncCallBack, CPeriodic, CHeartbeat, and CServer2.

SetActive()

IMPORT_C void CActive::SetActive ( )

protected

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:

1. the active scheduler, immediately before it calls the active object's RunL() function.

or

1. the active object within the implementation of the Cancel() function.

E32USER-CBase 46 panics may occur if an active object is set active but no request is made on its TRequestStatus, or vice-versa. This panic happens no earlier than the next time that the active scheduler assesses which objects are ready to run, and may happen much later. This panic is termed a 'stray event' because it indicates that some entity has sent an event to the active scheduler thread, but this thread is not in a state ready to handle it.

Panic condition: E32USER-CBase 42 if this active object is already active

Panic condition: E32USER-CBase 49 if this active object has not been added to the active scheduler.

(generated from Symbian Developer Library)

SetPriority()

IMPORT_C void CActive::SetPriority

(

TInt

aPriority

)

Sets the priority of the active object.

Parameters

aPriority

An integer specifying the new priority of this active object. CActive::TPriority defines a standard set of priorities.

Panic condition: E32USER-CBase 50 if this function is called while a request is outstanding.

(generated from Symbian Developer Library)

Friends And Related Symbol Documentation

CActiveScheduler

friend class CActiveScheduler

friend

Definition at line 1759 of file e32base.h.

CServer

friend class CServer

friend

Definition at line 1760 of file e32base.h.

CServer2

friend class CServer2

friend

Definition at line 1761 of file e32base.h.

Member Data Documentation

iStatus

TRequestStatus CActive::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.

Definition at line 1754 of file e32base.h.

---

The documentation for this class was generated from the following files:

• e32base.h
• e32base.h.dox