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