XMMS2
|
00001 /* XMMS2 - X Music Multiplexer System 00002 * Copyright (C) 2003-2011 XMMS2 Team 00003 * 00004 * PLUGINS ARE NOT CONSIDERED TO BE DERIVED WORK !!! 00005 * 00006 * This library is free software; you can redistribute it and/or 00007 * modify it under the terms of the GNU Lesser General Public 00008 * License as published by the Free Software Foundation; either 00009 * version 2.1 of the License, or (at your option) any later version. 00010 * 00011 * This library is distributed in the hope that it will be useful, 00012 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 00014 * Lesser General Public License for more details. 00015 */ 00016 00017 00018 00019 00020 #ifndef __XMMS_XFORMPLUGIN_H__ 00021 #define __XMMS_XFORMPLUGIN_H__ 00022 00023 #include <glib.h> 00024 #include <string.h> 00025 00026 /** 00027 * @defgroup XForm XForm 00028 * @ingroup XMMSServer 00029 * @brief XForm API 00030 * 00031 * An xform (transform) is something that reads data and applies some 00032 * kind of transformation to it such as decoding or demuxing or 00033 * applying an effect. 00034 * 00035 * The xform api is designed to allow xforms to be connected in a 00036 * chain where each xform does a different transformation step. Each 00037 * xform provides a "read" method, which should return transformed 00038 * data and when it needs more input data, it should call the read 00039 * method of the previous xform in the chain. 00040 * 00041 * The type of the data flowing from one xform to another is described 00042 * by an xmms_stream_type_t. So an xform registers which 00043 * xmms_stream_type_t it wants as input and when initialised it tells 00044 * what type the output data is. This allows the chain of xforms to 00045 * easily be built. 00046 * 00047 * @{ 00048 */ 00049 00050 00051 00052 #define XMMS_XFORM_API_VERSION 7 00053 00054 #include "xmms/xmms_error.h" 00055 #include "xmms/xmms_plugin.h" 00056 #include "xmms/xmms_sample.h" 00057 #include "xmms/xmms_streamtype.h" 00058 #include "xmms/xmms_config.h" 00059 #include "xmms/xmms_medialib.h" 00060 00061 00062 G_BEGIN_DECLS 00063 00064 struct xmms_xform_plugin_St; 00065 /** 00066 * Xform plugin. 00067 */ 00068 typedef struct xmms_xform_plugin_St xmms_xform_plugin_t; 00069 00070 /** 00071 * Declare an xform plugin. 00072 * Use this macro _ONCE_ for each plugin. 00073 * 00074 * @param shname Short name of the plugin, should not contain any 00075 * special characters, just a-z A-Z 0-9 and _. 00076 * @param name Full name, display name for plugin. 00077 * @param ver Version of plugin, as string. 00078 * @param desc Description of plugin and its uses. 00079 * @param setupfunc Function to be called when initializing plugin. 00080 * 00081 * 00082 * example: 00083 * XMMS_XFORM_PLUGIN("example", 00084 * "Example decoder", 00085 * "1.3.37-beta", 00086 * "Decoder for playing example files", 00087 * xmms_example_setup); 00088 * 00089 */ 00090 #define XMMS_XFORM_PLUGIN(shname, name, ver, desc, setupfunc) XMMS_PLUGIN(XMMS_PLUGIN_TYPE_XFORM, XMMS_XFORM_API_VERSION, shname, name, ver, desc, (gboolean (*)(gpointer))setupfunc) 00091 00092 /* */ 00093 00094 struct xmms_xform_St; 00095 /* xform */ 00096 typedef struct xmms_xform_St xmms_xform_t; 00097 00098 /** 00099 * Seek direction argument. 00100 */ 00101 typedef enum xmms_xform_seek_mode_E { 00102 XMMS_XFORM_SEEK_CUR = 1, 00103 XMMS_XFORM_SEEK_SET = 2, 00104 XMMS_XFORM_SEEK_END = 3 00105 } xmms_xform_seek_mode_t; 00106 00107 /** 00108 * Methods provided by an xform plugin. 00109 */ 00110 typedef struct xmms_xform_methods_St { 00111 /** 00112 * Initialisation method. 00113 * 00114 * Called when a new xform is to be instantiated. It should 00115 * prepare for the transformation and use 00116 * #xmms_xform_outdata_type_add to inform what type of data it 00117 * outputs. 00118 * 00119 * @returns TRUE if initialisation was successful, FALSE otherwise. 00120 */ 00121 gboolean (*init)(xmms_xform_t *); 00122 /** 00123 * Destruction method. 00124 * 00125 * Called when the xform isn't needed anymore. Should free any 00126 * resources used by the xform. 00127 */ 00128 void (*destroy)(xmms_xform_t *); 00129 /** 00130 * Read method. 00131 * 00132 * Called to read data from the xform. 00133 */ 00134 gint (*read)(xmms_xform_t *, gpointer, gint, xmms_error_t *); 00135 /** 00136 * Seek method. 00137 * 00138 * Called to change the offset in the stream. Observe that 00139 * the offset is measured in "natural" units; audio/pcm-data 00140 * is measured in samples, application/octet-stream in bytes. 00141 * 00142 */ 00143 gint64 (*seek)(xmms_xform_t *, gint64, xmms_xform_seek_mode_t, xmms_error_t *); 00144 00145 /** 00146 * browse method. 00147 * 00148 * Called when a users wants to do some server side browsing. 00149 * This is called without init() beeing called. 00150 */ 00151 gboolean (*browse)(xmms_xform_t *, const gchar *, xmms_error_t *); 00152 } xmms_xform_methods_t; 00153 00154 #define XMMS_XFORM_METHODS_INIT(m) memset (&m, 0, sizeof (xmms_xform_methods_t)) 00155 00156 00157 /** 00158 * 00159 * Should be called _once_ from the plugin's setupfunc. 00160 */ 00161 void xmms_xform_plugin_methods_set (xmms_xform_plugin_t *plugin, xmms_xform_methods_t *methods); 00162 /** 00163 * Add a valid input type to the plugin. 00164 * 00165 * The varargs should contain key-value pairs terminated with 00166 * XMMS_STREAM_TYPE_END. 00167 * 00168 * Should be called from the plugin's setupfunc. 00169 * 00170 * @param plugin the plugin 00171 * @param ... variable length arguments, terminated with XMMS_STREAM_TYPE_END 00172 * 00173 * example: 00174 * xmms_xform_plugin_indata_add (plugin, 00175 * XMMS_STREAM_TYPE_MIMETYPE, 00176 * "application/example", 00177 * XMMS_STREAM_TYPE_END); 00178 */ 00179 void xmms_xform_plugin_indata_add (xmms_xform_plugin_t *plugin, ...); 00180 00181 /** 00182 * Get private data for this xform. 00183 * 00184 * @param xform current xform 00185 * @returns the data set with #xmms_xform_private_data_set 00186 */ 00187 gpointer xmms_xform_private_data_get (xmms_xform_t *xform); 00188 /** 00189 * Set private data for this xform. 00190 * 00191 * Allows keeping information across calls to methods of the 00192 * xform. Usually set from init method and accessed with 00193 * #xmms_xform_private_data_get in read, seek and destroy methods. 00194 * 00195 * @param xform current xform 00196 * @param data 00197 */ 00198 void xmms_xform_private_data_set (xmms_xform_t *xform, gpointer data); 00199 00200 00201 void xmms_xform_outdata_type_add (xmms_xform_t *xform, ...); 00202 void xmms_xform_outdata_type_copy (xmms_xform_t *xform); 00203 00204 /** 00205 * Set numeric metadata for the media transformed by this xform. 00206 * 00207 * @param xform 00208 * @param key Metadatum key to set. Should preferably be one of the XMMS_MEDIALIB_ENTRY_PROPERTY_* values. 00209 * @param val 00210 */ 00211 void xmms_xform_metadata_set_int (xmms_xform_t *xform, const gchar *key, int val); 00212 /** 00213 * Set string metadata for the media transformed by this xform. 00214 * 00215 * @param xform 00216 * @param key Metadatum key to set. Should preferably be one of the XMMS_MEDIALIB_ENTRY_PROPERTY_* values. 00217 * @param val 00218 */ 00219 void xmms_xform_metadata_set_str (xmms_xform_t *xform, const gchar *key, const char *val); 00220 00221 gboolean xmms_xform_metadata_has_val (xmms_xform_t *xform, const gchar *key); 00222 gboolean xmms_xform_metadata_get_int (xmms_xform_t *xform, const gchar *key, 00223 gint *val); 00224 gboolean xmms_xform_metadata_get_str (xmms_xform_t *xform, const gchar *key, 00225 const gchar **val); 00226 void xmms_xform_auxdata_barrier (xmms_xform_t *xform); 00227 void xmms_xform_auxdata_set_int (xmms_xform_t *xform, const gchar *key, gint32 val); 00228 void xmms_xform_auxdata_set_str (xmms_xform_t *xform, const gchar *key, const gchar *val); 00229 void xmms_xform_auxdata_set_bin (xmms_xform_t *xform, const gchar *key, gpointer data, gssize len); 00230 gboolean xmms_xform_auxdata_has_val (xmms_xform_t *xform, const gchar *key); 00231 gboolean xmms_xform_auxdata_get_int (xmms_xform_t *xform, const gchar *key, gint32 *val); 00232 gboolean xmms_xform_auxdata_get_str (xmms_xform_t *xform, const gchar *key, const gchar **val); 00233 gboolean xmms_xform_auxdata_get_bin (xmms_xform_t *xform, const gchar *key, const guchar **data, gsize *datalen); 00234 00235 const char *xmms_xform_indata_get_str (xmms_xform_t *xform, xmms_stream_type_key_t key); 00236 gint xmms_xform_indata_get_int (xmms_xform_t *xform, xmms_stream_type_key_t key); 00237 00238 /** 00239 * Preview data from previous xform. 00240 * 00241 * Allows an xform to look at its input data without consuming it so 00242 * that a subsequent call to #xmms_xform_read will get the same 00243 * data. Up to siz bytes are read into the supplied buffer starting at 00244 * buf. If siz is less than one xmms_xform_read just returns zero. On 00245 * error -1 is returned and the error is stored in the supplied 00246 * #xmms_error_t. On end of stream zero is returned. 00247 * 00248 * @param xform 00249 * @param buf buffer to read data into 00250 * @param siz size of buffer 00251 * @param err error container which is filled in if error occours. 00252 * @returns the number of bytes read or -1 to indicate error and 0 when end of stream. 00253 */ 00254 gint xmms_xform_peek (xmms_xform_t *xform, gpointer buf, gint siz, xmms_error_t *err); 00255 00256 /** 00257 * Read one line from previous xform. 00258 * 00259 * Reads a line from the prev xform into buf. 00260 * 00261 * @param xform 00262 * @param buf buffer to write the line to, should be at least XMMS_XFORM_MAX_LINE_SIZE 00263 * @param err error container which is filled in if error occours. 00264 * @returns the line read from the parent or NULL to indicate error. 00265 */ 00266 gchar *xmms_xform_read_line (xmms_xform_t *xform, gchar *buf, xmms_error_t *err); 00267 00268 /** 00269 * Read data from previous xform. 00270 * 00271 * Reads up to siz bytes into the supplied buffer starting at buf. If 00272 * siz is less than one xmms_xform_read just returns zero. On error -1 00273 * is returned and the error is stored in the supplied 00274 * #xmms_error_t. On end of stream zero is returned. 00275 * 00276 * @param xform 00277 * @param buf buffer to read data into 00278 * @param siz size of buffer 00279 * @param err error container which is filled in if error occours. 00280 * @returns the number of bytes read or -1 to indicate error and 0 when end of stream. 00281 */ 00282 gint xmms_xform_read (xmms_xform_t *xform, gpointer buf, gint siz, xmms_error_t *err); 00283 00284 /** 00285 * Change offset in stream. 00286 * 00287 * Tries to change the offset from which data is read. 00288 * 00289 * @param xform 00290 * @param offset offset to seek to, measured in "natural" units 00291 * @param whence one of XMMS_XFORM_SEEK_{CUR,END,SET} 00292 * @param err error container which is filled in if error occours. 00293 * @returns new offset in stream, or -1 on error. 00294 * 00295 */ 00296 gint64 xmms_xform_seek (xmms_xform_t *xform, gint64 offset, xmms_xform_seek_mode_t whence, xmms_error_t *err); 00297 gboolean xmms_xform_iseos (xmms_xform_t *xform); 00298 00299 const xmms_stream_type_t *xmms_xform_get_out_stream_type (xmms_xform_t *xform); 00300 00301 gboolean xmms_magic_add (const gchar *desc, const gchar *mime, ...); 00302 gboolean xmms_magic_extension_add (const gchar *mime, const gchar *ext); 00303 00304 xmms_config_property_t *xmms_xform_plugin_config_property_register ( 00305 xmms_xform_plugin_t *xform_plugin, 00306 const gchar *name, 00307 const gchar *default_value, 00308 xmms_object_handler_t cb, 00309 gpointer userdata); 00310 xmms_config_property_t *xmms_xform_config_lookup (xmms_xform_t *xform, 00311 const gchar *path); 00312 00313 /** 00314 * Get the medialib entry played by this xform. 00315 * 00316 * @param xform 00317 * @returns 00318 */ 00319 xmms_medialib_entry_t xmms_xform_entry_get (xmms_xform_t *xform); 00320 const gchar *xmms_xform_get_url (xmms_xform_t *xform); 00321 00322 #define XMMS_XFORM_BROWSE_FLAG_DIR (1 << 0) 00323 00324 void xmms_xform_browse_add_entry (xmms_xform_t *xform, const gchar *path, guint32 flags); 00325 void xmms_xform_browse_add_entry_property (xmms_xform_t *xform, const gchar *key, xmmsv_t *val); 00326 void xmms_xform_browse_add_entry_property_str (xmms_xform_t *xform, 00327 const gchar *key, 00328 const gchar *value); 00329 void xmms_xform_browse_add_entry_property_int (xmms_xform_t *xform, 00330 const gchar *key, 00331 gint value); 00332 void xmms_xform_browse_add_symlink (xmms_xform_t *xform, const gchar *basename, const gchar *url); 00333 void xmms_xform_browse_add_symlink_args (xmms_xform_t *xform, const gchar *basename, const gchar *url, gint nargs, char **args); 00334 00335 #define XMMS_XFORM_MAX_LINE_SIZE 1024 00336 00337 /** 00338 * @} 00339 */ 00340 G_END_DECLS 00341 00342 #endif