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 CClientMtmRegistry
class has a member function to create a Client-side MTM object.
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 initializes the client registry by setting the available and relevant types (UI, UI Data, Client) of MTMs. This initialization 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:
A Messaging
client application calls the CClientMtmRegistry::NewMtmL()
function, passing the UID of the MTM component that it wants.
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.
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.
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 POP/IMAP Example.