diff options
Diffstat (limited to 'src/decoder_api.h')
| -rw-r--r-- | src/decoder_api.h | 112 |
1 files changed, 84 insertions, 28 deletions
diff --git a/src/decoder_api.h b/src/decoder_api.h index 37090d8d0..9df6bed19 100644 --- a/src/decoder_api.h +++ b/src/decoder_api.h @@ -17,15 +17,17 @@ * 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 "check.h" #include "decoder_command.h" #include "decoder_plugin.h" #include "input_stream.h" @@ -36,65 +38,119 @@ #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); + +/** + * Call this right before decoder_command_finished() when seeking has + * failed. + * + * @param decoder the decoder object + */ +void +decoder_seek_error(struct decoder *decoder); -void decoder_seek_error(struct decoder * decoder); +/** + * 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 *is, + void *buffer, size_t length); /** - * 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). + * Sets the time stamp for the next data chunk [seconds]. The MPD + * core automatically counts it up, and a decoder plugin only needs to + * use this function if it thinks that adding to the time stamp based + * on the buffer size won't work. */ -size_t decoder_read(struct decoder *decoder, - struct input_stream *inStream, - void *buffer, size_t length); +void +decoder_timestamp(struct decoder *decoder, double t); /** * 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, - float data_time, uint16_t bitRate, +decoder_data(struct decoder *decoder, struct input_stream *is, + const void *data, size_t length, + uint16_t kbit_rate, struct replay_gain_info *replay_gain_info); /** * 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, |