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"
58#include "xmms/xmms_config.h"
59#include "xmms/xmms_medialib.h"
60
61
62G_BEGIN_DECLS
63
64struct xmms_xform_plugin_St;
65/**
66 * Xform plugin.
67 */
68typedef 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
94struct xmms_xform_St;
95/* xform */
96typedef struct xmms_xform_St xmms_xform_t;
97
98/**
99 * Seek direction argument.
100 */
106
107/**
108 * Methods provided by an xform plugin.
109 */
110typedef 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 */
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 */
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 */
198void xmms_xform_private_data_set (xmms_xform_t *xform, gpointer data);
199
200
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 */
211void 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 */
219void xmms_xform_metadata_set_str (xmms_xform_t *xform, const gchar *key, const char *val);
220
221gboolean xmms_xform_metadata_has_val (xmms_xform_t *xform, const gchar *key);
222gboolean xmms_xform_metadata_get_int (xmms_xform_t *xform, const gchar *key,
223 gint *val);
224gboolean xmms_xform_metadata_get_str (xmms_xform_t *xform, const gchar *key,
225 const gchar **val);
227void xmms_xform_auxdata_set_int (xmms_xform_t *xform, const gchar *key, gint32 val);
228void xmms_xform_auxdata_set_str (xmms_xform_t *xform, const gchar *key, const gchar *val);
229void xmms_xform_auxdata_set_bin (xmms_xform_t *xform, const gchar *key, gpointer data, gssize len);
230gboolean xmms_xform_auxdata_has_val (xmms_xform_t *xform, const gchar *key);
231gboolean xmms_xform_auxdata_get_int (xmms_xform_t *xform, const gchar *key, gint32 *val);
232gboolean xmms_xform_auxdata_get_str (xmms_xform_t *xform, const gchar *key, const gchar **val);
233gboolean 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 */
254gint 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 */
266gchar *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 */
282gint 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 */
296gint64 xmms_xform_seek (xmms_xform_t *xform, gint64 offset, xmms_xform_seek_mode_t whence, xmms_error_t *err);
297gboolean xmms_xform_iseos (xmms_xform_t *xform);
298
300
301gboolean xmms_magic_add (const gchar *desc, const gchar *mime, ...);
302gboolean 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 */
320const gchar *xmms_xform_get_url (xmms_xform_t *xform);
321
322#define XMMS_XFORM_BROWSE_FLAG_DIR (1 << 0)
323
324void xmms_xform_browse_add_entry (xmms_xform_t *xform, const gchar *path, guint32 flags);
325void 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);
332void xmms_xform_browse_add_symlink (xmms_xform_t *xform, const gchar *basename, const gchar *url);
333void 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 */
340G_END_DECLS
341
342#endif
struct xmmsv_St xmmsv_t
void xmms_xform_private_data_set(xmms_xform_t *xform, gpointer data)
Set private data for this xform.
Definition xform.c:430
struct xmms_xform_plugin_St xmms_xform_plugin_t
Xform plugin.
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
gpointer xmms_xform_private_data_get(xmms_xform_t *xform)
Get private data for this xform.
Definition xform.c:424
xmms_xform_seek_mode_E
Seek direction argument.
gboolean xmms_xform_metadata_has_val(xmms_xform_t *xform, const gchar *key)
Definition xform.c:558
struct xmms_xform_St xmms_xform_t
void xmms_xform_browse_add_symlink(xmms_xform_t *xform, const gchar *basename, const gchar *url)
Definition xform.c:156
void xmms_xform_browse_add_entry_property_int(xmms_xform_t *xform, const gchar *key, gint value)
Definition xform.c:117
gboolean xmms_xform_auxdata_get_bin(xmms_xform_t *xform, const gchar *key, const guchar **data, gsize *datalen)
Definition xform.c:850
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)
xmms_config_property_t * xmms_xform_config_lookup(xmms_xform_t *xform, const gchar *path)
Definition xform.c:1453
gboolean xmms_xform_metadata_get_str(xmms_xform_t *xform, const gchar *key, const gchar **val)
void xmms_xform_plugin_indata_add(xmms_xform_plugin_t *plugin,...)
Add a valid input type to the plugin.
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.
void xmms_xform_outdata_type_add(xmms_xform_t *xform,...)
Definition xform.c:436
xmms_medialib_entry_t xmms_xform_entry_get(xmms_xform_t *xform)
Get the medialib entry played by this xform.
Definition xform.c:418
void xmms_xform_browse_add_entry_property(xmms_xform_t *xform, const gchar *key, xmmsv_t *val)
Definition xform.c:163
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
void xmms_xform_browse_add_entry(xmms_xform_t *xform, const gchar *path, guint32 flags)
Definition xform.c:175
void xmms_xform_auxdata_set_str(xmms_xform_t *xform, const gchar *key, const gchar *val)
Definition xform.c:762
void xmms_xform_auxdata_set_int(xmms_xform_t *xform, const gchar *key, gint32 val)
void xmms_xform_auxdata_barrier(xmms_xform_t *xform)
Definition xform.c:748
void xmms_xform_browse_add_symlink_args(xmms_xform_t *xform, const gchar *basename, const gchar *url, gint nargs, char **args)
gboolean xmms_magic_extension_add(const gchar *mime, const gchar *ext)
Definition magic.c:507
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_plugin_methods_set(xmms_xform_plugin_t *plugin, xmms_xform_methods_t *methods)
Should be called once from the plugin's setupfunc.
const gchar * xmms_xform_get_url(xmms_xform_t *xform)
Definition xform.c:1128
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
gboolean xmms_xform_auxdata_has_val(xmms_xform_t *xform, const gchar *key)
Definition xform.c:815
enum xmms_xform_seek_mode_E xmms_xform_seek_mode_t
Seek direction argument.
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.
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
gboolean xmms_xform_auxdata_get_int(xmms_xform_t *xform, const gchar *key, gint32 *val)
Definition xform.c:821
struct xmms_xform_methods_St xmms_xform_methods_t
Methods provided by an xform plugin.
const xmms_stream_type_t * xmms_xform_get_out_stream_type(xmms_xform_t *xform)
Definition xform.c:1217
void xmms_xform_auxdata_set_bin(xmms_xform_t *xform, const gchar *key, gpointer data, gssize len)
Definition xform.c:779
gboolean xmms_xform_iseos(xmms_xform_t *xform)
Definition xform.c:1205
gboolean xmms_xform_metadata_get_int(xmms_xform_t *xform, const gchar *key, gint *val)
const char * xmms_xform_indata_get_str(xmms_xform_t *xform, xmms_stream_type_key_t key)
Definition xform.c:472
gboolean xmms_magic_add(const gchar *desc, const gchar *mime,...)
Definition magic.c:524
void xmms_xform_browse_add_entry_property_str(xmms_xform_t *xform, const gchar *key, const gchar *value)
Definition xform.c:106
@ XMMS_XFORM_SEEK_SET
@ XMMS_XFORM_SEEK_CUR
@ XMMS_XFORM_SEEK_END
Methods provided by an xform plugin.
gboolean(* init)(xmms_xform_t *)
Initialisation method.
gint64(* seek)(xmms_xform_t *, gint64, xmms_xform_seek_mode_t, xmms_error_t *)
Seek method.
gboolean(* browse)(xmms_xform_t *, const gchar *, xmms_error_t *)
browse method.
void(* destroy)(xmms_xform_t *)
Destruction method.
gint(* read)(xmms_xform_t *, gpointer, gint, xmms_error_t *)
Read method.
struct xmms_config_property_St xmms_config_property_t
Definition xmms_config.h:26
G_BEGIN_DECLS typedef gint32 xmms_medialib_entry_t
enum xmms_stream_type_key_E xmms_stream_type_key_t
struct xmms_stream_type_St xmms_stream_type_t
G_BEGIN_DECLS struct xmms_error_St xmms_error_t
void(* xmms_object_handler_t)(xmms_object_t *object, xmmsv_t *data, gpointer userdata)
Definition xmms_object.h:66