1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

    12 <concept id="GUID-1138D29D-2EC5-59DF-9AA7-2D863FBC024F" xml:lang="en"><title>Factory

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

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

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

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

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

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

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

    20 shared between the two channels. </p>

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

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

    23     {

    24 public:

    25     DTemplateSoundScPddFactory();

    26     ~DTemplateSoundScPddFactory();

    27     virtual TInt Install();

    28     virtual void GetCaps(TDes8& aDes) const;

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

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

    31 private:

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

    33     TDynamicDfcQue* iDfcQ;

    34     friend class DTemplateSoundScTxPdd;

    35     friend class DTemplateSoundScRxPdd; 

    36     };</codeblock>

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

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

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

    40 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>.

    41 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>.

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

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

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

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

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

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

    48 no modification: </p>

    49 <ul>

    50 <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>

    51 <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>

    52 <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>

    53 <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>

    54 </ul>

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

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

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

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

    59 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

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

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

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

    63 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");

    64 

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

    66 _LIT(KSoundScDriverThreadName,"SoundDriverThread");

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

    68 

    69 TInt DTemplateSoundScPddFactory::Install()

    70 {

    71     TInt r=KErrNone;

    72     if (iDfcQ==NULL)

    73         {

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

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

    76         }

    77     

    78     if (r==KErrNone)

    79         {

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

    81         }

    82     return(r);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   103                                         TInt aUnit,

   104                                         const TDesC8* /*anInfo*/, 

   105                                         const TVersion& /*aVer*/)

   106     {

   107     // Create the appropriate PDD channel object.

   108     TInt r=KErrNoMemory;

   109     if (aUnit==KSoundScRxUnit0)

   110         {

   111         // Create a record PDD channel object

   112         DTemplateSoundScRxPdd* pD=new DTemplateSoundScRxPdd;

   113         aChannel=pD;

   114         if (pD)

   115             {

   116             pD->iPhysicalDevice=this;

   117             r=pD->DoCreate();

   118             }

   119         }

   120        else

   121         {

   122         // Create a playback PDD channel object

   123         DTemplateSoundScTxPdd* pD=new DTemplateSoundScTxPdd;

   124         aChannel=pD;

   125         if (pD)

   126             {

   127             pD->iPhysicalDevice=this;

   128             r=pD->DoCreate();

   129             }

   130         }

   131     return(r);

   132     } </codeblock> </section>

   133 </conbody></concept>