<?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-C57086D7-7672-4A52-8634-D28B37AC6290" xml:lang="en"><title>TSDIOFunction

Class Tutorial</title><shortdesc>Describes the TSDIOFunction API Class.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-9F2D54BC-A431-4FB0-BA25-740229443A4D"><title>Description</title><p>The <xref href="GUID-1342EC36-363F-3E7D-9B5F-4AFD3BAC98C8.dita"><apiname>TSDIOFunction</apiname></xref> class

provides access to functionality common to all SDIO functions. It may be used

as a base class for particular functions such as UART.</p><table id="GUID-9BD7FCBC-1B44-4E95-BEDD-6FA72435466A">

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

<tbody>

<row>

<entry><p>Header file</p></entry>

<entry><p><filepath>function.h</filepath></p></entry>

</row>

<row>

<entry><p>Source code file</p></entry>

<entry><p><filepath>function.cpp</filepath></p></entry>

</row>

<row>

<entry><p>Required libraries</p></entry>

<entry><p>EPBUSSDIO</p></entry>

</row>

<row>

<entry><p>Class declaration</p></entry>

<entry><p><codeph>class TSDIOFunction</codeph></p></entry>

</row>

</tbody>

</tgroup>

</table></section>

<section id="GUID-DBB544CC-A118-4954-A1BF-EED915A0D69E-GENID-1-2-1-10-1-5-1-9-1-1-7-1-4-1-10-1-3-2"><title>Enable()</title><p>The

function declaration for the <xref href="GUID-1B8F9258-D611-39DC-B0A7-8BB634915752.dita"><apiname>Enable()</apiname></xref> method is:</p><codeblock xml:space="preserve">IMPORT_C TInt Enable(TBool aPollReady = ETrue);</codeblock><p><b>Description</b></p><p>Enables the function by writing to the appropriate

register in the CCCR.</p><p><b>Parameters</b></p><p><table id="GUID-089FA8D7-150A-4D56-9629-034C5A1176E7">

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

<tbody>

<row>

<entry><p><codeph>TBool aPollReady</codeph></p></entry>

<entry>If <codeph>aPollReady == ETrue</codeph>, then the  function shall attempt

to enable the function, then poll for the recommended enable period until

the function is enabled, or times out.  Otherwise, flow returns control to

the calling function who should be responsible for polling the IO_READY bit

(using <codeph>TSDIOFunction::IsReady</codeph>)</entry>

</row>

</tbody>

</tgroup>

</table></p><p><b>Return value</b></p><p><codeph>KErrNone</codeph> if successful,

otherwise a standard Symbian platform error code.</p></section>

<section id="GUID-DBB544CC-A118-4954-A1BF-EED915A0D69E-GENID-1-2-1-10-1-5-1-9-1-1-7-1-4-1-10-1-3-3"><title>Disable()</title><p>The

function declaration for the <codeph>Disable()</codeph> method is:</p><codeblock xml:space="preserve">IMPORT_C TInt Disable();</codeblock><p><b>Description</b></p><p>Disables

the function by writing to the appropriate register in the CCCR.</p><p><b>Parameters</b></p><p>None</p><p><b>Return

value</b></p><p><codeph>KErrNone</codeph> if successful, otherwise a standard

Symbian platform error code.</p></section>

<section id="GUID-DBB544CC-A118-4954-A1BF-EED915A0D69E-GENID-1-2-1-10-1-5-1-9-1-1-7-1-4-1-10-1-3-4"><title>IsReady()</title><p>The

function declaration for the <xref href="GUID-3ADC7E12-92D2-3BC2-86AC-F11549D171F2.dita"><apiname>IsReady()</apiname></xref> method is:</p><codeblock xml:space="preserve">IMPORT_C TInt IsReady(TBool&amp; aIsReady);</codeblock><p><b>Description</b></p><p>Disables the function by writing to the appropriate register in the

CCCR.</p><p><b>Parameters</b></p><p><table id="GUID-A9A28DB1-1BAB-4D62-A35B-3B428EDA2855">

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

<tbody>

<row>

<entry><p><codeph>TBool&amp; aIsReady</codeph></p></entry>

<entry>Returns the current state of the function.</entry>

</row>

</tbody>

</tgroup>

</table></p><p><b>Return value</b></p><p><codeph>KErrNone</codeph> if successful,

otherwise a standard Symbian platform error code.</p></section>

<section id="GUID-DBB544CC-A118-4954-A1BF-EED915A0D69E-GENID-1-2-1-10-1-5-1-9-1-1-7-1-4-1-10-1-3-5"><title>RegisterClient()</title><p>The

function declaration for the <xref href="GUID-DDAB5214-FCA7-31FC-AE05-EC615D3033A3.dita"><apiname>RegisterClient()</apiname></xref> method is:</p><codeblock xml:space="preserve">IMPORT_C TInt RegisterClient(DBase* aHandle, DMutex* aMutexLockP = NULL);</codeblock><p><b>Description</b></p><p>Registers the client with the function.</p><p><b>Parameters</b></p><p><table id="GUID-A641F0CF-B691-48D8-9CC5-D5549D2AA8AC">

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

<tbody>

<row>

<entry><p><codeph>DBase* aHandle</codeph></p></entry>

<entry>The unique Client ID</entry>

</row>

<row>

<entry><p><codeph>DMutex* aMutexLockP</codeph></p></entry>

<entry>The client's data access mutex which locks access to the register interface.

Use of the mutex is optional and the parameter is initialized to NULL.</entry>

</row>

</tbody>

</tgroup>

</table></p><p><b>Return value</b></p><p><codeph>KErrNone</codeph> if successful,

otherwise a standard Symbian platform error code.</p></section>

<section id="GUID-DBB544CC-A118-4954-A1BF-EED915A0D69E-GENID-1-2-1-10-1-5-1-9-1-1-7-1-4-1-10-1-3-6"><title>DeregisterClient()</title><p>The

function declaration for the <xref href="GUID-26EF04A7-86EA-3BB0-89A6-BAB007DF6789.dita"><apiname>DeregisterClient()</apiname></xref> method

is:</p><codeblock xml:space="preserve">IMPORT_C TInt DeregisterClient(DBase* aHandle);</codeblock><p><b>Description</b></p><p>Deregisters

the client from the function.</p><p><b>Parameters</b></p><p><table id="GUID-5A5C241A-CF86-4322-9393-554D9E14D866">

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

<tbody>

<row>

<entry><p><codeph>DBase* aHandle</codeph></p></entry>

<entry>The unique Client ID.</entry>

</row>

</tbody>

</tgroup>

</table></p><p><b>Return value</b></p><p><codeph>KErrNone</codeph> if successful,

otherwise a standard Symbian platform error code.</p></section>

<section id="GUID-DBB544CC-A118-4954-A1BF-EED915A0D69E-GENID-1-2-1-10-1-5-1-9-1-1-7-1-4-1-10-1-3-7"><title>SetPriority()</title><p>The

function declaration for the <xref href="GUID-A2BDF5F7-06F0-3788-905E-D53FC9C67446.dita"><apiname>SetPriority()</apiname></xref> method is:</p><codeblock xml:space="preserve">IMPORT_C TInt SetPriority(TSDIOFunctionPriority aPriority);</codeblock><p><b>Description</b></p><p>This sets the priority of accesses to the function.

   It is intended to allow the suspend/resume protocol to determine whether

an access to a lower  priority function should become suspended while a higher

priority function is accessed.  Note that the Suspend/Resume protocol is not

currently implemented, but may be in a future release.</p><p><b>Parameters</b></p><p><table id="GUID-07E6378A-389D-4D47-83D4-24341B2BDE54">

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

<tbody>

<row>

<entry><p><codeph>TSDIOFunctionPriority aPriority</codeph></p></entry>

<entry>The requested function priority.</entry>

</row>

</tbody>

</tgroup>

</table></p><p><b>Return value</b></p><p><codeph>KErrNone</codeph> if successful,

otherwise a standard Symbian platform error code.</p></section>

<section id="GUID-DBB544CC-A118-4954-A1BF-EED915A0D69E-GENID-1-2-1-10-1-5-1-9-1-1-7-1-4-1-10-1-3-8"><title>RegisterInterface()</title><p>The

function declaration for the <xref href="GUID-151B6393-D5BC-3A21-B87C-B88F65816473.dita"><apiname>RegisterInterface()</apiname></xref> method

is:</p><codeblock xml:space="preserve">inline DSDIORegisterInterface* RegisterInterface(DBase* aHandle) const;</codeblock><p><b>Description</b></p><p>Returns

a pointer to an instance of a <xref href="GUID-CC5352E2-DB21-393F-A7A4-108AA3684460.dita"><apiname>DSDIORegInterface</apiname></xref> class that

may be used by a client to talk to the Function Specific Registers.</p><p><b>Parameters</b></p><p><table id="GUID-E2E3AEFE-C385-4022-80A0-4C0091F1273D">

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

<tbody>

<row>

<entry><p><codeph>DBase* aHandle</codeph></p></entry>

<entry>The ID of the client as registered using <xref href="GUID-DDAB5214-FCA7-31FC-AE05-EC615D3033A3.dita"><apiname>RegisterClient()</apiname></xref>.</entry>

</row>

</tbody>

</tgroup>

</table></p><p><b>Return value</b></p><p>A pointer to the <xref href="GUID-6BD11B5F-2269-3317-A40D-6547042CA463.dita"><apiname>DSDIORegisterInterface</apiname></xref> associated

with this function.</p></section>

<section id="GUID-DBB544CC-A118-4954-A1BF-EED915A0D69E-GENID-1-2-1-10-1-5-1-9-1-1-7-1-4-1-10-1-3-9"><title>Interrupt()</title><p>The

function declaration for the <xref href="GUID-95ABF84D-AF13-3B31-A3D2-D099F6C87C64.dita"><apiname>Interrupt()</apiname></xref> method is:</p><codeblock xml:space="preserve">inline TSDIOInterrupt&amp; Interrupt();</codeblock><p><b>Description</b></p><p>Returns a reference to a TSDIOInterrupt class that may be used by

the client to enable the use of interrupts for the function.</p><p><b>Parameters</b></p><p>None</p><p><b>Return

value</b></p><p>A reference to the interrupt class associated with this function.</p></section>

<section id="GUID-DBB544CC-A118-4954-A1BF-EED915A0D69E-GENID-1-2-1-10-1-5-1-9-1-1-7-1-4-1-10-1-3-10"><title>Capabilities()</title><p>The

function declaration for the <xref href="GUID-5EF2EECD-B9A0-3A76-A7F1-3C196AABFC40.dita"><apiname>Capabilities()</apiname></xref> method is:</p><codeblock xml:space="preserve">inline const TSDIOFunctionCaps&amp; Capabilities() const;</codeblock><p><b>Description</b></p><p>Returns information about the basic capabilities

of the function (function number, function type etc.).</p><p><b>Parameters</b></p><p>None</p><p><b>Return

value</b></p><p>A pointer to the <xref href="GUID-6BD11B5F-2269-3317-A40D-6547042CA463.dita"><apiname>DSDIORegisterInterface</apiname></xref> associated

with this function.</p></section>

</conbody></concept>