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:
- Connecting to mm-sync
The thread connects to the
multimedia synchronizer service (mm-sync) by calling
mm_sync_connect().
-
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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.