[5058] | 1 | .TH "roar_vs_file" "3" "June 2011" "RoarAudio" "RoarAudio Programmer's Manual" |
---|
| 2 | |
---|
| 3 | .SH NAME |
---|
| 4 | roar_vs_file, roar_vs_file_simple, roar_vs_new_from_file \- File mode for VS API |
---|
| 5 | |
---|
| 6 | .SH SYNOPSIS |
---|
| 7 | |
---|
| 8 | #include <roaraudio.h> |
---|
| 9 | |
---|
| 10 | int roar_vs_file(roar_vs_t * vss, struct roar_vio_calls * vio, int closefile, int * error); |
---|
| 11 | |
---|
| 12 | int roar_vs_file_simple(roar_vs_t * vss, char * filename, int * error); |
---|
| 13 | |
---|
| 14 | roar_vs_t * roar_vs_new_from_file(const char * server, const char * name, char * filename, int * error); |
---|
| 15 | |
---|
| 16 | .SH "DESCRIPTION" |
---|
| 17 | These functions are used to open the VS object in file mode. In the file mode the VS API |
---|
| 18 | reads or writes the data from or to the file itself. The file mode uses normal VIO/DSTR so |
---|
| 19 | it supports streams as well. Just pass the stream URL as filename. |
---|
| 20 | |
---|
| 21 | \fBroar_vs_file()\fR sets up the file mode for a already opened object using the open VIO handle \fBvio\fR. |
---|
| 22 | This function requires the use of \fBroar_vs_stream\fR(3). |
---|
| 23 | |
---|
| 24 | \fBroar_vs_file_simple()\fR sets up the file mode using a given filename (or URL). It opens the file using DSTR |
---|
| 25 | API. By default the function assumes playback mode and tries to auto detect the audio parameters. |
---|
| 26 | To override the auto detection or use a diffrent stream direction use \fBroar_vs_stream\fR(3). |
---|
| 27 | |
---|
| 28 | \fBroar_vs_new_from_file()\fR creates a new VS object and enters file mode using the file (or URL) given as |
---|
| 29 | \fBfilename\fR. |
---|
| 30 | |
---|
| 31 | To send data to or read data from use \fBroar_vs_iterate\fR(3) or \fBroar_vs_run\fR(3). |
---|
| 32 | |
---|
| 33 | .SH "PARAMETERS" |
---|
| 34 | .TP |
---|
| 35 | \fBserver\fR |
---|
| 36 | The server to connect to. NULL for defaults. |
---|
| 37 | |
---|
| 38 | .TP |
---|
| 39 | \fBname\fR |
---|
| 40 | The application name. This should be something the user can use to identify the application. |
---|
| 41 | It MUST NOT be the application's binary name or the value of argv[0]. |
---|
| 42 | |
---|
| 43 | .TP |
---|
| 44 | \fBvio\fR |
---|
| 45 | The VIO handle to be used by the file mode. |
---|
| 46 | |
---|
| 47 | .TP |
---|
| 48 | \fBclosefile\fR |
---|
| 49 | This parameter tells the file mode if the file should be closed on roar_vio_close(3). |
---|
| 50 | Must be ROAR_VS_TRUE (common) or ROAR_VS_FALSE. |
---|
| 51 | |
---|
| 52 | .TP |
---|
| 53 | \fBfilename\fR |
---|
| 54 | The filename used to open the file for file mode. The file is opend using DSTR API. |
---|
| 55 | All kinds of files supported by DSTR are supported. This includes HTTP streams. |
---|
| 56 | |
---|
| 57 | .TP |
---|
| 58 | \fBerror\fR |
---|
| 59 | This is a pointer to a integer used to store the error value in case of error. |
---|
| 60 | This can be NULL if not used but it is very recommended to use this error value to report |
---|
| 61 | good error messages to the user. |
---|
| 62 | |
---|
| 63 | .SH "RETURN VALUE" |
---|
| 64 | On success roar_vs_new_from_file() return a new VS object. On error, NULL is returned. |
---|
| 65 | roar_vs_file() and roar_vs_file_simple() returns 0 on success and \-1 on error. |
---|
| 66 | |
---|
| 67 | |
---|
| 68 | .SH "EXAMPLES" |
---|
| 69 | roar_vs_t * vss; |
---|
| 70 | int err; |
---|
| 71 | |
---|
| 72 | vss = roar_vs_new_from_file(NULL, "MyApp", "http://...", &err); |
---|
| 73 | if ( vss == NULL ) { |
---|
| 74 | //handle error. |
---|
| 75 | } |
---|
| 76 | |
---|
| 77 | if ( roar_vs_run(vss, &err) == -1 ) { |
---|
| 78 | //handle error. |
---|
| 79 | } |
---|
| 80 | |
---|
| 81 | if ( roar_vs_close(vss, ROAR_VS_FALSE, &err) == -1 ) { |
---|
| 82 | //handle error. |
---|
| 83 | } |
---|
| 84 | |
---|
| 85 | .SH "SEE ALSO" |
---|
| 86 | \fBroar_vs_new_simple\fR(3), |
---|
| 87 | \fBroar_vs_iterate\fR(3), |
---|
| 88 | \fBroar_vs_run\fR(3), |
---|
| 89 | \fBroar_vs_close\fR(3), |
---|
| 90 | \fBroarvs\fR(7), |
---|
| 91 | \fBlibroar\fR(7), |
---|
| 92 | \fBRoarAudio\fR(7). |
---|
| 93 | |
---|
| 94 | .\" ll |
---|