vlc_modules.h

/*****************************************************************************
 * 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 */