Commit e0cb2532 authored by Simon Morlat's avatar Simon Morlat

improve documentation, in particular indicate the replacement of obsoleted functions

parent 8c6bf3d3
......@@ -347,6 +347,7 @@ MS2_PUBLIC bool_t ms_tags_list_contains_tag(const MSList *list, const char *tag)
* Initialize the mediastreamer2 base library.
*
* This must be called once before calling any other API.
* @deprecated use ms_factory_new()
*/
MS2_PUBLIC MS2_DEPRECATED void ms_base_init(void);
......@@ -354,6 +355,7 @@ MS2_PUBLIC MS2_DEPRECATED void ms_base_init(void);
* Initialize the mediastreamer2 VoIP library.
*
* This must be called one before calling any other API.
* @deprecated use ms_factory_new_with_voip().
*/
MS2_PUBLIC MS2_DEPRECATED void ms_voip_init(void);
......@@ -362,12 +364,14 @@ MS2_PUBLIC MS2_DEPRECATED void ms_voip_init(void);
*
* This is just a wrapper around ms_load_plugins().
* This must be called after ms_base_init() and after ms_voip_init().
* @deprecated use ms_factory_init_plugins(), or ms_factory_new_with_voip() that does it automatically.
*/
MS2_PUBLIC MS2_DEPRECATED void ms_plugins_init(void);
/**
* Set the directory from where the plugins are to be loaded when calling ms_plugins_init().
* @param[in] path The path to the plugins directory.
* @deprecated use ms_factory_set_plugins_dir().
*/
MS2_PUBLIC MS2_DEPRECATED void ms_set_plugins_dir(const char *path);
......@@ -380,7 +384,8 @@ MS2_PUBLIC MS2_DEPRECATED void ms_set_plugins_dir(const char *path);
*
* @param directory A directory where plugins library are available.
*
* Returns: >0 if successfull, 0 if not plugins loaded, -1 otherwise.
* @return >0 if successfull, 0 if not plugins loaded, -1 otherwise.
* @deprecated use ms_factory_load_plugins().
*/
MS2_PUBLIC MS2_DEPRECATED int ms_load_plugins(const char *directory);
......@@ -388,6 +393,7 @@ MS2_PUBLIC MS2_DEPRECATED int ms_load_plugins(const char *directory);
* Release resource allocated in the mediastreamer2 base library.
*
* This must be called once before closing program.
* @deprecated use ms_factory_destroy().
*/
MS2_PUBLIC MS2_DEPRECATED void ms_base_exit(void);
......@@ -395,11 +401,13 @@ MS2_PUBLIC MS2_DEPRECATED void ms_base_exit(void);
* Release resource allocated in the mediastreamer2 VoIP library.
*
* This must be called once before closing program.
* @deprecated use ms_factory_destroy().
*/
MS2_PUBLIC MS2_DEPRECATED void ms_voip_exit(void);
/**
* Unload the plugins loaded by ms_plugins_init().
* @deprecated use ms_factory_destroy().
*/
MS2_PUBLIC MS2_DEPRECATED void ms_plugins_exit(void);
......@@ -416,10 +424,14 @@ MS2_PUBLIC void ms_usleep(uint64_t usec);
* The default value is 1440 computed as the standard internet MTU minus IPv6 header,
* UDP header and RTP header. As IPV4 header is smaller than IPv6 header, this
* value works for both.
*
* @deprecated use ms_factory_get_payload_max_size().
**/
MS2_PUBLIC MS2_DEPRECATED int ms_get_payload_max_size(void);
/**
* Set the maximum payload size allowed.
* @deprecated use ms_factory_set_payload_max_size().
**/
MS2_PUBLIC MS2_DEPRECATED void ms_set_payload_max_size(int size);
/**
......@@ -432,19 +444,25 @@ MS2_PUBLIC int ms_discover_mtu(const char *destination_host);
/**
* Set mediastreamer default mtu, used to compute the default RTP max payload size.
* This function will call ms_set_payload_max_size(mtu-[ipv6 header size]).
* @deprecated use ms_factory_set_mtu()
**/
MS2_PUBLIC MS2_DEPRECATED void ms_set_mtu(int mtu);
/**
* Get mediastreamer default mtu, used to compute the default RTP max payload size.
* @deprecated use ms_factory_get_mtu().
**/
MS2_PUBLIC MS2_DEPRECATED int ms_get_mtu(void);
/**
* Declare how many cpu (cores) are available on the platform
* @deprecated use ms_factory_set_cpu_count().
*/
MS2_PUBLIC MS2_DEPRECATED void ms_set_cpu_count(unsigned int c);
/**
* @deprecated use ms_factory_get_cpu_count().
**/
MS2_PUBLIC MS2_DEPRECATED unsigned int ms_get_cpu_count(void);
/**
......
......@@ -99,6 +99,9 @@ MS2_PUBLIC struct _MSSndCardManager* ms_factory_get_snd_card_manager(MSFactory *
MS2_PUBLIC struct _MSWebCamManager* ms_factory_get_web_cam_manager(MSFactory* f);
/**
* Register a filter descriptor (MSFilterDesc) into the factory.
**/
MS2_PUBLIC void ms_factory_register_filter(MSFactory *factory, MSFilterDesc *desc);
/**
......@@ -106,7 +109,7 @@ MS2_PUBLIC void ms_factory_register_filter(MSFactory *factory, MSFilterDesc *des
*
* @param mime A string indicating the codec.
*
* Returns: a MSFilterDesc if successfull, NULL otherwise.
* @return a MSFilterDesc if successfull, NULL otherwise.
*/
MS2_PUBLIC MSFilterDesc * ms_factory_get_encoding_capturer(MSFactory *factory, const char *mime);
......@@ -115,35 +118,25 @@ MS2_PUBLIC MSFilterDesc * ms_factory_get_encoding_capturer(MSFactory *factory, c
*
* @param mime A string indicating the codec.
*
* Returns: a MSFilterDesc if successfull, NULL otherwise.
* @return a MSFilterDesc if successfull, NULL otherwise.
*/
MS2_PUBLIC MSFilterDesc * ms_factory_get_decoding_renderer(MSFactory *factory, const char *mime);
/**
* Retrieve encoders according to codec name.
*
* Internal supported codecs:
* PCMU, PCMA, speex, gsm
* Existing Public plugins:
* iLBC
*
* @param mime A string indicating the codec.
*
* Returns: a MSFilterDesc if successfull, NULL otherwise.
* @return a MSFilterDesc if successfull, NULL otherwise.
*/
MS2_PUBLIC MSFilterDesc * ms_factory_get_encoder(MSFactory *factory, const char *mime);
/**
* Retrieve decoders according to codec name.
*
* Internal supported codecs:
* PCMU, PCMA, speex, gsm
* Existing Public plugins:
* iLBC
*
* @param mime A string indicating the codec.
*
* Returns: a MSFilterDesc if successfull, NULL otherwise.
* @return a MSFilterDesc if successfull, NULL otherwise.
*/
MS2_PUBLIC MSFilterDesc * ms_factory_get_decoder(MSFactory *factory, const char *mime);
......@@ -178,42 +171,27 @@ MS2_PUBLIC MSList *ms_factory_lookup_filter_by_interface(MSFactory *factory, MSF
/**
* Create encoder filter according to codec name.
*
* Internal supported codecs:
* PCMU, PCMA, speex, gsm
* Existing Public plugins:
* iLBC
*
* @param mime A string indicating the codec.
*
* Returns: a MSFilter if successfull, NULL otherwise.
* @return a MSFilter if successfull, NULL otherwise.
*/
MS2_PUBLIC MSFilter * ms_factory_create_encoder(MSFactory *factory, const char *mime);
/**
* Create decoder filter according to codec name.
*
* Internal supported codecs:
* PCMU, PCMA, speex, gsm
* Existing Public plugins:
* iLBC
*
* @param mime A string indicating the codec.
*
* Returns: a MSFilter if successfull, NULL otherwise.
* @return a MSFilter if successfull, NULL otherwise.
*/
MS2_PUBLIC MSFilter * ms_factory_create_decoder(MSFactory *factory, 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
*
* @param mime A string indicating the codec.
*
* Returns: TRUE if successfull, FALSE otherwise.
* @return TRUE if successfull, FALSE otherwise.
*/
MS2_PUBLIC bool_t ms_factory_codec_supported(MSFactory *factory, const char *mime);
......@@ -222,7 +200,7 @@ MS2_PUBLIC bool_t ms_factory_codec_supported(MSFactory *factory, const char *mim
*
* @param id A MSFilterId identifier for the filter.
*
* Returns: a MSFilter if successfull, NULL otherwise.
* @return a MSFilter if successfull, NULL otherwise.
*/
MS2_PUBLIC MSFilter *ms_factory_create_filter(MSFactory *factory, MSFilterId id);
......@@ -231,7 +209,7 @@ MS2_PUBLIC MSFilter *ms_factory_create_filter(MSFactory *factory, MSFilterId id)
*
* @param name A name for the filter.
*
* Returns: a MSFilter if successfull, NULL otherwise.
* @return a MSFilter if successfull, NULL otherwise.
*/
MS2_PUBLIC MSFilter *ms_factory_create_filter_from_name(MSFactory *factory, const char *name);
......@@ -243,20 +221,40 @@ MS2_PUBLIC MSFilter *ms_factory_create_filter_from_name(MSFactory *factory, cons
*
* @param desc A MSFilterDesc for the filter.
*
* Returns: a MSFilter if successfull, NULL otherwise.
* @return a MSFilter if successfull, NULL otherwise.
*/
MS2_PUBLIC MSFilter *ms_factory_create_filter_from_desc(MSFactory *factory, MSFilterDesc *desc);
/**
* Enable filter statistics measurement at run time.
**/
MS2_PUBLIC void ms_factory_enable_statistics(MSFactory* obj, bool_t enabled);
/**
* Obtain a list of MSFilterStats.
**/
MS2_PUBLIC const MSList * ms_factory_get_statistics(MSFactory* obj);
/**
* Reset filter's statistics.
**/
MS2_PUBLIC void ms_factory_reset_statistics(MSFactory *obj);
/**
* Output statistics to logs.
**/
MS2_PUBLIC void ms_factory_log_statistics(MSFactory *obj);
/**
* Get number of available cpus for processing.
* The factory initializes this value to the number of logicial processors
* available on the machine where it runs.
**/
MS2_PUBLIC unsigned int ms_factory_get_cpu_count(MSFactory *obj);
/**
* Set the number of available cpus for processing.
**/
MS2_PUBLIC void ms_factory_set_cpu_count(MSFactory *obj, unsigned int c);
MS2_PUBLIC void ms_factory_add_platform_tag(MSFactory *obj, const char *tag);
......@@ -269,12 +267,18 @@ MS2_PUBLIC struct _MSVideoPresetsManager * ms_factory_get_video_presets_manager(
MS2_PUBLIC void ms_factory_init_plugins(MSFactory *obj);
/**
* Set directory where plugins are to be loaded.
**/
MS2_PUBLIC void ms_factory_set_plugins_dir(MSFactory *obj, const char *path);
MS2_PUBLIC int ms_factory_load_plugins(MSFactory *factory, const char *dir);
MS2_PUBLIC void ms_factory_uninit_plugins(MSFactory *obj);
/**
* Init VOIP features (registration of codecs, sound card and webcam managers).
**/
MS2_PUBLIC void ms_factory_init_voip(MSFactory *obj);
MS2_PUBLIC void ms_factory_uninit_voip(MSFactory *obj);
......
......@@ -242,6 +242,7 @@ extern "C"{
* supported.
*
* @param desc a filter description.
* @deprecated use ms_factory_register_filter().
*/
MS2_PUBLIC MS2_DEPRECATED void ms_filter_register(MSFilterDesc *desc);
......@@ -250,7 +251,8 @@ MS2_PUBLIC MS2_DEPRECATED void ms_filter_register(MSFilterDesc *desc);
*
* @param mime A string indicating the codec.
*
* Returns: a MSFilterDesc if successfull, NULL otherwise.
* @return a MSFilterDesc if successfull, NULL otherwise.
* @deprecated use ms_factory_get_encoding_capturer().
*/
MS2_PUBLIC MS2_DEPRECATED MSFilterDesc * ms_filter_get_encoding_capturer(const char *mime);
......@@ -259,35 +261,30 @@ MS2_PUBLIC MS2_DEPRECATED MSFilterDesc * ms_filter_get_encoding_capturer(const c
*
* @param mime A string indicating the codec.
*
* Returns: a MSFilterDesc if successfull, NULL otherwise.
* @returns a MSFilterDesc if successfull, NULL otherwise.
* @deprecated use ms_factory_get_decoding_renderer()
*/
MS2_PUBLIC MS2_DEPRECATED MSFilterDesc * ms_filter_get_decoding_renderer(const char *mime);
/**
* Retrieve encoders according to codec name.
*
* Internal supported codecs:
* PCMU, PCMA, speex, gsm
* Existing Public plugins:
* iLBC
*
* @param mime A string indicating the codec.
*
* Returns: a MSFilterDesc if successfull, NULL otherwise.
* @return a MSFilterDesc if successfull, NULL otherwise.
* @deprecated use ms_factory_get_encoder().
*/
MS2_PUBLIC MS2_DEPRECATED MSFilterDesc * ms_filter_get_encoder(const char *mime);
/**
* Retrieve decoders according to codec name.
*
* Internal supported codecs:
* PCMU, PCMA, speex, gsm
* Existing Public plugins:
* iLBC
*
* @param mime A string indicating the codec.
*
* Returns: a MSFilterDesc if successfull, NULL otherwise.
* @return a MSFilterDesc if successfull, NULL otherwise.
* @deprecated use ms_factory_get_decoder().
*/
MS2_PUBLIC MS2_DEPRECATED MSFilterDesc * ms_filter_get_decoder(const char *mime);
......@@ -298,6 +295,8 @@ MS2_PUBLIC MS2_DEPRECATED MSFilterDesc * ms_filter_get_decoder(const char *mime)
* This function can be useful to query the presence of a filter loaded as a plugin, for example.
*
* @param filter_name The filter name.
* @return a MSFilterDesc or NULL if no match.
* @deprecated use ms_factory_lookup_filter_by_name().
**/
MS2_PUBLIC MS2_DEPRECATED MSFilterDesc *ms_filter_lookup_by_name(const char *filter_name);
......@@ -306,48 +305,38 @@ MS2_PUBLIC MS2_DEPRECATED MSFilterDesc *ms_filter_lookup_by_name(const char *fil
* The list itself must be freed by the caller of this function, but not the MSFilterDesc pointed by the list elements.
* @param id a filter interface id
* @return a newly allocated MSList of #MSFilterDesc.
* @deprecated use ms_factory_lookup_filter_by_interface().
**/
MS2_PUBLIC MS2_DEPRECATED MSList *ms_filter_lookup_by_interface(MSFilterInterfaceId id);
/**
* Create encoder filter according to codec name.
*
* Internal supported codecs:
* PCMU, PCMA, speex, gsm
* Existing Public plugins:
* iLBC
*
* @param mime A string indicating the codec.
*
* Returns: a MSFilter if successfull, NULL otherwise.
* @return a MSFilter if successfull, NULL otherwise.
* @deprecated use ms_factory_create_encoder().
*/
MS2_PUBLIC MS2_DEPRECATED MSFilter * ms_filter_create_encoder(const char *mime);
/**
* Create decoder filter according to codec name.
*
* Internal supported codecs:
* PCMU, PCMA, speex, gsm
* Existing Public plugins:
* iLBC
*
* @param mime A string indicating the codec.
*
* Returns: a MSFilter if successfull, NULL otherwise.
* @return a MSFilter if successfull, NULL otherwise.
* @deprecated use ms_factory_create_decoder().
*/
MS2_PUBLIC MS2_DEPRECATED MSFilter * ms_filter_create_decoder(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
* Check if both an encoder and a decoder filter exists for a codec name.
*
* @param mime A string indicating the codec.
*
* Returns: TRUE if successfull, FALSE otherwise.
* @return TRUE if successfull, FALSE otherwise.
* @deprecated use ms_factory_codec_supported().
*/
MS2_PUBLIC MS2_DEPRECATED bool_t ms_filter_codec_supported(const char *mime);
......@@ -356,7 +345,8 @@ MS2_PUBLIC MS2_DEPRECATED bool_t ms_filter_codec_supported(const char *mime);
*
* @param id A MSFilterId identifier for the filter.
*
* Returns: a MSFilter if successfull, NULL otherwise.
* @returns a MSFilter if successfull, NULL otherwise.
* @deprecated use ms_factory_create_filter().
*/
MS2_PUBLIC MS2_DEPRECATED MSFilter *ms_filter_new(MSFilterId id);
......@@ -365,7 +355,8 @@ MS2_PUBLIC MS2_DEPRECATED MSFilter *ms_filter_new(MSFilterId id);
*
* @param name A name for the filter.
*
* Returns: a MSFilter if successfull, NULL otherwise.
* @return a MSFilter if successfull, NULL otherwise.
* @deprecated use ms_factory_create_filter_from_name().
*/
MS2_PUBLIC MS2_DEPRECATED MSFilter *ms_filter_new_from_name(const char *name);
......@@ -377,7 +368,8 @@ MS2_PUBLIC MS2_DEPRECATED MSFilter *ms_filter_new_from_name(const char *name);
*
* @param desc A MSFilterDesc for the filter.
*
* Returns: a MSFilter if successfull, NULL otherwise.
* @return a MSFilter if successfull, NULL otherwise.
* @deprecated use ms_factory_create_filter_from_desc()
*/
MS2_PUBLIC MS2_DEPRECATED MSFilter *ms_filter_new_from_desc(MSFilterDesc *desc);
......
......@@ -160,6 +160,7 @@ extern "C"{
* Retreive a sound card manager object.
*
* Returns: MSSndCardManager if successfull, NULL otherwise.
* @deprecated use ms_factory_get_snd_card_manager()
*/
MS2_PUBLIC MS2_DEPRECATED MSSndCardManager * ms_snd_card_manager_get(void);
......
......@@ -93,9 +93,10 @@ extern "C"{
#endif
/**
* Retreive a webcam manager object.
* Retrieve a webcam manager object.
*
* Returns: MSWebCamManager if successfull, NULL otherwise.
* @returns: MSWebCamManager if successfull, NULL otherwise.
* @deprecated use ms_factory_get_web_cam_manager().
*/
MS2_PUBLIC MS2_DEPRECATED MSWebCamManager * ms_web_cam_manager_get(void);
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment