Synchronizing media content from applications

Media applications can manually detect mediastore attachments and start synchronizations. To do this, applications must read a PPS object to learn the mediastore mountpoints and, from these mountpoints, explore device filesystems to determine the paths of the files to be synchronized. The mountpoints and synchronization paths are needed by mm-sync.

To detect a mediastore and synchronize its media metadata, your application must:
  1. Monitor mediastore attachments

    Your application must subscribe to the /pps/qnx/mount/.all PPS object to monitor mediastore attachments. When the user attaches a mediastore, the appropriate device publisher writes the device's information to this object. For devices connected through USB (e.g., iPods and USB sticks), the usblauncher service publishes the device information; for SD cards, the mmcsdpub service publishes it.

  2. Load the database for a newly attached mediastore

    When your application notices a new entry in the .all object, it must read that entry's id attribute to obtain the mediastore's unique ID. Your application can then check if the database whose name contains this unique ID is loaded and if not, load that database by writing its configuration object into the QDB database configuration directory (/pps/qnx/qdb/config/).

    You must load a database before trying to synchronize or play media content on the corresponding device because the mm-sync and mm-renderer services can't load databases. For more details on loading databases, see "Loading QDB databases".

  3. Determine the media content to synchronize

    Before it can determine what content needs to be synchronized, your application must read the mount attribute in the .all object entry to learn the mediastore's mountpoint. From this mountpoint, your application can explore the mediastore's content and read file information.

    The decision to synchronize specific files or folders can depend on many factors, including 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 may need to be resynchronized to ensure that their database information is up to date.

  4. Connect to mm-sync

    If no content needs to be synchronized, your application can skip the rest of these steps and start querying the database to retrieve media metadata and use it as desired. Otherwise, your application must connect to mm-sync by calling mm_sync_connect(), so it can then use the service to upload the media metadata.

  5. Register for mm-sync events

    Your 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 allow you to track synchronization progress and to learn of any errors that occur.

  6. Start synchronizing media content

    Your application can now start synchronizing media content by calling mm_sync_start(). In this funcation call, you must provide the path of the device object used by the mediastore's database, the mediastore's mountpoint, and a synchronization path containing the content that you want to synchronize. The device object is stored in /pps/qdb/ and has the same name as the database.

    The function call returns a synchronization ID, which you must provide in subsequent API calls (e.g., sync_status_get_byid()) to refer to the same synchronization operation.

  7. Monitor mm-sync events

    To monitor mm-sync events, your application must make the appropriate OS system call to wait for the notification defined in Step 5. When it recieves that notification, your application must call mm_sync_events_get() to retrieve the event information.

    The MMSYNC_EVENT_MS_SYNCCOMPLETE event means that all the media information that you requested has been uploaded to the database, so you can now use that information.

  8. Disconnect from mm-sync

    If your application needs to synchronize metadata from another path, it can return to Step 6 to start a new synchronization. The decision to synchronize more metadata might depend on user activity. For instance, if you display a cover flow to represent the available albums, the user could select another album and your application would then need to synchronize the metadata found in the mediastore path that stores the album's tracks.

    When it has synchronized all the media metadata it needs, your application can disconnect from mm-sync by calling mm_sync_disconnect().

The database for the newly attached mediastore contains the media metadata required by your application. You can issue SQL queries against the database to read the file information and the creation and display information for audio tracks, video files, and photos on the mediastore. You must keep the database in memory for as long as your application needs to access metadata related to the media content on the mediastore. This may be long after you've finished synchronizing the metadata to the database. For details on unloading databases, see "Unloading QDB databases".

Exploring mediastores through directed synchronizations

You can synchronize content incrementally through directed synchronizations, which entail giving mm_sync_start() a synchronization path of one folder. After a synchronization completes, you can examine the files and folders database tables and pick a specific subfolder to synchronize in the next mm_sync_start() call. In this manner, you can explore a mediastore by using database queries and directed synchronizations.