CBaseMtmUi Class Reference

#include <mw/mtmuibas.h>

Link against: mtur.lib

class CBaseMtmUi : public CBase, public CBase

Inherits from

CBaseMtmUi
- CBase
- CBase

Protected Attributes
CBaseMtm &	iBaseMtm
CCoeEnv *	iCoeEnv
TUint	iFlags

Public Member Enumerations
enum	anonymous { EProgressStringMaxLen }

Public Member Functions
virtual	~CBaseMtmUi()
IMPORT_C CBaseMtm &	BaseMtm()
pure virtual CMsvOperation *	CancelL(TRequestStatus &, const CMsvEntrySelection &)
pure virtual CMsvOperation *	CloseL(TRequestStatus &)
pure virtual CMsvOperation *	CloseL(TRequestStatus &, const CMsvEntrySelection &)
virtual IMPORT_C CMsvOperation *	CopyFromL(const CMsvEntrySelection &, TMsvId, TRequestStatus &)
virtual IMPORT_C CMsvOperation *	CopyToL(const CMsvEntrySelection &, TRequestStatus &)
virtual IMPORT_C CMsvOperation *	CreateL(const TMsvEntry &, CMsvEntry &, TRequestStatus &)
virtual IMPORT_C CMsvOperation *	DeleteFromL(const CMsvEntrySelection &, TRequestStatus &)
virtual IMPORT_C CMsvOperation *	DeleteServiceL(const TMsvEntry &, TRequestStatus &)
virtual IMPORT_C TInt	DisplayProgressSummary(const TDesC8 &)
pure virtual CMsvOperation *	EditL(TRequestStatus &)
pure virtual CMsvOperation *	EditL(TRequestStatus &, const CMsvEntrySelection &)
pure virtual CMsvOperation *	ForwardL(TMsvId, TMsvPartList, TRequestStatus &)
virtual IMPORT_C TInt	GetProgress(const TDesC8 &, TBuf< EProgressStringMaxLen > &, TInt &, TInt &, TInt &, TInt &)
virtual IMPORT_C CMsvOperation *	InvokeAsyncFunctionL(TInt, const CMsvEntrySelection &, TRequestStatus &, TDes8 &)
virtual IMPORT_C void	InvokeSyncFunctionL(TInt, const CMsvEntrySelection &, TDes8 &)
virtual IMPORT_C CMsvOperation *	MoveFromL(const CMsvEntrySelection &, TMsvId, TRequestStatus &)
virtual IMPORT_C CMsvOperation *	MoveToL(const CMsvEntrySelection &, TRequestStatus &)
pure virtual CMsvOperation *	OpenL(TRequestStatus &)
pure virtual CMsvOperation *	OpenL(TRequestStatus &, const CMsvEntrySelection &)
IMPORT_C TUint	Preferences()
virtual IMPORT_C TInt	QueryCapability(TUid, TInt &)
pure virtual CMsvOperation *	ReplyL(TMsvId, TMsvPartList, TRequestStatus &)
IMPORT_C void	SetPreferences(TUint)
IMPORT_C TUid	Type()
virtual IMPORT_C CMsvOperation *	UnDeleteFromL(const CMsvEntrySelection &, TRequestStatus &)
pure virtual CMsvOperation *	ViewL(TRequestStatus &)
pure virtual CMsvOperation *	ViewL(TRequestStatus &, const CMsvEntrySelection &)

Protected Member Functions
	CBaseMtmUi(CBaseMtm &, CRegisteredMtmDll &)
virtual IMPORT_C void	ConstructL()
virtual IMPORT_C TAny *	GetInterface(TUid)
pure virtual void	GetResourceFileName(TFileName &)
IMPORT_C CMsvSession &	Session()

Inherited Functions
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::Extension_(TUint,TAny &,TAny )
	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 MTM-specific user interaction, such as editing, viewing, deleting, and copying of message entries.

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 base class is largely an interface definition: it implements little important functionality itself. For implementers, this documentation defines conditions that any implementation must fulfil, plus suggested semantics for behaviour. This still leaves many decisions in the hands of the implementer. A key design time activity is to define how the particular characteristics of the implemented protocol are best mapped to the interface. As this class is concerned with user interfaces, implementers should be sensitive to the look and feel of the target phone.

Many functions are required to return an instance of a CMsvOperation-derived class to provide asynchronous control and monitoring to the caller of the operation being performed.

The following are some significant groups of functions:

Entry manipulation functions: OpenL(), CloseL(), EditL(), and ViewL() are all available in two overloaded versions. The first version operates on the current context. The second version operates upon groups of entries specified by a CMsvEntrySelection argument. All entries must be in same folder and all of the correct MTM type. The context may change after calling these functions. Concrete User Interface MTMs can legally ignore any of the entries within the selection - many may, for example, simply open the first entry.

Copying and moving functions: the CopyToL(), CopyFromL(), MoveToL(), and MoveFromL() functions are concerned with copying and moving entries to and from remote servers. MTMs can implement these functions to provide any user interaction needed before copying or moving can proceed, such as dialogs to confirm settings; and, any protocol-specific setup steps that can be done at this stage: for example, a fax MTM could render messages into the required image format.

Progress information functions: DisplayProgressSummary() and GetProgress() convert MTM-specific progress information about some asynchronous operation, such as message sending, to a human-readable form. The progress information to pass into these functions is, in general, obtained from an on-going CMsvOperation by calling CMsvOperation::Progress(). The nature of any information provided is MTM-specific.

MTM-specific UI functions: 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

iBaseMtm

CBaseMtm &

iBaseMtm

[protected]

The CBaseMtm-derived object (Client-side MTM) that requested the User Interface MTM. It is set by the constructor.

iCoeEnv

CCoeEnv *

iCoeEnv

[protected]

Control environment object. It is set by the constructor.

iFlags

TUint

iFlags

[protected]

This flag records the preferences as set by SetPreferences().

Member Enumeration Documentation

Enum anonymous

Progress information buffer length.

Enumerator	Value	Description
EProgressStringMaxLen	255	Defines the maximum buffer length used in GetProgress() to hold progress information.

Constructor & Destructor Documentation

CBaseMtmUi ( CBaseMtm &, CRegisteredMtmDll & )

IMPORT_C	CBaseMtmUi	(	CBaseMtm &	aBaseMtm,
			CRegisteredMtmDll &	aRegisteredMtmDll
		)	[protected]

Constructor, which initialises member variables from the passed arguments.

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

The value of aBaseMtm is stored in the protected data member iBaseMtm, so it can be accessed by derived classes.

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.

Parameters
aBaseMtm	The CBaseMtm requesting the object
aRegisteredMtmDll	Registration data for the DLL

~CBaseMtmUi ( )

IMPORT_C

~CBaseMtmUi

(

)

[virtual]

Destructor.

Cleans up the base class. CBaseMtmUi-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

BaseMtm ( )

IMPORT_C CBaseMtm &

BaseMtm

(

)

const

Gets a reference to the Client-side MTM that requested this object.

Return Value: Client-side MTM that requested this object

CancelL ( TRequestStatus &, const CMsvEntrySelection & )

CMsvOperation *	CancelL	(	TRequestStatus &	aStatus,
			const CMsvEntrySelection &	aSelection
		)	[pure virtual]

Cancels the sending of specified messages.

Parameters
aStatus	The request status to be completed when the operation has finished
aSelection	Selection of message entries

Return Value: If successful, this is an asynchronously completing cancel operation. If failed, this is a completed operation, with status set to the relevant error code.

Leave Codes
KErrNotSupported	The
Other	Dependent on implementation

CloseL ( TRequestStatus & )

CMsvOperation *

CloseL

(

TRequestStatus &

aStatus

)

[pure virtual]

Closes an entry. The behaviour that this implies is dependent on the current context:

1. for message contexts, this usually closes any launched editors or viewers

2. for folder contexts, leaves with KErrNotSupported

3. for service contexts, causes closure of a connection to a server

The returned CMsvOperation object completes when closing is complete.

Requirements:

Implementations should:

1. check aEntry.iType.iUid to ensure that they can close the requested type of entry and leave with code KErrNotSupported if they cannot

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

Parameters
aStatus	The request status to be completed when the operation has finished

Return Value: If successful, this is an asynchronously completing close operation. If failed, this is a completed operation, with status set to the relevant error code.

Leave Codes
KErrNotSupported	The
Other	Dependent on implementation

CloseL ( TRequestStatus &, const CMsvEntrySelection & )

CMsvOperation *	CloseL	(	TRequestStatus &	aStatus,
			const CMsvEntrySelection &	aSelection
		)	[pure virtual]

Closes a selection of entries.

The behaviour that this implies is dependent on the current context:

1. for message contexts, this usually closes any launched editors or viewers

2. for folder contexts, leaves with KErrNotSupported

3. for service contexts, causes closure of a connection to a server

The returned CMsvOperation object completes when closing is complete.

Requirements:

Implementations should:

1. check aEntry.iType.iUid to ensure that they can close the requested type of entry and leave with code KErrNotSupported if they cannot

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

Parameters
aStatus	The request status to be completed when the operation has finished
aSelection	Selection of message entries

Return Value: If successful, this is an asynchronously completing close operation. If failed, this is a completed operation, with status set to the relevant error code.

Leave Codes
KErrNotSupported	The
Other	Dependent on implementation

ConstructL ( )

IMPORT_C void

ConstructL

(

)

[protected, virtual]

Second-phase constructor.

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

Requirements:

Derived classes implement two-phase construction functions (NewL(), ConstructL()) to create a new instance of the object, in which any dynamic allocation should be performed. ConstructL() should be called from the NewL() function of the derived class.

The default implementation of this function loads resources required by the base class. Derived classes can implement this function to perform any additional MTM-specific second stage construction tasks that they require. Implementations must call the base class ConstructL() function.

Concrete MTMs must also implement a factory function by which a MTM registry can request an instance of the class.

CopyFromL ( const CMsvEntrySelection &, TMsvId, TRequestStatus & )

IMPORT_C CMsvOperation *	CopyFromL	(	const CMsvEntrySelection &	aSelection,
			TMsvId	aTargetId,
			TRequestStatus &	aStatus
		)	[virtual]

Copies an entry selection from a remote service.

All entries in the selection must have the same parent. The current context must be the MTM folder or service from which to copy. The returned CMsvOperation object completes when copying the entries is complete.

The usual result of this function is to get messages. It is called when the user copies and pastes messages from a remote service. The exact behaviour varies between MTMs.

Requirements:

The default implementation calls CMsvEntry::CopyL() to do the copy. If message copying is not supported, implementations should leave with KErrNotSupported.

Where this function is implemented, it should return a CMsvOperation-derived object to provide asynchronous control and monitoring of the operation.

Parameters
aSelection	Selection of message entries
aTargetId	The ID of the entry to own the copies
aStatus	The request status to be completed when the operation has finished

Return Value: If successful, this is an asynchronously completing copy operation. If failed, this is a completed operation, with status set to the relevant error code.

Leave Codes
KErrNotSupported	The
Other	Dependent on implementation

CopyToL ( const CMsvEntrySelection &, TRequestStatus & )

IMPORT_C CMsvOperation *	CopyToL	(	const CMsvEntrySelection &	aSelection,
			TRequestStatus &	aStatus
		)	[virtual]

Copies an entry selection to a remote service.

All entries in the selection must have the same parent. The current context must be the MTM folder or service to which to copy. The returned CMsvOperation object completes when copying the entries is complete.

The usual result of this function is to send messages. The exact behaviour varies between MTMs: for example, a Fax MTM would transmit a fax when asked to copy a fax from a local folder to a fax service.

Requirements:

The default implementation calls CMsvEntry::CopyL() to do the copy. If message copying is not supported, implementations should leave with KErrNotSupported.

Where this function is implemented, it should return a CMsvOperation-derived object to provide asynchronous control and monitoring of the operation.

Parameters
aSelection	Selection of message entries
aStatus	The request status to be completed when the operation has finished

Return Value: If successful, this is an asynchronously completing copy operation. If failed, this is a completed operation, with status set to the relevant error code.

Leave Codes
KErrNotSupported	The
Other	Dependent on implementation

CreateL ( const TMsvEntry &, CMsvEntry &, TRequestStatus & )

IMPORT_C CMsvOperation *	CreateL	(	const TMsvEntry &	aEntry,
			CMsvEntry &	aParent,
			TRequestStatus &	aStatus
		)	[virtual]

Creates a new entry as a child.

Typically, after creating the entry, the function would launch a suitable interface, such as a message editor, for the user to edit the new entry.

The returned CMsvOperation object completes when creation is complete (for example, when the message editor application is closed).

Requirements:

The default implementation simply calls aParent.CreateL() to create the entry. If creating entries is not supported, implementations should leave with KErrNotSupported. Otherwise, implementations should:

1. check aEntry.iType.iUid to ensure that they can create the requested type of entry and leave with code KErrNotSupported if they cannot

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

3. for messages, launch a suitable editor application developed for the message type.

Parameters
aEntry	The data to be copied into the new entry
aParent	The parent of the new entry
aStatus	The request status to be completed when the operation has finished

Return Value: If successful, this is an asynchronously completing create operation. If failed, this is a completed operation, with status set to the relevant error code.

Leave Codes
KErrNotSupported	The requested type of entry cannot be created
Other	Dependent on implementation

DeleteFromL ( const CMsvEntrySelection &, TRequestStatus & )

IMPORT_C CMsvOperation *	DeleteFromL	(	const CMsvEntrySelection &	aSelection,
			TRequestStatus &	aStatus
		)	[virtual]

Deletes a selection of entries owned by the current context.

The current context must be a folder or service of the relevant MTM. The returned CMsvOperation object completes when deleting is complete.

Requirements:

The default implementation simply calls CMsvEntry::DeleteL() to delete the entries. Implementations can override this to provide any additional checking or user interaction. If deleting entries is not supported, implementations should leave with KErrNotSupported.

Where this function is implemented, it should return a CMsvOperation-derived object to provide asynchronous control and monitoring of the operation.

Parameters
aSelection	Selection of message entries
aStatus	The request status to be completed when the operation has finished

Return Value: If successful, this is an asynchronously completing delete operation. If failed, this is a completed operation, with status set to the relevant error code.

Leave Codes
KErrNotSupported	The
Other	Dependent on implementation

DeleteServiceL ( const TMsvEntry &, TRequestStatus & )

IMPORT_C CMsvOperation *	DeleteServiceL	(	const TMsvEntry &	aService,
			TRequestStatus &	aStatus
		)	[virtual]

Deletes a specified service entry.

This entry does not have to be the current context. The usual behaviour is to remove the service settings, disabling further use of that service. The returned CMsvOperation object completes when deleting is complete.

Requirements:

The default implementation calls CMsvEntry::DeleteL() to delete the entry. Implementations can override this to provide any additional checking or user interaction. If deleting services is not supported, implementations should leave with KErrNotSupported.

Where this function is implemented, it should return a CMsvOperation-derived object to provide asynchronous control and monitoring of the operation.

Parameters
aService	Service to delete
aStatus	The request status to be completed when the operation has finished

Return Value: If successful, this is an asynchronously completing delete operation. If failed, this is a completed operation, with status set to the relevant error code.

Leave Codes
KErrNotSupported	This
Other	Dependent on implementation

DisplayProgressSummary ( const TDesC8 & )

IMPORT_C TInt

DisplayProgressSummary

(

const TDesC8 &

aProgress

)

const [virtual]

Displays a message describing the progress of an operation.

Requirements:

The default implementation simply returns KErrNotSupported.

Implementations should unpack the passed aProgress buffer, construct from this a suitable message, and display it. The implementation of this function should share an understanding of the format of the buffer with the implementations of CMsvOperation-derived classes.

Parameters
aProgress	Progress information obtained from a call to CMsvOperation::Progress()

Return Value: A system error code

EditL ( TRequestStatus & )

CMsvOperation *

EditL

(

TRequestStatus &

aStatus

)

[pure virtual]

Edits an entry.

The behaviour that this implies is dependent on the current context:

1. for message contexts, this usually launches the appropriate message editor, or returns status KErrReadOnly if the message is not editable

2. for remote folder contexts, launches a settings dialog, for example to rename the folder, completing asynchronously

3. for service contexts, launches a service settings dialog, completing asynchronously

The returned CMsvOperation object completes when editing is complete.

Requirements:

Implementations should:

1. check aEntry.iType.iUid to ensure that they can edit the requested type of entry and leave with code KErrNotSupported if they cannot

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

3. for remote messages, typically, copy the messages to the Inbox

4. follow the leave protocols described in Leave considerations below

Parameters
aStatus	The request status to be completed when the operation has finished

Return Value: If successful, this is an asynchronously completing edit operation. If failed, this is a completed operation, with status set to the relevant error code.

Leave Codes
KErrNotSupported	The
KErrReadOnly	Context is read-only
Other	Dependent on implementation

EditL ( TRequestStatus &, const CMsvEntrySelection & )

CMsvOperation *	EditL	(	TRequestStatus &	aStatus,
			const CMsvEntrySelection &	aSelection
		)	[pure virtual]

Edits a selection of entries.

The behaviour that this implies is dependent on the current context:

1. for message contexts, this usually launches the appropriate message editor, or returns status KErrReadOnly if the message is not editable

2. for remote folder contexts, launches a settings dialog, for example to rename the folder, completing asynchronously

3. for service contexts, launches a service settings dialog, completing asynchronously

The returned CMsvOperation object completes when editing is complete.

Requirements:

Implementations should:

1. check aEntry.iType.iUid to ensure that they can edit the requested type of entry and leave with code KErrNotSupported if they cannot

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

3. for remote messages, typically, copy the messages to the Inbox

4. follow the leave protocols described in Leave considerations below

Parameters
aStatus	The request status to be completed when the operation has finished
aSelection	Selection of message entries

Return Value: If successful, this is an asynchronously completing edit operation. If failed, this is a completed operation, with status set to the relevant error code.

Leave Codes
KErrNotSupported	The
KErrReadOnly	Context is read-only
Other	Dependent on implementation

ForwardL ( TMsvId, TMsvPartList, TRequestStatus & )

CMsvOperation *	ForwardL	(	TMsvId	aDestination,
			TMsvPartList	aPartList,
			TRequestStatus &	aCompletionStatus
		)	[pure virtual]

Creates a forwarded message from the current message context, and allows the user to edit it through a message-type specific editor.

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 forwarded message entry by calling CBaseMtm::ForwardL()

2. call EditL() allow the user to edit the forwarded message

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

Parameters
aDestination	The entry to which to assign the forwarded message
aPartList	Defines the parts which are to be copied from the original message into the forwarded message
aCompletionStatus	The 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
KErrNotSupported	The
Other	Dependent on implementation

GetInterface ( TUid )

IMPORT_C TAny *

GetInterface

(

TUid

aUid

)

[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
aUid	Uid of the extension interface

Return Value: Pointer to the extension interface

GetProgress ( const TDesC8 &, TBuf< EProgressStringMaxLen > &, TInt &, TInt &, TInt &, TInt & )

IMPORT_C TInt	GetProgress	(	const TDesC8 &	aProgress,
			TBuf< EProgressStringMaxLen > &	aReturnString,
			TInt &	aTotalEntryCount,
			TInt &	aEntriesDone,
			TInt &	aCurrentEntrySize,
			TInt &	aCurrentBytesTrans
		)	const [virtual]

Obtains progress information description and statistics. A message client application can then display this information to the user.

Requirements:

The default implementation returns KErrNotSupported.

Implementations should unpack the passed aProgress buffer, and fill in the return values appropriately. The implementation of this function should share an understanding of the format of the buffer with the implementations of CMsvOperation-derived classes.

Parameters
aProgress	MTM-specific transfer progress information
aReturnString	On return, a string describing the progress status
aTotalEntryCount	On return, the total number of entries the operation is acting upon
aEntriesDone	On return, the number of entries which the operation has completed on
aCurrentEntrySize	On return, the size of the current entry the operation is acting upon
aCurrentBytesTrans	On return, the number of bytes of the current entry which have been completed

Return Value: A system error code

GetResourceFileName ( TFileName & )

void

GetResourceFileName

(

TFileName &

aFileName

)

const [protected, pure virtual]

Sets the full path and name of the resource file associated with the User Interface MTM.

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

Requirements:

The function is called by CBaseMtmUi::ConstructL(), which then loads the resource file.

Parameters
aFileName	Filename buffer to be filled with the resource file path and name

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

IMPORT_C CMsvOperation *	InvokeAsyncFunctionL	(	TInt	aFunctionId,
			const CMsvEntrySelection &	aSelection,
			TRequestStatus &	aCompletionStatus,
			TDes8 &	aParameter
		)	[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:

The default implementation calls the corresponding function on the Client-side MTM (through iBaseMtm). This is sufficient for many implementations. However, there may be certain MTM-specific functions which require interaction with the user. These should be implemented here.

InvokeAsyncFunctionL() should return a CMsvOperation-derived object to provide asynchronous control and monitoring of the operation.

Parameters
aFunctionId	ID of the requested function
aSelection	Selection of message entries. This is used if the operation requires message entries to work on.
aCompletionStatus	The request status to be completed when the operation has finished
aParameter	Buffer containing input and output parameters. The format of this is specific to the operation.

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
KErrNotSupported	aFunctionId is not a recognised function ID
Other	Dependent on implementation

InvokeSyncFunctionL ( TInt, const CMsvEntrySelection &, TDes8 & )

IMPORT_C void	InvokeSyncFunctionL	(	TInt	aFunctionId,
			const CMsvEntrySelection &	aSelection,
			TDes8 &	aParameter
		)	[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:

Parameters
aFunctionId	ID of the requested function
aSelection	Selection of message entries. This is used if the operation requires message entries to work on.
aParameter	Buffer containing input and output parameters. The format of this is specific to the operation.

Leave Codes
KErrNotSupported	aFunctionId is not a recognised function ID
Other	Dependent on implementation

MoveFromL ( const CMsvEntrySelection &, TMsvId, TRequestStatus & )

IMPORT_C CMsvOperation *	MoveFromL	(	const CMsvEntrySelection &	aSelection,
			TMsvId	aTargetId,
			TRequestStatus &	aStatus
		)	[virtual]

Moves an entry selection from a remote service.

All entries in the selection must have the same parent. The current context must be the MTM folder or service from which to move. The returned CMsvOperation object completes when moving the entries is complete.

The usual result of this function is to get messages, in a similar way to CopyFromL(). The difference is that CopyFromL() does not remove the original entries.

Requirements:

The default implementation calls CMsvEntry::MoveL() to do the move. Implementations are likely to be similar to those for CopyToL(), and may indeed share code.

If an MTM does not support message moving, then it should leave with value KErrNotSupported.

Where this function is implemented, it should return a CMsvOperation-derived object to provide asynchronous control and monitoring of the operation.

Parameters
aSelection	Selection of message entries
aTargetId	The entry ID of the remote service
aStatus	The request status to be completed when the operation has finished

Return Value: If successful, this is an asynchronously completing move operation. If failed, this is a completed operation, with status set to the relevant error code.

Leave Codes
KErrNotSupported	The
Other	Dependent on implementation

MoveToL ( const CMsvEntrySelection &, TRequestStatus & )

IMPORT_C CMsvOperation *	MoveToL	(	const CMsvEntrySelection &	aSelection,
			TRequestStatus &	aStatus
		)	[virtual]

Moves an entry selection to a remote service.

All entries in the selection must have the same parent. The current context must be the MTM folder or service to which to move the entries. The returned CMsvOperation object completes when moving the entries is complete.

The usual result of this function is to send messages, in a similar way to CopyToL(). The difference is that CopyToL() does not remove the original entries.

The exact behaviour varies between MTMs, as described for CopyToL().

Requirements:

The default implementation calls CMsvEntry::MoveL() to do the move. Implementations are likely to be similar to those for CopyToL(), and may indeed share code.

If an MTM does not support message moving, then it should leave with value KErrNotSupported.

Where this function is implemented, it should return a CMsvOperation-derived object to provide asynchronous control and monitoring of the operation.

Parameters
aSelection	Selection of message entries
aStatus	The request status to be completed when the operation has finished

Return Value: If successful, this is an asynchronously completing move operation. If failed, this is a completed operation, with status set to the relevant error code.

Leave Codes
KErrNotSupported	The
Other	Dependent on implementation

OpenL ( TRequestStatus & )

CMsvOperation *

OpenL

(

TRequestStatus &

aStatus

)

[pure virtual]

Opens an entry.

The behaviour that this implies is dependent on the current context:

1. for message contexts, OpenL() is the equivalent of EditL(), or for read-only messages, ViewL(). Whether opening of remote messages is allowed is MTM-specific.

2. for service contexts, the function may initiate a connection to obtain the service contents from the server, completing asynchronously

3. for remote folder contexts, dependent on implementation, the function may initiate a connection to obtain the folder contents from the server, completing asynchronously

The returned CMsvOperation object completes when opening is complete.

Requirements:

If opening entries is not supported, implementations should leave with KErrNotSupported. Otherwise, implementations should:

1. check aEntry.iType.iUid to ensure that they can open the requested type of entry and leave with code KErrNotSupported if they cannot

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

3. for remote messages, typically, copy the messages to the Inbox

Parameters
aStatus	The request status to be completed when the operation has finished

Return Value: If successful, this is an asynchronously completing open operation. If failed, this is a completed operation, with status set to the relevant error code.

Leave Codes
KErrNotSupported	The
Other	Dependent on implementation

OpenL ( TRequestStatus &, const CMsvEntrySelection & )

CMsvOperation *	OpenL	(	TRequestStatus &	aStatus,
			const CMsvEntrySelection &	aSelection
		)	[pure virtual]

Opens a selection of entries.

The behaviour that this implies is dependent on the current context:

1. for message contexts, OpenL() is the equivalent of EditL(), or for read-only messages, ViewL(). Whether opening of remote messages is allowed is MTM-specific.

2. for service contexts, the function may initiate a connection to obtain the service contents from the server, completing asynchronously

3. for remote folder contexts, dependent on implementation, the function may initiate a connection to obtain the folder contents from the server, completing asynchronously

The returned CMsvOperation object completes when opening is complete.

Requirements:

If opening entries is not supported, implementations should leave with KErrNotSupported. Otherwise, implementations should:

1. check aEntry.iType.iUid to ensure that they can open the requested type of entry and leave with code KErrNotSupported if they cannot

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

3. for remote messages, typically, copy the messages to the Inbox

Parameters
aStatus	The request status to be completed when the operation has finished
aSelection	Selection of message entries

Return Value: If successful, this is an asynchronously completing open operation. If failed, this is a completed operation, with status set to the relevant error code.

Leave Codes
KErrNotSupported	The
Other	Dependent on implementation

Preferences ( )

IMPORT_C TUint

Preferences

(

)

const

Gets flags that communicate the MTM's preferences to the application UI.

Return Value: Bitmask of preference flags

QueryCapability ( TUid, TInt & )

IMPORT_C TInt	QueryCapability	(	TUid	aCapability,
			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:

The default implementation calls iBaseMtm->QueryCapability() (i.e. the corresponding function on the Client-side MTM) to do the query. This is sufficient for many implementations.

However, it is expected that each MTM-specific function is indicated by a capability. For example, if the MTM supports a function with UID KMtmUiMessagingXYZ, then there might be a capability KMtmUiQueryMessagingXYZ. Therefore, if different MTM-specific functions are supported by a User Interface MTM and by the corresponding Client-side MTM, this function should be implemented to reflect this.

Parameters
aCapability	Capability for which to query
aResponse	On return, indicates whether the capability is supported, or some other property of the capability..

Return Value: KErrNone if successful, KErrNotSupported: aCapability is not a recognised value

ReplyL ( TMsvId, TMsvPartList, TRequestStatus & )

CMsvOperation *	ReplyL	(	TMsvId	aDestination,
			TMsvPartList	aPartlist,
			TRequestStatus &	aCompletionStatus
		)	[pure virtual]

Creates a reply message to the current message context, and allows the user to edit it through a message-type specific editor.

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 editing 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 reply entry by calling CBaseMtm::ReplyL()

2. call EditL() allow the user to edit the reply

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

Parameters
aDestination	The entry to which to assign the reply
aPartlist	Defines the parts which are to be copied from the original message into the reply. See CBaseMtm::ReplyL() for details.
aCompletionStatus	The 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
KErrNotSupported	The
Other	Dependent on implementation

Session ( )

IMPORT_C CMsvSession &

Session

(

)

const [protected]

Gets a reference to the session object used by the Client-side MTM that requested the User Interface MTM.

Return Value: Session object used by the Client-side MTM

SetPreferences ( TUint )

IMPORT_C void

SetPreferences

(

TUint

aFlags

)

Sets flags that communicate the MTM's preferences to the application UI.

Parameters
aFlags	Bitmask of preference flags

Type ( )

IMPORT_C TUid

Type

(

)

const

Gets the Type UID of the message type associated with the User Interface MTM.

Return Value: UID of the message type associated with the MTM

UnDeleteFromL ( const CMsvEntrySelection &, TRequestStatus & )

IMPORT_C CMsvOperation *	UnDeleteFromL	(	const CMsvEntrySelection &	aSelection,
			TRequestStatus &	aStatus
		)	[virtual]

Undeletes the specified selection.

The default implementation leaves with KErrNotSupported.

Parameters
aSelection	Selection of message entries
aStatus	The request status to be completed when the operation has finished

Return Value: If successful, this is an asynchronously completing undelete operation. If failed, this is a completed operation, with status set to the relevant error code.

Leave Codes
KErrNotSupported	The
Other	Dependent on implementation

ViewL ( TRequestStatus & )

CMsvOperation *

ViewL

(

TRequestStatus &

aStatus

)

[pure virtual]

Views an entry.

For message contexts, this usually launches the appropriate message viewer. Other context types leave with KErrNotSupported. The returned CMsvOperation object completes when viewing is complete.

Requirements:

Implementations should:

1. check aEntry.iType.iUid to ensure that they can view the requested type of entry and leave with code KErrNotSupported if they cannot

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

Parameters
aStatus	The request status to be completed when the operation has finished

Return Value: If successful, this is an asynchronously completing view operation. If failed, this is a completed operation, with status set to the relevant error code.

Leave Codes
KErrNotSupported	The
Other	Dependent on implementation

ViewL ( TRequestStatus &, const CMsvEntrySelection & )

CMsvOperation *	ViewL	(	TRequestStatus &	aStatus,
			const CMsvEntrySelection &	aSelection
		)	[pure virtual]

Views a selection of entries.

For message contexts, this usually launches the appropriate message viewer. Other context types leave with KErrNotSupported. The returned CMsvOperation object completes when viewing is complete.

Requirements:

Implementations should:

1. check aEntry.iType.iUid to ensure that they can view the requested type of entry and leave with code KErrNotSupported if they cannot

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

Parameters
aStatus	The request status to be completed when the operation has finished
aSelection	Selection of message entries

Return Value: If successful, this is an asynchronously completing view operation. If failed, this is a completed operation, with status set to the relevant error code.

Leave Codes
KErrNotSupported	The
Other	Dependent on implementation