<?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-A7ECF51F-F96A-5251-A71F-2F269C8C0664" xml:lang="en"><title>Accessor

Functions for Derived Attributes</title><shortdesc>Explains how to add accessor functions for derived attributes.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>You can change HAL to add accessor functions for new derived attributes.

This step is not often done, because all normal accessor functions are already

defined in <filepath>...\hal\src\userhal.cpp</filepath>. </p>

<p>Each derived attribute is declared with an associated function name in <xref href="GUID-52583CC7-483E-54B5-8094-F0F61BD46B7F.dita#GUID-52583CC7-483E-54B5-8094-F0F61BD46B7F/GUID-8648B87A-B712-5458-850A-FDF318669FE3">Config

file</xref>. A function with that name must be provided, and it must have

the following signature, which is also defined by the <xref href="GUID-0885487F-1482-3BD4-9EA8-9E9643125A0A.dita"><apiname>THalImplementation</apiname></xref> typedef: </p>

<codeblock id="GUID-53946166-A153-57E1-8FAB-BB3870B0B829" xml:space="preserve">TInt Function(TInt aAttrib, TBool aSet, TAny* aInOut);</codeblock>

<p>This function is called whenever any client of the HAL references the associated

attribute. </p>

<table id="GUID-2672A463-7AB1-504E-9D0C-2AA29757178A">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<tbody>

<row>

<entry><p> <codeph>aAttrib</codeph>  </p> </entry>

<entry><p>Contains the attribute number. </p> </entry>

</row>

<row>

<entry><p> <codeph>aSet</codeph>  </p> </entry>

<entry><p>Defines whether the attribute is being set or being read: <xref href="GUID-781E8158-805B-3784-8FED-D7A191822FC3.dita"><apiname>ETrue</apiname></xref> means

that the attribute value is being set; <xref href="GUID-A759CA2D-8327-348F-9337-4886E619D920.dita"><apiname>EFalse</apiname></xref> means that

the attribute value is being read. </p> <p>Note that if the attribute, as

defined in the <filepath>config.hcf</filepath> file, does not have the settable

property, then <codeph>aSet</codeph> is ignored . </p> </entry>

</row>

<row>

<entry><p> <codeph>aInOut</codeph>  </p> </entry>

<entry><p>A pointer to a <xref href="GUID-7A2A43EC-6125-3BFE-834B-23C37F7B40D5.dita"><apiname>TInt</apiname></xref> type, that contains: </p> <ul>

<li id="GUID-B7598EEB-4B73-5E51-8F92-EC527FCED605"><p>the attribute value

to be set, if <codeph>aSet</codeph> is <xref href="GUID-781E8158-805B-3784-8FED-D7A191822FC3.dita"><apiname>ETrue</apiname></xref>  </p> </li>

<li id="GUID-BEA21EED-2D95-5169-B09C-DD6CC7CE4507"><p>the attribute value

to be read, if <codeph>aSet</codeph> is <xref href="GUID-A759CA2D-8327-348F-9337-4886E619D920.dita"><apiname>EFalse</apiname></xref>. </p> </li>

</ul> </entry>

</row>

</tbody>

</tgroup>

</table>

<p>Once the config file has been written, the Perl script <filepath>...\hal\group\halcfg.pl</filepath> can

be used to generate a skeleton implementation file. For example, calling </p>

<p><userinput>perl \hal\group\halcfg.pl -s \hal\inc\hal_data.h config.hcf

imp.cpp</userinput> </p>

<p>produces the file <filepath>imp.cpp</filepath> containing the following

skeleton code for <i>each</i> derived attribute: </p>

<codeblock id="GUID-EAA857F6-61FB-5FAE-815E-9B3601CF182C" xml:space="preserve">// EAttributeName

TInt Function(TInt /*aAttrib*/, TBool /*aSet*/, TAny* aInOut)

    {

    return KErrNone;

    }

</codeblock>

<p>The full implementation for the function can now be written. </p>

<p>Notes: </p>

<ul>

<li id="GUID-25545667-6870-5AAF-9271-D7402E9F777E"><p>The <codeph>aAttrib</codeph> parameter

is always marked as a comment because it is not usually needed; it is only

needed if the same function is used to implement more than one attribute. </p> </li>

<li id="GUID-8DE7C359-AA59-5158-82BD-2184D874168C"><p>The <codeph>aSet</codeph> parameter

is marked as a comment if the attribute does not have the <i>settable</i> property. </p> </li>

<li id="GUID-27CE60FA-8104-511C-9FC2-3D4557D92BBC"><p>On some platforms it

may be necessary to access some HAL attributes via a device driver or server,

rather than using <codeph>UserSvr::HalFunction()</codeph> . In this case,

a handle to the device driver or server must be opened on the first access.

Use the <codeph>HalInternal::Tls()</codeph> function to do this. </p> </li>

<li id="GUID-72462FB8-F607-56D8-9F0B-FD9980FDCEBD"><p>Access to any HAL attribute

requiring the use of a server or device driver can fail due to lack of memory. </p> </li>

</ul>

<p>Thee code fragments in the <xref href="GUID-A7ECF51F-F96A-5251-A71F-2F269C8C0664.dita#GUID-A7ECF51F-F96A-5251-A71F-2F269C8C0664/GUID-61707920-B82E-5580-8821-4FD1DC3BE77A">example

accessor functions</xref> show the cases where the HAL has an attribute that

requires a device driver and another attribute that requires a server. </p>

<p>See also <xref href="GUID-F8B8C030-B5E1-5EB3-A672-83BF35555801.dita">halcfg.pl

Syntax</xref>. </p>

<section id="GUID-61707920-B82E-5580-8821-4FD1DC3BE77A"><title>Example accessor

functions for derived attributes using a device driver and a server</title> <p>This

code fragment shows the implementation of accessor functions for two HAL derived

attributes. One uses a device driver, and the other uses a server to provide

the necessary functionality. </p> <p>The examples assume that the attributes

are defined in the <filepath>config.hcf</filepath> file with function names <codeph>Attrib1</codeph> and <codeph>Attrib2</codeph>. </p> <p><b>Using a device driver</b> </p> <codeblock id="GUID-810DF0E3-4AE7-5FFC-8434-A845513BCC65" xml:space="preserve">TInt Attrib1(TInt /*aAttrib*/, TBool aSet, TAny* aInOut)

    {

       // Do something with the device driver

       RHwDevice d;

       TInt r=GetDeviceDriverHandle(d);

       if (r==KErrNone)

        {

        if (aSet)

            {

            r=d.Write((TInt)aInOut);

            }

        else

            {

            r=d.Read(*(TInt*)aInOut);

            }

         }

    return r;

    }</codeblock> <codeblock id="GUID-88E9FA83-D669-5073-B92A-48A22BFEC4B2" xml:space="preserve">TInt GetDeviceDriverHandle(RHwDevice&amp; aDevice)

    {

    // Return the device driver handle for this thread

    // If it doesn't exist, attempt to open a handle

    // Careful with OOM errors

    SHandles* pH=GetHandles();

    if (!pH)

        {

        return KErrNoMemory;    // couldn't allocate TLS memory

        }

    if (pH->iDevHandle)

        {

        // device driver handle already open

        aDevice.SetHandle(pH->iDevHandle);

        return KErrNone;

        }

    // note: Someone should have previously loaded the required

    // device driver.  Eg.

    // User::LoadLogicalDevice(_L("HARDWARE.LDD"));

    // This can be done here, but it is inefficient since it will

    // happen once per thread.  It's much better to do it once

    // at Hal start-up.

    TInt r=aDevice.Open();    // open handle to driver

    if (r==KErrNone)

        {

           pH->iDevHandle=aDevice.Handle();    // store handle

        }

    return r;

    }</codeblock> <codeblock id="GUID-264AF5EC-A4F3-5BA7-AC47-576C338D81F2" xml:space="preserve">struct SHandles

    {

    TInt iDevHandle;

    TInt iSvrHandle;

    };

</codeblock> <codeblock id="GUID-7F5DC241-B4B1-501F-A7B6-0B864676A4A2" xml:space="preserve">SHandles* GetHandles()

    {

    // Return a pointer to the SHandles structure for this thread

    // If it doesn't exist, attempt to create it

    // This function zeros a newly allocated memory block

    return (SHandles*)HalInternal::Tls(sizeof(SHandles));

    }

</codeblock> <p><b>Using

a server</b> </p> <codeblock id="GUID-E0CB12CC-2F83-5AB6-B1F3-B494AD7346CB" xml:space="preserve">TInt Attrib2(TInt /*aAttrib*/, TBool aSet, TAny* aInOut)

    {

    // Do something with the server

    RHwServer s;

    TInt r=GetServerHandle(s);

    if (r==KErrNone)

        {

        if (aSet)

            {

            r=s.Write((TInt)aInOut);

            }

            else

            {

            r=s.Read(*(TInt*)aInOut);

            }

        }

    return r;

    }</codeblock> <codeblock id="GUID-C74F36A5-78CA-52A6-A8E9-6BEAAC7B9257" xml:space="preserve">TInt GetServerHandle(RHwServer&amp; aServer)

    {

    // Return the server handle for this thread

    // If it doesn't exist, attempt to open a handle

    // Careful with OOM errors

    SHandles* pH=GetHandles();

    if (!pH)

        {

        return KErrNoMemory;    // couldn't allocate TLS memory

        }

    if (pH->iSvrHandle)

        {

        // server handle already open

           aServer.SetHandle(pH->iSvrHandle);

           return KErrNone;

        }

    TInt r=aServer.Connect();    // create session with server

    if (r==KErrNone)

        {

        pH->iSvrHandle=aServer.Handle();    // store handle

        }

    return r;

    }</codeblock> <codeblock id="GUID-9527E73D-FAFA-519A-80F1-FD10E5AF3D40" xml:space="preserve">struct SHandles

    {

    TInt iDevHandle;

    TInt iSvrHandle;

    };

</codeblock> <codeblock id="GUID-6C88ED9C-E8D1-5901-BE00-F52130F3509C" xml:space="preserve">SHandles* GetHandles()

    {

    // Return a pointer to the SHandles structure for this thread

    // If it doesn't exist, attempt to create it

    // This function zeros a newly allocated memory block

    return (SHandles*)HalInternal::Tls(sizeof(SHandles));

    }

</codeblock> </section>