XMMS2
src/include/xmms/xmms_xformplugin.h
Go to the documentation of this file.
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