ALgetstatus(3dm)ALgetstatus(3dm)NAMEALgetstatus - get information concerning the most recent error in the
audio stream associated with a port.
SYNOPSIS
#include <dmedia/audio.h>
int ALgetstatus(ALport port, long *PVbuffer, long bufferlength)
PARAMETER
port expects the ALport to which this command applies.
PVbuffer expects an array of longs. The even elements of this
array should each contain an error variable that you
choose to read. The subsequent odd elements are the
current or new value of these variables.
bufferlength expects the number of longs in the buffer pointed to by
PVbuffer. This value must be even.
DESCRIPTIONALgetstatus(3dm) returns the current values for the port error variables
referenced in the PVbuffer array. The values are written into the odd
locations of PVbuffer immediately after the corresponding error variable.
Errors may occur in an audio stream if reading and writing samples does
not keep pace with the audio port. If an output port is not provided
enough samples, underflow occurs. Likewise, if data is not read from an
input port fast enough, an overflow error occurs. ALgetstatus(3dm) allows
for these errors to be detected and quantified. This information can
enable the program (or user) to change the behavior of the program to
eliminate errors.
Two concepts regarding error detection deserve more explanation:
I. The length of the current error (AL_ERROR_LENGTH) is a sampled value,
and thus it may change even though the error count and/or the error
location may not. Note: if an error is particularly large, the length
variable may overflow its 24-bit limit.
II. The location of the error marks the point in the port lifetime that
the error was detected. Thus, the location represents the number of
sample frames (sample pairs for stereo; single samples for mono) that
have passed through the port to the audio hardware. The error location is
a 48-bit number, allowing the port to be open and active for over 200
years without counter overflow. The 48-bit location is generated by
concatenating the lower 24 bits of the values associated with
AL_ERROR_LOCATION_LSP and AL_ERROR_LOCATION_MSP.
The currently defined set of error parameters, found in audio.h, are:
Page 1
ALgetstatus(3dm)ALgetstatus(3dm)
AL_ERROR_NUMBER
The number of errors associated with the port since the port
was opened. This count is initialized to 0 when the port is
opened.
AL_ERROR_TYPE
The type of error which has most recently occurred on the port.
Supported error types are: AL_ERROR_INPUT_OVERFLOW and
AL_ERROR_OUTPUT_UNDERFLOW.
AL_ERROR_LENGTH
The current length (in samples frames) of the current error.
Consecutive values of this variable may differ if the current
error has not completed. Only the least significant 24 bits
of this variable are valid.
AL_ERROR_LOCATION_LSP
The least significant portion (LSP) of the location of the
beginning of the current error (in samples frames). Only the 24
least significant bits of this variable are valid.
AL_ERROR_LOCATION_MSP
The most significant portion (MSP) of the location of the
beginning of the current error (in samples frames). Only the 24
least significant bits of this variable are valid.
In order to maintain the greatest possible performance, ALgetstatus(3dm)
does not verify the validity of port, PVbuffer, or
bufferlength. You should make certain that these are valid before
passing them as arguments to ALgetstatus(3dm).
EXAMPLE
#include <dmedia/audio.h>
...
ALport port;
...
/* Get data concerning the most recent audio stream error */
long buf[10];
buf[0] = AL_ERROR_NUMBER;
buf[2] = AL_ERROR_TYPE;
buf[4] = AL_ERROR_LENGTH;
buf[6] = AL_ERROR_LOCATION_LSP;
buf[8] = AL_ERROR_LOCATION_MSP;
ALgetstatus(port,buf,10);
NOTE
Since an output port is initially empty, there may be an initial error
for the port.
SEE ALSOALreadsamps(3dm), ALwritesamps(3dm)
Page 2
