XMMS2
Data Structures | Defines | Typedefs | Enumerations | Functions
XForm
XMMSServer

XForm API. More...

Data Structures

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

Defines

#define XMMS_XFORM_API_VERSION   7
#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)
 Declare an xform plugin.
#define XMMS_XFORM_METHODS_INIT(m)   memset (&m, 0, sizeof (xmms_xform_methods_t))
#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.
typedef struct xmms_xform_St xmms_xform_t
typedef enum xmms_xform_seek_mode_E xmms_xform_seek_mode_t
 Seek direction argument.
typedef struct
xmms_xform_methods_St 
xmms_xform_methods_t
 Methods provided by an xform plugin.

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.
void xmms_xform_plugin_indata_add (xmms_xform_plugin_t *plugin,...)
 Add a valid input type to the plugin.
gpointer xmms_xform_private_data_get (xmms_xform_t *xform)
 Get private data for this xform.
void xmms_xform_private_data_set (xmms_xform_t *xform, gpointer data)
 Set private data for this xform.
void xmms_xform_outdata_type_add (xmms_xform_t *xform,...)
void xmms_xform_outdata_type_copy (xmms_xform_t *xform)
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_metadata_set_str (xmms_xform_t *xform, const gchar *key, const char *val)
 Set string metadata for the media transformed by this xform.
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)
void xmms_xform_auxdata_barrier (xmms_xform_t *xform)
void xmms_xform_auxdata_set_int (xmms_xform_t *xform, const gchar *key, gint32 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_int (xmms_xform_t *xform, const gchar *key, gint32 *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.
gchar * xmms_xform_read_line (xmms_xform_t *xform, gchar *buf, xmms_error_t *err)
 Read one line from previous xform.
gint xmms_xform_read (xmms_xform_t *xform, gpointer buf, gint siz, xmms_error_t *err)
 Read data from previous xform.
gint64 xmms_xform_seek (xmms_xform_t *xform, gint64 offset, xmms_xform_seek_mode_t whence, xmms_error_t *err)
 Change offset in stream.
gboolean xmms_xform_iseos (xmms_xform_t *xform)
const xmms_stream_type_txmms_xform_get_out_stream_type (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_txmms_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_txmms_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.
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.


Define Documentation

#define XMMS_XFORM_API_VERSION   7

Definition at line 52 of file xmms_xformplugin.h.

#define XMMS_XFORM_BROWSE_FLAG_DIR   (1 << 0)

Definition at line 322 of file xmms_xformplugin.h.

Referenced by xmms_xform_browse_add_entry().

#define XMMS_XFORM_MAX_LINE_SIZE   1024

Definition at line 335 of file xmms_xformplugin.h.

Referenced by xmms_xform_read_line().

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

Definition at line 154 of file xmms_xformplugin.h.

#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)

Declare an xform plugin.

Use this macro _ONCE_ for each plugin.

Parameters:
shnameShort name of the plugin, should not contain any special characters, just a-z A-Z 0-9 and _.
nameFull name, display name for plugin.
verVersion of plugin, as string.
descDescription of plugin and its uses.
setupfuncFunction to be called when initializing plugin.

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

Definition at line 90 of file xmms_xformplugin.h.


Typedef Documentation

Methods provided by an xform plugin.

typedef struct xmms_xform_plugin_St xmms_xform_plugin_t

Xform plugin.

Definition at line 68 of file xmms_xformplugin.h.

Seek direction argument.

typedef struct xmms_xform_St xmms_xform_t

Definition at line 96 of file xmms_xformplugin.h.


Enumeration Type Documentation

Seek direction argument.

Enumerator:
XMMS_XFORM_SEEK_CUR 
XMMS_XFORM_SEEK_SET 
XMMS_XFORM_SEEK_END 

Definition at line 101 of file xmms_xformplugin.h.


Function Documentation

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

Definition at line 524 of file magic.c.

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

Definition at line 507 of file magic.c.

Definition at line 748 of file xform.c.

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

Definition at line 850 of file xform.c.

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

Definition at line 821 of file xform.c.

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

Definition at line 835 of file xform.c.

Referenced by xmms_xform_auxdata_set_str().

gboolean xmms_xform_auxdata_has_val ( xmms_xform_t xform,
const gchar *  key 
)

Definition at line 815 of file xform.c.

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

Definition at line 779 of file xform.c.

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

Definition at line 762 of file xform.c.

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

Definition at line 175 of file xform.c.

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 
)
void xmms_xform_browse_add_entry_property_int ( xmms_xform_t xform,
const gchar *  key,
gint  value 
)

Definition at line 117 of file xform.c.

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 
)

Definition at line 106 of file xform.c.

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 
)

Definition at line 156 of file xform.c.

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 
)

Definition at line 1453 of file xform.c.

Get the medialib entry played by this xform.

Parameters:
xform
Returns:

Definition at line 418 of file xform.c.

Definition at line 1217 of file xform.c.

const gchar* xmms_xform_get_url ( xmms_xform_t xform)

Definition at line 1128 of file xform.c.

Referenced by xmms_xform_browse_add_entry().

Definition at line 478 of file xform.c.

Definition at line 472 of file xform.c.

Referenced by xmms_xform_get_url().

gboolean xmms_xform_iseos ( xmms_xform_t xform)

Definition at line 1205 of file xform.c.

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 
)

Definition at line 558 of file xform.c.

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.

Parameters:
xform
keyMetadatum key to set. Should preferably be one of the XMMS_MEDIALIB_ENTRY_PROPERTY_* values.
val
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.

Parameters:
xform
keyMetadatum key to set. Should preferably be one of the XMMS_MEDIALIB_ENTRY_PROPERTY_* values.
val
void xmms_xform_outdata_type_add ( xmms_xform_t xform,
  ... 
)

Definition at line 436 of file xform.c.

Referenced by xmms_xform_browse().

Definition at line 452 of file xform.c.

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
bufbuffer to read data into
sizsize of buffer
errerror 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.

Definition at line 1060 of file xform.c.

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 at line 141 of file xform_plugin.c.

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:
pluginthe 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);

Definition at line 79 of file xform_plugin.c.

Should be called _once_ from the plugin's setupfunc.

Definition at line 53 of file xform_plugin.c.

Get private data for this xform.

Parameters:
xformcurrent xform
Returns:
the data set with xmms_xform_private_data_set

Definition at line 424 of file xform.c.

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:
xformcurrent xform
data

Definition at line 430 of file xform.c.

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
bufbuffer to read data into
sizsize of buffer
errerror 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.

Definition at line 1113 of file xform.c.

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
bufbuffer to write the line to, should be at least XMMS_XFORM_MAX_LINE_SIZE
errerror container which is filled in if error occours.
Returns:
the line read from the parent or NULL to indicate error.

Definition at line 1068 of file xform.c.

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
offsetoffset to seek to, measured in "natural" units
whenceone of XMMS_XFORM_SEEK_{CUR,END,SET}
errerror container which is filled in if error occours.
Returns:
new offset in stream, or -1 on error.

Definition at line 1120 of file xform.c.