vlc | branch: master | Rémi Denis-Courmont <[email protected]> | Mon Mar 4 21:41:43 2019 +0200| [38d7d2248663c54803cbfdea7f69711c08793a08] | committer: Rémi Denis-Courmont
modules: move documentation to header > http://git.videolan.org/gitweb.cgi/vlc.git/?a=commit;h=38d7d2248663c54803cbfdea7f69711c08793a08 --- include/vlc_modules.h | 137 ++++++++++++++++++++++++++++++++++++++++++++++---- src/modules/modules.c | 75 --------------------------- 2 files changed, 127 insertions(+), 85 deletions(-) diff --git a/include/vlc_modules.h b/include/vlc_modules.h index a39f0485db..d0115a7ede 100644 --- a/include/vlc_modules.h +++ b/include/vlc_modules.h @@ -36,6 +36,26 @@ 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; @@ -51,6 +71,20 @@ VLC_API module_t *vlc_module_load(struct vlc_logger *log, const char *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; @@ -70,23 +104,106 @@ static inline module_t *module_need_var(vlc_object_t *obj, const char *cap, 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; -VLC_API module_t * module_find(const char *) VLC_USED; -VLC_API module_config_t * module_config_get( const module_t *, unsigned * ) VLC_USED; -VLC_API void module_config_free( module_config_t * ); +/** + * 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; -VLC_API bool module_provides( const module_t *m, const char *cap ); -VLC_API const char * module_get_object( const module_t *m ) VLC_USED; -VLC_API const char * module_get_name( const module_t *m, bool long_name ) 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 ) -VLC_API const char * module_get_help( const module_t *m ) VLC_USED; -VLC_API const char * module_get_capability( const module_t *m ) VLC_USED; -VLC_API int module_get_score( const module_t *m ) VLC_USED; -VLC_API const char * module_gettext( const module_t *, const char * ) VLC_USED; + +/** + * 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) { diff --git a/src/modules/modules.c b/src/modules/modules.c index 1d8c9f15ae..caef245ffc 100644 --- a/src/modules/modules.c +++ b/src/modules/modules.c @@ -42,24 +42,11 @@ #include "vlc_arrays.h" #include "modules/modules.h" -/** - * Checks whether a module implements a capability. - * - * \param m the module - * \param cap the capability to check - * \return true if the module has the capability - */ bool module_provides (const module_t *m, const char *cap) { return !strcmp (module_get_capability (m), cap); } -/** - * Get the internal name of a module - * - * \param m the module - * \return the module name - */ const char *module_get_object( const module_t *m ) { if (unlikely(m->i_shortcuts == 0)) @@ -67,13 +54,6 @@ const char *module_get_object( const module_t *m ) return m->pp_shortcuts[0]; } -/** - * Get the human-friendly name of a module. - * - * \param m the module - * \param long_name TRUE to have the long name of the module - * \return the short or long name of the module - */ const char *module_get_name( const module_t *m, bool long_name ) { if( long_name && ( m->psz_longname != NULL) ) @@ -84,46 +64,21 @@ const char *module_get_name( const module_t *m, bool long_name ) return module_get_object (m); } -/** - * Get the help for a module - * - * \param m the module - * \return the help - */ const char *module_get_help( const module_t *m ) { return m->psz_help; } -/** - * Gets the capability of a module - * - * \param m the module - * \return the capability, or "none" if unspecified - */ const char *module_get_capability (const module_t *m) { return (m->psz_capability != NULL) ? m->psz_capability : "none"; } -/** - * Get the score for a module - * - * \param m the module - * return the score for the capability - */ int module_get_score( const module_t *m ) { return m->i_score; } -/** - * Translate a string using the module's text domain - * - * \param m the module - * \param str the American English ASCII string to localize - * \return the gettext-translated string - */ const char *module_gettext (const module_t *m, const char *str) { if (unlikely(str == NULL || *str == '\0')) @@ -280,11 +235,6 @@ done: return module; } -/** - * Deinstantiates a module. - * \param module the module pointer as returned by vlc_module_load() - * \param deinit deactivation callback - */ void vlc_module_unload(module_t *module, vlc_deactivate_t deinit, ...) { if (module->pf_deactivate != NULL) @@ -344,12 +294,6 @@ void module_unneed(vlc_object_t *obj, module_t *module) vlc_objres_clear(obj); } -/** - * 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 - */ module_t *module_find (const char *name) { size_t count; @@ -373,24 +317,11 @@ module_t *module_find (const char *name) return NULL; } -/** - * Tell if a module exists - * - * \param psz_name th name of the module - * \return TRUE if the module exists - */ bool module_exists (const char * psz_name) { return module_find (psz_name) != NULL; } -/** - * Get the configuration of a module - * - * \param module the module - * \param psize the size of the configuration returned - * \return the configuration as an array - */ module_config_t *module_config_get( const module_t *module, unsigned *restrict psize ) { const vlc_plugin_t *plugin = module->plugin; @@ -427,12 +358,6 @@ module_config_t *module_config_get( const module_t *module, unsigned *restrict p return config; } -/** - * Release the configuration - * - * \param the configuration - * \return nothing - */ void module_config_free( module_config_t *config ) { free( config ); _______________________________________________ vlc-commits mailing list [email protected] https://mailman.videolan.org/listinfo/vlc-commits
