Each client plugin has a declaration that provides the interface to the client library. The structure to declare the plugin begins with a fixed set of members common to all plugin types, followed by members specific to the plugin type.
The st_mysql_client_plugin structure is a
“generic” descriptor that contains the common
members:
/* generic plugin header structure */
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 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_VERSIONfor 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_AUTHoption or specify the--default-authoption to the mysql client.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 asNULLin the plugin descriptor.init: A once-only initialization function, orNULLif 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
initfunction uses its first two arguments to return an error message if an error occurs. The first argument is a pointer to acharbuffer, and the second argument indicates the buffer length. Any message returned by theinitfunction 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, orNULLif 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, orNULLif there is no such function. The function takes two arguments representing the option name and a pointer to its value.
The declaration for a specific client plugin type begins with
the common members, followed by any 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) ...common members fromnametooptions ... ...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_init,
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.
The main function, my_auth_main(), is
declared like this:
int my_auth_main(MYSQL_PLUGIN_VIO *vio, MYSQL *mysql);
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, but each 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.
Normally, a client program causes a plugin to be loaded and
used 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"; mysql_options(&mysql, MYSQL_PLUGIN_DIR, plugin_dir); mysql_options(&mysql, MYSQL_DEFAULT_AUTH, default_auth);
Should a client program require lower-level plugin management,
the client library contains functions that take an
st_mysql_client_plugin argument. See
Section 22.9.10, “C API Client Plugin Functions”.