NAME

       roar_vs_position, roar_vs_latency, roar_vs_latency2 - Get stream position information

SYNOPSIS

       #include <roaraudio.h>

       ssize_t roar_vs_position(roar_vs_t * vss, int backend, int * error);

       roar_mus_t roar_vs_latency(roar_vs_t * vss, int backend, int * error);

       roar_mus_t roar_vs_latency2(roar_vs_t * vss, int backend, int wait, int * error);

DESCRIPTION

       roar_vs_position() returns the current server site position of the stream plus the current offset for the
       selected backend.

       roar_vs_latency()  returns  the  latency  between  the  client  site  stream position and the server site
       position plus the latency by the backend.

       Use of roar_vs_latency() is not recommended as it requires the codec to use a true constant bit rate.

       roar_vs_latency2() is perfectly equivalent to roar_vs_latency()  expect  that  it  takes  the  additional
       parameter  wait.  The  wait parameter may have the values ROAR_VS_WAIT, ROAR_VS_NOWAIT and ROAR_VS_ASYNC.
       If  it  is  ROAR_VS_WAIT  the  function  does  the  same  as  roar_vs_latency().   If  the  parameter  is
       ROAR_VS_NOWAIT  roar_vs_latency2()  will return interpolated data based on old data collected by calls to
       roar_vs_latency(), roar_vs_latency2() or roar_vs_position().  ROAR_VS_ASYNC is used to  trigger  asyncron
       updates  to  this  internal  state.  Asyncron  operations need to be enabled before they can be used. See
       roar_vs_ctl(3).

       Calling these functions too often will result in  bad  performance  and  incorrect  data  (pool  interval
       smaller than server response time). Polling up to 20 times per second shoudn't be a problem.

PARAMETERS

       vss    The VS object to be used.

       backend
              The backend used for correction. This can be a stream ID of the stream to use as backend or one of
              the  special  values  defined by the constants ROAR_VS_BACKEND_*.  ROAR_VS_BACKEND_NONE is used to
              ask for no correction.  ROAR_VS_BACKEND_DEFAULT is used to ask for the  default  correction.  This
              should  be used in all common cases.  ROAR_VS_BACKEND_FIRST is used to ask for correction based on
              the first primary stream on the same mixer.

       wait   Tells the  API  if  the  call  should  wait  or  not.  Must  be  ROAR_VS_WAIT,  ROAR_VS_NOWAIT  or
              ROAR_VS_ASYNC.

       error  This  is  a pointer to a integer used to store the error value in case of error.  This can be NULL
              if not used but it is very recommended to use this error value to report good  error  messages  to
              the user.

RETURN VALUE

       roar_vs_position()  returns  the  stream  position  on  success  and -1 on error.  Stream position is the
       current position of the stream in units of samples (not frames!).

       roar_vs_latency() returns the stream latency on success and zero on error. However zero is a valid value.
       In case of error error is set to the error. In case of no error but zero latency error is cleared (set to
       ROAR_ERROR_NONE).  Latency is retruned in mu-seconds (1/10^-6s).

EXAMPLES

       FIXME

SEE ALSO

       roarvs(7), libroar(7), RoarAudio(7).

RoarAudio                                           June 2011                                roar_vs_position(3)