X-Git-Url: http://git.tuebingen.mpg.de/?p=paraslash.git;a=blobdiff_plain;f=audiod.c;h=dd6022889280eb6b19980ccdb0750af1306401fc;hp=72276ffe072f1a24fa67ac866e18c4d9a33889cd;hb=50fac71430f5993560d40eb5044d45d8255d7ca6;hpb=a2fb56bdfa2726d401de8c1c3cd569ba96a5ccc3

diff --git a/audiod.c b/audiod.c
index 72276ffe..dd602288 100644
--- a/audiod.c
+++ b/audiod.c
@@ -160,8 +160,9 @@ struct command_task {
 #define FOR_EACH_AUDIO_FORMAT(af) for (af = 0; af < NUM_AUDIO_FORMATS; af++)
 
 /**
- * get the audio format number
- * \param name the name of the audio format
+ * Get the audio format number.
+ *
+ * \param name The name of the audio format.
  *
  * \return The audio format number on success, -E_UNSUPPORTED_AUDIO_FORMAT if
  * \a name is not a supported audio format.
@@ -178,6 +179,27 @@ int get_audio_format_num(const char *name)
 	return -E_UNSUPPORTED_AUDIO_FORMAT;
 }
 
+/**
+ * Compute the play time based on information of the given slot.
+ *
+ * \param slot_num The slot number (negative means: no slot).
+ *
+ * This computes a string of the form "0:07 [3:33] (3%/3:40)" using information
+ * from the status items received from para_server and the start time of the
+ * (first) writer of the given slot.
+ *
+ * It has to to take into account that probably the stream was not started at
+ * the beginning of the file, that the clock between the server and the client
+ * host may differ and that playback of the stream was delayed, e.g. because
+ * the prebuffer filter is used in the filter chain of the given slot.
+ *
+ * If no writer is active in the given slot, or \a slot_num is negative
+ * (indicating that para_audiod runs in standby mode), an approximation based
+ * only on the status items is computed and the returned string is prefixed
+ * with "~".
+ *
+ * \return A string that must be freed by the caller.
+ */
 char *get_time_string(int slot_num)
 {
 	int ret, seconds = 0, length;
@@ -580,6 +602,15 @@ static int receiver_running(int format)
 	return ret;
 }
 
+/**
+ * Return the root node of the current buffer tree.
+ *
+ * This is only used for stream grabbing.
+ *
+ * \return \p NULL if no slot is currently active. If more than one buffer tree
+ * exists, the node corresponding to the most recently started receiver is
+ * returned.
+ */
 struct btr_node *audiod_get_btr_root(void)
 {
 	int i, newest_slot = -1;