Class CActive

class CActive : public CBase;

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.

Derivation

• CBase - Base class for all classes to be instantiated on the heap.

• CActive - The core class of the active object abstraction.

Members

Defined in CActive:

• CActive(TInt)Constructs the active object with the specified priority.
• Cancel()Cancels the wait for completion of an outstanding request.
• Deque()Removes the active object from the active scheduler's list of active objects.
• DoCancel()Implements cancellation of an outstanding request.
• EPriorityHighA priority higher than EPriorityUserInput.
• EPriorityIdleA low priority, useful for active objects representing background processing.
• EPriorityLowA priority higher than EPriorityIdle but lower than EPriorityStandard.
• EPriorityStandardMost active objects will have this priority.
• EPriorityUserInputA priority higher than EPriorityStandard; useful for active objects handling use...
• Extension_(TUint,TAny *&,TAny *)Extension function
• IsActive()constDetermines whether the active object has a request outstanding.
• IsAdded()constDetermines whether the active object has been added to the active scheduler's li...
• Priority()constGets the priority of the active object.
• RunError(TInt)Handles a leave occurring in the request completion event handler CActive::RunL(...
• RunL()Handles an active object's request completion event.
• SetActive()Indicates that the active object has issued a request and that it is now outstan...
• SetPriority(TInt)Sets the priority of the active object.
• TPriorityDefines standard priorities for active objects.
• iStatusThe request status associated with an asynchronous request.
• ~CActive()Frees resources prior to destruction.

Inherited from CBase:

• Delete(CBase *)Deletes the specified object.
• operator new(TUint)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TAny *)Initialises the object to binary zeroes.
• operator new(TUint,TLeave)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TLeave,TUint)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TUint)Allocates the object from the heap and then initialises its contents to binary z...

Related Topics

 » Symbian OS v9.4 » Examples » Application Framework example code » AnimExample: An UI application with a toolbar

• Animation example

 » Symbian OS v9.4 » Examples » Messaging example code » Imap4Example: An Email manager using IMAP4 and SMTP

• Imap4Example: An Email manager using IMAP4 and SMTP » Class summary

 » Symbian OS v9.4 » Examples » Messaging example code » Pop3Example: An Email manager using POP3 and SMTP

• Pop3Example: An Email manager using POP3 and SMTP » Class summary

IMPORT_C ~CActive();

Description

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 CActive::Cancel() in its destructor.

Panic codes

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

See also:

• CActive::Cancel()Cancels the wait for completion of an outstanding request.

protected: IMPORT_C CActive(TInt aPriority);

Description

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

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

IMPORT_C void Cancel();

Description

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

See also:

• CActive::DoCancel()Implements cancellation of an outstanding request.
• CActive::IsActive()constDetermines whether the active object has a request outstanding.
• CActive::~CActive()Frees resources prior to destruction.
• User::WaitForRequest(TRequestStatus &)Waits for a specific asynchronous request to complete.

IMPORT_C void Deque();

Description

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.

See also:

• CActive::Cancel()Cancels the wait for completion of an outstanding request.

IMPORT_C void SetPriority(TInt aPriority);

Description

Sets the priority of the active object.

Parameters

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

Panic codes

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

inline TBool IsActive() const;

Description

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.

Return value

TBool True, if a request is outstanding; false, otherwise.

inline TBool IsAdded() const;

Description

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 CActive::Deque() to remove the active object from the scheduler.

Return value

TBool True, if the active object has been added to an active scheduler; false, otherwise.

See also:

• CActive::Deque()Removes the active object from the active scheduler's list of active objects.

inline TInt Priority() const;

Description

Gets the priority of the active object.

Return value

TInt The active object's priority value.

protected: IMPORT_C void SetActive();

Description

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 CActive::RunL() function.

or

2. the active object within the implementation of the CActive::Cancel() function.

See also:

• CActive::IsActive()constDetermines whether the active object has a request outstanding.
• CActive::RunL()Handles an active object's request completion event.
• CActive::Cancel()Cancels the wait for completion of an outstanding request.

protected: virtual void DoCancel()=0;

Description

Implements cancellation of an outstanding request.

This function is called as part of the active object's CActive::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.

CActive::DoCancel() must not wait for event completion; this is handled by CActive::Cancel().

See also:

• CActive::Cancel()Cancels the wait for completion of an outstanding request.

protected: virtual void RunL()=0;

Description

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 CActive::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)

CActive::RunL() runs under a trap harness in the active scheduler. If it leaves, then the active scheduler calls CActive::RunError(TInt) 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 CActive::RunL() or CActive::RunError(TInt) functions.

See also:

• CActiveScheduler::Start()Starts a new wait loop under the control of the current active scheduler.
• CActiveScheduler::Error(TInt)constHandles the result of a leave occurring in an active object’s RunL() function.
• CActiveScheduler::WaitForAnyRequest()Wait for an asynchronous request to complete.

protected: IMPORT_C virtual TInt RunError(TInt aError);

Description

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

The active scheduler calls this function if this active object's CActive::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(TInt)const 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(TInt)const function must be supplied.

Parameters

TInt aError The leave code

Return value

TInt The default implementation returns aError. A derived class implementation should return KErrNone, if it handles the leave; otherwise it should return any suitable value to cause the handling of the error to be propagated back to the active scheduler.

See also:

• CActiveScheduler::Error(TInt)constHandles the result of a leave occurring in an active object’s RunL() function.

protected: IMPORT_C virtual TInt Extension_(TUint aExtensionId, TAny *&a0, TAny *a1);

Description

Extension function

Parameters

TUint aExtensionId TAny *&a0 TAny *a1

Return value

TInt

TPriority

Description

Defines standard priorities for active objects.

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.

TRequestStatus iStatus;

Description

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.