1

#ifndef MODULE_H

     2

#define MODULE_H

     3

     4

/**

     5

 * @file

     6

 *

     7

 * Dynamically loadable modules for use with nexus.

     8

 *

     9

 * The modules are loaded using dlopen(), and hence should be standard dynamic libraries. Modules are then "loaded" by

    10

 * resolving a `struct module_funcs` symbol called "<modname>_funcs", and then using the init func to construct a

    11

 * "context", which is then further manipulated by various other module functions.

    12

 */

    13

#include "nexus.h"

    14

#include "config.h"

    15

#include "error.h"

    16

    17

#include <sys/queue.h>

    18

    19

/**

    20

 * Information required to load/identify a module.

    21

 */

    22

struct module_info {

    23

    /** Human-readable name */

    24

    const char *name;

    25

    26

    /** Filesystem path to the .so */

    27

    const char *path;

    28

};

    29

    30

/**

    31

 * A table of (function/other) pointers defining a module's behaviour. This is dynamically resolved from the module DSO

    32

 * using the "<mod_name>_module" symbol.

    33

 */

    34

struct module_desc {

    35

    /**

    36

     * Initialize the module, returning an opaque context pointer that is stored in the module state, and supplied for

    37

     * subsequent calls. The supplied nexus arg can be used to access the global state.

    38

     *

    39

     * @param nexus a pointer to the nexus struct containing the global state

    40

     * @param ctx_ptr the context pointer should be returned via this

    41

     * @param err returned error info

    42

     */

    43

    err_t (*init) (struct nexus *nexus, void **ctx_ptr, struct error_info *err);

    44

    45

    /**

    46

     * A module may define a set of available configuration parameters for use by module_conf, by setting this to an

    47

     * array of config_option's.

    48

     *

    49

     * The handler functions will recieve the module's context pointer as their ctx argument.

    50

     */

    51

    const struct config_option *config_options;

    52

    53

    /**

    54

     * Unload the module, removing all handlers/callbacks added to the nexus' irc_client. This does not have to act

    55

     * immediately, and will still have access to all irc_* resources it had earlier, and may perform I/O to unload

    56

     * cleanly. But the unloading should complete reasonably quickly, after which all event handlers added by the

    57

     * module to the nexus' ev_base should have been removed, and resources released.

    58

     *

    59

     * @param ctx the module's context pointer as returned by init

    60

     */

    61

    err_t (*unload) (void *ctx);

    62

};

    63

    64

/**

    65

 * A loaded module.

    66

 */

    67

struct module {

    68

    /** The identifying info for the module */

    69

    struct module_info info;

    70

    71

    /** The dlopen handle */

    72

    void *handle;

    73

    74

    /** The module entry point */

    75

    struct module_desc *desc;

    76

    77

    /** The module context object */

    78

    void *ctx;

    79

    80

    /** Reference back to modules struct used to load this module */

    81

    struct modules *modules;

    82

    83

    /**

    84

     * Is the module currently being unloaded?

    85

     */

    86

    bool unloading;

    87

    88

    /** Our entry in the list of modules */

    89

    TAILQ_ENTRY(module) modules_list;

    90

};

    91

    92

/**

    93

 * A set of loaded modules, and functionality to load more

    94

 */

    95

struct modules {

    96

    /** The nexus in use */

    97

    struct nexus *nexus;

    98

    99

    /** List of loaded modules */

   100

    TAILQ_HEAD(module_ctx_modules, module) list;

   101

};

   102

   103

/**

   104

 * Possible error codes

   105

 */

   106

enum module_error_code {

   107

    _ERR_MODULE_BEGIN = _ERR_MODULE,

   108

   109

    ERR_MODULE_OPEN,        ///< dlopen() failed

   110

    ERR_MODULE_NAME,        ///< invalid module_info.name

   111

    ERR_MODULE_SYM,         ///< invalid symbol

   112

    ERR_MODULE_INIT_FUNC,   ///< invalid module_init_func_t

   113

    ERR_MODULE_CONF,        ///< value error in configuration data

   114

};

   115

   116

   117

/**

   118

 * Maximum length of a module name

   119

 */

   120

#define MODULE_NAME_MAX 24

   121

   122

/**

   123

 * Maximum length of module symbol suffix

   124

 */

   125

#define MODULE_SUFFIX_MAX 16

   126

   127

/**

   128

 * Maximum length of symbol name name, including terminating NUL

   129

 */

   130

#define MODULE_SYMBOL_MAX (MODULE_NAME_MAX + 1 + MODULE_SUFFIX_MAX + 1)

   131

   132

/**

   133

 * Create a new modules state

   134

 */

   135

err_t modules_create (struct modules **modules_ptr, struct nexus *nexus);

   136

   137

/**

   138

 * Load a new module

   139

 *

   140

 * @param modules the module-loading context

   141

 * @param module_ptr return the new module via this, if not NULL

   142

 * @param info the info required to identify and load the module

   143

 * @param err return error info

   144

 */

   145

err_t module_load (struct modules *modules, struct module **module_ptr, const struct module_info *info, struct error_info *err);

   146

   147

/**

   148

 * Lookup a module by name

   149

 *

   150

 * @param modules the modules state

   151

 * @param name the module name to get

   152

 * @return the module struct, or NULL if not found

   153

 */

   154

struct module* module_get (struct modules *modules, const char *name);

   155

   156

/**

   157

 * Look up a module configuration option by name

   158

 */

   159

const struct config_option* module_conf_lookup (struct module *module, const char *name, struct error_info *err);

   160

   161

/**

   162

 * Apply a module configuration option using a structured value

   163

 */

   164

err_t module_conf (struct module *module, const struct config_option *opt, const struct config_value *value, struct error_info *err);

   165

   166

/**

   167

 * Set a module configuration option using a raw value

   168

 */

   169

err_t module_conf_raw (struct module *module, const char *name, char *value, struct error_info *err);

   170

   171

/**

   172

 * Unload a module. This means calling its 'unload' func, which will then go about shutting down the module. This might

   173

 * not happen right away, though, so the module is not destroyed yet.

   174

 *

   175

 * XXX: currently the module is never destroyed, there needs to be a "module unload done" callback...

   176

 */

   177

err_t module_unload (struct module *module);

   178

   179

/**

   180

 * Destroy a module, releasing as many resources as possible

   181

 */

   182

void module_destroy (struct module *module);

   183

   184

/**

   185

 * Unload all modules, this just calls module_unload for each module, logging errors as warnings.

   186

 *

   187

 * XXX: currently, this does not destroy any modules, or the modules state itself.

   188

 */

   189

err_t modules_unload (struct modules *modules);

   190

   191

#endif