24.2.5 MySQL Services for Plugins

MySQL server plugins have access to server services. The services interface exposes server functionality that plugins can call. It complements the plugin API and has these characteristics:

Current services include the following, and others can be implemented:

The plugin services interface differs from the plugin API as follows:

For developers who wish to modify the server to add a new service, see MySQL Services for Plugins.

The remainder of this section describes how a plugin uses server functionality that is available as a service. See also the source for the daemon example plugin, which uses the my_snprintf service. Within a MySQL source distribution, that plugin is located in the plugin/daemon_example directory.

To determine what services exist and what functions they provide, look in the include/mysql directory of a MySQL source distribution. The relevant files are:

Each service-specific header should contain comments that provide full usage documentation for a given service, including what service functions are available, their calling sequences, and return values.

To use a service or services from within a plugin, the plugin source file must include the plugin.h header file to access service-related information:

#include <mysql/plugin.h>

This does not represent any additional setup cost. A plugin must include that file anyway because it contains definitions and structures that every plugin needs.

To access a service, a plugin calls service functions like any other function. For example, to format a string into a buffer for printing, call the my_snprintf() function provided by the service of the same name:

char buffer[BUFFER_SIZE];

my_snprintf(buffer, sizeof(buffer), format_string, argument_to_format, ...);

To report an error that the server will write to the error log, first choose an error level. mysql/service_my_plugin_log.h defines these levels:

enum plugin_log_level
{
  MY_ERROR_LEVEL,
  MY_WARNING_LEVEL,
  MY_INFORMATION_LEVEL
};  

Then invoke my_plugin_log_message():

int my_plugin_log_message(MYSQL_PLUGIN *plugin, enum plugin_log_level level,
                          const char *format, ...);

For example:

my_plugin_log_message(plugin_ptr, MY_ERROR_LEVEL, "Cannot initialize plugin");

When you build your plugin, you must link in the libmysqlservices library. Use the -lmysqlservices flag at link time. For example, for CMake, put this in the top-level CMakeLists.txt file:

FIND_LIBRARY(MYSQLSERVICES_LIB mysqlservices 
 PATHS "${MYSQL_SRCDIR}/libservices" NO_DEFAULT_PATH)

Put this in the CMakeLists.txt file in the directory containing the plugin source:

# the plugin needs the mysql services library for error logging
TARGET_LINK_LIBRARIES (your_plugin_library_name ${MYSQLSERVICES_LIB})