ALgetstatus(3dm)

NAME
     ALgetstatus - 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.

DESCRIPTION
     ALgetstatus(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:
          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 ALSO
     ALreadsamps(3dm), ALwritesamps(3dm)