snd_ctl_ducking_status_read()

Arguments:

handle

The handle for the control connection to the card. This must be a handle created by snd_ctl_open().

ducking_output

The name of the ducking output to monitor. The ducking output is the audio concurrency management context or output specified by the audio configuration file audiomgmt_id key.

info

A pointer to location where a snd_ducking_priority_status_t structure is stored. The structure contains information about the audio types that are active. If the call is successful, the system allocates memory for you, therefore it's the responsibility of the caller to free the allocated memory. This value can't be NULL.

Library:

libasound.so

Use the -l asound option with qcc to link against this library.

Description:

The snd_ctl_ducking_status_read() function gets a list of all the active audio subchannels and information about their priority and ducking state, regardless of whether they are audible or not.

Because audio concurrency management handles a PCM link group as a single stream, this function reports only information for the first subchannel in a group.

Use this function to get information about active audio types after you receive a SND_CTL_READ_AUDIOMGMT_STATUS_CHG event in an audiomgmt callback.

The priority and ducking state information is specified in the snd_ducking_priority_status_t structure that info points to:

typedef struct snd_ducking_priority_status {
    int                       nsubchns;
    snd_ducking_subchn_info_t subchns[];
} snd_ducking_priority_status_t;

This structure includes the following members:

nsubchns

The number of active subchannels. Subchannels do not have to be audible to be considered active.

subchns

An array of subchannel ducking information structures.

The subchns member is a variable-sized array of snd_ducking_status_t structures:

typedef struct snd_ducking_subchn_info
{
    pid_t    pid;
    uint32_t prio;
    uint32_t state;
    uint32_t ducked_by;
    char      name[32];
} snd_ducking_subchn_info_t;

The members include:

pid

The process ID of the application that opened the audio stream.

prio

The priority of the audio type. The higher the number, the higher the priority.

state

The ducking state. The following values are valid:

• SND_PCM_DUCKING_STATE_ACTIVE — Ducking is active because the stream is active.
• SND_PCM_DUCKING_STATE_HARD_SUSPENDED — The subchannel is suspended by an audio type with a higher priority.
• SND_PCM_DUCKING_STATE_SOFT_SUSPENDED — The subchannel is suspended by an audio type of the same priority.
• SND_PCM_DUCKING_STATE_PAUSED — The stream will transition to SND_PCM_STATUS_PAUSED when unsuspended.
• SND_PCM_DUCKING_STATE_FORCED_ACTIVE — Ducking was made active using snd_pcm_channel_audio_ducking().
• SND_PCM_DUCKING_STATE_MUTE_BY_HIGHER — The stream was ducked by a stream with a higher priority.
• SND_PCM_DUCKING_STATE_MUTE_BY_SAME — The stream was ducked by a stream with an equal priority.
• SND_PCM_DUCKING_STATE_DUCKED — Ducking is active.

ducked_by

Describes the audio stream that ducked this active stream. Valid values are:

• SND_PCM_DUCKED_BY_SAME_PRIO
• SND_PCM_DUCKED_BY_HIGHER_PRIO
• SND_PCM_DUCKED_BY_NONTRANSIENT

Returns:

EOK on success. The priority status information is allocated and populated. The client application must free the buffer afterwards.

Errors:

-ENOMEM

No memory available to build the ducking status reply.

-EINVAL

Ducking output not found.

Classification:

QNX Neutrino