PDF (US Ltr) - 420.5Kb
PDF (A4) - 419.3Kb
每个客户端插件都必须有一个描述符，用于向客户端插件 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 * 成员应指定为以空字符结尾的字符串。
type: 插件类型。这必须是client_plugin.h中的插件类型值之一，例如MYSQL_CLIENT_AUTHENTICATION_PLUGIN。interface_version: 插件接口版本。例如，对于身份验证插件，这为MYSQL_CLIENT_AUTHENTICATION_PLUGIN_INTERFACE_VERSION。name: 提供插件名称的字符串。这是您在调用mysql_options()并使用MYSQL_DEFAULT_AUTH选项或为 MySQL 客户端程序指定--default-auth选项时引用插件的名称。author: 命名插件作者的字符串。这可以是您想要的任何内容。desc: 提供插件的总体描述的字符串。这可以是您想要的任何内容。version: 插件版本，作为三个整数数组表示，分别表示主版本、次版本和微版本。例如，{1,2,3}表示版本 1.2.3。license: 指定许可证类型的字符串。mysql_api: 用于内部使用。在插件描述符中将其指定为NULL。-
init: 一次性初始化函数，如果不存在此类函数，则为NULL。客户端库在加载插件时执行此函数。该函数返回值为零表示成功，非零表示失败。如果发生错误，
init函数使用其前两个参数返回错误消息。第一个参数是指向char缓冲区的指针，第二个参数指示缓冲区长度。由init函数返回的任何消息都必须以空字符结尾，因此最大消息长度为缓冲区长度减一。下一个参数传递给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;不要显式指定 type 或 interface_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 参数将 type 和 interface_version 成员分别设置为 MYSQL_CLIENT_AUTHENTICATION_PLUGIN 和 MYSQL_CLIENT_AUTHENTICATION_PLUGIN_INTERFACE_VERSION。
根据插件类型，描述符可能在通用成员后面包含其他成员。例如，对于身份验证插件，有一个函数（如刚刚显示的描述符中的 my_auth_main()）处理与服务器的通信。请参阅 第 4.4.9 节，“编写身份验证插件”。
通常，支持使用身份验证插件的客户端程序会通过调用 mysql_options() 设置 MYSQL_DEFAULT_AUTH 和 MYSQL_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 客户端插件接口。