AUDIO_DEVICE(3)

NAME
audio_device, et al - audio device control functions

DISCLAIMER

The manual pages, header files, and object library associated with /usr/demo/SOUND/libaudio.a are furnished on an AS IS basis as a preliminary interface to several useful audio data-processing capabilities. A future release of the operating system may redefine the syntax or semantics of some of the functions described herein.

SYNOPSIS
#include <multimedia/libaudio.h>
#include <multimedia/audio_device.h>

int audio_pause_play(fd)
int fd;
...

DESCRIPTION
A number of functions are provided to query and control the state of the audio device. By using these functions, applications do not need to be concerned with the details of the audio ioctl commands. This interface layer may be used, in the future, to redirect control/status messages to and from an audio server process instead of the audio device itself.

The fd argument of the device control functions specifies an open file descriptor referring to the audio device. In most cases, this descriptor may refer either to the audio i/o device (/dev/audio) or the audio control device (/dev/audioctl). All of these functions return the value AUDIO_SUCCESS if the requested operation succeeded; otherwise an error flag is returned. Note that, in some cases, successful completion does not mean that the requested change of status actually altered the state of the device.

Pause/Resume

The following functions pause and resume audio i/o. If the requested operations failed to take effect (for instance, output may not be paused if the device is not open for writing), the value AUDIO_ERR_NOEFFECT is returned.

audio_pause_play(fd)
    pauses audio output, without affecting previously queued data.

audio_pause_record(fd)
    pauses audio input. All input data that was converted prior to pausing is made available to the process.

audio_pause(fd)
    simultaneously pauses both input and output.

audio_resume_play(fd)
    resumes audio output.

audio_resume_record(fd)
    resumes audio input conversion.

audio_resume(fd)
    simultaneously resumes both input and output.

Flush Queues

The following functions flush the audio STREAMS buffers.

audio_flush_play(fd)
    flushes the output queue.

audio_flush_record(fd)
    flushes the input queue.

audio_flush(fd)
    simultaneously flushes the both the input and output queues.

Synchronization

The following functions perform operations related to the synchronization of output data.

audio_drain(fd,sig)
    causes the requesting process to block until all previously queued output data has been played. If the sig argument is TRUE, the reception of a signal will cause audio_drain() to return immediately with the value AUDIO_ERR_INTERRUPTED.

audio_play_eof(fd)
    writes an End-Of-File marker to the specified device. When this marker is synchronously played, the output eof counter in the device information structure will be incremented.

Gain

The following functions manipulate the various gains associated with the audio device. Gain levels are represented by a floating-point value between 0. and 1. (where 0. denotes infinite attenuation and 1. represents the maximum gain level). In this way, applications may map any number of gradations of volume over the full scale of the device. The valp argument specifies the address of a floating-point double. In the case of the set routines, this value is scaled to the device range and the gain level is set. Both the get and set routines return the latest gain setting in the address given by valp.

audio_get_play_gain(fd,valp)
    retrieves the current output gain.

audio_get_record_gain(fd,valp)
    retrieves the current input gain.

audio_get_monitor_gain(fd,valp)
    retrieves the current monitor gain.

audio_set_play_gain(fd,valp)
    sets the output gain and returns the new value.

audio_set_record_gain(fd,valp)
    sets the input gain and returns the new value.

audio_set_monitor_gain(fd,valp)
    sets the monitor gain and returns the new value.

Device Status

The following functions manipulate the various state flags of the audio device. The valp argument specifies the address of an unsigned integer. This value updated with the latest value of the particular state field. In the case of the set routines, this value is first set in the appropriate device state field. Requests to alter read-only fields or to set values that are inappropriate for the particular audio device are ignored. Applications may check the return value in order to ensure that the requested change took place.

audio_get_play_port(fd,valp)
    retrieves the current output port configuration.

audio_get_record_port(fd,valp)
    retrieves the current input port configuration.

audio_get_play_samples(fd,valp)
    retrieves the current output sample count.

audio_get_record_samples(fd,valp)
    retrieves the current input sample count.

audio_get_play_error(fd,valp)
    sets *valp TRUE if the output underflow indicator is set.

audio_get_record_error(fd,valp)
    sets *valp TRUE if the input overflow indicator is set.

audio_get_play_eof(fd,valp)
    retrieves the current output end-of-file counter.

audio_get_play_open(fd,valp)
    sets *valp if the device is open for output.

audio_get_record_open(fd,valp)
    sets *valp if the device is open for input.

audio_get_play_active(fd,valp)
    sets *valp if data output is currently in progress.

audio_get_record_active(fd,valp)
    sets *valp if data input is currently in progress.

audio_get_play_waiting(fd,valp)
    sets *valp if a process is waiting for write access to the audio device.

audio_get_record_waiting(fd,valp)
    sets *valp if a process is waiting for read access to the audio device.

audio_set_play_port(fd,valp)
    sets the output port configuration and returns the new value.

audio_set_record_port(fd,valp)
    sets the input port configuration and returns the new value.

audio_set_play_samples(fd,valp)
    sets the output sample counter. The value of the output sample counter immediately prior to setting the new value is returned.

audio_set_record_samples(fd,valp)
    sets the input sample counter. The value of the input sample counter immediately prior to setting the new value is returned.

audio_set_play_error(fd,valp)
    sets the output error flag. Ordinarily, applications should only reset this flag to zero. The value of the output error flag immediately prior to setting the new value is returned.

audio_set_record_error(fd,valp)
    sets the input error flag. Ordinarily, applications should only reset this flag to zero. The value of the input error flag immediately prior to setting the new value is returned.

audio_set_play_eof(fd,valp)
    sets the output end-of-file counter. The value of the output eof flag immediately prior to setting the new value is returned.

audio_set_play_waiting(fd,valp)
    sets the output waiting flag. This flag may only be set (it is cleared when the device becomes available for output).

audio_set_record_waiting(fd,valp)
    sets the input waiting flag. This flag may only be set (it is cleared when the device becomes available for input).

Encoding Configuration

The following routines convert the current audio device encoding configuration to an Audio_hdr structure whose address is given by the hp argument.

audio_get_play_config(fd,hp)
    returns the current output configuration.

audio_get_record_config(fd,hp)
    returns the current input configuration.

The following routines attempt to configure the audio device to match the encoding specified in the Audio_hdr structure. Some of the requested fields may be read-only for the device. If the device configuration cannot be made to match the requested encoding, the value AUDIO_ERR_NOEFFECT is returned. In this case, the application should check the particular fields of the returned Audio_hdr in order to determine the current state of the device.

audio_set_play_config(fd,hp)
    sets the output configuration to match the given Audio_hdr. The new output configuration is returned.

audio_set_record_config(fd,hp)
    sets the input configuration to match the given Audio_hdr. The new input configuration is returned.

Direct Device Control

In some cases, applications may wish to read or modify several device state fields atomically. The following functions are provided for this purpose, though their use should be avoided where possible, since they expose the audio ioctl interface to applications. The ip argument specifies the address of an Audio_info_t structure (see audio(4)) that is filled in with the current state of the device.

#include <sun/audioio.h>

audio_getinfo(fd,ip)
    returns the current device information structure.

audio_setinfo(fd,ip)
    sets the device state from *ip and updates it to reflect the new state. If the AUDIO_INITINFO macro was used to initialize the information structure, then only fields that were subsequently modified will affect the audio device state.

RETURN VALUE
These routines return AUDIO_SUCCESS on successful completion or, if unsuccessful, one of the following error codes:

AUDIO_UNIXERROR
    An error occurred while executing a system library function. The global value errno contains the error code.

AUDIO_ERR_BADARG
    A user-supplied argument value was invalid.

AUDIO_ERR_ENCODING
    The device or Audio_hdr encoding contained an invalid or unsupported format code.

AUDIO_ERR_NOEFFECT
    The requested operation did not entirely take effect. Partial device state changes may have occurred.

AUDIO_ERR_INTERRUPTED
    The requested operation was interrupted by a signal.

SEE ALSO
audio_intro(3), audio_hdr(3), audio(4).