Device Messages

This chapter describes the MediaFS device control messages and how to use them. It contains the following sections:


Note:
  • The MediaFS device control messages, constants and data structures are defined in the header file io-fs/lib/public/sys/dcmd_media.h.
  • If a buffer is required for a command message, this documentation includes a buffer description with the message description; the buffer description follows the template: “Buffer: description. If the control message does not require a buffer, then no buffer description is presented with the message description.
  • For information about how to use MediaFS device control messages, see Using device control messages below.
  • For information about the messages used to retrieve album art, see Album art retrieval messages in the chapter Getting Album Art.

Using device control messages

MediaFS device control messages can be applied to open files and directories in the MediaFS filesystem to:

Control messages are applied by calls to the devctl() function. When a control message is applied to a MediaFS entity, the filesystem routes the message to the appropriate device driver. The device driver must:

All state modification control messages must be synchronous. A requested action must either complete or fail before returning. For example, if the state modifier DCMD_MEDIA_PLAY message is issued, upon return of the devctl() call, the underlying device must be in a playing state, or have returned a POSIX error indicating why the command failed.

As with other directories and files, an application must open a MediaFS directory or file with, respectively, the opendir() and the open() functions before it can use the devctl() function to issue control messages to them.

To pass data to and receive data from media devices, a client application should use the devctl() function's dev_data_ptr and dev_info_ptr arguments to point to the appropriate _media_* data structures. These _media_* structures are described in the chapter Playback Structures and Constants.

For a list of POSIX functions that MediaFS supports, see Required POSIX function support in the chapter MediaFS Structure. For more information about the functions, such as open() and devctl(), used to control devices, see the QNX Neutrino Library Reference.

Device configuration messages

This section describes the device messages defined to get and set device configurations. These message are:

DCMD_MEDIA_GET_XML

DCMD_MEDIA_GET_XML returns an XML configuration string (UTF-8) with the device configuration information. See also the chapter MediaFS Entities.

Buffer: char[1]

DCMD_MEDIA_SET_XML

DCMD_MEDIA_SET_XML expects a buffer containing a terminated xpath string followed by a terminated value string; that is, the element or attribute to modify, and its new value.

Buffer: char[1]


Note: DCMD_MEDIA_GET_XML and DCMD_MEDIA_SET_XML use a common configuration layout that becomes specific for each device. For example:
<device api_version="1">
    <media>
        <interface type="usb" ... />
        <DeviceSpecificString>
        .... Device specific settings
        </DeviceSpecificString>
    </media>
</device>

See also the chapter MediaFS Entities.


iPod, UPnP device and streaming messages

This section describes the device control messages defined to obtain information from and manage iPod and UPnP devices, and media streams. These message are:


Note: Most devices do not support the full set of control messages. If a device does not support a requested action, the device controller must return the error code ENOTSUP (command invalid for this device).

Common messages

This section describes the device control messages that can be used to obtain information from and manage iPod devices, UPnP devices, DRM, and media streams. These messages are:

DCMD_MEDIA_CONFIG

DCMD_MEDIA_CONFIG issues a configuration setting to a media device.

Buffer: char[1]

DCMD_MEDIA_GET_DEVINFO

DCMD_MEDIA_GET_DEVINFO requests information about a media device.

Buffer: char[8*1024]

iPod device messages

This section describes the device control messages defined to obtain information from and manage iPod devices. These message are:

DCMD_MEDIA_IPOD_DAUDIO

DCMD_MEDIA_IPOD_DAUDIO is used to retrieve iPod audio settings from an iPod device. This information is carried in the _media_ipod_daudio data structure

Buffer: struct _media_ipod_daudio

DCMD_MEDIA_IPOD_CAP

DCMD_MEDIA_IPOD_CAP retrieves capabilities information from an iPod device.

Buffer: char[1]

DCMD_MEDIA_IPOD_TAG

DCMD_MEDIA_IPOD_TAG is used to add an iTunes tag to a file on an iPod device.

Buffer: uint8_t[1]

UPnP device messages

This section describes the device control messages defined to obtain information from and manage UPnP devices. These message are:

DCMD_MEDIA_UPNP_CDS_BROWSE

DCMD_MEDIA_UPNP_CDS_BROWSE browses a mediastore on a device that uses the UPnP protocol.

Buffer: char[8]

Media stream messages

This section describes the device control messages defined to obtain information from and manage media streams. These message are:

DCMD_MEDIA_CLOSE_STREAM

DCMD_MEDIA_CLOSE_STREAM closes a media stream.

DCMD_MEDIA_INFO_STREAM

DCMD_MEDIA_INFO_STREAM retrieves information about a media stream. This information must be placed in a _media_stream_info structure.

Buffer: struct _media_stream

DCMD_MEDIA_OPEN_STREAM

DCMD_MEDIA_OPEN_STREAM opens a media stream.

DCMD_MEDIA_READ_STREAM

DCMD_MEDIA_READ_STREAM reads a media stream into a buffer. Before a stream can be read, it must be opened with a DCMD_MEDIA_OPEN_STREAM message and set with a DCMD_MEDIA_SET_STREAM message.

Buffer: char[16*1024-1]

DCMD_MEDIA_SET_STREAM

DCMD_MEDIA_SET_STREAM sets the media stream that will be read by calls to devctl() with the DCMD_MEDIA_READ_STREAM message.

Buffer: unsigned int