<?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-D291C9E9-5207-4B23-B287-C240464087B9" xml:lang="en"><title>The
PDD Entry Point and Factory</title><shortdesc>This document describes how PDDs are created.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-1099A347-6D77-4231-BAF5-B0EAAEA560B7">           <p>A PDD
must define an entry point function using the macro <xref href="GUID-73947402-2F32-35C7-94C4-22B4D63D5FB3.dita"><apiname>DECLARE_STANDARD_PDD</apiname></xref>,
or <xref href="GUID-52853C0D-CA98-3B92-B7D4-FF1C1F06C1A6.dita"><apiname>DECLARE_EXTENSION_PDD</apiname></xref> in the case of kernel extensions.
This must create a PDD factory object derived from <xref href="GUID-A5484A7F-94B9-34C7-9F88-82B1BF516930.dita"><apiname>DPhysicalDevice</apiname></xref>: </p><codeblock id="GUID-895AE2E1-A739-5FDB-8039-D382E7ACF245" xml:space="preserve">DECLARE_STANDARD_PDD()
    {
    return new DerivedPhysicalDevice;
    }</codeblock> <p>This factory object is created on the kernel heap. Its
purpose is to create the physical channel, if needed. </p> <p> <xref href="GUID-A5484A7F-94B9-34C7-9F88-82B1BF516930.dita"><apiname>DPhysicalDevice</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>DPhysicalDevice</codeph> objects are given
a name, as these objects are always subsequently found by name. Names are
also used to identify those PDDs that can be used with a given LDD; they have
a name of the form <codeph>x.y</codeph> where <codeph>x</codeph> is the name
used by the LDD and <codeph>y</codeph> is PDD-specific. </p> <p>An LDD indicates
that it requires an accompanying PDD by setting the LDD factory object member <xref href="GUID-7616AA05-83E6-3989-AB9D-11AE01245BEB.dita#GUID-7616AA05-83E6-3989-AB9D-11AE01245BEB/GUID-EB891156-94D9-323A-AB23-7B5994CD95E3"><apiname>DLogicalDevice::iParseMask</apiname></xref> with
the <codeph>KDeviceAllowPhysicalDevice</codeph> flag. There are two ways that
a suitable PDD can be found: </p> <ol id="GUID-FA526F7D-1DD7-5228-AA5C-CEBC74191B0B">
<li id="GUID-2D096381-32BD-57EB-9387-2B10B0020686"><p>A user can specify the
name of a PDD through the <codeph>RBusLogicalChannel::DoCreate()</codeph> protected
function: </p><codeblock id="GUID-21CE3362-AD93-5FCE-BBC7-212C919ED83C" xml:space="preserve">TInt DoCreate(const TDesC&amp; aDevice, const TVersion&amp; aVer, TInt aUnit, const TDesC* aDriver, const TDesC8* anInfo, TOwnerType aType=EOwnerProcess, TBool aProtected=EFalse);</codeblock> <p>The user side passes a pointer to a descriptor containing the name of
the required PDD as the fourth argument. A PDD with that name must already
have been loaded, and its factory object created. The device driver framework
searches for a PDD factory object with that name, and if found, calls <codeph>Validate()</codeph> on
that object; if this function returns <xref href="GUID-6CA4F1ED-7947-3087-B618-D35858FAA3BC.dita"><apiname>KErrNone</apiname></xref>, then the
PDD is accepted as the required PDD. </p> </li>
<li id="GUID-ECF90DCF-71B6-5F1D-A3B5-0FF245A58306"><p>If no explicit PDD name
is passed from the user side, then the device driver framework searches for
all PDD factory objects, i.e. <xref href="GUID-A5484A7F-94B9-34C7-9F88-82B1BF516930.dita"><apiname>DPhysicalDevice</apiname></xref> objects,
that have a name in the form <codeph>x.y</codeph>, where <codeph>x</codeph> is
the name of the LDD factory object. The device driver framework calls <codeph>Validate()</codeph> on
each matching PDD factory object, passing the unit number and the optional
extra information block; the first one to return <xref href="GUID-6CA4F1ED-7947-3087-B618-D35858FAA3BC.dita"><apiname>KErrNone</apiname></xref> is
accepted as the required PDD. </p> </li>
</ol> <p>The file extension of a PDD DLL can be any permitted Symbian Platform
name but, by convention, the PDD DLL has the extension <filepath>.PDD</filepath>.
Device driver DLLs are polymorphic interface DLLs. When building PDDs, specify
a target type of <i>pdd</i> in the <filepath>.mmp</filepath> file. </p> <p>A
PDD is loaded by calling <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-A0F4BF4A-9C58-3E5E-88E1-6D98597DDA18"><apiname>User::LoadPhysicalDevice()</apiname></xref>. This
static function: </p><ul>
<li id="GUID-EFB4CF23-26C3-5874-9709-5BE112F92C2A"><p>loads the DLL into RAM,
if necessary </p> </li>
<li id="GUID-4C131AE3-7048-5C91-9EF8-C7EBC04CC7B3"><p>calls the exported function
at ordinal 1 to create the factory object, the <codeph>DPhysicalDevice</codeph> derived
object </p> </li>
<li id="GUID-FC279525-DC2E-5000-AE8F-B2E03F8A2FCF"><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 a PDD 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-A0F4BF4A-9C58-3E5E-88E1-6D98597DDA18"><apiname>User::LoadPhysicalDevice()</apiname></xref>), then
specify the entry point macros <codeph>DECLARE_STANDARD_EXTENSION</codeph> and <codeph>DECLARE_EXTENSION_PDD</codeph>. </p><codeblock id="GUID-CF83DB15-2040-5C18-9728-E1B3A56E9D50" xml:space="preserve">DECLARE_STANDARD_EXTENSION()
    {
    // initialise code here
    }

DECLARE_EXTENSION_PDD()
    {
    return new DMyPhysicalFactory;
    }</codeblock> <note><p>In order for the kernel to initialise the PDD 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 PDD - 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-67DF6521-DE70-39E1-8EFB-246D419F7566"><apiname>User::LoadPhysicalDevice().</apiname></xref></p></note> 
   </section>
</conbody></concept>