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
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_pluginstructure. 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.
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_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 of
mysql_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 macOS,
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
option and the
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.