23.2.4.4. Client Plugin API Data Structures

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 from client_plugin.h, such as MYSQL_CLIENT_AUTHENTICATION_PLUGIN.

  • interface_version: The plugin interface version. For example, this is MYSQL_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 call mysql_options() with the MYSQL_DEFAULT_AUTH option or specify the --default-auth option 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 as NULL in the plugin descriptor.

  • init: A once-only initialization function, or NULL 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 a char buffer, and the second argument indicates the buffer length. Any message returned by the init function must be null-terminated, so the maximum message length is the buffer length minus one. The next arguments are passed to mysql_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, or NULL 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, or NULL if 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 from name to options ...
   ... 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() and mysql_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”.

Copyright © 2010-2024 Platon Technologies, s.r.o.           Home | Man pages | tLDP | Documents | Utilities | About
Design by styleshout