28.2.4.2 插件数据结构
插件库文件包含 Descriptors 信息,以指示其包含哪些插件。
如果插件库包含任何服务器插件,则它必须包含以下 Descriptors 信息:
- 库 Descriptors 指示库使用的常规服务器插件 API 版本号,并包含库中每个服务器插件的常规插件 Descriptors。要提供此 Descriptors 的框架,请从
plugin.h
头文件中调用两个宏:
mysql_declare_plugin(name)
... one or more server plugin descriptors here ...
mysql_declare_plugin_end;
宏会展开以自动提供 API 版本的声明。您必须提供插件 Descriptors。
-
在库 Descriptors 中,每个通用服务器插件均由
st_mysql_plugin
结构描述。该插件 Descriptors 结构包含每种服务器插件类型共有的信息:指示插件类型的值;插件名称,作者,描述和许可证类型;指向服务器在加载和卸载插件时调用的初始化和反初始化函数的指针,以及指向插件实现的任何状态或系统变量的指针。 -
库 Descriptors 中的每个常规服务器插件 Descriptors 还包含一个指向特定于类型的插件 Descriptors 的指针。特定于类型的 Descriptors 的结构因一种插件类型而异,因为每种插件类型都可以具有自己的 API。特定于类型的插件 Descriptors 包含特定于类型的 API 版本号和指向实现该插件类型所需的功能的指针。例如,全文分析器插件具有初始化和反初始化功能,以及主要的分析功能。服务器在使用插件解析文本时会调用这些功能。
插件库还包含接口函数,该函数由库中每个插件的常规和特定于类型的 Descriptors 引用。
如果插件库包含 Client 端插件,则它必须包含该插件的 Descriptors。Descriptors 以所有 Client 端插件共有的一组固定成员开头,然后是该插件类型专有的所有成员。要提供 Descriptors 框架,请从client_plugin.h
头文件中调用两个宏:
mysql_declare_client_plugin(plugin_type)
... members common to all client plugins ...
... type-specific extra members ...
mysql_end_client_plugin;
插件库还包含 Client 端 Descriptors 引用的所有接口函数。
mysql_declare_plugin()
和mysql_declare_client_plugin()
宏的调用方式有所不同,这对插件库的内容有影响。以下准则概述了规则:
-
mysql_declare_plugin()
和mysql_declare_client_plugin()
都可以在同一源文件中使用,这意味着插件库可以同时包含服务器插件和 Client 端插件。但是,mysql_declare_plugin()
和mysql_declare_client_plugin()
最多只能使用一次。 -
mysql_declare_plugin()
允许多个服务器插件声明,因此插件库可以包含多个服务器插件。 -
mysql_declare_client_plugin()
仅允许单个 Client 端插件声明。要创建多个 Client 端插件,必须使用单独的插件库。
当 Client 端程序查找位于插件库中且未内置在libmysqlclient
中的 Client 端插件时,它将查找基名称与插件名称相同的文件。例如,如果程序需要在使用.so
作为库后缀的系统上使用名为auth_xxx
的 Client 端身份验证插件,则它将在名为auth_xxx.so
的文件中查找。 (在 macOS 上,程序首先查找auth_xxx.dylib
,然后查找auth_xxx.so
.)因此,如果插件库包含 Client 端插件,则该库必须具有与该插件相同的基本名称。
对于包含服务器插件的库,情况并非如此。 --plugin-load选项和INSTALL PLUGIN语句显式提供了库文件名,因此库名与其包含的任何服务器插件的名称之间都不需要明确的关系。
28.2.4.2.1 服务器插件库和插件 Descriptors
每个包含服务器插件的插件库都必须包含一个库 Descriptors,该 Descriptors 包含文件中每个服务器插件的常规插件 Descriptors。本节讨论如何编写服务器插件的库和常规 Descriptors。
库 Descriptors 必须定义两个符号:
-
_mysql_plugin_interface_version_
指定常规插件框架的版本号。这由plugin.h
文件中定义的MYSQL_PLUGIN_INTERFACE_VERSION
符号给出。 -
_mysql_plugin_declarations_
定义插件声明的数组,该声明以所有成员均设置为 0 的声明终止。每个声明都是st_mysql_plugin
结构的实例(也在plugin.h
中定义)。库中的每个服务器插件必须有一个。
如果服务器在库中找不到这两个符号,则它将不接受它作为合法的插件库,并以错误拒绝它。除非将库专门作为插件库构建,否则这将阻止将库用于插件目的。
定义两个必需符号的常规方法是使用plugin.h
文件中的mysql_declare_plugin()
和mysql_declare_plugin_end
宏:
mysql_declare_plugin(name)
... one or more server plugin descriptors here ...
mysql_declare_plugin_end;
每个服务器插件都必须具有向服务器插件 API 提供信息的常规 Descriptors。所有插件类型的通用 Descriptors 都具有相同的结构。 plugin.h
文件中的st_mysql_plugin
结构定义了此 Descriptors:
struct st_mysql_plugin
{
int type; /* the plugin type (a MYSQL_XXX_PLUGIN value) */
void *info; /* pointer to type-specific plugin descriptor */
const char *name; /* plugin name */
const char *author; /* plugin author (for I_S.PLUGINS) */
const char *descr; /* general descriptive text (for I_S.PLUGINS) */
int license; /* the plugin license (PLUGIN_LICENSE_XXX) */
int (*init)(void *); /* the function to invoke when plugin is loaded */
int (*deinit)(void *);/* the function to invoke when plugin is unloaded */
unsigned int version; /* plugin version (for I_S.PLUGINS) */
struct st_mysql_show_var *status_vars;
struct st_mysql_sys_var **system_vars;
void * __reserved1; /* reserved for dependency checking */
unsigned long flags; /* flags for plugin */
};
st_mysql_plugin
Descriptors 结构成员的用法如下。 char *
成员应指定为以 null 终止的字符串。
type
:插件类型。这必须是plugin.h
的插件类型值之一:
/*
The allowable types of plugins
*/
#define MYSQL_UDF_PLUGIN 0 /* User-defined function */
#define MYSQL_STORAGE_ENGINE_PLUGIN 1 /* Storage Engine */
#define MYSQL_FTPARSER_PLUGIN 2 /* Full-text parser plugin */
#define MYSQL_DAEMON_PLUGIN 3 /* The daemon/raw plugin type */
#define MYSQL_INFORMATION_SCHEMA_PLUGIN 4 /* The I_S plugin type */
#define MYSQL_AUDIT_PLUGIN 5 /* The Audit plugin type */
#define MYSQL_REPLICATION_PLUGIN 6 /* The replication plugin type */
#define MYSQL_AUTHENTICATION_PLUGIN 7 /* The authentication plugin type */
...
例如,对于全文语法分析器插件,type
的值为MYSQL_FTPARSER_PLUGIN
。
-
info
:指向插件的特定于类型的 Descriptors 的指针。与通用插件 Descriptors 结构不同,此 Descriptors 的结构取决于插件的特定类型。出于版本控制的目的,每个插件类型的特定于类型的 Descriptors 的第一个成员应该是该类型的接口版本。这使服务器可以检查每个插件的特定于类型的版本,无论其类型如何。在版本号之后,Descriptors 包括所需的任何其他成员,例如回调函数和服务器正确调用插件所需的其他信息。稍后有关编写特定类型的服务器插件的部分将描述其特定于类型的 Descriptors 的结构。 -
name
:给出插件名称的字符串。这是将在mysql.plugin
table 中列出的名称,通过它您可以在或_之类的 SQL 语句中或通过--plugin-load选项引用该插件。该名称在INFORMATION_SCHEMA.PLUGINStable 或SHOW PLUGINS的输出中也可见。
插件名称不应以任何服务器选项的名称开头。如果是这样,服务器将无法初始化它。例如,服务器具有--socket选项,因此您不应使用诸如socket
,socket_plugin
之类的插件名称。
-
author
:一个命名插件作者的字符串。这可以随便你。 -
desc
:一个字符串,提供插件的一般说明。这可以随便你。 -
license
:插件许可证类型。该值可以是PLUGIN_LICENSE_PROPRIETARY
,PLUGIN_LICENSE_GPL
或PLUGIN_LICENSE_BSD
之一。 -
init
:仅一次初始化的函数;如果没有此类函数,则返回NULL
。服务器在加载插件时执行此功能,这种情况在服务器启动时发生在INSTALL PLUGIN或mysql.plugin
table 中列出的插件上。该函数采用一个参数,该参数指向用于标识插件的内部结构。成功返回零,失败返回非零。 -
deinit
:仅一次取消初始化的函数;如果没有此类函数,则返回NULL
。服务器在卸载插件时执行此功能,这种情况发生在UNINSTALL PLUGIN或mysql.plugin
table 中列出的插件在服务器关闭时。该函数采用一个参数,该参数指向用于标识插件的内部结构。成功返回零,失败返回非零。 -
version
:插件版本号。安装插件后,可以从INFORMATION_SCHEMA.PLUGINStable 中检索此值。该值包括主要和次要数字。如果将值写为十六进制常量,则格式为0xMMNN
,其中*MM
*和NN
分别是主数和副数。例如,0x0302
代 table 版本 3.2. -
status_vars
:指向与插件关联的状态变量的结构的指针;如果没有此类变量,则为NULL
。安装插件后,这些变量将显示在SHOW STATUS语句的输出中。
status_vars
成员(如果不是NULL
)指向描述状态变量的st_mysql_show_var
结构数组。参见第 28.2.4.2.2 节,“服务器插件状态和系统变量”。
system_vars
:指向与插件关联的系统变量的结构的指针;如果没有此类变量,则为NULL
。这些选项和系统变量可用于帮助初始化插件中的变量。安装插件后,这些变量将显示在SHOW VARIABLES语句的输出中。
system_vars
成员(如果不是NULL
)指向描述系统变量的st_mysql_sys_var
结构数组。参见第 28.2.4.2.2 节,“服务器插件状态和系统变量”。
-
__reserved1
:Future 的占位符。应该将其设置为NULL
。 -
flags
:插件标志。各个位对应于不同的标志。该值应设置为适用标志的“或”。这些标志可用:
#define PLUGIN_OPT_NO_INSTALL 1UL /* Not dynamically loadable */
#define PLUGIN_OPT_NO_UNINSTALL 2UL /* Not dynamically unloadable */
启用时,这些标志具有以下含义:
-
PLUGIN_OPT_NO_INSTALL
:不能在运行时使用INSTALL PLUGIN语句加载插件。这适用于必须在服务器启动时使用--plugin-load或--plugin-load-add选项加载的插件。PLUGIN_OPT_NO_UNINSTALL
:无法在运行时使用UNINSTALL PLUGIN语句卸载插件。
服务器仅在加载和卸载插件时才在通用插件 Descriptors 中调用init
和deinit
函数。它们与插件的使用无关,例如当 SQL 语句导致调用插件时发生的情况。
例如,包含单个名为simple_parser
的全文分析器插件的库的 Descriptors 信息如下所示:
mysql_declare_plugin(ftexample)
{
MYSQL_FTPARSER_PLUGIN, /* type */
&simple_parser_descriptor, /* descriptor */
"simple_parser", /* name */
"Oracle Corporation", /* author */
"Simple Full-Text Parser", /* description */
PLUGIN_LICENSE_GPL, /* plugin license */
simple_parser_plugin_init, /* init function (when loaded) */
simple_parser_plugin_deinit,/* deinit function (when unloaded) */
0x0001, /* version */
simple_status, /* status variables */
simple_system_variables, /* system variables */
NULL,
0
}
mysql_declare_plugin_end;
对于全文分析器插件,类型必须为MYSQL_FTPARSER_PLUGIN
。这是一个值,用于在创建FULLTEXT
索引时将插件标识为在WITH PARSER
子句中合法使用。 (此条款没有其他插件类型合法.)
plugin.h
定义mysql_declare_plugin()
和mysql_declare_plugin_end
宏,如下所示:
#ifndef MYSQL_DYNAMIC_PLUGIN
#define __MYSQL_DECLARE_PLUGIN(NAME, VERSION, PSIZE, DECLS) \
MYSQL_PLUGIN_EXPORT int VERSION= MYSQL_PLUGIN_INTERFACE_VERSION; \
MYSQL_PLUGIN_EXPORT int PSIZE= sizeof(struct st_mysql_plugin); \
MYSQL_PLUGIN_EXPORT struct st_mysql_plugin DECLS[]= {
#else
#define __MYSQL_DECLARE_PLUGIN(NAME, VERSION, PSIZE, DECLS) \
MYSQL_PLUGIN_EXPORT int _mysql_plugin_interface_version_= MYSQL_PLUGIN_INTERFACE_VERSION; \
MYSQL_PLUGIN_EXPORT int _mysql_sizeof_struct_st_plugin_= sizeof(struct st_mysql_plugin); \
MYSQL_PLUGIN_EXPORT struct st_mysql_plugin _mysql_plugin_declarations_[]= {
#endif
#define mysql_declare_plugin(NAME) \
__MYSQL_DECLARE_PLUGIN(NAME, \
builtin_ ## NAME ## _plugin_interface_version, \
builtin_ ## NAME ## _sizeof_struct_st_plugin, \
builtin_ ## NAME ## _plugin)
#define mysql_declare_plugin_end ,{0,0,0,0,0,0,0,0,0,0,0,0,0}}
Note
仅当定义了MYSQL_DYNAMIC_PLUGIN
符号时,这些声明才定义_mysql_plugin_interface_version_
符号。这意味着-DMYSQL_DYNAMIC_PLUGIN
必须作为编译命令的一部分提供,以将插件构建为共享库。
如图所示使用宏时,它们将扩展为以下代码,该代码定义了两个必需的符号(_mysql_plugin_interface_version_
和_mysql_plugin_declarations_
):
int _mysql_plugin_interface_version_= MYSQL_PLUGIN_INTERFACE_VERSION;
int _mysql_sizeof_struct_st_plugin_= sizeof(struct st_mysql_plugin);
struct st_mysql_plugin _mysql_plugin_declarations_[]= {
{
MYSQL_FTPARSER_PLUGIN, /* type */
&simple_parser_descriptor, /* descriptor */
"simple_parser", /* name */
"Oracle Corporation", /* author */
"Simple Full-Text Parser", /* description */
PLUGIN_LICENSE_GPL, /* plugin license */
simple_parser_plugin_init, /* init function (when loaded) */
simple_parser_plugin_deinit,/* deinit function (when unloaded) */
0x0001, /* version */
simple_status, /* status variables */
simple_system_variables, /* system variables */
NULL,
0
}
,{0,0,0,0,0,0,0,0,0,0,0,0}}
};
前面的示例在常规 Descriptors 中声明了一个插件,但是可以声明多个插件。依次在mysql_declare_plugin()
和mysql_declare_plugin_end
之间列出声明,并用逗号分隔。
MySQL 服务器插件可以用 C 或 C(或可以使用 C 调用约定的另一种语言)编写。如果编写 C 插件,则不应该使用的 C 功能是非常量变量来初始化全局结构。诸如st_mysql_plugin
结构之类的结构成员仅应使用常量变量进行初始化。前面显示的simple_parser
Descriptors 在 C 插件中是允许的,因为它满足了以下要求:
mysql_declare_plugin(ftexample)
{
MYSQL_FTPARSER_PLUGIN, /* type */
&simple_parser_descriptor, /* descriptor */
"simple_parser", /* name */
"Oracle Corporation", /* author */
"Simple Full-Text Parser", /* description */
PLUGIN_LICENSE_GPL, /* plugin license */
simple_parser_plugin_init, /* init function (when loaded) */
simple_parser_plugin_deinit,/* deinit function (when unloaded) */
0x0001, /* version */
simple_status, /* status variables */
simple_system_variables, /* system variables */
NULL,
0
}
mysql_declare_plugin_end;
这是编写通用 Descriptors 的另一种有效方法。它使用常量变量来指示插件名称,作者和描述:
const char *simple_parser_name = "simple_parser";
const char *simple_parser_author = "Oracle Corporation";
const char *simple_parser_description = "Simple Full-Text Parser";
mysql_declare_plugin(ftexample)
{
MYSQL_FTPARSER_PLUGIN, /* type */
&simple_parser_descriptor, /* descriptor */
simple_parser_name, /* name */
simple_parser_author, /* author */
simple_parser_description, /* description */
PLUGIN_LICENSE_GPL, /* plugin license */
simple_parser_plugin_init, /* init function (when loaded) */
simple_parser_plugin_deinit,/* deinit function (when unloaded) */
0x0001, /* version */
simple_status, /* status variables */
simple_system_variables, /* system variables */
NULL,
0
}
mysql_declare_plugin_end;
但是,以下通用 Descriptors 无效。它使用结构成员来指示插件名称,作者和描述,但是在 C 中,结构不被视为常量初始化器:
typedef struct
{
const char *name;
const char *author;
const char *description;
} plugin_info;
plugin_info parser_info = {
"simple_parser",
"Oracle Corporation",
"Simple Full-Text Parser"
};
mysql_declare_plugin(ftexample)
{
MYSQL_FTPARSER_PLUGIN, /* type */
&simple_parser_descriptor, /* descriptor */
parser_info.name, /* name */
parser_info.author, /* author */
parser_info.description, /* description */
PLUGIN_LICENSE_GPL, /* plugin license */
simple_parser_plugin_init, /* init function (when loaded) */
simple_parser_plugin_deinit,/* deinit function (when unloaded) */
0x0001, /* version */
simple_status, /* status variables */
simple_system_variables, /* system variables */
NULL,
0
}
mysql_declare_plugin_end;
28.2.4.2.2 服务器插件状态和系统变量
服务器插件界面使插件可以使用常规插件 Descriptors 的status_vars
和system_vars
成员公开状态和系统变量。
通用插件 Descriptors 的status_vars
成员(如果不为 0)指向st_mysql_show_var
结构的数组,每个结构都描述一个状态变量,然后是一个结构,其中所有成员都设置为 0.st_mysql_show_var
结构具有以下定义:
struct st_mysql_show_var {
const char *name;
char *value;
enum enum_mysql_show_type type;
};
下 table 显示了允许的状态变量type
值以及相应的变量应为多少。
table28.1 服务器插件状态变量类型
Variable Type | Meaning |
---|---|
SHOW_BOOL |
指向布尔变量的指针 |
SHOW_INT |
指向整数变量的指针 |
SHOW_LONG |
指向长整数变量的指针 |
SHOW_LONGLONG |
指向 longlong 整数变量的指针 |
SHOW_CHAR |
A string |
SHOW_CHAR_PTR |
指向字符串的指针 |
SHOW_ARRAY |
指向另一个st_mysql_show_var 数组的指针 |
SHOW_FUNC |
指向功能的指针 |
SHOW_DOUBLE |
指向双精度指针 |
对于SHOW_FUNC
类型,将调用该函数并填写其out
参数,该参数随后提供有关要显示的变量的信息。该函数具有以下签名:
#define SHOW_VAR_FUNC_BUFF_SIZE 1024
typedef int (*mysql_show_var_func) (void *thd,
struct st_mysql_show_var *out,
char *buf);
system_vars
成员(如果不是 0)指向st_mysql_sys_var
结构的数组,每个结构描述一个系统变量(也可以从命令行或配置文件中设置),然后是一个结构,其中所有成员都设置为 0. st_mysql_sys_var
结构定义如下:
struct st_mysql_sys_var {
int flags;
const char *name, *comment;
int (*check)(THD*, struct st_mysql_sys_var *, void*, st_mysql_value*);
void (*update)(THD*, struct st_mysql_sys_var *, void*, const void*);
};
根据标志的需要,可以附加其他字段。
为方便起见,定义了许多宏,这些宏使在插件内创建新的系统变量更加简单。
在整个宏中,以下字段可用:
-
name
:系统变量的未引用标识符。 -
varname
:静态变量的标识符。如果不可用,则与name
字段相同。 -
opt
:系统变量的其他使用标志。下 table 显示了允许的标志。
table28.2 服务器插件系统变量标志
Flag Value | Description |
---|---|
PLUGIN_VAR_READONLY |
系统变量是只读的 |
PLUGIN_VAR_NOSYSVAR |
在运行时用户看不到系统变量 |
PLUGIN_VAR_NOCMDOPT |
不能从命令行配置系统变量 |
PLUGIN_VAR_NOCMDARG |
在命令行上不需要参数(通常用于布尔变量) |
PLUGIN_VAR_RQCMDARG |
在命令行中需要一个参数(这是默认值) |
PLUGIN_VAR_OPCMDARG |
命令行中的参数是可选的 |
PLUGIN_VAR_MEMALLOC |
用于字符串变量;指示要为存储字符串分配内存 |
-
comment
:要在服务器帮助消息中显示的描述性 Comments。NULL
(如果要隐藏此变量)。 -
check
:检查功能,默认为NULL
。 -
update
:更新功能,默认为NULL
。 -
default
:变量默认值。 -
minimum
:可变最小值。 -
maximum
:可变最大值。 -
blocksize
:可变块大小。设置该值后,会将其舍入为blocksize
的最接近倍数。
可以通过直接使用静态变量或通过使用SYSVAR()
访问器宏来访问系统变量。提供SYSVAR()
宏是为了完整性。通常,仅当代码无法直接访问基础变量时才应使用它。
For example:
static int my_foo;
static MYSQL_SYSVAR_INT(foo_var, my_foo,
PLUGIN_VAR_RQCMDARG, "foo comment",
NULL, NULL, 0, 0, INT_MAX, 0);
...
SYSVAR(foo_var)= value;
value= SYSVAR(foo_var);
my_foo= value;
value= my_foo;
只能通过THDVAR()
访问器宏访问会话变量。例如:
static MYSQL_THDVAR_BOOL(some_flag,
PLUGIN_VAR_NOCMDARG, "flag comment",
NULL, NULL, FALSE);
...
if (THDVAR(thd, some_flag))
{
do_something();
THDVAR(thd, some_flag)= FALSE;
}
使用之前,所有全局和会话系统变量都必须发布到mysqld。这是通过构造变量的NULL
终止的数组并在插件公共接口中链接到它来完成的。例如:
static struct st_mysql_sys_var *my_plugin_vars[]= {
MYSQL_SYSVAR(foo_var),
MYSQL_SYSVAR(some_flag),
NULL
};
mysql_declare_plugin(fooplug)
{
MYSQL_..._PLUGIN,
&plugin_data,
"fooplug",
"foo author",
"This does foo!",
PLUGIN_LICENSE_GPL,
foo_init,
foo_fini,
0x0001,
NULL,
my_plugin_vars,
NULL,
0
}
mysql_declare_plugin_end;
以下便利宏使您可以声明不同类型的系统变量:
- 类型为
my_bool
的布尔系统变量,它是 1 字节的布尔值。 (0 =假,1 =真)
MYSQL_THDVAR_BOOL(name, opt, comment, check, update, default)
MYSQL_SYSVAR_BOOL(name, varname, opt, comment, check, update, default)
- 类型为
char*
的字符串系统变量,它是一个以 null 终止的字符串的指针。
MYSQL_THDVAR_STR(name, opt, comment, check, update, default)
MYSQL_SYSVAR_STR(name, varname, opt, comment, check, update, default)
-
整数系统变量,其中有几个变体。
-
int
系统变量,通常是一个 4 字节的带符号字。
MYSQL_THDVAR_INT(name, opt, comment, check, update, default, min, max, blk)
MYSQL_SYSVAR_INT(name, varname, opt, comment, check, update, default,
minimum, maximum, blocksize)
unsigned int
系统变量,通常为 4 字节无符号字。
MYSQL_THDVAR_UINT(name, opt, comment, check, update, default, min, max, blk)
MYSQL_SYSVAR_UINT(name, varname, opt, comment, check, update, default,
minimum, maximum, blocksize)
long
系统变量,通常为 4 或 8 字节的带符号字。
MYSQL_THDVAR_LONG(name, opt, comment, check, update, default, min, max, blk)
MYSQL_SYSVAR_LONG(name, varname, opt, comment, check, update, default,
minimum, maximum, blocksize)
unsigned long
系统变量,通常是 4 或 8 字节的无符号字。
MYSQL_THDVAR_ULONG(name, opt, comment, check, update, default, min, max, blk)
MYSQL_SYSVAR_ULONG(name, varname, opt, comment, check, update, default,
minimum, maximum, blocksize)
long long
系统变量,通常是一个 8 字节的带符号字。
MYSQL_THDVAR_LONGLONG(name, opt, comment, check, update,
default, minimum, maximum, blocksize)
MYSQL_SYSVAR_LONGLONG(name, varname, opt, comment, check, update,
default, minimum, maximum, blocksize)
unsigned long long
系统变量,通常是 8 字节无符号字。
MYSQL_THDVAR_ULONGLONG(name, opt, comment, check, update,
default, minimum, maximum, blocksize)
MYSQL_SYSVAR_ULONGLONG(name, varname, opt, comment, check, update,
default, minimum, maximum, blocksize)
double
系统变量,通常是一个 8 字节的带符号字。
MYSQL_THDVAR_DOUBLE(name, opt, comment, check, update,
default, minimum, maximum, blocksize)
MYSQL_SYSVAR_DOUBLE(name, varname, opt, comment, check, update,
default, minimum, maximum, blocksize)
unsigned long
系统变量,通常是 4 或 8 字节的无符号字。可能值的范围是typelib
中元素的序数,从 0 开始。
MYSQL_THDVAR_ENUM(name, opt, comment, check, update, default, typelib)
MYSQL_SYSVAR_ENUM(name, varname, opt, comment, check, update,
default, typelib)
unsigned long long
系统变量,通常是 8 字节无符号字。每一位代 tabletypelib
中的一个元素。
MYSQL_THDVAR_SET(name, opt, comment, check, update, default, typelib)
MYSQL_SYSVAR_SET(name, varname, opt, comment, check, update,
default, typelib)
在内部,所有可变和插件系统变量都存储在HASH
结构中。
通过编译与命令行选项相关的所有变量的DYNAMIC_ARRAY
,对它们进行排序,然后遍历它们以显示每个选项,来处理服务器命令行帮助文本的显示。
处理完命令行选项后,便通过handle_option()
函数(my_getopt.c
)将其从argv
中删除;实际上,它被消耗了。
服务器在插件安装过程中,成功加载插件之后,但调用插件初始化函数之前立即处理命令行选项。
在运行时加载的插件无法从任何配置选项中受益,并且必须具有可用的默认值。安装它们后,它们将在mysqld初始化时加载,并且可以在命令行或my.cnf
内设置配置选项。
插件应将thd
参数视为只读。
28.2.4.2.3Client 端插件 Descriptors
每个 Client 端插件必须具有一个 Descriptors,该 Descriptors 向 Client 端插件 API 提供信息。Descriptors 结构开始于所有 Client 端插件共有的一组固定成员,然后是特定于插件类型的所有成员。
client_plugin.h
文件中的st_mysql_client_plugin
结构定义了一个包含通用成员的“通用”Descriptors:
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
Descriptors 结构成员如下使用。 char *
成员应指定为以 null 终止的字符串。
-
type
:插件类型。这必须是client_plugin.h
的插件类型值之一,例如MYSQL_CLIENT_AUTHENTICATION_PLUGIN
。 -
interface_version
:插件界面版本。例如,对于身份验证插件,这是MYSQL_CLIENT_AUTHENTICATION_PLUGIN_INTERFACE_VERSION
。 -
name
:提供插件名称的字符串。这是在使用MYSQL_DEFAULT_AUTH
选项调用mysql_options()或为 MySQLClient 端程序指定--default-auth
选项时引用插件的名称。 -
author
:一个命名插件作者的字符串。这可以随便你。 -
desc
:一个字符串,提供插件的一般说明。这可以随便你。 -
version
:插件版本,由三个整数组成,table 示主要,次要和小版本。例如,{1,2,3}
table 示版本 1.2.3. -
license
:一个字符串,用于指定许可证类型。 -
mysql_api
:供内部使用。在插件 Descriptors 中将其指定为NULL
。 -
init
:仅限一次的初始化函数;如果没有此类函数,则返回NULL
。Client 端库在加载插件时执行此功能。该函数成功返回零,失败返回非零。
如果发生错误,则init
函数使用其前两个参数返回错误消息。第一个参数是指向char
缓冲区的指针,第二个参数指示缓冲区的长度。 init
函数返回的任何消息都必须以空值结尾,因此最大消息长度是缓冲区长度减去一。接下来的参数传递给mysql_load_plugin()。第一个 table 示存在多少个参数(如果没有则为 0),其后是剩余的任何参数。
-
deinit
:仅一次取消初始化的函数;如果没有此类函数,则返回NULL
。Client 端库在卸载插件时执行此功能。该函数不带参数。成功返回零,失败返回非零。 -
options
:用于处理传递给插件的选项的函数,或者NULL
(如果没有此函数)。该函数使用两个参数 table 示选项名称和一个指向其值的指针。该函数成功返回零,失败返回非零。
对于给定的 Client 端插件类型,公共 Descriptors 成员后可以跟随实现该类型插件所必需的其他成员。例如,身份验证插件的st_mysql_client_plugin_AUTHENTICATION
结构在 Client 端库调用以执行身份验证的末尾具有一个功能。
要声明插件,请使用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
*参数自动生成它们的值。例如,声明这样的身份验证 Client 端插件:
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
。
根据插件的类型,Descriptors 可能在公共成员之后还有其他成员。例如,对于身份验证插件,有一个函数(在刚刚显示的 Descriptors 中为my_auth_main()
)处理与服务器的通信。参见第 28.2.4.9 节“编写身份验证插件”。
通常,支持身份验证插件使用的 Client 端程序会通过调用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
选项,这些选项使用户可以覆盖默认值。
如果 Client 端程序需要较低级别的插件 Management,则 Client 端库应包含带有st_mysql_client_plugin
参数的函数。参见第 27.7.13 节“ C APIClient 端插件功能”。