Symbian3/SDK/Source/GUID-7DDF477A-1744-589A-82CB-3CB32D56D7CE.dita
changeset 0 89d6a7a84779
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-7DDF477A-1744-589A-82CB-3CB32D56D7CE.dita	Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,129 @@
+<?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>
\ No newline at end of file