alGetResourceByName(3dm)alGetResourceByName(3dm)NAMEalGetResourceByName - 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.
DESCRIPTIONalGetResourceByName 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"
Page 1
alGetResourceByName(3dm)alGetResourceByName(3dm)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.
Page 2
alGetResourceByName(3dm)alGetResourceByName(3dm)SEE ALSOoserror(3C), alIntro(3dm), alSetDevice(3dm), alResources(3dm)
Page 3
