NAME

AOpenAudio − open connection to specified audio server

SYNOPSIS

#include <audio/Alib.h>

Audio *AOpenAudio(char *audio_name, long *status_return);

DESCRIPTION

AOpenAudio() opens a connection to the server for the specified audio controller and returns a pointer to an Audio structure.  The audio library allocates the Audio structure to hold information that supports the controller.  The structure acts as the information connection between the application and the server; the application passes the Audio pointer to subsequent audio library function calls to identify which connection the call should affect. 

NOTE: If the audio server is not active, this function returns a NULL and sets status_return to AEOpenFailed.  For this reason, the application should use status_return (not set it to NULL) and should check it before proceeding. 

audio_name specifies the audio controller name as a string.  If audio_name is specified NULL, the value of the AUDIO environment variable is used. 

The string format is hostname:number

where:

hostname specifies the name of the host machine on which the audio controller is physically installed. 

number specifies the audio server number on that host machine.  Each audio server services one audio controller.  More than one audio controller can be installed in a machine.  The audio servers are numbered starting with 0. 

status_return receives the returned status of the operation unless it is set to NULL. 

One successful call to AOpenAudio() must precede all other audio operation function calls pertaining to a connection. 

To close the connection, use ACloseAudio(). 

EXTERNAL INFLUENCES

If audio_name is specified NULL, the value of the AUDIO environment variable is used. 

RETURN VALUE

Upon successful completion, AOpenAudio() returns a pointer to an Audio structure.  Otherwise, it returns a NULL. 

ERRORS

If status_return is not set to NULL, one of the following is returned in status_return:

 0 AENoError

 1 AESystemCall

 4 AEHostNotFound

 5 AENoSuchAudioNumber

17 AEOutOfMemory

18 AEOpenFailed

23 AEllbdNotStarted

AOpenAudio() does not generate error events. 

EXAMPLES

The following example sets the audio name argument, a_name, to NULL, causing the value of the AUDIO environment variable to be used; status is set up to receive an error status. 

Audio *audio;     /* audio connection */ char a_name;      /* audio name */ long status;      /* error status */ .  .  .  /* open audio connection */ a_name = ""; audio = AOpenAudio(a_name, &status);

DEPENDENCIES

This function belongs to the Audio Library of functions that manage connections to an audio server.  The audio server must run on a system that has audio hardware.  To find out whether or not your system has audio hardware, refer to the hardware manual that accompanies your system. 

AUTHOR

AOpenAudio() was developed by HP. 

SEE ALSO

ACloseAudio(3X). 

Using the Audio Application Program Interface.

Hewlett-Packard Company  —  HP-UX Release 9.03: April 1994