<?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 id="GUID-260C7ACD-0024-59DE-B1C6-0C852E44C457" xml:lang="en"><title>Dynamically Loading Link Libraries Overview</title><shortdesc>Description of Polymorphic DLLs.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-25D3E357-BE6E-40BD-897D-DA5EB92029C5"><title>Purpose</title> <p>Dynamically load libraries during program execution.</p> <p>These

interfaces are used by programs that need to load libraries at run-time,

that have a common interface, but different concrete behavior. Because

of this relationship between interface and behaviour, such libraries

are called <i>polymorphic DLLs</i>. </p> </section>

<section id="GUID-5444CFD3-5FC2-4160-BD8A-8BD7154402B3"><title>Architectural

relationships</title> <p>Many parts of the system use polymorphic

DLLs. Communications components, such as Sockets and Messaging, use

architectures in which particular communications protocols are provided

as polymorphic DLLs, and are loaded as needed. UI application programs

are also polymorphic DLLs that are loaded when the user starts the

program.</p> </section>

<section id="GUID-2A379537-7B05-445F-83FC-C4396794A3CD"><title>Description</title> <p>The API has three key concepts: polymorphic DLL, polymorphic

DLL handle, and polymorphic DLL function pointer. </p> </section>

<section id="GUID-0A0DF81E-94C0-4D91-8F2A-1DFBE542E019"><title>Polymorphic

DLL</title> <p>A program that uses a type of polymorphic DLLs defines

their interface in terms of a single abstract class whose functions

are declared as pure virtual. Each type of polymorphic DLL is given

a unique identifier (UID). </p> <p>A particular concrete DLL:</p> <ul>

<li id="GUID-E073605D-1AC4-55B9-94AA-FD1A761B5448"><p>implements the

interface by defining and implementing a concrete class derived from

the abstract class.</p> </li>

<li id="GUID-AF95C27B-841D-53B5-836B-A55B4ED3E5F3"><p>exports a function

that creates an object of the derived class type. All other functions

in the DLL are virtual and called through the base class interface.</p> </li>

</ul></section>

<section id="GUID-825B7916-7E13-42B5-BAE4-A7009679E4F2"><title>Polymorphic

DLL handle</title><p>The polymorphic DLL handle allows a program to

load and close a particular polymorphic DLL. It also allows the caller

to obtain pointers to functions exported by the DLL. The system can

check that a polymorphic DLL is of the correct type by checking the

type UID value.</p> <p>The polymorphic DLL handle interface is provided

by <xref href="GUID-25327159-83D6-3507-B187-09EA4BB3727F.dita"><apiname>RLibrary</apiname></xref>.</p> <p>A wildcard file system search

for polymorphic DLLs can be done through <xref href="GUID-1B05E2E3-B64E-36A8-BFFF-430028113BA4.dita"><apiname>TFindLibrary</apiname></xref>.</p> </section>

<section id="GUID-C16BECEC-B59A-4FFE-94F0-548DB602A0BA"><title>Polymorphic

DLL function pointer</title> <p>An exported function is called through

a pointer to function obtained through a polymorphic DLL handle.</p> <p>The polymorphic DLL function pointer type is provided by the <xref href="GUID-7E0A7BA7-0EF8-3832-A1EA-B85FFADD1A9B.dita"><apiname>TLibraryFunction</apiname></xref> typedef. The caller casts the pointer

to the real type of the exported function before using it.</p> </section>

</conbody><related-links>

<link href="GUID-AB705D21-87A3-5F32-A4B9-17B7593DD5C3.dita"><linktext>UID

Manipulation Overview</linktext></link>