扩展 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如果没有这样的函数。客户端库在加载插件时执行此函数。该函数返回零表示成功，非零表示失败。

    The init function uses its first two arguments to return an error message if an error occurs. The first argument is a pointer to a char buffer, and the second argument indicates the buffer length. Any message returned by the init function must be null-terminated, so the maximum message length is the buffer length minus one. The next arguments are passed to mysql_load_plugin(). The first indicates how many more arguments there are (0 if none), followed by any remaining arguments.

  • deinit: A once-only deinitialization function, or NULL if there is no such function. The client library executes this function when it unloads the plugin. The function takes no arguments. It returns zero for success and nonzero for failure.

  • options: A function for handling options passed to the plugin, or NULL if there is no such function. The function takes two arguments representing the option name and a pointer to its value. The function returns zero for success and nonzero for failure.

For a given client plugin type, the common descriptor members may be followed by additional members necessary to implement plugins of that type. For example, the st_mysql_client_plugin_AUTHENTICATION structure for authentication plugins has a function at the end that the client library calls to perform authentication.

To declare a plugin, use the mysql_declare_client_plugin() and mysql_end_client_plugin macros: 

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

Do not specify the type or interface_version member explicitly. The mysql_declare_client_plugin() macro uses the plugin_type argument to generate their values automatically. For example, declare an authentication client plugin like this: 

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;

This declaration uses the AUTHENTICATION argument to set the type and interface_version members to MYSQL_CLIENT_AUTHENTICATION_PLUGIN and MYSQL_CLIENT_AUTHENTICATION_PLUGIN_INTERFACE_VERSION.

Depending on the plugin type, the descriptor may have other members following the common members. For example, for an authentication plugin, there is a function (my_auth_main() in the descriptor just shown) that handles communication with the server. See Section 4.4.9, “Writing Authentication Plugins”.

Normally, a client program that supports the use of authentication plugins causes a plugin to be loaded by calling mysql_options() to set the MYSQL_DEFAULT_AUTH and MYSQL_PLUGIN_DIR options: 

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);

Typically, the program will also accept --plugin-dir and --default-auth options that enable users to override the default values.

Should a client program require lower-level plugin management, the client library contains functions that take an st_mysql_client_plugin argument. See C API Client Plugin Interface.