Playback Messages

This chapter describes the MediaFS device control messages defined to retrieve state information from and control playback on a media device accessed and managed through MediaFS, or that are outside MediaFS. These message are:

Playback control and device status messages can be issued to the MediaFS control file only.

The exceptions to this rule are:


Note:
  • Most devices do not support the full set of control messages. If a message is not supported by the media device the requested action, the device controller must return the error code ENOTSUP (command invalid for this device).
  • All state modification control messages must be synchronous; the requested action must either complete or fail before returning.

    For example, if the state modifier DCMD_MEDIA_PLAY is issued, upon return of the devctl() call, the underlying device must be in a playing state, or have returned a POSIX error indicating why the command failed.


DCMD_MEDIA_ACCESS_TYPE

DCMD_MEDIA_ACCESS_TYPE retrieves information about how a file is to be accessed. The status values may indicate that the file is known to be either DRM protected or not DRM protected, as well as whether a POSIX read() function can be used to access the file's media content.

This command does not use a data transfer buffer. If the devctl() status is EOK, the integer return value (obtained using the last parameter of the devctl() function) may contain a combination of the following values:

Type Value Description
ACCESS_TYPE_DRM_PROTECTED 1 The file is known to be DRM protected. May not be combined with ACCESS_TYPE_DRM_UNPROTECTED.
ACCESS_TYPE_DRM_UNPROTECTED 2 The file is known to not be DRM protected. May not be combined with ACCESS_TYPE_DRM_PROTECTED.
ACCESS_TYPE_READ_SUPPORTED 4 The file can be read using POSIX read functions (the file is not Zune). May be combined with ACCESS_TYPE_DRM_UNPROTECTED or with ACCESS_TYPE_DRM_PROTECTED.

DCMD_MEDIA_FASTFWD

DCMD_MEDIA_FASTFWD instructs the media device to go to the fast forward speed specified by the rate member of the _media_speed structure. Behavior when this message is issued to a media device that is not in a playing state is device dependent: the request may succeed or fail, depending on the media device's capabilities and characteristics.

Buffer: struct _media_speed

DCMD_MEDIA_FASTRWD

DCMD_MEDIA_FASTRWD instructs the media device to go to the fast reverse speed specified by the _media_speed data structure's rate member. Behavior when this message is issued to a media device that is not in a playing state is device dependent: the request may succeed or fail, depending on the media device's capabilities and characteristics.

Buffer: struct _media_speed

DCMD_MEDIA_GET_REPEAT

DCMD_MEDIA_GET_REPEAT queries the media device for its current repeat playback mode. Defined repeat modes are:

On success, the call must return the current device repeat mode, in the _media_settings data structure's value member.

Buffer: struct _media_settings

DCMD_MEDIA_GET_SHUFFLE

DCMD_MEDIA_GET_SHUFFLE queries the media device for its current random playback mode. Defined random modes are:

On success, the call must return the current device random mode, in the _media_settings data structure's value member.

Buffer: struct _media_settings

DCMD_MEDIA_GET_STATE

DCMD_MEDIA_GET_STATE queries the media device for its current settings and returns the data in the _media_settings data structure. This data can be used at a later time to restore playback to the state at the time of the query.

Buffer: uint8_t[1]

DCMD_MEDIA_NEXT_CHAP

DCMD_MEDIA_NEXT_CHAP instructs the media device to skip forward to the next chapter in a video. Behavior when this message is issued to a media device that is not in a playing state is device dependent: the request may succeed or fail, depending on the media device's capabilities and characteristics.

DCMD_MEDIA_NEXT_TRACK

DCMD_MEDIA_NEXT_TRACK instructs the media device to skip forward to the next file in its playlist. Behavior when this message is issued to a media device that is not in a playing state is device dependent: the request may succeed or fail, depending on the media device's capabilities and characteristics.

DCMD_MEDIA_PAUSE

DCMD_MEDIA_PAUSE instructs the media device to pause playback of the current file. Issuing this message always causes a “pause” instruction to be sent to the media device, even when playback is already in a paused state.

DCMD_MEDIA_PLAY

DCMD_MEDIA_PLAY directs a media device to start playback. Behavior depends on the entity to which this message is issued, as follows:

DCMD_MEDIA_PLAY_AT

DCMD_MEDIA_PLAY_AT instructs the media device to start playback at a specified time offset in a file. This play time offset is set in the _media_play data structure.

Buffer: struct _media_play

DCMD_MEDIA_PLAYBACK_INFO

DCMD_MEDIA_PLAYBACK_INFO queries the media device for its current playback information and returns the data in the _media_playback data structure.

All media devices must support this capability, as it is fundamental to executing playback.

Buffer: struct _media_playback

DCMD_MEDIA_PLAYBACK_STATUS

DCMD_MEDIA_PLAYBACK_STATUS queries the media device for its current playback status and returns the data in the _media_playback_status data structure.

All media devices must support this capability, as it is fundamental to executing playback.

Buffer: struct _media_playback_status

DCMD_MEDIA_PREV_CHAP

DCMD_MEDIA_PREV_CHAP instructs the media device to skip back to the previous chapter in a video. Behavior when this message is issued to a media device that is not in a playing state is device dependent: the request may succeed or fail, depending on the media device's capabilities and characteristics.

DCMD_MEDIA_PREV_TRACK

DCMD_MEDIA_PREV_TRACK instructs the media device to skip backward to the previous file in its playlist. Behavior when this message is issued to a media device that is not in a playing state is device dependent: the request may succeed or fail, depending on the media device's capabilities and characteristics.

DCMD_MEDIA_RESUME

DCMD_MEDIA_RESUME instructs the media device to resume the playback of the current file. Issuing this message always causes a “resume” instruction to be sent to the media device, even when playback has already resumed.

DCMD_MEDIA_SEEK_CHAP

DCMD_MEDIA_SEEK_CHAP instructs the media device to seek to the specified chapter in a video. Behavior when this message is issued to a media device that is not in a playing state is device dependent: the request may succeed or fail, depending on the media device's capabilities and characteristics.

Buffer: uint32_t

DCMD_MEDIA_SET_REPEAT

DCMD_MEDIA_SET_REPEAT sets the repeat mode on the media device. For a list of defined repeat modes, see DCMD_MEDIA_GET_REPEAT above.

Buffer: struct _media_settings

DCMD_MEDIA_SET_SHUFFLE

DCMD_MEDIA_SET_SHUFFLE sets the random (shuffle) mode on the media device, changing the playback order. For a list of defined random modes, see DCMD_MEDIA_GET_SHUFFLE above.

Buffer: struct _media_settings

DCMD_MEDIA_SET_STATE

DCMD_MEDIA_SET_STATE restores the playback settings on the media device to the values stored in the _media_settings data structure by a devctl() call with the DCMD_MEDIA_GET_STATE message.

Buffer: uint8_t[1]