aboutsummaryrefslogtreecommitdiffstats
path: root/src/decoder_api.h
diff options
context:
space:
mode:
authorMax Kellermann <max@duempel.org>2009-10-08 15:39:45 +0200
committerMax Kellermann <max@duempel.org>2009-10-08 15:39:45 +0200
commit16c981d425d4021d696630566ce531a3ce50d01d (patch)
treeceb91d3ae712f0c018c20cd1ac3d82bb491be5de /src/decoder_api.h
parent81e56705ada331fcb44537e5e5545a1379f601f4 (diff)
downloadmpd-16c981d425d4021d696630566ce531a3ce50d01d.tar.gz
mpd-16c981d425d4021d696630566ce531a3ce50d01d.tar.xz
mpd-16c981d425d4021d696630566ce531a3ce50d01d.zip
decoder_api: document all function parameters
Diffstat (limited to '')
-rw-r--r--src/decoder_api.h100
1 files changed, 73 insertions, 27 deletions
diff --git a/src/decoder_api.h b/src/decoder_api.h
index 37090d8d0..2ecd98ce7 100644
--- a/src/decoder_api.h
+++ b/src/decoder_api.h
@@ -17,15 +17,16 @@
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
*/
-#ifndef MPD_DECODER_API_H
-#define MPD_DECODER_API_H
-
-/*
+/*! \file
+ * \brief The MPD Decoder API
+ *
* This is the public API which is used by decoder plugins to
* communicate with the mpd core.
- *
*/
+#ifndef MPD_DECODER_API_H
+#define MPD_DECODER_API_H
+
#include "decoder_command.h"
#include "decoder_plugin.h"
#include "input_stream.h"
@@ -36,56 +37,97 @@
#include <stdbool.h>
-
/**
* Notify the player thread that it has finished initialization and
* that it has read the song's meta data.
+ *
+ * @param decoder the decoder object
+ * @param audio_format the audio format which is going to be sent to
+ * decoder_data()
+ * @param seekable true if the song is seekable
+ * @param total_time the total number of seconds in this song; -1 if unknown
*/
-void decoder_initialized(struct decoder * decoder,
- const struct audio_format *audio_format,
- bool seekable, float total_time);
+void
+decoder_initialized(struct decoder *decoder,
+ const struct audio_format *audio_format,
+ bool seekable, float total_time);
/**
* Returns the URI of the current song in UTF-8 encoding.
*
- * The return value is allocated on the heap, and must be freed by the
- * caller.
+ * @param decoder the decoder object
+ * @return an allocated string which must be freed with g_free()
*/
-char *decoder_get_uri(struct decoder *decoder);
+char *
+decoder_get_uri(struct decoder *decoder);
-enum decoder_command decoder_get_command(struct decoder * decoder);
+/**
+ * Determines the pending decoder command.
+ *
+ * @param decoder the decoder object
+ * @return the current command, or DECODE_COMMAND_NONE if there is no
+ * command pending
+ */
+enum decoder_command
+decoder_get_command(struct decoder *decoder);
/**
* Called by the decoder when it has performed the requested command
* (dc->command). This function resets dc->command and wakes up the
* player thread.
+ *
+ * @param decoder the decoder object
*/
-void decoder_command_finished(struct decoder * decoder);
+void
+decoder_command_finished(struct decoder *decoder);
-double decoder_seek_where(struct decoder * decoder);
+/**
+ * Call this when you have received the DECODE_COMMAND_SEEK command.
+ *
+ * @param decoder the decoder object
+ * @return the destination position for the week
+ */
+double
+decoder_seek_where(struct decoder *decoder);
-void decoder_seek_error(struct decoder * decoder);
+/**
+ * Call this right before decoder_command_finished() when seeking has
+ * failed.
+ *
+ * @param decoder the decoder object
+ */
+void
+decoder_seek_error(struct decoder *decoder);
/**
- * Blocking read from the input stream. Returns the number of bytes
- * read, or 0 if one of the following occurs: end of file; error;
- * command (like SEEK or STOP).
+ * Blocking read from the input stream.
+ *
+ * @param decoder the decoder object
+ * @param is the input stream to read from
+ * @param buffer the destination buffer
+ * @param length the maximum number of bytes to read
+ * @return the number of bytes read, or 0 if one of the following
+ * occurs: end of file; error; command (like SEEK or STOP).
*/
-size_t decoder_read(struct decoder *decoder,
- struct input_stream *inStream,
- void *buffer, size_t length);
+size_t
+decoder_read(struct decoder *decoder, struct input_stream *is,
+ void *buffer, size_t length);
/**
* This function is called by the decoder plugin when it has
* successfully decoded block of input data.
*
- * We send inStream for buffering the inputStream while waiting to
- * send the next chunk
+ * @param decoder the decoder object
+ * @param is an input stream which is buffering while we are waiting
+ * for the player
+ * @param data the source buffer
+ * @param length the number of bytes in the buffer
+ * @return the current command, or DECODE_COMMAND_NONE if there is no
+ * command pending
*/
enum decoder_command
-decoder_data(struct decoder *decoder,
- struct input_stream *inStream,
- const void *data, size_t datalen,
+decoder_data(struct decoder *decoder, struct input_stream *is,
+ const void *data, size_t length,
float data_time, uint16_t bitRate,
struct replay_gain_info *replay_gain_info);
@@ -93,8 +135,12 @@ decoder_data(struct decoder *decoder,
* This function is called by the decoder plugin when it has
* successfully decoded a tag.
*
+ * @param decoder the decoder object
* @param is an input stream which is buffering while we are waiting
* for the player
+ * @param tag the tag to send
+ * @return the current command, or DECODE_COMMAND_NONE if there is no
+ * command pending
*/
enum decoder_command
decoder_tag(struct decoder *decoder, struct input_stream *is,