mirror of
https://code.videolan.org/videolan/vlc
synced 2024-09-04 09:11:33 +02:00
220 lines
7.4 KiB
C
220 lines
7.4 KiB
C
/*****************************************************************************
|
|
* vlc_modules.h : Module descriptor and load functions
|
|
*****************************************************************************
|
|
* Copyright (C) 2001-2011 VLC authors and VideoLAN
|
|
*
|
|
* Authors: Samuel Hocevar <sam@zoy.org>
|
|
*
|
|
* This program is free software; you can redistribute it and/or modify it
|
|
* under the terms of the GNU Lesser General Public License as published by
|
|
* the Free Software Foundation; either version 2.1 of the License, or
|
|
* (at your option) any later version.
|
|
*
|
|
* This program is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
* GNU Lesser General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU Lesser General Public License
|
|
* along with this program; if not, write to the Free Software Foundation,
|
|
* Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
|
|
*****************************************************************************/
|
|
|
|
#ifndef VLC_MODULES_H
|
|
#define VLC_MODULES_H 1
|
|
|
|
/**
|
|
* \file
|
|
* This file defines functions for modules in vlc
|
|
*/
|
|
|
|
typedef int (*vlc_activate_t)(void *func, bool forced, va_list args);
|
|
typedef void (*vlc_deactivate_t)(void *func, va_list args);
|
|
struct vlc_logger;
|
|
|
|
/*****************************************************************************
|
|
* Exported functions.
|
|
*****************************************************************************/
|
|
|
|
/**
|
|
* Finds and instantiates the best module of a certain type.
|
|
* All candidates modules having the specified capability and name will be
|
|
* sorted in decreasing order of priority. Then the probe callback will be
|
|
* invoked for each module, until it succeeds (returns 0), or all candidate
|
|
* module failed to initialize.
|
|
*
|
|
* The probe callback first parameter is the address of the module entry point.
|
|
* Further parameters are passed as an argument list; it corresponds to the
|
|
* variable arguments passed to this function. This scheme is meant to
|
|
* support arbitrary prototypes for the module entry point.
|
|
*
|
|
* \param log logger for debugging (or NULL to ignore)
|
|
* \param capability capability, i.e. class of module
|
|
* \param name name of the module asked, if any
|
|
* \param strict if true, do not fallback to plugin with a different name
|
|
* but the same capability
|
|
* \param probe module probe callback
|
|
* \return the module or NULL in case of a failure
|
|
*/
|
|
VLC_API module_t *vlc_module_load(struct vlc_logger *log, const char *cap,
|
|
const char *name, bool strict,
|
|
vlc_activate_t probe, ... ) VLC_USED;
|
|
#ifndef __cplusplus
|
|
#define vlc_module_load(ctx, cap, name, strict, ...) \
|
|
_Generic ((ctx), \
|
|
struct vlc_logger *: \
|
|
vlc_module_load((void *)(ctx), cap, name, strict, __VA_ARGS__), \
|
|
void *: \
|
|
vlc_module_load((void *)(ctx), cap, name, strict, __VA_ARGS__), \
|
|
default: \
|
|
vlc_module_load(vlc_object_logger((vlc_object_t *)(ctx)), cap, \
|
|
name, strict, __VA_ARGS__))
|
|
#endif
|
|
|
|
/**
|
|
* Deinstantiates a module.
|
|
*
|
|
* This is an inconvenience wrapper for deactivating a module if the module
|
|
* capability/type expects it. In that fashion, it is paired with
|
|
* vlc_module_load(). It is rather inconvenient however, as it requires
|
|
* variable arguments for no good reasons, and inhibits type safety.
|
|
*
|
|
* In practice, it is easier to treat vlc_module_load() as an object "factory",
|
|
* and define a type-safe custom callback for object deletion.
|
|
*
|
|
* \param module the module pointer as returned by vlc_module_load()
|
|
* \param deinit deactivation callback
|
|
*/
|
|
VLC_API void vlc_module_unload(module_t *, vlc_deactivate_t deinit, ... );
|
|
|
|
VLC_API module_t * module_need( vlc_object_t *, const char *, const char *, bool ) VLC_USED;
|
|
#define module_need(a,b,c,d) module_need(VLC_OBJECT(a),b,c,d)
|
|
|
|
VLC_USED
|
|
static inline module_t *module_need_var(vlc_object_t *obj, const char *cap,
|
|
const char *varname)
|
|
{
|
|
char *list = var_InheritString(obj, varname);
|
|
module_t *m = module_need(obj, cap, list, false);
|
|
|
|
free(list);
|
|
return m;
|
|
}
|
|
#define module_need_var(a,b,c) module_need_var(VLC_OBJECT(a),b,c)
|
|
|
|
VLC_API void module_unneed( vlc_object_t *, module_t * );
|
|
#define module_unneed(a,b) module_unneed(VLC_OBJECT(a),b)
|
|
|
|
/**
|
|
* Checks if a module exists.
|
|
*
|
|
* \param name name of the module
|
|
* \retval true if the module exists
|
|
* \retval false if the module does not exist (in the running installation)
|
|
*/
|
|
VLC_API bool module_exists(const char *) VLC_USED;
|
|
|
|
/**
|
|
* Get a pointer to a module_t given it's name.
|
|
*
|
|
* \param name the name of the module
|
|
* \return a pointer to the module or NULL in case of a failure
|
|
*/
|
|
VLC_API module_t *module_find(const char *name) VLC_USED;
|
|
|
|
/**
|
|
* Gets the table of module configuration items.
|
|
*
|
|
* \note Use module_config_free() to release the allocated memory.
|
|
*
|
|
* \param module the module
|
|
* \param psize the size of the configuration returned
|
|
* \return the configuration as an array
|
|
*/
|
|
VLC_API module_config_t *module_config_get(const module_t *module,
|
|
unsigned *restrict psize) VLC_USED;
|
|
|
|
/**
|
|
* Releases the configuration items table.
|
|
*
|
|
* \param tab base address of a table returned by module_config_get()
|
|
*/
|
|
VLC_API void module_config_free( module_config_t *tab);
|
|
|
|
VLC_API void module_list_free(module_t **);
|
|
VLC_API module_t ** module_list_get(size_t *n) VLC_USED;
|
|
|
|
/**
|
|
* Checks whether a module implements a capability.
|
|
*
|
|
* \param m the module
|
|
* \param cap the capability to check
|
|
* \retval true if the module has the capability
|
|
* \retval false if the module has another capability
|
|
*/
|
|
VLC_API bool module_provides(const module_t *m, const char *cap);
|
|
|
|
/**
|
|
* Gets the internal name of a module.
|
|
*
|
|
* \param m the module
|
|
* \return the module name
|
|
*/
|
|
VLC_API const char * module_get_object(const module_t *m) VLC_USED;
|
|
|
|
/**
|
|
* Gets the human-friendly name of a module.
|
|
*
|
|
* \param m the module
|
|
* \param longname TRUE to have the long name of the module
|
|
* \return the short or long name of the module
|
|
*/
|
|
VLC_API const char *module_get_name(const module_t *m, bool longname) VLC_USED;
|
|
#define module_GetLongName( m ) module_get_name( m, true )
|
|
|
|
/**
|
|
* Gets the help text for a module.
|
|
*
|
|
* \param m the module
|
|
* \return the help
|
|
*/
|
|
VLC_API const char *module_get_help(const module_t *m) VLC_USED;
|
|
|
|
/**
|
|
* Gets the capability string of a module.
|
|
*
|
|
* \param m the module
|
|
* \return the capability, or "none" if unspecified
|
|
*/
|
|
VLC_API const char *module_get_capability(const module_t *m) VLC_USED;
|
|
|
|
/**
|
|
* Gets the precedence of a module.
|
|
*
|
|
* \param m the module
|
|
* return the score for the capability
|
|
*/
|
|
VLC_API int module_get_score(const module_t *m) VLC_USED;
|
|
|
|
/**
|
|
* Translates a string using the module's text domain
|
|
*
|
|
* \param m the module
|
|
* \param s the American English ASCII string to localize
|
|
* \return the gettext-translated string
|
|
*/
|
|
VLC_API const char *module_gettext(const module_t *m, const char *s) VLC_USED;
|
|
|
|
VLC_USED static inline module_t *module_get_main (void)
|
|
{
|
|
return module_find ("core");
|
|
}
|
|
#define module_get_main(a) module_get_main()
|
|
|
|
VLC_USED static inline bool module_is_main( const module_t * p_module )
|
|
{
|
|
return !strcmp( module_get_object( p_module ), "core" );
|
|
}
|
|
|
|
#endif /* VLC_MODULES_H */
|