To synchronize metadata, applications must learn about mediastore mountpoints through PPS and explore these mountpoints to determine which files and folders need to have their metadata synchronized. Then, they must provide mm-sync with a mountpoint and synchronization path to upload the required metadata from a mediastore to its database.
Monitor mediastore mounting
To monitor mediastore mounting, the application can subscribe to the /pps/qnx/mount/.all PPS object. When the user attaches a device and one or more mediastores on it get mounted, the appropriate device publisher writes the mount information to this object. For USB-connected devices (e.g., Apple devices, USB sticks), the usblauncher service publishes this information; for SD cards, mmcsdpub publishes it; for CDs, cdpub publishes it.
Load the database for a newly mounted mediastore
When the application notices a new entry in the .all object, it must read that entry's id attribute to obtain the mediastore's unique ID. Then, it can check if the database whose name contains this unique ID is loaded and if it's not, load that database. Information on doing so is given in the “Loading QDB databases” entry in the QDB Developer's Guide.
You must load a database before trying to synchronize or play media on the associated mediastore because the mm-sync and mm-renderer services can't load databases.
Determine the media content to synchronize
Next, the application must read the mount attribute in the .all object entry to learn the mediastore's mountpoint. From this mountpoint, it can explore the mediastore's files and folders to determine which ones need to have their metadata synchronized.
The decision to synchronize specific files or folders may depend on their last synchronization time (if known), the available system resources, and the mediastore's type. New files and folders must be synchronized if they contain media that the user might play. Folders with fewer files than before have to be resynchronized if you want their database information to be up to date.
Connect to mm-sync
If no content needs to be synchronized, the application can skip the rest of these steps and start querying the database to retrieve media information and then using it. Otherwise, the application must begin interacting with mm-sync by calling mm_sync_connect().
Register for mm-sync events
An application can request to receive event notifications by calling mm_sync_events_register(). The function's event argument must be set to a struct sigevent object initialized with the type of notification to deliver with each event. Event notifications let clients monitor synchronization progress and learn of any errors that occur.
Start synchronizing media content
The application can start synchronizing media content by calling mm_sync_start(). The function call must specify the path of the device object used by the mediastore's database. This object is kept in /pps/qdb/ and has the same name as the database. The call must also name the mediastore mountpoint and a synchronization path, to indicate what content is being synchronized.
The mm_sync_start() function returns a synchronization ID, which you must provide in subsequent API calls (e.g., mm_sync_status_get_byid()) to refer to the same operation.
Monitor mm-sync events
To monitor mm-sync events, the application must make the appropriate system call to wait for the notification defined in Step 5. When it recieves that notification, it can then call mm_sync_events_get() to retrieve the event information.
The MMSYNC_EVENT_MS_SYNCCOMPLETE event means that all requested media information has been uploaded to the database. At this point, if the mediastore is removed, the application can still provide users with information about its synchronized content (although playback requires the mediastore to be present).
Disconnect from mm-sync
If the client needs to synchronize metadata from another path, it can repeat Step 6 to start a new synchronization. The decision to synchronize more metadata might depend on user activity. For instance, if the user selects another album from a cover flow of available albums, the application then needs to synchronize the metadata from the mediastore path that stores the album's tracks.
When it has synchronized all of the metadata that it needs, the application can disconnect from mm-sync by calling mm_sync_disconnect().
After completing these steps, an application can query databases to read up-to-date file, content creation, and playback information for media files found on mediastores previously connected to the target system. These media files can include audio tracks, video files, and photos.
Any database must be kept in memory as long as the application needs to access metadata related to content kept on the associated mediastore. This may be for long after the synchronization finishes. For details on unloading databases, see “Unloading QDB databases” in the QDB Developer's Guide.
You can synchronize content incrementally through directed synchronizations, which entail giving mm_sync_start() a synchronization path that names specific folders or files. After a directed synchronization completes, you can examine the files and folders database tables and pick a specific subfolder to synchronize next. This way, you can explore a mediastore with database queries and synchronizations of individual folders.