[vlc-commits] modules: move documentation to header
Rémi Denis-Courmont
git at videolan.org
Mon Mar 4 21:05:57 CET 2019
vlc | branch: master | Rémi Denis-Courmont <remi at remlab.net> | 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 );
More information about the vlc-commits
mailing list