alGetResourceByName(3dm)			      alGetResourceByName(3dm)

NAME    [Toc]    [Back]

     alGetResourceByName - find	an audio resource by name

SYNOPSIS    [Toc]    [Back]

     #include <dmedia/audio.h>

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

PARAMETER    [Toc]    [Back]

     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    [Toc]    [Back]

     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"






									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 %s0, 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	failed0);
	      }

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

DIAGNOSTICS    [Toc]    [Back]

     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    [Toc]    [Back]
	  name is too long.

     AL_BAD_DEVICE_ACCESS    [Toc]    [Back]
	  There	is no audio system available, or it is improperly configured.

     AL_BAD_RESOURCE    [Toc]    [Back]
	  start_res is an invalid resource.

     AL_BAD_NOT_FOUND    [Toc]    [Back]
	  A resource could not be found	which met the given criteria.







									Page 2






alGetResourceByName(3dm)			      alGetResourceByName(3dm)



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


									PPPPaaaaggggeeee 3333