<?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-1138D29D-2EC5-59DF-9AA7-2D863FBC024F" xml:lang="en"><title>Factory

Implementation</title><shortdesc>Describes how to implement a factory. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>The Sound Driver PDD must provide a factory class to create channels. All

PDD factory classes are derived from <xref href="GUID-A5484A7F-94B9-34C7-9F88-82B1BF516930.dita"><apiname>DPhysicalDevice</apiname></xref>. The

template PDD factory class <xref href="GUID-CA70CE3A-ACD8-39C7-8F27-D73EA9E6C2E1.dita"><apiname>TemplateSoundScPddFactory</apiname></xref> creates

the appropriate PDD object when a driver channel is opened on the device.

As well as the configurations supporting both record and playback, this class

implements control of those aspects of the audio hardware device that are

shared between the two channels. </p>

<p> <xref href="GUID-8720456A-173A-3801-BECB-736ABFA7912A.dita"><apiname>DTemplateSoundScPddFactory</apiname></xref> is defined as: </p>

<codeblock id="GUID-A66766B6-6953-59AC-9520-A686A8216E0F" xml:space="preserve">class DTemplateSoundScPddFactory : public DPhysicalDevice

    {

public:

    DTemplateSoundScPddFactory();

    ~DTemplateSoundScPddFactory();

    virtual TInt Install();

    virtual void GetCaps(TDes8& aDes) const;

    virtual TInt Create(DBase*& aChannel, TInt aUnit, const TDesC8* aInfo, const TVersion& aVer);

    virtual TInt Validate(TInt aUnit, const TDesC8* aInfo, const TVersion& aVer);

private:

    /** The DFC queue (used also by the LDD). */ 

    TDynamicDfcQue* iDfcQ;

    friend class DTemplateSoundScTxPdd;

    friend class DTemplateSoundScRxPdd; 

    };</codeblock>

<p>The PDD factory class provided by the template Sound Driver creates a new

DFC queue and associated kernel thread, <codeph>iDfcQ</codeph>, for exclusive

use by this pair of Sound Driver channels. This is created within the second

stage constructor function <xref href="GUID-1138D29D-2EC5-59DF-9AA7-2D863FBC024F.dita#GUID-1138D29D-2EC5-59DF-9AA7-2D863FBC024F/GUID-48FD1134-253A-56E6-8152-C95260E4CB21">Install()</xref>.

A pointer to the DFC queue is returned by the PDD function <xref href="GUID-71190437-912E-3E23-8E68-4FA8FF913D7A.dita"><apiname>DfcQ()</apiname></xref>.

See the <xref href="GUID-AC560324-798C-5D0A-B23D-2419A7688A5B.dita#GUID-AC560324-798C-5D0A-B23D-2419A7688A5B/GUID-61725EEB-5114-5A85-9C28-57A47F14000C">PDD

class constructor</xref> section. </p>

<p>The class <xref href="GUID-8720456A-173A-3801-BECB-736ABFA7912A.dita"><apiname>DTemplateSoundScPddFactory</apiname></xref> contains four virtual

functions, including the constructor, that must be implemented by the PDD

for both driver channels. The template Sound Driver contains default implementations

together with a constructor and destructor and, typically, need little or

no modification: </p>

<ul>

<li id="GUID-896078FE-06EF-5AAC-ABDD-4B8AC7B0B72C"><p> <xref href="GUID-1138D29D-2EC5-59DF-9AA7-2D863FBC024F.dita#GUID-1138D29D-2EC5-59DF-9AA7-2D863FBC024F/GUID-CE921DE4-77A2-580F-8415-749DBA2782B8">DTemplateSoundScPddFactory constructor</xref>  </p> </li>

<li id="GUID-A3959AB1-9B25-5892-ADDE-4C79995A611B"><p> <xref href="GUID-1138D29D-2EC5-59DF-9AA7-2D863FBC024F.dita#GUID-1138D29D-2EC5-59DF-9AA7-2D863FBC024F/GUID-48FD1134-253A-56E6-8152-C95260E4CB21">Install()</xref> </p> </li>

<li id="GUID-2D388367-517C-526A-B385-DE86FBB59A5E"><p> <xref href="GUID-1138D29D-2EC5-59DF-9AA7-2D863FBC024F.dita#GUID-1138D29D-2EC5-59DF-9AA7-2D863FBC024F/GUID-FFDCBC89-FC11-57AA-A43E-689355B48E5A">Validate()</xref> </p> </li>

<li id="GUID-06C058F0-5CE7-56F6-A34C-C1CAF67D1E95"><p> <xref href="GUID-1138D29D-2EC5-59DF-9AA7-2D863FBC024F.dita#GUID-1138D29D-2EC5-59DF-9AA7-2D863FBC024F/GUID-B28B533E-1630-52F6-9589-F71E3FAFEBBB">Create()</xref>  </p> </li>

</ul>

<section id="GUID-CE921DE4-77A2-580F-8415-749DBA2782B8"><title>DTemplateSoundScPddFactory

constructor</title> <p>Ensure that the inherited data member <codeph>iUnitsMask</codeph> is

setup correctly according to the unit numbers to be supported. The default

version enables the PDD to open both the first playback driver channel number <codeph>KSoundScTxUnit0</codeph> and

the first record driver channel number <codeph>KSoundScRxUnit0</codeph>: </p> <codeblock id="GUID-F294EA90-83AD-557C-8EC7-675062FB768C" xml:space="preserve">// Support units KSoundScTxUnit0 &amp; KSoundScRxUnit0

iUnitsMask=(1&lt;&lt;KSoundScRxUnit0)|(1&lt;&lt;KSoundScTxUnit0);</codeblock> </section>

<section id="GUID-48FD1134-253A-56E6-8152-C95260E4CB21"><title>Install()</title> <p>This

is the second stage constructor for the PDD factory class. The template version

creates the DFC queue and sets the driver name. </p> <codeblock id="GUID-1A94099F-B0AB-55D4-9D43-E63E7C92482E" xml:space="preserve">_LIT(KSoundScPddName,"SoundSc.Template");

// Definitions for the kernel thread created for this sound driver.

_LIT(KSoundScDriverThreadName,"SoundDriverThread");

const TInt KSoundScDriverThreadPriority=26; // One less than DFC thread 0

TInt DTemplateSoundScPddFactory::Install()

{

    TInt r=KErrNone;

    if (iDfcQ==NULL)

        {

        // Create a new sound driver DFC queue (and associated kernel thread). 

        r=Kern::DynamicDfcQCreate(iDfcQ, KSoundScDriverThreadPriority, KSoundScDriverThreadName);

        }

    if (r==KErrNone)

        {

        r=SetName(&KSoundScPddName); // Set the name of the driver object

        }

    return(r);

    }</codeblock> <p>The physical device is identified by the driver name,

alter this to reflect your device. The driver name is the same as the LDD

name, but followed by a dot and a short string to represent the physical device.

For example, the name used for template is "<codeph>SoundSc.Template</codeph> ". </p> </section>

<section id="GUID-FFDCBC89-FC11-57AA-A43E-689355B48E5A"><title>Validate()</title> <p>This

function is called by the kernel device driver framework to see whether this

PDD is suitable for use with a particular driver channel. Ensure that the

unit number checking code is correct for the unit numbers that are to be supported.

The default version enables the PDD to open both the first playback driver

channel number <codeph>KSoundScTxUnit0</codeph> and the first record driver

channel number <codeph>KSoundScRxUnit0</codeph>. </p> <codeblock id="GUID-21542AAA-48FA-5D9E-A1EA-5F8363F3FE84" xml:space="preserve">// Check the unit number is compatible

if (aUnit!=KSoundScTxUnit0 && aUnit!=KSoundScRxUnit0)

    return(KErrNotSupported);</codeblock> </section>

<section id="GUID-B28B533E-1630-52F6-9589-F71E3FAFEBBB"><title>Create()</title> <p>This

function is called by the kernel device driver framework to create a PDD object.

Ensure that the unit number checking code is correct for the unit numbers

that are to be supported. For configurations supporting both playback and

record, it must be capable of creating either a playback or record PDD object

according to the channel number specified. The template version is implemented

as follows: </p> <codeblock id="GUID-B1625466-4560-56C2-A7BF-8700FFAEAAD8" xml:space="preserve">TInt DTemplateSoundScPddFactory::Create(DBase*&amp; aChannel, 

                                        TInt aUnit,

                                        const TDesC8* /*anInfo*/, 

                                        const TVersion& /*aVer*/)

    {

    // Create the appropriate PDD channel object.

    TInt r=KErrNoMemory;

    if (aUnit==KSoundScRxUnit0)

        {

        // Create a record PDD channel object

        DTemplateSoundScRxPdd* pD=new DTemplateSoundScRxPdd;

        aChannel=pD;

        if (pD)

            {

            pD->iPhysicalDevice=this;

            r=pD->DoCreate();

            }

        }

       else

        {

        // Create a playback PDD channel object

        DTemplateSoundScTxPdd* pD=new DTemplateSoundScTxPdd;

        aChannel=pD;

        if (pD)

            {

            pD->iPhysicalDevice=this;

            r=pD->DoCreate();

            }

        }

    return(r);

    } </codeblock> </section>