<?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-7DDF477A-1744-589A-82CB-3CB32D56D7CE" xml:lang="en"><title>Commands

and Responses</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>This tutorial deals with the commands and responses available for remote

control framework applications. </p>

<p><b>Intended Audience: </b> </p>

<p>This tutorial is designed for Symbian licensees and 3rd party application

developers. </p>

<section><title>Using Commands and Responses</title> <p>The following tasks

will be covered in this tutorial: </p> <ul>

<li id="GUID-0F780A84-DECF-5FF3-B2A1-1B11ADD91380"><p> <b>As Controller</b>  </p> <ul>

<li id="GUID-BA8C996B-3E5D-540F-B96D-623E21372990"><p>Send Commands </p> </li>

<li id="GUID-23E3F61D-590F-5593-B68E-240DEA8750F0"><p>Receive responses </p> </li>

</ul> </li>

<li id="GUID-0FF1F84C-CCC0-5B1C-A1F9-36C3D6F5F7F0"><p> <b>As Target</b>  </p> <ul>

<li id="GUID-29C9E51A-9292-52A5-9C1A-27233F95FF2E"><p>Receive Commands </p> </li>

<li id="GUID-71816C68-E2DD-5494-9498-69908BA72ED4"><p>Send Responses </p> </li>

</ul> </li>

</ul> </section>

<section><title>Controller</title> <p>The device used to send control commands

to a remote target is the controller. There are two broad kinds of controller

operations that need to be understood: sending commands and receiving responses.

They are discussed below. </p> <p><b>Sending Commands</b> </p> <p>Commands

are sent to a remote control target device to tell the device to do something.

This may include changing the volume setting, requesting a track listing,

starting or stopping music playback, requesting a file listing, or depending

on the kind of device being controlled, telling the device to move in some

way. </p> <codeblock id="GUID-5A1B8672-7AD8-5BAB-BE6C-7D7D3650F6DD" xml:space="preserve">...

 CRemConCoreApiController* iCoreController;

... // open the controller as previously discussed.

 TRequestStatus stat;

 TUint numRemotes;

 // numRemotes is a value representing a specific participating device.

 iCoreController->Play(stat, numRemotes, ERemConCoreApiButtonClick);

 User::WaitForRequest(stat);

 LEAVEIFERRORL(stat.Int());</codeblock> <p>When a target receives the command

it will handle it in an appropriate way, as discussed in the next section.

The target may also send a response to the controller. </p> <p><b>Receiving

Responses</b> </p> <p>If a target sends a response to a received command the

controller needs to handle the response. The response could be something as

simple as an acknowledgement that a command has been received or it could

be as complex as a listing of audio tracks that the controller needs to process

in some way. </p> <p>To receive responses the application should implement

the <xref href="GUID-8457DAF2-0AEA-3D05-99C9-DAF4CBDF77FD.dita"><apiname>MRemConCoreApiControllerObserver</apiname></xref> controller observer

interface. It then receives callbacks when a response has arrived. </p> <codeblock id="GUID-15F36049-159A-5E34-8A86-56837E027573" xml:space="preserve">void MrccacoResponse(TRemConCoreApiOperationId aOperationId, 

                     TInt aError);

...

void CRemConTestOuter::MrccacoResponse(TRemConCoreApiOperationId aOperationId,

                                       TInt aError)

    {

    switch ( aOperationId )

        {

        case ERemConCoreApiPlay: 

             iManager.MtmWrite(_L8("\ta 'play' response came in with error %d"), aError);

             break;

        case ERemConCoreApiStop:

             iManager.MtmWrite(_L8("\ta 'stop' response came in with error %d"), aError);

             break;

        case ERemConCoreApiVolumeUp:

             iManager.MtmWrite(_L8("\ta 'VolumeUp' response came in with error %d"), aError);

             break;

        case ERemConCoreApiVolumeDown: 

             iManager.MtmWrite(_L8("\ta 'VolumeDown' response came in with error %d"), aError);

             break;

        case ERemConCoreApiForward:

             iManager.MtmWrite(_L8("\ta 'Forward' response came in with error %d"), aError);

             break;

        case ERemConCoreApiBackward:

             iManager.MtmWrite(_L8("\ta 'Backward' response came in with error %d"), aError);

             break;    

        }

    }</codeblock> <p>Responses are often followed up by the controller with

a series of actions such as presenting the information provided by the response

to the user, waiting for the user to make a choice of some kind, and sending

a new command, which begins the whole process again. </p> </section>

<section><title>Target</title> <p>A target device is set up to wait for and

handle commands sent to it from a controller and respond in some way to those

commands. </p> <p><b>Receiving Commands</b> </p> <p>To receive a command,

such as a request to increase the volume or return a listing of audio tracks,

the client must implement the <xref href="GUID-50F877E1-F630-3960-8DB4-37B6AD807308.dita"><apiname>MRemConCoreApiTargetObserver</apiname></xref> target

observer interface. It then will receive a callback through this interface

when a command is received. </p> <codeblock id="GUID-76929311-D3D1-5440-9608-FAC4ADBE0F55" xml:space="preserve">iCoreTarget = CRemConCoreApiTarget::NewL(*iInterfaceSelector, *this);

...

void CRemConTestOuter::MrccatoPlay(TRemConCoreApiPlaybackSpeed aSpeed,

                                   TRemConCoreApiButtonAction aButtonAct)

    {

    ...

    // used below

    TRequestStatus stat;

    // send the response

    iCoreTarget->PlayResponse(stat, KErrNone);

    User::WaitForRequest(stat);

    ...

    }</codeblock> <p><b>Sending Responses</b> </p> <p>Once the command has

been handled the target will send a response to the controller. The response

could be a simple acknowledgement, an error message, or a listing of files

or music tracks or some other data. Use the <xref href="GUID-723FC8F2-DB48-3C70-976F-D027E19F480B.dita"><apiname>CRemConCoreApiTarget</apiname></xref> interface. </p> <codeblock id="GUID-9F502820-CE27-5FB3-9D89-80C28A386F12" xml:space="preserve">...

CRemConCoreApiTarget* iCoreTarget;

...

    {

    ...

    // from above

    TRequestStatus stat;

    // send the response

    iCoreTarget->PlayResponse(stat, KErrNone);

    User::WaitForRequest(stat);

     ...

    }</codeblock> </section>

<section><title>What's next?</title> <ul>

<li id="GUID-5D4365C4-0012-5F27-A22C-440C8E6905E9"><p> <xref href="GUID-C4A072E1-4385-5C98-98C1-56F297132F11.dita">Remote

Control Basics</xref> </p> </li>

<li id="GUID-A6A62C85-0913-5954-B954-FBFAE9DFD839"><p> <xref href="GUID-E25A5C1E-83D7-51D5-8F11-9C44C6CEEDCE.dita">Starting

as Controller</xref>  </p> </li>

<li id="GUID-01D925B8-5864-554C-9D9D-E9C2A29230A9"><p> <xref href="GUID-8E25E84C-E8F3-50B2-82E5-0611A341ED27.dita">Starting

as Target</xref>  </p> </li>

<li id="GUID-7BFBAB9C-6810-5D35-BE95-D00D57D8B668"><p> <b>Commands and Responses</b> -

This document </p> </li>

</ul> </section>