The mm-control service monitors its PPS control object constantly.
When a client writes a command to this PPS object, mm-control
checks the command syntax and if it's valid, invokes other multimedia services
to perform the requested media operation. When these services report that the operation
is complete, mm-control writes the operation's outcome to the same
PPS object.
We recommend that any PPS-based service that you write to replace
mm-control follow the procedure and design described here.
The mm-control service consists of a PPS communications layer
and several subsystems that each manage a different set of media operations.
When a client application writes a new command to the PPS control object, these
mm-control components process the command by
performing the following steps:
- Reading new PPS object content
The read() system call returns the new content of the
PPS control object to the mm-control service.
The service's PPS layer searches this content for the msg and
dat attributes; if either one is missing, the service logs an
error and stops processing the command.
- Dispatching appropriate subsystem
If the command written to PPS has the necessary attributes,
mm-control reads the operation name stored in the
msg attribute. The first word in the operation name refers to
the command category, which must be one of the following:
- output
- zone
- trksession
- player
The commands in each of these categories operate on different object types,
as explained in mm-control components.
Based on the command category, mm-control invokes
the appropriate subsystem to examine the remaining words in the operation name.
If the operation name doesn't begin with any of the four words listed above or
if its remaining words don't refer to any action supported by the selected
subsystem, mm-control logs an error and stops processing
the command.
- Data and state validation
The mm-control subsystem that's processing the command
examines the dat attribute to verify that the client provided
all the necessary data parameters, and then verifies that the parameter values
and the current playback state are valid for the requested operation.
For example, when issuing the "player_play" command, a
client must provide a player name that matches one of the entries in the
mm-control players list. Also, the playback state,
which is also stored by mm-control, must be
IDLE, PAUSED, or STOPPED.
If the validity check for the data and the playback state fails,
mm-control logs an error and stops processing the command.
- Invoking lower-level multimedia services
The lower-level multimedia services aren't needed to carry out any commands in the
output and zone categories; for these commands,
mm-control skips this step.
When processing trksession or player commands,
mm-control either writes to PPS objects or makes API calls
to invoke the lower-level multimedia services to carry out the requested media
operation.
For instance, in response to the "player_set_params" command,
the player subsystem
examines the type attribute found in the content read from the PPS
control object. Based on this attribute's value (e.g., input,
track), the subsystem
then calls the mm-renderer API function that sets the specified
type of parameters (e.g., mmr_input_parameters(),
mmr_track_parameters()).
For the full list of supported media commands, shown by category, see the
/pps/services/mm-control/control entry in the
PPS Objects Reference.
- Updating internal data structures
The mm-control subsystem that processes the command checks the
return codes of all API function calls. After each successful call, the subsystem
updates the internal data structures as necessary.
For example, the mmr_set_speed() returns 0
after the "player_set_speed" command has been successfully
executed. In response, the player subsystem updates the speed
setting in the data structure that holds information on the player indicated by
the command's data.
For commands that don't require using any lower-level multimedia services
(e.g., "output_create" and
"zone_attach_outputs",
the relevant subsystem simply updates the lists of media resources available
for playback, based on the requested operation.
- Reporting operation outcome
The last command-processing activity done by mm-control is to
write the outcome (result) of the media operation into the PPS control object.
The operation name is echoed in the res attribute.
Any data describing the new playback state is encoded in JSON format and
stored in the data attribute; for instance,
after executing the "player_next_track" command,
mm-control reports the track ID, file ID, and URL
for the newly selected (and now playing) track.
The error code is written to the err attribute.
If this code is 0, then no error has occurred. Otherwise, the
errstr attribute contains a brief description of the error
encountered.
Clients can retrieve the results as soon as mm-control
updates the PPS control object by using delta mode and blocking
read() calls, identical to how mm-control
reads this same PPS object.