|
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-7DDF477A-1744-589A-82CB-3CB32D56D7CE" xml:lang="en"><title>Commands |
|
13 and Responses</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>This tutorial deals with the commands and responses available for remote |
|
15 control framework applications. </p> |
|
16 <p><b>Intended Audience: </b> </p> |
|
17 <p>This tutorial is designed for Symbian licensees and 3rd party application |
|
18 developers. </p> |
|
19 <section><title>Using Commands and Responses</title> <p>The following tasks |
|
20 will be covered in this tutorial: </p> <ul> |
|
21 <li id="GUID-0F780A84-DECF-5FF3-B2A1-1B11ADD91380"><p> <b>As Controller</b> </p> <ul> |
|
22 <li id="GUID-BA8C996B-3E5D-540F-B96D-623E21372990"><p>Send Commands </p> </li> |
|
23 <li id="GUID-23E3F61D-590F-5593-B68E-240DEA8750F0"><p>Receive responses </p> </li> |
|
24 </ul> </li> |
|
25 <li id="GUID-0FF1F84C-CCC0-5B1C-A1F9-36C3D6F5F7F0"><p> <b>As Target</b> </p> <ul> |
|
26 <li id="GUID-29C9E51A-9292-52A5-9C1A-27233F95FF2E"><p>Receive Commands </p> </li> |
|
27 <li id="GUID-71816C68-E2DD-5494-9498-69908BA72ED4"><p>Send Responses </p> </li> |
|
28 </ul> </li> |
|
29 </ul> </section> |
|
30 <section><title>Controller</title> <p>The device used to send control commands |
|
31 to a remote target is the controller. There are two broad kinds of controller |
|
32 operations that need to be understood: sending commands and receiving responses. |
|
33 They are discussed below. </p> <p><b>Sending Commands</b> </p> <p>Commands |
|
34 are sent to a remote control target device to tell the device to do something. |
|
35 This may include changing the volume setting, requesting a track listing, |
|
36 starting or stopping music playback, requesting a file listing, or depending |
|
37 on the kind of device being controlled, telling the device to move in some |
|
38 way. </p> <codeblock id="GUID-5A1B8672-7AD8-5BAB-BE6C-7D7D3650F6DD" xml:space="preserve">... |
|
39 CRemConCoreApiController* iCoreController; |
|
40 ... // open the controller as previously discussed. |
|
41 TRequestStatus stat; |
|
42 TUint numRemotes; |
|
43 // numRemotes is a value representing a specific participating device. |
|
44 iCoreController->Play(stat, numRemotes, ERemConCoreApiButtonClick); |
|
45 User::WaitForRequest(stat); |
|
46 LEAVEIFERRORL(stat.Int());</codeblock> <p>When a target receives the command |
|
47 it will handle it in an appropriate way, as discussed in the next section. |
|
48 The target may also send a response to the controller. </p> <p><b>Receiving |
|
49 Responses</b> </p> <p>If a target sends a response to a received command the |
|
50 controller needs to handle the response. The response could be something as |
|
51 simple as an acknowledgement that a command has been received or it could |
|
52 be as complex as a listing of audio tracks that the controller needs to process |
|
53 in some way. </p> <p>To receive responses the application should implement |
|
54 the <xref href="GUID-8457DAF2-0AEA-3D05-99C9-DAF4CBDF77FD.dita"><apiname>MRemConCoreApiControllerObserver</apiname></xref> controller observer |
|
55 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, |
|
56 TInt aError); |
|
57 ... |
|
58 void CRemConTestOuter::MrccacoResponse(TRemConCoreApiOperationId aOperationId, |
|
59 TInt aError) |
|
60 { |
|
61 switch ( aOperationId ) |
|
62 { |
|
63 case ERemConCoreApiPlay: |
|
64 iManager.MtmWrite(_L8("\ta 'play' response came in with error %d"), aError); |
|
65 break; |
|
66 case ERemConCoreApiStop: |
|
67 iManager.MtmWrite(_L8("\ta 'stop' response came in with error %d"), aError); |
|
68 break; |
|
69 case ERemConCoreApiVolumeUp: |
|
70 iManager.MtmWrite(_L8("\ta 'VolumeUp' response came in with error %d"), aError); |
|
71 break; |
|
72 case ERemConCoreApiVolumeDown: |
|
73 iManager.MtmWrite(_L8("\ta 'VolumeDown' response came in with error %d"), aError); |
|
74 break; |
|
75 case ERemConCoreApiForward: |
|
76 iManager.MtmWrite(_L8("\ta 'Forward' response came in with error %d"), aError); |
|
77 break; |
|
78 case ERemConCoreApiBackward: |
|
79 iManager.MtmWrite(_L8("\ta 'Backward' response came in with error %d"), aError); |
|
80 break; |
|
81 } |
|
82 }</codeblock> <p>Responses are often followed up by the controller with |
|
83 a series of actions such as presenting the information provided by the response |
|
84 to the user, waiting for the user to make a choice of some kind, and sending |
|
85 a new command, which begins the whole process again. </p> </section> |
|
86 <section><title>Target</title> <p>A target device is set up to wait for and |
|
87 handle commands sent to it from a controller and respond in some way to those |
|
88 commands. </p> <p><b>Receiving Commands</b> </p> <p>To receive a command, |
|
89 such as a request to increase the volume or return a listing of audio tracks, |
|
90 the client must implement the <xref href="GUID-50F877E1-F630-3960-8DB4-37B6AD807308.dita"><apiname>MRemConCoreApiTargetObserver</apiname></xref> target |
|
91 observer interface. It then will receive a callback through this interface |
|
92 when a command is received. </p> <codeblock id="GUID-76929311-D3D1-5440-9608-FAC4ADBE0F55" xml:space="preserve">iCoreTarget = CRemConCoreApiTarget::NewL(*iInterfaceSelector, *this); |
|
93 ... |
|
94 void CRemConTestOuter::MrccatoPlay(TRemConCoreApiPlaybackSpeed aSpeed, |
|
95 TRemConCoreApiButtonAction aButtonAct) |
|
96 { |
|
97 ... |
|
98 // used below |
|
99 TRequestStatus stat; |
|
100 // send the response |
|
101 iCoreTarget->PlayResponse(stat, KErrNone); |
|
102 User::WaitForRequest(stat); |
|
103 ... |
|
104 }</codeblock> <p><b>Sending Responses</b> </p> <p>Once the command has |
|
105 been handled the target will send a response to the controller. The response |
|
106 could be a simple acknowledgement, an error message, or a listing of files |
|
107 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">... |
|
108 CRemConCoreApiTarget* iCoreTarget; |
|
109 ... |
|
110 { |
|
111 ... |
|
112 // from above |
|
113 TRequestStatus stat; |
|
114 // send the response |
|
115 iCoreTarget->PlayResponse(stat, KErrNone); |
|
116 User::WaitForRequest(stat); |
|
117 ... |
|
118 }</codeblock> </section> |
|
119 <section><title>What's next?</title> <ul> |
|
120 <li id="GUID-5D4365C4-0012-5F27-A22C-440C8E6905E9"><p> <xref href="GUID-C4A072E1-4385-5C98-98C1-56F297132F11.dita">Remote |
|
121 Control Basics</xref> </p> </li> |
|
122 <li id="GUID-A6A62C85-0913-5954-B954-FBFAE9DFD839"><p> <xref href="GUID-E25A5C1E-83D7-51D5-8F11-9C44C6CEEDCE.dita">Starting |
|
123 as Controller</xref> </p> </li> |
|
124 <li id="GUID-01D925B8-5864-554C-9D9D-E9C2A29230A9"><p> <xref href="GUID-8E25E84C-E8F3-50B2-82E5-0611A341ED27.dita">Starting |
|
125 as Target</xref> </p> </li> |
|
126 <li id="GUID-7BFBAB9C-6810-5D35-BE95-D00D57D8B668"><p> <b>Commands and Responses</b> - |
|
127 This document </p> </li> |
|
128 </ul> </section> |
|
129 </conbody></concept> |