0
0
Fork 0
mirror of https://github.com/matrix-construct/construct synced 2024-10-30 02:18:58 +01:00
construct/include/modules.h
Jason Volk e8355cb7be MAPI Version 3
This version leverages a flexible, cleaner key-value strategy
reducing the need to design entire new headers for every feature
addition, change, etc.

* A friendly declaration for the module authors, with minimal
requirements to fill in, and explicit labels of what the fields are.
* Repetition of keys, removing references to (and the requirement to
build) a clist, hlist and hfnlist and caplist and whatever the future
holds.
* Safe deterministic loading and unloading. Keys are evaluated in
order, errors can be recognized, and unloading occurs in reverse
order.

ircd: Refactor internal half of modules.c, with some V3 additions.
Provides better delegation for versions, a cleaner stack with better
error handling, and some functionality deduping. V1 and V2 handlers
are still somewhat unaltered, just factored in.
2016-06-28 20:14:09 -07:00

201 lines
6.4 KiB
C

/*
* ircd-ratbox: A slightly useful ircd.
* modules.h: A header for the modules functions.
*
* Copyright (C) 1990 Jarkko Oikarinen and University of Oulu, Co Center
* Copyright (C) 1996-2002 Hybrid Development Team
* Copyright (C) 2002-2004 ircd-ratbox development team
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 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 General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
* USA
*/
#ifndef INCLUDED_modules_h
#define INCLUDED_modules_h
#include "serno.h"
#include "defaults.h"
#include "setup.h"
#include "parse.h"
#define MAPI_CHARYBDIS 2
#include <ltdl.h>
#include "msg.h"
#include "hook.h"
struct module
{
const char *name;
const char *path;
const char *version;
const char *description;
lt_dlhandle address;
int core; /* This is int for backwards compat reasons */
int origin; /* Ditto */
int mapi_version;
void *mapi_header; /* actually struct mapi_mheader_av<mapi_version> */
rb_dlink_node node;
};
#define MAPI_MAGIC_HDR 0x4D410000
#define MAPI_V1 (MAPI_MAGIC_HDR | 0x1)
#define MAPI_V2 (MAPI_MAGIC_HDR | 0x2)
#define MAPI_V3 (MAPI_MAGIC_HDR | 0x3)
#define MAPI_MAGIC(x) ((x) & 0xffff0000)
#define MAPI_VERSION(x) ((x) & 0x0000ffff)
typedef struct Message* mapi_clist_av1;
typedef struct
{
const char *hapi_name;
int *hapi_id;
} mapi_hlist_av1;
typedef struct
{
const char *hapi_name;
hookfn fn;
} mapi_hfn_list_av1;
#define MAPI_CAP_CLIENT 1
#define MAPI_CAP_SERVER 2
typedef struct
{
int cap_index; /* Which cap index does this belong to? */
const char *cap_name; /* Capability name */
void *cap_ownerdata; /* Not used much but why not... */
unsigned int *cap_id; /* May be set to non-NULL to store cap id */
} mapi_cap_list_av2;
struct mapi_mheader_av1
{
int mapi_version; /* Module API version */
int (*mapi_register)(void); /* Register function; ret -1 = failure (unload) */
void (*mapi_unregister)(void); /* Unregister function. */
mapi_clist_av1 *mapi_command_list; /* List of commands to add. */
mapi_hlist_av1 *mapi_hook_list; /* List of hooks to add. */
mapi_hfn_list_av1 *mapi_hfn_list; /* List of hook_add_hook's to do */
const char *mapi_module_version; /* Module's version (freeform) */
};
#define MAPI_ORIGIN_UNKNOWN 0 /* Unknown provenance (AV1 etc.) */
#define MAPI_ORIGIN_EXTENSION 1 /* Charybdis extension */
#define MAPI_ORIGIN_CORE 2 /* Charybdis core module */
struct mapi_mheader_av2
{
int mapi_version; /* Module API version */
int (*mapi_register)(void); /* Register function; ret -1 = failure (unload) */
void (*mapi_unregister)(void); /* Unregister function. */
mapi_clist_av1 *mapi_command_list; /* List of commands to add. */
mapi_hlist_av1 *mapi_hook_list; /* List of hooks to add. */
mapi_hfn_list_av1 *mapi_hfn_list; /* List of hook_add_hook's to do */
mapi_cap_list_av2 *mapi_cap_list; /* List of CAPs to add */
const char *mapi_module_version; /* Module's version (freeform), replaced with ircd version if NULL */
const char *mapi_module_description; /* Module's description (freeform) */
time_t mapi_datecode; /* Unix timestamp of module's build */
};
#define DECLARE_MODULE_AV1(name, reg, unreg, cl, hl, hfnlist, v) \
struct mapi_mheader_av1 _mheader = { MAPI_V1, reg, unreg, cl, hl, hfnlist, v}
#define DECLARE_MODULE_AV2(name, reg, unreg, cl, hl, hfnlist, caplist, v, desc) \
struct mapi_mheader_av2 _mheader = { MAPI_V2, reg, unreg, cl, hl, hfnlist, caplist, v, desc, DATECODE}
/***
Version 3 modules utilize a flexible key/value vector.
Example:
DECLARE_MODULE_AV3
(
MOD_ATTR { "name", "mymodule" },
MOD_ATTR { "mtab", &message_foo },
MOD_ATTR { "mtab", &message_unfoo },
MOD_ATTR { "init", modinitfunc },
MOD_ATTR { "hook", MOD_HOOK { "myhook", &id } },
MOD_ATTR { "hookfn", MOD_HOOKFN { "myhook", hookfun } },
)
Notes:
- Multiple keys with the same name will have different behavior depending on the logic for that key.
- On load, the order in which keys are specified is the order they will be evaluated (top to bottom).
- On unload, the evaluation is the REVERSE order (bottom to top).
- If an init function returns false, or other error occurs, no further keys are evaluated and the
unload rolls back from that point.
***/
struct mapi_av3_attr
{
#define MAPI_V3_KEY_MAXLEN 16 /* Maximum length for a key string */
const char *key;
union { const void *cvalue; void *value; int (*init)(void); void (*fini)(void); };
};
struct mapi_mheader_av3
{
int mapi_version; // Module API version
struct mapi_av3_attr **attrs; // A vector of attributes, NULL terminated
};
#define MOD_ATTR &(struct mapi_av3_attr)
#define MOD_HOOK &(mapi_hlist_av1)
#define MOD_HOOKFN &(mapi_hfn_list_av1)
#define DECLARE_MODULE_AV3(...) \
struct mapi_mheader_av3 _mheader = \
{ \
MAPI_V3, (struct mapi_av3_attr *[]) \
{ \
MOD_ATTR { "time", DATECODE }, \
__VA_ARGS__, \
NULL \
} \
};
// Prefixes your slog() message with module info
void module_log(struct module *mod, const char *fmt, ...) AFP(2, 3);
/* add a path */
void mod_add_path(const char *path);
void mod_clear_paths(void);
/* load a module */
extern void load_module(char *path);
/* load all modules */
extern void load_all_modules(bool warn);
/* load core modules */
extern void load_core_modules(bool);
extern bool unload_one_module(const char *, bool);
extern bool load_one_module(const char *, int, bool);
extern bool load_a_module(const char *, bool, int, bool);
extern struct module *findmodule_byname(const char *);
extern void init_modules(void);
extern rb_dlink_list module_list;
extern rb_dlink_list mod_paths;
#endif /* INCLUDED_modules_h */