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 diffrent 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).