跳转到正文

生命周期与导出函数

插件的加载、初始化、启停、卸载流程,以及所有必须和可选的 DLL 导出函数说明。

生命周期流程

  1. 载入与信息读取:主程序载入 DLL,调用 plugin_info() 读取元信息并校验 sdk_version 与插件 ID 规则。
  2. 安装初始化:调用 plugin_install(api),传入主程序接口表。插件必须先调用 api_init(api) 保存接口表,整个载入期间只调用一次。
  3. 启用:用户启用插件(或主程序启动时该插件处于启用状态)时,调用 plugin_switch(true)。插件在此启动自己的工作线程或定时任务;返回 true 后才开始接收消息与事件回调。
  4. 停用:插件停用后不再接收新消息,待正在执行的回调全部返回后调用 plugin_switch(false)。插件应在此停止所有工作线程与定时任务。停用期间未处理的消息不会补发。
  5. 卸载与释放:程序退出、退出客户端登录或更新插件时,主程序先停止插件,再调用 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 误判为业务成功。

本页目录