MME Synchronization 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 other 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.

Synchronization events

The MME delivers synchronization events (MME_EVENT_CLASS_SYNC) to the client application to indicate the status or result of a synchronization.

The MME synchronization events are:

MME_EVENT_MS_DETECTION_DISABLED

The MME synchronization event MME_EVENT_MS_DETECTION_DISABLED is for future use.

Event data

No event data is delivered.

Database table updated

No database tables are updated.

MME_EVENT_MS_DETECTION_ENABLED

The MME delivers the synchronization event MME_EVENT_MS_DETECTION_ENABLED when it has successfully read a path monitoring configuration, connected to a path monitoring system, and enabled device detection.

Event data

No event data is delivered.

Database table updated

The following table is updated:


Note: After the MME delivers the event MME_EVENT_MS_DETECTION_ENABLED it may begin processing mediastore state changes and updating the mediastores table accordingly.

MME_EVENT_METADATA_LICENSING

The MME delivers the synchronization event MME_EVENT_METADATA_LICENSING when it uses a metadata service that has special licensing requirements, such as a requirement to display the service's logo. The MME delivers this event each time it begins using the metadata service.

Event data

This event delivers the following data, in mme_event_metadata_licensing_t, as follows:

Database table updated

No database tables are updated.

MME_EVENT_MS_1PASSCOMPLETE

The MME delivers the event MME_EVENT_MS_1PASSCOMPLETE when it has completed the first pass of file and folder synchronization between a mediastore and the MME library.

With the first synchronization pass the MME:

When it finds a file on the mediastore, the MME:

When it finds a folder (directory) on the mediastore, the MME:

The MME adds files only if their extensions match the media support extensions defined by the in element <SyncFileMask> in the file configuration file mme.conf. For more information, see Configurable file skipping: <SyncFileMask> in the chapter Configuring Media Synchronizations in the MME Configuration Guide.

When the first synchronization pass is complete:

When it has completed the first synchronization pass, the MME sets to 1:

Event data

The synchronization data, in mme_sync_data_t:

Database tables updated

The following tables are updated:

MME_EVENT_MS_2PASSCOMPLETE

The MME delivers the event MME_EVENT_MS_2PASSCOMPLETE to inform the client application that it has completed the second pass of file and folder synchronization.

When the second synchronization pass is complete:

When it has completed the second synchronization pass, the MME adds the value 2 to the value of:

Thus, when the MME has completed the second syncrhonization pass, the updated fields syncflags and synced in the mediastores and folders tables have the value 3.

Event data

The synchronization data, in mme_sync_data_t:

Database tables updated

The following tables are updated:

MME_EVENT_MS_3PASSCOMPLETE

The MME delivers the event MME_EVENT_MS_3PASSCOMPLETE when it has completed the third pass of file and folder synchronization for a mediastore.

During the third synchronization pass the MME:

When the third synchronization pass is complete the MME has accurate and complete playlists for the mediastore.

When it has completed the second synchronization pass, the MME adds the value 4 to the value of:

Thus, when the MME has completed the third syncrhonization pass, the updated fields syncflags and synced in the mediastores and folders tables have the value 7.

Event data

The synchronization data, in mme_sync_data_t:

Database tables updated

The following tables are updated:

MME_EVENT_MS_STATECHANGE

The MME delivers the event MME_EVENT_MS_STATECHANGE when it has detected that a mediastore state has changed. Mediastore state changes occur when a mediastore:

A mediastore state change indicates only the state of the mediastore in the system. It does not provide information about the state of the mediastore synchronization.

Event data

The mediastore state data, in mme_ms_statechange_t:

Database tables updated

The following table is updated:

MME_EVENT_MS_SYNCCOMPLETE

The MME delivers the event MME_EVENT_MS_SYNCCOMPLETE when it has successfully completed all requested synchronization passes for a mediastore.

When the synchronization is complete:

Different mediastore types may require different synchronization activities, including a different number of synchronization passes. If it checks for the MME_EVENT_MS_SYNCCOMPLETE event, the client application does not need to know the number of synchronization passes required for a media type. When it receives the MME_EVENT_MS_SYNCCOMPLETE event the client application knows that the MME has successfully completed all requested synchronization activity required for the mediastore.


Note: Receiving the event MME_EVENT_MS_SYNCCOMPLETE does not mean that there will necessarily be files to play. For example, requesting only the second synchronization pass won't populate the MME tables with the minimum information needed to build track sessions and playing tracks.


Note: When the MME synchronizes prunable mediastores that it has synchronized earlier, the MME may clean up unused metadata in its database. This clean up may take up to several seconds, depending on the size of the MME database, and cause a corresponding delay between delivery of the MME_EVENT_MS_*PASSCOMPLETE event and delivery of the MME_EVENT_MS_SYNCCOMPLETE event. For more information, see Database clean up during synchronization in the chapter Synchronizing Media of the MME Developer's Guide.

Event data

The synchronization data, in mme_sync_data_t:

Database tables updated

The following tables are updated:

For more details, see the information for the specific synchronization passes.

MME_EVENT_MS_SYNC_FIRST_EXISTING_FID

The MME delivers the event MME_EVENT_MS_SYNC_FIRST_EXISTING_FID to inform the client application that it has a track or file that it can begin playing. It delivers this event under the following conditions:

Unlike MME_EVENT_MS_SYNCFIRSTFID, whose delivery confirms that all items in the database are valid, MME_EVENT_MS_SYNC_FIRST_EXISTING_FID only informs the client application that a playable file has been found. If the synchronization operation is pruning files from the database, there is no guarantee that all items in the database are valid.

The MME delivers this event on all (initial and subsequent) first synchronization passes of a mediastore, and when a new file has been synchronized during file synchronization (with mme_sync_file()).

Event data

The file ID (fid) and the mediastore ID (msid) of the first playable track or file:

Database tables updated

No database tables are updated.

MME_EVENT_MS_SYNCFIRSTFID

The MME delivers the event MME_EVENT_MS_SYNCFIRSTFID to:

The MME delivers this event under the following conditions:

The MME delivers this event on all (initial and subsequent) first synchronization passes of a mediastore, and when a new file has been synchronized during file synchronization (with mme_sync_file()).

Event data

The file ID (fid) and the mediastore ID (msid) of the first playable track or file, in mme_first_fid_data_t:

Database tables updated

No database tables are updated.

MME_EVENT_MS_SYNC_FOLDER_COMPLETE

The MME delivers the event MME_EVENT_MS_SYNC_FOLDER_COMPLETE when it completes a non-recursive synchronization of all files in a folder, and when the child folders in that folder have been enumerated.

Event data

The event data delivered differs between the first and second synchronization passes:

Database table updated

The following table is updated:

MME_EVENT_MS_SYNC_FOLDER_CONTENTS_COMPLETE

The MME delivers the event MME_EVENT_MS_SYNC_FOLDER_CONTENTS_COMPLETE when it completes a recursive synchronization of all files and child folders in a folder. It does not deliver this event when is completes a non-recursive synchronization of a folder.

Event data

mme_folder_sync_data_t.num_folders with the number of synchronized child folders in this folder, and mme_folder_sync_data_t.num_files set to 0 (zero).

Database table updated

The following table is updated:

MME_EVENT_MS_SYNC_FOLDER_STARTED

The MME delivers the event MME_EVENT_MS_SYNC_FOLDER_STARTED when it begins synchronization of a folder; specifically, delivery is:

Event data

mme_folder_sync_data_t, with the number of files and the number of child folders in the folder being synchronized set to 0 (zero).

Database table updated

The following table is updated:

MME_EVENT_MS_SYNC_PENDING

The MME delivers the event MME_EVENT_MS_SYNC_PENDING when it has placed a mediastore on the synchronization pending list because it does not have a synchronization thread available to perform the synchronization.

Event data

The synchronization data, in mme_sync_data_t:

Database tables updated

No database tables are updated.

MME_EVENT_MS_SYNC_STARTED

The MME delivers the event MME_EVENT_MS_SYNC_STARTED when it has started synchronization of a mediastore.

Event data

The synchronization data, in mme_sync_data_t:

Database tables updated

The following tables are updated:

MME_EVENT_MS_UPDATE

The MME delivers the event MME_EVENT_MS_UPDATE when it writes new data to the MME database during:

Delivery of MME_EVENT_MS_UPDATE other than during a synchronization operation indicates one of the following:

Event data

This event carries data about the operation, in mme_ms_update_data_t.

Database tables updated

The MME updates different tables, depending on the operation that delivers the event. The type of operation is indicated by the value of mme_ms_update_data_t.flags carried by the event.

flag=0
library
library_*
flag=MME_SYNC_OPTION_PASS_FILES
folders
library
mediastores
playlists
flag=MME_SYNC_OPTION_PASS_METADATA
folders
library
library_*
mediastores
flag=MME_SYNC_OPTION_PASS_PLAYLISTS
mediastores
playlists
playlistsdata

MME_EVENT_SYNCABORTED

The MME delivers the event MME_EVENT_SYNCABORTED when a synchronization operation is aborted. When this event is delivered, the mediastore is partially synchronized with the library. The extent of this synchronization can vary greatly, depending on how far the synchronization had progressed.

Event data

The synchronization data, in mme_sync_data_t:

Database tables updated

No database tables are updated.

MME_EVENT_SYNC_ERROR

The MME delivers the event MME_EVENT_SYNC_ERROR when an error occurs during a synchronization operation. The cause of the error is carried in the event data.

Event data

The synchronization error code, in mme_sync_error_t.

Database tables updated

No database tables are updated.

MME_EVENT_SYNC_SKIPPED

The MME delivers the event MME_EVENT_SYNC_SKIPPED when it has detected the insertion of a mediastore, but has not automatically started synchronization of this mediastore. When the client application receives this event it can request a synchronization of the mediastore.

This event is delivered if a mediastore is inserted into the system and any of the following conditions is true:

Event data

The ID of the inserted mediastore, in a uint64_t.

Database tables updated

No database tables are updated.

Synchronization error events

The MME synchronization error events are defined by the enumerated type mme_sync_error_type_t:

typedef enum mme_sync_error_type {
    ...
    MME_SYNC_ERROR_*
    ...
} mme_sync_error_type_t;

The MME synchronization error events are:

MME_SYNC_ERROR_MEDIABUSY

The MME delivers the event MME_SYNC_ERROR_MEDIABUSY after it fails to start start synchronization of a mediastore because the mediastore was being used by a process, such as playback, that has higher priority than synchronization.

Event data

The ID of the skipped mediastore, in a uint64_t.

Database tables updated

No database tables are updated.

MME_SYNC_ERROR_NETWORK

The MME delivers the event MME_SYNC_ERROR_NETWORK when it is unable to complete a synchronization because of a network error.

Event data

The ID of the mediastore that was not synchronized, in a uint64_t.

Database tables updated

No database tables are updated.

MME_SYNC_ERROR_FOLDER_DEPTH_LIMIT

The MME delivers the event MME_SYNC_ERROR_FOLDER_DEPTH_LIMIT when it has skipped sychronizing a folder to avoid synchronizing beyond the permitted depth, set by the <MaxRecursionDepth> configuration element. The MME delivers this event the first time it skips a folder because it has reached the maximum configured recursion depth.

Event data

Synchronization information in mme_sync_error_t, including

Event data

Media status information, and the reason for delivery of the event, in mm_media_status_event_t.

Database tables updated

No database tables are updated.

MME_SYNC_ERROR_FOLDER_LIMIT

The MME delivers the event MME_SYNC_ERROR_FOLDER_LIMIT during the first synchronization pass, when it has reached the configured maximum number of items (files and folders) permitted in a folder. This error event does not indicate a terminal event. It informs the client application that:

Event data

This event carries:

Database tables updated

No database tables are updated.

MME_SYNC_ERROR_LIB_LIMIT

The MME delivers the event MME_SYNC_ERROR_LIB_LIMIT during the first synchronization pass, when it can add no more entries to the library table. This error event does not indicate a terminal event. It informs the client application that:

Event data

This event carries:

Database tables updated

No database tables are updated.

MME_SYNC_ERROR_NOTSPECIFIED

The MME delivers the event MME_SYNC_ERROR_NOTSPECIFIED at any time during a synchronization process that it must stop synchronization due to an error not covered by the other error events.

Event data

The ID of the mediastore that was not synchronized, in a uint64_t.

Database tables updated

No database tables are updated.

MME_SYNC_ERROR_READ

The MME delivers the event MME_SYNC_ERROR_READ when it encounters a read error that prevents the mediastore from being synchronized. Read errors can be caused by scratched disks, or other similar faults in the mediastore.

Event data

The ID of the mediastore with the problem, in a uint64_t.

Database tables updated

No database tables are updated.

MME_SYNC_ERROR_UNSUPPORTED

The MME delivers the event MME_SYNC_ERROR_UNSUPPORTED when it is unable to start a synchronization because it does not support the mediastore format.

Event data

The ID of the mediastore that was not synchronized, in a uint64_t.

Database tables updated

No database tables are updated.

MME_SYNC_ERROR_USERCANCEL

The MME delivers the event MME_SYNC_ERROR_USERCANCEL when it stopped synchronization of mediastore in response to a cancellation request from the client application.

Event data

The ID of the mediastore that was not synchronized, in a uint64_t.

Database tables updated

No database tables are updated.