<?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-32B82E5C-FD53-48E6-9ABC-88F82ACF71BC-GENID-1-7-1-14-1-1-7-1-4-1-1-4-1-5-1" xml:lang="en"><title>The
LDD Entry Point and Factory</title><shortdesc>This document describes how LDDs are created.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-A3C0C24F-BFE3-4126-A8C3-3CAEBDE28307-GENID-1-7-1-14-1-1-7-1-4-1-1-4-1-5-1-3-1">           <p>An LDD
must define an entry point function using the macro <xref href="GUID-B5DA78FD-07CA-3C9F-9154-D29A04E5E1E7.dita"><apiname>DECLARE_STANDARD_LDD</apiname></xref>,
or <xref href="GUID-38771B51-195D-3148-A462-277DA3696117.dita"><apiname>DECLARE_EXTENSION_LDD</apiname></xref> in the case of kernel extensions.
This must create an LDD factory object derived from <xref href="GUID-7616AA05-83E6-3989-AB9D-11AE01245BEB.dita"><apiname>DLogicalDevice</apiname></xref>: </p> <codeblock id="GUID-4867DF18-9CCD-548F-AB08-25C168527BD8-GENID-1-7-1-14-1-1-7-1-4-1-1-4-1-5-1-3-1-2" xml:space="preserve">DECLARE_STANDARD_LDD()
    {
    return new DerivedLogicalDevice;
    }</codeblock> <p>This factory object is created on the kernel heap. Its
purpose is to create the logical channel, the object through which all client
interaction with the driver will occur. </p> <p> <xref href="GUID-7616AA05-83E6-3989-AB9D-11AE01245BEB.dita"><apiname>DLogicalDevice</apiname></xref> is
derived from <xref href="GUID-E48F1435-14B6-37F1-BE47-2EA803AFE497.dita"><apiname>DObject</apiname></xref>, and is, therefore a reference-counting
object. It also means that <codeph>DLogicalDevice</codeph> objects are given
a name, as these objects are always subsequently found by name. The user-side
specifies the name of the logical device through the first parameter in the
user-side call to <xref href="GUID-6FBFA078-8253-3E24-B1F8-5F75E86C3066.dita#GUID-6FBFA078-8253-3E24-B1F8-5F75E86C3066/GUID-669AF44C-96BD-3CAB-95E7-DB2C5BEA00AF"><apiname>RBusLogicalChannel::DoCreate()</apiname></xref>. </p> <p>The
file extension of a LDD DLL can be any permitted Symbian Platform name but,
by convention, the LDD DLL has the extension <filepath>.LDD</filepath>. Device
driver DLLs are polymorphic interface DLLs. When building LDDs, specify a
target type of <i>ldd</i> in the <filepath>.mmp</filepath> file. </p> <p>An
LDD is loaded by calling <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-AE0D51B7-7ADC-3C9F-ACAA-8F6D9EA0AEFA"><apiname>User::LoadLogicalDevice()</apiname></xref>. This
static function: </p> <ul>
<li id="GUID-774CC8D6-4E6C-54C6-B6A4-1409EEDD8965-GENID-1-7-1-14-1-1-7-1-4-1-1-4-1-5-1-3-1-7-1"><p>loads the DLL into RAM,
if necessary </p> </li>
<li id="GUID-A9D6846C-F13F-56B3-A7C5-0CC2021BFF93-GENID-1-7-1-14-1-1-7-1-4-1-1-4-1-5-1-3-1-7-2"><p>calls the exported function
at ordinal 1 to create the factory object, the <codeph>DLogicalDevice</codeph> derived
object </p> </li>
<li id="GUID-50E53C2E-216A-592C-B0E6-4F8CA3D1B577-GENID-1-7-1-14-1-1-7-1-4-1-1-4-1-5-1-3-1-7-3"><p>places the factory object
into the appropriate object container. </p> </li>
</ul> <note> This only needs to be done once, not every time the driver is
used. </note> <p>If an LDD needs to perform initialisation at boot time (before
the driver is loaded by <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-AE0D51B7-7ADC-3C9F-ACAA-8F6D9EA0AEFA"><apiname>User::LoadLogicalDevice()</apiname></xref>) then
specify the entry point macros <codeph>DECLARE_STANDARD_EXTENSION</codeph> and <codeph>DECLARE_EXTENSION_LDD</codeph>. </p><codeblock id="GUID-4F20539E-4BC6-5D37-858B-53FD27E3A91E-GENID-1-7-1-14-1-1-7-1-4-1-1-4-1-5-1-3-1-10" xml:space="preserve">DECLARE_STANDARD_EXTENSION()
    {
    // initialise code here
    }

DECLARE_EXTENSION_LDD()
    {
    return new DMyLogicalFactory;
    }</codeblock><note><p>In order for the kernel to initialise the LDD extension
at boot time then the <filepath>.oby</filepath> file must specify the <codeph>extension</codeph> keyword.
Also note that initialisation of the extension will not load
the LDD: this still has to be done through a call to <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-AE0D51B7-7ADC-3C9F-ACAA-8F6D9EA0AEFA"><apiname>User::LoadLogicalDevice()</apiname></xref>.</p></note></section>
</conbody></concept>