<?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-6DE69F29-45B0-5E62-AA13-DA4041B1BC46" xml:lang="en"><title>Factory
Implementation</title><shortdesc>Describes how to implement a factory.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>The Serial Port Driver PDD must provide a factory class to create channels.
The purpose of the PDD factory is to create the physical channel. For the
Uart, this is defined by the <codeph>DDriverComm</codeph> class, which is
derived from <xref href="GUID-A5484A7F-94B9-34C7-9F88-82B1BF516930.dita"><apiname>DPhysicalDevice</apiname></xref>. The class is defined in the
Uart source code: </p>
<codeblock id="GUID-15ED5794-BC8A-5CF0-BE5D-8620AFDEDEEA" xml:space="preserve">class DDriverComm : public DPhysicalDevice
    {
public:
    DDriverComm();
    virtual TInt Install();
    virtual void GetCaps(TDes8 &amp;aDes) const;
    virtual TInt Create(DBase*&amp; aChannel, TInt aUnit, const TDesC8* anInfo, const TVersion &amp;aVer);
    virtual TInt Validate(TInt aUnit, const TDesC8* anInfo, const TVersion &amp;aVer);
    };
</codeblock>
<p>This implements the four virtual functions that the base class defines,
as well as a default constructor. </p>
<section id="GUID-5A36A559-CBB6-4495-A1ED-0C4F9289F9B0"><title>Install()</title> <p> <codeph>Install()</codeph> sets
the driver name. The name is the way that the physical device is identified.
The name is the same as the LDD name, but followed by a dot and a short string
to represent the physical device. If you have similar existing source, just
copy from there. The function is implemented as: </p> <codeblock id="GUID-6988B583-5060-5CE7-9404-C631C40B188A" xml:space="preserve">TInt DDriverComm::Install()
    {
    return SetName(&amp;KPddName);
    }
</codeblock> <p>In the template port, the name is the string <codeph>Comm.Template</codeph>. </p> <p>See
also <xref href="GUID-A5484A7F-94B9-34C7-9F88-82B1BF516930.dita#GUID-A5484A7F-94B9-34C7-9F88-82B1BF516930/GUID-0065FAAF-D734-3ED2-816A-CCE9BF607BAB"><apiname>DPhysicalDevice::Install()</apiname></xref>  </p> </section>
<section id="GUID-CBFB3280-3C16-4F15-A7DB-EDCA278562F6"><title>GetCaps()</title> <p> <codeph>GetCaps()</codeph> returns
the capabilities of the physical driver <i>factory</i> (not the driver object).
Since driver factories all produce polymorphic objects there is no point in
differentiating between them so the function should ignore the passed in descriptor
reference. The driver object’s capabilities are returned by the <codeph>DComm</codeph> derived <codeph>Caps()</codeph> function. </p> <p>GetCaps()
can be implemented as a stub function, i.e.: </p> <codeblock id="GUID-338ECD13-DD25-55E0-812F-3ED3A49826CD" xml:space="preserve">Void DDriverComm::GetCaps(TDes8&amp;  /* aDes */)
    {
    }</codeblock> <p>See also <xref href="GUID-A5484A7F-94B9-34C7-9F88-82B1BF516930.dita#GUID-A5484A7F-94B9-34C7-9F88-82B1BF516930/GUID-CA336905-B068-3CFB-80D7-4DF29B92BF4F"><apiname>DPhysicalDevice::GetCaps()</apiname></xref>  </p> </section>
<section id="GUID-70BBF195-3943-4ABE-9EFB-FCC2BDAC52DD"><title>Validate()</title> <p> <codeph> Validate()</codeph> verifies
that the physical driver version is compatible with the caller’s version.
This function can be copied in its entirety from any current driver source.
It also checks that the unit number used to create a physical channel object
is valid, typically checking that the number lies within a valid range. </p> <codeblock id="GUID-03DC2E07-FEBF-5F52-B3A5-7F52C855FC06" xml:space="preserve">TInt DDriverComm::Validate(TInt aUnit, const TDesC8* /*anInfo*/, const TVersion&amp; aVer)
    {
    if (
        (!Kern::QueryVersionSupported(iVersion,aVer)) || 
        (!Kern::QueryVersionSupported(aVer,TVersion(KMinimumLddMajorVersion,KMinimumLddMinorVersion,KMinimumLddBuild)))
       )
    return KErrNotSupported;
    if (aUnit&lt;UART_UNIT_OFFSET || aUnit&gt;=(UART_TOTAL_NUMBER_UNITS+UART_UNIT_OFFSET))
        return KErrNotSupported;
    return KErrNone;
    }
</codeblock> <p>Note that <codeph>iVersion</codeph> is a data member in the
base class <xref href="GUID-A5484A7F-94B9-34C7-9F88-82B1BF516930.dita"><apiname>DPhysicalDevice</apiname></xref>. </p> <p>See also: </p> <ul>
<li id="GUID-0EF9F2F1-EC2A-50E3-9E1B-2D6112FE8623"><p> <xref href="GUID-A5484A7F-94B9-34C7-9F88-82B1BF516930.dita#GUID-A5484A7F-94B9-34C7-9F88-82B1BF516930/GUID-70B6293C-9000-31D9-AE9E-441C9760B92E"><apiname>DPhysicalDevice::Validate()</apiname></xref>  </p> </li>
<li id="GUID-4ED7473E-D789-5813-9404-0F6BDCB83D3F"><p> <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>  </p> </li>
</ul> </section>
<section id="GUID-48EF94F9-ACBC-58DA-9F0E-4034E56C6C74"><title>Create()</title> <p> <codeph>Create()</codeph> creates
and returns a pointer to the physical channel object through the <xref href="GUID-4FCB6127-84F3-38F6-8AD2-FC3B94D67DA3.dita"><apiname>DBase</apiname></xref> *&amp;
type argument. In the case of serial device drivers, a physical channel is
an instance of a class derived from <codeph>DComm</codeph>, which is itself
derived from <xref href="GUID-4FCB6127-84F3-38F6-8AD2-FC3B94D67DA3.dita"><apiname>DBase</apiname></xref>. </p> <p>Implementing this function
may involve: </p> <ul>
<li id="GUID-D6D5111E-22E1-5EA2-B217-EAC3BA5B9599"><p>setting up any port
related hardware; for example, defining GPIO pins as UART port I/O </p> </li>
<li id="GUID-6769D49B-478C-5282-A918-6D659F823B95"><p>initialising the UART
device itself; for example, enabling UART clock sources </p> </li>
<li id="GUID-BFEC3036-6F9C-5499-81AF-7A5D01BDD890"><p>binding any interrupt
resources to the UART Interrupt Service Routine (ISR). </p> </li>
</ul> <p>The function sets a reference argument to point to the newly instantiated
physical channel object, but returns an error code if object allocation or
initialisation fails, i.e. the call to the physical channel object’s <codeph>DoCreate()</codeph> function
fails. Error codes are returned to the caller. </p> <p>This code is typical,
and can be copied from any current source. </p> <codeblock id="GUID-E93C6DEA-852D-5B5F-8531-CA4B76B91879" xml:space="preserve">TInt DDriverComm::Create(DBase*&amp; aChannel, TInt aUnit, const TDesC8* anInfo, const TVersion&amp; aVer)
    {
    DCommXXX* pD=new DCommXXX;
    aChannel=pD;
    TInt r=KErrNoMemory;
    if (pD)
        r=pD-&gt;DoCreate(aUnit,anInfo);
    return r;
    }
</codeblock> <p>where <codeph>DCommXXX</codeph> is a <codeph>DComm</codeph> derived
class. </p> <p>Customisation depends on the functions in the <codeph>DCommXXX::DoCreate()</codeph> function. </p> </section>
</conbody><related-links>
<link href="GUID-3C34724F-B476-5329-B0B1-6D5A34294979.dita"><linktext>Interrupt
Dispatcher Tutorial</linktext></link>
</related-links></concept>