<?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-B47C22DA-D1E6-5D89-87E7-7E4A5FD5A8D4" xml:lang="en"><title>The

LDD Factory</title><shortdesc>The LDD factory implements a factory for logical channel objects. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>The LDD factory class is <xref href="GUID-7616AA05-83E6-3989-AB9D-11AE01245BEB.dita"><apiname>DLogicalDevice</apiname></xref>. </p>

<p>The class provides a framework in the standard way, where some of the functions

are virtual and can be overridden, and others are pure virtual and an implementation

is obligatory. In addition, a derived class can add data members and functions,

including C++ constructors and a destructor. </p>

<p>The LDD factory class is built as part of the LDD DLL. User side code calls <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> to

load the LDD DLL and create the LDD factory object on the Kernel heap. </p>

<p>The class, with its publicly accessible functions and member data, is defined

as: </p>

<codeblock id="GUID-4E390788-A773-5758-B50D-D2B45562F314" xml:space="preserve">class DLogicalDevice : public DObject

    {

public:

    IMPORT_C virtual ~DLogicalDevice();

    IMPORT_C virtual TBool QueryVersionSupported(const TVersion& aVer) const;

    IMPORT_C virtual TBool IsAvailable(TInt aUnit, const TDesC* aDriver, const TDesC8* aInfo) const;

    virtual TInt Install()=0;

    virtual void GetCaps(TDes8& aDes) const =0;

    virtual TInt Create(DLogicalChannelBase*& aChannel)=0;

public:

    TVersion iVersion;

    TUint iParseMask;

    TUint iUnitsMask;

    DCodeSeg* iCodeSeg;

    TInt iOpenChannels;

    };

</codeblock>

<p>Note that the terms <i>LDD</i>, <i>LDD factory</i>, and <i>logical device</i> tend

to be used as synonyms for each other. </p>

<ul>

<li id="GUID-0A528E80-1A82-56EB-AF48-5C2048298CE7"><p> <xref href="GUID-B47C22DA-D1E6-5D89-87E7-7E4A5FD5A8D4.dita#GUID-B47C22DA-D1E6-5D89-87E7-7E4A5FD5A8D4/GUID-592E22CB-E6F2-50C2-9BD4-BE992535F2DB">Requirements</xref>  </p> <ul>

<li id="GUID-86F8A6A5-2D4D-5C11-B388-E7FDD55E21D3"><p> <xref href="GUID-B47C22DA-D1E6-5D89-87E7-7E4A5FD5A8D4.dita#GUID-B47C22DA-D1E6-5D89-87E7-7E4A5FD5A8D4/GUID-830ADD59-0317-513D-841D-CD2106ACA8F8">The entry point and creation of the factory object</xref>  </p> </li>

<li id="GUID-24F8AD21-B22D-5171-A4F1-40CE328B4E3C"><p> <xref href="GUID-B47C22DA-D1E6-5D89-87E7-7E4A5FD5A8D4.dita#GUID-B47C22DA-D1E6-5D89-87E7-7E4A5FD5A8D4/GUID-E8ABD435-8F7E-5A54-BFDE-0CBB200C88A0">Constructor</xref> </p> </li>

<li id="GUID-099D39A0-35F2-5FE7-9CEB-DB281BC7D4AE"><p> <xref href="GUID-B47C22DA-D1E6-5D89-87E7-7E4A5FD5A8D4.dita#GUID-B47C22DA-D1E6-5D89-87E7-7E4A5FD5A8D4/GUID-BABA46B6-94A1-56AE-B732-8ECF401C5086">Implementing Install()</xref>  </p> </li>

<li id="GUID-19BD4AD4-7958-5330-8071-3457C449838B"><p> <xref href="GUID-B47C22DA-D1E6-5D89-87E7-7E4A5FD5A8D4.dita#GUID-B47C22DA-D1E6-5D89-87E7-7E4A5FD5A8D4/GUID-4F7A9727-7DCC-5FA2-A88D-38646EF9EA26">Implementing GetCaps()</xref>  </p> </li>

<li id="GUID-A93A9AC8-26B2-5D52-811A-46591E6208EA"><p> <xref href="GUID-B47C22DA-D1E6-5D89-87E7-7E4A5FD5A8D4.dita#GUID-B47C22DA-D1E6-5D89-87E7-7E4A5FD5A8D4/GUID-4E2880B7-C20D-546F-B57E-43112EE90E1D">Implementing Create()</xref>  </p> </li>

</ul> </li>

<li id="GUID-5740E3F9-6871-545B-8B8D-B19F7E64EE7E"><p> <xref href="GUID-B47C22DA-D1E6-5D89-87E7-7E4A5FD5A8D4.dita#GUID-B47C22DA-D1E6-5D89-87E7-7E4A5FD5A8D4/GUID-EDE0E5D7-AE37-53F5-96BD-B6B9C290899D">Optional changes</xref>  </p> <ul>

<li id="GUID-FAE20AF6-5CC2-5DFA-8465-CFC986066D8D"><p> <xref href="GUID-B47C22DA-D1E6-5D89-87E7-7E4A5FD5A8D4.dita#GUID-B47C22DA-D1E6-5D89-87E7-7E4A5FD5A8D4/GUID-DFBB0D38-EF9A-5FEE-A89B-68E2FC7FFB37">Re-implementing QueryVersionSupported()</xref>  </p> </li>

<li id="GUID-A86E068C-F0FC-5966-90FB-1A7AE1769C73"><p> <xref href="GUID-B47C22DA-D1E6-5D89-87E7-7E4A5FD5A8D4.dita#GUID-B47C22DA-D1E6-5D89-87E7-7E4A5FD5A8D4/GUID-4311EED9-F15A-5E80-8C0E-79369426BE65">Re-implementing IsAvailable()</xref>  </p> </li>

</ul> </li>

</ul>

<section id="GUID-592E22CB-E6F2-50C2-9BD4-BE992535F2DB"><title>Requirements</title> <p id="GUID-830ADD59-0317-513D-841D-CD2106ACA8F8"><b>The entry point and creation

of the factory object</b> </p> <p>You need to provide an entry point for your

LDD DLL. There is a standard macro for this: <codeph>DECLARE_STANDARD_LDD()</codeph>.

You code this as: </p> <codeblock id="GUID-E6151C11-3129-529D-B2CB-7F756576A0E3" xml:space="preserve">DECLARE_STANDARD_LDD()

    {

    // code to be run on entry to the LDD DLL

    }</codeblock> <p>If your LDD is also a kernel extension, then use <codeph>DECLARE_EXTENSION_LDD()</codeph> instead. </p> <p>The

macro declares a function that is exported at ordinal 1, and your implementation

should create an instance of your class derived from <xref href="GUID-7616AA05-83E6-3989-AB9D-11AE01245BEB.dita"><apiname>DLogicalDevice</apiname></xref>.

The following is standard: </p> <codeblock id="GUID-F0EB9B6D-0DC0-5D23-AE01-3D45F45D2DBB" xml:space="preserve">DECLARE_STANDARD_LDD()

    {

    return new DerivedLogicalDevice;

    }</codeblock> <p>where <codeph>DerivedLogicalDevice</codeph> is your derived

class. </p> <p id="GUID-E8ABD435-8F7E-5A54-BFDE-0CBB200C88A0"><b>Constructor</b> </p> <p>The

default constructor is called as part of the process of creating the factory

object. </p> <p>A derived class usually provides a default constructor to

initialise member data, and in particular to initialise the following data

members of the <codeph>DLogicalDevice</codeph> base class : <xref href="GUID-7616AA05-83E6-3989-AB9D-11AE01245BEB.dita#GUID-7616AA05-83E6-3989-AB9D-11AE01245BEB/GUID-F2D6445C-D651-3D06-9D11-52C25D5CFF7E"><apiname>DLogicalDevice::iVersion</apiname></xref>,

and <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>. </p> <p>Note that <xref href="GUID-7616AA05-83E6-3989-AB9D-11AE01245BEB.dita#GUID-7616AA05-83E6-3989-AB9D-11AE01245BEB/GUID-BFE7A7B7-E9E7-3F6A-810E-CFC8D8453D69"><apiname>DLogicalDevice::iUnitsMask</apiname></xref> is

not used. </p> <p>This is the constructor from the example driver's LDD factory

class: </p> <codeblock id="GUID-BA631D20-5094-528A-912D-FB05866999AE" xml:space="preserve">DDriver1Factory::DDriver1Factory()

    {

    // Set version number for this device

    iVersion=RDriver1::VersionRequired();

    // Indicate that we work with a PDD

    iParseMask=KDeviceAllowPhysicalDevice;

    }

</codeblock> <p> <codeph>iVersion</codeph> represents the version of the interface

supported by this LDD. It will normally be be incremented if the interface

changes. Checking code assumes that clients requesting older versions will

be OK with a newer version, but clients requesting newer versions will not

want an old version. </p> <p id="GUID-BABA46B6-94A1-56AE-B732-8ECF401C5086"><b>Implementing Install()</b> </p> <p>This

function is called after the LDD DLL has been successfully loaded, and the

factory object has been successfully created on the kernel heap. </p> <p>The

function is a second stage constructor for the factory object, and allows

any further initialisation of the factory object to be done. </p> <p>The only

requirement of this function is that it must define and set the name of the

factory object. The name is important as it is the way in which these objects

are subsequently found. Note that this name is <i>not</i> the same as the

name of the file containing the LDD DLL itself. </p> <p>This is the <codeph>Install()</codeph> function

from the example driver's LDD factory class: </p> <codeblock id="GUID-2DB208AB-6968-5ECA-BBF3-C2978C18E236" xml:space="preserve">TInt DDriver1Factory::Install()

    {

    return SetName(&RDriver1::Name());

    }

</codeblock> <codeblock id="GUID-04306F2D-61BE-561C-B7DC-2AE397E68A55" xml:space="preserve">const TDesC&amp; RDriver1::Name()

    {

    _LIT(KDriver1Name,"DRIVER1");

    return KDriver1Name;

    }</codeblock> <p>The factory class is ultimately derived from <xref href="GUID-E48F1435-14B6-37F1-BE47-2EA803AFE497.dita"><apiname>DObject</apiname></xref>,

and means that the factory object is a reference counting object. Names are

properties of reference counting objects and <codeph>SetName()</codeph> is

called on this <codeph>DObject</codeph> base class. </p> <p>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> will specify a name

as its first parameter, and the device driver framework finds the factory

object by searching for a matching name. </p> <p>Names are also used to identify

the PDDs which can be used with a given LDD – these have a name of the form

x.y where x is the name used by the LDD and y is PDD-specific. </p> <p id="GUID-4F7A9727-7DCC-5FA2-A88D-38646EF9EA26"><b>Implementing GetCaps()</b> </p> <p>This

function is called as a result of a user-side request to <xref href="GUID-92BAC78E-8ACF-3952-8E77-CCF93ED3BDC9.dita#GUID-92BAC78E-8ACF-3952-8E77-CCF93ED3BDC9/GUID-9C38652A-0135-360D-A54F-A9542C45E608"><apiname>RDevice::GetCaps()</apiname></xref>. </p> <p>The

function should fill the descriptor passed in by reference with device specific

capabilities. </p> <p>Be aware that capabilities in this context refer to

the services that the driver can offer. <b>DO NOT CONFUSE</b> this with the

idea of security capabilities, which is completely different (see <xref href="GUID-C8615948-0CCB-5C4C-BB74-FA66D7028788.dita">Platform

Security Issues</xref>). </p> <p>The device driver framework does not define

how a device's capabilities are encoded. Any encoding scheme must follow a

convention that is understood by the user side caller of <codeph>GetCaps()</codeph>.

A common convention is simply to return the version of the LDD on the grounds

that capabilities correlate with the version. </p> <p>This is the <codeph>GetCaps()</codeph> function

from the example driver's LDD factory class: </p> <codeblock id="GUID-4CB5671A-DFEC-5892-8500-7637252A0897" xml:space="preserve">void DDriver1Factory::GetCaps(TDes8&amp; aDes) const

    {

    // Create a capabilities object

    RDriver1::TCaps caps;

    caps.iVersion = iVersion;

    // Write it back to user memory

    Kern::InfoCopy(aDes,(TUint8*)&caps,sizeof(caps));

    }</codeblock> <codeblock id="GUID-9A8D410E-6EB5-540A-9D05-E0BB0B82679C" xml:space="preserve">class RDriver1 : public RBusLogicalChannel

    {

public:

    class TCaps

        {

    public:

        TVersion iVersion;

        };

    . . .

    }</codeblock> <p id="GUID-4E2880B7-C20D-546F-B57E-43112EE90E1D"><b>Implementing Create()</b> </p> <p>This

is called by the device driver framework to create a logial channel. </p> <p>It

is called in the context of the client user-side thread that requested the

creation of the logical channel. This is a result of a 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

function has the signature: </p> <codeblock id="GUID-9F4C6E51-2F82-5079-825C-147A66A4D818" xml:space="preserve">TInt Create(DLogicalChannelBase*&amp; aChannel);</codeblock> <p>It should create an object of type <xref href="GUID-E7550422-5121-3393-A85E-BB797969CD2A.dita"><apiname>DLogicalChannelBase</apiname></xref>,

and return its pointer through the supplied reference. Depending on the running

model, the object returned can be one derived directly from <xref href="GUID-E7550422-5121-3393-A85E-BB797969CD2A.dita"><apiname>DLogicalChannelBase</apiname></xref>,

or one derived from <xref href="GUID-A3CC1D95-4681-3349-A67C-F113A614041D.dita"><apiname>DLogicalChannel</apiname></xref>. </p> <p>The implementation

is straightforward. This is the <codeph>Create()</codeph> function from the

example driver's LDD factory class: </p> <codeblock id="GUID-5E4E9902-1B80-544B-8864-3C21DDA28A9C" xml:space="preserve">TInt DDriver1Factory::Create(DLogicalChannelBase*&amp; aChannel)

    {

    aChannel=new DDriver1Channel;

    if(!aChannel)

        return KErrNoMemory;

    return KErrNone;

    }</codeblock> <codeblock id="GUID-3E2C16B6-FEE9-5A1C-83B8-DEDC15E6C4E6" xml:space="preserve">class DDriver1Channel : public DLogicalChannel

    {

    . . .

    }</codeblock> <p>In effect, it is a factory function for creating the

logical channel object. Note that you must indicate the sucess or failure

of the operation through the return value. The leave mechanism is not available

in kernel-side code. </p> <fig id="GUID-D5C4BA59-98D2-558C-BB84-EE46289F0C6F">

<image href="GUID-53ADC647-E058-5EA3-A37E-D8B40B858C28_d0e267911_href.png" placement="inline"/>

</fig> </section>

<section id="GUID-EDE0E5D7-AE37-53F5-96BD-B6B9C290899D"><title>Optional changes</title> <p id="GUID-DFBB0D38-EF9A-5FEE-A89B-68E2FC7FFB37"><b>Re-implementing QueryVersionSupported()</b> </p> <p>This

function is called as a result of a user-side request to <xref href="GUID-92BAC78E-8ACF-3952-8E77-CCF93ED3BDC9.dita#GUID-92BAC78E-8ACF-3952-8E77-CCF93ED3BDC9/GUID-846746E4-7C94-3EDA-8B07-D4641147E99A"><apiname>RDevice::QueryVersionSupported()</apiname></xref>. </p> <p>Any

implementation should decide whether this LDD can support the client's requirements,

as represented by the supplied version. </p> <p>The default implementation

just calls <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-A28757CC-B89B-3F63-AD39-9955FBE7533B"><apiname>Kern::QueryVersionSupported()</apiname></xref> and compares the

supplied version information with the version information in this LDD factory

object. </p> <p>It should rarely, if ever, be necessary to change the default

implementation. </p> <p id="GUID-4311EED9-F15A-5E80-8C0E-79369426BE65"><b>Re-implementing IsAvailable()</b> </p> <p>This

function is called as a result of a user-side request to <xref href="GUID-92BAC78E-8ACF-3952-8E77-CCF93ED3BDC9.dita#GUID-92BAC78E-8ACF-3952-8E77-CCF93ED3BDC9/GUID-6DD17652-06E3-3FD4-A2E8-2782B0BBCFF1"><apiname>RDevice::IsAvailable()</apiname></xref>. </p> <p>An

implementation should decide whether the combinmation of: specified unit,

the additional information, and the name of the PDD, is supported by the driver,

and return true or false as appropriate. The default implementation always

returns true. </p> </section>