Commands and Responses

This tutorial deals with the commands and responses available for remote control framework applications.

Intended Audience:

This tutorial is designed for Symbian licensees and 3rd party application developers.

Using Commands and Responses

The following tasks will be covered in this tutorial:

  • As Controller

    • Send Commands

    • Receive responses

  • As Target

    • Receive Commands

    • Send Responses

Controller

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.

Sending Commands

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.

...
 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());

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.

Receiving Responses

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.

To receive responses the application should implement the MRemConCoreApiControllerObserver controller observer interface. It then receives callbacks when a response has arrived.

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;    
        }
    }

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.

Target

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.

Receiving Commands

To receive a command, such as a request to increase the volume or return a listing of audio tracks, the client must implement the MRemConCoreApiTargetObserver target observer interface. It then will receive a callback through this interface when a command is received.

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);
    ...
    }

Sending Responses

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

...
CRemConCoreApiTarget* iCoreTarget;
...
    {
    ...
    // from above
    TRequestStatus stat;
    // send the response
    iCoreTarget->PlayResponse(stat, KErrNone);
    User::WaitForRequest(stat);
     ...
    }

What's next?