VLC 4.0.0-dev
Loading...
Searching...
No Matches
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
31typedef int (*vlc_activate_t)(void *func, bool forced, va_list args);
33
34/*****************************************************************************
35 * Exported functions.
36 *****************************************************************************/
37
38/**
39 * Finds the candidate modules for given criteria.
40 *
41 * All candidates modules having the specified capability and name will be
42 * sorted in decreasing order of priority and returned in a heap-allocated
43 * table.
44 *
45 * \param capability capability, i.e. class of module
46 * \param names string of comma-separated requested module shortcut names,
47 * or NULL for defaults
48 * \param strict whether to exclude modules with no unmatching shortcut names
49 * \param modules storage location for the base address of a sorted table
50 * of candidate modules (NULL on error) [OUT]
51 * \param strict_matches storage location for the count of strictly matched
52 * modules [OUT]
53 * \return number of modules found or a strictly negative value on error
54 */
56ssize_t vlc_module_match(const char *capability, const char *names,
57 bool strict, module_t ***restrict modules,
58 size_t *restrict strict_matches);
59
60/**
61 * Maps a module in memory.
62 *
63 * This function attempts to map a given module in memory, if it is not
64 * already mapped. If it is already mapped, this function does nothing.
65 *
66 * \param log message logger
67 * \param mod module to map
68 *
69 * \return the module activation function on success, NULL on failure
70 */
72void *vlc_module_map(struct vlc_logger *log, module_t *mod);
73
74/**
75 * Finds and instantiates the best module of a certain type.
76 * All candidates modules having the specified capability and name will be
77 * sorted in decreasing order of priority. Then the probe callback will be
78 * invoked for each module, until it succeeds (returns 0), or all candidate
79 * module failed to initialize.
80 *
81 * The probe callback first parameter is the address of the module entry point.
82 * Further parameters are passed as an argument list; it corresponds to the
83 * variable arguments passed to this function. This scheme is meant to
84 * support arbitrary prototypes for the module entry point.
85 *
86 * \param log logger for debugging (or NULL to ignore)
87 * \param cap capability, i.e. class of module
88 * \param name name of the module asked, if any
89 * \param strict if true, do not fallback to plugin with a different name
90 * but the same capability
91 * \param probe module probe callback
92 * \return the module or NULL in case of a failure
93 */
94VLC_API module_t *vlc_module_load(struct vlc_logger *log, const char *cap,
95 const char *name, bool strict,
96 vlc_activate_t probe, ... ) VLC_USED;
97
98VLC_API module_t * module_need( vlc_object_t *, const char *, const char *, bool ) VLC_USED;
99#define module_need(a,b,c,d) module_need(VLC_OBJECT(a),b,c,d)
102static inline module_t *module_need_var(vlc_object_t *obj, const char *cap,
103 const char *varname)
104{
105 char *list = var_InheritString(obj, varname);
106 if (unlikely(list == NULL))
107 return NULL;
108
109 module_t *m = module_need(obj, cap, list, false);
110
111 free(list);
112 return m;
113}
114#define module_need_var(a,b,c) module_need_var(VLC_OBJECT(a),b,c)
117#define module_unneed(a,b) module_unneed(VLC_OBJECT(a),b)
119/**
120 * Get a pointer to a module_t given it's name.
121 *
122 * \param name the name of the module
123 * \return a pointer to the module or NULL in case of a failure
124 */
126
127/**
128 * Checks if a module exists.
129 *
130 * \param name name of the module
131 * \retval true if the module exists
132 * \retval false if the module does not exist (in the running installation)
133 */
134VLC_USED static inline bool module_exists(const char * name)
136 return module_find(name) != NULL;
137}
138
139/**
140 * Gets the table of module configuration items.
141 *
142 * \note Use module_config_free() to release the allocated memory.
143 *
144 * \param module the module
145 * \param psize the size of the configuration returned
146 * \return the configuration as an array
147 */
149 unsigned *restrict psize) VLC_USED;
150
151/**
152 * Releases a configuration items table.
153 *
154 * \param tab base address of a table returned by module_config_get()
155 */
157
158/**
159 * Frees a flat list of VLC modules.
160 *
161 * \param list list obtained by module_list_get()
162 */
164
165/**
166 * Gets the flat list of VLC modules.
167 *
168 * \param n [OUT] pointer to the number of modules
169 * \return table of module pointers (release with module_list_free()),
170 * or NULL in case of error (in that case, *n is zeroed).
171 */
173
174/**
175 * Checks whether a module implements a capability.
176 *
177 * \param m the module
178 * \param cap the capability to check
179 * \retval true if the module has the capability
180 * \retval false if the module has another capability
181 */
182VLC_API bool module_provides(const module_t *m, const char *cap);
183
184/**
185 * Gets the internal name of a module.
186 *
187 * \param m the module
188 * \return the module name
189 */
190VLC_API const char * module_get_object(const module_t *m) VLC_USED;
191
192/**
193 * Gets the human-friendly name of a module.
194 *
195 * \param m the module
196 * \param longname TRUE to have the long name of the module
197 * \return the short or long name of the module
198 */
199VLC_API const char *module_get_name(const module_t *m, bool longname) VLC_USED;
200#define module_GetShortName( m ) module_get_name( m, false )
201#define module_GetLongName( m ) module_get_name( m, true )
203/**
204 * Gets the help text for a module.
205 *
206 * \param m the module
207 * \return the help
208 */
209VLC_API const char *module_get_help(const module_t *m) VLC_USED;
210
211/**
212 * Gets the help HTML for a module.
213 *
214 * \param m the module
215 * \return the help HTML
216 */
217VLC_API const char *module_get_help_html(const module_t *m) VLC_USED;
218
219/**
220 * Gets the capability string of a module.
221 *
222 * \param m the module
223 * \return the capability, or "none" if unspecified
224 */
225VLC_API const char *module_get_capability(const module_t *m) VLC_USED;
226
227/**
228 * Gets the precedence of a module.
229 *
230 * \param m the module
231 * return the score for the capability
232 */
234
235/**
236 * Translates a string using the module's text domain
237 *
238 * \param m the module
239 * \param s the American English ASCII string to localize
240 * \return the gettext-translated string
241 */
242VLC_API const char *module_gettext(const module_t *m, const char *s) VLC_USED;
243
244VLC_USED static inline module_t *module_get_main (void)
246 return module_find ("core");
247}
248
249VLC_USED static inline bool module_is_main( const module_t * p_module )
251 return !strcmp( module_get_object( p_module ), "core" );
252}
253
254#endif /* VLC_MODULES_H */
static struct @101 modules
struct vlc_param ** list
Definition core.c:402
#define VLC_USED
Definition fourcc_gen.c:32
#define VLC_API
Definition fourcc_gen.c:31
#define unlikely(p)
Predicted false condition.
Definition vlc_common.h:246
static char * var_InheritString(vlc_object_t *obj, const char *name)
Definition vlc_variables.h:737
const char name[16]
Definition httpd.c:1298
Configuration item.
Definition vlc_configuration.h:70
Internal module descriptor.
Definition modules.h:76
Definition messages.c:85
VLC object common members.
Definition vlc_objects.h:53
This file is a collection of common definitions and types.
static bool module_exists(const char *name)
Checks if a module exists.
Definition vlc_modules.h:135
module_t * vlc_module_load(struct vlc_logger *log, const char *cap, const char *name, bool strict, vlc_activate_t probe,...)
Finds and instantiates the best module of a certain type.
Definition modules.c:195
void * vlc_module_map(struct vlc_logger *log, module_t *mod)
Maps a module in memory.
Definition modules.c:190
int module_get_score(const module_t *m)
Gets the precedence of a module.
Definition modules.c:82
const char * module_get_help(const module_t *m)
Gets the help text for a module.
Definition modules.c:67
module_config_t * module_config_get(const module_t *module, unsigned *restrict psize)
Gets the table of module configuration items.
Definition modules.c:318
const char * module_get_object(const module_t *m)
Gets the internal name of a module.
Definition modules.c:50
#define module_unneed(a, b)
Definition vlc_modules.h:118
static module_t * module_get_main(void)
Definition vlc_modules.h:245
#define module_need(a, b, c, d)
Definition vlc_modules.h:100
void module_list_free(module_t **)
Frees a flat list of VLC modules.
Definition bank.c:824
static bool module_is_main(const module_t *p_module)
Definition vlc_modules.h:250
const char * module_gettext(const module_t *m, const char *s)
Translates a string using the module's text domain.
Definition modules.c:87
void module_config_free(module_config_t *tab)
Releases a configuration items table.
Definition modules.c:355
const char * module_get_capability(const module_t *m)
Gets the capability string 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
int(* vlc_activate_t)(void *func, bool forced, va_list args)
Definition vlc_modules.h:32
module_t * module_find(const char *name)
Get a pointer to a module_t given it's name.
Definition modules.c:295
module_t ** module_list_get(size_t *n)
Gets the flat list of VLC modules.
Definition bank.c:829
const char * module_get_name(const module_t *m, bool longname)
Gets the human-friendly name of a module.
Definition modules.c:57
ssize_t vlc_module_match(const char *capability, const char *names, bool strict, module_t ***restrict modules, size_t *restrict strict_matches)
Finds the candidate modules for given criteria.
Definition modules.c:110
const char * module_get_help_html(const module_t *m)
Gets the help HTML for a module.
Definition modules.c:72
#define module_need_var(a, b, c)
Definition vlc_modules.h:115