XMMS2
xmms_xformplugin.h
Go to the documentation of this file.
1 /* XMMS2 - X Music Multiplexer System
2  * Copyright (C) 2003-2011 XMMS2 Team
3  *
4  * PLUGINS ARE NOT CONSIDERED TO BE DERIVED WORK !!!
5  *
6  * This library is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU Lesser General Public
8  * License as published by the Free Software Foundation; either
9  * version 2.1 of the License, or (at your option) any later version.
10  *
11  * This library is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  * Lesser General Public License for more details.
15  */
16 
17 
18 
19 
20 #ifndef __XMMS_XFORMPLUGIN_H__
21 #define __XMMS_XFORMPLUGIN_H__
22 
23 #include <glib.h>
24 #include <string.h>
25 
26 /**
27  * @defgroup XForm XForm
28  * @ingroup XMMSServer
29  * @brief XForm API
30  *
31  * An xform (transform) is something that reads data and applies some
32  * kind of transformation to it such as decoding or demuxing or
33  * applying an effect.
34  *
35  * The xform api is designed to allow xforms to be connected in a
36  * chain where each xform does a different transformation step. Each
37  * xform provides a "read" method, which should return transformed
38  * data and when it needs more input data, it should call the read
39  * method of the previous xform in the chain.
40  *
41  * The type of the data flowing from one xform to another is described
42  * by an xmms_stream_type_t. So an xform registers which
43  * xmms_stream_type_t it wants as input and when initialised it tells
44  * what type the output data is. This allows the chain of xforms to
45  * easily be built.
46  *
47  * @{
48  */
49 
50 
51 
52 #define XMMS_XFORM_API_VERSION 7
53 
54 #include "xmms/xmms_error.h"
55 #include "xmms/xmms_plugin.h"
56 #include "xmms/xmms_sample.h"
57 #include "xmms/xmms_streamtype.h"
58 #include "xmms/xmms_config.h"
59 #include "xmms/xmms_medialib.h"
60 
61 
62 G_BEGIN_DECLS
63 
64 struct xmms_xform_plugin_St;
65 /**
66  * Xform plugin.
67  */
68 typedef struct xmms_xform_plugin_St xmms_xform_plugin_t;
69 
70 /**
71  * Declare an xform plugin.
72  * Use this macro _ONCE_ for each plugin.
73  *
74  * @param shname Short name of the plugin, should not contain any
75  * special characters, just a-z A-Z 0-9 and _.
76  * @param name Full name, display name for plugin.
77  * @param ver Version of plugin, as string.
78  * @param desc Description of plugin and its uses.
79  * @param setupfunc Function to be called when initializing plugin.
80  *
81  *
82  * example:
83  * XMMS_XFORM_PLUGIN("example",
84  * "Example decoder",
85  * "1.3.37-beta",
86  * "Decoder for playing example files",
87  * xmms_example_setup);
88  *
89  */
90 #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)
91 
92 /* */
93 
94 struct xmms_xform_St;
95 /* xform */
96 typedef struct xmms_xform_St xmms_xform_t;
97 
98 /**
99  * Seek direction argument.
100  */
106 
107 /**
108  * Methods provided by an xform plugin.
109  */
110 typedef struct xmms_xform_methods_St {
111  /**
112  * Initialisation method.
113  *
114  * Called when a new xform is to be instantiated. It should
115  * prepare for the transformation and use
116  * #xmms_xform_outdata_type_add to inform what type of data it
117  * outputs.
118  *
119  * @returns TRUE if initialisation was successful, FALSE otherwise.
120  */
121  gboolean (*init)(xmms_xform_t *);
122  /**
123  * Destruction method.
124  *
125  * Called when the xform isn't needed anymore. Should free any
126  * resources used by the xform.
127  */
128  void (*destroy)(xmms_xform_t *);
129  /**
130  * Read method.
131  *
132  * Called to read data from the xform.
133  */
134  gint (*read)(xmms_xform_t *, gpointer, gint, xmms_error_t *);
135  /**
136  * Seek method.
137  *
138  * Called to change the offset in the stream. Observe that
139  * the offset is measured in "natural" units; audio/pcm-data
140  * is measured in samples, application/octet-stream in bytes.
141  *
142  */
144 
145  /**
146  * browse method.
147  *
148  * Called when a users wants to do some server side browsing.
149  * This is called without init() beeing called.
150  */
151  gboolean (*browse)(xmms_xform_t *, const gchar *, xmms_error_t *);
153 
154 #define XMMS_XFORM_METHODS_INIT(m) memset (&m, 0, sizeof (xmms_xform_methods_t))
155 
156 
157 /**
158  *
159  * Should be called _once_ from the plugin's setupfunc.
160  */
162 /**
163  * Add a valid input type to the plugin.
164  *
165  * The varargs should contain key-value pairs terminated with
166  * XMMS_STREAM_TYPE_END.
167  *
168  * Should be called from the plugin's setupfunc.
169  *
170  * @param plugin the plugin
171  * @param ... variable length arguments, terminated with XMMS_STREAM_TYPE_END
172  *
173  * example:
174  * xmms_xform_plugin_indata_add (plugin,
175  * XMMS_STREAM_TYPE_MIMETYPE,
176  * "application/example",
177  * XMMS_STREAM_TYPE_END);
178  */
180 
181 /**
182  * Get private data for this xform.
183  *
184  * @param xform current xform
185  * @returns the data set with #xmms_xform_private_data_set
186  */
187 gpointer xmms_xform_private_data_get (xmms_xform_t *xform);
188 /**
189  * Set private data for this xform.
190  *
191  * Allows keeping information across calls to methods of the
192  * xform. Usually set from init method and accessed with
193  * #xmms_xform_private_data_get in read, seek and destroy methods.
194  *
195  * @param xform current xform
196  * @param data
197  */
198 void xmms_xform_private_data_set (xmms_xform_t *xform, gpointer data);
199 
200 
201 void xmms_xform_outdata_type_add (xmms_xform_t *xform, ...);
203 
204 /**
205  * Set numeric metadata for the media transformed by this xform.
206  *
207  * @param xform
208  * @param key Metadatum key to set. Should preferably be one of the XMMS_MEDIALIB_ENTRY_PROPERTY_* values.
209  * @param val
210  */
211 void xmms_xform_metadata_set_int (xmms_xform_t *xform, const gchar *key, int val);
212 /**
213  * Set string metadata for the media transformed by this xform.
214  *
215  * @param xform
216  * @param key Metadatum key to set. Should preferably be one of the XMMS_MEDIALIB_ENTRY_PROPERTY_* values.
217  * @param val
218  */
219 void xmms_xform_metadata_set_str (xmms_xform_t *xform, const gchar *key, const char *val);
220 
221 gboolean xmms_xform_metadata_has_val (xmms_xform_t *xform, const gchar *key);
222 gboolean xmms_xform_metadata_get_int (xmms_xform_t *xform, const gchar *key,
223  gint *val);
224 gboolean xmms_xform_metadata_get_str (xmms_xform_t *xform, const gchar *key,
225  const gchar **val);
227 void xmms_xform_auxdata_set_int (xmms_xform_t *xform, const gchar *key, gint32 val);
228 void xmms_xform_auxdata_set_str (xmms_xform_t *xform, const gchar *key, const gchar *val);
229 void xmms_xform_auxdata_set_bin (xmms_xform_t *xform, const gchar *key, gpointer data, gssize len);
230 gboolean xmms_xform_auxdata_has_val (xmms_xform_t *xform, const gchar *key);
231 gboolean xmms_xform_auxdata_get_int (xmms_xform_t *xform, const gchar *key, gint32 *val);
232 gboolean xmms_xform_auxdata_get_str (xmms_xform_t *xform, const gchar *key, const gchar **val);
233 gboolean xmms_xform_auxdata_get_bin (xmms_xform_t *xform, const gchar *key, const guchar **data, gsize *datalen);
234 
237 
238 /**
239  * Preview data from previous xform.
240  *
241  * Allows an xform to look at its input data without consuming it so
242  * that a subsequent call to #xmms_xform_read will get the same
243  * data. Up to siz bytes are read into the supplied buffer starting at
244  * buf. If siz is less than one xmms_xform_read just returns zero. On
245  * error -1 is returned and the error is stored in the supplied
246  * #xmms_error_t. On end of stream zero is returned.
247  *
248  * @param xform
249  * @param buf buffer to read data into
250  * @param siz size of buffer
251  * @param err error container which is filled in if error occours.
252  * @returns the number of bytes read or -1 to indicate error and 0 when end of stream.
253  */
254 gint xmms_xform_peek (xmms_xform_t *xform, gpointer buf, gint siz, xmms_error_t *err);
255 
256 /**
257  * Read one line from previous xform.
258  *
259  * Reads a line from the prev xform into buf.
260  *
261  * @param xform
262  * @param buf buffer to write the line to, should be at least XMMS_XFORM_MAX_LINE_SIZE
263  * @param err error container which is filled in if error occours.
264  * @returns the line read from the parent or NULL to indicate error.
265  */
266 gchar *xmms_xform_read_line (xmms_xform_t *xform, gchar *buf, xmms_error_t *err);
267 
268 /**
269  * Read data from previous xform.
270  *
271  * Reads up to siz bytes into the supplied buffer starting at buf. If
272  * siz is less than one xmms_xform_read just returns zero. On error -1
273  * is returned and the error is stored in the supplied
274  * #xmms_error_t. On end of stream zero is returned.
275  *
276  * @param xform
277  * @param buf buffer to read data into
278  * @param siz size of buffer
279  * @param err error container which is filled in if error occours.
280  * @returns the number of bytes read or -1 to indicate error and 0 when end of stream.
281  */
282 gint xmms_xform_read (xmms_xform_t *xform, gpointer buf, gint siz, xmms_error_t *err);
283 
284 /**
285  * Change offset in stream.
286  *
287  * Tries to change the offset from which data is read.
288  *
289  * @param xform
290  * @param offset offset to seek to, measured in "natural" units
291  * @param whence one of XMMS_XFORM_SEEK_{CUR,END,SET}
292  * @param err error container which is filled in if error occours.
293  * @returns new offset in stream, or -1 on error.
294  *
295  */
296 gint64 xmms_xform_seek (xmms_xform_t *xform, gint64 offset, xmms_xform_seek_mode_t whence, xmms_error_t *err);
297 gboolean xmms_xform_iseos (xmms_xform_t *xform);
298 
300 
301 gboolean xmms_magic_add (const gchar *desc, const gchar *mime, ...);
302 gboolean xmms_magic_extension_add (const gchar *mime, const gchar *ext);
303 
305  xmms_xform_plugin_t *xform_plugin,
306  const gchar *name,
307  const gchar *default_value,
309  gpointer userdata);
311  const gchar *path);
312 
313 /**
314  * Get the medialib entry played by this xform.
315  *
316  * @param xform
317  * @returns
318  */
320 const gchar *xmms_xform_get_url (xmms_xform_t *xform);
321 
322 #define XMMS_XFORM_BROWSE_FLAG_DIR (1 << 0)
323 
324 void xmms_xform_browse_add_entry (xmms_xform_t *xform, const gchar *path, guint32 flags);
325 void xmms_xform_browse_add_entry_property (xmms_xform_t *xform, const gchar *key, xmmsv_t *val);
327  const gchar *key,
328  const gchar *value);
330  const gchar *key,
331  gint value);
332 void xmms_xform_browse_add_symlink (xmms_xform_t *xform, const gchar *basename, const gchar *url);
333 void xmms_xform_browse_add_symlink_args (xmms_xform_t *xform, const gchar *basename, const gchar *url, gint nargs, char **args);
334 
335 #define XMMS_XFORM_MAX_LINE_SIZE 1024
336 
337 /**
338  * @}
339  */
340 G_END_DECLS
341 
342 #endif
enum xmms_stream_type_key_E xmms_stream_type_key_t
gboolean xmms_xform_metadata_has_val(xmms_xform_t *xform, const gchar *key)
Definition: xform.c:558
G_BEGIN_DECLS typedef gint32 xmms_medialib_entry_t
Definition: xmms_medialib.h:86
gboolean(* browse)(xmms_xform_t *, const gchar *, xmms_error_t *)
browse method.
struct xmms_xform_plugin_St xmms_xform_plugin_t
Xform plugin.
gboolean xmms_magic_add(const gchar *desc, const gchar *mime,...)
Definition: magic.c:524
gboolean xmms_xform_metadata_get_str(xmms_xform_t *xform, const gchar *key, const gchar **val)
gchar * xmms_xform_read_line(xmms_xform_t *xform, gchar *buf, xmms_error_t *err)
Read one line from previous xform.
Definition: xform.c:1068
void xmms_xform_browse_add_symlink(xmms_xform_t *xform, const gchar *basename, const gchar *url)
Definition: xform.c:156
struct xmms_stream_type_St xmms_stream_type_t
struct xmmsv_St xmmsv_t
Definition: xmmsv_general.h:48
void xmms_xform_plugin_indata_add(xmms_xform_plugin_t *plugin,...)
Add a valid input type to the plugin.
Definition: xform_plugin.c:79
void xmms_xform_browse_add_entry_property(xmms_xform_t *xform, const gchar *key, xmmsv_t *val)
Definition: xform.c:163
struct xmms_xform_methods_St xmms_xform_methods_t
Methods provided by an xform plugin.
struct xmms_xform_St xmms_xform_t
gboolean(* init)(xmms_xform_t *)
Initialisation method.
void xmms_xform_browse_add_entry_property_int(xmms_xform_t *xform, const gchar *key, gint value)
Definition: xform.c:117
void xmms_xform_auxdata_barrier(xmms_xform_t *xform)
Definition: xform.c:748
void xmms_xform_metadata_set_str(xmms_xform_t *xform, const gchar *key, const char *val)
Set string metadata for the media transformed by this xform.
gpointer xmms_xform_private_data_get(xmms_xform_t *xform)
Get private data for this xform.
Definition: xform.c:424
gboolean xmms_xform_auxdata_get_bin(xmms_xform_t *xform, const gchar *key, const guchar **data, gsize *datalen)
Definition: xform.c:850
const char * xmms_xform_indata_get_str(xmms_xform_t *xform, xmms_stream_type_key_t key)
Definition: xform.c:472
gboolean xmms_xform_metadata_get_int(xmms_xform_t *xform, const gchar *key, gint *val)
enum xmms_xform_seek_mode_E xmms_xform_seek_mode_t
Seek direction argument.
const xmms_stream_type_t * xmms_xform_get_out_stream_type(xmms_xform_t *xform)
Definition: xform.c:1217
Methods provided by an xform plugin.
void xmms_xform_auxdata_set_str(xmms_xform_t *xform, const gchar *key, const gchar *val)
Definition: xform.c:762
void xmms_xform_plugin_methods_set(xmms_xform_plugin_t *plugin, xmms_xform_methods_t *methods)
Should be called once from the plugin&#39;s setupfunc.
Definition: xform_plugin.c:53
const gchar * xmms_xform_get_url(xmms_xform_t *xform)
Definition: xform.c:1128
gint64 xmms_xform_seek(xmms_xform_t *xform, gint64 offset, xmms_xform_seek_mode_t whence, xmms_error_t *err)
Change offset in stream.
Definition: xform.c:1120
gboolean xmms_magic_extension_add(const gchar *mime, const gchar *ext)
Definition: magic.c:507
xmms_medialib_entry_t xmms_xform_entry_get(xmms_xform_t *xform)
Get the medialib entry played by this xform.
Definition: xform.c:418
xmms_config_property_t * xmms_xform_config_lookup(xmms_xform_t *xform, const gchar *path)
Definition: xform.c:1453
gboolean xmms_xform_auxdata_get_int(xmms_xform_t *xform, const gchar *key, gint32 *val)
Definition: xform.c:821
void(* destroy)(xmms_xform_t *)
Destruction method.
gboolean xmms_xform_auxdata_get_str(xmms_xform_t *xform, const gchar *key, const gchar **val)
Definition: xform.c:835
void xmms_xform_outdata_type_copy(xmms_xform_t *xform)
Definition: xform.c:452
xmms_config_property_t * xmms_xform_plugin_config_property_register(xmms_xform_plugin_t *xform_plugin, const gchar *name, const gchar *default_value, xmms_object_handler_t cb, gpointer userdata)
Definition: xform_plugin.c:141
gint xmms_xform_read(xmms_xform_t *xform, gpointer buf, gint siz, xmms_error_t *err)
Read data from previous xform.
Definition: xform.c:1113
void xmms_xform_metadata_set_int(xmms_xform_t *xform, const gchar *key, int val)
Set numeric metadata for the media transformed by this xform.
xmms_xform_seek_mode_E
Seek direction argument.
void xmms_xform_outdata_type_add(xmms_xform_t *xform,...)
Definition: xform.c:436
gint(* read)(xmms_xform_t *, gpointer, gint, xmms_error_t *)
Read method.
gint xmms_xform_peek(xmms_xform_t *xform, gpointer buf, gint siz, xmms_error_t *err)
Preview data from previous xform.
Definition: xform.c:1060
gint xmms_xform_indata_get_int(xmms_xform_t *xform, xmms_stream_type_key_t key)
Definition: xform.c:478
G_BEGIN_DECLS struct xmms_error_St xmms_error_t
void xmms_xform_auxdata_set_int(xmms_xform_t *xform, const gchar *key, gint32 val)
struct xmms_config_property_St xmms_config_property_t
Definition: xmms_config.h:26
void xmms_xform_auxdata_set_bin(xmms_xform_t *xform, const gchar *key, gpointer data, gssize len)
Definition: xform.c:779
void xmms_xform_browse_add_symlink_args(xmms_xform_t *xform, const gchar *basename, const gchar *url, gint nargs, char **args)
void xmms_xform_browse_add_entry(xmms_xform_t *xform, const gchar *path, guint32 flags)
Definition: xform.c:175
void xmms_xform_private_data_set(xmms_xform_t *xform, gpointer data)
Set private data for this xform.
Definition: xform.c:430
void xmms_xform_browse_add_entry_property_str(xmms_xform_t *xform, const gchar *key, const gchar *value)
Definition: xform.c:106
gint64(* seek)(xmms_xform_t *, gint64, xmms_xform_seek_mode_t, xmms_error_t *)
Seek method.
void(* xmms_object_handler_t)(xmms_object_t *object, xmmsv_t *data, gpointer userdata)
Definition: xmms_object.h:66
gboolean xmms_xform_auxdata_has_val(xmms_xform_t *xform, const gchar *key)
Definition: xform.c:815
gboolean xmms_xform_iseos(xmms_xform_t *xform)
Definition: xform.c:1205