msfactory.h 12.3 KB
Newer Older
Simon Morlat's avatar
Simon Morlat committed
1
/*
2 3 4
mediastreamer2 library - modular sound and video processing and streaming
Copyright (C) 2014  Belledonne Communications SARL

Simon Morlat's avatar
Simon Morlat committed
5 6 7 8 9 10 11 12 13 14 15 16
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
17
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
Simon Morlat's avatar
Simon Morlat committed
18 19 20 21 22
*/

#ifndef msfactory_h
#define msfactory_h

23 24

#include "mediastreamer2/msfilter.h"
25
#include "mediastreamer2/devices.h"
26

Simon Morlat's avatar
Simon Morlat committed
27 28 29 30
/*do not use these fields directly*/
struct _MSFactory{
	MSList *desc_list;
	MSList *stats_list;
31
	MSList *offer_answer_provider_list;
32
#ifdef _WIN32
Simon Morlat's avatar
Simon Morlat committed
33 34 35
	MSList *ms_plugins_loaded_list;
#endif
	MSList *formats;
36
	MSList *platform_tags;
Simon Morlat's avatar
Simon Morlat committed
37
	char *plugins_dir;
38
	struct _MSVideoPresetsManager *video_presets_manager;
Simon Morlat's avatar
Simon Morlat committed
39 40 41 42
	int cpu_count;
	struct _MSEventQueue *evq;
	int max_payload_size;
	int mtu;
43
	struct _MSSndCardManager* sndcardmanager;
44
	struct _MSWebCamManager* wbcmanager;
45 46 47
	void (*voip_uninit_func)(struct _MSFactory*);
	bool_t statistics_enabled;
	bool_t voip_initd;
48
	MSDevicesInfo *devices_info;
Simon Morlat's avatar
Simon Morlat committed
49 50 51 52
};

typedef struct _MSFactory MSFactory;

Simon Morlat's avatar
Simon Morlat committed
53 54 55 56
#ifdef __cplusplus
extern "C" {
#endif

57
#ifndef MS2_DEPRECATED
58
#if defined(_MSC_VER)
59
#define MS2_DEPRECATED __declspec(deprecated)
60
#else
61
#define MS2_DEPRECATED __attribute__ ((deprecated))
62 63 64
#endif
#endif
	
Simon Morlat's avatar
Simon Morlat committed
65 66 67 68 69
/**
 * Create a mediastreamer2 factory. This is the root object that will create everything else from mediastreamer2.
**/
MS2_PUBLIC MSFactory *ms_factory_new(void);

70 71 72 73 74
/**
 * Create a mediastreamer2 factory and initialize all voip related filter, card and webcam managers.
**/
MS2_PUBLIC MSFactory* ms_factory_new_with_voip(void);

75
/**
76
 * Create the fallback factory (for compatibility with applications not using MSFactory to create ms2 object)
77
**/
78
MS2_DEPRECATED MS2_PUBLIC MSFactory *ms_factory_create_fallback(void);
79

Simon Morlat's avatar
Simon Morlat committed
80 81 82 83
/**
 * Used by the legacy functions before MSFactory was added.
 * Do not use in an application.
**/
84
MS2_DEPRECATED MS2_PUBLIC MSFactory *ms_factory_get_fallback(void);
Simon Morlat's avatar
Simon Morlat committed
85 86 87 88 89 90 91

/**
 * Destroy the factory.
 * This should be done after destroying all objects created by the factory.
**/
MS2_PUBLIC void ms_factory_destroy(MSFactory *factory);

92 93 94 95 96
/*
 * Obtain the soundcard manager.
**/
MS2_PUBLIC struct _MSSndCardManager* ms_factory_get_snd_card_manager(MSFactory *f);

97
/**
98 99 100
 * Obtain the webcam manager.
*/
MS2_PUBLIC struct _MSWebCamManager* ms_factory_get_web_cam_manager(MSFactory* f);
101

102

103 104 105
/**
 * Register a filter descriptor (MSFilterDesc) into the factory.
**/
Simon Morlat's avatar
Simon Morlat committed
106 107 108 109 110 111 112
MS2_PUBLIC void ms_factory_register_filter(MSFactory *factory, MSFilterDesc *desc);

/**
 * Retrieve capture filter that supports encoding to codec name.
 *
 * @param mime    A string indicating the codec.
 *
113
 * @return a MSFilterDesc if successfull, NULL otherwise.
Simon Morlat's avatar
Simon Morlat committed
114 115 116 117 118 119 120 121
 */
MS2_PUBLIC MSFilterDesc * ms_factory_get_encoding_capturer(MSFactory *factory, const char *mime);

/**
 * Retrieve render filter that supports decoding to codec name.
 *
 * @param mime    A string indicating the codec.
 *
122
 * @return a MSFilterDesc if successfull, NULL otherwise.
Simon Morlat's avatar
Simon Morlat committed
123 124 125 126 127 128 129 130
 */
MS2_PUBLIC MSFilterDesc * ms_factory_get_decoding_renderer(MSFactory *factory, const char *mime);

/**
 * Retrieve encoders according to codec name.
 *
 * @param mime    A string indicating the codec.
 *
131
 * @return a MSFilterDesc if successfull, NULL otherwise.
Simon Morlat's avatar
Simon Morlat committed
132 133 134 135 136 137 138 139
 */
MS2_PUBLIC MSFilterDesc * ms_factory_get_encoder(MSFactory *factory, const char *mime);

/**
 * Retrieve decoders according to codec name.
 *
 * @param mime    A string indicating the codec.
 *
140
 * @return a MSFilterDesc if successfull, NULL otherwise.
Simon Morlat's avatar
Simon Morlat committed
141 142 143 144 145 146 147 148 149 150 151
 */
MS2_PUBLIC MSFilterDesc * ms_factory_get_decoder(MSFactory *factory, const char *mime);

/**
 * 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.
 *
 * @param filter_name The filter name.
**/
152
MS2_PUBLIC MSFilterDesc *ms_factory_lookup_filter_by_name(const MSFactory *factory, const char *filter_name);
Simon Morlat's avatar
Simon Morlat committed
153 154 155 156 157 158 159 160 161 162 163 164 165 166 167

/**
 * Lookup a mediastreamer2 filter using its id.
 * 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.
 *
 * @param id The filter id.
**/
MS2_PUBLIC MSFilterDesc* ms_factory_lookup_filter_by_id( MSFactory* factory, MSFilterId id);

/**
 * Returns a list of filter descriptions implementing a given interface.
 * 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
168
 * @return a newly allocated MSList of #MSFilterDesc.
Simon Morlat's avatar
Simon Morlat committed
169
**/
170
MS2_PUBLIC MSList *ms_factory_lookup_filter_by_interface(MSFactory *factory, MSFilterInterfaceId id);
Simon Morlat's avatar
Simon Morlat committed
171 172 173 174 175 176

/**
 * Create encoder filter according to codec name.
 *
 * @param mime    A string indicating the codec.
 *
177
 * @return a MSFilter if successfull, NULL otherwise.
Simon Morlat's avatar
Simon Morlat committed
178 179 180 181 182 183 184 185
 */
MS2_PUBLIC MSFilter * ms_factory_create_encoder(MSFactory *factory, const char *mime);

/**
 * Create decoder filter according to codec name.
 *
 * @param mime    A string indicating the codec.
 *
186
 * @return a MSFilter if successfull, NULL otherwise.
Simon Morlat's avatar
Simon Morlat committed
187 188 189 190 191 192 193 194
 */
MS2_PUBLIC MSFilter * ms_factory_create_decoder(MSFactory *factory, const char *mime);

/**
 * Check if a encode or decode filter exists for a codec name.
 *
 * @param mime    A string indicating the codec.
 *
195
 * @return TRUE if successfull, FALSE otherwise.
Simon Morlat's avatar
Simon Morlat committed
196 197 198 199 200 201 202 203
 */
MS2_PUBLIC bool_t ms_factory_codec_supported(MSFactory *factory, const char *mime);

/**
 * Create decoder filter according to a filter's MSFilterId.
 *
 * @param id     A MSFilterId identifier for the filter.
 *
204
 * @return a MSFilter if successfull, NULL otherwise.
Simon Morlat's avatar
Simon Morlat committed
205 206 207 208 209 210 211 212
 */
MS2_PUBLIC MSFilter *ms_factory_create_filter(MSFactory *factory, MSFilterId id);

/**
 * Create decoder filter according to a filter's name.
 *
 * @param name   A name for the filter.
 *
213
 * @return a MSFilter if successfull, NULL otherwise.
Simon Morlat's avatar
Simon Morlat committed
214 215 216 217 218 219 220 221 222 223 224
 */
MS2_PUBLIC MSFilter *ms_factory_create_filter_from_name(MSFactory *factory, const char *name);

/**
 * 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.
 *
 * @param desc   A MSFilterDesc for the filter.
 *
225
 * @return a MSFilter if successfull, NULL otherwise.
Simon Morlat's avatar
Simon Morlat committed
226 227 228
 */
MS2_PUBLIC MSFilter *ms_factory_create_filter_from_desc(MSFactory *factory, MSFilterDesc *desc);

229 230 231
/**
 * Enable filter statistics measurement at run time.
**/
Simon Morlat's avatar
Simon Morlat committed
232 233
MS2_PUBLIC void ms_factory_enable_statistics(MSFactory* obj, bool_t enabled);

234 235 236
/**
 * Obtain a list of MSFilterStats.
**/
Simon Morlat's avatar
Simon Morlat committed
237 238
MS2_PUBLIC const MSList * ms_factory_get_statistics(MSFactory* obj);

239 240 241
/**
 * Reset filter's statistics.
**/
Simon Morlat's avatar
Simon Morlat committed
242 243
MS2_PUBLIC void ms_factory_reset_statistics(MSFactory *obj);

244 245 246
/**
 * Output statistics to logs.
**/
Simon Morlat's avatar
Simon Morlat committed
247 248
MS2_PUBLIC void ms_factory_log_statistics(MSFactory *obj);

249 250 251 252 253
/**
 * 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.
**/
Simon Morlat's avatar
Simon Morlat committed
254 255
MS2_PUBLIC unsigned int ms_factory_get_cpu_count(MSFactory *obj);

256 257 258
/**
 * Set the number of available cpus for processing.
**/
Simon Morlat's avatar
Simon Morlat committed
259 260
MS2_PUBLIC void ms_factory_set_cpu_count(MSFactory *obj, unsigned int c);

261 262 263 264 265 266 267 268
MS2_PUBLIC void ms_factory_add_platform_tag(MSFactory *obj, const char *tag);

MS2_PUBLIC MSList * ms_factory_get_platform_tags(MSFactory *obj);

MS2_PUBLIC char * ms_factory_get_platform_tags_as_string(MSFactory *obj);

MS2_PUBLIC struct _MSVideoPresetsManager * ms_factory_get_video_presets_manager(MSFactory *factory);

Simon Morlat's avatar
Simon Morlat committed
269 270
MS2_PUBLIC void ms_factory_init_plugins(MSFactory *obj);

271 272 273
/**
 * Set directory where plugins are to be loaded.
**/
Simon Morlat's avatar
Simon Morlat committed
274 275
MS2_PUBLIC void ms_factory_set_plugins_dir(MSFactory *obj, const char *path);

Simon Morlat's avatar
Simon Morlat committed
276 277
MS2_PUBLIC int ms_factory_load_plugins(MSFactory *factory, const char *dir);

Simon Morlat's avatar
Simon Morlat committed
278 279
MS2_PUBLIC void ms_factory_uninit_plugins(MSFactory *obj);

280 281 282
/**
 * Init VOIP features (registration of codecs, sound card and webcam managers).
**/
Simon Morlat's avatar
Simon Morlat committed
283 284 285 286
MS2_PUBLIC void ms_factory_init_voip(MSFactory *obj);

MS2_PUBLIC void ms_factory_uninit_voip(MSFactory *obj);

287 288 289 290 291 292 293
/**
 * Creates an event queue.
 * Only one can exist so if it has already been created the same one will be returned.
 * @param[in] obj MSFactory object.
 * @return The created event queue.
 */
MS2_PUBLIC struct _MSEventQueue * ms_factory_create_event_queue(MSFactory *obj);
294 295 296 297
	
MS2_PUBLIC void ms_factory_destroy_event_queue(MSFactory *obj);
	
	/**
298 299 300 301 302
 * Gets the event queue associated with the factory.
 * Can be NULL if no event queue has been created.
 * @param[in] obj MSFactory object.
 * @return The event queue associated with the factory.
 */
Simon Morlat's avatar
Simon Morlat committed
303 304 305 306 307 308 309
MS2_PUBLIC struct _MSEventQueue * ms_factory_get_event_queue(MSFactory *obj);

MS2_PUBLIC void ms_factory_set_event_queue(MSFactory *obj,struct _MSEventQueue *q);

MS2_PUBLIC int ms_factory_get_payload_max_size(MSFactory *factory);

MS2_PUBLIC void ms_factory_set_payload_max_size(MSFactory *obj, int size);
310
	
311 312 313
MS2_PUBLIC void ms_factory_set_mtu(MSFactory *obj, int mtu);

MS2_PUBLIC int ms_factory_get_mtu(MSFactory *obj);
Simon Morlat's avatar
Simon Morlat committed
314 315 316

MS2_PUBLIC const struct _MSFmtDescriptor * ms_factory_get_audio_format(MSFactory *obj, const char *mime, int rate, int channels, const char *fmtp);

317 318 319
MS2_PUBLIC const struct _MSFmtDescriptor * ms_factory_get_video_format(MSFactory *obj, const char *mime, MSVideoSize size, float fps, const char *fmtp);

MS2_PUBLIC const MSFmtDescriptor *ms_factory_get_format(MSFactory *obj, const MSFmtDescriptor *ref);
Simon Morlat's avatar
Simon Morlat committed
320

321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340
/**
 * Specifies if a filter is enabled or not. Only enabled filter are return by functions like ms_filter_get_encoder
 * @param factory
 * @param name   A name for the filter.
 * @param enable, true/false
 * @return 0 in case of success
 *
 */
MS2_PUBLIC int ms_factory_enable_filter_from_name(MSFactory *factory, const char *name, bool_t enable);

/**
 * Specifies if a filter is enabled or not. Only enabled filter are return by functions like ms_filter_get_encoder
 *
 * @param factory
 * @param name   A name for the filter.
 * @return true/false if enabled
 *
 */
MS2_PUBLIC bool_t ms_factory_filter_from_name_enabled(const MSFactory *factory, const char *name);

341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375

#ifndef MS_OFFER_ANSWER_CONTEXT_DEFINED
#define MS_OFFER_ANSWER_CONTEXT_DEFINED
typedef struct _MSOfferAnswerContext MSOfferAnswerContext;
#endif
typedef struct _MSOfferAnswerProvider MSOfferAnswerProvider;

/**
 * Registers an offer-answer provider. An offer answer provider is a kind of factory that creates
 * context objects able to execute the particular offer/answer logic for a given codec.
 * Indeed, several codecs have complex parameter handling specified in their RFC, and hence cannot be
 * treated in a generic way by the global SDP offer answer logic.
 * Mediastreamer2 plugins can then register with this method their offer/answer logic together with the encoder
 * and decoder filters, so that it can be used by the signaling layer of the application.
 * @param factory 
 * @param offer_answer_prov the offer answer provider descriptor.
**/
MS2_PUBLIC void ms_factory_register_offer_answer_provider(MSFactory *f, MSOfferAnswerProvider *offer_answer_prov);

/**
 * Retrieve an offer answer provider previously registered, giving the codec name.
 * @param f the factory
 * @param mime_type the codec mime type.
 * @return an MSOfferAnswerProvider or NULL if none was registered for this codec.
**/
MS2_PUBLIC MSOfferAnswerProvider * ms_factory_get_offer_answer_provider(MSFactory *f, const char *mime_type);

/**
 * Directly creates an offer-answer context giving the codec mime-type.
 * @param f the factory
 * @param the mime-type of the codec.
 * @return an MSOfferAnswerContext or NULL if none was registered for this codec.
**/
MS2_PUBLIC MSOfferAnswerContext * ms_factory_create_offer_answer_context(MSFactory *f, const char *mime_type);

376 377
MS2_PUBLIC MSDevicesInfo* ms_factory_get_devices_info(MSFactory *f);

Simon Morlat's avatar
Simon Morlat committed
378 379 380 381
#ifdef __cplusplus
}
#endif
	
Simon Morlat's avatar
Simon Morlat committed
382
#endif