1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

    12 <concept id="GUID-C57086D7-7672-4A52-8634-D28B37AC6290" xml:lang="en"><title>TSDIOFunction

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

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

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

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

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

    18 <tbody>

    19 <row>

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

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

    22 </row>

    23 <row>

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

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

    26 </row>

    27 <row>

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

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

    30 </row>

    31 <row>

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

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

    34 </row>

    35 </tbody>

    36 </tgroup>

    37 </table></section>

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

    39 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

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

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

    42 <tbody>

    43 <row>

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

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

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

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

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

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

    50 </row>

    51 </tbody>

    52 </tgroup>

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

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

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

    56 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

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

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

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

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

    61 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

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

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

    64 <tbody>

    65 <row>

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

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

    68 </row>

    69 </tbody>

    70 </tgroup>

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

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

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

    74 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">

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

    76 <tbody>

    77 <row>

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

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

    80 </row>

    81 <row>

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

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

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

    85 </row>

    86 </tbody>

    87 </tgroup>

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

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

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

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

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

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

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

    95 <tbody>

    96 <row>

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

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

    99 </row>

   100 </tbody>

   101 </tgroup>

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

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

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

   105 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.

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

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

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

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

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

   111 <tbody>

   112 <row>

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

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

   115 </row>

   116 </tbody>

   117 </tgroup>

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

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

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

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

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

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

   124 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">

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

   126 <tbody>

   127 <row>

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

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

   130 </row>

   131 </tbody>

   132 </tgroup>

   133 </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

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

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

   136 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

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

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

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

   140 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

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

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

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

   144 </conbody></concept>