XForm API. More...

Data Structures
struct	xmms_xform_metadata_basic_mapping_St
	Mapping between format specific and internal metadata naming. More...

struct	xmms_xform_metadata_mapping_St

struct	xmms_xform_methods_St
	Methods provided by an xform plugin. More...

Macros
#define	XMMS_XFORM_API_VERSION 7

#define	XMMS_XFORM_PLUGIN_DEFINE(shname, name, ver, desc, setupfunc) XMMS_PLUGIN_DEFINE(XMMS_PLUGIN_TYPE_XFORM, XMMS_XFORM_API_VERSION, shname, name, ver, desc, (gboolean (*)(gpointer))setupfunc)
	Declare an xform plugin. More...

#define	XMMS_XFORM_METHODS_INIT(m) memset (&m, 0, sizeof (xmms_xform_methods_t))

#define	xmms_xform_auxdata_get_int xmms_xform_auxdata_get_int32

#define	XMMS_XFORM_BROWSE_FLAG_DIR (1 << 0)

#define	XMMS_XFORM_MAX_LINE_SIZE 1024

Typedefs
typedef struct xmms_xform_plugin_St	xmms_xform_plugin_t
	Xform plugin. More...

typedef struct xmms_xform_St	xmms_xform_t

typedef struct xmms_xform_metadata_basic_mapping_St	xmms_xform_metadata_basic_mapping_t
	Mapping between format specific and internal metadata naming. More...

typedef gboolean(*	xmms_xform_metadata_mapper_func_t )(xmms_xform_t xform, const gchar key, const gchar *value, gsize length)
	Mapping function that recieves a metadata key and value pair. More...

typedef struct xmms_xform_metadata_mapping_St	xmms_xform_metadata_mapping_t

typedef enum xmms_xform_seek_mode_E	xmms_xform_seek_mode_t
	Seek direction argument. More...

typedef struct xmms_xform_methods_St	xmms_xform_methods_t
	Methods provided by an xform plugin. More...

Enumerations
enum	xmms_xform_seek_mode_E { XMMS_XFORM_SEEK_CUR = 1, XMMS_XFORM_SEEK_SET = 2, XMMS_XFORM_SEEK_END = 3 }
	Seek direction argument. More...

Functions
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. More...

void	xmms_xform_plugin_metadata_basic_mapper_init (xmms_xform_plugin_t xform_plugin, const xmms_xform_metadata_basic_mapping_t mappings, gint count)
	Configure automatic metadata mapping. More...

void	xmms_xform_plugin_metadata_mapper_init (xmms_xform_plugin_t xform_plugin, const xmms_xform_metadata_basic_mapping_t basic_mappings, gint basic_count, const xmms_xform_metadata_mapping_t *mappings, gint count)
	Configure automatic metadata mapping. More...

void	xmms_xform_plugin_indata_add (xmms_xform_plugin_t *plugin,...)
	Add a valid input type to the plugin. More...

void	xmms_xform_plugin_set_out_stream_type (xmms_xform_plugin_t *plugin,...)
	Set a static output type to the plugin. More...

gpointer	xmms_xform_private_data_get (xmms_xform_t *xform)
	Get private data for this xform. More...

void	xmms_xform_private_data_set (xmms_xform_t *xform, gpointer data)
	Set private data for this xform. More...

void	xmms_xform_outdata_type_add (xmms_xform_t *xform,...)

void	xmms_xform_outdata_type_copy (xmms_xform_t *xform)

gboolean	xmms_xform_metadata_set_int (xmms_xform_t xform, const gchar key, int val)
	Set numeric metadata for the media transformed by this xform. More...

gboolean	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. More...

gboolean	xmms_xform_metadata_has_val (xmms_xform_t xform, const gchar key)

gboolean	xmms_xform_metadata_get_int (xmms_xform_t xform, const gchar key, gint *val)

gboolean	xmms_xform_metadata_get_str (xmms_xform_t xform, const gchar key, const gchar **val)

gboolean	xmms_xform_metadata_parse_number (xmms_xform_t xform, const gchar key, const gchar *value, gsize length)
	Set numeric metadata for the media by parsing a string value. More...

gboolean	xmms_xform_metadata_parse_compilation (xmms_xform_t xform, const gchar key, const gchar *value, gsize length)
	Set compliation status by performing a number of probes on a value. More...

gboolean	xmms_xform_metadata_parse_replay_gain (xmms_xform_t xform, const gchar key, const gchar *value, gsize length)
	Set string metadata represesting replay gain for the media by parsing a string value. More...

gboolean	xmms_xform_metadata_mapper_match (xmms_xform_t xform, const gchar key, const gchar *value, gsize length)
	Attempt to automatically set a metadata property. More...

void	xmms_xform_auxdata_barrier (xmms_xform_t *xform)

void	xmms_xform_auxdata_set_int (xmms_xform_t xform, const gchar key, gint64 val)

void	xmms_xform_auxdata_set_str (xmms_xform_t xform, const gchar key, const gchar *val)

void	xmms_xform_auxdata_set_bin (xmms_xform_t xform, const gchar key, gpointer data, gssize len)

gboolean	xmms_xform_auxdata_has_val (xmms_xform_t xform, const gchar key)

gboolean	xmms_xform_auxdata_get_int32 (xmms_xform_t xform, const gchar key, gint32 *val)

gboolean	xmms_xform_auxdata_get_int64 (xmms_xform_t xform, const gchar key, gint64 *val)

gboolean	xmms_xform_auxdata_get_str (xmms_xform_t xform, const gchar key, const gchar **val)

gboolean	xmms_xform_auxdata_get_bin (xmms_xform_t xform, const gchar key, const guchar *data, gsize datalen)

const char *	xmms_xform_indata_get_str (xmms_xform_t *xform, xmms_stream_type_key_t key)

gint	xmms_xform_indata_get_int (xmms_xform_t *xform, xmms_stream_type_key_t key)

gint	xmms_xform_peek (xmms_xform_t xform, gpointer buf, gint siz, xmms_error_t err)
	Preview data from previous xform. More...

gchar *	xmms_xform_read_line (xmms_xform_t xform, gchar buf, xmms_error_t *err)
	Read one line from previous xform. More...

gint	xmms_xform_read (xmms_xform_t xform, gpointer buf, gint siz, xmms_error_t err)
	Read data from previous xform. More...

gint64	xmms_xform_seek (xmms_xform_t xform, gint64 offset, xmms_xform_seek_mode_t whence, xmms_error_t err)
	Change offset in stream. More...

gboolean	xmms_xform_iseos (xmms_xform_t *xform)

gboolean	xmms_magic_add (const gchar desc, const gchar mime,...)

gboolean	xmms_magic_extension_add (const gchar mime, const gchar ext)

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_plugin_config_lookup (xmms_xform_plugin_t xform_plugin, const gchar path)

xmms_config_property_t *	xmms_xform_config_lookup (xmms_xform_t xform, const gchar path)

xmms_medialib_entry_t	xmms_xform_entry_get (xmms_xform_t *xform)
	Get the medialib entry played by this xform. More...

const gchar *	xmms_xform_get_url (xmms_xform_t *xform)

void	xmms_xform_browse_add_entry (xmms_xform_t xform, const gchar path, guint32 flags)

void	xmms_xform_browse_add_entry_property (xmms_xform_t xform, const gchar key, xmmsv_t *val)

void	xmms_xform_browse_add_entry_property_str (xmms_xform_t xform, const gchar key, const gchar *value)

void	xmms_xform_browse_add_entry_property_int (xmms_xform_t xform, const gchar key, gint value)

void	xmms_xform_browse_add_symlink (xmms_xform_t xform, const gchar basename, const gchar *url)

void	xmms_xform_browse_add_symlink_args (xmms_xform_t xform, const gchar basename, const gchar url, gint nargs, char *args)

Detailed Description

XForm API.

An xform (transform) is something that reads data and applies some kind of transformation to it such as decoding or demuxing or applying an effect.

The xform api is designed to allow xforms to be connected in a chain where each xform does a different transformation step. Each xform provides a "read" method, which should return transformed data and when it needs more input data, it should call the read method of the previous xform in the chain.

The type of the data flowing from one xform to another is described by an xmms_stream_type_t. So an xform registers which xmms_stream_type_t it wants as input and when initialised it tells what type the output data is. This allows the chain of xforms to easily be built.

Macro Definition Documentation

#define XMMS_XFORM_API_VERSION 7

Referenced by xmms_plugin_load().

#define xmms_xform_auxdata_get_int xmms_xform_auxdata_get_int32

#define XMMS_XFORM_BROWSE_FLAG_DIR (1 << 0)

Referenced by xmms_xform_browse_add_entry().

#define XMMS_XFORM_MAX_LINE_SIZE 1024

Referenced by xmms_xform_read_line().

#define XMMS_XFORM_METHODS_INIT ( m ) memset (&m, 0, sizeof (xmms_xform_methods_t))

#define XMMS_XFORM_PLUGIN_DEFINE	(	shname,
		name,
		ver,
		desc,
		setupfunc
	)	XMMS_PLUGIN_DEFINE(XMMS_PLUGIN_TYPE_XFORM, XMMS_XFORM_API_VERSION, shname, name, ver, desc, (gboolean (*)(gpointer))setupfunc)

Declare an xform plugin.

Use this macro ONCE for each plugin.

Parameters

shname	Short name of the plugin, should not contain any special characters, just a-z A-Z 0-9 and _.
name	Full name, display name for plugin.
ver	Version of plugin, as string.
desc	Description of plugin and its uses.
setupfunc	Function to be called when initializing plugin.

example: XMMS_XFORM_PLUGIN_DEFINE("example", "Example decoder", "1.3.37-beta", "Decoder for playing example files", xmms_example_setup);

Typedef Documentation

typedef struct xmms_xform_metadata_basic_mapping_St xmms_xform_metadata_basic_mapping_t

Mapping between format specific and internal metadata naming.

typedef gboolean(* xmms_xform_metadata_mapper_func_t)(xmms_xform_t *xform, const gchar *key, const gchar *value, gsize length)

Mapping function that recieves a metadata key and value pair.

typedef struct xmms_xform_metadata_mapping_St xmms_xform_metadata_mapping_t

typedef struct xmms_xform_methods_St xmms_xform_methods_t

Methods provided by an xform plugin.

typedef struct xmms_xform_plugin_St xmms_xform_plugin_t

Xform plugin.

typedef enum xmms_xform_seek_mode_E xmms_xform_seek_mode_t

Seek direction argument.

typedef struct xmms_xform_St xmms_xform_t

Enumeration Type Documentation

enum xmms_xform_seek_mode_E

Seek direction argument.

Enumerator
XMMS_XFORM_SEEK_CUR
XMMS_XFORM_SEEK_SET
XMMS_XFORM_SEEK_END

Function Documentation

gboolean xmms_magic_add	(	const gchar *	desc,
		const gchar *	mime,
			...
	)

gboolean xmms_magic_extension_add	(	const gchar *	mime,
		const gchar *	ext
	)

void xmms_xform_auxdata_barrier ( xmms_xform_t * xform )

gboolean xmms_xform_auxdata_get_bin	(	xmms_xform_t *	xform,
		const gchar *	key,
		const guchar **	data,
		gsize *	datalen
	)

gboolean xmms_xform_auxdata_get_int32	(	xmms_xform_t *	xform,
		const gchar *	key,
		gint32 *	val
	)

gboolean xmms_xform_auxdata_get_int64	(	xmms_xform_t *	xform,
		const gchar *	key,
		gint64 *	val
	)

gboolean xmms_xform_auxdata_get_str	(	xmms_xform_t *	xform,
		const gchar *	key,
		const gchar **	val
	)

Referenced by xmms_xform_auxdata_set_str().

gboolean xmms_xform_auxdata_has_val	(	xmms_xform_t *	xform,
		const gchar *	key
	)

void xmms_xform_auxdata_set_bin	(	xmms_xform_t *	xform,
		const gchar *	key,
		gpointer	data,
		gssize	len
	)

void xmms_xform_auxdata_set_int	(	xmms_xform_t *	xform,
		const gchar *	key,
		gint64	val
	)

void xmms_xform_auxdata_set_str	(	xmms_xform_t *	xform,
		const gchar *	key,
		const gchar *	val
	)

void xmms_xform_browse_add_entry	(	xmms_xform_t *	xform,
		const gchar *	path,
		guint32	flags
	)

Referenced by xmms_xform_browse_add_symlink_args().

void xmms_xform_browse_add_entry_property	(	xmms_xform_t *	xform,
		const gchar *	key,
		xmmsv_t *	val
	)

Referenced by xmms_xform_browse_add_entry_property_int(), and xmms_xform_browse_add_entry_property_str().

void xmms_xform_browse_add_entry_property_int	(	xmms_xform_t *	xform,
		const gchar *	key,
		gint	value
	)

Referenced by xmms_xform_browse_add_entry().

void xmms_xform_browse_add_entry_property_str	(	xmms_xform_t *	xform,
		const gchar *	key,
		const gchar *	value
	)

Referenced by xmms_xform_browse_add_entry(), and xmms_xform_browse_add_symlink_args().

void xmms_xform_browse_add_symlink	(	xmms_xform_t *	xform,
		const gchar *	basename,
		const gchar *	url
	)

void xmms_xform_browse_add_symlink_args	(	xmms_xform_t *	xform,
		const gchar *	basename,
		const gchar *	url,
		gint	nargs,
		char **	args
	)

xmms_config_property_t* xmms_xform_config_lookup	(	xmms_xform_t *	xform,
		const gchar *	path
	)

xmms_medialib_entry_t xmms_xform_entry_get ( xmms_xform_t * xform )

Get the medialib entry played by this xform.

Parameters

xform

Returns

const gchar* xmms_xform_get_url ( xmms_xform_t * xform )

Referenced by xmms_xform_browse_add_entry().

gint xmms_xform_indata_get_int	(	xmms_xform_t *	xform,
		xmms_stream_type_key_t	key
	)

const char* xmms_xform_indata_get_str	(	xmms_xform_t *	xform,
		xmms_stream_type_key_t	key
	)

Referenced by xmms_xform_get_url(), and xmms_xform_indata_find_str().

gboolean xmms_xform_iseos ( xmms_xform_t * xform )

gboolean xmms_xform_metadata_get_int	(	xmms_xform_t *	xform,
		const gchar *	key,
		gint *	val
	)

gboolean xmms_xform_metadata_get_str	(	xmms_xform_t *	xform,
		const gchar *	key,
		const gchar **	val
	)

gboolean xmms_xform_metadata_has_val	(	xmms_xform_t *	xform,
		const gchar *	key
	)

gboolean xmms_xform_metadata_mapper_match	(	xmms_xform_t *	xform,
		const gchar *	key,
		const gchar *	value,
		gsize	length
	)

Attempt to automatically set a metadata property.

Parameters

xform	current xform
key	the name of a key found by the xform
value	the corresponding value found by the xform
length	the length of the value, optional for NULL terminated values

Returns: TRUE if the configured metadata mapper marshalled the key/value into a property

gboolean xmms_xform_metadata_parse_compilation	(	xmms_xform_t *	xform,
		const gchar *	key,
		const gchar *	value,
		gsize	length
	)

Set compliation status by performing a number of probes on a value.

First check if the value is an integer (0 or 1), next check if the string matches the MusicBrainz Artist ID for various artists, and then finally see if the string equals 'Various Artists' which is usually the albumartist in the case of compilations.

Parameters

xform	current xform
key	Metadatum key to set. Should preferably be XMMS_MEDIALIB_ENTRY_PROPERTY_COMPILATION.
val	The value to interpret as compliation or not.

Returns: TRUE if the key now maps to the suggested value, otherwise FALSE.

gboolean xmms_xform_metadata_parse_number	(	xmms_xform_t *	xform,
		const gchar *	key,
		const gchar *	value,
		gsize	length
	)

Set numeric metadata for the media by parsing a string value.

Parameters

xform	current xform
key	Metadatum key to set. Should preferably be one of the XMMS_MEDIALIB_ENTRY_PROPERTY_* values.
val	The value to parse to an integer.

Returns: TRUE if the key now maps to the suggested value, otherwise FALSE.

gboolean xmms_xform_metadata_parse_replay_gain	(	xmms_xform_t *	xform,
		const gchar *	key,
		const gchar *	value,
		gsize	length
	)

Set string metadata represesting replay gain for the media by parsing a string value.

Parameters

xform	current xform
key	Metadatum key to set. Should preferably be one of the XMMS_MEDIALIB_ENTRY_PROPERTY_* values.
val	The value to interpret as replay gain.

Returns: TRUE if the key now maps to the suggested value, otherwise FALSE.

gboolean xmms_xform_metadata_set_int	(	xmms_xform_t *	xform,
		const gchar *	key,
		int	val
	)

Set numeric metadata for the media transformed by this xform.

Parameters

xform
key	Metadatum key to set. Should preferably be one of the XMMS_MEDIALIB_ENTRY_PROPERTY_* values.
val

Returns: TRUE if the key now maps to the suggested value, otherwise FALSE.

gboolean 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.

Parameters

xform
key	Metadatum key to set. Should preferably be one of the XMMS_MEDIALIB_ENTRY_PROPERTY_* values.
val

Returns: TRUE if the key now maps to the suggested value, otherwise FALSE.

void xmms_xform_outdata_type_add	(	xmms_xform_t *	xform,
			...
	)

Referenced by xmms_xform_browse().

void xmms_xform_outdata_type_copy ( xmms_xform_t * xform )

gint xmms_xform_peek	(	xmms_xform_t *	xform,
		gpointer	buf,
		gint	siz,
		xmms_error_t *	err
	)

Preview data from previous xform.

Allows an xform to look at its input data without consuming it so that a subsequent call to xmms_xform_read will get the same data. Up to siz bytes are read into the supplied buffer starting at buf. If siz is less than one xmms_xform_read just returns zero. On error -1 is returned and the error is stored in the supplied xmms_error_t. On end of stream zero is returned.

Parameters

xform
buf	buffer to read data into
siz	size of buffer
err	error container which is filled in if error occours.

Returns: the number of bytes read or -1 to indicate error and 0 when end of stream.

xmms_config_property_t* xmms_xform_plugin_config_lookup	(	xmms_xform_plugin_t *	xform_plugin,
		const gchar *	path
	)

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
	)

Referenced by xmms_xform_plugin_indata_add().

void xmms_xform_plugin_indata_add	(	xmms_xform_plugin_t *	plugin,
			...
	)

Add a valid input type to the plugin.

The varargs should contain key-value pairs terminated with XMMS_STREAM_TYPE_END.

Should be called from the plugin's setupfunc.

Parameters

plugin	the plugin
...	variable length arguments, terminated with XMMS_STREAM_TYPE_END

example: xmms_xform_plugin_indata_add (plugin, XMMS_STREAM_TYPE_MIMETYPE, "application/example", XMMS_STREAM_TYPE_END);

void xmms_xform_plugin_metadata_basic_mapper_init	(	xmms_xform_plugin_t *	xform_plugin,
		const xmms_xform_metadata_basic_mapping_t *	mappings,
		gint	count
	)

Configure automatic metadata mapping.

Parameters

xform_plugin	the plugin
mappings	mapping from format specific naming to internal naming.
count	the number of properties

void xmms_xform_plugin_metadata_mapper_init	(	xmms_xform_plugin_t *	xform_plugin,
		const xmms_xform_metadata_basic_mapping_t *	basic_mappings,
		gint	basic_count,
		const xmms_xform_metadata_mapping_t *	mappings,
		gint	count
	)

Configure automatic metadata mapping.

Parameters

xform_plugin	the plugin
basic_mappings	mapping from format specific naming to internal naming.
basic_count	the number of properties
mappings	custom mapping from format specific naming to a function that will marshall the property.
count	the number of custom properties

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.

void xmms_xform_plugin_set_out_stream_type	(	xmms_xform_plugin_t *	plugin,
			...
	)

Set a static output type to the plugin.

The output stream type is used as a default if the plugin doesn't override this at runtime.

Should be called from the plugin's setupfunc.

Parameters

plugin	the plugin
...	variable length arguments, terminated with XMMS_STREAM_TYPE_END

example: xmms_xform_plugin_set_out_stream_type (plugin, XMMS_STREAM_TYPE_MIMETYPE, "application/x-xmms2-playlist-entries", XMMS_STREAM_TYPE_END);

gpointer xmms_xform_private_data_get ( xmms_xform_t * xform )

Get private data for this xform.

Parameters

xform current xform

Returns: the data set with xmms_xform_private_data_set

void xmms_xform_private_data_set	(	xmms_xform_t *	xform,
		gpointer	data
	)

Set private data for this xform.

Allows keeping information across calls to methods of the xform. Usually set from init method and accessed with xmms_xform_private_data_get in read, seek and destroy methods.

Parameters

xform	current xform
data

gint xmms_xform_read	(	xmms_xform_t *	xform,
		gpointer	buf,
		gint	siz,
		xmms_error_t *	err
	)

Read data from previous xform.

Reads up to siz bytes into the supplied buffer starting at buf. If siz is less than one xmms_xform_read just returns zero. On error -1 is returned and the error is stored in the supplied xmms_error_t. On end of stream zero is returned.

Parameters

xform
buf	buffer to read data into
siz	size of buffer
err	error container which is filled in if error occours.

Returns: the number of bytes read or -1 to indicate error and 0 when end of stream.

Referenced by xmms_xform_read_line().

gchar* xmms_xform_read_line	(	xmms_xform_t *	xform,
		gchar *	buf,
		xmms_error_t *	err
	)

Read one line from previous xform.

Reads a line from the prev xform into buf.

Parameters

xform
buf	buffer to write the line to, should be at least XMMS_XFORM_MAX_LINE_SIZE
err	error container which is filled in if error occours.

Returns: the line read from the parent or NULL to indicate error.

gint64 xmms_xform_seek	(	xmms_xform_t *	xform,
		gint64	offset,
		xmms_xform_seek_mode_t	whence,
		xmms_error_t *	err
	)

Change offset in stream.

Tries to change the offset from which data is read.

Parameters

xform
offset	offset to seek to, measured in "natural" units
whence	one of XMMS_XFORM_SEEK_{CUR,END,SET}
err	error container which is filled in if error occours.

Returns: new offset in stream, or -1 on error.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation