扩展 MySQL 8.0  / 第 4 章 MySQL 插件 API  / 4.4 编写插件  /  4.4.2 插件数据结构

4.4.2 插件数据结构

插件库文件包含描述符信息以指示它包含哪些插件。

如果插件库包含任何服务器插件,它必须包含以下描述符信息:

  • 库描述符指示库使用的通用服务器插件 API 版本号,并包含库中每个服务器插件的通用插件描述符。要为此描述符提供框架,请从头plugin.h 文件中调用两个宏:

    mysql_declare_plugin(name)
     ... one or more server plugin descriptors here ...
    mysql_declare_plugin_end;

    宏扩展以自动提供 API 版本的声明。您必须提供插件描述符。

  • 在库描述符中,每个通用服务器插件都由一个st_mysql_plugin 结构描述。此插件描述符结构包含每种类型的服务器插件共有的信息:指示插件类型的值;插件名称、作者、描述和许可证类型;指向服务器在加载和卸载插件时调用的初始化和取消初始化函数的指针,以及指向插件实现的任何状态或系统变量的指针。

  • 库描述符中的每个通用服务器插件描述符还包含一个指向特定类型插件描述符的指针。特定于类型的描述符的结构因插件类型而异,因为每种插件都可以有自己的 API。特定类型的插件描述符包含特定类型的 API 版本号和指向实现该插件类型所需的函数的指针。例如,一个全文解析器插件有初始化和反初始化函数,以及一个主要的解析函数。服务器在使用插件解析文本时调用这些函数。

插件库还包含库中每个插件的通用和特定类型描述符所引用的接口函数。

如果插件库包含客户端插件,则它必须包含插件的描述符。描述符以所有客户端插件通用的一组固定成员开始,然后是特定于插件类型的任何成员。要提供描述符框架,请从头 client_plugin.h文件调用两个宏:

mysql_declare_client_plugin(plugin_type)
   ... members common to all client plugins ...
   ... type-specific extra members ...
mysql_end_client_plugin;

插件库还包含客户端描述符引用的任何接口函数。

mysql_declare_plugin()和 宏 的mysql_declare_client_plugin()调用方式有所不同,这对插件库的内容有影响。以下指南总结了这些规则:

  • mysql_declare_plugin()并且 mysql_declare_client_plugin()可以在同一个源文件中使用,这意味着插件库可以同时包含服务器和客户端插件。但是,每个mysql_declare_plugin()mysql_declare_client_plugin()最多只能使用一次。

  • mysql_declare_plugin()允许多个服务器插件声明,因此一个插件库可以包含多个服务器插件。

  • mysql_declare_client_plugin()只允许一个客户端插件声明。要创建多个客户端插件,必须使用单独的插件库。

当客户端程序查找插件库中而非内置的客户端插件时 libmysqlclient,它会查找基本名称与插件名称相同的文件。例如,如果程序需要使用 auth_xxx在系统上 命名.so为库后缀的客户端身份验证插件,它会在名为auth_xxx.so. (在 macOS 上,程序首先查找 auth_xxx.dylib,然后查找 auth_xxx.so。)因此,如果插件库包含客户端插件,则该库必须与该插件具有相同的基本名称。

对于包含服务器插件的库来说情况并非如此。--plugin-load 选项和语句明确提供库INSTALL PLUGIN 文件名,因此库名和它包含的任何服务器插件的名称之间不需要明确的关系。