MME Events

MME events are like other QNX Neutrino events. They are signals or pulses used to notify a client application thread that a particular condition has occurred. Unlike signals and pulses, events can be used to carry data.

This chapter includes:

For information about other types of MME events, see the following chapters in this reference:

For more information about events in general, see the QNX Neutrino Programmer's Guide.

About MME events

MME events are associated with the control contexts through which the client application is connected to the MME. Each client connected to a control context has its own event queue to which the MME delivers events.

To receive events from the MME, your client application must:

See also the chapter Starting Up and Connecting to the MME in the MME Developer's Guide.

MME event classes

MME events are divided into classes, which mme_event_class_t defines as bitmasks. Its values are described in the table below.

Constant Value Description
MME_EVENT_CLASS_PLAY 0x0001 See the chapter MME Playback Events.
MME_EVENT_CLASS_SYNC 0x0002 See the chapter MME Synchronization Events.
MME_EVENT_CLASS_COPY 0x0004 See the chapter MME Media Copy and Ripping Events.
MME_EVENT_CLASS_GENERAL 0x0008 See Events not specified in the other classes below.
MME_EVENT_CLASS_METADATA 0x0010 See the chapter MME Metadata Events.
MME_EVENT_CLASS_ALL 0xFFFF All events.

The MME event classes are bitmasks. They can be used together with an OR operator to register for several events at once. For example, to register for playback and synchronization events call the function mme_register_for_events() as follows:

mme_register_for_events( hdl,
                         MME_EVENT_CLASS_PLAY | MME_EVENT_CLASS_SYNC,
                         event );

The client application can register each of its connections for any or all of these classes, as required.

MME event data

Event data is delivered in the following structures:

For more information about the structures mme_sync_data_t and mme_first_fid_data_t, and the mme_*_error_t structures, see the relevant sections below.

mme_copy_error_t

typedef struct mme_copy_error {
   uint32_t        type;
   uint64_t        cqid;
   uint32_t        reserved;
   union {
       uint64_t    value;
       uint64_t    msid;
   };
} mme_copy_error_t;

The structure mme_copy_error_t carries media copying and ripping error data. Its members are described in the table below:

Member Type Description
type uint32_t Type of media copying and ripping error.
cqid uint64_t The copy queue ID.
reserved uint32_t Reserved for internal use.
union uint64_t Either value: copy queue ID, or msid: mediastore ID.

mme_event_t

typedef struct _mme_event {
    mme_event_type_t  type;
    size_t            size;
    char              data[0];
} mme_event_t;

The structure mme_event_t is described in the table below:

Member Type Description
type mme_event_type_t The event type.
size size_t The size, in bytes of the event data.
data char The event data.

mme_event_default_language_t

#include <mme/types.h>

typedef struct s_mme_default_language_event {
    int        error;
    const char language[1];
} mme_event_default_language_t;

The data structure mme_event_default_language_t carries information delivered with a MME_EVENT_DEFAULT_LANGUAGE event, including the result of the last attempt to set the default language, and a NULL terminated string indicating the current default language. It includes at least the members described in the table below:

Member Type Description
error int The result of the last request; this member is set to EOK on success.
language const char A NULL terminated string that indicates the current default language.

mme_event_metadata_image_t

typedef struct s_mme_metadata_image_event {
    uint64_t                 mdinfo_irid;
    int32_t                  error;
    uint32_t                 reserved;
    mme_metadata_image_url_t url;
} mme_event_metadata_image_t;

The data structure mme_event_metadata_image_t carries data for the MME_EVENT_METADATA_IMAGE event. It includes at least the members listed in the table below:

Member Type Description
mdinfo_irid uint64_t A metadata image request identifier.
error int The errno returned with the request; set to EOK on success.
reserved uint32_t Reserved for internal use.
url mme_metadata_image_url_t The structure with the URL location for the image.

mme_event_metadata_info_t

typedef struct s_mme_metadata_info_event {
    uint64_t            mdinfo_rid;
    int32_t             error;
    uint32_t            reserved;
    mme_metadata_info_t metadata;
} mme_event_metadata_info_t;

The data structure mme_event_metadata_info_t carries data for the MME_EVENT_METADATA_INFO event. It includes at least the members listed in the table below:

Member Type Description
mdinfo_irid uint64_t A metadata information request identifier.
error int The errno returned with the request; set to EOK on success.
reserved uint32_t Reserved for internal use.
metadata mme_metadata_info_t The structure with the metadata.

mme_event_metadata_licensing_t

typedef struct mme_event_metadata_licensing {
    uint64_t    msid;
    uint64_t    fid;
    char        license[32];
} mme_event_metadata_licensing_t;

The data structure mme_event_metadata_licensing_t carries metadata licensing data. It includes at least the members described in the table below:

Member Type Description
msid uint64_t During mediastore synchronizations, the mediastore ID.
fid uint64_t During individual file synchronizations, the file ID.
license char The license agreement, up to 32 characters long.

mme_event_queue_size_t

typedef struct s_mme_event_queue_size {
    size_t  first_event;
    size_t  all_events;
} mme_event_queue_size_t;

The structure mme_event_queue_size_t carries data for the event MME_EVENT_BUFFER_TOO_SMALL event. It includes at least the members listed in the table below:

Member Type Description
first_event size_t The size, in bytes, of the first event.
all_events size_t The size, in bytes, of all the events in the queue.

mme_event_type_t

typedef enum mme_event_type {
	...
    MME_EVENT_*
    ...
} mme_event_type_t;

The enumerated type mme_event_type_t defines the types of events delivered by the MME. For details, see the events described in this chapter.

mme_first_fid_data_t

mme_first_fid_data {
    uint64_t    fid;
    uint64_t    msid;
    uint64_t    timestamp;
    uint32_t    operation_id;
    uint32_t	reserved;
} mme_first_fid_data_t;

The structure mme_first_fid_data_t carries the file ID (fid) and mediastore ID (msid) for the first file and mediastore found during synchronization. It has at least these members:

Member Type Description
fid uint64_t The file ID.
msid uint64_t The mediastore ID.
timestamp uint64_t During a first synchronization pass, the MME's internal timestamp from the library table last_sync field; set to 0 (zero) at the second synchronization pass.
operation_id uint32_t The ID of the synchronization process that delivers the event carrying mme_first_fid_data_t.
reserved uint32_t Reserved for internal use.

mme_folder_sync_data_t

typedef struct s_mme_folder_sync_data {
    uint64_t    msid;
    uint64_t    folderid;
    uint32_t    pass;
    uint32_t    num_files;
    uint32_t    num_folders;
    uint32_t    num_playlists;
    uint64_t    timestamp;
    uint32_t    operation_id;
    uint32_t	reserved;
} mme_folder_sync_data_t;

The data structure mme_folder_sync_data_t carries event data for folder synchronizations. It contains at least the members described in the table below:

Member Type Description
msid uint64_t The ID of the mediastore with the folder being synchronized.
folderid uint64_t The ID of the folder being synchronized.
pass uint32_t The synchronization pass this event is for; uses the MME_SYNC_OPTION_PASS_* flags.
num_files uint32_t See event specific documentation.
num_folders uint32_t See event specific documentation.
num_playlists uint32_t The number of playlists added to the playlist file.
timestamp uint64_t A timestamp of the last synchronization (last_sync value) for items associated with the event that delivers this structure.
operation_id uint32_t The operation ID.
reserved uint32_t Reserved for internal use.

mme_ms_update_data_t

typedef struct s_mms_ms_update_data {
    uint64_t	msid;
    uint64_t	added_filecount;
    uint64_t	added_foldercount;
    uint32_t	operation_id;
    uint32_t	flags;
    uint64_t	timestamp;
} mme_ms_update_data_t;

The data structure mme_ms_update_data_t carries data about files information copied during synchronizations. It is described in the table below:

Member Type Description
msid uint64_t The ID of the synchronized mediastore.
added_filecount uint64_t The number of file IDs (fids) added to the MME database by this synchronization.
added_foldercount uint64_t The number of folders added to the MME database by this synchronization.
operation_id uint32_t The operation ID.
flags uint32_t The type of operation. See flags below.
timestamp uint64_t The time stamp to write in the last_sync column for items associated with the event that carries this data structure.

flags

The mme_ms_update_data_t member flags can have the following values:

flags Meaning
0 Not a synchronization operation
MME_SYNC_OPTION_PASS_FILES Synchronization pass 1
MME_SYNC_OPTION_PASS_METADATA Synchronization pass 2
MME_SYNC_OPTION_PASS_PLAYLISTS Synchronization pass 3

mme_play_command_error_t

typedef struct mme_play_command_error {
    uint32_t    command;
    uint32_t    button;
    uint64_t    fid;
} mme_play_command_error_t;

The structure mme_play_command_error_t carries the playback error types. Its members are described in the table below:

Member Type Description
command mme_command_type_t Command error data.
button uint32_t Button error data.
fid uint32_t The file ID of the file being accessed when the error occurs.

mme_play_error_t

typedef struct mme_play_error {
   uint32_t                     type;
   uint32_t                     reserved;
   union {
      uint64_t                  value;
      uint64_t                  fid;
      uint64_t                  trksessionid;
      uint64_t                  msid;
      uint64_t                  outputid;
      mme_play_command_error_t  command_error;
      mme_play_error_track_t    track;
  };
} mme_play_error_t;

The structure mme_play_error_t carries playback error data. Its members are described in the table below:

Member Type Description
type uint32_t The type of playback error; see Playback error events in the chapter MME Playback Events.
reserved uint32_t Reserved for internal use.
value uint64_t The error value.
fid uint64_t The file ID.
trksessionid uint64_t The track session ID.
msid uint64_t The mediastore ID.
outputid uint64_t The output ID.
command_error_t mme_play_command_error_t The command error type.
mme_play_error_track_t mme_play_error_track_t The file ID or the offset of the track that generated the error.

mme_play_error_track_t

typedef struct mme_play_error_track {
    uint64_t                fid;
    uint64_t                offset;
} mme_play_error_track_t;

The data structure mme_play_error_track_t carries the file ID or the offset in the track session of the track where a playback error occurred. It contains the following members:

Member Type Description
fid uint64_t The file ID of the track where an error occurred; used for library-based track sessions.
offset uint64_t The offset of the track where an error occurred; used for file-based track sessions.

mme_sync_data_t

typedef struct mme_sync_data {
    uint64_t    msid;
    uint32_t    operation_id;
   uint32_t    reserved;
} mme_sync_data_t;

The structure mme_sync_data_t carries data for many synchronization events (MME_EVENT_MS_SYNC_*). It has these members:

Member Type Description
msid uint64_t The mediastore ID.
operation_id uint32_t The synchronization operation ID.
reserved uint32_t Reserved for internal use.

mme_sync_error_t

typedef struct mme_sync_error {
    uint32_t    type;
    uint32_t    operation_id;
    uint32_t    param;
    uint32_t    reserved;
    uint64_t    msid;
} mme_sync_error_t;

The structure mme_sync_error_t carries synchronization error data. Its members are described in the table below:

Member Type Description
type uint32_t The type of synchronization error.
operation_id uint32_t The synchronization operation ID.
param uint32_t Parameters for the synchronization.
reserved uint32_t Reserved for internal use.
msid uint64_t The mediastore ID.

mme_trackchange_t

typedef struct mme_trackchange {
   uint64_t    fid;
   uint64_t    fid_requested;
   uint64_t    offset;

} mme_trackchange_t;

The data structure mme_trackchange_t carries data for the MME_EVENT_TRACKCHANGE event. It is described in the table below:

Member Type Description
fid uint64_t The file ID of the track being played.
fid_requested uint64_t The file ID that was requested for playback. In most cases fid and fid_requested will have the same values. However, when playback occurs during a ripping operation, fid and fid_requested may be different, because the client application may request playback of a track from the source, such as a CDDA, but the MME will play the ripped destination file on the HDD.
offset uint64_t The current offset in the track session.

mm_warning_info_t

typedef struct s_mm_warning_info {
	_Uint32t mm_warning;	/* mm_warnings_t */
	_Uint32t flags;			/* mm_warning_flags_t */
} mm_warning_info_t;

The structure mm_warning_info_t carries information about the conditions that have caused a warning. It contains at least the members described in the table below.

Member Type Description
mm_warning mme_warnings_t The type of warning condition reported byio-media.
flags mme_warning_flags_t Information about the conditions that caused the warningPlayback warnings for io-media.

mm_warnings_t

The enumerated type mm_warnings_t defines the type of warning condition detected. Its values and the behaviors they define are described below:

mm_warning_flags_t

The enumerated type mm_warning_flags_t defines the state of an MME operation associated with a warning. Its values and the behaviors they define are described below:

MME general events

The MME delivers general events (MME_EVENT_CLASS_GENERAL) to the client application to indicate changes in status, or the result of an activity.

The MME general events are:

MME_EVENT_AUTOPAUSECHANGED

The MME delivers the event MME_EVENT_AUTOPAUSECHANGED after it has changed the autopause mode for a specified control context.

To change the autopause mode for a control context, call the function mme_setautopause().

Event data

The new autopause setting, in a uint64_t:

1
Enabled.
0
Disabled.

Database tables updated

No database tables are updated.

MME_EVENT_BUFFER_TOO_SMALL

The MME delivers the event MME_EVENT_BUFFER_TOO_SMALL to a client application when the client application's event buffer is too small to retrieve any events from the MME.

Event data

The size, in bytes, of the first event in the event buffer, in mme_event_queue_size_t.first_event, and the size of all the events in the event queue, in mme_event_queue_size_t.all_events.

Database tables updated

No database tables are updated.

MME_EVENT_DEFAULT_LANGUAGE

The MME function mme_media_set_def_lang() delivers the event MME_EVENT_DEFAULT_LANGUAGE to indicate that the default preferred language for a media item has been set.

Event data

The success or failure of the default preferred language update, and the preferred language, in mme_event_default_language_t.


Note: The string in mme_event_default_language_t.language always indicates the current default preferred language. That is, if mme_media_set_def_lang() is unable to change the default language to the requested language, this string will indicate the preferred language before the function call was made (because it is still the set preferred language).

Database tables updated

No database tables are updated.

MME_EVENT_NONE

The MME delivers the event MME_EVENT_NONE to a client application when there are no events in the queue for the control context from which the client application requested events.

To request events, use the function mme_get_event().

Event data

No data.

Database tables updated

No database tables are updated.

MME_EVENT_SHUTDOWN

The MME delivers the event MME_EVENT_SHUTDOWN to all control contexts after it receives a request to shut down. If your client application receives this event, it should inform the user that it is shutting down.

To shut down the MME, call the function mme_shutdown().


Note: The function mme_shutdown() returns immediately and shuts down MME threads in the background. This behavior means that the MME may deliver other events after it has delivered MME_EVENT_SHUTDOWN. When all MME threads have shut down, the MME delivers the event MME_EVENT_SHUTDOWN_COMPLETED.

Event data

No data.

Database tables updated

No database tables are updated.

MME_EVENT_SHUTDOWN_COMPLETED

The MME delivers the event MME_EVENT_SHUTDOWN_COMPLETED to all control contexts to indicate that it has completed its shutdown preparations. Playback, ripping and synchronization operations have been stopped.

Event data

No data.

Database tables updated

No database tables updated.


Caution: Operations attempted with the MME after it has delivered the MME_EVENT_SHUTDOWN_COMPLETED event may produce unexpected results and compromise the integrity of your system. To use the MME after receiving the MME_EVENT_SHUTDOWN_COMPLETED event, you should terminate the MME, then start it again.

MME_EVENT_USERMSG

Not currently implemented.