Provides a high-level interface for accessing and manipulating a Message Server entry.

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.

The following are some significant groups of functions:

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 that: any changes made to an existing context are not automatically saved: the message client application should ensure this itself by calling SaveMessageL(); no message data for the new context is retrieved from the Message Server, to retrieve entry data, call LoadMessageL() after setting the context; calling Body() immediately after setting the context returns an empty CRichText object: this is because the private cache of context body text that the base class maintains is re-initialised to an empty value. 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.

Store and restore entry data functions: 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 a Client-side MTM. The message store and restore functions are concerned with transferring data between that cache and committed storage. Note that, unlike message contexts, message client applications are not expected to manipulate directly service contexts. Instead, the corresponding User Interface MTM will provide dialogs to allow the user to alter service settings, and call Client-side MTM functions to handle their retrieval and storage. Symbian OS v5 expects the base class functions to handle storage and retrieval for both message and service contexts, and their implementations must detect what the context is, and act accordingly. Post-v5, the API is clarified by restricting the base class functions to handle message contexts only. To handle service contexts, a Client-side MTM must define its own functions for the User Interface MTM to call.

Store and restore body text functions: 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(). StoreBodyL() and RestoreBodyL() encapsulate for implementers of derived classes the retrieval and storage of this CRichText object to a CMsvStore.

Address list functions: the format and storage of message addresses is MTM-specific. AddresseeList(), AddAddresseeL(), and RemoveAddressee() 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.

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.