NAME

       roar_vs_file, roar_vs_file_simple, roar_vs_new_from_file - File mode for VS API

SYNOPSIS

       #include <roaraudio.h>

       int  roar_vs_file(roar_vs_t  *  vss,  struct  roar_vio_calls  *  vio, int closefile, int *
       error);

       int roar_vs_file_simple(roar_vs_t * vss, char * filename, int * error);

       roar_vs_t * roar_vs_new_from_file(const char * server, const char * name, char * filename,
       int * error);

DESCRIPTION

       These  functions  are used to open the VS object in file mode. In the file mode the VS API
       reads or writes the data from or to the file itself. The file mode uses normal VIO/DSTR so
       it supports streams as well. Just pass the stream URL as filename.

       roar_vs_file() sets up the file mode for a already opened object using the open VIO handle
       vio.  This function requires the use of roar_vs_stream(3).

       roar_vs_file_simple() sets up the file mode using a given filename (or URL). It opens  the
       file  using  DSTR  API.  By  default  the function assumes playback mode and tries to auto
       detect the audio parameters.  To override the auto detection or  use  a  different  stream
       direction use roar_vs_stream(3).

       roar_vs_new_from_file()  creates  a  new VS object and enters file mode using the file (or
       URL) given as filename.

       To send data to or read data from use roar_vs_iterate(3) or roar_vs_run(3).

PARAMETERS

       server The server to connect to. NULL for defaults.

       name   The application name. This should be something the user can  use  to  identify  the
              application.  It MUST NOT be the application's binary name or the value of argv[0].

       vio    The VIO handle to be used by the file mode.

       closefile
              This   parameter   tells   the   file   mode  if  the  file  should  be  closed  on
              roar_vio_close(3).  Must be ROAR_VS_TRUE (common) or ROAR_VS_FALSE.

       filename
              The filename used to open the file for file mode. The file is opend using DSTR API.
              All kinds of files supported by DSTR are supported. This includes HTTP streams.

       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

       On  success  roar_vs_new_from_file()  return a new VS object.  On error, NULL is returned.
       roar_vs_file() and roar_vs_file_simple() returns 0 on success and -1 on error.

EXAMPLES

        roar_vs_t * vss;
        int err;

        vss = roar_vs_new_from_file(NULL, "MyApp", "http://...", &err);
        if ( vss == NULL ) {
         //handle error.
        }

        if ( roar_vs_run(vss, &err) == -1 ) {
         //handle error.
        }

        if ( roar_vs_close(vss, ROAR_VS_FALSE, &err) == -1 ) {
         //handle error.
        }

SEE ALSO

       roar_vs_new_simple(3), roar_vs_iterate(3),  roar_vs_run(3),  roar_vs_close(3),  roarvs(7),
       libroar(7), RoarAudio(7).