MediaFS Entities

This chapter describes:

The .FS_info. directory and its contents

When a MediaFS implementation learns of a device, it creates a .FS_info. directory for the media device with device-specific playback and metadata interface items. The table below lists these items:

Item Type Required? Description
info.xml file Yes XML file with device-specific information.
control file Optional File in which device-specific playback actions are issued to a media device.
dev symbolic link Optional Symbolic link to device identified by the <uuid> element in the info.xml file.
current symbolic link Optional Symbolic link pointing to the currently playing file in MediaFS.
playback directory Optional Directory with symbolic links, listed in the same order as the media device will complete playback of the files.

See the sections below for complete descriptions of the .FS_info. items.

The info.xml file

The info.xml device information file is an XML version 1.0 file that contains device-specific information. The MediaFS implementation creates this file when it creates the .FS_info. directory for a media device, placing it in the root directory for the device as .FS_info./info.xml. This file is static and persists for the lifetime of the MediaFS instance that created it.


Note: To the client application, the info.xml file is a read only file. Client applications can not write to this file.

When it creates the info.xml file, MediaFS does not populate it with device information. To enable MediaFS to present to higher level software layers a standard interface to all media devices, device controllers must populate the info.xml file for each device with XML-formatted, device-specific information. This XML-formatted information can be used by higher-level software, such as the MME, and may also be useful for human viewing.

The table below lists the basic elements of an info.xml file:

XML Key Required? Description
<media> Yes Root XML key for the media
<media>/<device> Yes A name used to indicate to upper layer components the device below the MediaFS.
<media>/<serial> Yes Device serial number
<media>/<model>/<*> Optional Device model information
<media>/<protocol>/<*> Optional Device protocol information
<media>/<swversion> Optional Device software revision
<uuid> Optional A unique identifier for the media device; upper layer components, such as the MME, must be able to use this key to associate the media device with its settings and remember these settings. A <uuid> number must be static, and unique to a media device.

Example info.xml file

The example below presents the minimum required content of a info.xml file:

<?xml version="1.0" standalone="yes"?>
<uuid>unique_media_identifier</uuid>
<media>
	<device>devicename</device>
	<serial>8N838BUH2C7</serial>
</media>

Note: Mediastore changer devices, such as CD or DVD changers, require different elements in their info.xml file. For more information, see The info.xml file for mediastore changers in the chapter Working with Media Changers.

The control file

The control file in the .FS_info. directory is the file where device-specific playback actions are issued to a media device. This MediaFS control file is a file interface that supports the following I/O capabilities:

The MediaFS control file provides state information and metadata for the current device. That is:


Note: The control file is required for devices, such as iPods, that use serial (“two-wire”) connections. It is not required for devices, such as PFS devices and certain iPods, that use USB (“one-wire”) connections.

Conditions for sending a notification

If the state or the metadata of the currently active device changes, the MediaFS control file should send a notification via an out-of-band message to all registered listeners, such as, for example, the MME.

The MediaFS control file sends a notification if any of the following conditions is met:


Note: To receive asynchronous notifications, a client application must use the QNX io_notify() function to register for these notifications.

The dev symbolic link

The dev element in the .FS_info. directory is a symbolic link to the media device identified by the <uuid> element. It should be an entry in the /dev directory and provide access directly to the media device.


Note: Devices such as an HTTP client driver may not have a dev entry.

The current symbolic link

The current symbolic link is optional. If it is present, this symbolic link is a relative path from the .FS_info. directory which, when it is resolved, points to the currently active file. This active file is in the MediaFS file system.

If the playback directory is present, the symbolic link points to an entry in this directory. If no file on the media device is currently active, the current symbolic link is removed or deleted.

Metadata retrieval commands issued on the current symbolic link return the specified metadata for the currently playing file.

The MediaFS control file sends a notification to registered clients via an out-of-band message whenever the current symbolic link is updated.


Note: A system must support the POSIX readlink() function in order to resolve the current symbolic link.

The playback directory

The playback directory is optional. If it is present, this directory contains symbolic links to files that the media device will play. When it writes these symbolic links to the playback directory, the device controller should organize them in the same order as the media device will play the files referenced by the links.

Whenever possible, symbolic links in the playback directory should point to the files that they represent in the main media filesystem. However, for some operational modes on some devices, the device may not be able to guarantee the accuracy of these pointers. Client applications should, therefore, treat the links as hints and not as guarantees of a file's location in the main media filesystem.

Metadata retrieval

Client applications can use metadata retrieval messages to execute metadata extraction calls against the files listed in the playback directory. If the links point into the MediaFS hierarchy, the results of a call to one of these symbolic links is the same as the result of a call to retrieve metadata directly from a file in MediaFS.

For more information about metadata retrieval messages, see the chapter Metadata Messages.

Changes to the playback directory

When the content of the playback directory changes (because, for example, the client has selected a play operation against a new set of media files), the control file sends a notification of the change to all applications registered for out-of-band messages on the control file.

Directories and files outside the .FS_info. directory

The behavior of MediaFS entities located outside the .FS_info. directory structure varies according to the capabilities and behaviors of each underlying media device. However, MediaFS maintains some behaviors throughout for these directories and files, as described in this section.

Directory behavior

MediaFS directories outside the .FS_info. directory represent the data hierarchy of the target device. For example, directories on an Apple iPod could be represented using the following structure:

/ipod0
/ipod0/.FS_info.
/ipod0/Music
/ipod0/Music/Artists
/ipod0/Music/Songs
...

Directory characteristics

To be usable by MediaFS, a directory outside the .FS_info. directory structure must have the following characteristics:

Additionally, directories outside the .FS_info. directory structure may need to accept the DCMD_MEDIA_PLAY command, if the associated media device supports playback of all items in a directory; that is, if the device supports using a directory as a playlist.

File behavior

MediaFS files outside the .FS_info. directory represent files or tracks that can used with the media device.

The POSIX filesystem representation for these files is free-form, with the following restrictions:

Supported device control messages

MediaFS files outside the .FS_info. directory structure must support state change and metadata query device control messages.

Messages issued directly to a file outside this directory structure must apply to the specified file. For example, the device control message DCMD_MEDIA_SONG issued directly to a file outside the .FS_info. directory structure returns the song title for that file, not the song title of the currently playing file.

If a device control message cannot be completed due to media device limitations, the call that issues the control message returns an ENOTSUP error.

For a complete list of device control messages used with MediaFS and descriptions of these messages, see the chapters Playback Messages and Metadata Messages.

Playlist files and directories

A playlist can be either of:


Note: Playlist support is subject to upper layer component (MME) support.

MediaFS playlists

Note the following about MediaFS playlists:

Indentifying a MediaFS playlist

The code snippet below shows how to determine if a directory is a MediaFS playlist:

stat(path, &statbuf);
if ((S_ISDIR ! S_IXOTH) & statbuf.st_mode)==S_ISDIR) {
    //This is a MediaFS playlist
}

For more information about the stat structure, see stat(), stat64() in the the QNX Neutrino Library Reference.