snd_afm_get_ap_data()

Updated: April 19, 2023

Retrieve data from the acoustic library in an AFM

Synopsis:

#include <sys/asoundlib.h>

int snd_afm_get_ap_data( snd_afm_t *handle,
                         snd_afm_ap_param_t *param,
                         void *data );

Arguments:

handle
The handle for the AFM device, which you must have opened by calling snd_afm_open_name() or snd_afm_open().
param
A pointer to a snd_afm_ap_param_t structure that specifies the library parameter information and the size of the data buffer.
data
NULL, or a pointer to the location where the function can store the retrieved data.

Library:

libasound

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

Description:

Note: This function can only be used if you have QNX Acoustic Management Platform 3.0 installed.

The snd_afm_get_ap_data() function retrieves data from the acoustic library in an AFM, as specified in the snd_afm_ap_param_t structure that param points to:

typedef struct snd_afm_ap_param {
    uint32_t size;
    uint32_t dataId;
    int32_t  channel;
    int32_t  status;
} snd_afm_ap_param_t;

This structure includes the following members:

size
The size of the buffer that data points to. On return, this member is updated with the actual size of the retrieved data.
dataId
The identifier for the parameter whose value you want to get. Each AFM has its own set of IDs; see the AFM's <qwa_afm_defs.h> header file (e.g., <qwa_icc_defs.h>). The comments for each parameter indicate the data type and when it's valid to get and set the parameter.
channel
The channel identifier, which is applicable only for selected channel-based parameters (see the AFM's documentation). The channel number is zero-based and should be from 0 to one less than the maximum number of channels valid for the specified parameter.
status
The return code from the library; one of the QWA_* codes defined in <qwa_err.h>.

If you specify NULL for data, no data is returned, but the size member is set to the minimum size required for the data buffer.

This function is applicable only to acoustic (ASD, CSA, ICC, QAV) AFMs. For more information about getting and setting parameters, see the documentation for the specific AFM.

Returns:

EOK if the request was successfully issued to the library and a response was returned, or a negative errno value if an error occurred.

Note: You should check both the function's return value and the status member of the snd_afm_ap_param_t structure to determine if a call is successful.
This function can also return the return values of devctl() (see devctl() in the QNX Neutrino C Library Reference).

Errors:

-EINVAL
The value of handle or param is NULL.

Classification:

QNX Neutrino

Safety:  
Cancellation point Yes
Interrupt handler No
Signal handler Yes
Thread Yes

Caveats:

This function is not thread safe if the handle (snd_afm_t) is used across multiple threads.