Please note that as of October 24, 2014, the Nokia Developer Wiki will no longer be accepting user contributions, including new entries, edits and comments, as we begin transitioning to our new home, in the Windows Phone Development Wiki. We plan to move over the majority of the existing entries over the next few weeks. Thanks for all your past and future contributions.
Message Type Modules
Messaging provides base classes, which defines the component interfaces for MTM implementations. The base classes also provide implementations of some methods. The interfaces allows MTM components to be used polymorphically. As part of these interfaces, User Interface, Client-side, and User Interface Data MTMs must all support a function that allows message client applications to query the supported functionality: for example, the maximum message size, or whether attachments are supported.
MTM components must also be able to offer protocol-specific functionality not provided by base class interface functions. A MTM component defines UIDs that correspond to each protocol-specific capability offered, and implements a function that allow clients to access these capabilities by passing in the appropriate UID. Two versions of this function are available, supporting synchronous and asynchronous behaviour respectively.
User Interface MTMs
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. User Interface MTMs allow developers to produce user interface components to suit these differing requirements. Some messaging protocols may even not need any user interaction at all: in such cases, a User Interface MTM component does not need to be implemented.
User Interface MTMs offer some or all of the following capabilities:
- viewing messages
- editing messages
- folder manipulation
- editing service settings
- providing pre-transfer/connection settings UI
- providing pre-transfer preparation of messages before sending
- interpreting and displaying mail transfer progress
- interpreting and displaying error conditions
A User Interface MTM need not supply all these functions. The Fax User Interface MTM, for example, would not supply folder manipulation, since folders are not appropriate within a fax service, but does provide pre-transfer preparation, as a fax may need to be rendered before transmitting.
Editors and Viewers
Functionality to edit and/or view messages may be one of the larger programming tasks in creating an MTM. Such functionality is typically implemented in separate DLLs that the User Interface MTM loads as required, to reduce the memory footprint of a User Interface MTM.
Client-side MTMs act as the interface between the internal representation of a message’s data and the User Interface MTM. This separation allows, for example, a User Interface MTM to offer a user interface to enter message addresses, without having to know the address storage format.
Client-side MTMs offer some or all of the following capabilities:
- address list manipulation
- creation of forward and response messages
- message subject access
- message validation
- internalising and externalising MTM-specific data to the message store
The entry with which the Client-side MTM is currently working is referred to as the context, similarly to CMsvEntry. User Interface MTMs always operate on the context set through the Client-side MTM.
Message client applications that do not require a user interface can use these functions directly for automated message handling.
UI Data MTMs
Message client applications are likely to need access to certain MTM-specific functions often and rapidly. These functions could be held in User Interface MTMs, but the resulting requirement to hold many User Interface MTMs in memory simultaneously could impose a large memory overhead. For this reason, a separate component type, the UI Data MTM, is defined.
UI Data MTMs offer the following capabilities:
- Provide bitmap icons for messages, folders, and services for display in the various folder views. For each icon, an array of bitmaps should be available, giving the icon in a number of sizes.
- Provide command captions for MTM-specific functions that the message client application can dynamically add to menus and dialog controls. A function ID is associated with each caption to identify the MTM-specific function that should be invoked when the command is chosen. This data is encapsulated in a resource file MTUD_FUNCTION type.
- Validate that specified functions are available on a particular entry, so that a message client application can, for example, grey out menu items that do not apply to that entry.
The implementation of UI Data MTMs is relatively simple, as they contain little more than functions to return the required icons and extra menu items.
The server-side component of an MTM deals with the interaction between the internal data representation of message data, and the transport components (for example, the sockets layer, or ETel). When receiving a message, a Server-side MTM creates a new index entry, and stores the message data in the entry and associated message store and binary files. Similarly, when sending a message, a Server-side MTM retrieves the message data, and translates the data into a format appropriate for the protocol.
Server-side MTMs should provide the following capabilities:
- copy and move files to and/or from the local folders
- return the progress of the current operation
- interpret MTM-specific commands
Some Server-side MTMs may also have the ability to create, delete, and change messages and folders on remote servers. Sophisticated Server-side MTMs may be able to cache requested operations off-line for execution at a later time.
Different Server-side MTMs interpret generic commands in different ways. For example, a fax MTM would transmit a fax when asked to copy a fax message from a local folder to a fax service. By contrast, an IMAP4 MTM could create a copy of the Internet mail message on the remote server and update the index to show the copy of the message on the remote server.
MTM-specific commands allow actions not defined by the base class interface to be made available. For example: for fax, dial a fax back service; for POP3, connect to a remote server and download messages.
A record of all the MTM components installed on a machine is held in a dedicated file managed by the Message Server called the MTM Registry. Registry classes use this registration data to allow MTM components to be identified and instantiated. For example, the CClientMtmRegistry class has a member function to create a Client-side MTM object.
- a message client application calls this function, passing in the UID of the MTM component that it wants
- CClientMtmRegistry searches the registry for a record for the required MTM component, and obtains from it the library name, and ordinal of the library's exported factory function that can create an MTM object
- CClientMtmRegistry loads the DLL and calls the factory function, passing the new object back to the caller
A similar process is used for User Interface and UI Data MTMs. Such MTM objects are owned by the clients that create them. Clients are also responsible for deleting these objects.
Server-side MTM objects are created by a server-side registry class in response to calls from the Message Server. When the Message Server has no more requests queued for that MTM, it deletes the object. For efficiency, an MTM object can stop itself being deleted when more commands are expected shortly: see CBaseServerMtm::CommandExpected().
Registry classes monitor the use of MTM component DLLs and maintain a reference count of the objects instantiated from each. This allows a registry class to unload a DLL when it is no longer required. However, message client applications can often require a particular MTM component a number of times in any particular session. The registry classes do not therefore immediately unload a component DLL when the reference count is zero. Instead, a timer is started. When the timer completes, the DLL is unloaded if its reference count has remained at zero for the duration.