Changeset 4204:79a5aeb80b85 in roaraudio for include/libroar/vs.h

Timestamp:

08/19/10 02:41:06 (14 years ago)

Author:

phi

Branch:

default

Phase:

public

Message:

write comments about the functions

File:

• include/libroar/vs.h (modified) (2 diffs)

include/libroar/vs.h

@@ -43 +43 @@
 typedef struct roar_vs roar_vs_t;
 
+/* return readable string descriping the problem */
 const char * roar_vs_strerr(int error);
 
+/* create a new VS object from normal RoarAudio connection object
+ * The connection must not be closed caller before roar_vs_close() is called.
+ * The connection is not closed by roar_vs_close().
+ */
 roar_vs_t * roar_vs_new_from_con(struct roar_connection * con, int * error);
+
+/* create a new VS object with a new connection */
 roar_vs_t * roar_vs_new(const char * server, const char * name, int * error);
 
+/* start a the stream in the VS object */
 int roar_vs_stream(roar_vs_t * vss, const struct roar_audio_info * info, int dir, int * error);
 
+/* connect to server and start stream in once
+ * this is basicly roar_vs_new() and roar_vs_stream() in one function.
+ */
 roar_vs_t * roar_vs_new_simple(const char * server, const char * name, int rate, int channels, int codec, int bits, int dir, int * error);
 
+/* create a VS object for playback.
+ * This is roar_vs_new_simple() with direction set to 'playback' (wave form data)
+ */
 #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))
 
+/* Boolean TRUE for VS functions */
 #define ROAR_VS_TRUE     1
+/* Boolean FALSE for VS functions */
 #define ROAR_VS_FALSE    0
+/* Boolean TOGGLE for VS functions */
 #define ROAR_VS_TOGGLE  -1
+/* Boolean value used to ask for a value, do not change the value only ask for current value */
 #define ROAR_VS_ASK     -2
 
+/* close and free the VS object
+ * This does all needed cleanup.
+ * If server connection was made by VS it is closed, too.
+ * If server connectionw as provided by caller it is untouched.
+ */
 int roar_vs_close(roar_vs_t * vss, int killit, int * error);
 
+/* write data to a stream
+ * This function writes some data to the stream.
+ * return is number of bytes written or -1 on error.
+ * return value can be zero to intercate no data can be written but no error.
+ * this may be the case with non-blocking streams.
+ * retruned value can be less then requested value. indecates a short write.
+ * you should wait some (short!) time (for example one main loop interation) and try again.
+ */
 ssize_t roar_vs_write(roar_vs_t * vss, const void * buf, size_t len, int * error);
+
+/* read data from a stream
+ * This function reads some data from the stream.
+ * return is number of bytes read or -1 on error.
+ * return value can be zero to intercate no data can be read but no error.
+ * this may be the case with non-blocking streams.
+ * retruned value can be less then requested value. indecates a short read.
+ * you should wait some (short!) time (for example one main loop interation) and try again.
+ */
 ssize_t roar_vs_read (roar_vs_t * vss,       void * buf, size_t len, int * error);
 
+/* wait value for waiting */
 #define ROAR_VS_WAIT   1
+/* wait value for no waiting */
 #define ROAR_VS_NOWAIT 0
 
+/* sync a stream with the server (flush buffers)
+ * Returns 0 on no error and -1 on error.
+ */
 int     roar_vs_sync (roar_vs_t * vss, int wait, int * error);
 
+/* set blocking mode of stream
+ * returns old blocking state
+ */
 int     roar_vs_blocking (roar_vs_t * vss, int val, int * error);
 
+/* TODO: document this */
 #define ROAR_VS_BACKEND_DEFAULT ROAR_VS_BACKEND_FIRST
 #define ROAR_VS_BACKEND_NONE    -1
@@ -78 +127 @@
 ssize_t roar_vs_latency(roar_vs_t * vss, int backend, int * error);
 
+/* set pause flag
+ * The pause flag should be set whenever the user presses the pause button or simular.
+ * The stream may be come blocking after the pause flag has been set.
+ * returns old pause setting (usefull with ROAR_VS_TOGGLE)
+ */
 int     roar_vs_pause(roar_vs_t * vss, int val, int * error);
 
+/* set the mute flag of the stream
+ * Thie pause flag should be set wehnever the user mutes the stream in some way.
+ * This flag is used so the volume is not changed and can be restored by the server
+ * while unmuting.
+ * It is very recommended to use this flag and not just set the volume to zero
+ * returns old mute setting (usefull with ROAR_VS_TOGGLE)
+ */
 int     roar_vs_mute (roar_vs_t * vss, int val, int * error);
 
+/* set volume of stream (all channels to the same value)
+ * volume c is float from 0 ('muted', see above) to 1 (full volume).
+ * Returns 0 on no error and -1 on error.
+ */
 int     roar_vs_volume_mono   (roar_vs_t * vss, float c, int * error);
+/* set volume of stream (like volume + ballance, stereo mode)
+ * volume l and r are floats from 0 ('muted', see above) to 1 (full volume).
+ * Returns 0 on no error and -1 on error.
+ */
 int     roar_vs_volume_stereo (roar_vs_t * vss, float l, float r, int * error);
 
+/* get volume from stream (like volume + ballance, stereo mode)
+ * volume pinters l and r are floats from 0 ('muted', see above) to 1 (full volume).
+ * Returns 0 on no error and -1 on error.
+ * NOTE: if you want a 'mono' volume (like roar_vs_volume_mono() takes)
+ * you can just use: c = (*l + *r)/2
+ */
 int     roar_vs_volume_get    (roar_vs_t * vss, float * l, float * r, int * error);
 
+/* set an array of meta data for the stream
+ * This sets an array of meta data stored in kv of length len for
+ * the stream.
+ * This should be called before streaming is started using read or write functions
+ * but may be called at any time (for example to updata meta data).
+ * Returns 0 on no error and -1 on error.
+ * Example:
+ * struct roar_keyval kv = {.key = "TITLE", .value = "Some artist"};
+ * ret = roar_vs_meta(vss, &kv, 1, &err);
+ */
 int     roar_vs_meta          (roar_vs_t * vss, struct roar_keyval * kv, size_t len, int * error);
 
+/* Get used connection object
+ * This may be usefull if you want to use functions from the main API.
+ * Returns used connection object or NULL on error.
+ */
 struct roar_connection * roar_vs_connection_obj(roar_vs_t * vss, int * error);
+
+/* Get used stream object
+ * This may be usefull if you want to use functions from the main API.
+ * Returns used stream object or NULL on error.
+ */
 struct roar_stream     * roar_vs_stream_obj    (roar_vs_t * vss, int * error);
+
+/* Get used VIO object
+ * This may be usefull if you want to use functions from the main API.
+ * For example this can be used in non-blocking mode
+ * to test if we can read or write. To test that use roar_vio_select().
+ * Returns used VIO object or NULL on error.
+ */
 struct roar_vio_calls  * roar_vs_vio_obj       (roar_vs_t * vss, int * error);
 
+/* send NOOP command to server
+ * This can be used to ping the server.
+ * This is of no use normaly.
+ * Returns 0 on no error and -1 on error.
+ */
 #define roar_vs_noop(v, error) roar_noop(roar_vs_connection_obj((v), (error)))