Class CMsvOperation

class CMsvOperation : public CActive;

Description

Defines an interface for use by objects which control asynchronous commands in the messaging system.

Such objects are returned by CMsvEntry and User Interface MTM functions that complete asynchronously. The interface allows clients to:

1. get progress information about the operation

2. cancel the operation

3. be signalled asynchronously when the operation completes; a client passes in a TRequestStatus of a suitable active object for this purpose

The client only needs to understand the CMsvOperation interface, not the concrete implementation used.

Writing derived classes:

As the base class interface for User Interface MTMs, CBaseUiMtm, defines functions that return CMsvOperation objects for control of asynchronous operations, implementers of these MTM components are required to provide suitable derived classes. For example, if CBaseUiMtm::EditL() is implemented to provide message editing, a CMsvOperation -derived class would be provided that completes when the editing operation is complete.

Concrete derived classes must provide implementations of the pure virtual DoCancel() and RunL() functions defined by CActive. DoCancel() should be provided in the normal way to cancel the operation. RunL() should, in addition to any other required functionality, always end by signalling the client that the operation is complete with a suitable completion code.

Derivation

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

• CActive - The core class of the active object abstraction

• CMsvOperation - Defines an interface for use by objects which control asynchronous commands in the messaging system

Members

Defined in CMsvOperation:
CMsvOperation(), Extension_(), FinalProgress(), Id(), Mtm(), ProgressL(), Service(), SystemProgress(), iMsvSession, iMtm, iObserverRequestStatus, iService, ~CMsvOperation()

Inherited from CActive:
Cancel(), Deque(), DoCancel(), EPriorityHigh, EPriorityIdle, EPriorityLow, EPriorityStandard, EPriorityUserInput, IsActive(), IsAdded(), Priority(), RunError(), RunL(), SetActive(), SetPriority(), TPriority, iStatus

Inherited from CBase:
Delete(), operator new()

See also

• Class summary
• Class summary

IMPORT_C CMsvOperation(CMsvSession &aMsvSession, TInt aPriority, TRequestStatus &aObserverRequestStatus);

Description

Constructor. This is called by MTM implementers from the derived class constructor.

CMsvOperation-derived objects are not created by message client applications. The constructor uses the CMsvSession object to obtain a ID for the operation. This ID can be accessed by clients through Id().

aPriority is the priority used by the active object. Typically, this is EPriorityStandard.

aObserverRequestStatus is the asynchronous status object of an active object provided by the caller. The derived class is required to signal the caller through this when the operation completes. It is stored by the constructor in the iObserverRequestStatus member.

Parameters

CMsvSession &aMsvSession Session object TInt aPriority Active object priority TRequestStatus &aObserverRequestStatus Request status of operation observer

IMPORT_C ~CMsvOperation();

Description

Destructor.

This base class function takes no action. Derived classes should implement a destructor to do the clean up tasks that they require. Minimally, they should call Cancel() to cancel any outstanding request.

virtual const TDesC8 &ProgressL()=0;

Description

Gets information on the progress of the operation.

All operations on local entries share the same progress information format, which defined by TMsvLocalOperationProgress.

For MTM-specific operations, progress information can be extracted by calling CBaseUiMtm::GetProgress() or displayed by CBaseUiMtm::DisplayProgressSummary() on the appropriate User Interface MTM.

Requirements:

Derived classes should implement this function so that the client can check on the progress of the operation. The function should share an understanding of the format of the buffer with the implementations of CBaseUiMtm::GetProgress() and CBaseUiMtm::DisplayProgressSummary() in the User Interface MTM. The arguments of CBaseUiMtm::GetProgress() show some information that should be included where appropriate.

Return value

const TDesC8 & Descriptor holding progress information. The maximum buffer size should be KMsvProgressBufferLength (defined in msvipc.h).

Leave codes

KErrNotReady The operation has not yet been started: it has been queued for execution in the Message Server

virtual IMPORT_C const TDesC8 &FinalProgress();

Description

Gets information about a completed operation.

Unlike ProgressL(), this is guaranteed to provide status information reflecting the outcome of a completed operation.

Requirements:

The default implementation of this function returns the result from ProgressL(). If the operation is active or ProgressL() leaves, a panic occurs.

A derived class should implement the function to meet the requirement to provide appropriate final status information. Typically, on active object completion, it will store progress information in a private member, and return that stored information from this function.

Return value

const TDesC8 & Descriptor holding progress information

Panic codes

MSGS 285 Operation is active MSGS 286 Could not get final progress information, as ProgressL() left.

IMPORT_C TInt SystemProgress(TMsvSystemProgress &aOutSysProg);

Description

This call leads to calling SystemProgress() in the server to populate the TMsvSystemProgress structure.

Parameters

TMsvSystemProgress &aOutSysProg The TMsvSystemProgress structure to be populated by the server

Return value

TInt the error of the Extension_ method call

virtual IMPORT_C TUid Mtm() const;

Description

Gets the UID of the MTM associated with the operation.

This UID can be used to determine the appropriate method of getting information from a progress descriptor.

The default implementation returns iMtm.

Return value

TUid The UID of the MTM associated with the operation

See also:

• ProgressL()

inline TMsvOp Id() const;

Description

Gets the operation ID.

This ID is unique within a Message Server session. The ID allows the client to keep track of different operations.

Return value

TMsvOp The ID of the operation

inline TMsvId Service() const;

Description

Gets the ID of the service that is associated with this operation.

If the operation is not associated with a service, the function returns KMsvLocalServiceIndexEntryId.

Return value

TMsvId ID of the service associated with the operation

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

Description

The extension method provides a polymorphic behaviour to call the correct SystemProgress function.

Parameters

TUint aExtensionId The Uid passed in as KUIDMsgMsvSystemProgress to obtain the System Progress. TAny *&a0 TAny *a1

Return value

TInt KErrExtensionNotSupported retuned if no Extension_ function is overriddden by the derived class.

protected: TMsvId iService;

Description

The ID of the service that is associated with this operation.

Usually, the derived class constructor will contain a suitable argument to allow the caller to set this.

See also:

• Service()

protected: TUid iMtm;

Description

The UID of the MTM associated with the operation.

The appropriate value should be set by the derived class constructor.

See also:

• Mtm()

protected: TRequestStatus & iObserverRequestStatus;

Description

Request status of the operation observer.

This is the aObserverRequestStatus passed in the constructor.

protected: CMsvSession & iMsvSession;

Description

Message Server session used by object. This is set by the constructor.