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-7AB51180-7A1A-40C7-B28F-EA46314A6E5B-GENID-1-2-1-9-1-6-1-9-1-5-1" xml:lang="en"><title>Synchronous

    13 Requests</title><shortdesc>This document describes the use of synchronous requests by device

    14 drivers.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    15 <section id="GUID-6C508A3B-B2E6-4D16-9421-03EE1A0B595F-GENID-1-2-1-9-1-6-1-9-1-5-1-3-1">       <title><b>Synchronous

    16 requests</b></title>       <p>Synchronous requests are typically used to set

    17 or retrieve some information for the device driver. These requests almost

    18 never need to access the hardware itself, and usually complete relatively

    19 quickly. They return only after the completion of the request and the user

    20 side thread is blocked till completion. Synchronous requests are usuallly

    21 initiated by a call to <xref href="GUID-6FBFA078-8253-3E24-B1F8-5F75E86C3066.dita#GUID-6FBFA078-8253-3E24-B1F8-5F75E86C3066/GUID-D774DE92-6431-374A-A1F6-1C7045BD4FE5"><apiname>RBusLogicalChannel::DoControl()</apiname></xref>.

    22 The request is most likely to be executed in the context of the client user-side

    23 thread.</p> <p>A driver lists its available synchronous requests

    24 in an enumeration, for example: </p> <codeblock id="GUID-09E42EC9-CF71-59C0-876E-0651F27E591F-GENID-1-2-1-9-1-6-1-9-1-5-1-3-1-4" xml:space="preserve">// Synchronous control messages used with DoControl()

    25 enum TControl 

    26     {

    27     EControlConfigure, // Configure the device (UART)

    28     EControlTransmitData, // Transmit data over the device (UART)    

    29     EControlReceiveData,    // Receive the data from the device 

    30     ENumRequests, // Number of synchronous control requests

    31     AllRequests = (1<<ENumRequests)-1

    32     };</codeblock>     </section>

    33 <section id="GUID-EC33A9C8-CE41-4937-8008-35502C290581-GENID-1-2-1-9-1-6-1-9-1-5-1-3-2"><title>Implementation</title><p>Drivers

    34 generally implement the <xref href="GUID-06C73075-6095-3D8F-AFC9-FD832958A49C.dita"><apiname>DoControl()</apiname></xref> function in the LDD

    35 to handle the received synchronous messages. The implementation reads the

    36 request type and other passed arguments, and handles the request appropriately.

    37 For example, the following handles <codeph>RExDriver::EControlConfigure</codeph> requests: </p> <codeblock id="GUID-1996BA3A-A895-58C8-B394-4219510DF6D3-GENID-1-2-1-9-1-6-1-9-1-5-1-3-2-3" xml:space="preserve">TInt DExDriverLogicalChannel::DoControl(TInt aFunction, TAny* a1, TAny* /*a2*/)

    38     {

    39     switch (aFunction)

    40         {

    41         case RExDriver::EControlConfigure:

    42             memclr(&c, sizeof(c)));

    43             TPtr8 cfg((TUint8*)&c, 0, sizeof(c)));

    44             r = Kern::ThreadDesRead(iClient,a1,cfg,0,0);

    45             if (r==KErrNone)

    46                 Pdd()->Configure(&c);

    47             break;

    48             ...

    49         default:

    50                 r = KErrNotSupported;

    51         }

    52     return r;

    53     }</codeblock></section>

    54 </conbody></concept>