扩展 MySQL 8.0  / 第 4 章 MySQL 插件 API  / 4.4 编写插件  / 4.4.2 插件数据结构  /  4.4.2.3 客户端插件描述符

4.4.2.3 客户端插件描述符

每个客户端插件都必须有一个向客户端插件 API 提供信息的描述符。描述符结构以所有客户端插件共有的一组固定成员开始,然后是特定于插件类型的任何成员。

文件中的st_mysql_client_plugin结构client_plugin.h定义了一个 包含公共成员 的通用”描述符:

struct st_mysql_client_plugin
{
  int type;
  unsigned int interface_version;
  const char *name;
  const char *author;
  const char *desc;
  unsigned int version[3];
  const char *license;
  void *mysql_api;
  int (*init)(char *, size_t, int, va_list);
  int (*deinit)();
  int (*options)(const char *option, const void *);
};

公共st_mysql_client_plugin 描述符结构成员使用如下。 char *成员应指定为以 null 结尾的字符串。

  • type: 插件类型。这必须是来自 的插件类型值之一 client_plugin.h,例如 MYSQL_CLIENT_AUTHENTICATION_PLUGIN

  • interface_version: 插件接口版本。例如,这是 MYSQL_CLIENT_AUTHENTICATION_PLUGIN_INTERFACE_VERSION 一个身份验证插件。

  • name:给出插件名称的字符串。mysql_options()当您使用 选项调用或向 MySQL 客户端程序 MYSQL_DEFAULT_AUTH指定选项时,这是您引用插件的名称 。--default-auth

  • author:命名插件作者的字符串。这可以是任何你喜欢的。

  • desc:提供插件一般描述的字符串。这可以是任何你喜欢的。

  • version:插件版本作为三个整数的数组,指示主要版本、次要版本和极小版本。例如,{1,2,3} 表示版本 1.2.3。

  • license:指定许可证类型的字符串。

  • mysql_api: 供内部使用。NULL在插件描述符中 指定它。

  • init: 一个一次性的初始化函数,或者NULL如果没有这样的函数。客户端库在加载插件时执行此函数。该函数返回零表示成功,非零表示失败。

    init如果发生错误, 该函数使用其前两个参数返回错误消息。第一个参数是指向 char缓冲区的指针,第二个参数表示缓冲区长度。该函数返回的任何消息都 init必须以 null 结尾,因此最大消息长度是缓冲区长度减一。下一个参数传递给mysql_load_plugin(). 第一个表示还有多少参数(如果没有则为 0),然后是任何剩余的参数。

  • deinit: 一个一次性的反初始化函数,或者NULL如果没有这样的函数。客户端库在卸载插件时执行此函数。该函数不带参数。成功返回零,失败返回非零。

  • options:用于处理传递给插件的选项的函数,或者NULL 如果没有这样的函数。该函数有两个代表选项名称的参数和一个指向其值的指针。该函数返回零表示成功,非零表示失败。

对于给定的客户端插件类型,公共描述符成员后面可能跟有实现该类型插件所需的其他成员。例如, st_mysql_client_plugin_AUTHENTICATION 身份验证插件的结构在客户端库调用以执行身份验证的末尾有一个函数。

要声明一个插件,请使用 mysql_declare_client_plugin()mysql_end_client_plugin宏:

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

不要明确指定typeinterface_version成员。mysql_declare_client_plugin()宏使用plugin_type参数自动生成它们的值。 例如,像这样声明一个身份验证客户端插件:

mysql_declare_client_plugin(AUTHENTICATION)
  "my_auth_plugin",
  "Author Name",
  "My Client Authentication Plugin",
  {1,0,0},
  "GPL",
  NULL,
  my_auth_init,
  my_auth_deinit,
  my_auth_options,
  my_auth_main
mysql_end_client_plugin;

此声明使用AUTHENTICATION 参数将typeand interface_version成员设置为 MYSQL_CLIENT_AUTHENTICATION_PLUGINand MYSQL_CLIENT_AUTHENTICATION_PLUGIN_INTERFACE_VERSION

根据插件类型,描述符可能在公共成员之后有其他成员。例如,对于身份验证插件,有一个函数(my_auth_main()在刚刚显示的描述符中)处理与服务器的通信。请参阅 第 4.4.9 节,“编写身份验证插件”

通常,支持使用身份验证插件的客户端程序会通过调用mysql_options()设置MYSQL_DEFAULT_AUTHMYSQL_PLUGIN_DIR选项来加载插件:

char *plugin_dir = "path_to_plugin_dir";
char *default_auth = "plugin_name";

/* ... process command-line options ... */

mysql_options(&mysql, MYSQL_PLUGIN_DIR, plugin_dir);
mysql_options(&mysql, MYSQL_DEFAULT_AUTH, default_auth);

通常,该程序还将接受 使用户能够覆盖默认值的选项 --plugin-dir--default-auth

如果客户端程序需要较低级别的插件管理,则客户端库包含带有st_mysql_client_plugin参数的函数。请参阅 C API 客户端插件接口