SmartDeviceLink - HMI Documentation

SetMediaClockTimer

Type: Function
Sender: SDL
Purpose: Set a value and update mode for the media clock of a media application.

The UI.SetMediaClockTimer request indicates either an initial value for the media clock timer for a media application or an update to this value. The request may come for the application which is not currently active on the HMI.

Request

Must

Perform the update type indicated by the updateMode parameter:
- If the application is not active, the HMI must still store the values to be calculated for later display on the HMI.
- If the application is active, the updates must begin immediately.
Exhibit the following behavior based on the updateMode parameter:
- COUNTUP/COUNTDOWN modes:
  - Start counting up or down from the requested startTime value at the specified countRate with a step of 1 second;
  - Continue counting up or down until:
    - The next request of SetMediaClockTimer with appropriate parameters comes;
    - endTime is reached, if provided.
    - Zero is reached in the case of COUNTDOWN.
- PAUSE mode:
  - Pause the timer that is counting up or down;
  - If startTime or endTime parameters are provided, the values must be updated on the HMI.
- RESUME mode:
  - Resume the timer that was previously paused at the specified countRate;
- CLEAR mode:
  - Clear startTime to 00:00:00 in the case that the startTime parameter is not provided in the request, otherwise, startTime must be updated with a new value. It is up to the HMI to determine the way the media clock timer is cleared: either to remove it from display or to set it to zero.
Respond with the result code (see response section) correspondingly to the results of this RPC execution.
Send BC.OnResetTimeout notification to SDL to reset the timeout in case HMI needs more time to process the request.

Note

SDL will not send this request if the mediaClock field is not indicated as supported in UI.GetCapabilities.
HMI must remember the mode and the value (continuing to update it in case of COUNTUP / COUNTDOWN) of the media clock timer associated with appID and display the accurate values whenever the appID application is activated after having been deactivated.
Initially, the appID together with other application-related information is provided by SDL within one of UpdateAppList and OnAppRegistered RPCs.

Note

By default, forwardSeekIndicator and backSeekIndicator should be set to TRACK. The HMI should reset these values to TRACK when:

The media app is newly registered on the head unit (after RegisterAppInterface and the button subscription).
The media app was closed by the user (App enters HMI level NONE).
The app sends a SetMediaClockTimer request with forwardSeekIndicator and/or backSeekIndicator not set to any value.

Parameters

Name	Type	Mandatory	Additional	Description
startTime	Common.TimeFormat	false		startTime must be provided together with modes: "COUNTUP", "COUNTDOWN", "PAUSE" to HMI. startTime will be ignored for "RESUME", and "CLEAR".
endTime	Common.TimeFormat	false		endTime can be provided together with modes: "COUNTUP", "COUNTDOWN", "PAUSE" to HMI. To be used to calculate any visual progress bar (if not provided, this feature is ignored). If endTime is greater than startTime for COUNTDOWN or less than startTime for COUNTUP, then the request will return an INVALID_DATA. endTime will be ignored for "PAUSE", "RESUME", and "CLEAR".
updateMode	Common.ClockUpdateMode	true		Enumeration to control the media clock. In case of pause, resume, or clear, the start time value is ignored and shall be left out. For resume, the time continues with the same value as it was when paused.
audioStreamingIndicator	Common.AudioStreamingIndicator	false		Indicates that a button press of the Play/Pause button would play, pause or stop the current playback.
forwardSeekIndicator	Common.SeekStreamingIndicator	false		Used to control the forward seek button to either skip forward a set amount of time or to the next track.
backSeekIndicator	Common.SeekStreamingIndicator	false		Used to control the backward seek button to either skip back a set amount of time or to the previous track.
countRate	Float	false	minvalue: 0.1 maxvalue: 100.0 defvalue: 1.0	The rate at which the media clock timer will progress. Values less than 1.0 will advance the timer slower than real-time (ex. 0.5 would advance the timer at 50% speed), while values greater than 1.0 will advance the timer faster than real-time (ex. 2.0 would advance the timer at 200% speed).
appID	Integer	true

Response

Parameters

This RPC has no additional parameter requirements

Sequence Diagrams

Sequence Diagram

SetMediaClockTimer COUNTUP and COUNTDOWN for Full and Background applications

View Diagram

Sequence Diagram

SetMediaClockTimer Pause and Resume for Active Application

View Diagram

Sequence Diagram

SetMediaClockTimer COUNTDOWN for a deactivated application

View Diagram

JSON Message Examples

Example Request

{
  "id" : 109,
  "jsonrpc" : "2.0",
  "method" : "UI.SetMediaClockTimer",
  "params" :
  {
    "startTime" :
    {
         "hours" : 0,
         "minutes" : 18,
         "seconds" : 17
    },
    "updateMode" : "COUNTUP",
    "audioStreamingIndicator" : "PAUSE",
    "countRate": 1.0,
    "appID" : 65146
  }
}

Example Response

{
  "id" : 109,
  "jsonrpc" : "2.0",
  "result" :
  {
    "code" : 0,
    "method" : "UI.SetMediaClockTimer"
  }
}

Example Error

{
  "id" : 109,
  "jsonrpc" : "2.0",
  "error" :
  {
    "code" : 11,
    "message" : "Invalid data",
    "data" :
    {
      "method" : "UI.SetMediaClockTimer"
    }
  }
}

View on GitHub.com

Previous Section Next Section