src/modules/modules.h

   1 /*****************************************************************************
   2  * modules.h : Module management functions.
   3  *****************************************************************************
   4  * Copyright (C) 2001-2016 VLC authors and VideoLAN
   5  * $Id$
   6  *
   7  * Authors: Samuel Hocevar <sam@zoy.org>
   8  *
   9  * This program is free software; you can redistribute it and/or modify it
  10  * under the terms of the GNU Lesser General Public License as published by
  11  * the Free Software Foundation; either version 2.1 of the License, or
  12  * (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  17  * GNU Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public License
  20  * along with this program; if not, write to the Free Software Foundation,
  21  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  22  *****************************************************************************/
  23
  24 #ifndef LIBVLC_MODULES_H
  25 # define LIBVLC_MODULES_H 1
  26
  27 # include <stdatomic.h>
  28
  29 /** VLC plugin */
  30 typedef struct vlc_plugin_t
  31 {
  32     struct vlc_plugin_t *next;
  33     module_t *module;
  34     unsigned modules_count;
  35
  36     const char *textdomain; /**< gettext domain (or NULL) */
  37
  38     /**
  39      * Variables set by the module to store its config options
  40      */
  41     struct
  42     {
  43         module_config_t *items; /**< Table of configuration parameters */
  44         size_t size; /**< Size of items table */
  45         size_t count; /**< Number of configuration items */
  46         size_t booleans; /**< Number of booleal config items */
  47     } conf;
  48
  49 #ifdef HAVE_DYNAMIC_PLUGINS
  50     bool unloadable; /**< Whether the plug-in can be unloaded safely */
  51     atomic_uintptr_t handle; /**< Run-time linker handle (or nul) */
  52     char *abspath; /**< Absolute path */
  53
  54     char *path; /**< Relative path (within plug-in directory) */
  55     int64_t mtime; /**< Last modification time */
  56     uint64_t size; /**< File size */
  57 #endif
  58 } vlc_plugin_t;
  59
  60 /**
  61  * List of all plug-ins.
  62  */
  63 extern struct vlc_plugin_t *vlc_plugins;
  64
  65 #define MODULE_SHORTCUT_MAX 20
  66
  67 /** Plugin entry point prototype */
  68 typedef int (*vlc_plugin_cb) (int (*)(void *, void *, int, ...), void *);
  69
  70 /** Core module */
  71 int vlc_entry__core (int (*)(void *, void *, int, ...), void *);
  72
  73 /**
  74  * Internal module descriptor
  75  */
  76 struct module_t
  77 {
  78     vlc_plugin_t *plugin; /**< Plug-in/library containing the module */
  79     module_t   *next;
  80
  81     /** Shortcuts to the module */
  82     unsigned    i_shortcuts;
  83     const char **pp_shortcuts;
  84
  85     /*
  86      * Variables set by the module to identify itself
  87      */
  88     const char *psz_shortname;                              /**< Module name */
  89     const char *psz_longname;                   /**< Module descriptive name */
  90     const char *psz_help;        /**< Long help string for "special" modules */
  91
  92     const char *psz_capability;                              /**< Capability */
  93     int      i_score;                          /**< Score for the capability */
  94
  95     /* Callbacks */
  96     const char *activate_name;
  97     const char *deactivate_name;
  98     void *pf_activate;
  99     void *pf_deactivate;
 100 };
 101
 102 vlc_plugin_t *vlc_plugin_create(void);
 103 void vlc_plugin_destroy(vlc_plugin_t *);
 104 module_t *vlc_module_create(vlc_plugin_t *);
 105 void vlc_module_destroy (module_t *);
 106
 107 vlc_plugin_t *vlc_plugin_describe(vlc_plugin_cb);
 108 int vlc_plugin_resolve(vlc_plugin_t *, vlc_plugin_cb);
 109
 110 void module_InitBank (void);
 111 void module_LoadPlugins(vlc_object_t *);
 112 #define module_LoadPlugins(a) module_LoadPlugins(VLC_OBJECT(a))
 113 void module_EndBank (bool);
 114 int module_Map(vlc_object_t *, vlc_plugin_t *);
 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 */