<?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-7AB51180-7A1A-40C7-B28F-EA46314A6E5B" xml:lang="en"><title>Synchronous

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

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

<section id="GUID-6C508A3B-B2E6-4D16-9421-03EE1A0B595F">       <title><b>Synchronous

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

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

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

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

side thread is blocked till completion. Synchronous requests are usuallly

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

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

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

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

enum TControl 

    {

    EControlConfigure, // Configure the device (UART)

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

    EControlReceiveData,    // Receive the data from the device 

    ENumRequests, // Number of synchronous control requests

    AllRequests = (1<<ENumRequests)-1

    };</codeblock>     </section>

<section id="GUID-EC33A9C8-CE41-4937-8008-35502C290581"><title>Implementation</title><p>Drivers

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

to handle the received synchronous messages. The implementation reads the

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

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

    {

    switch (aFunction)

        {

        case RExDriver::EControlConfigure:

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

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

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

            if (r==KErrNone)

                Pdd()->Configure(&c);

            break;

            ...

        default:

                r = KErrNotSupported;

        }

    return r;

    }</codeblock></section>

</conbody></concept>