<?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

behaviour. 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>

<desc><xref href="GUID-AB705D21-87A3-5F32-A4B9-17B7593DD5C3.dita">UID Manipulation

Overview</xref></desc>

</link>