EPOC   SDK Home Glossary Indexes Previous Next Up

CBaseMtm class


Contents


CBaseMtm class — Client-side MTM base

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

MMsvEntryObserver

Abstract: interface for notification of entry events.

Defined in

mtclbase.h

Link against

mcld.lib

Description

This class is the base class for Client-side MTM components. It provides a high-level interface for accessing and manipulating a Message Server entry. For an overview of the functionality, see Client-side MTMs.

Message client applications use the class to access such functionality polymorphically. MTM implementers implement a derived class to provide such functionality for their message protocol.


Construction and destruction


CBaseMtm() — Constructor

protected: CBaseMtm(CRegisteredMtmDll& aRegisteredMtmDll,CMsvSession& aSession);

Description

Client applications do not use this function. It is relevant only to implementers of derived classes.

The base class constructor initialises member variables from the passed arguments. The value of aSession can be accessed through Session().

Derived classes can implement a constructor to perform any additional MTM-specific setup that can be safely carried out in a constructor. Such constructors must call the base class constructor function.

Derived classes also implement two-phase construction functions (NewL(), ConstructL()) to create a new instance of the object, in which any dynamic allocation should be performed. Client-side MTMs also implement a factory function by which a MTM registry can request an instance of the class: for details, see MtmFactoryFunctionL typedef.

Arguments

CRegisteredMtmDll& aRegisteredMtmDll

Registration data for the MTM DLL.

CMsvSession& aSession

The CMsvSession of the client requesting the object


~CBaseMtm() — Destructor

~CBaseMtm();

Description

CBaseMtm -derived objects must be deleted by client applications when they are no longer required. This function cleans up the base class.

Derived classes can implement a destructor to do any additional clean up tasks that they require.


Context functions

The SetCurrentEntryL() and SwitchCurrentEntryL() functions change the context— the entry on which later actions are performed. After creating a new Client-side MTM object, a message client application should set an initial context before using other functions.

Note the following behaviour:

MTM implementers should note that the virtual ContextEntrySwitched() is called from these functions to allow derived classes to also clear any caches of MTM-specific entry data.


SetCurrentEntryL() — Set context by entry

void SetCurrentEntryL(CMsvEntry* aEntry);

Description

Use this function to change the entry on which later actions are performed to the specified CMsvEntry.

Arguments

CMsvEntry* aEntry

The entry on which all following actions will be performed

Leave considerations

KErrNoMemory

Insufficient memory


SwitchCurrentEntryL() — Set context by ID

void SwitchCurrentEntryL(TMsvId aId);

Description

Use this function to change the entry on which later actions are performed to the entry with the specified TMsvId.

Arguments

TMsvId aId

The ID of the entry upon which all following actions will be performed

Leave considerations

KErrNoMemory

Insufficient memory

KErrNotFound

The requested entry does not exist


ContextEntrySwitched() — Context change notification

protected: virtual void ContextEntrySwitched()=0;

Description

Client applications do not use this function. It is relevant only to implementers of derived classes.

Requirements

This function is called by the base class functions SwitchCurrentEntryL() and SetCurrentEntryL() when the context is changed to another entry.

The implementation should clear:


HasContext() — Test if context set

TBool HasContext() const;

Description

Use this function to test if a context has been set. A Client-side MTM has no context until one is set through SwitchCurrentEntryL() or SetCurrentEntryL() .

Return value

TBool

ETrue: context has been set

EFalse: context has not been set


Store and restore entry data

The changes that a message client application makes to a message context through Client-side MTM functions, such as altering the body text obtained through Body(), are, for efficiency, cached in memory by the Client-side MTM. For this reason,


RestoreL() — Restore entry data

virtual void RestoreL()=0;

Description

Use this function to load the cache with the message data for the current context. It is typically used after the context has been set with one of the Context functions. CBaseMtm functions to manipulate the entry can only be called after this function has been called.

Requirements

An implementation must restore the store and index entry relating to the message context. The typical steps required to do this are as follows.

The message store should be opened for reading with CMsvEntry::ReadStoreL(). It should be then be read to set the following:

Leave considerations

Standard store-related errors


StoreL() — Store entry data

virtual void StoreL()=0;

Description

Use this function to commit cached changes to the storage controlled by the Message Server. It should be called in the following circumstances:

Requirements

An implementation must update the store and index entry relating to the message context. The typical steps required to do this are as follows.

The message store should be opened for editing with CMsvEntry::EditStoreL(). It should be updated as follows:

Changes can then be committed to the store with CMsvStore::CommitL().

The index entry should also be updated to reflect changes. Possible fields that may need updating include: Description (for subject changes); Details and Multiple Recipients (for recipient changes); and Size. Index entry changes are committed using CMsvEntry::ChangeL().

Leave considerations

Standard store-related errors


Store and restore body text

The base class maintains a private CRichText object cache to store the body text for the current context. This can be accessed for reading and writing by message client applications through Body(). The following functions encapsulate for implementers of derived classes the retrieval and storage of this CRichText object to a CMsvStore.


StoreBodyL() — Store body text

protected: void StoreBodyL(CMsvStore& aStore);

Description

Client applications do not use this function. It is relevant only to implementers of derived classes.

Implementations should call this function to store and commit the current cached CRichText body text to the appropriate stream in the message store specified in aStore. This overwrites any existing data in that stream. The implementation must have write access to aStore.

A typical use of this function is from StoreL().

Arguments

CMsvStore& aStore

Message store in which to store the body text

Leave considerations

KErrAccessDenied

The store was opened for read only

Other

Standard stream-related leave codes


RestoreBodyL() — Restore body text

protected: void RestoreBodyL(CMsvStore& aStore);

Description

Client applications do not use this function. It is relevant only to implementers of derived classes.

Implementations should call this function to set the current cached CRichText from the appropriate stream in the message store specified in aStore.

A typical use of this function is from RestoreL().

Arguments

CMsvStore& aStore

Message store from which to read the body text

Leave considerations

Standard stream-related leave codes


Response message creation


ReplyL() — Create reply message

virtual CMsvOperation* ReplyL(TMsvId aDestination, TMsvPartList aPartlist, TRequestStatus& aCompletionStatus)=0;

Description

Use this function to create a reply message to the current message context. Some MTMs may support inclusion of elements, specified by aPartlist, from the original message in the reply. The parent for the new entry is specified in aDestination.

The returned CMsvOperation object completes when creating the reply is complete. On completion, the context is set to the reply message.

Requirements

A typical implementation for this function would include the following steps:

If message replies are not supported, implementations should leave with KErrNotSupported.

The implementation of this function may be similar to that of ForwardL(), allowing opportunities for code sharing.

Arguments

TMsvId aDestination

The entry to which to assign the reply

TMsvPartList aPartlist

Defines the parts that are to be copied from the original message into the reply

TRequestStatus& aCompletionStatus

The request status to be completed when the operation has finished

Return value

CMsvOperation*

If successful, this is an asynchronously completing reply operation.

If failed, this is a completed operation, with status set to the relevant error code.

Leave considerations

KErrNotSupported

The Client-side MTM does not support reply operations

Other leave codes

Dependent on implementation


ForwardL() — Create forwarded message

virtual CMsvOperation* ForwardL(TMsvId aDestination, TMsvPartList aPartList, TRequestStatus& aCompletionStatus)=0;

Description

Use this function to create a forwarded message from the current message context. Some MTMs may support inclusion of elements, specified by aPartlist, from the original message in the forwarded message. The parent for the new entry is specified in aDestination. The returned CMsvOperation object completes when editing the forwarded message is complete. On completion, the context is set to the forwarded message.

Requirements

A typical implementation for this function would include the following steps:

If forwarded messages are not supported, implementations should leave with KErrNotSupported.

The implementation of this function may be similar to that of ReplyL(), allowing opportunities for code sharing.

Arguments

TMsvId aDestination

The entry to which to assign the forwarded message

TMsvPartList aPartList

Defines the parts that are to be copied from the original message into the forwarded message

TRequestStatus& aCompletionStatus

The request status to be completed when the operation has finished

Return value

CMsvOperation*

If successful, this is an asynchronously completing forward message operation.

If failed, this is a completed operation, with status set to the relevant error code.

Leave considerations

KErrNotSupported

The Client-side MTM does not support creation of forwarded messages

Other leave codes

Dependent on implementation


Validation and search


ValidateMessage() — Message validation

virtual TMsvPartList ValidateMessage(TMsvPartList aPartList)=0;

Description

Use this function to validate the current context. The precise validation performed is specific to the MTM, but, typically, checks that the specified message parts are well-formed.

Requirements

Implementation of this function is highly protocol-specific. The minimum implementation is to check that the current context is a message.

Arguments

TMsvPartList aPartList

Indicates the message parts for which validation is requested

Return value

TMsvPartList

If valid, KErrNone

If invalid, identifies the invalid part(s). The error value is the bitmask of the TMsvPartList IDs for each invalid part


Find() — Find text in entry

virtual TMsvPartList Find(const TDesC& aTextToFind, TMsvPartList aPartList)=0;

Description

Use this function to search the specified message part(s) of the current context for aTextToFind. If the specified part list indicates a part that is not supported, or is not present in the current message, the function behaves as if the specified part exists but does not contain the required text.

Requirements

The parts of the entry for which searching is allowed is implementation specific. If no searching is supported, always return 0.

Arguments

const TDesC& aTextToFind

The plain-text version of the text to be found.

TMsvPartList aPartList

Indicates the message parts which should be searched.

Return value

TMsvPartList

If the text was not found, or searching is unsupported, 0.

If the text was found, a bitmask of the TMsvPartList IDs for each part in which the text was present.

 


Address list

The format and storage of message addresses is MTM-specific. The following functions are designed to allow clients with no MTM-specific knowledge to access address information in a generic way. The base class has a protected data member iAddresseeList, an array of descriptors, which these functions manipulate.

Implementations should save the address information to the appropriate place in the message store when the message is stored: see Store and restore entry data.


AddresseeList() — Retrieve list of recipients

const CDesCArray& AddresseeList() const;

Description

Use this function to get the list of intended recipients for the current context, which must be a message.

In the case of protocols that allow different classes of recipient (such as To, Cc and Bcc), the list returned is whatever the protocol defines as the default recipient list.

Requirements

The default implementation simply returns the value of the protected data member iAddresseeList. As a consequence, Client-side MTM implementations should update this member whenever the address list is modified.

Return value

CDesCArray&

Array of recipients


AddAddresseeL() — Add addressee

virtual void AddAddresseeL(const TDesC& aRealAddress)=0;

virtual void AddAddresseeL(const TDesC& aRealAddress, const TDesC& aAlias)=0;

Description

Use this function to add an address for the current context, which must be a message. Addresses are not validated by checking their format by this function. Usually that is performed by calling Validate().

The second overload of the function allows an alias to be also supplied, which may be useful for some protocols. For example, for fax, if the address is the fax number, the alias could supply the recipient’s name.

Requirements

Implementations should append the address to the object’s address cache in the protected iAddresseeList data member. Some implementations may also wish to store addresses in an internal data structure appropriate for the protocol, for example, a class holding message header information.

Arguments

const TDesC& aRealAddress

String representing an address to be added to the list for the current message

const TDesC& aAlias

Alias information

Leave considerations

KErrNotSupported

The message already has the maximum number of addressees

Other leave codes

Dependent on implementation


RemoveAddressee() — Remove addressee

virtual void RemoveAddressee(TInt aIndex)=0;

Description

Use this function to remove an address from the current address list. The address is specified by a zero-based index into the address list. If the index is not known, applications can use AddresseeList() to retrieve the entire list to find the item.

Requirements

Implementations should call iAddresseeList->Delete(aIndex) to remove the address from in the address list protected data member.

Arguments

TInt aIndex

Index of address to be removed


Data accessors and mutators


Body() — Get message body text

CRichText& Body();

const CRichText& Body() const;

Description

Use these functions to get the body text of the context, which must be a message. For non-message contexts, an empty CRichText is returned.

Implementers should see Store and restore body text for an explanation of how the base class implements these functions.

Return value

CRichText&

Body text of the context


SetSubjectL() — Set message subject

virtual void SetSubjectL(const TDesC& aSubject);

Description

Use this function to set the subject text of the context, which must be a message. Some Client-side MTMs may not support subject text, in which case the function leaves with KErrNotSupported.

Requirements

If the message protocol supports subject text, implementations should maintain a private buffer to store this information, settable through this function.

Implementations should save the subject text to the appropriate place in the message store when the message is stored: see Store and restore entry data.

The default implementation leaves with KErrNotSupported.

Arguments

const TDesC& aSubject

Message subject text

Leave considerations

KErrNotSupported

The Client-side MTMs does not support subject text


SubjectL() — Get message subject

virtual const TPtrC SubjectL() const;

Description

Use this function to get the subject text of the context, which must be a message. Some Client-side MTMs may not support subject text, in which case the function leaves with KErrNotSupported.

Requirements

If the message protocol supports subject text, implementations should maintain a private buffer to store this information, gettable through this function.

The default implementation leaves with KErrNotSupported.

Return value

TPtrC

Message subject text

Leave considerations

KErrNotSupported

The Client-side MTMs does not support subject text


Session() — Get session object

CMsvSession& Session();

Description

Use this function to get a reference to the session object passed by the creator of the Client-side MTM.

Return value

CMsvSession&

Session object used by the Client-side MTM


Type() — Get Type UID

TUid Type() const;

Description

Use this function to get the Type UID of the message type associated with the Client-side MTM.

Return value

TUid

UID of the message type associated with the MTM


Entry() — Get CMsvEntry context

CMsvEntry& Entry() const;

Description

Use this function to obtain a CMsvEntry for the current context. The message client application can then use this to manipulate the entry.

Implementers should note that this function returns the value of the protected data member iMsvEntry.

Return value

CMsvEntry&

CMsvEntry for the current context


MTM capabilities


QueryCapability() — Query for capability

virtual TInt QueryCapability(TUid aCapability, TInt& aResponse);

Description

Use this function to query if the MTM supports a particular capability, specified by a UID. For a list of standard capability UIDs, see Capability constants. For MTM-specific UIDs, see the documentation for the relevant MTM.

Requirements

Implementations should check aCapability for the standard capability values, plus any MTM-specific capabilities, and if recognised, return a suitable response in aResponse. If aCapability is unknown, return KErrNotSupported.

The default implementation returns KErrNotSupported.

Arguments

TUid aCapability

UID of capability to be queried

TInt& aResponse

Response value. The format of the response varies according to the capability. See Capability constants for the standard responses.

Return value

TInt

KErrNone: aCapability is a recognised value and a response is returned

KErrNotSupported: aCapability is not a recognised value


MTM-specific functionality

MTM components can offer protocol-specific functionality not provided by base class interface functions. MTM components define IDs that correspond to each protocol-specific operation offered, and implement the InvokeSyncFunctionL() and InvokeAsyncFunctionL() functions to allow clients to access these operations by passing in the appropriate ID. Two functions are provided to allow the MTM component to offer both synchronous and asynchronous functionality.

Message client applications can dynamically add user-interface features for these operations using CBaseMtmUiData::MtmSpecificFunctions().

MTM developers should document the IDs if they wish to make the operations available to clients.


InvokeAsyncFunctionL() — Call MTM-specific operation asynchronously

virtual CMsvOperation* InvokeAsyncFunctionL(TInt aFunctionId, const CMsvEntrySelection& aSelection, TDes8& aParameter, TRequestStatus& aCompletionStatus)=0;

Description

This function should be used to invoke asynchronous protocol-specific operations. For synchronous operations, a similar function, InvokeSyncFunctionL(), is available.

aSelection and aParameter allow data to be passed to the operation. The TRequestStatus and CMsvOperation objects are used as normal to control and monitor the operation.

Requirements

For functionality that requires message transport access, such as making a connection, the implementation should pass the request onto the corresponding Server-side MTM. This is done through calling CMsvSession::TransferCommandL(). Implementations may also provide protocol-specific functions themselves if this is useful.

InvokeAsyncFunctionL() should return a CMsvOperation-derived object to provide asynchronous control and monitoring of the operation. If CMsvSession::TransferCommandL() is called, this should be the CMsvOperation object returned by that function.

Arguments

TInt aFunctionId

ID of the requested operation

const CMsvEntrySelection& aSelection

Selection of message entries. This is used if the operation requires message entries to work on.

TDes8& aParameter

Buffer containing input and output parameters. The format of this is specific to the operation.

TRequestStatus& aCompletionStatus

The request status to be completed when the operation has finished

Return value

CMsvOperation*

If successful, this is an asynchronously completing operation.

If failed, this is a completed operation, with status set to the relevant error code.

Leave considerations

KErrNotSupported

aFunctionId is not a recognised operation ID

Other leave codes

Dependent on implementation


InvokeSyncFunctionL() — Call MTM-specific operation synchronously

virtual void InvokeSyncFunctionL(TInt aFunctionId, const CMsvEntrySelection& aSelection, TDes8& aParameter)=0;

Description

This function should be used to invoke synchronous protocol-specific operations. For asynchronous operations, a similar function, InvokeAsyncFunctionL(), is available.

aSelection and aParameter allow data to be passed to the operation.

Requirements

For functionality that requires message transport access, such as making a connection, the implementation should pass the request onto the corresponding Server-side MTM. This is done through calling CMsvSession::TransferCommandL(). Implementations may also provide protocol-specific functions themselves if this is useful.

Arguments

TInt aFunctionId

ID of the requested operation

const CMsvEntrySelection& aSelection

Selection of message entries. This is used if the operation requires message entries to work on.

TDes8& aParameter

Buffer containing input and output parameters. The format of this is specific to the operation.

Leave considerations

KErrNotSupported

aFunctionId is not a recognised operation ID

Other leave codes

Dependent on implementation


Protected data members

The following protected data members can be accessed by implementers of derived classes.

CMsvEntry* iMsvEntry

The current context. See Context functions for the main functions that use this member.

CDesCArrayFlat* iAddresseeList

The address list for the current context. See Address list for the main functions that use this member.

CParaFormatLayer* iParaFormatLayer

Paragraph formatting applied to the CRichText object for the body text, as returned by Body(). This is set to an empty CParaFormatLayer instance whenever the context is set.

Implementations can modify this if they wish to apply particular formatting to body text.

CCharFormatLayer* iCharFormatLayer

Character formatting applied to the CRichText object for the body text, as returned by Body().

Implementations can modify this if they wish to apply particular formatting to body text.

EPOC       SDK Home Glossary Indexes Previous Next Up