AOpenAudio(3X)

NAME

AOpenAudio − open a connection to the specified audio server

SYNOPSIS

#include <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.

audio_name specifies the audio controller name as a string.

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 this parameter is passed in as a NULL pointer. If status_return is set to NULL, Alib will do the error handling.

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.

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. If AUDIO is not set the Audio library attempts to use the audio server on the system defined by the DISPLAY environment variable. If neither AUDIO nor DISPLAY is set, the Audio library uses the audio server on the local system.

RETURN VALUE

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

ERRORS

If status_return is not set to NULL, it can return one of the following values:

0 AENoError No error - the call completed successfully.

1 AESystemCall A file read, write, or open failed with an error other than File Not Found.

17 AEOutOfMemory Alib attempted to allocate space for an internal structure but failed.

18 AEOpenFailed Possible causes are:

−
The AUDIO environment variable or audio_name is not a valid node name.

−
The Audio server is not running on the named node.

23 AEllbdNotStarted llbd (HP-UX 9.x) or rpcd (HP-UX 10.0 DCE) is not started.

26 AEServerAccessDenied The user or the system the user is running on are not allowed access by the ASF file on the audio server node.

Note that AOpenAudio() does not generate error events.

EXAMPLE

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);

NOTE

In order to ensure that the compiler finds the Audio Library (libAlib.sl) and the Alib.h header file, you must add the following switches:

-L /opt/audio/lib
-I/opt/audio/include

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 Using the Audio Developer’s Kit or the online help for the Audio control panel. For information about the audio capabilities of a particular system use the online example audioinfo.c.

AUTHOR

AOpenAudio() was developed by HP.

Museum

Related Articles