Filter API - manage mediastreamer2 filters.

Filter API to manage mediastreamer2 filters. More...

Typedefs
typedef void(*	MSFilterFunc) (struct _MSFilter *f)
typedef int(*	MSFilterMethodFunc) (struct _MSFilter *f, void *arg)
typedef void(*	MSFilterNotifyFunc) (void *userdata, unsigned int id, void *arg)
typedef struct _MSFilterMethod	MSFilterMethod
typedef enum _MSFilterCategory	MSFilterCategory
typedef struct _MSFilterDesc	MSFilterDesc
typedef struct _MSFilterStats	MSFilterStats
typedef struct _MSFilter	MSFilter
typedef struct _MSConnectionPoint	MSConnectionPoint
typedef struct _MSConnectionHelper	MSConnectionHelper

Functions
void	ms_filter_register (MSFilterDesc *desc)
int	ms_filter_enable (char *filter_name, int enable)
MSFilterDesc *	ms_filter_get_encoder (const char *mime)
MSFilterDesc *	ms_filter_get_decoder (const char *mime)
MSFilter *	ms_filter_create_encoder (const char *mime)
MSFilter *	ms_filter_create_decoder (const char *mime)
bool_t	ms_filter_codec_supported (const char *mime)
MSFilter *	ms_filter_new (MSFilterId id)
MSFilter *	ms_filter_new_from_name (const char *name)
MSFilter *	ms_filter_new_from_desc (MSFilterDesc *desc)
int	ms_filter_link (MSFilter *f1, int pin1, MSFilter *f2, int pin2)
int	ms_filter_unlink (MSFilter *f1, int pin1, MSFilter *f2, int pin2)
int	ms_filter_call_method (MSFilter *f, unsigned int id, void *arg)
int	ms_filter_call_method_noarg (MSFilter *f, unsigned int id)
void	ms_filter_set_notify_callback (MSFilter *f, MSFilterNotifyFunc fn, void *userdata)
void	ms_filter_enable_synchronous_notifcations (MSFilter *f, bool_t yesno)
MSFilterId	ms_filter_get_id (MSFilter *f)
MSList *	ms_filter_find_neighbours (MSFilter *me)
void	ms_filter_destroy (MSFilter *f)
void	ms_connection_helper_start (MSConnectionHelper *h)
int	ms_connection_helper_link (MSConnectionHelper *h, MSFilter *f, int inpin, int outpin)
	Enter a MSFilter to be connected into the MSConnectionHelper object. More...
int	ms_connection_helper_unlink (MSConnectionHelper *h, MSFilter *f, int inpin, int outpin)
	Enter a MSFilter to be disconnected into the MSConnectionHelper object. Process exactly the same way as ms_connection_helper_link() but calls ms_filter_unlink() on the entered filters.

Detailed Description

Filter API to manage mediastreamer2 filters.

This file provide the API needed to create, link, unlink, find and destroy filter.

It also provides definitions if you wish to implement your own filters.

Typedef Documentation

MSFilterFunc

MSFilterFunc

Structure for filter's methods (init, preprocess, process, postprocess, uninit).

MSFilterMethodFunc

MSFilterMethodFunc

Structure for filter's methods used to set filter's options.

MSFilterNotifyFunc

MSFilterNotifyFunc

Structure for filter's methods used as a callback to notify events.

MSFilterMethod

MSFilterMethod

Structure for holding filter's methods to set filter's options.

MSFilterCategory

MSFilterCategory

Structure to describe filter's category.

    MS_FILTER_OTHER
    MS_FILTER_ENCODER
    MS_FILTER_DECODER

MSFilterDesc

MSFilterDesc

Structure for filter's description.

MSFilterStats

MSFilterStats

Structure for filter's fps.

MSFilter

MSFilter

Structure to create/link/unlink/destroy filter's object.

MSConnectionPoint

MSConnectionPoint

Structure that represents a connection point of a MSFilter

MSConnectionHelper

MSConnectionHelper

Structure that holds data when using the ms_connection_helper_* functions.

Function Documentation

ms_filter_register()

void ms_filter_register

(

MSFilterDesc *

desc

)

Register a filter description. (plugins use only!)

When you build your own plugin, this method will add the encoder or decoder to the internal list of supported codec. Then, this plugin can be used transparently from the application.

ms_filter_get_encoder, ms_filter_get_decoder, ms_filter_create_encoder, ms_filter_create_decoder and ms_filter_codec_supported can then be used as if the codec was internally. supported.

Parameters

desc	a filter description.

ms_filter_enable()

int ms_filter_enable	(	char *	filter_name,
		int	enable
	)

Enable or Disable a registered filter.

Parameters

filter_name	a filter name.
enable	<=0 to disable, >0 to enable

Returns: 0 if successful, -1 otherwise.

ms_filter_get_encoder()

MSFilterDesc* ms_filter_get_encoder

(

const char *

mime

)

Retrieve encoders according to codec name.

Internal supported codecs: PCMU, PCMA, speex, gsm Existing Public plugins: iLBC

Parameters

mime	A string indicating the codec.

Returns: a MSFilterDesc if successful, NULL otherwise.

ms_filter_get_decoder()

MSFilterDesc* ms_filter_get_decoder

(

const char *

mime

)

Retrieve decoders according to codec name.

Internal supported codecs: PCMU, PCMA, speex, gsm Existing Public plugins: iLBC

Parameters

mime	A string indicating the codec.

Returns: a MSFilterDesc if successful, NULL otherwise.

ms_filter_create_encoder()

MSFilter* ms_filter_create_encoder

(

const char *

mime

)

Create encoder filter according to codec name.

Internal supported codecs: PCMU, PCMA, speex, gsm Existing Public plugins: iLBC

Parameters

mime	A string indicating the codec.

Returns: a MSFilter if successful, NULL otherwise.

ms_filter_create_decoder()

MSFilter* ms_filter_create_decoder

(

const char *

mime

)

Create decoder filter according to codec name.

Internal supported codecs: PCMU, PCMA, speex, gsm Existing Public plugins: iLBC

Parameters

mime	A string indicating the codec.

Returns: a MSFilter if successful, NULL otherwise.

ms_filter_codec_supported()

bool_t ms_filter_codec_supported

(

const char *

mime

)

Check if a encode or decode filter exists for a codec name.

Internal supported codecs: PCMU, PCMA, speex, gsm Existing Public plugins: iLBC

Parameters

mime	A string indicating the codec.

Returns: TRUE if successful, FALSE otherwise.

ms_filter_new()

MSFilter* ms_filter_new

(

MSFilterId

id

)

Create decoder filter according to a filter's MSFilterId.

Parameters

id	A MSFilterId identifier for the filter.

Returns: a MSFilter if successful, NULL otherwise.

ms_filter_new_from_name()

MSFilter* ms_filter_new_from_name

(

const char *

name

)

Create decoder filter according to a filter's name.

Parameters

name	A name for the filter.

Returns: a MSFilter if successful, NULL otherwise.

ms_filter_new_from_desc()

MSFilter* ms_filter_new_from_desc

(

MSFilterDesc *

desc

)

Create decoder filter according to a filter's description.

The primary use is to create your own filter's in your application and avoid registration inside mediastreamer2.

Parameters

desc	A MSFilterDesc for the filter.

Returns: a MSFilter if successful, NULL otherwise.

ms_filter_link()

int ms_filter_link	(	MSFilter *	f1,
		int	pin1,
		MSFilter *	f2,
		int	pin2
	)

Link one OUTPUT pin from a filter to an INPUT pin of another filter.

All data coming from the OUTPUT pin of one filter will be distributed to the INPUT pin of the second filter.

Parameters

f1	A MSFilter object containing the OUTPUT pin
pin1	An index of an OUTPUT pin.
f2	A MSFilter object containing the INPUT pin
pin2	An index of an INPUT pin.

Returns: 0 if sucessful, -1 otherwise.

ms_filter_unlink()

int ms_filter_unlink	(	MSFilter *	f1,
		int	pin1,
		MSFilter *	f2,
		int	pin2
	)

Unlink one OUTPUT pin from a filter to an INPUT pin of another filter.

Parameters

f1	A MSFilter object containing the OUTPUT pin
pin1	An index of an OUTPUT pin.
f2	A MSFilter object containing the INPUT pin
pin2	An index of an INPUT pin.

Returns: 0 if sucessful, -1 otherwise.

ms_filter_call_method()

int ms_filter_call_method	(	MSFilter *	f,
		unsigned int	id,
		void *	arg
	)

Call a filter's method to set or get options.

Parameters

f	A MSFilter object.
id	A private filter ID for the option.
arg	A private user data for the filter.

Returns: 0 if successful, -1 otherwise.

ms_filter_call_method_noarg()

int ms_filter_call_method_noarg	(	MSFilter *	f,
		unsigned int	id
	)

Call a filter's method to set options.

Parameters

f	A MSFilter object.
id	A private filter ID for the option.

Returns: 0 if successful, -1 otherwise.

ms_filter_set_notify_callback()

void ms_filter_set_notify_callback	(	MSFilter *	f,
		MSFilterNotifyFunc	fn,
		void *	userdata
	)

Set a callback on filter's to be informed of private filter's event. This callback is called from the filter's MSTicker, unless a global event queue is created to receive all filter's notification asynchronously. See ms_event_queue_new() for details.

Parameters

f	A MSFilter object.
fn	A MSFilterNotifyFunc that will be called.
userdata	A pointer to private data.

ms_filter_enable_synchronous_notifcations()

void ms_filter_enable_synchronous_notifcations	(	MSFilter *	f,
		bool_t	yesno
	)

Forces the filter to synchronously send notifications, that is the notify callback will be called from MSTicker thread instead of being run by a MSEventQueue.

ms_filter_get_id()

MSFilterId ms_filter_get_id

(

MSFilter *

f

)

Get MSFilterId's filter.

Parameters

f	A MSFilter object.

Returns: MSFilterId if successful, -1 otherwise.

ms_filter_find_neighbours()

MSList* ms_filter_find_neighbours

(

MSFilter *

me

)

Obtain the list of current filter's neighbours, ie filters that are part of same graph.

Returns: a MSList of MSFilter, that needs to be freed by the caller when no more needed.

ms_filter_destroy()

void ms_filter_destroy

(

MSFilter *

f

)

Destroy a filter object.

Parameters

f	A MSFilter object.

ms_connection_helper_start()

void ms_connection_helper_start

(

MSConnectionHelper *

h

)

Initialize a MSConnectionHelper.

Parameters

h	A MSConnectionHelper, usually (but not necessarily) on stack

ms_connection_helper_link()

int ms_connection_helper_link	(	MSConnectionHelper *	h,
		MSFilter *	f,
		int	inpin,
		int	outpin
	)

Enter a MSFilter to be connected into the MSConnectionHelper object.

This functions enters a MSFilter to be connected into the MSConnectionHelper object and connects it to the last entered if not the first one. The MSConnectionHelper is useful to reduce the amount of code necessary to create graphs in case the connections are made in an ordered manner and some filters are present conditionally in graphs. For example, instead of writing

ms_filter_link(f1,0,f2,1);
ms_filter_link(f2,0,f3,0);
ms_filter_link(f3,1,f4,0);

You can write:

MSConnectionHelper h;
ms_connection_helper_start(&h);
ms_connection_helper_link(&h,f1,-1,0);
ms_connection_helper_link(&h,f2,1,0);
ms_connection_helper_link(&h,f3,0,1);
ms_connection_helper_link(&h,f4,0,-1);

Which is a bit longer to write here, but now imagine f2 needs to be present in the graph only in certain conditions: in the first case you have rewrite the two first lines, in the second case you just need to replace the fourth line by:

if (my_condition) ms_connection_helper_link(&h,f2,1,0);

Parameters

h	a connection helper
f	a MSFilter
inpin	an input pin number with which the MSFilter needs to connect to previously entered MSFilter
outpin	an output pin number with which the MSFilter needs to be connected to the next entered MSFilter

Returns: the return value of ms_filter_link() that is called internally to this function.