source: roaraudio/doc/man3/roar_vs_file.3 @ 5058:45211d6eeea9

.TH "roar_vs_file" "3" "June 2011" "RoarAudio" "RoarAudio Programmer's Manual"

.SH NAME
roar_vs_file, roar_vs_file_simple, roar_vs_new_from_file \- File mode for VS API

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

.SH "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.

\fBroar_vs_file()\fR sets up the file mode for a already opened object using the open VIO handle \fBvio\fR.
This function requires the use of \fBroar_vs_stream\fR(3).

\fBroar_vs_file_simple()\fR 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 \fBroar_vs_stream\fR(3).

\fBroar_vs_new_from_file()\fR creates a new VS object and enters file mode using the file (or URL) given as
\fBfilename\fR.

To send data to or read data from use \fBroar_vs_iterate\fR(3) or \fBroar_vs_run\fR(3).

.SH "PARAMETERS"
.TP
\fBserver\fR
The server to connect to. NULL for defaults.

.TP
\fBname\fR
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].

.TP
\fBvio\fR
The VIO handle to be used by the file mode.

.TP
\fBclosefile\fR
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.

.TP
\fBfilename\fR
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.

.TP
\fBerror\fR
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.

.SH "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.


.SH "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.
 }

.SH "SEE ALSO"
\fBroar_vs_new_simple\fR(3),
\fBroar_vs_iterate\fR(3),
\fBroar_vs_run\fR(3),
\fBroar_vs_close\fR(3),
\fBroarvs\fR(7),
\fBlibroar\fR(7),
\fBRoarAudio\fR(7).

.\" ll