<?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-&gt;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-&gt;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-&gt;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>
</conbody></concept>