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 task

    11   PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">

    12 <task id="GUID-6E89E787-749D-5AC5-957D-967B4B9ACD74" xml:lang="en"><title>Using

    13 the BIL Interface</title><shortdesc>This tutorial describes how to use the Buffer Interface Layer (BIL)

    14 to read and write shared chunks form the client driver. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody>

    15 <context id="GUID-40DA18C7-1949-5495-BC1B-03ED9C437B7C"><p> </p> <p>The BIL

    16 is a thin layer over the LDD APIs that removes the need for the class driver

    17 to handle buffers directly. The BIL is consistent between different class

    18 drivers and reduces the buffer related understanding needed to use the USBSc

    19 LDD. </p> <p>Using the BIL is optional to the class driver, but very highly

    20 recommended. </p><p> Before completing these steps you must have followed

    21 the procedure from

    22  the beginning of the tutorial set through to

    23 <xref href="GUID-4D1AE286-41EE-3361-948A-3E8634D81DBA.dita#GUID-4D1AE286-41EE-3361-948A-3E8634D81DBA/GUID-C2FF3692-93FE-3F9B-ADBC-A0875B5290D4"><apiname>RDevUsbcScClient::FinalizeInterface()</apiname></xref></p> </context>

    24 <steps id="GUID-E17FCECC-D0A2-57C9-9248-0A71E8A0B61D">

    25 <step id="GUID-C4CEF921-C970-5C0D-AC32-F18A0A482278"><cmd> Open each endpoint

    26 object.  </cmd>

    27 

    28 <info>Use the function <xref href="GUID-4D1AE286-41EE-3361-948A-3E8634D81DBA.dita#GUID-4D1AE286-41EE-3361-948A-3E8634D81DBA/GUID-98D986E5-6529-375A-84F4-769F20CFD161"><apiname>RDevUsbcScClient::OpenEndpoint()</apiname></xref> for

    29 each endpoint object. </info>

    30 <stepxmp><codeblock id="GUID-B1EFEBB5-3FF2-5124-A821-07223946110A" xml:space="preserve">TEndpointBuffer iEpBuf;

    31 const TUint KWriteEp = 1;

    32 

    33 gPort.OpenEndpoint(iEpBuf, KWriteEp);</codeblock> </stepxmp>

    34 <info> <codeph>OpenEndpoint()</codeph> fills the provided endpoint buffer

    35 (<codeph>iEpBuf</codeph>) for use with the given endpoint number (<codeph>KWriteEp</codeph>).

    36 This endpoint will be opened on the current alternate interface setting. </info>

    37 </step>

    38 <step id="GUID-1A4579B9-8643-5F42-8048-BCEBADD56406"><cmd/>

    39 <info> Reading with an OUT endpoint.  </info>

    40 <info>To read with an endpoint call <xref href="GUID-46F7D0B5-8F71-3D63-AC40-D940240B0373.dita#GUID-46F7D0B5-8F71-3D63-AC40-D940240B0373/GUID-80654761-26F2-3C1A-BD75-86C24A41FB14"><apiname>TEndpointBuffer::GetBuffer()</apiname></xref> to

    41 request data from the BIL. </info>

    42 <stepxmp><codeblock id="GUID-985944AC-D3DC-53C1-A0AE-417A51E2F951" xml:space="preserve">r = iEpBuf.GetBuffer(scReadData, readSize, readZlp, aStatus);</codeblock> </stepxmp>

    43 <info>The first parameter passed to <codeph>GetBuffer()</codeph> can be either

    44 a pointer to the transfer buffer or the offset of the transfer data within

    45 the shared chunk. </info>

    46 <info>This function allows the BIL to expire any previously retrieved transfer

    47 on this endpoint so that it can be used again for new transfers. If the transfer

    48 or the LDD are not ready then <codeph>aStatus</codeph> is set to pending.

    49 If no transfer is available then the variable passed in the first parameter

    50 is set to NULL or 0 depending on the API. Call this function again on completion,

    51 to wait for data again. </info>

    52 <info>The function <codeph>GetBuffer()</codeph> returns: </info>

    53 

    54 <substeps id="GUID-3DABE2BC-8A54-503A-B7A2-D6867B0BE306">

    55 <substep id="GUID-6C7D86C5-60DE-5677-B1F3-2EBE8802CA8F"><cmd/>

    56 <info> <codeph>KErrCompletion</codeph> if data could be retrieved without

    57 a pending request, </info>

    58 </substep>

    59 <substep id="GUID-ACD12551-A216-5615-B24F-0CEAB33D92B2"><cmd/>

    60 <info> <codeph>KErrNone</codeph> if an asynchronous request was queued. This

    61 function should be called again on completion, </info>

    62 </substep>

    63 <substep id="GUID-1545994A-F7D2-5904-9B13-BEDA58A9AF06"><cmd/>

    64 <info> <codeph>KErrEof</codeph> if the end of the data in the endpoint has

    65 been reached, </info>

    66 </substep>

    67 <substep id="GUID-B3CA8F5E-8816-535B-94D1-512305870882"><cmd/>

    68 <info> <codeph>KErrNotSupported</codeph> if the endpoint is an IN endpoint. </info>

    69 </substep>

    70 </substeps>

    71 <info>If the host has changed to an alternate setting and you wish to continue

    72 reading and writing data then you must <codeph>Close()</codeph> all endpoints

    73 and go to step five Process the next alternate set of endpoints. Otherwise,

    74 if you have finished then go to step four Close each endpoint object. </info>

    75 </step>

    76 <step id="GUID-D1347544-106F-5883-9789-0001DF12ED15"><cmd/>

    77 <info> Writing with an IN endpoint.  </info>

    78 <info>After filling a shared chunk buffer with some data call <xref href="GUID-46F7D0B5-8F71-3D63-AC40-D940240B0373.dita#GUID-46F7D0B5-8F71-3D63-AC40-D940240B0373/GUID-013E135D-AF87-3FFD-8B35-42D7B3FDECD8"><apiname>TEndpointBuffer::WriteBuffer()</apiname></xref> to

    79 write the data to endpoint hardware. </info>

    80 <info> <codeph>WriteBuffer()</codeph> transmits the provided buffer on the

    81 given endpoint asynchronously. More than one request may be outstanding at

    82 any time. This reduces the time between buffer transfers. </info>

    83 <stepxmp><codeblock id="GUID-4F511487-D318-5DFA-BDF5-20CA98BE04BC" xml:space="preserve">r = iEpBuf.WriteBuffer(buffer, length, ETrue, aStatus);</codeblock> </stepxmp>

    84 <info>The first parameter passed to <codeph>WriteBuffer()</codeph> can be

    85 either a pointer to the transfer buffer or the offset of the transfer data

    86 within the shared chunk. </info>

    87 <info>If the host has changed to an alternate setting and you wish to continue

    88 reading and writing data then you must <codeph>Close()</codeph> all endpoints

    89 and go to step five Process the next alternate set of endpoints. Otherwise,

    90 if you have finished then go to step four Close each endpoint object. </info>

    91 </step>

    92 <step id="GUID-6C39309D-0822-59D0-8A47-2E7146991FC6"><cmd/>

    93 <info> Close each endpoint object.  </info>

    94 <info>Each endpoint object opened with <codeph>OpenEndpoint()</codeph> must

    95 be closed with <xref href="GUID-46F7D0B5-8F71-3D63-AC40-D940240B0373.dita#GUID-46F7D0B5-8F71-3D63-AC40-D940240B0373/GUID-CD3F8021-67E2-3AA4-9DA9-7C854A134A54"><apiname>TEndpointBuffer::Close()</apiname></xref>. </info>

    96 <stepxmp><codeblock id="GUID-CA3F1F92-B224-5246-A91E-67004EDCD754" xml:space="preserve">iEpBuf.Close();</codeblock> </stepxmp>

    97 <info>If the host has changed to an alternate setting and you wish to continue

    98 reading and writing data then you must <codeph>Close()</codeph> all endpoints

    99 and go to step five Process the next alternate set of endpoints. Otherwise,

   100 if you have finished data transfer then <xref href="GUID-BE73CFE6-D48D-5B92-AF49-E2D967ADF0EC.dita">Close

   101 and Unload the Driver</xref>. </info>

   102 <info>If you wish to continue reading and writing data but on an alternate

   103 setting then call <xref href="GUID-4D1AE286-41EE-3361-948A-3E8634D81DBA.dita#GUID-4D1AE286-41EE-3361-948A-3E8634D81DBA/GUID-A4726204-4DE4-31FC-9CB3-54A3BC5155C2"><apiname>RDevUsbcScClient::StartNextOutAlternateSetting()</apiname></xref>.

   104 Otherwise if you have finished then Close and Unload the Driver. </info>

   105 </step>

   106 <step id="GUID-1F1A169A-EC61-50D3-BCEA-5CEC8A13C8BE"><cmd/>

   107 <info> Process the next alternate set of endpoints.  </info>

   108 <info>Use the function <xref href="GUID-4D1AE286-41EE-3361-948A-3E8634D81DBA.dita#GUID-4D1AE286-41EE-3361-948A-3E8634D81DBA/GUID-A4726204-4DE4-31FC-9CB3-54A3BC5155C2"><apiname>RDevUsbcScClient::StartNextOutAlternateSetting()</apiname></xref> to

   109 switch to the next set of endpoints. The alternate interfaces were initialised

   110 with <codeph>SetInterface()</codeph>. See <xref href="GUID-5F614B75-056D-5798-AE06-8DA6E9ED6834.dita">Set

   111 the Interface Descriptors</xref>. </info>

   112 <stepxmp><codeblock id="GUID-81FA57A5-F55A-5437-A9B6-8406D12AF1A2" xml:space="preserve">TInt r = StartNextOutAlternateSetting(ETrue);</codeblock> </stepxmp>

   113 <info>Pass ETrue to the function to purge the buffers of any data unread for

   114 the previous setting. </info>

   115 <info> Note: All open endpoints (except EP0) must be closed before this is

   116 called. </info>

   117 </step>

   118 </steps>

   119 <postreq><p>When you have finished reading and writing <xref href="GUID-BE73CFE6-D48D-5B92-AF49-E2D967ADF0EC.dita">Close

   120 and Unload the Driver</xref>. </p> </postreq>

   121 </taskbody></task>