VLC  4.0.0-dev
modules.h
Go to the documentation of this file.
1 /*****************************************************************************
2  * modules.h : Module management functions.
3  *****************************************************************************
4  * Copyright (C) 2001-2016 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 LIBVLC_MODULES_H
24 # define LIBVLC_MODULES_H 1
25 
26 # include <stdatomic.h>
27 
28 /** VLC plugin */
29 typedef struct vlc_plugin_t
30 {
31  struct vlc_plugin_t *next;
33  unsigned modules_count;
34 
35  const char *textdomain; /**< gettext domain (or NULL) */
36 
37  /**
38  * Variables set by the module to store its config options
39  */
40  struct
41  {
42  module_config_t *items; /**< Table of configuration parameters */
43  size_t size; /**< Size of items table */
44  size_t count; /**< Number of configuration items */
45  size_t booleans; /**< Number of booleal config items */
46  } conf;
47 
48 #ifdef HAVE_DYNAMIC_PLUGINS
49  bool unloadable; /**< Whether the plug-in can be unloaded safely */
50  atomic_uintptr_t handle; /**< Run-time linker handle (or nul) */
51  char *abspath; /**< Absolute path */
52 
53  char *path; /**< Relative path (within plug-in directory) */
54  int64_t mtime; /**< Last modification time */
55  uint64_t size; /**< File size */
56 #endif
57 } vlc_plugin_t;
58 
59 /**
60  * List of all plug-ins.
61  */
62 extern struct vlc_plugin_t *vlc_plugins;
63 
64 #define MODULE_SHORTCUT_MAX 20
65 
66 /** Plugin entry point prototype */
67 typedef int (*vlc_plugin_cb) (int (*)(void *, void *, int, ...), void *);
68 
69 /** Core module */
70 int vlc_entry__core (int (*)(void *, void *, int, ...), void *);
71 
72 /**
73  * Internal module descriptor
74  */
75 struct module_t
76 {
77  vlc_plugin_t *plugin; /**< Plug-in/library containing the module */
79 
80  /** Shortcuts to the module */
81  unsigned i_shortcuts;
82  const char **pp_shortcuts;
83 
84  /*
85  * Variables set by the module to identify itself
86  */
87  const char *psz_shortname; /**< Module name */
88  const char *psz_longname; /**< Module descriptive name */
89  const char *psz_help; /**< Long help string for "special" modules */
90 
91  const char *psz_capability; /**< Capability */
92  int i_score; /**< Score for the capability */
93 
94  /* Callbacks */
95  const char *activate_name;
96  const char *deactivate_name;
97  void *pf_activate;
98  void (*deactivate)(vlc_object_t *);
99 };
100 
105 
108 
109 void module_InitBank (void);
111 #define module_LoadPlugins(a) module_LoadPlugins(VLC_OBJECT(a))
112 void module_EndBank (bool);
113 int module_Map(struct vlc_logger *, vlc_plugin_t *);
114 void *module_Symbol(struct vlc_logger *, vlc_plugin_t *, const char *name);
115 
116 ssize_t module_list_cap (module_t ***, const char *);
117 
118 int vlc_bindtextdomain (const char *);
119 
120 /* Low-level OS-dependent handler */
121 
122 /**
123  * Loads a dynamically linked library.
124  *
125  * \param path library file path
126  * \param lazy whether to resolve the symbols lazily
127  * \return a module handle on success, or NULL on error.
128  */
129 void *vlc_dlopen(const char *path, bool) VLC_USED;
130 
131 /**
132  * Unloads a dynamic library.
133  *
134  * This function unloads a previously opened dynamically linked library
135  * using a system dependent method.
136  * \param handle handle of the library
137  * \retval 0 on success
138  * \retval -1 on error (none are defined though)
139  */
140 int vlc_dlclose(void *);
141 
142 /**
143  * Looks up a symbol from a dynamically loaded library
144  *
145  * This function looks for a named symbol within a loaded library.
146  *
147  * \param handle handle to the library
148  * \param name function name
149  * \return the address of the symbol on success, or NULL on error
150  *
151  * \note If the symbol address is NULL, errors cannot be detected. However,
152  * normal symbols such as function or global variables cannot have NULL as
153  * their address.
154  */
155 void *vlc_dlsym(void *handle, const char *) VLC_USED;
156 
157 /**
158  * Formats an error message for vlc_dlopen() or vlc_dlsym().
159  *
160  * \return a heap-allocated nul-terminated error string, or NULL.
161  */
162 char *vlc_dlerror(void) VLC_USED;
163 
164 /* Plugins cache */
165 vlc_plugin_t *vlc_cache_load(vlc_object_t *, const char *, block_t **);
166 vlc_plugin_t *vlc_cache_lookup(vlc_plugin_t **, const char *relpath);
167 
168 void CacheSave(vlc_object_t *, const char *, vlc_plugin_t *const *, size_t);
169 
170 #endif /* !LIBVLC_MODULES_H */
int vlc_entry__core(int(*)(void *, void *, int,...), void *)
Core module.
Definition: libvlc-module.c:1565
VLC plugin.
Definition: modules.h:29
void vlc_module_destroy(module_t *)
Destroys a module.
Definition: entry.c:82
void * module_Symbol(struct vlc_logger *, vlc_plugin_t *, const char *name)
Definition: bank.c:631
int vlc_plugin_resolve(vlc_plugin_t *, vlc_plugin_cb)
Definition: entry.c:581
size_t size
Size of items table.
Definition: modules.h:43
int(* vlc_plugin_cb)(int(*)(void *, void *, int,...), void *)
Plugin entry point prototype.
Definition: modules.h:67
Configuration item.
Definition: vlc_configuration.h:76
vlc_plugin_t * vlc_plugin_describe(vlc_plugin_cb)
Runs a plug-in descriptor.
Definition: entry.c:443
const char * textdomain
gettext domain (or NULL)
Definition: modules.h:35
const char * psz_capability
Capability.
Definition: modules.h:91
void vlc_plugin_destroy(vlc_plugin_t *)
Destroys a plug-in.
Definition: entry.c:123
Internal module descriptor.
Definition: modules.h:75
char * vlc_dlerror(void) VLC_USED
Formats an error message for vlc_dlopen() or vlc_dlsym().
Definition: plugin.c:65
const char * psz_shortname
Module name.
Definition: modules.h:87
module_t * next
Definition: modules.h:78
int vlc_bindtextdomain(const char *)
Definition: textdomain.c:33
#define module_LoadPlugins(a)
Definition: modules.h:111
const char * deactivate_name
Definition: modules.h:96
struct vlc_plugin_t::@102 conf
Variables set by the module to store its config options.
unsigned modules_count
Definition: modules.h:33
module_t * module
Definition: modules.h:32
void * vlc_dlsym(void *handle, const char *) VLC_USED
Looks up a symbol from a dynamically loaded library.
Definition: plugin.c:57
struct vlc_plugin_t vlc_plugin_t
VLC plugin.
size_t count
Number of configuration items.
Definition: modules.h:44
vlc_plugin_t * plugin
Plug-in/library containing the module.
Definition: modules.h:77
vlc_plugin_t * vlc_plugin_create(void)
Definition: entry.c:94
const char name[16]
Definition: httpd.c:1266
const char ** pp_shortcuts
Definition: modules.h:82
const char * activate_name
Definition: modules.h:95
Definition: messages.c:54
void module_InitBank(void)
Init bank.
Definition: bank.c:645
unsigned i_shortcuts
Shortcuts to the module.
Definition: modules.h:81
vlc_plugin_t * vlc_cache_lookup(vlc_plugin_t **, const char *relpath)
void module_EndBank(bool)
Unloads all unused plugin modules and empties the module bank in case of success. ...
Definition: bank.c:677
void CacheSave(vlc_object_t *, const char *, vlc_plugin_t *const *, size_t)
Definition: vlc_block.h:117
void * vlc_dlopen(const char *path, bool) VLC_USED
Loads a dynamically linked library.
Definition: plugin.c:40
module_config_t * items
Table of configuration parameters.
Definition: modules.h:42
vlc_plugin_t * vlc_cache_load(vlc_object_t *, const char *, block_t **)
ssize_t module_list_cap(module_t ***, const char *)
int module_Map(struct vlc_logger *, vlc_plugin_t *)
Definition: bank.c:620
int i_score
Score for the capability.
Definition: modules.h:92
VLC object common members.
Definition: vlc_objects.h:43
void * pf_activate
Definition: modules.h:97
size_t booleans
Number of booleal config items.
Definition: modules.h:45
struct vlc_plugin_t * next
Definition: modules.h:31
const char * psz_help
Long help string for "special" modules.
Definition: modules.h:89
#define VLC_USED
Definition: fourcc_gen.c:32
const char * psz_longname
Module descriptive name.
Definition: modules.h:88
int vlc_dlclose(void *)
Unloads a dynamic library.
Definition: plugin.c:52
module_t * vlc_module_create(vlc_plugin_t *)
Definition: entry.c:40
struct vlc_plugin_t * vlc_plugins
List of all plug-ins.
Definition: bank.c:102