alQueryValues(3dm)                                          alQueryValues(3dm)


NAME
     alQueryValues - get the set of possible values for a parameter

SYNOPSIS
     #include <dmedia/audio.h>

     int alQueryValues(int res, int param, ALvalue *set, int setsize,
                            ALpv *quals, int qualsize);


PARAMETER
     res  expects the audio resource (see alResources(3dm)) for which you
          desire the information.

     param
          expects the parameter whose values you desire. Not all parameters
          support alQueryValues(3dm); see alParams(3dm) for which parameters
          apply.

     set  expects an array of ALvalues large enough to hold the results.  See
          alParams(3dm) and alSetParams(3dm) for more information on ALvalues.

     setsize
          is the number of ALvalues in set.

     quals
          expects an array of ALpv structs called qualifiers. These are used
          to filter the results before putting them in the given set.  See
          alParams(3dm) and alSetParams(3dm) for more information on ALpv
          structs.

     qualsize
          is the number of ALpv structs in quals.

DESCRIPTION
     alQueryValues returns the set of possible values for a given parameter on
     a given resource, optionally filtering through the results to see if they
     meet certain qualifiers.

     alQueryValues only applies to certain parameters whose values are
     resources, enumerated values, or sets. See alParams(3dm) for information
     on which parameters apply.

     Qualifiers only apply to parameters whose values are resources. If quals
     is non-NULL and qualsize is non-zero, alQueryValues will acquire the set
     of potential values for param, then filter through it, selecting only
     those resources whose current values for the parameters in quals match
     the corresponding values in quals.

     alQueryValues will fill no more than setsize elements in set.  If setsize
     is 0, or set is NULL, alQueryValues will ignore set. In any case, it will
     return the number of possible values which meet the given qualifiers.


EXAMPLE
          #include <audio.h>

          /*
           * A simple function to dump information about an
           * AL resource.
           */
          void
          dump_resources(ALvalue *x, int rv)
          {
              ALpv y[3];
              char n[32];
              int i;

              for (i = 0; i < rv; i++) {
               y[0].param = AL_NAME;
               y[0].value.ptr = n;
               y[0].sizeIn = 32;
               y[1].param = AL_RATE;
               y[2].param = AL_TYPE;
               alGetParams(x[i].i,y,3);
               printf("found resource %d [%s] -- rate %lf, type %d\n",x[i].i, n,alFixedToDouble(y[1].value.ll), y[2].value.i);
              }
          }

          main()
          {
               ALvalue vals[32];
               ALpv quals[16];
               int rv;

               /*
                * alQueryValues can be used to count the number of
                * potential values for a parameter. We simply leave out
                * the sets. Here we ask how many different values
                * AL_DEFAULT_OUTPUT can have on our machine. This returns
                * the number of output devices on the system.
                */
               if ((rv= alQueryValues(AL_SYSTEM,AL_DEFAULT_OUTPUT,0,0,0,0))>=0) {
               printf("There are %d output devices on this system\n",rv);
               }
               else {
               printf("alQueryValues failed: %s\n", alGetErrorString(oserror()));
               exit(-1);
               }

               /*
                * Now we find a device with a particular name. We could use
                * alQueryValues for this, using AL_NAME as a qualifier, e.g.
                *
                * quals[0].param = AL_NAME;
                * quals[0].value.ptr = "AnalogIn";


                * quals[0].sizeIn = strlen(quals[0].value.ptr)+1;       // add 1 to count the NULL
                * if ((rv= alQueryValues(AL_SYSTEM,AL_DEVICES,vals,16,quals,1))>0) {
                *     printf("AnalogIn is resource %d\n",vals[0].i);
                * }
                *
                * ... but alGetResourceByName is easier.
                */
               if (rv=alGetResourceByName(AL_SYSTEM, "AnalogIn", AL_DEVICE_TYPE)) {
               printf("AnalogIn is resource %d\n",rv);
               }

               /*
                * We look up the master clocks that this device can get to,
                * and find all whose types are AL_CRYSTAL_MCLK_TYPE.
                * Note that the device understands AL_MASTER_CLOCK even though
                * it's a clock-generator parameter -- parameters for interfaces
                * and clock-generators can be sent to the devices that use them.
                */
               quals[0].param = AL_TYPE;
               quals[0].value.i = AL_CRYSTAL_MCLK_TYPE;
               if ((rv= alQueryValues(rv,AL_MASTER_CLOCK,vals,16,quals,1))>0) {
               dump_resources(vals, rv);
               }
               if (rv < 0) {
               printf("alQueryValues failed: %s\n", alGetErrorString(oserror()));
               }
          }


DIAGNOSTICS
     alQueryValues always returns the number of possible values which meet the
     qualifiers. If it finds no such possible values, it returns 0.  If the
     call fails for other reasons, it returns -1.  In this case, the error
     code retrieved by oserror(3C) will be one of:

     AL_BAD_PVBUFFER
          quals is invalid and qualsize is nonzero.

     AL_BAD_BUFFERLENGTH
          qualsize or setsize 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 res does not exist.

     AL_BAD_PARAM
          The given parameter param is not supported by the given resource.


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


                                                                        Page 4