alGetResourceByName(3dm)                              alGetResourceByName(3dm)


NAME
     alGetResourceByName - find an audio resource by name

SYNOPSIS
     #include <dmedia/audio.h>

     int alGetResourceByName(int start_res, char *name, int type)

PARAMETER
     start_res
            expects a resource at which the name search is to begin. Typically
            this is AL_SYSTEM, the top of the audio resource hierarchy.

     name   is a character string describing the resource to be found.

     type   is the type of the desired resource.

DESCRIPTION
     alGetResourceByName searches the resources accessible from start_res for
     a resource of type type which has a resource matching the given name
     accessible to it. See alResources(3dm) for general information on
     resources, resource types, and the resource hierarchy.

     There are three ways for name to match a given resource. The first is
     when name exactly matches the resource's name (AL_NAME).  The second is
     when name exactly matches the resource's label (AL_LABEL). The third is
     when name specifies a type which matches the type of the resource. The
     search is performed in this order.

     Periods in the name act as qualifiers. A name of the form (A.B) matches
     resource B if and only if it is accessible from resource A.

EXAMPLE NAMES
     "AnalogIn"
          matches a resource named "AnalogIn"

     "in.analog"
          matches an analog interface accessible from an input device.

     "out.analog"
          matches an analog interface accessible from an output device.

     "RAD1.microphone"
          matches a microphone interface accessible from a resource called
          "RAD1"

     "A2.out.analog"
          matches an analog interface accessible from an output device
          accessible from a resource called "A2"


EXAMPLE CODE
     The following code fragment finds a device dev which can access the
     resource which matches name, and, if the named resource is an interface,
     selects that interface on the device. For example, if name were
     "microphone," this code will look for a device dev with a microphone
     input, and select that input on the device.

          int dev;

          dev = alGetResourceByName(AL_SYSTEM, name, AL_DEVICE_TYPE);
          if (!dev) {
              printf("invalid device %s\n", name);
              exit(-1);
          }
          if (itf = alGetResourceByName(AL_SYSTEM, name, AL_INTERFACE_TYPE)) {
              /*
               * the named resource is an interface. Select the interface on the
               * given device.
               */
              ALpv p;

              p.param = AL_INTERFACE;
              p.value.i = itf;
              if (alSetParams(dev, &p, 1) < 0 || p.sizeOut < 0) {
                  printf("set interface failed\n");
              }

          }
          [... now do something with src...]


DIAGNOSTICS
     If alGetResourceByName is successful, it returns a non-zero resource. If
     it fails, it returns 0 and sets an error code which can be retrieved with
     oserror(3C). The error codes returned include:  alGetResourceByName can
     fail for the following reasons:

     AL_BAD_BUFFERLENGTH
          name is too long.

     AL_BAD_DEVICE_ACCESS
          There is no audio system available, or it is improperly configured.

     AL_BAD_RESOURCE
          start_res is an invalid resource.

     AL_BAD_NOT_FOUND
          A resource could not be found which met the given criteria.


SEE ALSO
     oserror(3C), alIntro(3dm), alSetDevice(3dm), alResources(3dm)


                                                                        Page 3