1 #ifndef DECODER_H 2 #define DECODER_H 3 4 #include "audio.h" 5 #include "playlist.h" 6 #include "io.h" 7 8 #ifdef __cplusplus 9 extern "C" { 10 #endif 11 12 /** Version of the decoder API. 13 * 14 * On every change in the decoder API this number will be changed, so MOC will 15 * not load plugins compiled with older/newer decoder.h. */ 16 #define DECODER_API_VERSION 7 17 18 /** Type of the decoder error. */ 19 enum decoder_error_type 20 { 21 ERROR_OK, /*!< There was no error. */ 22 ERROR_STREAM, /*!< Recoverable error in the stream. */ 23 ERROR_FATAL /*!< Fatal error in the stream - further decoding can't be 24 performed. */ 25 }; 26 27 /** Decoder error. 28 * 29 * Describes decoder error. Fields don't need to be accessed directly, there are 30 * functions to modify/access decoder_error object. */ 31 struct decoder_error 32 { 33 enum decoder_error_type type; /*!< Type of the error. */ 34 char *err; /*!< malloc()ed error string or NULL. */ 35 }; 36 37 /** @struct decoder 38 * Functions provided by the decoder plugin. 39 * 40 * Describes decoder - contains pointers to decoder's functions. If some field 41 * is optional, it may have NULL value. */ 42 struct decoder 43 { 44 /** API version used by the plugin. 45 * 46 * Set it to DECODER_API_VERSION to recognize if MOC and the plugin can 47 * communicate. This is the first field in the structure, so even after 48 * changing other fields it will hopefully be always read properly. 49 */ 50 int api_version; 51 52 /** Initialize the plugin. 53 * 54 * This function is called once at MOC startup (once for the client and 55 * once for the server). Optional. */ 56 void (*init) (); 57 58 /** Cleanup the plugin. 59 * 60 * This function is called once at exit (once for the client and 61 * once for the server). Optional. */ 62 void (*destroy) (); 63 64 /** Open the resource. 65 * 66 * Open the given resource (file). 67 * 68 * \param uri URL to the resource that can be used as the file parameter and return pointer 69 * to io_open(). 70 * 71 * \return Private decoder data. This pointer will be passed to every 72 * other function that operates on the stream. 73 */ 74 void *(*open)(const char *uri); 75 76 /** Open the resource for an already opened stream. 77 * 78 * Handle the stream that was already opened, but no data were read. 79 * You must operate on the stream using io_*() functions. This is used 80 * for internet streams, so seeking is not possible. This function is 81 * optional. 82 * 83 * \param stream Opened stream from which the decoder must read. 84 * 85 * \return Private decoder data. This pointer will be passed to every 86 * other function that operates on the stream. 87 */ 88 void *(*open_stream)(struct io_stream *stream); 89 90 /** Check if the decoder is able to decode from this stream. 91 * 92 * Used to check if the decoder is able to read from an already opened 93 * stream. This is used to find the proper decoder for an internet 94 * stream when searching by the MIME type failed. The decoder must not 95 * read from this stream (io_read()), but can peek data (io_peek()). 96 * The decoder is expected to peek a few bytes to recognize its format. 97 * Optional. 98 * 99 * \param stream Opened stream. 100 * 101 * \return 1 if the decoder is able to decode data from this stream. 102 */ 103 int (*can_decode)(struct io_stream *stream); 104 105 /** Close the resource and cleanup. 106 * 107 * Free all decoder's private data and allocated resources. 108 * 109 * \param data Decoder's private data. 110 */ 111 void (*close)(void *data); 112 113 /** Decode a piece of input. 114 * 115 * Decode a piece of input and write it to the buffer. The buffer size 116 * is at least 32KB, but don't make any assumptions that it is always 117 * true. It is preferred that as few bytes as possible be decoded 118 * without loss of performance to minimise delays. 119 * 120 * \param data Decoder's private data. 121 * \param buf Buffer to put data in. 122 * \param buf_len Size of the buffer in bytes. 123 * \param sound_params Parameters of the decoded sound. This must be 124 * always filled. 125 * 126 * \return Number of bytes written or 0 on EOF. 127 */ 128 int (*decode)(void *data, char *buf, int buf_len, 129 struct sound_params *sound_params); 130 131 /** Seek in the stream. 132 * 133 * Seek to the given position. 134 * 135 * \param data Decoder's private data. 136 * \param sec Where to seek in seconds (never less than zero). 137 * 138 * \return The position that we actually seek to or -1 on error. 139 * -1 is not a fatal error and further decoding will be performed. 140 */ 141 int (*seek)(void *data, int sec); 142 143 /** Get tags for a file. 144 * 145 * Get requested file's tags. If some tags are not available, the 146 * decoder can just not fill the field. The function can even not 147 * fill any field. 148 * 149 * \param file File for which to get tags. 150 * \param tags Pointer to the tags structure where we must put 151 * the tags. All strings must be malloc()ed. 152 * \param tags_sel OR'ed list of requested tags (values of 153 * enum tags_select). 154 */ 155 void (*info)(const char *file, struct file_tags *tags, 156 const int tags_sel); 157 158 /** Get the current bitrate. 159 * 160 * Get the bitrate of the last decoded piece of sound. 161 * 162 * \param data Decoder's private data. 163 * 164 * \return Current bitrate in kbps or -1 if not available. 165 */ 166 int (*get_bitrate)(void *data); 167 168 /** Get duration of the stream. 169 * 170 * Get duration of the stream. It is used as a faster alternative 171 * for getting duration than using info() if the file is opened. 172 * 173 * \param data Decoder's private data. 174 * 175 * \return Duration in seconds or -1 on error. -1 is not a fatal 176 * error, further decoding will be performed. 177 */ 178 int (*get_duration)(void *data); 179 180 /** Get error for the last decode() invocation. 181 * 182 * Get the error for the last decode() invocation. If there was no 183 * error the type of the error must be ERROR_OK. Don't access the 184 * error object's fields directly, there are proper functions for 185 * that. 186 * 187 * \param data Decoder's private data. 188 * \param error Pointer to the decoder_error object to fill. 189 */ 190 void (*get_error)(void *data, struct decoder_error *error); 191 192 /** Check if the file extension is for a file that this decoder 193 * supports. 194 * 195 * \param ext Extension (chars after the last dot in the file name). 196 * 197 * \return Value other than 0 if the extension if a file with this 198 * extension is supported. 199 */ 200 int (*our_format_ext)(const char *ext); 201 202 /** Check if a stream with the given MIME type is supported by this 203 * decoder. Optional. 204 * 205 * \param mime_type MIME type. 206 * 207 * \return Value other than 0 if a stream with this MIME type is 208 * supported. 209 */ 210 int (*our_format_mime)(const char *mime_type); 211 212 /** Get a 3-chars format name for a file. 213 * 214 * Get an abbreviated format name (up to 3 chars) for a file. 215 * 216 * \param file File for which we want the format name. 217 * \param buf Buffer where the format name and ending zero-byte 218 * must be put. 219 */ 220 void (*get_name)(const char *file, char buf[4]); 221 222 /** Get current tags for the stream. 223 * 224 * Fill the tags structure with the current tags for the stream. This 225 * is intended for internet streams and used when the source of the 226 * stream doesn't provide tags while broadcasting. This function is 227 * optional. 228 * 229 * \param data Decoder's private data. 230 * 231 * \return 1 if the tags were changed from the last call of this 232 * function or 0 if not. 233 */ 234 int (*current_tags)(void *data, struct file_tags *tags); 235 236 /** Get the IO stream used by the decoder. 237 * 238 * Get the pointer to the io_stream object used by the decoder. This is 239 * used for fast interrupting especially when the stream reads from 240 * a network. This function is optional. 241 * 242 * \param data Decoder's private data. 243 * 244 * \return Pointer to the used IO stream. 245 */ 246 struct io_stream *(*get_stream)(void *data); 247 248 /** Get the average bitrate. 249 * 250 * Get the bitrate of the whole file. 251 * 252 * \param data Decoder's private data. 253 * 254 * \return Average bitrate in kbps or -1 if not available. 255 */ 256 int (*get_avg_bitrate)(void *data); 257 }; 258 259 /** Initialize decoder plugin. 260 * 261 * Each decoder plugin must export a function name plugin_init of this type. 262 * The function must return a pointer to the struct decoder variable filled 263 * with pointers to decoder's functions. 264 */ 265 typedef struct decoder *(*plugin_init_func)(); 266 267 int is_sound_file (const char *name); 268 struct decoder *get_decoder (const char *file); 269 struct decoder *get_decoder_by_content (struct io_stream *stream); 270 const char *get_decoder_name (const struct decoder *decoder); 271 void decoder_init (int debug_info); 272 void decoder_cleanup (); 273 char *file_type_name (const char *file); 274 275 /** @defgroup decoder_error_funcs Decoder error functions 276 * 277 * These functions can be used to modify variables of the decoder_error 278 * structure. 279 */ 280 /*@{*/ 281 282 /** Fill decoder_error structure with an error. 283 * 284 * Fills decoder error variable with an error. It can be used like printf(). 285 * 286 * \param error Pointer to the decoder error variable to fill. 287 * \param type Type of the error. 288 * \param add_errno If this value is non-zero, a space and a string describing 289 * system error for errno equal to the value of add_errno is appended to the 290 * error message. 291 * \param format Format, like in the printf() function. 292 */ 293 #ifdef HAVE__ATTRIBUTE__ 294 void decoder_error (struct decoder_error *error, 295 const enum decoder_error_type type, const int add_errno, 296 const char *format, ...) __attribute__((format (printf, 4, 5))); 297 #else 298 void decoder_error (struct decoder_error *error, 299 const enum decoder_error_type type, const int add_errno, 300 const char *format, ...); 301 #endif 302 303 /** Clear decoder_error structure. 304 * 305 * Clear decoder_error structure. Set the system type to ERROR_OK and 306 * the error message to NULL. Frees all memory used by the error's fields. 307 */ 308 void decoder_error_clear (struct decoder_error *error); 309 310 /** Copy decoder_error variable. 311 * 312 * Copies the decoder_error variable to another decoder_error variable. 313 * 314 * \param dst Destination. 315 * \param src Source. 316 */ 317 void decoder_error_copy (struct decoder_error *dst, 318 const struct decoder_error *src); 319 320 /** Return the error text from the decoder_error variable. 321 * 322 * Returns the error text from the decoder_error variable. NULL may be 323 * returned if decoder_error() has not been called. 324 * 325 * \param dst Destination. 326 * \param src Source. 327 * 328 * \return The address of the error text or NULL. 329 */ 330 const char *decoder_error_text (const struct decoder_error *error); 331 332 /** Initialize decoder_error variable. 333 * 334 * Initialize decoder_error variable and set the error to ERROR_OK with no 335 * message. 336 */ 337 void decoder_error_init (struct decoder_error *error); 338 339 /*@}*/ 340 341 #ifdef __cplusplus 342 } 343 #endif 344 345 #endif 346