MediaFS Events

This chapter describes MediaFS events and the data structures they use.

Working with MediaFS events

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

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.

Writing events to the queue

When the device controller writes an event to the MediaFS queue, it must:

Event queue management

The device controller should ensure the following event queue behavior:


Note: In order to assure backwards compatibility with MediaFS 1.0, which did not support events, the MediaFS event queue is optional.

Reading MediaFS events

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

DCMD_MEDIA_READ_EVENTS instructs MediaFS to populate the client application's data buffer with data from the MediaFS event queue.

Buffer: char[1]

Managing your buffer when using DCMD_MEDIA_READ_EVENTS

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.

Behavior when the queue is larger than the client application buffer

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:

  1. Increase the size of the buffer it uses for the MediaFS events to at least the size returned in len.
  2. Call devctl() with the DCMD_MEDIA_READ_EVENTS message again to read the events from the queue.

Behavior when the queue is smaller than or equal to the client application buffer

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:

Event types

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.

MediaFS events and their structures

This section describes MediaFS events, organized by event type. It includes:

The _media_event data structure

_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).

Track, time and other information update events

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.

_media_event_info

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.

_media_event_time

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.

_media_event_track

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.

Metadata update events

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.

_media_event_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.

Error and warning events

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.

_media_event_error

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.

_media_event_warning

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.