MTM Registration

MTM registries

Registration of an MTM on the device is managed by four registries—three transient registries within each client process (Client MTM, UI MTM and UI Data MTM) and one permanent registry on the server-side (Server MTM). The server-side registry owns and maintains a streamed copy of the registration data for all MTM components on the device. When a new client-side registry is created by a client process, the server-side registry initialises the client registry by setting the available and relevant types (UI, UI Data, Client) of MTMs. This initialisation takes place through the Message Server and the session object which is owned by the process that instantiated the new registry object.

Note: Updating the client-side registries during run-time is done through the same process. The MTM installation control panel is a client-side process that uses a session object to talk to the server. Registration data representing new MTM DLLs is passed to the Message Server and onto the server-side registry. The server-side registry then updates its cached data before notifying all current client processes about the newly available MTM DLL.

The Messaging Server uses a registry to instantiate Server MTMs, and deletes the MTM objects when there no client requests. The server-side registry classes monitor the use of MTM component DLLs and maintain a reference count of the objects instantiated from each DLL. When that reference count falls to zero, the DLL that provides the MTM is unloaded. However, this is not done immediately, but only after the time specified in TTimeIntervalMicroSeconds32 aTimeoutMicroSeconds32. This increases the efficiency in cases where the DLL is required again shortly.

The CClientMtmRegistry::NewMtmL(TUid) function is used to create a Client MTM object for a protocol with a specified UID. The following steps illustrate how a Client MTM is identified and initialised:

1. A Messaging client application calls the CClientMtmRegistry::NewMtmL() function, passing the UID of the MTM component that it wants.

2. The CClientMtmRegistry class searches the registry for a record for the required MTM component, and obtains the library name from it, and the ordinal number of the library's exported factory function that can create an MTM object.

3. The CClientMtmRegistry class loads the DLL and calls the factory function, passing the new object back to the caller.

A similar process is used for UI and UI Data MTMs. After a client application has obtained an MTM object from the registry, it is responsible for that object and must delete it when it is no longer needed.

Example

The following example explains the steps to create a Client MTM registry.

When a Messaging client application is created to send and receive messages, a Client registry must be created. For detailed instructions, see the POP3 and IMAP4 example programs.

Use the CClientMtmRegistry::NewL() function with TTimeIntervalMicroSeconds32 aTimeoutMicroSeconds32 to create a Client MTM object for a protocol with a specified UID. The TTimeIntervalMicroSeconds32 aTimeoutMicroSeconds32 parameter represents a microsecond time interval stored in 32 bit, which is used to wait before unloading MTM DLLs.

void CImap4Example::CreateClientRegistryL()
    {
    // Create a message server session
    iSession=CMsvSession::OpenSyncL(*this);
    CleanupStack::PushL(iSession);

    // Create a client MTM registry
                // Time interval to unload a unused MTM DLL
    iClientRegistry=CClientMtmRegistry::NewL(*iSession,KMsvDefaultTimeoutMicroSeconds32);
                // IMAP4 email account   
                if (iClientRegistry != NULL && iClientRegistry->IsPresent(KUidMsgTypeIMAP4))
        {
        CleanupStack::PushL(iClientRegistry);
        }    
    }

For more details on how a Messaging client application gets an instance of the client MTM registry and creates Client MTM objects for the specified UID, see An Email manager using POP3 and SMTP and An Email manager using IMAP4 and SMTP.