User Interface MTM

User Interface (UI) MTMs offer user interface capabilities, such as viewing, editing and copying of messages. Users interact with different message types in different ways. For example, a messaging protocol that supports attachments needs a more feature-rich editor than one that only supports text. UI MTMs allows a developer to produce user interface components to suit these differing requirements. Some Messaging protocols do not need any user interaction at all: in such cases, a UI MTM component does not need to be implemented.

UI MTMs offer some or all of the following capabilities:

  • Message viewing

  • Message editing

  • Folder manipulation

  • Editing service settings

  • Providing pre-transfer or connection settings UI

  • Providing pre-transfer preparation of messages before sending

  • Interpreting and displaying mail transfer progress

  • Interpreting and displaying error conditions

UI MTM base class

The base class for UI MTMs is CBaseMtmUi. Message client applications use the class to access the functionality polymorphically. 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 functions that can be implemented in a class derived from the CBaseMtmUi base class:

  • Entry manipulation functions

    The CBaseMtmUi::OpenL(), CBaseMtmUi::CloseL(), CBaseMtmUi::EditL(), and CBaseMtmUi::ViewL() functions are entry manipulation functions. They 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.

  • Copying and moving functions

    The CBaseMtmUi::CopyToL(), CBaseMtmUi::CopyFromL(), CBaseMtmUi::MoveToL(), and CBaseMtmUi::MoveFromL() functions copy and move 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 dialog to confirm settings.

  • Progress information functions

    The CBaseMtmUi::DisplayProgressSummary() and CBaseMtmUi::GetProgress() progress information functions 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 by these functions 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 CBaseMtmUi::InvokeSyncFunctionL() and CBaseMtmUi::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().

The CBaseMtmUi class provides the virtual functions for overriding in derived classes.

Editors and viewers

Functionality to edit and view messages may be one of the larger programming tasks in creating an MTM. Such functionality is typically implemented in separate DLLs that the UI MTM loads as required, to reduce the memory footprint of a UI MTM.

Related concepts
MTM overview
MTM Capabilities
Related tasks
Writing a UI MTM