VLC  4.0.0-dev
vlc_modules.h
Go to the documentation of this file.
1 /*****************************************************************************
2  * vlc_modules.h : Module descriptor and load functions
3  *****************************************************************************
4  * Copyright (C) 2001-2011 VLC authors and VideoLAN
5  *
6  * Authors: Samuel Hocevar <sam@zoy.org>
7  *
8  * This program is free software; you can redistribute it and/or modify it
9  * under the terms of the GNU Lesser General Public License as published by
10  * the Free Software Foundation; either version 2.1 of the License, or
11  * (at your option) any later version.
12  *
13  * This program is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16  * GNU Lesser General Public License for more details.
17  *
18  * You should have received a copy of the GNU Lesser General Public License
19  * along with this program; if not, write to the Free Software Foundation,
20  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
21  *****************************************************************************/
22 
23 #ifndef VLC_MODULES_H
24 #define VLC_MODULES_H 1
25 
26 /**
27  * \file
28  * This file defines functions for modules in vlc
29  */
30 
31 typedef int (*vlc_activate_t)(void *func, bool forced, va_list args);
32 struct vlc_logger;
33 
34 /*****************************************************************************
35  * Exported functions.
36  *****************************************************************************/
37 
38 /**
39  * Finds and instantiates the best module of a certain type.
40  * All candidates modules having the specified capability and name will be
41  * sorted in decreasing order of priority. Then the probe callback will be
42  * invoked for each module, until it succeeds (returns 0), or all candidate
43  * module failed to initialize.
44  *
45  * The probe callback first parameter is the address of the module entry point.
46  * Further parameters are passed as an argument list; it corresponds to the
47  * variable arguments passed to this function. This scheme is meant to
48  * support arbitrary prototypes for the module entry point.
49  *
50  * \param log logger for debugging (or NULL to ignore)
51  * \param capability capability, i.e. class of module
52  * \param name name of the module asked, if any
53  * \param strict if true, do not fallback to plugin with a different name
54  * but the same capability
55  * \param probe module probe callback
56  * \return the module or NULL in case of a failure
57  */
58 VLC_API module_t *vlc_module_load(struct vlc_logger *log, const char *cap,
59  const char *name, bool strict,
60  vlc_activate_t probe, ... ) VLC_USED;
61 #ifndef __cplusplus
62 #define vlc_module_load(ctx, cap, name, strict, ...) \
63  _Generic ((ctx), \
64  struct vlc_logger *: \
65  vlc_module_load((void *)(ctx), cap, name, strict, __VA_ARGS__), \
66  void *: \
67  vlc_module_load((void *)(ctx), cap, name, strict, __VA_ARGS__), \
68  default: \
69  vlc_module_load(vlc_object_logger((vlc_object_t *)(ctx)), cap, \
70  name, strict, __VA_ARGS__))
71 #endif
72 
73 VLC_API module_t * module_need( vlc_object_t *, const char *, const char *, bool ) VLC_USED;
74 #define module_need(a,b,c,d) module_need(VLC_OBJECT(a),b,c,d)
75 
76 VLC_USED
77 static inline module_t *module_need_var(vlc_object_t *obj, const char *cap,
78  const char *varname)
79 {
80  char *list = var_InheritString(obj, varname);
81  module_t *m = module_need(obj, cap, list, false);
82 
83  free(list);
84  return m;
85 }
86 #define module_need_var(a,b,c) module_need_var(VLC_OBJECT(a),b,c)
87 
89 #define module_unneed(a,b) module_unneed(VLC_OBJECT(a),b)
90 
91 /**
92  * Checks if a module exists.
93  *
94  * \param name name of the module
95  * \retval true if the module exists
96  * \retval false if the module does not exist (in the running installation)
97  */
98 VLC_API bool module_exists(const char *) VLC_USED;
99 
100 /**
101  * Get a pointer to a module_t given it's name.
102  *
103  * \param name the name of the module
104  * \return a pointer to the module or NULL in case of a failure
105  */
106 VLC_API module_t *module_find(const char *name) VLC_USED;
107 
108 /**
109  * Gets the table of module configuration items.
110  *
111  * \note Use module_config_free() to release the allocated memory.
112  *
113  * \param module the module
114  * \param psize the size of the configuration returned
115  * \return the configuration as an array
116  */
118  unsigned *restrict psize) VLC_USED;
119 
120 /**
121  * Releases the configuration items table.
122  *
123  * \param tab base address of a table returned by module_config_get()
124  */
126 
129 
130 /**
131  * Checks whether a module implements a capability.
132  *
133  * \param m the module
134  * \param cap the capability to check
135  * \retval true if the module has the capability
136  * \retval false if the module has another capability
137  */
138 VLC_API bool module_provides(const module_t *m, const char *cap);
139 
140 /**
141  * Gets the internal name of a module.
142  *
143  * \param m the module
144  * \return the module name
145  */
146 VLC_API const char * module_get_object(const module_t *m) VLC_USED;
147 
148 /**
149  * Gets the human-friendly name of a module.
150  *
151  * \param m the module
152  * \param longname TRUE to have the long name of the module
153  * \return the short or long name of the module
154  */
155 VLC_API const char *module_get_name(const module_t *m, bool longname) VLC_USED;
156 #define module_GetLongName( m ) module_get_name( m, true )
158 /**
159  * Gets the help text for a module.
160  *
161  * \param m the module
162  * \return the help
163  */
164 VLC_API const char *module_get_help(const module_t *m) VLC_USED;
165 
166 /**
167  * Gets the capability string of a module.
168  *
169  * \param m the module
170  * \return the capability, or "none" if unspecified
171  */
172 VLC_API const char *module_get_capability(const module_t *m) VLC_USED;
173 
174 /**
175  * Gets the precedence of a module.
176  *
177  * \param m the module
178  * return the score for the capability
179  */
181 
182 /**
183  * Translates a string using the module's text domain
184  *
185  * \param m the module
186  * \param s the American English ASCII string to localize
187  * \return the gettext-translated string
188  */
189 VLC_API const char *module_gettext(const module_t *m, const char *s) VLC_USED;
190 
191 VLC_USED static inline module_t *module_get_main (void)
192 {
193  return module_find ("core");
194 }
195 #define module_get_main(a) module_get_main()
197 VLC_USED static inline bool module_is_main( const module_t * p_module )
198 {
199  return !strcmp( module_get_object( p_module ), "core" );
200 }
201 
202 #endif /* VLC_MODULES_H */
const char * module_gettext(const module_t *m, const char *s)
Translates a string using the module&#39;s text domain.
Definition: modules.c:82
module_config_t ** list
Definition: core.c:401
void module_list_free(module_t **)
Frees the flat list of VLC modules.
Definition: bank.c:754
static char * var_InheritString(vlc_object_t *obj, const char *name)
Definition: vlc_variables.h:705
Configuration item.
Definition: vlc_configuration.h:76
#define module_unneed(a, b)
Definition: vlc_modules.h:90
const char * module_get_name(const module_t *m, bool longname)
Gets the human-friendly name of a module.
Definition: modules.c:57
Internal module descriptor.
Definition: modules.h:75
int module_get_score(const module_t *m)
Gets the precedence of a module.
Definition: modules.c:77
bool module_provides(const module_t *m, const char *cap)
Checks whether a module implements a capability.
Definition: modules.c:45
void module_config_free(module_config_t *tab)
Releases the configuration items table.
Definition: modules.c:343
#define module_need_var(a, b, c)
Definition: vlc_modules.h:87
static bool module_is_main(const module_t *p_module)
Definition: vlc_modules.h:198
module_t ** module_list_get(size_t *n)
Gets the flat list of VLC modules.
Definition: bank.c:765
Definition: messages.c:54
#define VLC_API
Definition: fourcc_gen.c:31
const char * module_get_capability(const module_t *m)
Gets the capability string of a module.
Definition: modules.c:72
#define module_get_main(a)
Definition: vlc_modules.h:196
bool module_exists(const char *)
Checks if a module exists.
Definition: modules.c:302
#define module_need(a, b, c, d)
Definition: vlc_modules.h:75
module_config_t * module_config_get(const module_t *module, unsigned *restrict psize)
Gets the table of module configuration items.
Definition: modules.c:307
module_t * module_find(const char *name)
Get a pointer to a module_t given it&#39;s name.
Definition: modules.c:279
const char * module_get_help(const module_t *m)
Gets the help text for a module.
Definition: modules.c:67
int(* vlc_activate_t)(void *func, bool forced, va_list args)
Definition: vlc_modules.h:32
#define vlc_module_load(ctx, cap, name, strict,...)
Definition: vlc_modules.h:63
VLC object common members.
Definition: vlc_objects.h:43
#define VLC_USED
Definition: fourcc_gen.c:32
const char * module_get_object(const module_t *m)
Gets the internal name of a module.
Definition: modules.c:50