Rechercher dans le manuel MySQL
29.2.4.2 Plugin Data Structures
A plugin library file includes descriptor information to indicate what plugins it contains.
If the plugin library contains any server plugins, it must include the following descriptor information:
A library descriptor indicates the general server plugin API version number used by the library and contains a general plugin descriptor for each server plugin in the library. To provide the framework for this descriptor, invoke two macros from the
plugin.h
header file:mysql_declare_plugin(name) ... one or more server plugin descriptors here ... mysql_declare_plugin_end;
The macros expand to provide a declaration for the API version automatically. You must provide the plugin descriptors.
Within the library descriptor, each general server plugin is described by a
st_mysql_plugin
structure. This plugin descriptor structure contains information that is common to every type of server plugin: A value that indicates the plugin type; the plugin name, author, description, and license type; pointers to the initialization and deinitialization functions that the server invokes when it loads and unloads the plugin, and pointers to any status or system variables the plugin implements.Each general server plugin descriptor within the library descriptor also contains a pointer to a type-specific plugin descriptor. The structure of the type-specific descriptors varies from one plugin type to another because each type of plugin can have its own API. A type-specific plugin descriptor contains a type-specific API version number and pointers to the functions that are needed to implement that plugin type. For example, a full-text parser plugin has initialization and deinitialization functions, and a main parsing function. The server invokes these functions when it uses the plugin to parse text.
The plugin library also contains the interface functions that are referenced by the general and type-specific descriptors for each plugin in the library.
If the plugin library contains a client plugin, it must
include a descriptor for the plugin. The descriptor begins
with a fixed set of members common to all client plugins,
followed by any members specific to the plugin type. To
provide the descriptor framework, invoke two macros from the
client_plugin.h
header file:
mysql_declare_client_plugin(plugin_type)
... members common to all client plugins ...
... type-specific extra members ...
mysql_end_client_plugin;
The plugin library also contains any interface functions referenced by the client descriptor.
The mysql_declare_plugin()
and
mysql_declare_client_plugin()
macros differ
somewhat in how they can be invoked, which has implications
for the contents of plugin libraries. The following guidelines
summarize the rules:
mysql_declare_plugin()
andmysql_declare_client_plugin()
can both be used in the same source file, which means that a plugin library can contain both server and client plugins. However, each ofmysql_declare_plugin()
andmysql_declare_client_plugin()
can be used at most once.mysql_declare_plugin()
permits multiple server plugin declarations, so a plugin library can contain multiple server plugins.mysql_declare_client_plugin()
permits only a single client plugin declaration. To create multiple client plugins, separate plugin libraries must be used.
When a client program looks for a client plugin that is in a
plugin library and not built into
libmysqlclient
, it looks for a file with a
base name that is the same as the plugin name. For example, if
a program needs to use a client authentication plugin named
auth_xxx
on a system that uses
.so
as the library suffix, it looks in
the file named auth_xxx.so
. (On OS X, the
program looks first for auth_xxx.dylib
,
then for auth_xxx.so
.) For this reason,
if a plugin library contains a client plugin, the library must
have the same base name as that plugin.
The same is not true for a library that contains server
plugins. The --plugin-load
option and the INSTALL PLUGIN
statement provide the library file name explicitly, so there
need be no explicit relationship between the library name and
the name of any server plugins it contains.
29.2.4.2.1 Server Plugin Library and Plugin Descriptors
Every plugin library that contains server plugins must include a library descriptor that contains the general plugin descriptor for each server plugin in the file. This section discusses how to write the library and general descriptors for server plugins.
The library descriptor must define two symbols:
_mysql_plugin_interface_version_
specifies the version number of the general plugin framework. This is given by theMYSQL_PLUGIN_INTERFACE_VERSION
symbol, which is defined in theplugin.h
file._mysql_plugin_declarations_
defines an array of plugin declarations, terminated by a declaration with all members set to 0. Each declaration is an instance of thest_mysql_plugin
structure (also defined inplugin.h
). There must be one of these for each server plugin in the library.
If the server does not find those two symbols in a library, it does not accept it as a legal plugin library and rejects it with an error. This prevents use of a library for plugin purposes unless it was built specifically as a plugin library.
The conventional way to define the two required symbols is
by using the mysql_declare_plugin()
and
mysql_declare_plugin_end
macros from the
plugin.h
file:
mysql_declare_plugin(name)
... one or more server plugin descriptors here ...
mysql_declare_plugin_end;
Each server plugin must have a general descriptor that
provides information to the server plugin API. The general
descriptor has the same structure for all plugin types. The
st_mysql_plugin
structure in the
plugin.h
file defines this descriptor:
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 */
};
The st_mysql_plugin
descriptor structure
members are used as follows. char *
members should be specified as null-terminated strings.
type
: The plugin type. This must be one of the plugin-type values fromplugin.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 */ ...
For example, for a full-text parser plugin, the
type
value isMYSQL_FTPARSER_PLUGIN
.info
: A pointer to the type-specific descriptor for the plugin. This descriptor's structure depends on the particular type of plugin, unlike that of the general plugin descriptor structure. For version-control purposes, the first member of the type-specific descriptor for every plugin type is expected to be the interface version for the type. This enables the server to check the type-specific version for every plugin no matter its type. Following the version number, the descriptor includes any other members needed, such as callback functions and other information needed by the server to invoke the plugin properly. Later sections on writing particular types of server plugins describe the structure of their type-specific descriptors.name
: A string that gives the plugin name. This is the name that will be listed in themysql.plugin
table and by which you refer to the plugin in SQL statements such asINSTALL PLUGIN
andUNINSTALL PLUGIN
, or with the--plugin-load
option. The name is also visible in theINFORMATION_SCHEMA.PLUGINS
table or the output fromSHOW PLUGINS
.The plugin name should not begin with the name of any server option. If it does, the server will fail to initialize it. For example, the server has a
--socket
option, so you should not use a plugin name such assocket
,socket_plugin
, and so forth.author
: A string naming the plugin author. This can be whatever you like.desc
: A string that provides a general description of the plugin. This can be whatever you like.license
: The plugin license type. The value can be one ofPLUGIN_LICENSE_PROPRIETARY
,PLUGIN_LICENSE_GPL
, orPLUGIN_LICENSE_BSD
.init
: A once-only initialization function, orNULL
if there is no such function. The server executes this function when it loads the plugin, which happens forINSTALL PLUGIN
or, for plugins listed in themysql.plugin
table, at server startup. The function takes one argument that points to the internal structure used to identify the plugin. It returns zero for success and nonzero for failure.deinit
: A once-only deinitialization function, orNULL
if there is no such function. The server executes this function when it unloads the plugin, which happens forUNINSTALL PLUGIN
or, for plugins listed in themysql.plugin
table, at server shutdown. The function takes one argument that points to the internal structure used to identify the plugin It returns zero for success and nonzero for failure.version
: The plugin version number. When the plugin is installed, this value can be retrieved from theINFORMATION_SCHEMA.PLUGINS
table. The value includes major and minor numbers. If you write the value as a hex constant, the format is0x
, whereMMNN
MM
andNN
are the major and minor numbers, respectively. For example,0x0302
represents version 3.2.status_vars
: A pointer to a structure for status variables associated with the plugin, orNULL
if there are no such variables. When the plugin is installed, these variables are displayed in the output of theSHOW STATUS
statement.The
status_vars
member, if notNULL
, points to an array ofst_mysql_show_var
structures that describe status variables. See Section 29.2.4.2.2, “Server Plugin Status and System Variables”.system_vars
: A pointer to a structure for system variables associated with the plugin, orNULL
if there are no such variables. These options and system variables can be used to help initialize variables within the plugin. When the plugin is installed, these variables are displayed in the output of theSHOW VARIABLES
statement.The
system_vars
member, if notNULL
, points to an array ofst_mysql_sys_var
structures that describe system variables. See Section 29.2.4.2.2, “Server Plugin Status and System Variables”.__reserved1
: A placeholder for the future. It should be set toNULL
.flags
: Plugin flags. Individual bits correspond to different flags. The value should be set to the OR of the applicable flags. These flags are available:#define PLUGIN_OPT_NO_INSTALL 1UL /* Not dynamically loadable */ #define PLUGIN_OPT_NO_UNINSTALL 2UL /* Not dynamically unloadable */
PLUGIN_OPT_NO_INSTALL
indicates that the plugin cannot be loaded at runtime with theINSTALL PLUGIN
statement. This is appropriate for plugins that must be loaded at server startup with the--plugin-load
option.PLUGIN_OPT_NO_UNINSTALL
indicates that the plugin cannot be unloaded at runtime with theUNINSTALL PLUGIN
statement.
The server invokes the init
and
deinit
functions in the general plugin
descriptor only when loading and unloading the plugin. They
have nothing to do with use of the plugin such as happens
when an SQL statement causes the plugin to be invoked.
For example, the descriptor information for a library that
contains a single full-text parser plugin named
simple_parser
looks like this:
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;
For a full-text parser plugin, the type must be
MYSQL_FTPARSER_PLUGIN
. This is the value
that identifies the plugin as being legal for use in a
WITH PARSER
clause when creating a
FULLTEXT
index. (No other plugin type is
legal for this clause.)
plugin.h
defines the
mysql_declare_plugin()
and
mysql_declare_plugin_end
macros like
this:
#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}}
Those declarations define the
_mysql_plugin_interface_version_
symbol
only if the MYSQL_DYNAMIC_PLUGIN
symbol
is defined. This means that
-DMYSQL_DYNAMIC_PLUGIN
must be provided
as part of the compilation command to build the plugin as
a shared library.
When the macros are used as just shown, they expand to the
following code, which defines both of the required symbols
(_mysql_plugin_interface_version_
and
_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}}
};
The preceding example declares a single plugin in the
general descriptor, but it is possible to declare multiple
plugins. List the declarations one after the other between
mysql_declare_plugin()
and
mysql_declare_plugin_end
, separated by
commas.
MySQL server plugins must be compiled as C++ code. One C++
feature that you should not use is nonconstant variables to
initialize global structures. Members of structures such as
the st_mysql_plugin
structure should be
initialized only with constant variables. The
simple_parser
descriptor shown earlier is
permissible in a C++ plugin because it satisfies that
requirement:
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;
Here is another valid way to write the general descriptor. It uses constant variables to indicate the plugin name, author, and description:
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;
However, the following general descriptor is invalid. It uses structure members to indicate the plugin name, author, and description, but structures are not considered constant initializers in 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;
The server plugin interface enables plugins to expose status
and system variables using the
status_vars
and
system_vars
members of the general plugin
descriptor.
The status_vars
member of the general
plugin descriptor, if not 0, points to an array of
st_mysql_show_var
structures, each of
which describes one status variable, followed by a structure
with all members set to 0. The
st_mysql_show_var
structure has this
definition:
struct st_mysql_show_var {
const char *name;
char *value;
enum enum_mysql_show_type type;
};
The following table shows the permissible status variable
type
values and what the corresponding
variable should be.
Table 29.1 Server Plugin Status Variable Types
Variable Type | Meaning |
---|---|
SHOW_BOOL |
Pointer to a boolean variable |
SHOW_INT |
Pointer to an integer variable |
SHOW_LONG |
Pointer to a long integer variable |
SHOW_LONGLONG |
Pointer to a longlong integer variable |
SHOW_CHAR |
A string |
SHOW_CHAR_PTR |
Pointer to a string |
SHOW_ARRAY |
Pointer to another st_mysql_show_var array |
SHOW_FUNC |
Pointer to a function |
SHOW_DOUBLE |
Pointer to a double |
For the SHOW_FUNC
type, the function is
called and fills in its out
parameter,
which then provides information about the variable to be
displayed. The function has this signature:
#define SHOW_VAR_FUNC_BUFF_SIZE 1024
typedef int (*mysql_show_var_func) (void *thd,
struct st_mysql_show_var *out,
char *buf);
The system_vars
member, if not 0, points
to an array of st_mysql_sys_var
structures, each of which describes one system variable
(which can also be set from the command-line or
configuration file), followed by a structure with all
members set to 0. The st_mysql_sys_var
structure is defined as follows:
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*);
};
Additional fields are append as required depending upon the flags.
For convenience, a number of macros are defined that make creating new system variables within a plugin much simpler.
Throughout the macros, the following fields are available:
name
: An unquoted identifier for the system variable.varname
: The identifier for the static variable. Where not available, it is the same as thename
field.opt
: Additional use flags for the system variable. The following table shows the permissible flags.Table 29.2 Server Plugin System Variable Flags
Flag Value Description PLUGIN_VAR_READONLY
The system variable is read only PLUGIN_VAR_NOSYSVAR
The system variable is not user visible at runtime PLUGIN_VAR_NOCMDOPT
The system variable is not configurable from the command line PLUGIN_VAR_NOCMDARG
No argument is required at the command line (typically used for boolean variables) PLUGIN_VAR_RQCMDARG
An argument is required at the command line (this is the default) PLUGIN_VAR_OPCMDARG
An argument is optional at the command line PLUGIN_VAR_MEMALLOC
Used for string variables; indicates that memory is to be allocated for storage of the string comment
: A descriptive comment to be displayed in the server help message.NULL
if this variable is to be hidden.check
: The check function,NULL
for default.update
: The update function,NULL
for default.default
: The variable default value.minimum
: The variable minimum value.maximum
: The variable maximum value.blocksize
: The variable block size. When the value is set, it is rounded to the nearest multiple ofblocksize
.
A system variable may be accessed either by using the static
variable directly or by using the
SYSVAR()
accessor macro. The
SYSVAR()
macro is provided for
completeness. Usually it should be used only when the code
cannot directly access the underlying variable.
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;
Session variables may be accessed only through the
THDVAR()
accessor macro. For example:
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;
}
All global and session system variables must be published to
mysqld before use. This is done by
constructing a NULL
-terminated array of
the variables and linking to it in the plugin public
interface. For example:
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;
The following convenience macros enable you to declare different types of system variables:
Boolean system variables of type
bool
, which is a 1-byte boolean. (0 =false
, 1 =true
)MYSQL_THDVAR_BOOL(name, opt, comment, check, update, default) MYSQL_SYSVAR_BOOL(name, varname, opt, comment, check, update, default)
String system variables of type
char*
, which is a pointer to a null-terminated string.MYSQL_THDVAR_STR(name, opt, comment, check, update, default) MYSQL_SYSVAR_STR(name, varname, opt, comment, check, update, default)
Integer system variables, of which there are several varieties.
An
int
system variable, which is typically a 4-byte signed word.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)
An
unsigned int
system variable, which is typically a 4-byte unsigned word.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)
A
long
system variable, which is typically either a 4- or 8-byte signed word.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)
An
unsigned long
system variable, which is typically either a 4- or 8-byte unsigned word.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)
A
long long
system variable, which is typically an 8-byte signed word.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)
An
unsigned long long
system variable, which is typically an 8-byte unsigned word.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)
A
double
system variable, which is typically an 8-byte signed word.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)
An
unsigned long
system variable, which is typically either a 4- or 8-byte unsigned word. The range of possible values is an ordinal of the number of elements in thetypelib
, starting from 0.MYSQL_THDVAR_ENUM(name, opt, comment, check, update, default, typelib) MYSQL_SYSVAR_ENUM(name, varname, opt, comment, check, update, default, typelib)
An
unsigned long long
system variable, which is typically an 8-byte unsigned word. Each bit represents an element in thetypelib
.MYSQL_THDVAR_SET(name, opt, comment, check, update, default, typelib) MYSQL_SYSVAR_SET(name, varname, opt, comment, check, update, default, typelib)
Internally, all mutable and plugin system variables are
stored in a HASH
structure.
Display of the server command-line help text is handled by
compiling a DYNAMIC_ARRAY
of all
variables relevant to command-line options, sorting them,
and then iterating through them to display each option.
When a command-line option has been handled, it is then
removed from the argv
by the
handle_option()
function
(my_getopt.c
); in effect, it is
consumed.
The server processes command-line options during the plugin installation process, immediately after the plugin has been successfully loaded but before the plugin initialization function has been called
Plugins loaded at runtime do not benefit from any
configuration options and must have usable defaults. Once
they are installed, they are loaded at
mysqld initialization time and
configuration options can be set at the command line or
within my.cnf
.
Plugins should consider the thd
parameter
to be read only.
Each client plugin must have a descriptor that provides information to the client plugin API. The descriptor structure begins with a fixed set of members common to all client plugins, followed by any members specific to the plugin type.
The st_mysql_client_plugin
structure in
the client_plugin.h
file defines a
“generic” descriptor that contains the common
members:
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 *);
};
The common st_mysql_client_plugin
descriptor structure members are used as follows.
char *
members should be specified as
null-terminated strings.
type
: The plugin type. This must be one of the plugin-type values fromclient_plugin.h
, such asMYSQL_CLIENT_AUTHENTICATION_PLUGIN
.interface_version
: The plugin interface version. For example, this isMYSQL_CLIENT_AUTHENTICATION_PLUGIN_INTERFACE_VERSION
for an authentication plugin.name
: A string that gives the plugin name. This is the name by which you refer to the plugin when you callmysql_options()
with theMYSQL_DEFAULT_AUTH
option or specify the--default-auth
option to a MySQL client program.author
: A string naming the plugin author. This can be whatever you like.desc
: A string that provides a general description of the plugin. This can be whatever you like.version
: The plugin version as an array of three integers indicating the major, minor, and teeny versions. For example,{1,2,3}
indicates version 1.2.3.license
: A string that specifies the license type.mysql_api
: For internal use. Specify it asNULL
in the plugin descriptor.init
: A once-only initialization function, orNULL
if there is no such function. The client library executes this function when it loads the plugin. The function returns zero for success and nonzero for failure.The
init
function uses its first two arguments to return an error message if an error occurs. The first argument is a pointer to achar
buffer, and the second argument indicates the buffer length. Any message returned by theinit
function must be null-terminated, so the maximum message length is the buffer length minus one. The next arguments are passed tomysql_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, orNULL
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, orNULL
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 29.2.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
Section 28.7.17, “C API Client Plugin Functions”.
Traduction non disponible
Le manuel MySQL n'est pas encore traduit en français sur l'infobrol. Seule la version anglaise est disponible pour l'instant.
Document créé le 26/06/2006, dernière modification le 26/10/2018
Source du document imprimé : https://www.gaudry.be/mysql-rf-plugin-data-structures.html
L'infobrol est un site personnel dont le contenu n'engage que moi. Le texte est mis à disposition sous licence CreativeCommons(BY-NC-SA). Plus d'info sur les conditions d'utilisation et sur l'auteur.
Références
Ces références et liens indiquent des documents consultés lors de la rédaction de cette page, ou qui peuvent apporter un complément d'information, mais les auteurs de ces sources ne peuvent être tenus responsables du contenu de cette page.
L'auteur de ce site est seul responsable de la manière dont sont présentés ici les différents concepts, et des libertés qui sont prises avec les ouvrages de référence. N'oubliez pas que vous devez croiser les informations de sources multiples afin de diminuer les risques d'erreurs.