CBaseMtm Class Reference

#include <mw/mtclbase.h>

class CBaseMtm : public CBase, public MMsvEntryObserver, public CBase, public MMsvEntryObserver
Protected Attributes
CMsvRecipientList *iAddresseeList
CCharFormatLayer *iCharFormatLayer
CMsvEntry *iMsvEntry
CParaFormatLayer *iParaFormatLayer
Public Member Functions
~CBaseMtm()
pure virtual voidAddAddresseeL(const TDesC &)
pure virtual voidAddAddresseeL(const TDesC &, const TDesC &)
virtual IMPORT_C voidAddAddresseeL(TMsvRecipientType, const TDesC &)
virtual IMPORT_C voidAddAddresseeL(TMsvRecipientType, const TDesC &, const TDesC &)
virtual IMPORT_C voidAddAttachmentL(const TDesC &, const TDesC8 &, TUint, TRequestStatus &)
virtual IMPORT_C voidAddAttachmentL(RFile &, const TDesC8 &, TUint, TRequestStatus &)
virtual IMPORT_C voidAddEntryAsAttachmentL(TMsvId, TRequestStatus &)
virtual IMPORT_C voidAddLinkedAttachmentL(const TDesC &, const TDesC8 &, TUint, TRequestStatus &)
IMPORT_C const CMsvRecipientList &AddresseeList()
virtual IMPORT_C voidBioTypeChangedL(TUid)
IMPORT_C CRichText &Body()
IMPORT_C const CRichText &Body()
virtual IMPORT_C voidCancelAttachmentOperation()
virtual IMPORT_C voidChangeDefaultServiceL(const TMsvId &)
virtual IMPORT_C voidCreateAttachmentL(const TDesC &, RFile &, const TDesC8 &, TUint, TRequestStatus &)
virtual IMPORT_C voidCreateMessageL(TMsvId)
virtual IMPORT_C TMsvIdDefaultServiceL()
IMPORT_C CMsvEntry &Entry()
virtual voidFiller1()
virtual voidFiller2()
pure virtual TMsvPartList Find(const TDesC &, TMsvPartList)
pure virtual CMsvOperation *ForwardL(TMsvId, TMsvPartList, TRequestStatus &)
IMPORT_C TAny *GetExtensionData()
IMPORT_C TBoolHasContext()
pure virtual CMsvOperation *InvokeAsyncFunctionL(TInt, const CMsvEntrySelection &, TDes8 &, TRequestStatus &)
pure virtual voidInvokeSyncFunctionL(TInt, const CMsvEntrySelection &, TDes8 &)
pure virtual voidLoadMessageL()
virtual IMPORT_C TIntQueryCapability(TUid, TInt &)
pure virtual voidRemoveAddressee(TInt)
virtual IMPORT_C voidRemoveDefaultServiceL()
pure virtual CMsvOperation *ReplyL(TMsvId, TMsvPartList, TRequestStatus &)
pure virtual voidSaveMessageL()
IMPORT_C CMsvSession &Session()
IMPORT_C voidSetCurrentEntryL(CMsvEntry *)
IMPORT_C voidSetExtensionData(TAny *)
IMPORT_C TIntSetMessageCharacterSet(TUint)
virtual IMPORT_C voidSetSubjectL(const TDesC &)
virtual IMPORT_C const TPtrCSubjectL()
IMPORT_C voidSwitchCurrentEntryL(TMsvId)
IMPORT_C TUidType()
pure virtual TMsvPartList ValidateMessage(TMsvPartList)
Protected Member Functions
CBaseMtm(CRegisteredMtmDll &, CMsvSession &)
pure virtual voidContextEntrySwitched()
virtual IMPORT_C TIntExtension_(TUint, TAny *&, TAny *)
virtual IMPORT_C TAny *GetInterface(TUid)
virtual IMPORT_C voidHandleEntryEventL(TMsvEntryEvent, TAny *, TAny *, TAny *)
IMPORT_C voidRestoreBodyL(CMsvStore &)
IMPORT_C voidStoreBodyL(CMsvStore &)
Inherited Enumerations
MMsvEntryObserver:TMsvEntryEvent
Inherited Functions
CBase::CBase()
CBase::Delete(CBase *)
CBase::operator new(TUint)
CBase::operator new(TUint,TAny *)
CBase::operator new(TUint,TLeave)
CBase::operator new(TUint,TLeave,TUint)
CBase::operator new(TUint,TUint)
CBase::~CBase()

Detailed Description

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.

Member Attribute Documentation

iAddresseeList

CMsvRecipientList *iAddresseeList[protected]

The address list for the current context.

iCharFormatLayer

CCharFormatLayer *iCharFormatLayer[protected]

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.

iMsvEntry

CMsvEntry *iMsvEntry[protected]

The current context.

iParaFormatLayer

CParaFormatLayer *iParaFormatLayer[protected]

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.

Constructor & Destructor Documentation

CBaseMtm ( CRegisteredMtmDll &, CMsvSession & )

IMPORT_CCBaseMtm(CRegisteredMtmDll &aRegisteredMtmDll,
CMsvSession &aSession
)[protected]

Creates a CBaseMtm with member variables initialised from the passed arguments.

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

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.

Parameters
aRegisteredMtmDllRegistration data for the MTM DLL.
aSessionThe CMsvSession of the client requesting the object

~CBaseMtm ( )

IMPORT_C~CBaseMtm()

Cleans up the base class.

CBaseMtm -derived objects must be deleted by client applications when they are no longer required.

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

Member Function Documentation

AddAddresseeL ( const TDesC & )

voidAddAddresseeL(const TDesC &aRealAddress)[pure virtual]

Adds an addressee for the current context.

Addresses are not validated by checking their format by this function. Usually that is performed by calling ValidateMessage().

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.

Parameters
aRealAddressString representing an address to be added to the list for the current message
Leave Codes
KErrNotSupportedThe message already has the maximum number of addressees
Otherleave codes Dependent on implementation

AddAddresseeL ( const TDesC &, const TDesC & )

voidAddAddresseeL(const TDesC &aRealAddress,
const TDesC &aAlias
)[pure virtual]

Adds an addressee for the current context, and enables the client to specify an alias, 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.

Addresses are not validated by checking their format by this function. Usually that is performed by calling ValidateMessage().

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.

Parameters
aRealAddressString representing an address to be added to the list for the current message
aAliasAlias information
Leave Codes
KErrNotSupportedThe message already has the maximum number of addressees
Otherleave codes Dependent on implementation

AddAddresseeL ( TMsvRecipientType, const TDesC & )

IMPORT_C voidAddAddresseeL(TMsvRecipientTypeaType,
const TDesC &aRealAddress
)[virtual]

Adds addressee to list.

The default implementation treats To: and Cc: type addressees as if the addressee had no type.

The default implementation does not support Bcc type addressees.

Parameters
aTypeThe addressee type.
aRealAddressThe addressee address.
Leave Codes
KErrNotSupprtedThe addressee type was Bcc which is not supported in the default implementation.

AddAddresseeL ( TMsvRecipientType, const TDesC &, const TDesC & )

IMPORT_C voidAddAddresseeL(TMsvRecipientTypeaType,
const TDesC &aRealAddress,
const TDesC &aAlias
)[virtual]

Adds addressee to list.

The default implementation treats To: and Cc: type addressees as if the addressee had no type.

The default implementation does not support Bcc type addressees.

Parameters
aTypeThe addressee type.
aRealAddressThe addressee address.
aAliasThe alias for the addressee.
Leave Codes
KErrNotSupprtedThe addressee type was Bcc which is not supported in the default implementation.

AddAttachmentL ( const TDesC &, const TDesC8 &, TUint, TRequestStatus & )

IMPORT_C voidAddAttachmentL(const TDesC &aFilePath,
const TDesC8 &aMimeType,
TUintaCharset,
TRequestStatus &aStatus
)[virtual]

Adds a file attachment to the current message entry.

The attachment is referenced by its file path and is copied into the message store. Only one asynchronous operation can be run at any one time.

Parameters
aFilePathThe full path specification of the attachment file.
aMimeTypeThe mime type of the attachment file.
aCharsetThe mime charset. The value is a standard IANA value. The value 0 indicates that no charset is provided.
aStatusThe request status to complete when request has completed.
Leave Codes
System-wideerror codes.

AddAttachmentL ( RFile &, const TDesC8 &, TUint, TRequestStatus & )

IMPORT_C voidAddAttachmentL(RFile &aFile,
const TDesC8 &aMimeType,
TUintaCharset,
TRequestStatus &aStatus
)[virtual]

Adds a file attachment to the current message entry.

The attachment is referenced by an open file handle and is copied into the message store. Only one asynchronous operation can be run at any one time.

Parameters
aFileAn open file handle for the file attachment.
aMimeTypeThe mime type of the attachment file.
aCharsetThe mime charset. The value is a standard IANA value. The value 0 indicates that no charset is provided.
aStatusThe request status to complete when request has completed.
Leave Codes
System-wideerror codes.

AddEntryAsAttachmentL ( TMsvId, TRequestStatus & )

IMPORT_C voidAddEntryAsAttachmentL(TMsvIdaAttachmentId,
TRequestStatus &aStatus
)[virtual]

Adds a message entry as an attachment to the current message entry.

This method simply registers an existing message entry as an attachment to the current entry. Only one asynchronous operation can be run at any one time.

Parameters
aAttachmentIdThe message Id of the message entry to add as an attachment.
aStatusThe request status to complete when request has completed.
Leave Codes
System-wideerror codes.

AddLinkedAttachmentL ( const TDesC &, const TDesC8 &, TUint, TRequestStatus & )

IMPORT_C voidAddLinkedAttachmentL(const TDesC &aFilePath,
const TDesC8 &aMimeType,
TUintaCharset,
TRequestStatus &aStatus
)[virtual]

Adds a file attachment to the current message entry as a linked file.

The attachment is referenced by its file path and is not copied into the message store. The attachment file is always used from its original location on disk indicated by the aFilePath parameter. Only one asynchronous operation can be run at any one time.

Parameters
aFilePathThe full path specification of the attachment file.
aMimeTypeThe mime type of the attachment file.
aCharsetThe mime charset. The value is a standard IANA value. The value 0 indicates that no charset is provided.
aStatusThe request status to complete when request has completed.
Leave Codes
System-wideerror codes.

AddresseeList ( )

IMPORT_C const CMsvRecipientList &AddresseeList()const

Gets 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
Array of recipients

BioTypeChangedL ( TUid )

IMPORT_C voidBioTypeChangedL(TUidaBioTypeUid)[virtual]

Informs client-side MTM that the context's BIO field is being changed as a result of a call to CSendAs::SetBioTypeL().

CSendAs::SetBioTypeL() calls this function before setting the BIO field in the context's index entry. This allows a client-side MTM to perform MTM specific actions when the BIO type changes.

CSendAs will not change the BIO type if this function leaves.

The default implementation is to do nothing.

See also: CSendAs::SetBioTypeL()

Parameters
aBioTypeUidNew value for the BIO field

Body ( )

IMPORT_C CRichText &Body()

Gets the body text of the context, that must be a message. For non-message contexts, an empty CRichText is returned.

See also: StoreBodyL() RestoreBodyL()

Return Value
Body text of the context

Body ( )

IMPORT_C const CRichText &Body()const

Gets the read-only body text of the context, that must be a message. For non-message contexts, an empty CRichText is returned.

See also: StoreBodyL() RestoreBodyL()

Return Value
Read-only body text of the context

CancelAttachmentOperation ( )

IMPORT_C voidCancelAttachmentOperation()[virtual]

Cancels the current attachment operation.

ChangeDefaultServiceL ( const TMsvId & )

IMPORT_C voidChangeDefaultServiceL(const TMsvId &aService)[virtual]

Sets the default MTM service. The default implementation of this function assumes that the MTM only supports one service and therefore this does nothing.

Parameters
aServiceThe default service

ContextEntrySwitched ( )

voidContextEntrySwitched()[protected, pure virtual]

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

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

Requirements:

An implementation should clear:

1. address data stored in iAddresseeList

2. any caches of MTM-specific entry data relating to a previous context. For example, if the implementation has a private buffer storing a message subject, for access through Subject(), this buffer should be cleared.

CreateAttachmentL ( const TDesC &, RFile &, const TDesC8 &, TUint, TRequestStatus & )

IMPORT_C voidCreateAttachmentL(const TDesC &aFileName,
RFile &aAttachmentFile,
const TDesC8 &aMimeType,
TUintaCharset,
TRequestStatus &aStatus
)[virtual]

Creates a new empty file attachment to the current message entry.

An empty file attachment is created with the suggested given name and if completed successfully, the aAttachmentFile will be open on the new file. Only one asynchronous operation can be run at any one time.

Parameters
aFileNameThe suggested file name for the new attachment file.
aAttachmentFileIf successful, this will be set to the open new file.
aMimeTypeThe mime type of the attachment file.
aCharsetThe mime charset. The value is a standard IANA value. The value 0 indicates that no charset is provided.
aStatusThe request status to complete when request has completed.
Leave Codes
System-wideerror codes.

CreateMessageL ( TMsvId )

IMPORT_C voidCreateMessageL(TMsvIdaServiceId)[virtual]

Creates a new message entry as a child of the current context.

The default implementation creates an empty entry with its visible flag set to false and its in-preparation flag set to true.

Parameters
aServiceIdID of the service to own the entry.

DefaultServiceL ( )

IMPORT_C TMsvIdDefaultServiceL()const [virtual]

Gets the default MTM service.

The default implementation is to assume the MTM only supports one service so finds the first service associated with this MTM and returns that.

KErrNotFound If no service has been created.
Return Value
The default service
Leave Codes

Entry ( )

IMPORT_C CMsvEntry &Entry()const

Gets 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 for the current context

Extension_ ( TUint, TAny *&, TAny * )

IMPORT_C TIntExtension_(TUintaExtensionId,
TAny *&a0,
TAny *a1
)[protected, virtual]

Reimplemented from CBase::Extension_(TUint,TAny *&,TAny *)

The default Extension service. The default implementation of this function assumes that the new service for setting the charset encoding value for a SMS message is not supported. TAny* is equivalent to void*.

Parameters
aExtensionIdUid of the extension interface
a0The collective parameters of TAny*
a1The collective parameters of TAny*,Charset encoding value is actually extracted from a1.
Return Value
KErrExtensionNotSupported If the message is other than SMS. Other Standard system-wide error codes.

Filler1 ( )

voidFiller1()[inline, virtual]

Filler2 ( )

voidFiller2()[inline, virtual]

Find ( const TDesC &, TMsvPartList )

TMsvPartList Find(const TDesC &aTextToFind,
TMsvPartListaPartList
)[pure virtual]

Searches the specified message part(s) for the plain-text version of the text to be found.

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.

Parameters
aTextToFindThe plain-text version of the text to be found.
aPartListIndicates the message parts which should be searched.
Return Value
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.

ForwardL ( TMsvId, TMsvPartList, TRequestStatus & )

CMsvOperation *ForwardL(TMsvIdaDestination,
TMsvPartListaPartList,
TRequestStatus &aCompletionStatus
)[pure virtual]

Creates 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:

1. create a new message in the specified destination by calling CMsvEntry::CreateL()

2. set the entry index values as appropriate

3. set message content as required. The normal minimum is to include the text of the original message. An implementation may also follow the options specified in aPartlist to include other properties of the original message.

4. set the context to the reply

5. return a CMsvOperation-derived object to provide asynchronous control and monitoring of the operation

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.

Parameters
aDestinationThe entry to which to assign the forwarded message
aPartListDefines the parts that are to be copied from the original message into the forwarded message
aCompletionStatusThe request status to be completed when the operation has finished
Return Value
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 Codes
KErrNotSupportedThe Client-side MTM does not support creation of forwarded messages
Otherleave codes Dependent on implementation

GetExtensionData ( )

IMPORT_C TAny *GetExtensionData()

GetInterface ( TUid )

IMPORT_C TAny *GetInterface(TUidaUid)[protected, virtual]

Returns a pointer to the interface with the specified Uid.

This method is the first part of an extension pattern to allow for more functionality to be supported without adding virtual methods to this base class.

The default implementation returns a NULL pointer.

Parameters
aUidUid of the extension interface
Return Value
Pointer to the extension interface

HandleEntryEventL ( TMsvEntryEvent, TAny *, TAny *, TAny * )

IMPORT_C voidHandleEntryEventL(TMsvEntryEventaEvent,
TAny *aArg1,
TAny *aArg2,
TAny *aArg3
)[protected, virtual]

Indicates that an event has occurred.

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

The Client-side MTM object is automatically set as an observer, through CMsvEntry::AddObserverL(), for the context whenever the context changes (by SetCurrentEntryL() or SwitchCurrentEntryL()).

The default implementation is defined to do nothing.

Requirements:

Implementations can override this function to handle events concerning the current context.

Parameters
aEventIndicates the event type
aArg1Event specific argument value
aArg2Event specific argument value
aArg3Event specific argument value

HasContext ( )

IMPORT_C TBoolHasContext()const

Tests if an MTM context has been set.

A Client-side MTM has no context until one is set through SwitchCurrentEntryL() or SetCurrentEntryL() .

Return Value
ETrue: context has been set EFalse: context has not been set

InvokeAsyncFunctionL ( TInt, const CMsvEntrySelection &, TDes8 &, TRequestStatus & )

CMsvOperation *InvokeAsyncFunctionL(TIntaFunctionId,
const CMsvEntrySelection &aSelection,
TDes8 &aParameter,
TRequestStatus &aCompletionStatus
)[pure virtual]

Invokes 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.

Parameters
aFunctionIdID of the requested operation
aSelectionSelection of message entries. This is used if the operation requires message entries to work on.
aParameterBuffer containing input and output parameters. The format of this is specific to the operation.
aCompletionStatusThe request status to be completed when the operation has finished
Return Value
If successful, this is an asynchronously completing operation. If failed, this is a completed operation, with status set to the relevant error code.
Leave Codes
KErrNotSupportedaFunctionId is not a recognised operation ID
Otherleave codes Dependent on implementation

InvokeSyncFunctionL ( TInt, const CMsvEntrySelection &, TDes8 & )

voidInvokeSyncFunctionL(TIntaFunctionId,
const CMsvEntrySelection &aSelection,
TDes8 &aParameter
)[pure virtual]

Invokes 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.

Parameters
aFunctionIdID of the requested operation
aSelectionSelection of message entries. This is used if the operation requires message entries to work on.
aParameterBuffer containing input and output parameters. The format of this is specific to the operation.
Leave Codes
KErrNotSupportedaFunctionId is not a recognised operation ID
Otherleave codes Dependent on implementation

LoadMessageL ( )

voidLoadMessageL()[pure virtual]

Loads the cache with the message data for the current context.

It can only be called on message contexts.

It is typically used after the context has been set with SetCurrentEntryL() or SwitchCurrentEntryL(). 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. Typically, the message store should be opened for reading with CMsvEntry::ReadStoreL(). It should be then be read to set the following:

1. body text: call RestoreBodyL() to update the cached body text

2. address list: read the appropriate MTM-specific area of the store to update iAddresseeList

3. subject: if supported, read the appropriate MTM-specific area of the store and update the cache with SetSubjectL()

The function should panic for non-message contexts.

QueryCapability ( TUid, TInt & )

IMPORT_C TIntQueryCapability(TUidaCapability,
TInt &aResponse
)[virtual]

Queries if the MTM supports a particular capability, specified by a UID.

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.

Parameters
aCapabilityUID of capability to be queried
aResponseResponse value. The format of the response varies according to the capability.
Return Value
KErrNone: aCapability is a recognised value and a response is returned KErrNotSupported: aCapability is not a recognised value

RemoveAddressee ( TInt )

voidRemoveAddressee(TIntaIndex)[pure virtual]

Removes 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.

Parameters
aIndexIndex of address to be removed

RemoveDefaultServiceL ( )

IMPORT_C voidRemoveDefaultServiceL()[virtual]

Removes the default service setting. The default implementation of this function assumes that the MTM only supports one service and therefore this does nothing.

ReplyL ( TMsvId, TMsvPartList, TRequestStatus & )

CMsvOperation *ReplyL(TMsvIdaDestination,
TMsvPartListaPartlist,
TRequestStatus &aCompletionStatus
)[pure virtual]

Creates 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:

1. create a new message in the specified destination by calling CMsvEntry::CreateL()

2. set the entry index values as appropriate

3. set the properties of the message as required. The normal minimum is to set the address to the sender of the original message. An implementation may also follow the options specified in aPartlist to set other properties, for example, to include the original message text.

4. set the context to the reply

5. return a CMsvOperation-derived object to provide asynchronous control and monitoring of the operation

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.

Parameters
aDestinationThe entry to which to assign the reply
aPartlistDefines the parts that are to be copied from the original message into the reply
aCompletionStatusThe request status to be completed when the operation has finished
Return Value
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 Codes
KErrNotSupportedThe Client-side MTM does not support reply operations
Otherleave codes Dependent on implementation

RestoreBodyL ( CMsvStore & )

IMPORT_C voidRestoreBodyL(CMsvStore &aStore)[protected]

Gets the current cached CRichText from the appropriate stream in the specified message store. Client applications do not use this function. It is relevant only to implementers of derived classes.

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

Parameters
aStoreMessage store from which to read the body text

SaveMessageL ( )

voidSaveMessageL()[pure virtual]

Commits cached changes to the storage controlled by the Message Server.

It can only be called on message contexts. It should be called in the following circumstances:

1. to preserve changes when the context is changed, or when the Client-side MTM object is deleted

2. to enable other parts of the Messaging to access the updated entry, as required, for example, before sending a message

Requirements:

An implementation must update the store and index entry relating to the message context. Typically, the message store should be opened for editing with CMsvEntry::EditStoreL(). It should be updated as follows:

1. body text: call StoreBodyL() to update the store's body text stream

2. address list: update the appropriate MTM-specific area of the store from the data in iAddresseeList

3. subject: if supported, update the appropriate MTM-specific area of the store from the private cache set by SetSubjectL()

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

The function should panic for non-message contexts.

Session ( )

IMPORT_C CMsvSession &Session()

Gets a reference to the session object passed by the creator of the Client-side MTM.

Return Value
Session object used by the Client-side MTM

SetCurrentEntryL ( CMsvEntry * )

IMPORT_C voidSetCurrentEntryL(CMsvEntry *aEntry)

Sets the entry on which later actions are performed to the specified CMsvEntry.

Parameters
aEntryThe entry on which all following actions will be performed
Leave Codes
KErrNoMemoryInsufficient memory

SetExtensionData ( TAny * )

IMPORT_C voidSetExtensionData(TAny *aSortData)

SetMessageCharacterSet ( TUint )

IMPORT_C TIntSetMessageCharacterSet(TUintaCharSet)

Sets the character encoding value. The character encoding value options are 7-bit, 8-bit and 16-Bit Unicode. By default the character set encoding is 7 bit encoding.

Parameters
aCharSetCharacter encoding value may be 7-bit/8-bit/16-bit Unicode.
Return Value
KErrNone If charset is changed successfully in SMS settings.

SetSubjectL ( const TDesC & )

IMPORT_C voidSetSubjectL(const TDesC &aSubject)[virtual]

Sets 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.

The default implementation leaves with KErrNotSupported.

See also: StoreBodyL() RestoreBodyL()

Parameters
aSubjectMessage subject text
Leave Codes
KErrNotSupportedThe Client-side MTMs does not support subject text

StoreBodyL ( CMsvStore & )

IMPORT_C voidStoreBodyL(CMsvStore &aStore)[protected]

Stores and commits the current cached CRichText body text to the appropriate stream in the specified message store. Client applications do not use this function. It is relevant only to implementers of derived classes.

The function overwrites any existing data in that stream. The implementation must have write access to aStore.

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

Parameters
aStoreMessage store in which to store the body text
Leave Codes
KErrAccessDeniedThe store was opened for read only
OtherStandard stream-related leave codes

SubjectL ( )

IMPORT_C const TPtrCSubjectL()const [virtual]

Gets 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
Message subject text
Leave Codes
KErrNotSupportedThe Client-side MTMs does not support subject text

SwitchCurrentEntryL ( TMsvId )

IMPORT_C voidSwitchCurrentEntryL(TMsvIdaId)

Changes the entry on which later actions are performed to the entry with the specified TMsvId.

Parameters
aIdThe ID of the entry upon which all following actions will be performed
Leave Codes
KErrNoMemoryInsufficient memory
KErrNotFoundThe requested entry does not exist

Type ( )

IMPORT_C TUidType()const

Gets the Type UID of the message type associated with the Client-side MTM.

Return Value
UID of the message type associated with the MTM

ValidateMessage ( TMsvPartList )

TMsvPartList ValidateMessage(TMsvPartListaPartList)[pure virtual]

Validates the current message 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. A minimum step is to check that the current context is a message.

Parameters
aPartListIndicates the message parts for which validation is requested
Return Value
If valid, KErrNone If invalid, identifies the invalid part(s). The error value is the bitmask of the TMsvPartList IDs for each invalid part