source: roaraudio/include/libroar/vs.h @ 4605:8f0e515e61a6

Last change on this file since 4605:8f0e515e61a6 was 4605:8f0e515e61a6, checked in by phi, 13 years ago

typos

File size: 9.9 KB
Line 
1//vs.h:
2
3/*
4 *      Copyright (C) Philipp 'ph3-der-loewe' Schafft - 2010
5 *
6 *  This file is part of libroar a part of RoarAudio,
7 *  a cross-platform sound system for both, home and professional use.
8 *  See README for details.
9 *
10 *  This file is free software; you can redistribute it and/or modify
11 *  it under the terms of the GNU General Public License version 3
12 *  as published by the Free Software Foundation.
13 *
14 *  libroar is distributed in the hope that it will be useful,
15 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
16 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17 *  GNU General Public License for more details.
18 *
19 *  You should have received a copy of the GNU General Public License
20 *  along with this software; see the file COPYING.  If not, write to
21 *  the Free Software Foundation, 51 Franklin Street, Fifth Floor,
22 *  Boston, MA 02110-1301, USA.
23 *
24 *  NOTE for everyone want's to change something and send patches:
25 *  read README and HACKING! There a addition information on
26 *  the license of this document you need to read before you send
27 *  any patches.
28 *
29 *  NOTE for uses of non-GPL (LGPL,...) software using libesd, libartsc
30 *  or libpulse*:
31 *  The libs libroaresd, libroararts and libroarpulse link this lib
32 *  and are therefore GPL. Because of this it may be illegal to use
33 *  them with any software that uses libesd, libartsc or libpulse*.
34 */
35
36#ifndef _LIBROARVS_H_
37#define _LIBROARVS_H_
38
39#include "libroar.h"
40
41struct roar_vs;
42
43typedef struct roar_vs roar_vs_t;
44typedef signed long int roar_mus_t;
45
46/* return readable string describing the problem */
47const char * roar_vs_strerr(int error);
48
49/* create a new VS object from normal RoarAudio connection object
50 * The connection must not be closed caller before roar_vs_close() is called.
51 * The connection is not closed by roar_vs_close().
52 */
53roar_vs_t * roar_vs_new_from_con(struct roar_connection * con, int * error);
54
55/* create a new VS object with a new connection */
56roar_vs_t * roar_vs_new(const char * server, const char * name, int * error);
57
58/* start a the stream in the VS object */
59int roar_vs_stream(roar_vs_t * vss, const struct roar_audio_info * info, int dir, int * error);
60
61/* connect to server and start stream in once
62 * this is basically roar_vs_new() and roar_vs_stream() in one function.
63 */
64roar_vs_t * roar_vs_new_simple(const char * server, const char * name, int rate, int channels, int codec, int bits, int dir, int * error);
65
66/* create a VS object for playback.
67 * This is roar_vs_new_simple() with direction set to 'playback' (wave form data)
68 */
69#define roar_vs_new_playback(s,n,r,c,e,b,error) roar_vs_new_simple((s), (n), (r), (c), (e), (b), ROAR_DIR_PLAY, (error))
70
71
72/* Attach a open file.
73 */
74
75int roar_vs_file(roar_vs_t * vss, struct roar_vio_calls * vio, int closefile, int * error);
76
77/* Open a file and attach it.
78 */
79int roar_vs_file_simple(roar_vs_t * vss, char * filename, int * error);
80
81/* Connects to a server to just play a file.
82 */
83roar_vs_t * roar_vs_new_from_file(const char * server, const char * name, char * filename, int * error);
84
85/* Boolean TRUE for VS functions */
86#define ROAR_VS_TRUE     1
87/* Boolean FALSE for VS functions */
88#define ROAR_VS_FALSE    0
89/* Boolean TOGGLE for VS functions */
90#define ROAR_VS_TOGGLE  -1
91/* Boolean value used to ask for a value, do not change the value only ask for current value */
92#define ROAR_VS_ASK     -2
93
94/* close and free the VS object
95 * This does all needed cleanup.
96 * If server connection was made by VS it is closed, too.
97 * If server connection was provided by caller it is untouched.
98 */
99int roar_vs_close(roar_vs_t * vss, int killit, int * error);
100
101/* write data to a stream
102 * This function writes some data to the stream.
103 * return is number of bytes written or -1 on error.
104 * return value can be zero to indicate no data can be written but no error.
105 * this may be the case with non-blocking streams.
106 * returned value can be less then requested value. indicates a short write.
107 * you should wait some (short!) time (for example one main loop iteration) and try again.
108 */
109ssize_t roar_vs_write(roar_vs_t * vss, const void * buf, size_t len, int * error);
110
111/* read data from a stream
112 * This function reads some data from the stream.
113 * return is number of bytes read or -1 on error.
114 * return value can be zero to indicate no data can be read but no error.
115 * this may be the case with non-blocking streams.
116 * returned value can be less then requested value. indicates a short read.
117 * you should wait some (short!) time (for example one main loop iteration) and try again.
118 */
119ssize_t roar_vs_read (roar_vs_t * vss,       void * buf, size_t len, int * error);
120
121/* wait value for waiting */
122#define ROAR_VS_WAIT   1
123/* wait value for no waiting */
124#define ROAR_VS_NOWAIT 0
125
126/* sync a stream with the server (flush buffers)
127 * Returns 0 on no error and -1 on error.
128 */
129int     roar_vs_sync (roar_vs_t * vss, int wait, int * error);
130
131/* set blocking mode of stream
132 * returns old blocking state
133 */
134int     roar_vs_blocking (roar_vs_t * vss, int val, int * error);
135
136/* default backend */
137#define ROAR_VS_BACKEND_DEFAULT ROAR_VS_BACKEND_FIRST
138/* do not supply backend offset */
139#define ROAR_VS_BACKEND_NONE    -1
140/* use first found primary stream of same mixer as offset source */
141#define ROAR_VS_BACKEND_FIRST   -2
142/* use mean of primary streams of same mixer as offset source */
143#define ROAR_VS_BACKEND_MEAN    -3
144
145/* get server's position of stream
146 * returns server's position of the stream or -1 on error.
147 * The returned server position is the position in samples
148 * plus a offset provided by the selected backend
149 */
150ssize_t roar_vs_position(roar_vs_t * vss, int backend, int * error);
151
152/* get latency between playback and local write counter
153 * This function may fail because the used codec uses
154 * non-fixed bitrate.
155 * if this function fails it returns zero and sets error or
156 * clear error to ROAR_ERROR_NONE.
157 * If non-zero is returned error is untouched.
158 * return value is in mu-sec (units of 10^-6s).
159 * Note that the returned value may be negative (the server being
160 * ahead of us). This is normal in case we read a stream.
161 */
162roar_mus_t roar_vs_latency(roar_vs_t * vss, int backend, int * error);
163
164/* set pause flag
165 * The pause flag should be set whenever the user presses the pause button or similar.
166 * The stream may be come blocking after the pause flag has been set.
167 * returns old pause setting (useful with ROAR_VS_TOGGLE)
168 */
169int     roar_vs_pause(roar_vs_t * vss, int val, int * error);
170
171/* set the mute flag of the stream
172 * The pause flag should be set whenever the user mutes the stream in some way.
173 * This flag is used so the volume is not changed and can be restored by the server
174 * while unmuting.
175 * It is very recommended to use this flag and not just set the volume to zero
176 * returns old mute setting (useful with ROAR_VS_TOGGLE)
177 */
178int     roar_vs_mute (roar_vs_t * vss, int val, int * error);
179
180/* set volume of stream (all channels to the same value)
181 * volume c is float from 0 ('muted', see above) to 1 (full volume).
182 * Returns 0 on no error and -1 on error.
183 */
184int     roar_vs_volume_mono   (roar_vs_t * vss, float c, int * error);
185/* set volume of stream (like volume + balance, stereo mode)
186 * volume l and r are floats from 0 ('muted', see above) to 1 (full volume).
187 * Returns 0 on no error and -1 on error.
188 */
189int     roar_vs_volume_stereo (roar_vs_t * vss, float l, float r, int * error);
190
191/* get volume from stream (like volume + balance, stereo mode)
192 * volume pointers l and r are floats from 0 ('muted', see above) to 1 (full volume).
193 * Returns 0 on no error and -1 on error.
194 * NOTE: if you want a 'mono' volume (like roar_vs_volume_mono() takes)
195 * you can just use: c = (*l + *r)/2
196 */
197int     roar_vs_volume_get    (roar_vs_t * vss, float * l, float * r, int * error);
198
199/* set an array of meta data for the stream
200 * This sets an array of meta data stored in kv of length len for
201 * the stream.
202 * This should be called before streaming is started using read or write functions
203 * but may be called at any time (for example to updata meta data).
204 * Returns 0 on no error and -1 on error.
205 * Example:
206 * struct roar_keyval kv = {.key = "TITLE", .value = "Some artist"};
207 * ret = roar_vs_meta(vss, &kv, 1, &err);
208 */
209int     roar_vs_meta          (roar_vs_t * vss, struct roar_keyval * kv, size_t len, int * error);
210
211/* sets the stream role
212 * see ../roaraudio/stream.h for possible roles
213 * Returns 0 on no error and -1 on error.
214 */
215int     roar_vs_role          (roar_vs_t * vss, int role, int * error);
216
217/* Run a single iteration.
218 * This will try to read data from source, write it to the stream
219 * and flush the buffer in buffered mode.
220 * Returns -1 on error, 0 on EOF and positive true value on no error.
221 */
222int     roar_vs_iterate       (roar_vs_t * vss, int wait, int * error);
223
224/* Iterate until EOF or error.
225 * Very simple main loop.
226 * Returns 0 on no error and -1 on error.
227 */
228int     roar_vs_run           (roar_vs_t * vss, int * error);
229
230/* Get used connection object
231 * This may be useful if you want to use functions from the main API.
232 * Returns used connection object or NULL on error.
233 */
234struct roar_connection * roar_vs_connection_obj(roar_vs_t * vss, int * error);
235
236/* Get used stream object
237 * This may be useful if you want to use functions from the main API.
238 * Returns used stream object or NULL on error.
239 */
240struct roar_stream     * roar_vs_stream_obj    (roar_vs_t * vss, int * error);
241
242/* Get used VIO object
243 * This may be useful if you want to use functions from the main API.
244 * For example this can be used in non-blocking mode
245 * to test if we can read or write. To test that use roar_vio_select().
246 * Returns used VIO object or NULL on error.
247 */
248struct roar_vio_calls  * roar_vs_vio_obj       (roar_vs_t * vss, int * error);
249
250/* send NOOP command to server
251 * This can be used to ping the server.
252 * This is of no use normally.
253 * Returns 0 on no error and -1 on error.
254 */
255#define roar_vs_noop(v, error) roar_noop(roar_vs_connection_obj((v), (error)))
256
257#endif
258
259//ll
Note: See TracBrowser for help on using the repository browser.