alGetParams(3dm)                                              alGetParams(3dm)


NAME
     alGetParams - get the values of audio resource parameters

SYNOPSIS
     #include <dmedia/audio.h>

     int alGetParams(int resource, ALpv *pvs, int npvs)

PARAMETERS
     resource
            expects the resource from which you wish to get parameter values.

     pvs    is an array of ALpv structures, each of which contains a single
            parameter and will contain the associated value upon return from
            alGetParams.

     npvs   is the number of ALpv items in the array.

DESCRIPTION
     alGetParams acquires the current values for a set of parameters from a
     specific audio resource.

     Each parameter/value pair is represented by a single ALpv structure:

          typedef struct {
              int     param;          /* parameter */
              ALvalue value;          /* value */
              short   sizeIn;         /* size in -- 1st dimension */
              short   size2In;         /* size out -- 2nd dimension */
              short   sizeOut;        /* size out */
              short   size2Out;        /* size out -- 2nd dimension */
          } ALpv;


     The application should set the param field in each ALpv to indicate which
     parameter is of interest.

     For scalar parameters, this is sufficient; alGetParams will fill in the
     corresponding value field.

     For non-scalar parameters, the application is responsible for allocating
     the memory required to hold the value. In addition to setting param, the
     application must set the pointer field of value (value.ptr) to point to
     the allocated buffer, and set sizeIn to indicate the size of the buffer,
     in elements. alGetParams will write the value to the given buffer,
     filling in at most sizeIn elements.

     alGetParams will set the sizeOut field of each ALpv to indicate how many
     elements it returned. For valid scalar parameters, this is always 1.  For
     non-scalar parameters, it return the number of elements available, even
     if greater than sizeIn. For any parameter, it can also set sizeOut to a
     negative value to indicate an error with that particular parameter.


     alGetParams currently supports only one negative sizeOut value:
     AL_INVALID_PARAM, which indicates that the given parameter was
     unrecognized by the given resource.

     See the alParams(3dm) man page for more information on the semantics of
     particular parameters.

EXAMPLE
     The following code fragment gets the value of the sample rate, the gain,
     and the name of the default audio input device.

          int  i;
          ALpv      pvs[3];
          char      name[32];
          ALfixed gain[8];

          pvs[0].param = AL_RATE;       /* a scalar parameter */

          pvs[1].param = AL_GAIN;       /* a vector parameter */
          pvs[1].value.ptr = gain; /* the vector we've allocated */
          pvs[1].sizeIn = 8;       /* the number of elements in gain */

          pvs[2].param = AL_NAME;       /* a string parameter */
          pvs[2].value.ptr = name; /* the string we've allocated */
          pvs[2].sizeIn = 32;      /* the array size, in characters,
                                 including space for NULL */

          /*
           * Now we ask the default input device for its sample rate, name,
           * and current input gain. Note that there's nothing input-specific
           * about this code. To use a default output device, we simply supply
           * AL_DEFAULT_OUTPUT as the resource to alGetParams.
           */
          if (alGetParams(AL_DEFAULT_INPUT, pvs, 3) < 0) {
              printf("alGetParams failed: %s\n", alGetErrorString(oserror()));
          }

          printf("name is %s, rate is %lf\n",
              name, alFixedToDouble(pvs[0].value.ll));

          for (i = 0; i < pvs[1].sizeOut; i++) {
              printf("gain[%d] = %lf dB\n", alFixedToDouble(gain[i]));
          }


DIAGNOSTICS
     alGetParams returns the number of recognized parameters in the given PV
     list. It can also return a negative value, and set an error code, to
     indicate errors with the entire alGetParams call. In this case, the error
     code retrieved by oserror(3C) will be one of:


     AL_BAD_PVBUFFER
          pvs is invalid.

     AL_BAD_BUFFERLENGTH
          npvs is patently wrong (e.g. negative).

     AL_BAD_DEVICE_ACCESS
          The audio system is inaccessible, either because it is not installed
          on the system, or because it is incorrectly configured.

     AL_BAD_RESOURCE
          The given resource resource does not exist.

SEE ALSO
     alParams(3dm), alSetParams(3dm), alGetParamInfo(3dm), oserror(3C)


                                                                        Page 3