Media synchronization thread actions

The media synchronization threads spawned by mm-detect handle all the interaction with mm-sync necessary to synchronize a device's media metadata. These threads also publish synchronization status updates through PPS, so client applications can learn when the media information in device databases is up to date.

Learning the procedure followed by the media synchronization threads teaches you how to invoke mm-sync from another program to ensure a device is properly synchronized. This is essential if you choose to write your own version of mm-detect.

When creating a thread for synchronizing a device's media metadata, mm-detect passes all the information it has on the newly attached device to the new thread. This information includes the device's unique ID (UID), which is also the name of the device's QDB database, and the device's mountpoint.

Each media synchronization thread performs the following actions:

  1. Connecting to mm-sync

    The thread connects to the multimedia synchronizer service (mm-sync) by calling mm_sync_connect().
  2. Registering for events

    To register for mm-sync event notifications, the synchronization thread calls mm_sync_events_register(), specifying the system event type (a pulse) and code (the pulse type) to be delivered by the OS to indicate an mm-sync event has occurred.
  3. Starting media synchronization

    The thread calls mm_sync_start() to start synchronizing the device's media metadata. The paths of the filesystem object representing the device's QDB database (/dev/qdb/<UID>) and of the device's mountpoint are provided as parameters in the mm_sync_start() call.

    The API call parameters also specify the root directory ("/") as the synchronization path and set the recursive option, instructing mm-sync to search all directories on the device for media metadata. Also included as call parameters are the flags to synchronize the file information and media creation and runtime information, but not the flag for synchronizing playlist entry information.
  4. Sending of first status update

    Just after starting the synchronization, the mm-detect thread sends a status update to the HMI through PPS. The device status is written to a special PPS object (see PPS synchronization status object).

    The status summary includes the synchronization completion flag, which is set to "false" initially to show that the device is still being synchronized. A client application within the HMI can read the status from the PPS object and learn that a device has been inserted, but its media information has not yet been updated to its database.
  5. Sending of second status update

    The mm-detect thread monitors system events as it waits for the synchronization to complete. When the thread receives from the OS the type of pulse it registered for in Step 2, the thread calls mm_sync_event_get() to read the mm-sync data.

    If the event data indicates that mm-sync has completed the file synchronization pass, mm-detect sends another status update through PPS. This time, the synchronization completion flag is set to "true" to show that the media file information in the device's database is now up to date. A client application can then display all the device's media information to users.
    Note: If the synchronization is aborted by mm-sync, the mm-detect thread receives different event data that indicates a failed synchronization operation. See the Unexpected synchronization termination subsection for details.
  6. Waiting for synchronization to complete

    After sending the second status update, the synchronization thread continues to monitor system events until it receives another pulse indicating that an mm-sync event has occurred. When the event data indicates that all synchronization passes have been completed, mm-detect updates the device's information to reflect the successful synchronization, and then proceeds to its shutdown tasks.
  7. Deregistering for events

    To stop mm-sync from sending further event notifications, mm-detect calls mm_sync_events_register(), specifying NULL as the event type.
  8. Disconnecting from mm-sync

    The mm-detect thread closes its connection to the multimedia synchronizer service by calling mm_sync_disconnect().

Unexpected synchronization termination

If the mm-sync synchronization operation fails unexpectedly, the mm-detect media synchronization thread receives a pulse from the OS indicating that an mm-sync event has occurred, and then calls mm_sync_event_get() to examine the event data. In this case, the event data indicates an aborted synchronization, so mm-detect updates its information for the device to show that the synchronization failed, and then begins its shutdown activities.

If the user removes (detaches) a device while that device is still being synchronized, mm-detect sends a special pulse to the active synchronization thread associated with the newly removed device. This pulse contains a code that tells the synchronization thread to terminate, which it does by proceeding to its shutdown tasks.