Unsynchronized Media

The MME provides an extensive API for exploring and browsing unsynchronized mediastores.

Exploring unsynchronized mediastores

The MME's mediastore explorer API can be used to provide the end-user with the following information from an unsynchronized mediastore, such as an iPod. It provides:


Caution: Retrieving more items than can be shown at one time in the HMI display window reduces system responsiveness:
  • Always request a number of items less than or equal to the number of items that can be shown at one time in the HMI display window size.
  • Adjust the number of items requested to correspond to changes to the size of the HMI display window.

The explorer API includes the following functions, structures and constants:

Exploring a mediastore

To explore an unsynchronized mediastore:

  1. Call mme_explore_start(), passing it the path to the folder you want to explore. This function returns a handle, mme_explore_hdl_t, which you can use with the other explorer functions to explore the folder.
  2. Optional tasks:
  3. Begin exploring the items in the folder, starting at the specified offset, by calling mme_explore_info_get(). Each time you call this function, the offset will increment by one, so that the next call to mme_explore_info_get() retrieves information for the next item in the folder. When mme_explore_info_get() reaches the end of the folder, it returns NULL.

    As you explore the folder, you can display to the user any metadata you have retrieved, and, if the user requests more complete metadata, call mme_ms_metadata_get(), mme_metadata_extract_data() and, if required, mme_metadata_extract_string() and mme_metadata_extract_unsigned() to retrieve and extract the metadata, then pass it up to the user.

Items retrieved by mme_explore_info_get() are presented as they occur; that is, they are not sorted or reorganized in any way. The items that are playable tracks, can be placed in file-based track sessions for playback. For information about how to create and modify file-based track sessions, see Creating and modifying file-based track sessions in the chapter Playing Audio.


Caution: This function may require considerable time to complete execution: with some mediastore types, it requires a readdir() of the entire item being explored.

Retrieving metadata from unsynchronized files

The mediastore explorer API can be used to get the number of files and folders inside a specified folder on a mediastore, and, if requested, metadata. For optimal performance you should compose two different strings specifying the metadata to be retrieved:


Note: It is possible to request complete metadata from mme_explore_info_get(), but doing so may prove slow, especially when communicating with external devices, such as iPods, that are connected via relatively slow ports.

There are two possible methods for composing the strings to retrieve metadata. Both methods use the values defined by the METADATA_* constants. You can compose your strings as comma-separated values according to either of the following models:

Reading and displaying explored file names

All filesystem APIs under QNX use UTF-8 character sets; and, with the exception of QNX4, all enforce its use, converting the character set on media to and from UTF-8 as required.

This characteristic of QNX filesystems means that when your client application is reading file and folder names from the explorer API it should assume that these names are in UTF-8 format. This rule includes filenames successfully converted from playlist file entries, but it does not include unconverted (raw) playlist file entries; the explorer API takes these entries directly from the playlist itself and does not convert them.

For information specific to displaying information from iPods, see Displaying information from an iPod in the chapter Working with iPods.

Filtering explored files

You can use the mme_explore_position_set() function's flags and filter arguments to filter the files examined and deliver only files of interest. Filtering is based on the values set in the flags argument, and can be done in two ways:

For example, to include only MP3 and WAVE files, based on the extensions .mp3 and .wav, you should call mme_explore_position_set() as follows:

rc = mme_explore_position_set( x_hdl, 0, 20, NULL, ".mp3$|.wav$", MME_EXPLORE_FILTER_INCLUDE );

Or, to exclude all files with the extension .mov, do the following:

rc = mme_explore_position_set( x_hdl, 0, 20, NULL, ".mov$", MME_EXPLORE_FILTER_EXCLUDE );

For more detailed information, see mme_explore_position_set() in the MME API Library Reference.

Using directed synchronization to browse mediastores

You can use the MME's directed synchronization capabilities to browse through mediastores. To let users browse through parts of a mediastore, call mme_sync_directed() with the path to the folder where you want to begin browsing. When the end user selects a new folder, call the function again with the new path.

For more information about directed synchronization, see Directed synchronization in the chapter Synchronizing Media.