ALqueryparams(3dm)ALqueryparams(3dm)NAMEALqueryparams - (obsolete) get descriptor/description pairs for audio
device state variables
SYNOPSIS
#include <dmedia/audio.h>
long ALqueryparams(long device, long *PVbuffer, long bufferlength)
PARAMETER
device expects a device. Currently, there is only one device,
AL_DEFAULT_DEVICE.
PVbuffer expects an array of longs into which ALqueryparams(3dm)
can write descriptor/description pairs for each state
variable associated with device. The even (0,2,4, ...)
entries receive the descriptors. The odd entries (1,3,5,
...) receive the descriptions. These descriptions take on
one of four values:
+/-AL_RANGE_VALUE if this device state variable can assume
a range of values, and the range has some meaning, i.e.
larger values mean more of whatever this parameter
controls. A value of -AL_RANGE_VALUE indicates that the
parameter is read-only.
+/-AL_ENUM_VALUE if this device state variable assumes
values from an enumerated type. They still have a limited
range, but there is no inherent relationship between them.
A value of -AL_ENUM_VALUE indicates that the parameter is
read-only.
bufferlength expects the length of the buffer, in longs, pointed to by
PVbuffer.
DESCRIPTIONALqueryparams is obsolete and is provided for backward compatibility. The
preferred method is to use alQueryValues(3dm) with the AL_PARAMS
parameter to list the supported parameters, followed by
alGetParamInfo(3dm) to get information about each supported parameter.
ALqueryparams(3dm) lets you get a list of descriptors for all the state
variables associated with the specified device.
ALqueryparams(3dm) also tells you whether the value of a state variable
must be one of a set of enumerated types or any number within a specific
range. In both cases the values are numbers within the range returned by
ALgetminmax(3dm) and have the default value returned by
ALgetdefault(3dm).
Page 1
ALqueryparams(3dm)ALqueryparams(3dm)
Typical device parameters are expected to be things like volume and
sample rate. You can find a list of parameters and their descriptions in
ALgetparams(3dm).
ALqueryparams(3dm) returns the length of the buffer (number of longs)
that is required to hold all pairs of descriptors/descriptions. If
PVbuffer is smaller than this value, you have not acquired a complete
list of descriptor/description pairs and should increase your PVbuffer
and try again.
To simply determine the size of the buffer needed to hold the parameters
and descriptions, call ALqueryparams(3dm) with bufferlength set to zero.
ALqueryparams(3dm) can fail for the following reasons:
AL_BAD_DEVICE device is not valid.
AL_BAD_PVBUFFER PVbuffer is null valued.
AL_BAD_BUFFERLENGTH_ODD bufferlength is odd.
AL_BAD_BUFFERLENGTH_NEG bufferlength is negative.
AL_BAD_DEVICE_ACCESS audio hardware is inaccessible.
EXAMPLE
#include <dmedia/audio.h>
#include <malloc.h>
...
/* Get a buffer containing all the device parameters. */
long *buf,buflen;
buflen=ALqueryparams(AL_DEFAULT_DEVICE,0,0);
buf=(long *)malloc(buflen*sizeof(long));
(void)ALqueryparams(AL_DEFAULT_DEVICE,buf,buflen);
DIAGNOSTICS
Upon successful completion ALqueryparams(3dm) returns the size of the
buffer, in longs, needed to hold all the descriptor/description pairs for
device. Otherwise, ALqueryparams(3dm) returns -1 and sets an error number
which can be retrieved with oserror(3C).
SEE ALSOALgetparams(3dm), ALsetparams(3dm), ALgetminmax(3dm), ALgetname(3dm),
ALgetdefault(3dm), ALsetdevice(3dm), oserror(3C)
Page 2
