mediastreamer2 2.7.3
Defines | Typedefs | Enumerations | Functions
Filter API - manage mediastreamer2 filters.
Mediastreamer2's base APIs

Filter API to manage mediastreamer2 filters. More...

Defines

#define MS_FILTER_SET_SAMPLE_RATE   MS_FILTER_BASE_METHOD(0,int)
#define MS_FILTER_GET_SAMPLE_RATE   MS_FILTER_BASE_METHOD(1,int)
#define MS_FILTER_SET_BITRATE   MS_FILTER_BASE_METHOD(2,int)
#define MS_FILTER_GET_BITRATE   MS_FILTER_BASE_METHOD(3,int)
#define MS_FILTER_ADD_FMTP   MS_FILTER_BASE_METHOD(7,const char)
#define MS_FILTER_GET_LATENCY   MS_FILTER_BASE_METHOD(11,int)

Typedefs

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

Enumerations

enum  _MSFilterCategory {
  MS_FILTER_OTHER,
  MS_FILTER_ENCODER,
  MS_FILTER_DECODER
}

Functions

void ms_filter_register (MSFilterDesc *desc)
MSFilterDescms_filter_get_encoder (const char *mime)
MSFilterDescms_filter_get_decoder (const char *mime)
MSFilterDescms_filter_lookup_by_name (const char *filter_name)
MSFilterms_filter_create_encoder (const char *mime)
MSFilterms_filter_create_decoder (const char *mime)
bool_t ms_filter_codec_supported (const char *mime)
MSFilterms_filter_new (MSFilterId id)
MSFilterms_filter_new_from_name (const char *name)
MSFilterms_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)
bool_t ms_filter_has_method (MSFilter *f, unsigned int id)
void ms_filter_set_notify_callback (MSFilter *f, MSFilterNotifyFunc fn, void *userdata)
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.
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.
void ms_filter_enable_statistics (bool_t enabled)
 Enable processing time measurements statistics for filters.
void ms_filter_reset_statistics (void)
 Reset processing time statistics for filters.
const MSList * ms_filter_get_statistics (void)
 Retrieves statistics for running filters. Returns a list of MSFilterStats.
void ms_filter_log_statistics (void)
 Logs runtime statistics for running filters.

Detailed Description

Filter API to manage mediastreamer2 filters.

This section documents the API needed to create, link, unlink, find and destroy filters.

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


Define Documentation

#define MS_FILTER_SET_SAMPLE_RATE   MS_FILTER_BASE_METHOD(0,int)

some MSFilter base generic methods: Set filter output/input sampling frequency in hertz

#define MS_FILTER_GET_SAMPLE_RATE   MS_FILTER_BASE_METHOD(1,int)

Get filter output/input sampling frequency in hertz

#define MS_FILTER_SET_BITRATE   MS_FILTER_BASE_METHOD(2,int)

Set filter output network bitrate in bit per seconds, this value include IP+UDP+RTP overhead

#define MS_FILTER_GET_BITRATE   MS_FILTER_BASE_METHOD(3,int)

Get filter output network bitrate in bit per seconds, this value include IP+UDP+RTP overhead

#define MS_FILTER_ADD_FMTP   MS_FILTER_BASE_METHOD(7,const char)

Set codec dependent attributes as taken from the SDP

#define MS_FILTER_GET_LATENCY   MS_FILTER_BASE_METHOD(11,int)

Filters can return their latency in milliseconds (if known) using this method:


Typedef Documentation

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

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

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

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

Structure to describe filter's category.

     MS_FILTER_OTHER
     MS_FILTER_ENCODER
     MS_FILTER_DECODER
 

Structure for filter's description.

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

Structure that represents a connection point of a MSFilter

Structure that holds data when using the ms_connection_helper_* functions.


Enumeration Type Documentation

Filter's category

Enumerator:
MS_FILTER_OTHER 

others

MS_FILTER_ENCODER 

used by encoders

MS_FILTER_DECODER 

used by decoders


Function Documentation

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:
desca filter description.
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:
mimeA string indicating the codec.

Returns: a MSFilterDesc if successfull, NULL otherwise.

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:
mimeA string indicating the codec.

Returns: a MSFilterDesc if successfull, NULL otherwise.

MSFilterDesc* ms_filter_lookup_by_name ( const char *  filter_name)

Lookup a mediastreamer2 filter using its name. If found, the descriptor (MSFilterDesc) is returned. This descriptor can be used to instanciate the filter using ms_filter_new_from_desc() This function can be useful to query the presence of a filter loaded as a plugin, for example.

Parameters:
nameThe filter name.
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:
mimeA string indicating the codec.

Returns: a MSFilter if successfull, NULL otherwise.

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:
mimeA string indicating the codec.

Returns: a MSFilter if successfull, NULL otherwise.

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:
mimeA string indicating the codec.

Returns: TRUE if successfull, FALSE otherwise.

MSFilter* ms_filter_new ( MSFilterId  id)

Create decoder filter according to a filter's MSFilterId.

Parameters:
idA MSFilterId identifier for the filter.

Returns: a MSFilter if successfull, NULL otherwise.

MSFilter* ms_filter_new_from_name ( const char *  name)

Create decoder filter according to a filter's name.

Parameters:
nameA name for the filter.

Returns: a MSFilter if successfull, NULL otherwise.

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:
descA MSFilterDesc for the filter.

Returns: a MSFilter if successfull, NULL otherwise.

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:
f1A MSFilter object containing the OUTPUT pin
pin1An index of an OUTPUT pin.
f2A MSFilter object containing the INPUT pin
pin2An index of an INPUT pin.

Returns: 0 if sucessful, -1 otherwise.

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:
f1A MSFilter object containing the OUTPUT pin
pin1An index of an OUTPUT pin.
f2A MSFilter object containing the INPUT pin
pin2An index of an INPUT pin.

Returns: 0 if sucessful, -1 otherwise.

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

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

Parameters:
fA MSFilter object.
idA private filter ID for the option.
argA private user data for the filter.

Returns: 0 if successfull, -1 otherwise.

int ms_filter_call_method_noarg ( MSFilter f,
unsigned int  id 
)

Call a filter's method to set options.

Parameters:
fA MSFilter object.
idA method ID.

Returns: 0 if successfull, -1 otherwise.

bool_t ms_filter_has_method ( MSFilter f,
unsigned int  id 
)

Returns whether the filter implements a given method

Parameters:
fA MSFilter object.
idA method ID.

Returns: 0 if successfull, -1 otherwise.

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:
fA MSFilter object.
fnA MSFilterNotifyFunc that will be called.
userdataA pointer to private data.
MSFilterId ms_filter_get_id ( MSFilter f)

Get MSFilterId's filter.

Parameters:
fA MSFilter object.

Returns: MSFilterId if successfull, -1 otherwise.

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.

void ms_filter_destroy ( MSFilter f)

Destroy a filter object.

Parameters:
fA MSFilter object.
void ms_connection_helper_start ( MSConnectionHelper h)

Initialize a MSConnectionHelper.

Parameters:
hA MSConnectionHelper, usually (but not necessarily) on stack
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:

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:
ha connection helper
fa MSFilter
inpinan input pin number with which the MSFilter needs to connect to previously entered MSFilter
outpinan 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.

Rabisu Mirror Service We provide mirrors to support Open source communities. Our mirror server is located in Istanbul/Turkey region.

Please do not hesitate to contact mirror@rabisu.com for new open source mirror submissions.