1 /*****************************************************************************
2 * modules.c : Builtin and plugin modules management functions
3 *****************************************************************************
4 * Copyright (C) 2001-2011 the VideoLAN team
7 * Authors: Sam Hocevar <sam@zoy.org>
8 * Ethan C. Baldridge <BaldridgeE@cadmus.com>
9 * Hans-Peter Jansen <hpj@urpla.net>
10 * Gildas Bazin <gbazin@videolan.org>
11 * RĂ©mi Denis-Courmont
13 * This program is free software; you can redistribute it and/or modify
14 * it under the terms of the GNU General Public License as published by
15 * the Free Software Foundation; either version 2 of the License, or
16 * (at your option) any later version.
18 * This program is distributed in the hope that it will be useful,
19 * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 * GNU General Public License for more details.
23 * You should have received a copy of the GNU General Public License
24 * along with this program; if not, write to the Free Software
25 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
26 *****************************************************************************/
39 #include <vlc_common.h>
40 #include <vlc_modules.h>
42 #include "config/configuration.h"
43 #include "vlc_arrays.h"
44 #include "modules/modules.h"
47 * Checks whether a module implements a capability.
50 * \param cap the capability to check
51 * \return TRUE if the module have the capability
53 bool module_provides( const module_t *m, const char *cap )
55 if (unlikely(m->psz_capability == NULL))
57 return !strcmp( m->psz_capability, cap );
61 * Get the internal name of a module
64 * \return the module name
66 const char *module_get_object( const module_t *m )
68 if (unlikely(m->i_shortcuts == 0))
70 return m->pp_shortcuts[0];
74 * Get the human-friendly name of a module.
77 * \param long_name TRUE to have the long name of the module
78 * \return the short or long name of the module
80 const char *module_get_name( const module_t *m, bool long_name )
82 if( long_name && ( m->psz_longname != NULL) )
83 return m->psz_longname;
85 if (m->psz_shortname != NULL)
86 return m->psz_shortname;
87 return module_get_object (m);
91 * Get the help for a module
96 const char *module_get_help( const module_t *m )
102 * Get the capability for a module
104 * \param m the module
105 * return the capability
107 const char *module_get_capability( const module_t *m )
109 return m->psz_capability;
113 * Get the score for a module
115 * \param m the module
116 * return the score for the capability
118 int module_get_score( const module_t *m )
124 * Translate a string using the module's text domain
126 * \param m the module
127 * \param str the American English ASCII string to localize
128 * \return the gettext-translated string
130 const char *module_gettext (const module_t *m, const char *str)
132 if (m->parent != NULL)
134 if (unlikely(str == NULL || *str == '\0'))
137 const char *domain = m->domain;
138 return dgettext ((domain != NULL) ? domain : PACKAGE_NAME, str);
146 int module_start (vlc_object_t *obj, const module_t *m)
148 int (*activate) (vlc_object_t *) = m->pf_activate;
150 return (activate != NULL) ? activate (obj) : VLC_SUCCESS;
154 void module_stop (vlc_object_t *obj, const module_t *m)
156 void (*deactivate) (vlc_object_t *) = m->pf_deactivate;
158 if (deactivate != NULL)
162 typedef struct module_list_t
169 static int modulecmp (const void *a, const void *b)
171 const module_list_t *la = a, *lb = b;
172 /* Note that qsort() uses _ascending_ order,
173 * so the smallest module is the one with the biggest score. */
174 return lb->i_score - la->i_score;
177 #undef vlc_module_load
179 * Finds and instantiates the best module of a certain type.
180 * All candidates modules having the specified capability and name will be
181 * sorted in decreasing order of priority. Then the probe callback will be
182 * invoked for each module, until it succeeds (returns 0), or all candidate
183 * module failed to initialize.
185 * The probe callback first parameter is the address of the module entry point.
186 * Further parameters are passed as an argument list; it corresponds to the
187 * variable arguments passed to this function. This scheme is meant to
188 * support arbitrary prototypes for the module entry point.
190 * \param p_this VLC object
191 * \param psz_capability capability, i.e. class of module
192 * \param psz_name name name of the module asked, if any
193 * \param b_strict if true, do not fallback to plugin with a different name
194 * but the same capability
195 * \param probe module probe callback
196 * \return the module or NULL in case of a failure
198 module_t *vlc_module_load(vlc_object_t *p_this, const char *psz_capability,
199 const char *psz_name, bool b_strict,
200 vlc_activate_t probe, ...)
202 stats_TimerStart( p_this, "module_need()", STATS_TIMER_MODULE_NEED );
204 module_list_t *p_list;
207 char *psz_shortcuts = NULL, *psz_var = NULL, *psz_alias = NULL;
208 bool b_force_backup = p_this->b_force;
210 /* Deal with variables */
211 if( psz_name && psz_name[0] == '$' )
213 psz_name = psz_var = var_CreateGetString( p_this, psz_name + 1 );
216 /* Count how many different shortcuts were asked for */
217 if( psz_name && *psz_name )
219 char *psz_parser, *psz_last_shortcut;
221 /* If the user wants none, give him none. */
222 if( !strcmp( psz_name, "none" ) )
225 stats_TimerStop( p_this, STATS_TIMER_MODULE_NEED );
226 stats_TimerDump( p_this, STATS_TIMER_MODULE_NEED );
227 stats_TimerClean( p_this, STATS_TIMER_MODULE_NEED );
232 psz_parser = psz_shortcuts = psz_last_shortcut = strdup( psz_name );
234 while( ( psz_parser = strchr( psz_parser, ',' ) ) )
238 psz_last_shortcut = ++psz_parser;
241 /* Check if the user wants to override the "strict" mode */
242 if( psz_last_shortcut )
244 if( !strcmp(psz_last_shortcut, "none") )
249 else if( !strcmp(psz_last_shortcut, "any") )
257 /* Sort the modules and test them */
259 module_t **p_all = module_list_get (&count);
260 p_list = malloc( count * sizeof( module_list_t ) );
262 /* Parse the module list for capabilities and probe each of them */
264 for (size_t i = 0; (p_module = p_all[i]) != NULL; i++)
266 int i_shortcut_bonus = 0;
268 /* Test that this module can do what we need */
269 if( !module_provides( p_module, psz_capability ) )
272 /* If we required a shortcut, check this plugin provides it. */
273 if( i_shortcuts > 0 )
275 const char *name = psz_shortcuts;
277 for( unsigned i_short = i_shortcuts; i_short > 0; i_short-- )
279 for( unsigned i = 0; i < p_module->i_shortcuts; i++ )
282 if( ( c = strchr( name, '@' ) )
283 ? !strncasecmp( name, p_module->pp_shortcuts[i],
285 : !strcasecmp( name, p_module->pp_shortcuts[i] ) )
290 i_shortcut_bonus = i_short * 10000;
295 /* Go to the next shortcut... This is so lame! */
296 name += strlen( name ) + 1;
299 /* If we are in "strict" mode and we couldn't
300 * find the module in the list of provided shortcuts,
301 * then kick the bastard out of here!!! */
306 /* Trash <= 0 scored plugins (they can only be selected by shortcut) */
307 if( p_module->i_score <= 0 )
311 /* Store this new module */
312 p_list[count].p_module = p_module;
313 p_list[count].i_score = p_module->i_score + i_shortcut_bonus;
314 p_list[count].b_force = i_shortcut_bonus && b_strict;
318 /* We can release the list, interesting modules are held */
319 module_list_free (p_all);
321 /* Sort candidates by descending score */
322 qsort (p_list, count, sizeof (p_list[0]), modulecmp);
323 msg_Dbg( p_this, "looking for %s module: %zu candidate%s", psz_capability,
324 count, count == 1 ? "" : "s" );
326 /* Parse the linked list and use the first successful module */
329 va_start(args, probe);
332 for (size_t i = 0; (i < count) && (p_module == NULL); i++)
334 module_t *p_cand = p_list[i].p_module;
336 if (module_Map (p_this, p_cand))
338 p_this->b_force = p_list[i].b_force;
342 if (likely(p_cand->pf_activate != NULL))
347 ret = probe(p_cand->pf_activate, ap);
361 /* good module, but aborted */
364 default: /* bad module */
371 p_this->b_force = b_force_backup;
373 if( p_module != NULL )
375 msg_Dbg( p_this, "using %s module \"%s\"",
376 psz_capability, module_get_object(p_module) );
377 vlc_object_set_name( p_this, psz_alias ? psz_alias
378 : module_get_object(p_module) );
380 else if( count == 0 )
381 msg_Dbg( p_this, "no %s module matched \"%s\"",
382 psz_capability, (psz_name && *psz_name) ? psz_name : "any" );
384 msg_Dbg( p_this, "no %s module matching \"%s\" could be loaded",
385 psz_capability, (psz_name && *psz_name) ? psz_name : "any" );
387 free( psz_shortcuts );
390 stats_TimerStop( p_this, STATS_TIMER_MODULE_NEED );
391 stats_TimerDump( p_this, STATS_TIMER_MODULE_NEED );
392 stats_TimerClean( p_this, STATS_TIMER_MODULE_NEED );
394 /* Don't forget that the module is still locked */
400 * Deinstantiates a module.
401 * \param module the module pointer as returned by vlc_module_load()
402 * \param deinit deactivation callback
404 void vlc_module_unload(module_t *module, vlc_deactivate_t deinit, ...)
406 if (module->pf_deactivate != NULL)
410 va_start(ap, deinit);
411 deinit(module->pf_deactivate, ap);
417 static int generic_start(void *func, va_list ap)
419 vlc_object_t *obj = va_arg(ap, vlc_object_t *);
420 int (*activate)(vlc_object_t *) = func;
422 return activate(obj);
425 static void generic_stop(void *func, va_list ap)
427 vlc_object_t *obj = va_arg(ap, vlc_object_t *);
428 void (*deactivate)(vlc_object_t *) = func;
434 module_t *module_need(vlc_object_t *obj, const char *cap, const char *name,
437 return vlc_module_load(obj, cap, name, strict, generic_start, obj);
441 void module_unneed(vlc_object_t *obj, module_t *module)
443 msg_Dbg(obj, "removing module \"%s\"", module_get_object(module));
444 vlc_module_unload(module, generic_stop, obj);
448 * Get a pointer to a module_t given it's name.
450 * \param name the name of the module
451 * \return a pointer to the module or NULL in case of a failure
453 module_t *module_find (const char *name)
455 module_t **list, *module;
457 assert (name != NULL);
458 list = module_list_get (NULL);
462 for (size_t i = 0; (module = list[i]) != NULL; i++)
464 if (unlikely(module->i_shortcuts == 0))
466 if (!strcmp (module->pp_shortcuts[0], name))
469 module_list_free (list);
474 * Tell if a module exists and release it in thic case
476 * \param psz_name th name of the module
477 * \return TRUE if the module exists
479 bool module_exists (const char * psz_name)
481 return module_find (psz_name) != NULL;
485 * Get a pointer to a module_t that matches a shortcut.
486 * This is a temporary hack for SD. Do not re-use (generally multiple modules
487 * can have the same shortcut, so this is *broken* - use module_need()!).
489 * \param psz_shortcut shortcut of the module
490 * \param psz_cap capability of the module
491 * \return a pointer to the module or NULL in case of a failure
493 module_t *module_find_by_shortcut (const char *psz_shortcut)
495 module_t **list, *module;
497 list = module_list_get (NULL);
501 for (size_t i = 0; (module = list[i]) != NULL; i++)
502 for (size_t j = 0; j < module->i_shortcuts; j++)
503 if (!strcmp (module->pp_shortcuts[j], psz_shortcut))
506 module_list_free (list);
511 * Get the configuration of a module
513 * \param module the module
514 * \param psize the size of the configuration returned
515 * \return the configuration as an array
517 module_config_t *module_config_get( const module_t *module, unsigned *restrict psize )
520 unsigned size = module->confsize;
521 module_config_t *config = malloc( size * sizeof( *config ) );
523 assert( psize != NULL );
529 for( i = 0, j = 0; i < size; i++ )
531 const module_config_t *item = module->p_config + i;
532 if( item->b_internal /* internal option */
533 || item->b_removed /* removed option */ )
536 memcpy( config + j, item, sizeof( *config ) );
545 * Release the configuration
547 * \param the configuration
550 void module_config_free( module_config_t *config )