<?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-GENID-1-7-1-14-1-1-7-1-4-1-1-7-1-6-1" 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-GENID-1-7-1-14-1-1-7-1-4-1-1-7-1-6-1-3-1">           <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-GENID-1-7-1-14-1-1-7-1-4-1-1-7-1-6-1-3-1-2" 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-GENID-1-7-1-14-1-1-7-1-4-1-1-7-1-6-1-3-1-6">

<li id="GUID-2D096381-32BD-57EB-9387-2B10B0020686-GENID-1-7-1-14-1-1-7-1-4-1-1-7-1-6-1-3-1-6-1"><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-GENID-1-7-1-14-1-1-7-1-4-1-1-7-1-6-1-3-1-6-1-2" 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-GENID-1-7-1-14-1-1-7-1-4-1-1-7-1-6-1-3-1-6-2"><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-GENID-1-7-1-14-1-1-7-1-4-1-1-7-1-6-1-3-1-9-1"><p>loads the DLL into RAM,

if necessary </p> </li>

<li id="GUID-4C131AE3-7048-5C91-9EF8-C7EBC04CC7B3-GENID-1-7-1-14-1-1-7-1-4-1-1-7-1-6-1-3-1-9-2"><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-GENID-1-7-1-14-1-1-7-1-4-1-1-7-1-6-1-3-1-9-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 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-GENID-1-7-1-14-1-1-7-1-4-1-1-7-1-6-1-3-1-12" 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>