EPOC   SDK Home Glossary Indexes Previous Next Up

CMsvOperation class


Contents


CMsvOperation class — Operation control

Section Contents


Overview

Compatibility

Applications that use this class will not work correctly on a version of EPOC earlier than ER5.

Derivation

CBase

Abstract: CBase behaviour

CActive

Abstract: active object abstraction

Defined in

msvapi.h

Link against

mcld.lib

Description

This is an abstract base class, derived from CActive, which 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:

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.


Constructor & destructor


CMsvOperation() — Constructor

CMsvOperation(CMsvSession& aSession, TInt aPriority, TRequestStatus& aObserverRequestStatus);

Description

CMsvOperation-derived objects are not created by message client applications. MTM implementers should call this base class constructor from the derived class constructor.

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.

Arguments

CMsvSession& aSession

Session object

TInt aPriority

Active object priority

TRequestStatus& aObserverRequestStatus

Request status of operation observer


~CMsvOperation() — Destructor

~CMsvOperation();

Description

CMsvOperation-derived objects must be deleted by client applications when they are no longer required. 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.


Progress reporting


ProgressL() — Progress information

const TDesC8& ProgressL()=0;

Description

Use this function to get information on the progress of the operation. The information is returned in a package buffer.

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.

Success return

const TDesC8&

Descriptor holding progress information

Leave considerations

KErrNotReady

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


Accessors


Id() — Read operation ID

TMsvOp Id() const;

Description

Use this function to get 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


Mtm() — Get UID of MTM

TUid Mtm() const;

Description

Use this function to get 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. See ProgressL().

If the operation is not associated with a service, it returns KUidMsvLocalServiceMtm

Return value

TUid

The UID of the MTM associated with the operation


Service() — Get service ID

TMsvId Service() const;

Description

Returns 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 member data

TMsvId iService

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

TUid iMtm

The UID of the MTM associated with the operation. The appropriate value should be set by the derived class constructor.

See also Mtm().

TRequestStatus& iObserverRequestStatus

Request status of the operation observer. This is the aObserverRequestStatus passed in the constructor.

CMsvSession& iMsvSession

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

EPOC       SDK Home Glossary Indexes Previous Next Up