Symbian3/SDK/Source/GUID-E96D8052-0CB2-53A6-915F-133D3058DCF9.dita
author Dominic Pinkman <Dominic.Pinkman@Nokia.com>
Thu, 21 Jan 2010 18:18:20 +0000
changeset 0 89d6a7a84779
permissions -rw-r--r--
Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
0
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     1
<?xml version="1.0" encoding="utf-8"?>
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     2
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     3
<!-- This component and the accompanying materials are made available under the terms of the License 
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     4
"Eclipse Public License v1.0" which accompanies this distribution, 
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     5
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     6
<!-- Initial Contributors:
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     7
    Nokia Corporation - initial contribution.
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     8
Contributors: 
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
     9
-->
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    10
<!DOCTYPE concept
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    11
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    12
<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>
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    13
          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>
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    14
          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>
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    15
          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()
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    16
    {
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    17
    // Create a message server session
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    18
    iSession=CMsvSession::OpenSyncL(*this);
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    19
    CleanupStack::PushL(iSession);
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    20
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    21
    // Create a client MTM registry
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    22
                // Time interval to unload a unused MTM DLL
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    23
    iClientRegistry=CClientMtmRegistry::NewL(*iSession,KMsvDefaultTimeoutMicroSeconds32);
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    24
                // IMAP4 email account   
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    25
                if (iClientRegistry != NULL &amp;&amp; iClientRegistry-&gt;IsPresent(KUidMsgTypeIMAP4))
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    26
        {
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    27
        CleanupStack::PushL(iClientRegistry);
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    28
        }    
89d6a7a84779 Initial contribution of Documentation_content according to Feature bug 1266 bug 1268 bug 1269 bug 1270 bug 1372 bug 1374 bug 1375 bug 1379 bug 1380 bug 1381 bug 1382 bug 1383 bug 1385
Dominic Pinkman <Dominic.Pinkman@Nokia.com>
parents:
diff changeset
    29
    }</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>