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