生命周期与导出函数
插件的加载、初始化、启停、卸载流程,以及所有必须和可选的 DLL 导出函数说明。
生命周期流程
- 载入与信息读取:主程序载入 DLL,调用
plugin_info()读取元信息并校验sdk_version与插件 ID 规则。 - 安装初始化:调用
plugin_install(api),传入主程序接口表。插件必须先调用api_init(api)保存接口表,整个载入期间只调用一次。 - 启用:用户启用插件(或主程序启动时该插件处于启用状态)时,调用
plugin_switch(true)。插件在此启动自己的工作线程或定时任务;返回true后才开始接收消息与事件回调。 - 停用:插件停用后不再接收新消息,待正在执行的回调全部返回后调用
plugin_switch(false)。插件应在此停止所有工作线程与定时任务。停用期间未处理的消息不会补发。 - 卸载与释放:程序退出、退出客户端登录或更新插件时,主程序先停止插件,再调用
plugin_uninstall(),最后释放 DLL。
确保线程完全退出
DLL 释放后插件代码不再存在于进程地址空间中。插件创建的所有线程必须在 plugin_switch(false) 或 plugin_uninstall() 返回前全部结束。
PluginInfo 结构体
#define SDK_VERSION 1
typedef struct PluginInfo {
uint32_t sdk_version; /* 填 SDK_VERSION */
const char *id; /* 插件 ID,域名格式 */
const char *name; /* 插件名称,不能为空 */
const char *version; /* 版本文案,可为 "" 或 NULL */
const char *author; /* 作者,可为 "" 或 NULL */
const char *description; /* 插件说明,可为 "" 或 NULL */
} PluginInfo;- 所有文本使用 UTF-8,单个原始文本字段不超过 4096 字节。
sdk_version低于客户端最低支持版本时,插件不会被载入。id、name去除首尾空白后不能为空;version、author、description传""或NULL时按空文本显示。- 结构体及字符串由插件持有,载入期间必须保持有效,不交给
free_*。
必须导出的函数
plugin_info
EXPORT const PluginInfo *plugin_info(void);返回指向静态 PluginInfo 的指针。
plugin_install
EXPORT bool plugin_install(const Api *api);- 必须在函数开头调用
api_init(api)保存接口表,之后才能调用任何 SDK 接口函数。 - 返回
true表示安装成功;返回false表示失败,插件不会被启用。
plugin_switch
EXPORT bool plugin_switch(bool enabled);enabled == true时启动插件;返回false表示启动失败,插件保持停用状态。enabled == false时停止插件,结束后台线程与定时任务。
可选导出的函数
仅导出需要的功能即可;未导出的消息或事件回调,主程序不会向插件投递对应类别的数据。
| 导出函数 | 说明 |
|---|---|
EXPORT void plugin_uninstall(void) | 卸载前调用一次,用于释放安装期申请的句柄或资源。 |
EXPORT void on_group_message(const GroupMessage *message) | 接收群聊消息,详见 群聊消息。 |
EXPORT void on_friend_message(const FriendMessage *message) | 接收好友消息,详见 好友消息。 |
EXPORT void on_group_event(const GroupEvent *event) | 接收群聊事件,详见 群聊事件。 |
EXPORT void on_friend_event(const FriendEvent *event) | 接收好友事件,详见 好友事件。 |
EXPORT void plugin_settings(void) | 打开插件自定义设置窗口。主程序在独立线程中调用,插件自行创建窗口并运行消息循环,窗口关闭后再返回。设置窗口打开期间不能更新插件。 |
接口表与版本兼容机制
plugin.h 提供了 api_init(api) 和 api_find(name),所有 SDK 接口函数均为基于 api_find 的 static inline 包装:
- 客户端版本较旧、尚未提供某项接口时:
- 返回
bool的接口返回false - 返回指针的接口返回
NULL free_*函数不做任何操作
- 返回
- 调用方不应将
NULL或false误判为业务成功。