Media Controller: Communicating Between the Media Controller Server and Client

This tutorial demonstrates how you can to develop server and client applications for controlling various media functions of the device.

The Media Controller API is mandatory for both Tizen mobile and wearable profiles, which means that it is supported in all mobile and wearable devices. All mandatory APIs are supported on the Tizen Emulators.

Warm-up

Become familiar with the Media Controller API basics by learning about:

Getting the Client and Server
Create a server, and get a client and find all active servers.
Managing Requests
Send a request from the client and handle it in the server.
Receiving Notifications from the Server
Receive notifications when the server makes changes in the play modes.
Sending and Receiving Custom Commands
Send a custom command from the client, and receive and handle it in the server.

Getting the Client and Server

To manage the media controller features in your application, you must learn to set up the client and server pair:

Create a media controller server using the createServer() method:
```
var mcServer = tizen.mediacontroller.createServer();
```

Get the client using the getClient() method:

var mcClient = tizen.mediaController.getClient();

Define a success (and optionally error) event handler by implementing the MediaControllerServerInfoArraySuccessCallback interface (in mobile and wearable applications):

var mcServerInfo;

function findSuccessCallback(servers) 
{
   console.log("Found " + servers.length + " servers");
   if (servers.length > 0) 
   {
      mcServerInfo = servers[0];
   }
}

function findErrorCallback(e) 
{
   console.log("Error name: " + e.name + " Error message: " + e.message);
}

To search for all activated media controller servers, use the findServers() method of the MediaControllerClient interface (in mobile and wearable applications):
```
mcClient.findServers(findSuccessCallback, findErrorCallback);
```

Managing Requests

To manage the media controller features in your application, you must learn to handle requests from the client to the server:

Create a MediaControllerChangeRequestPlaybackInfoCallback object (in mobile and wearable applications) to define listeners for getting the requests from a client.

Each listener must invoke the appropriate function to perform the related update on the server and send an appropriate notification to the client. For example, the onplaybackstaterequest listener must use the updatePlaybackState() method to update the playback state.

var requestPlaybackInfoCb = 
{
   onplaybackstaterequest: function(state) 
   {
      console.log('Request to change the playback state to: ' + state);
      mcServer.updatePlaybackState(state);
   },
   onplaybackpositionrequest: function(position) 
   {
      console.log('Request to change the playback position to: ' + position);
      mcServer.updatePlaybackPosition(position);
   },
   onshufflemoderequest: function(mode) 
   {
      console.log('Request to change the playback shuffle mode to: ' + (mode ? 'TRUE' : 'FALSE'));
      mcServer.updateShuffleMode(mode);
   },
   onrepeatmoderequest: function(mode) 
   {
      console.log('Request to change the playback repeat mode to: ' + (mode ? 'TRUE' : 'FALSE'));
      mcServer.updateRepeatMode(mode);
   }
};

Add the listeners defined in the MediaControllerChangeRequestPlaybackInfoCallback object to the server:
```
var watchId = mcServer.addChangeRequestPlaybackInfoListener(requestPlaybackInfoCb);
```
The watchId variable stores the value, which can be used in the future to remove the listeners from the server using the removeChangeRequestPlaybackInfoListener() method.

At the client side, before sending a request, define optional success and error callbacks:

function successCallback() 
{
   console.log("Playback has been paused.");
}

function errorCallback(e) 
{
   console.log("Error name: " + e.name + " Error message: " + e.message);
}

You can send a request from the client using the sendPlaybackState(), sendPlaybackPosition(), endShuffleMode(), or sendRepeatMode() method of the MediaControllerServerInfo interface (in mobile and wearable applications).
In the following example, send a request for the changing the playback state to paused using the sendPlaybackState() method:
```
mcServerInfo.sendPlaybackState("PAUSE", successCallback, errorCallback);
```

Receiving Notifications from the Server

To manage the media controller features in your application, you must learn to receive notifications from the server:

Define the needed variable:
```
var watcherId;
```

Define the event handlers for different notifications by implementing the MediaControllerPlaybackInfoChangeCallback interface (in mobile and wearable applications):

var playbackListener = 
{
   onplaybackchanged: function(state, position) 
   {
      console.log("Current playback state: " + state);
      console.log("Current playback position: " + position);
   },
   onshufflemodechanged: function(mode) 
   {
      console.log("Shuffle mode changed to: " + mode);
   },
   onrepeatmodechanged: function(mode) 
   {
       console.log("Repeat mode changed to: " + mode);
   },
   onmetadatachanged: function(metadata) 
   {
      console.log("Playback metadata changed: " + JSON.stringify(metadata));
   }
};

Register the listener to start receiving notifications about playback changes:
```
watcherId = mcServerInfo.addPlaybackInfoChangeListener(playbackListener);
```
To stop receiving notifications, use the removePlaybackInfoChangeListener() method:
```
mcServerInfo.removePlaybackInfoChangeListener(watcherId);
```

Sending and Receiving Custom Commands

To manage the media controller features in your application, you must learn to send custom commands:

On the client side:

Define your custom command:

var exampleCustomCommandData = 
{
   myFilter: "rock"
};

Define a success (and optionally error) callback implementing the MediaControllerSendCommandSuccessCallback interface (in mobile and wearable applications):

function sendCommandSuccessCallback(response) 
{
   console.log("Command executed with result: " + JSON.stringify(response));
}

function sendCommandErrorCallback(e) 
{
   console.log("Error name: " + e.name + " Error message: " + e.message);
}

Send the command to the server using the sendCommand() method:

mcServerInfo.sendCommand("myPlaylistFilter", sendCommandSuccessCallback, sendCommandErrorCallback);

On the server side:
1. Create the MediaControllerReceiveCommandCallback object (in mobile and wearable applications) to define a listener for receiving custom commands from a client:
```
var commandReceiveListener = function(client, command, data) 
{
   console.log('command: ' + command + ' client: ' + client + ' data: ' + JSON.stringify(data));

   return {reply: 'response from server'};
};
```
  The callback function within the listener returns the object with the response to the client. The client can obtain this value as an argument of the success callback of the sendCommand() method that it used to send the command.
2. Add the listener defined in the MediaControllerReceiveCommandCallback object to the server:
```
var watcherId = mcServer.addCommandListener(commandReceiveListener);
```
  The watcherId variable stores the value, which can be used in the future to remove the listener from the server using the removeCommandListener() method.