<?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-DA382265-232F-40F4-92ED-C90E6DE3D709" xml:lang="en"><title>Version</title><shortdesc>This document describes how to set the interface version used by

an LDD or a PDD and how to check version compatibility.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>An LDD and a PDD each have a version number which helps to identify the

interface. In order to communicate, an LDD and a PDD must have the same version

number.</p>

<section id="GUID-A0AC274C-E530-44C4-A955-582E294C3986">       <title>Version

definition</title>       <p>Each LDD and PDD has their own version number.

LDDs and PDDs must set their version numbers in their respective factory objects,

using a <xref href="GUID-D82DEC7A-71C2-3004-BFC2-C82C009A2715.dita"><apiname>TVersion</apiname></xref> object. <codeph>TVersion</codeph> specifies

a major number, a minor number and a build number. </p> <p>A version number

defines the interface version supported by the LDD or PDD. It is used to check

that an LDD and PDD are compatible. It is also checked against the version

requested by a client when it opens a channel. </p> <p>The following shows

how the example device drivers set their version numbers: </p> <codeblock id="GUID-0346530F-4560-5132-BD78-625C55F69840" xml:space="preserve">inline TVersion RExDriverChannel::VersionRequired()

    {    

    return (TVersion(EUartMajorVersionNumber,

            EUartMinorVersionNumber,

            EUartBuildVersionNumber));

    }</codeblock> <codeblock id="GUID-C89697A9-B8D3-5BAC-8020-429483C5D492" xml:space="preserve">// LDD Factory object Constructor

DExDriverLogicalDevice::DExDriverLogicalDevice ()

    {

    iVersion = RExDriverChannel::VersionRequired();

    }</codeblock> <codeblock id="GUID-728B933E-6F42-599A-8C63-9C572EB6C54E" xml:space="preserve">// PDD Factory object Constructor

DExH4PhysicalDevice::DExH4PhysicalDevice ()

    {        

    iVersion= RExDriverChannel::VersionRequired();

    }</codeblock>     </section>

<section id="GUID-7778CFE6-EFFC-45FD-A1CD-92EE21A35C14"><title>Version compatibility</title> <p>The

Kernel provides the <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> API to

enforce a consistent set of rules for checking version compatibility. It returns

true if one of the following conditions is true: </p> <ul>

<li id="GUID-5DE6B5DA-2823-546D-BB2D-0556D3AEEC52"><p>the major version of

the client is less than the major version of the driver. </p> </li>

<li id="GUID-54E77028-897E-53BE-BEAB-72ECD796EF63"><p>the major version of

the client is equal to the major version of the driver, and the minor version

of the client is less than or equal to the minor version of the driver. </p> </li>

</ul> <p> <xref href="GUID-A3CC1D95-4681-3349-A67C-F113A614041D.dita#GUID-A3CC1D95-4681-3349-A67C-F113A614041D/GUID-3DE558DF-16A3-39F9-87E3-F5600899A4D4"><apiname>DLogicalChannel::DoCreate()</apiname></xref> typically checks

the client version against the driver using this API. </p> <codeblock id="GUID-2E1A3DC4-5A28-5CB7-A983-BDE461E4A861" xml:space="preserve">// Logical Channel Second stage constructor

TInt DExDriverLogicalChannel::DoCreate(TInt /*aUnit*/, const TDesC8* 

/*anInfo*/, const TVersion& aVer)

    {

    ...

    // Version check

    if(!Kern::QueryVersionSupported(RExDriver::VersionRequired(),

aVer))

    return KErrNotSupported;

    ...

    }</codeblock> <p>When the device framework searches for a corresponding

PDD factory object for an LDD, it calls <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> on

each matching PDD factory object, passing the unit number and the optional

extra information block. The first PDD to return <codeph>KErrNone</codeph> is

accepted as the required PDD. </p> <p>The example PDD's <codeph>Validate()</codeph> implementation

checks the version of the LDD against the PDD, using the <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> API: </p> <codeblock id="GUID-56F482C2-B312-58B6-8454-262A774A1B53" xml:space="preserve">// PDD: Validate

TInt DExH4PhysicalDevice::Validate(TInt aUnit, const TDesC8* 

/*aInfo*/, const TVersion& aVer)    

    {

    ...

    // Version check

    if (!Kern::QueryVersionSupported(iVersion,aVer))    

        return KErrNotSupported;

    ...

    }</codeblock></section>