![]() |
![]() |
![]() |
![]() |
This chapter describes MediaFS events and the data structures they use.
MediaFS supports events for communication between devices and upper-level applications. A device driver should, therefore, be designed to write, whenever the underlying device changes state, the appropriate MediaFS events and their payloads to the MediaFS event queue so that they can be read by client applications.
This section presents:
For a complete list of supported MediaFS event types, events and event data structures, see “MediaFS events and their structures” below.
The MediaFS event queue is the means by which a device driver can communicate playback status changes and updates, and device state changes to client applications in the sequence in which they occur.
The MediaFS event queue:
The MediaFS queue's FIFO behavior means that a client reading items from the queue will always receive events in chronological order.
When the device controller writes an event to the MediaFS queue, it must:
The device controller should ensure the following event queue behavior:
![]() |
In order to assure backwards compatibility with MediaFS 1.0, which did not support events, the MediaFS event queue is optional. |
Multimedia applications using MediaFS should be designed to use devctl() calls with the DCMD_MEDIA_READ_EVENTS to read events from the MediaFS event queue, and to use the information provided by these events to manage media playback and other activities. To read MediaFS events, an application must call the devctl() function with the DCMD_MEDIA_READ_EVENTS message.
DCMD_MEDIA_READ_EVENTS instructs MediaFS to populate the client application's data buffer with data from the MediaFS event queue.
Buffer: char[1]
The DCMD_MEDIA_READ_EVENTS is used to instruct MediaFS to populate the client application's data buffer with data from the MediaFS event queue. It is the responsibility of the client application to ensure that it has a buffer large enough for the events in the MediaFS event queue.
If the number of bytes of data in the event queue is greater than the size of the client application's data buffer, a call to devctl() with the DCMD_MEDIA_READ_EVENTS message will:
In this case, the client application should:
If the number of bytes of data in the event queue is less than or equal to the size of the client application's data buffer, a call to devctl() with the DCMD_MEDIA_READ_EVENTS message will:
MediaFS uses five types of events. Values for these event types are carried in the _media_event structure's type member. They are described in the table below:
Event type | Value | Description |
---|---|---|
MEDIA_EVENT_ERROR | 0 | Error |
MEDIA_EVENT_WARNING | 1 | Warning |
MEDIA_EVENT_TRACK | 2 | Communicate a track information change. |
MEDIA_EVENT_TIME | 3 | Communicate a time update. |
MEDIA_EVENT_METADATA | 4 | Communicate changes to metadata. |
This section describes MediaFS events, organized by event type. It includes:
_media_event struct _media_event { uint32_t type; uint32_t len; };
The _media_event structure is a included in all other MediaFS event structures. It specifies the event type, and the length of the event data. This structure includes at least the members described in the table below.
Member | Type | Description |
---|---|---|
type | uint32_t | The event type; see “Event types” above. |
len | uint32_t | The length of the event data, in bytes (including padding to 8-byte alignment). |
MediaFS information events signal an update to track or time information for the specified media track or file. Depending on the type of information they communicate, these events carry either the _media_event_info, the _media_event_time or the _media_event_track data structure.
The table below describes the MediaFS track and time update events:
Event | Value | Description |
---|---|---|
MEDIA_EVENT_INFO_UNKNOWN | 0 | Events carrying information, such as time or track updates, about a track or media file. |
struct _media_event_info { struct _media_event event; uint32_t index; uint32_t type; char value[1]; };
The _media_event_info structure contains track or media file information. It should be populated when track or media file information changes, and, if relevant, included with the information events that MediaFS places in its event queue.
Member | Type | Description |
---|---|---|
event | struct | The _media_event structure with the event type and size. |
index | uint32_t | The index number for the track to which the event is associated. |
type | uint32_t | The type of information event; see “Track, time and other information update events” above. |
value [1] | char | A character string with the changed track information. |
struct _media_event_time { struct _media_event event; uint32_t index; uint32_t elapsed; uint32_t duration; };
The _media_event_time structure contains track or media file time information. It should be populated when track or media file time information changes, and, if relevant, included with the information events that MediaFS places in its event queue.
Member | Type | Description |
---|---|---|
event | struct | The _media_event structure with the event type and size. |
index | uint32_t | The index number for the track to which the event is associated. |
elapsed | uint32_t | The elapsed time for the current track, in milliseconds. |
duration | uint32_t | The track duration (total time) of the current track, in milliseconds. |
struct _media_event_track { struct _media_event event; uint32_t index; uint32_t duration; char trackpath[1]; };
The _media_event_track structure contains track or media file information. It should be populated when track or media file information changes, and, if relevant, included with the information events that MediaFS places in its event queue.
Member | Type | Description |
---|---|---|
event | struct | The _media_event structure with the event type and size. |
duration | uint32_t | The track duration (total time) of the current track, in milliseconds. |
trackpath | char | A character string with the path (relative to the mountpoint) of the current media file or track. |
MediaFS metadata events signal an update or other change to metadata for the specified media track or file. These events carry the data structure _media_event_metadata.
The table below describes the MediaFS metadata update events:
Event | Value | Description |
---|---|---|
MEDIA_EVENT_METADATA_UNKNOWN | 0 | An unspecified change has been made to the file's metadata. |
MEDIA_EVENT_METADATA_SONG | 1 | Change to the file's song metadata. |
MEDIA_EVENT_METADATA_ALBUM | 2 | Change to the file's album metadata. |
MEDIA_EVENT_METADATA_ARTIST | 3 | Change to the file's artist metadata. |
MEDIA_EVENT_METADATA_GENRE | 4 | Change to the file's genre metadata. |
MEDIA_EVENT_METADATA_COMPOSER | 5 | Change to the file's composer metadata. |
MEDIA_EVENT_METADATA_RELEASE_DATE | 6 | Change to the file's release date metadata. |
MEDIA_EVENT_METADATA_TRACK_NUM | 7 | Change to the file's track number metadata. |
MEDIA_EVENT_METADATA_PUBLISHER | 8 | Change to the file's publisher metadata. |
MEDIA_EVENT_METADATA_DURATION | 9 | Change to the file's duration metadata. |
MEDIA_EVENT_METADATA_NAME | 10 | Change to the file's name metadata. |
MEDIA_EVENT_METADATA_COMMENT | 11 | Change to the file's comment metadata. |
struct _media_event_metadata { struct _media_event event; uint32_t type; uint32_t index; uint32_t duration; struct _media_date date; char value[1]; };
The _media_event_metadata structure contains track metadata. It should be populated whenever metadata for a track or media file changes, and included with the metadata update events that MediaFS places in its event queue.
Member | Type | Description |
---|---|---|
event | struct | The _media_event structure with the event type and size. |
type | uint32_t | The type of metadata event; see “Metadata update events” above. |
index | uint32_t | The index number for the track to which the event is associated. |
duration | uint32_t | The track date. |
date | struct | The _media_date structure with the track date information. |
value [1] | char | A UTF-8 encoded character string for character-based metadata types. |
MediaFS error and warning events signal an error or other condition that requires attention from the client application. These events carry, respectively, the data structure _media_event_error or _media_event_warning.
The table below describes the MediaFS error and warning events:
Event | Value | Description |
---|---|---|
MEDIA_EVENT_ERROR_UNKNOWN | 0 | An unspecified error condition has occurred. |
MEDIA_EVENT_ERROR_DRM | 1 | A DRM error has occurred. |
MEDIA_EVENT_ERROR_CORRUPT | 2 | The media file is corrupt. |
MEDIA_EVENT_WARNING_UNKNOWN | 0 | An unspecified condition that requires attention has occurred. |
struct _media_event_error { struct _media_event event; uint32_t index; uint32_t type; };
The _media_event_error structure contains track or media file error information. It should be populated when an error is encountered with a track or media file, and included with the error events that MediaFS places in its event queue.
Member | Type | Description |
---|---|---|
event | struct | The _media_event structure with the event type and size. |
index | uint32_t | The index number for the track to which the event is associated. |
type | uint32_t | The type of error event; see “Error and warning events” above. |
struct _media_event_warning { struct _media_event event; uint32_t index; uint32_t type; };
The _media_event_warning structure contains track or media file error information. It should be populated when a warning situation is encountered with a track or media file, and included with the error events that MediaFS places in its event queue.
Member | Type | Description |
---|---|---|
event | struct | The _media_event structure with the event type and size. |
index | uint32_t | The index number for the track to which the event is associated. |
type | uint32_t | The type of warning event; see “Error and warning events” above. |
![]() |
![]() |
![]() |
![]() |