alSelectEvents(3dm)                                        alSelectEvents(3dm)


NAME
     alSelectEvents - Setup event queue to receive audio events.

SYNOPSIS
     #include <dmedia/audio.h>

     int alSelectEvents(ALeventQueue eventq, int resource
                         int *params, int nparams)

PARAMETER
     eventq   expects an ALeventQueue structure properly initialized by
              alOpenEventQueue(3dm).

     resource expects a resource ID from which you desire events.

     params   expects an int pointer with a list of parameters for which you
              desire events.

     nparams  expects an int with the total number of parameters in the list
              params.


DESCRIPTION
     (see alResources(3dm)). An event will be generated whenever the value of
     a parameter from params changes on the given resource.  Please refer to
     alParams(3dm) for a complete list of parameters that can generate events.
     To retrieve events, use alNextEvent(3dm) and alCheckEvent(3dm).

     You can call alSelectEvents(3dm) several times on an event queue. Thus a
     single event queue can monitor events from multiple resources.

     In some cases, the resource that generates an event will differ from the
     resource specified in alSelectEvents. As noted in alParams(3dm),
     parameters addressed to one resource can be passed on to other resources.
     For example, an AL_RATE passed to a device is actually handled by the
     device's clock-generator, a separate resource. In this case, if you
     request AL_RATE events from the device, you will be notified when the
     value of AL_RATE changes on the device's clock-generator; both resource
     ID's will show up in the event. Refer to alGetEventSrcResource(3dm) and
     alGetEventResource(3dm) for more information.

     Event queues monitoring either AL_DEFAULT_INPUT or AL_DEFAULT_OUTPUT will
     change to monitor the new device when the default is changed. Note that
     events with certain parameters will cease to be generated due to the
     characteristics of the new resource.

     To deselect event notification on an event queue, use
     alDeselectEvents(3dm).


EXAMPLE
     The following example sets up an event queue to receive events with
     either AL_RATE or AL_MUTE parameters from the default output device.

          int params[2];
          ALeventQueue eventq;

          /*
           * Open event queue and set it up to receive events.
           */

          eventq = alOpenEventQueue("output");

          if(eventq == NULL) {
              fprintf(stderr,"Open event queue failed \n");
              return -1;
          }

          params[0] = AL_RATE;
          params[1] = AL_MUTE;

          status = alSelectEvents(eventq,AL_DEFAULT_OUTPUT,params,2);

          if(status == -1) {
              fprintf(stderr,"Select event queue failed \n");
              return -1;
          }


DIAGNOSTICS
     Upon successful completion, alSelectEvents returns 0. Otherwise,
     alSelectEvents returns -1 and sets an error number which can be retrieved
     with oserror(3C).

     alSelectEvents can fail for the following reason:

     AL_BAD_INVALID_EVENTQ    eventq is either invalid or null.
     AL_BAD_RESOURCE         resource is invalid.
     AL_BAD_PARAM             params is either invalid or null.
     AL_BAD_BUFFERLENGTH_NEG  nparams is either less than or equal to zero.

SEE ALSO
     alOpenEventQueue(3dm), alDeselectEvents(3dm), alParams(3dm),
     alNextEvent(3dm), alCheckEvent(3dm), alGetEventResource(3dm),
     alGetEventSrcResource(3dm), oserror(3C)


                                                                        Page 2