Media Controller: Communicating Between the Server and Client for Media Control

This tutorial demonstrates how you can transfer information and send commands between the media controller server and client.

This feature is supported in mobile applications only.

Warm-up

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

Initializing the Media Controller
Initialize the media controller server and client for use.
Updating and Retrieving Information
Update the metadata and playback information on the server side, and then retrieve the metadata and playback information on the client side.
Sending and Processing Commands
Send a command to the server from the client side, and then process the command on the server side.

Initializing the Media Controller

To initialize the media controller server for use:

To use the functions and data types of the Media Controller Server API, include the <media_controller_server.h> header file in your application:
```
#include <media_controller_server.h>
```
To work with the Media Controller Server API, define a handle variable for the media controller server:
```
static mc_server_h g_server_h = NULL;
```
The server updates the metadata and playback information, and processes the requests and commands sent by the client.

This tutorial uses a global variable for the handle.

To initialize the media controller client for use:

To use the functions and data types of the Media Controller Client API, include the <media_controller_client.h> header file in your application:
```
#include <media_controller_client.h>
```
To work with the Media Controller Client API, define a handle variable for the media controller client:
```
static mc_client_h g_client_h = NULL;
```
The client requests metadata and playback information from the server, and sends playback commands to server.

This tutorial uses a global variable for the handle.

Updating and Retrieving Information

To update the metadata and playback information on the server side:

Create the media controller server handle using the mc_server_create() function:
```
ret = mc_server_create(&g_server_h);
```
Set the metadata or playback information to be updated using the corresponding mc_server_set_XXX() function, and then update the metadata or playback information using the corresponding mc_server_update_XXX() function.

For example, to update the playback state information, set the information to be updated using the mc_server_set_playback_state() function, and then update the information using the mc_server_update_playback_info() function:
```
ret = mc_server_set_playback_state(g_mc_server, MC_PLAYBACK_STATE_PLAYING);

ret = mc_server_update_playback_info(g_mc_server);
```
When no longer needed, destroy the media controller server handle using the mc_server_destroy() function:
```
mc_server_destroy(g_server_h);
```

To retrieve the metadata and playback information on the client side:

Create the media controller client handle using the mc_client_create() function:
```
ret = mc_client_create(&g_client_h);
```

Retrieve the server name using the mc_client_get_latest_server_info() function:

char *server_name = NULL;
mc_server_state_e server_state;

ret = mc_client_get_latest_server_info(g_mc_client, &server_name, &server_state);
dlog_print(DLOG_DEBUG, LOG_TAG, "Server Name: %s, Server state: %d\n", server_name, server_state);

Retrieve the metadata or playback information from the server using the corresponding mc_client_get_server_XXX() function. Use the server name retrieved in the previous step to identify the server.

For example, to retrieve the playback information from the server, use the mc_client_get_server_playback_info() function:
```
mc_playback_h playback = NULL;
mc_playback_states_e playback_state;

ret = mc_client_get_server_playback_info(g_client_h, server_name, &playback);

ret = mc_client_get_playback_state(playback, &playback_state);
dlog_print(DLOG_DEBUG, LOG_TAG, "Playback State: %d\n", playback_state);
```
The mc_client_get_playback_state() function retrieves the playback state from the playback information returned by the mc_client_get_server_playback_info() function.
When no longer needed, destroy the media controller client handle using the mc_client_destroy() function:
```
mc_client_destroy(g_client_h);
```

Sending and Processing Commands

To send a command to the server from the client side:

Create the media controller client handle using the mc_client_create() function:
```
ret = mc_client_create(&g_client_h);
```

Retrieve the server name using the mc_client_get_latest_server_info() function:

char *server_name = NULL;
mc_server_state_e server_state;

ret = mc_client_get_latest_server_info(g_mc_client, &server_name, &server_state);
dlog_print(DLOG_DEBUG, LOG_TAG, "Server Name: %s, Server state: %d\n", server_name, server_state);

Send the command to the server using the corresponding mc_client_send_XXX() function. Use the server name retrieved in the previous step to identify the server.

For example, to send a playback state change command to the server, use the mc_client_send_playback_state_command() function with the new state defined in the third parameter:
```
mc_playback_h playback = NULL;
mc_playback_states_e playback_state = MC_PLAYBACK_STATE_PLAYING;

ret = mc_client_send_playback_state_command(g_client_h, server_name, playback_state);
```
If you want to define your own commands to send to the server, use the mc_client_send_custom_command() function.
When no longer needed, destroy the media controller client handle using the mc_client_destroy() function:
```
mc_client_destroy(g_client_h);
```

To process the received command on the server side:

Create the media controller server handle using the mc_server_create() function:
```
ret = mc_server_create(&g_server_h);
```

Define the callback that is invoked when the server receives the command.

For example, to define a callback for playback state change commands:

void
command_received_cb(const char* client_name, mc_playback_states_e state, void *user_data)
{
   dlog_print(DLOG_DEBUG, LOG_TAG, "Client Name: %s, Playback state: %d\n", client_name, state);
}

Register the callback:
- To register a callback for playback state change commands, use the mc_server_set_playback_state_command_received_cb() function.
- To register a callback for a custom command, use the mc_server_set_custom_command_received_cb() function.
For example, to register a callback for playback state change commands:
```
ret = mc_server_set_playback_state_command_received_cb(g_mc_server, command_received_cb, NULL);
```
When no longer needed, destroy the media controller server handle using the mc_server_destroy() function:
```
mc_server_destroy(g_server_h);
```