Партнёры:
Хостинг:
NAME
audio_device - audio device control functions
SYNOPSIS
#include <multimedia/libaudio.h>
DESCRIPTION
A number of functions are provided to query and control the
state of the audio device. By using these functions, appli-
cations do not need to be concerned with the details of the
audio ioctl(2) 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; other-
wise 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 writ-
ing), the value AUDIO_ERR_NOEFFECT is returned.
audio_pause_play(int fd); pauses audio output, without
affecting previously queued
data.
audio_pause_record(int fd ); pauses audio input. All
input data that was converted
prior to pausing is made
available to the process.
audio_pause(int fd ); simultaneously pauses both
input and output.
audio_resume_play(int fd ); resumes audio output.
audio_resume_record(int fd ); resumes audio input conver-
sion.
audio_resume(int fd ); simultaneously resumes both
input and output.
Flush Queues
The following functions flush the audio STREAMS buffers.
audio_flush_play(int fd); flushes the output queue.
audio_flush_record(int fd); flushes the input queue.
audio_flush(int 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(int 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(int fd); writes an End-Of-File marker
to the specified device.
When this marker is synchro-
nously played, the output eof
counter in the device infor-
mation structure will be
incremented.
Gain
The following functions manipulate the various gains associ-
ated 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 dou-
ble. 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(int fd, unsigned valp);
retrieves the current output
gain.
audio_get_record_gain(int fd, unsigned valp);
retrieves the current input
gain.
audio_get_monitor_gain(int fd, unsigned valp);
retrieves the current monitor
gain.
audio_set_play_gain(int fd, unsigned valp);
sets the output gain and
returns the new value.
audio_set_record_gain(int fd, unsigned valp);
sets the input gain and
returns the new value.
audio_set_monitor_gain(int fd, unsigned 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(int fd, unsigned valp);
retrieves the current output
port configuration.
audio_get_record_port(int fd, unsigned valp);
retrieves the current input
port configuration.
audio_get_play_samples(int fd, unsigned valp);
retrieves the current output
sample count.
audio_get_record_samples(int fd, unsigned valp);
retrieves the current input
sample count.
audio_get_play_error(int fd, unsigned valp);
sets *valp TRUE if the output
underflow indicator is set.
audio_get_record_error(int fd, unsigned valp);
sets *valp TRUE if the input
overflow indicator is set.
audio_get_play_eof(int fd, unsigned valp);
retrieves the current output
end-of-file counter.
audio_get_play_open(int fd, unsigned valp);
sets *valp if the device is
open for output.
audio_get_record_open(int fd, unsigned valp);
sets *valp if the device is
open for input.
audio_get_play_active(int fd, unsigned valp);
sets *valp if data output is
currently in progress.
audio_get_record_active(int fd, unsigned valp);
sets *valp if data input is
currently in progress.
audio_get_play_waiting(int fd, unsigned valp);
sets *valp if a process is
waiting for write access to
the audio device.
audio_get_record_waiting(int fd, unsigned valp);
sets *valp if a process is
waiting for read access to
the audio device.
audio_set_play_port(int fd, unsigned valp);
sets the output port confi-
guration and returns the new
value.
audio_set_record_port(int fd, unsigned valp);
sets the input port confi-
guration and returns the new
value.
audio_set_play_samples(int fd, unsigned valp);
sets the output sample
counter. The value of the
output sample counter immedi-
ately prior to setting the
new value is returned.
audio_set_record_samples(int fd, unsigned valp);
sets the input sample
counter. The value of the
input sample counter immedi-
ately prior to setting the
new value is returned.
audio_set_play_error(int fd, unsigned 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(int fd, unsigned 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(int fd, unsigned 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(int fd, unsigned valp);
sets the output waiting flag.
This flag may only be set (it
is cleared when the device
becomes available for out-
put).
audio_set_record_waiting(int fd, unsigned 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(int fd, hp);
returns the current output configuration.
audio_get_record_config(int 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 dev-
ice. 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(int fd, hp);
sets the output configuration
to match the given Audio_hdr.
The new output configuration
is returned.
audio_set_record_config(int 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 func-
tions 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 <sys/audioio.h>
audio_getinfo(int fd, hp) returns the current device
information structure.
audio_setinfo(int fd, hp); 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 modi-
fied 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 glo-
bal 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 dev-
ice state changes may have
occurred.
AUDIO_ERR_INTERRUPTED The requested operation was inter-
rupted by a signal.
SEE ALSO
audio_intro(3), audio_hdr(3), audio(4)
WARNINGS
The manual pages, header files, and object library associ-
ated 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.
|
Закладки на сайте Проследить за страницей |
Created 1996-2024 by Maxim Chirkov Добавить, Поддержать, Вебмастеру |