<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept xml:lang="en" id="GUID-E96D8052-0CB2-53A6-915F-133D3058DCF9"><title>MTM Registration</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>Any MTM that is used by a client application must be registered with the Message Server. The registration information about all the MTMs installed on a device is contained 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 <xref href="GUID-A0682D04-9084-3DC3-AA18-5B81A78A1DA8.dita"><apiname>CClientMtmRegistry</apiname></xref> class has a member function to create a Client-side MTM object. </p> <section><title>MTM registries</title> <p>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 <xref href="GUID-C45FFBDD-37D4-5892-8D13-CFE292264268.dita#GUID-C45FFBDD-37D4-5892-8D13-CFE292264268/GUID-EBBDB3ED-B5BD-580C-8869-BA35DBA64F1F">client-side registry</xref> 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. </p> <p> <b>Note:</b> 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. </p> <p>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 <xref href="GUID-EEC5813B-4C9F-323B-BCD6-1BB1A08D0B8C.dita"><apiname>TTimeIntervalMicroSeconds32</apiname></xref> <codeph>

          aTimeoutMicroSeconds32</codeph>. This increases the efficiency in cases where the DLL is required again shortly. </p> <p>The <xref href="GUID-A0682D04-9084-3DC3-AA18-5B81A78A1DA8.dita#GUID-A0682D04-9084-3DC3-AA18-5B81A78A1DA8/GUID-3010EA8F-DCC4-34AD-ADD8-83B789B10638"><apiname>CClientMtmRegistry::NewMtmL(TUid)</apiname></xref> 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: </p> <ol id="GUID-A4C4A3AE-395F-586C-BFAB-D1B0E30CFC8C"><li id="GUID-D9CD05E2-620B-501A-9C0D-8C24BE47F997"><p>A Messaging client application calls the <xref href="GUID-A0682D04-9084-3DC3-AA18-5B81A78A1DA8.dita#GUID-A0682D04-9084-3DC3-AA18-5B81A78A1DA8/GUID-76DA50D4-BA2E-3B06-8D80-A0619337C233"><apiname>CClientMtmRegistry::NewMtmL()</apiname></xref> function, passing the UID of the MTM component that it wants. </p> </li> <li id="GUID-7A27FC2C-1CA6-53F0-B2EE-D1814E455BF1"><p>The <xref href="GUID-A0682D04-9084-3DC3-AA18-5B81A78A1DA8.dita"><apiname>CClientMtmRegistry</apiname></xref> 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. </p> </li> <li id="GUID-4A89BA96-B946-5EC6-B285-9797A41E967A"><p>The <xref href="GUID-A0682D04-9084-3DC3-AA18-5B81A78A1DA8.dita"><apiname>CClientMtmRegistry</apiname></xref> class loads the DLL and calls the factory function, passing the new object back to the caller. </p> </li> </ol> <p>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. </p> </section> <section id="GUID-EBBDB3ED-B5BD-580C-8869-BA35DBA64F1F"><title>Example</title> <p>The following example explains the steps to create a Client MTM registry. </p> <p>When a Messaging client application is created to send and receive messages, a Client registry must be created. For detailed instructions, see the <xref href="GUID-BB35DBCC-FE56-547F-BADA-9EF854691ADC.dita">POP3</xref> and <xref href="GUID-D73AD200-BE4D-50BF-BCF9-14627DE530B7.dita">IMAP4</xref> example programs. </p> <p>Use the <xref href="GUID-A0682D04-9084-3DC3-AA18-5B81A78A1DA8.dita#GUID-A0682D04-9084-3DC3-AA18-5B81A78A1DA8/GUID-DBD7038B-A0E2-3791-A4C9-3A22FFCA146A"><apiname>CClientMtmRegistry::NewL()</apiname></xref> function with <xref href="GUID-EEC5813B-4C9F-323B-BCD6-1BB1A08D0B8C.dita"><apiname>TTimeIntervalMicroSeconds32</apiname></xref> <codeph>

          aTimeoutMicroSeconds32</codeph> to create a Client MTM object for a protocol with a specified UID. The <xref href="GUID-EEC5813B-4C9F-323B-BCD6-1BB1A08D0B8C.dita"><apiname>TTimeIntervalMicroSeconds32</apiname></xref> <codeph>

          aTimeoutMicroSeconds32</codeph> parameter represents a microsecond time interval stored in 32 bit, which is used to wait before unloading MTM DLLs. </p> <codeblock id="GUID-1F9B89A1-C908-5578-B3FD-B4B1EA5F032A" xml:space="preserve">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);

        }    

    }</codeblock> <p>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 <xref href="GUID-BB35DBCC-FE56-547F-BADA-9EF854691ADC.dita">An Email manager using POP3 and SMTP</xref> and <xref href="GUID-D73AD200-BE4D-50BF-BCF9-14627DE530B7.dita">An Email manager using IMAP4 and SMTP</xref>. </p> </section> </conbody></concept>