<?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 task
  PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<task id="GUID-6E89E787-749D-5AC5-957D-967B4B9ACD74" xml:lang="en"><title>Using
the BIL Interface</title><shortdesc>This tutorial describes how to use the Buffer Interface Layer (BIL)
to read and write shared chunks form the client driver. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody>
<context id="GUID-40DA18C7-1949-5495-BC1B-03ED9C437B7C"><p> </p> <p>The BIL
is a thin layer over the LDD APIs that removes the need for the class driver
to handle buffers directly. The BIL is consistent between different class
drivers and reduces the buffer related understanding needed to use the USBSc
LDD. </p> <p>Using the BIL is optional to the class driver, but very highly
recommended. </p><p> Before completing these steps you must have followed
the procedure from
 the beginning of the tutorial set through to
<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>
<steps id="GUID-E17FCECC-D0A2-57C9-9248-0A71E8A0B61D">
<step id="GUID-C4CEF921-C970-5C0D-AC32-F18A0A482278"><cmd> Open each endpoint
object.  </cmd>

<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
each endpoint object. </info>
<stepxmp><codeblock id="GUID-B1EFEBB5-3FF2-5124-A821-07223946110A" xml:space="preserve">TEndpointBuffer iEpBuf;
const TUint KWriteEp = 1;

gPort.OpenEndpoint(iEpBuf, KWriteEp);</codeblock> </stepxmp>
<info> <codeph>OpenEndpoint()</codeph> fills the provided endpoint buffer
(<codeph>iEpBuf</codeph>) for use with the given endpoint number (<codeph>KWriteEp</codeph>).
This endpoint will be opened on the current alternate interface setting. </info>
</step>
<step id="GUID-1A4579B9-8643-5F42-8048-BCEBADD56406"><cmd/>
<info> Reading with an OUT endpoint.  </info>
<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
request data from the BIL. </info>
<stepxmp><codeblock id="GUID-985944AC-D3DC-53C1-A0AE-417A51E2F951" xml:space="preserve">r = iEpBuf.GetBuffer(scReadData, readSize, readZlp, aStatus);</codeblock> </stepxmp>
<info>The first parameter passed to <codeph>GetBuffer()</codeph> can be either
a pointer to the transfer buffer or the offset of the transfer data within
the shared chunk. </info>
<info>This function allows the BIL to expire any previously retrieved transfer
on this endpoint so that it can be used again for new transfers. If the transfer
or the LDD are not ready then <codeph>aStatus</codeph> is set to pending.
If no transfer is available then the variable passed in the first parameter
is set to NULL or 0 depending on the API. Call this function again on completion,
to wait for data again. </info>
<info>The function <codeph>GetBuffer()</codeph> returns: </info>

<substeps id="GUID-3DABE2BC-8A54-503A-B7A2-D6867B0BE306">
<substep id="GUID-6C7D86C5-60DE-5677-B1F3-2EBE8802CA8F"><cmd/>
<info> <codeph>KErrCompletion</codeph> if data could be retrieved without
a pending request, </info>
</substep>
<substep id="GUID-ACD12551-A216-5615-B24F-0CEAB33D92B2"><cmd/>
<info> <codeph>KErrNone</codeph> if an asynchronous request was queued. This
function should be called again on completion, </info>
</substep>
<substep id="GUID-1545994A-F7D2-5904-9B13-BEDA58A9AF06"><cmd/>
<info> <codeph>KErrEof</codeph> if the end of the data in the endpoint has
been reached, </info>
</substep>
<substep id="GUID-B3CA8F5E-8816-535B-94D1-512305870882"><cmd/>
<info> <codeph>KErrNotSupported</codeph> if the endpoint is an IN endpoint. </info>
</substep>
</substeps>
<info>If the host has changed to an alternate setting and you wish to continue
reading and writing data then you must <codeph>Close()</codeph> all endpoints
and go to step five Process the next alternate set of endpoints. Otherwise,
if you have finished then go to step four Close each endpoint object. </info>
</step>
<step id="GUID-D1347544-106F-5883-9789-0001DF12ED15"><cmd/>
<info> Writing with an IN endpoint.  </info>
<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
write the data to endpoint hardware. </info>
<info> <codeph>WriteBuffer()</codeph> transmits the provided buffer on the
given endpoint asynchronously. More than one request may be outstanding at
any time. This reduces the time between buffer transfers. </info>
<stepxmp><codeblock id="GUID-4F511487-D318-5DFA-BDF5-20CA98BE04BC" xml:space="preserve">r = iEpBuf.WriteBuffer(buffer, length, ETrue, aStatus);</codeblock> </stepxmp>
<info>The first parameter passed to <codeph>WriteBuffer()</codeph> can be
either a pointer to the transfer buffer or the offset of the transfer data
within the shared chunk. </info>
<info>If the host has changed to an alternate setting and you wish to continue
reading and writing data then you must <codeph>Close()</codeph> all endpoints
and go to step five Process the next alternate set of endpoints. Otherwise,
if you have finished then go to step four Close each endpoint object. </info>
</step>
<step id="GUID-6C39309D-0822-59D0-8A47-2E7146991FC6"><cmd/>
<info> Close each endpoint object.  </info>
<info>Each endpoint object opened with <codeph>OpenEndpoint()</codeph> must
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>
<stepxmp><codeblock id="GUID-CA3F1F92-B224-5246-A91E-67004EDCD754" xml:space="preserve">iEpBuf.Close();</codeblock> </stepxmp>
<info>If the host has changed to an alternate setting and you wish to continue
reading and writing data then you must <codeph>Close()</codeph> all endpoints
and go to step five Process the next alternate set of endpoints. Otherwise,
if you have finished data transfer then <xref href="GUID-BE73CFE6-D48D-5B92-AF49-E2D967ADF0EC.dita">Close
and Unload the Driver</xref>. </info>
<info>If you wish to continue reading and writing data but on an alternate
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>.
Otherwise if you have finished then Close and Unload the Driver. </info>
</step>
<step id="GUID-1F1A169A-EC61-50D3-BCEA-5CEC8A13C8BE"><cmd/>
<info> Process the next alternate set of endpoints.  </info>
<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
switch to the next set of endpoints. The alternate interfaces were initialised
with <codeph>SetInterface()</codeph>. See <xref href="GUID-5F614B75-056D-5798-AE06-8DA6E9ED6834.dita">Set
the Interface Descriptors</xref>. </info>
<stepxmp><codeblock id="GUID-81FA57A5-F55A-5437-A9B6-8406D12AF1A2" xml:space="preserve">TInt r = StartNextOutAlternateSetting(ETrue);</codeblock> </stepxmp>
<info>Pass ETrue to the function to purge the buffers of any data unread for
the previous setting. </info>
<info> Note: All open endpoints (except EP0) must be closed before this is
called. </info>
</step>
</steps>
<postreq><p>When you have finished reading and writing <xref href="GUID-BE73CFE6-D48D-5B92-AF49-E2D967ADF0EC.dita">Close
and Unload the Driver</xref>. </p> </postreq>
</taskbody></task>