23.2.4.2. Сменные Структуры данных

mysql_declare_client_plugin(plugin_type)   ... members common to all client plugins ...   ... type-specific extra members ...mysql_end_client_plugin;

Каждая сменная библиотека, которая содержит плагины сервера, должна включать дескриптор библиотеки, который содержит общий сменный дескриптор для каждого плагина сервера в файле. Этот раздел обсуждает, как записать библиотеку и общие дескрипторы для плагинов сервера.

Дескриптор библиотеки должен определить два символа:

Если сервер не находит те два символа в библиотеке, он не принимает это как юридическую сменную библиотеку и отклоняет это с ошибкой. Это предотвращает использование библиотеки в сменных целях, если оно не было создано определенно как сменная библиотека.

Стандартный способ определить два необходимых символа при использовании mysql_declare_plugin() и mysql_declare_plugin_end макросы от plugin.h файл:

mysql_declare_plugin(name) ... one or more server plugin descriptors here ...mysql_declare_plugin_end;

У каждого плагина сервера должен быть общий дескриптор, который предоставляет информацию API плагина сервера. У общего дескриптора есть та же самая структура для всех сменных типов. st_mysql_plugin структура в plugin.h файл определяет этот дескриптор:

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 */};

st_mysql_plugin элементы структуры дескриптора используются следующим образом. char * элементы должны быть определены как завершенные нулем строки.

Сервер вызывает init и deinit функции в общем сменном дескрипторе только, когда загрузка и разгрузка плагин. Им нечего делать к использованию плагина с того, который происходит, когда SQL-оператор заставляет плагин быть вызванным.

Например, информация о дескрипторе для библиотеки, которая содержит единственный полнотекстовый названный плагин синтаксического анализатора simple_parser похож на это:

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;

Для полнотекстового плагина синтаксического анализатора тип должен быть MYSQL_FTPARSER_PLUGIN. Это - значение, которое идентифицирует плагин, как являющийся законным для использования в a WITH PARSER пункт, создавая a FULLTEXT индексировать. (Никакой другой сменный тип не является законным для этого пункта.)

plugin.h определяет mysql_declare_plugin() и mysql_declare_plugin_end макросы как это:

#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}}

Когда макросы используются как только показано, они расширяются до следующего кода, который определяет оба из необходимых символов (_mysql_plugin_interface_version_ и _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}}};

Предыдущий пример объявляет единственный плагин в общем дескрипторе, но возможно объявить многократные плагины. Перечислите объявления один за другим между mysql_declare_plugin() и mysql_declare_plugin_end, разделенный запятыми.

Плагины сервера MySQL могут быть записаны в C или C++ (или другой язык, который может использовать соглашения о вызовах C). Если Вы пишете плагин C++, одна функция C++, которую недопустимо использовать, является непостоянными переменными, чтобы инициализировать глобальные структуры. Элементы структур такой как st_mysql_plugin структура должна быть инициализирована только с постоянными переменными. simple_parser дескриптор, показанный ранее, допустим в плагине C++, потому что удовлетворяет что требование:

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;

Вот другой допустимый способ записать общий дескриптор. Это использует постоянные переменные, чтобы указать на сменное имя, автора, и описание:

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;

Однако, следующий общий дескриптор недопустим. Это использует элементы структуры, чтобы указать на сменное имя, автора, и описание, но структуры не считают постоянными инициализаторами в 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;

Интерфейс плагина сервера позволяет плагинам представить состояние и системные переменные, используя status_vars и system_vars элементы общего сменного дескриптора.

status_vars элемент общего сменного дескриптора, если не 0, указывает массиву st_mysql_show_var структуры, каждая из которых описывает одну переменную состояния, сопровождаемую структурой со всем задействованным набором к 0. st_mysql_show_var у структуры есть это определение:

struct st_mysql_show_var {  const char *name;  char *value;  enum enum_mysql_show_type type;};

Когда плагин устанавливается, сменное имя и name к значению присоединяются с подчеркиванием, чтобы сформировать имя, выведенное на экран SHOW STATUS.

Следующая таблица показывает допустимую переменную состояния type значения и какова соответствующая переменная должна быть.

Для SHOW_FUNC введите, функция вызывается и заполняет out параметр, который тогда предоставляет информацию о переменной, которая будет выведена на экран. У функции есть эта подпись:

#define SHOW_VAR_FUNC_BUFF_SIZE 1024typedef int (*mysql_show_var_func) (void *thd,                                    struct st_mysql_show_var *out,                                    char *buf);

system_vars элемент, если не 0, указывает массиву st_mysql_sys_var структуры, каждая из которых описывает одну системную переменную (который может также быть установлен от командной строки или конфигурационного файла), сопровождаемый структурой со всем задействованным набором к 0. st_mysql_sys_var структура определяется следующим образом:

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*);};

Дополнительные поля, добавляют как требуется в зависимости от флагов.

Для удобства много макросов определяются, которые делают создающие новые системные переменные в пределах плагина намного более простыми.

Всюду по макросам следующие поля доступны:

К системной переменной можно получить доступ или при использовании статической переменной непосредственно или при использовании SYSVAR()макрос средства доступа. SYSVAR() макрос обеспечивается для законченности. Обычно это должно использоваться только, когда код не может непосредственно получить доступ к базовой переменной.

Например:

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;

К переменным сеанса можно получить доступ только через THDVAR() макрос средства доступа. Например:

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;   }

Вся глобальная переменная и системные переменные сеанса должны быть опубликованы к mysqld перед использованием. Это делается, создавая a NULL- завершенный массив переменных и соединения с этим в сменном открытом интерфейсе. Например:

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;

Следующие макросы удобства позволяют Вам объявить различные типы системных переменных:

Внутренне, все изменчивые и сменные системные переменные сохранены в a HASH структура.

Дисплей текста справки командной строки сервера обрабатывается, компилируя a DYNAMIC_ARRAY из всех переменных, относящихся к параметрам командной строки, сортируя их, и затем выполняя итерации через них, чтобы вывести на экран каждую опцию.

Когда параметр командной строки был обработан, он тогда удаляется из argv handle_option() функция (my_getopt.c); в действительности это используется.

Параметры командной строки серверных процессов во время сменного процесса установки, сразу после того, как плагин был успешно загружен, но прежде, чем сменная функция инициализации была вызвана

Плагины, загруженные во времени выполнения, не извлекают выгоду ни из каких параметров конфигурации и должны иметь применимые значения по умолчанию. Как только они устанавливаются, они загружаются в mysqld время инициализации, и параметры конфигурации могут быть установлены в командной строке или в пределах my.cnf.

Плагины должны рассмотреть thd параметр, чтобы быть только для чтения.

У каждого клиентского плагина должен быть дескриптор, который предоставляет информацию клиентскому API плагина. Структура дескриптора начинается с фиксированного набора элементов, характерных для всех клиентских плагинов, сопровождаемых любыми элементами, определенными для сменного типа.

st_mysql_client_plugin структура в client_plugin.h файл определяет "универсальный" дескриптор, который содержит общие элементы:

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 *);};

Общее st_mysql_client_plugin элементы структуры дескриптора используются следующим образом. char * элементы должны быть определены как завершенные нулем строки.

Для данного клиентского типа плагина общие элементы дескриптора могут сопровождаться дополнительными элементами, необходимыми, чтобы реализовать плагины того типа. Например, st_mysql_client_plugin_AUTHENTICATION у структуры для плагинов аутентификации есть функция в конце, который клиентская библиотека вызывает, чтобы выполнить аутентификацию.

Чтобы объявить плагин, используйте mysql_declare_client_plugin() и mysql_end_client_plugin макросы:

mysql_declare_client_plugin(plugin_type)   ... members common to all client plugins ...   ... type-specific extra members ...mysql_end_client_plugin;

Не определяйте type или interface_version элемент явно. mysql_declare_client_plugin() макрос использует plugin_type параметр, чтобы генерировать их значения автоматически. Например, объявите клиентский плагин аутентификации как это:

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_mainmysql_end_client_plugin;

Это объявление использует AUTHENTICATION параметр установленному type и interface_version элементы к MYSQL_CLIENT_AUTHENTICATION_PLUGIN и MYSQL_CLIENT_AUTHENTICATION_PLUGIN_INTERFACE_VERSION.

В зависимости от сменного типа у дескриптора могут быть другие элементы после общих элементов. Например, для плагина аутентификации, есть функция (my_auth_main() в дескрипторе, только показанном), который обрабатывает передачу с сервером. См. Раздел 23.2.4.9, "Пишущий Плагины Аутентификации".

Обычно, клиентская программа, которая поддерживает использование плагинов аутентификации, заставляет плагин быть загруженным, вызывая mysql_options() установить MYSQL_DEFAULT_AUTH и MYSQL_PLUGIN_DIR опции:

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);

Как правило, программа также примет --plugin-dir и --default-auth опции, которые позволяют пользователям переопределить значения по умолчанию.

Если клиентская программа требует сменного управления низшего уровня, клиентская библиотека содержит функции, которые берут st_mysql_client_plugin параметр. См. Раздел 22.8.14, "Клиентские Функции Плагина API C".