Working with Mediastores

This chapter describes how to detect and manage mediastores, their state changes, and their removal from and insertion into the MME.

Detecting mediastores

The MME uses the Media Content Detector (MCD) utility to monitor and detect the insertion and removal of mediastores, and the slots table to associate mediastores with the devices that present them. To detect mediastores, your system must have the MCD and the slots table configured correctly. For more information, see Mediastore detection path configuration in the the chapter Configuring Device Support of the MME Configuration Guide..

Mediastore states

Mediastores can have any one of the following states:

The initial state of all mediastores is “nonexistent”. The MME checks for the insertion and removal of mediastores, including hard drives, CDs and DVDs, and USB memory sticks, and delivers the event MME_EVENT_MS_STATECHANGE when a mediastore state changes.


Note: When the state of a mediastore changes from another state to “nonexistent”, the MME prunes the entries for that mediastore from its database, regardless of the MME's pruning settings.

The default MME configuration is to automatically detect new mediastores. When it detects a new mediastore, the MME:

Understanding mediastore states at startup

In order to start the MME correctly, you should keep in mind the following:

For more information about mediastore states, see Detecting mediastores in the chapter Working with Mediastores.

System startup operations

The following describes the operation of the system at startup, assuming that automatic device detection is disabled.

  1. The QDB is started.
  2. The MME is started. Since device detection is disabled, the mediastores table doesn't change state, and the client application has a second opportunity to determine the startup (in fact, the previous shutdown) state of the mediastores.
  3. The client application instructs the MME to begin device detection. The MME goes through the mediastores table, and sets any active or available entries to unavailable. For each changed entry, the MME delivers an MME_EVENT_MS_STATECHANGE event. During this time, the mediastores table should not be read by other entities, as it may be changing.
  4. The MME delivers an MME_EVENT_MS_DETECTION_ENABLED event. Delivery of this event indicates that the MME has completed its database clean up. The client application may now read the database.

    Caution: The client application should not read from the MME database until the MME completes its database clean up and delivers the MME_EVENT_MS_DETECTION_ENABLED event. Until this event is delivered, the database reflects the previous state of mediastores, creating an inconsistency between the information about the mediastores in the MME database and the actual state of the mediastores. This inconsistency can cause errors.

  5. The MME handles insertion requests. After the MME delivers an MME_EVENT_MS_DETECTION_ENABLED event, it may process mediastore insertion requests from the path monitoring system. Handling of these causes the database to change: as the path monitoring system (normally the MCD) detects the appearance of media stores, it tells the MME, and the MME processes this new information and updates the mediastores table as needed.

Note: If the MME is configured for automatic device detection, the MME executes Step 3 internally, and the states for mediastores in the database state may change between Step 2 and Step 4 above.

Determining mediastore state changes after shut down

In some situations, a client application may want to determine if a mediastore remained in the system (was not removed) while the system was shut down. This information depends on information to which the MME does not have access. For example, to tell the client application that a CD remained in the system, the MME would need to know if CDs can be removed and inserted while the system power is off.

The mediastore information from the MME database that is directly available to the client application is the following:

These limitations mean that, in order to be able to distinguish between a mediastore that was never removed from the system and a mediastore that was inserted just as the system was starting up, the client application must be designed to use information that it requests and maintains independently of the information the MME can provide. If, for example, the client application is implemented in a system where CDs cannot be ejected when the system is shut down, it may be able to assume — independently of the information provided by the MME — that a CD that was present at shutdown is present at startup.

Configuring how the MME handles mediastores at startup

The delete_at_start field in the slots table allows you to manage how the MME processes mediastores marked as active at startup.

The default MME behavior at startup is to change the state of active mediastores to unavailable. However, when the delete_at_start field for a slot is set to a non-zero value, at startup the MME marks any mediastore found in the slot for deletion, and sets its state to non-existant. This configuration causes the MME to treat all mediastores in a slot as new mediastores; that is, as mediastores that the MME has never seen, and to perform synchronizations accordingly.

CD detection and presentation

The stages of disk insertion and detection are:

  1. Disk inserted into drive.
  2. The disk spins up.
  3. The MCD notices the path appearance for the CD.
  4. The MCD signals the insertion to the MME.
  5. The MME probes the disk to see how to handle it.
  6. The MME creates a media store entry (or marks an existing entry of the disk as active).
  7. The MME attempts to synchronize its database with the contents of the disk.

Mixed-mode CDs

The MME uses the first entry in a CD's table of contents (TOC) to determine if the CD is an audio or a data CD, and makes only one entry in the mediastores table for the CD. This behavior means that the MME presents a CD with both audio and data files to the client application as either an audio CD or a data CD, based on the type of file in its first TOC entry.

Recommended method for detecting mediastores

The recommended method for an client application to detect a mediastore state change, such as an insertion or a removal, is to check for the MME_EVENT_MS_STATECHANGE event, then check the new mediastore state:

Note that a state of e_mme_ms_nonexistent can occur when a mediastore has been removed from the MME database, for example, during a pruning operation. Client applications should therefore also check for this state.

Manually requesting device and mediastore detection

If you have configured the MME not to automatically detect devices and mediastores, you must call mme_start_device_detection() to start device and mediastore detection. The MME will check for any new devices that may have or be mediastores, and updates its mediastores table with the relevant information.


Caution: Between the time the MME starts up and mediastores are detected, the MME can't check the state of mediastores as defined in its database against the actual state of mediastores connected to the system. Therefore, if you have configured your MME to not automatically start device detection, always call mme_start_device_detection() before attempting any tasks that access devices (synchronization, playback, media copy and ripping, etc.).

Failure to call mme_start_device_detection() before attempting these type of tasks will produce unexpected results that may compromise the integrity of your system.


Mediastore identifiers

When the MME detects that a mediastore has been inserted into the system, it checks the mediastore for a unique identifier that it can match against an entry identifier column of the MME mediastores table. If the unique identifier for a mediastore matches an entry in this table, the MME considers that it has seen the mediastore before and proceeds accordingly; it may, for example, be able to optimize the synchronization of the mediastore if it ican confirm that some of the information it has about the mediastore is still accurate.

Identifiers for hard drive filesystems, USB memory sticks, and data CDs and DVDs

When a mediastore is inserted, if the MME has sufficient information to do so, it identifies that mediastore as already known. When it detects the insertion of a hard drive filesystem, USB memory stick, or data CD or DVD into the system, the MME searches for the file WMPInfo.xml at the root of the mediastore. It then attempts to extract the UUID from the file. If the extraction is successful, the MME stores this UUID in the identifier column of the MME mediastores table and uses it as a unique identifier for the mediastore.

If the MME doesn't find the file WMPInfo.xml, or if it is unable to extract a UUID from the file, it creates an identifier from a hash of the volume name (if found) and some file system information.

Note that in the absence of a UUID:

Identifying USB memory sticks

Many USB memory sticks don't have at least one of a WMPInfo.xml file, a volume name or a unique serial number. Without any of these unique identifiers, the MME has no mechanism for distinguishing between two USB sticks of the same size.

To solve the problem in a development environment, you can either assign a unique volume name to each USB stick, or synchronize each stick with Windows Media Player, which automatically creates a WMPinfo.xml file. In a production environment, you can have the HMI write a volume name or other unique identifier to USB sticks the first time they are inserted.

Support for multiple instances of a mediastore

The MME supports up to 10 instances of the same mediastore. When it detects a mediastore, the MME checks if the an instance of that mediastore is already present in its database. If the new mediastore is a duplicate, the MME:

  1. Doesn't change any information for any instances of the mediastore already present in the MME database.
  2. Creates an entry for the new (duplicate) mediastore.
  3. Appends “-in, where n is the instance number, to the string in the mediastore's identifier column, and (if this column is not empty) to the string in the driver_identifier column.

Thus, for example, if two duplicates of a mediastore with msid 123 are entered in the system, the MME mediastores will have three entries for this mediastore, as follows:

msid identifier driver_identifier
123 FAT12341234     6    
123 FAT12341234-i1 6-i1
123 FAT12341234-i2 6-i2

Note:
  • Identifiers can be from “-i1” to “-i9”.
  • The MME treats each mediastore instance as a separate, unique mediastore.
  • The MME prunes unused mediastore instances from its database, as required.

Mediastore and device capabilities

The MME uses the capabilities field in the mediastores table to store the capabilities of a mediastore or a device, such as an iPod, that presents itself as a mediastore. This field is a bit map defined by the MME_MSCAP_* constants.

To find out the capabilities supported by a mediastore or device, after receipt of an MME_EVENT_MS_STATECHANGE event indicating that the mediastore or device is active, check the value of the capabilities field for that mediastore or device.

If, for example, a device manages its own:

For more information about mediastore and device states, see Mediastore states above.

Track session capabilities

To get details about the current track session capabilities, call mme_trksession_get_info(). Note, however, that the information provided by this function is valid only if it is retrieved after playback has started on the external device.

Mapping mediastore filesystem paths to device locations

In order to be able to associate a filesystem path to the physical location of a mediastore, your client application should map the filesystem paths of mediastores to device paths, and these device paths to the physical locations of devices. The mountpath field of the mediastores table is always the filesystem path of a mediastore. To map the mountpaths in the mediastores table to device paths and, finally, to the physical locations of devices, your client application must know the following:

With this information, your client application could map, for example, /fs/cd_back from the mountpath field in the mediastores table to the device path/dev/cd_back and know that this mediastore is in the back seat CD changer.


Note: If Qnet is running and the MME is handed the device path, the filesystem mountpath found in the mediastores table will be prefixed by /net/nodename.

Associating devices and mediastores in the slots table

The slots table is used to associate mediastores in the MME system with the devices that provide them. As such, a slot is a representation of a device, such as a CD drive or a USB stick. The MME must have an entry in its slots table with the mountpath (or, in some cases, the device path) of every device that it may encounter. If the slots table doesn't have an entry for the device, the MME will not recognize the device and will not find the mediastores on that device.

The slots table is preloaded with default entires for an HDD, as well as for CD/DVD, USB, PFS, UPnP, and iPod devices. You should review these entries and modify, add or delete entries in the table to match your system. For instructions, see Configuring the slots table for supported devices in the chapter MME Configuration Guide.

Handling external disk changers

The MME fills in the name field in the mediastores table when the state of an external CD changer is set to available. This behavior allows the client application to communicate the CD changer name to users as soon as the changer is detected and available, even before it is active.

To trigger this new behavior, the client application must configure the slots table name fields corresponding to external CD disk changers to either empty strings or NULL values.


Note: For other mediastores, the MME sets the name field in the mediastores table when the mediastore state is set to active.

Handling removed mediastores

When the MME detects that a mediastore has been removed from the system, it:

Note that the available field set to 0 indicates only that the mediastore is not available. It does not provide information about the state of the mediastore synchronization.


Caution: If a mediastore is removed from the system while the MCD that monitors it is not running, the MME will never learn that the mediastore has been removed.

Handling reloaded mediastores

If the mediastore was inserted in the system and synchronized at a previous time, the content of the library table will have the mediastore information. However, because there can be no guarantee that a mediastore exactly matches the information in the MME database, the MME must resynchronize the mediastore to either confirm that all information is accurate, or add, remove, and change information as required.

During this resynchronization process, the MME uses any information available on the mediastore that can confirm the accuracy of its database before all synchronization work is complete. This strategy allows the MME to optimize performance by skipping resynchronization of parts of the mediastore that are confirmed unchanged since the last insertion and synchronization.

The default MME behavior is to automatically synchronize mediastores. Your client application needs only to monitor the progress of the synchronization to know when it can start playing media, displaying metadata, and using playlists.

“Manually” updating the library table

The MME provides a function, mme_lib_column_set(), that allows you to “manually” set the values of some fields for mediastores in the library table.

The function mme_lib_column_set() can only be used to update entries in the columns listed below:

For more information, see the MME API Library Reference.