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

RoarAudio                                           June 2011                                    roar_vs_file(3)