PDF (US Ltr)
- 26.8Mb
PDF (A4)
- 26.8Mb
プラグインライブラリファイルには、それに格納されているプラグインを示すディスクリプタ情報が含まれています。
プラグインライブラリにサーバープラグインが含まれている場合、プラグインライブラリには次のディスクリプタ情報が含まれている必要があります。
-
ライブラリディスクリプタは、ライブラリによって使用される一般的なサーバープラグイン API バージョン番号を示し、ライブラリ内の各サーバープラグインの一般プラグインディスクリプタを含んでいます。このディスクリプタのフレームワークを提供するには、
plugin.hヘッダーファイルから 2 つのマクロを呼び出します。mysql_declare_plugin(name) ... one or more server plugin descriptors here ... mysql_declare_plugin_end;マクロが展開され、API バージョンの宣言が自動的に提供されます。プラグインディスクリプタを指定する必要があります。
ライブラリディスクリプタ内の各一般的なサーバープラグインは、
st_mysql_plugin構造体によって記述されます。このプラグインのディスクリプタ構造体には、すべてのタイプのサーバープラグインに共通する情報 (プラグインタイプを示す値、プラグイン名、作成者、説明、ライセンスタイプ、サーバーがプラグインをロードおよびアンロードするときに呼び出す初期化関数と初期化解除関数へのポインタ、およびプラグインが実装するステータス変数またはシステム変数へのポインタ) が含まれています。ライブラリディスクリプタ内の各一般的なサーバープラグインディスクリプタには、タイプ固有のプラグインディスクリプタへのポインタも含まれています。プラグインはタイプごとに独自の API を持つことがあるため、タイプ固有のディスクリプタの構造体はプラグインタイプによって異なります。タイプ固有のプラグインディスクリプタには、タイプ固有の API バージョン番号およびそのプラグインタイプを実装するために必要な関数へのポインタが含まれています。たとえば、全文パーサープラグインには、初期化関数と初期化解除関数、およびメインの構文解析関数があります。サーバーはプラグインを使用してテキストを構文解析するときに、これらの関数を呼び出します。
プラグインライブラリには、ライブラリ内の各プラグインの一般ディスクリプタおよびタイプ固有のディスクリプタによって参照されるインタフェース関数も格納されています。
プラグインライブラリにクライアントプラグインが格納されている場合は、そのプラグインのディスクリプタが含まれている必要があります。そのディスクリプタはすべてのクライアントプラグインに共通する固定された一連のメンバーで始まり、そのあとにプラグインタイプ固有のメンバーが続きます。ディスクリプタフレームワークを提供するには、client_plugin.h ヘッダーファイルから 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_client_plugin() マクロは呼び出す方法が若干異なり、これはプラグインライブラリの内容が関係しています。次のガイドラインはこのルールを要約しています。
mysql_declare_plugin()およびmysql_declare_client_plugin()は同じソースファイル内で使用できます。これは、1 つのプラグインライブラリにサーバープラグインとクライアントプラグインを両方格納できることを意味します。ただし、mysql_declare_plugin()とmysql_declare_client_plugin()はそれぞれ 1 回しか使用できません。mysql_declare_plugin()は複数のサーバープラグイン宣言が可能であるため、1 つのプラグインライブラリに複数のサーバープラグインを格納できます。mysql_declare_client_plugin()は、単一のクライアントプラグイン宣言のみを行うことができます。複数のクライアントプラグインを作成するには、別々のプラグインライブラリを使用する必要があります。
プラグインライブラリに存在して libmysqlclient に組み込まれていないクライアントプラグインをクライアントプログラムが探す場合、クライアントプログラムはプラグイン名と同じベース名を持つファイルを探します。たとえば、ライブラリのサフィクスとして .so を使用するシステムで、auth_xxx という名前のクライアント認証プラグインをプログラムで使用する必要がある場合、プログラムは auth_xxx.so という名前のファイルを探します。(OS X では、プログラムはまず auth_xxx.dylib を探し、次に auth_xxx.so を探します。)このため、プラグインライブラリにクライアントプラグインが格納されている場合、ライブラリはそのプラグインと同じベース名である必要があります。
サーバープラグインを格納しているライブラリの場合は異なります。--plugin-load オプションおよび INSTALL PLUGIN ステートメントはライブラリファイル名を明示的に指定するため、ライブラリ名とライブラリに格納されているサーバープラグインの名前に明示的な関係がある必要はありません。
サーバープラグインを格納するすべてのプラグインライブラリには、ファイル内の各サーバープラグインの一般プラグインディスクリプタが含まれているライブラリディスクリプタが格納されている必要があります。このセクションでは、サーバープラグイン用のライブラリおよび一般ディスクリプタを記述する方法について説明します。
ライブラリディスクリプタは 2 つのシンボルを定義する必要があります。
_mysql_plugin_interface_version_は全般的なプラグインフレームワークのバージョン番号を指定します。これはMYSQL_PLUGIN_INTERFACE_VERSIONシンボルを使用して指定し、このシンボルはplugin.hファイルに定義します。_mysql_plugin_declarations_は、プラグイン宣言の配列を定義し、すべてのメンバーが 0 に設定された宣言で終わります。各宣言は、st_mysql_plugin構造体のインスタンスです (plugin.h内でも定義されます)。ライブラリ内のサーバープラグインごとに、これらのいずれかが必要となります。
サーバーがライブラリ内でこれらの 2 つのシンボルを見つけることができない場合、サーバーはこれを正当なプラグインライブラリとして受け入れず、拒否してエラーを発生させます。これにより、ライブラリをプラグインライブラリとして特別にビルドしないかぎり、プラグイン用にライブラリを使用できなくなります。
必須の 2 つのシンボルを定義する通常の方法は、plugin.h ファイルから mysql_declare_plugin() マクロおよび mysql_declare_plugin_end マクロを使用することです。
mysql_declare_plugin(name)
... one or more server plugin descriptors here ...
mysql_declare_plugin_end;
各サーバープラグインには、サーバープラグイン API に情報を提供する一般ディスクリプタが必要となります。一般ディスクリプタの構造体はすべてのプラグインタイプで同じです。plugin.h ファイル内の st_mysql_plugin 構造体によって、このディスクリプタが定義されます。
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 * メンバーは、NULL で終わる文字列として指定してください。
-
type: プラグインの型。これはplugin.hのプラグインタイプ値のいずれかである必要があります。/* The allowable types of plugins */ #define MYSQL_UDF_PLUGIN 0 /* User-defined function */ #define MYSQL_STORAGE_ENGINE_PLUGIN 1 /* Storage Engine */ #define MYSQL_FTPARSER_PLUGIN 2 /* Full-text parser plugin */ #define MYSQL_DAEMON_PLUGIN 3 /* The daemon/raw plugin type */ #define MYSQL_INFORMATION_SCHEMA_PLUGIN 4 /* The I_S plugin type */ #define MYSQL_AUDIT_PLUGIN 5 /* The Audit plugin type */ #define MYSQL_REPLICATION_PLUGIN 6 /* The replication plugin type */ #define MYSQL_AUTHENTICATION_PLUGIN 7 /* The authentication plugin type */ ...たとえば、全文パーサープラグインの場合、
type値はMYSQL_FTPARSER_PLUGINです。 info: プラグインのタイプ固有のディスクリプタへのポインタ。このディスクリプタの構造体は、一般プラグインディスクリプタ構造体とは異なり、プラグインの特定のタイプによって異なります。バージョンを制御するために、すべてのプラグインタイプのタイプ固有のディスクリプタの最初のメンバーは、タイプのインタフェースバージョンであることが予期されています。これにより、サーバーはタイプに関係なくすべてのプラグインのタイプ固有のバージョンをチェックできます。ディスクリプタには、バージョン番号のあとに、必要なほかのメンバー (サーバーがプラグインを適切に呼び出すために必要となるコールバック関数やその他の情報など) が含まれています。特定タイプのサーバープラグインの記述に関する以降のセクションでは、それらのタイプ固有のディスクリプタの構造体について説明しています。-
name: プラグイン名を指定する文字列。これはmysql.pluginテーブルに表示される名前であり、この名前を使用して、SQL ステートメント (INSTALL PLUGIN、UNINSTALL PLUGINなど) でプラグインを参照したり、--plugin-loadオプションで指定してプラグインを参照したりします。この名前は、INFORMATION_SCHEMA.PLUGINSテーブルおよびSHOW PLUGINSの出力にも表示されます。プラグイン名は、サーバーオプション名で始まらないようにしてください。そのようにした場合、サーバーはプラグインの初期化に失敗します。たとえば、サーバーには
--socketオプションがあるため、socket、socket_pluginなどのプラグイン名を使用しないでください。 author: プラグイン作成者を示す文字列。これには任意の文字列を指定できます。desc: プラグインの概要を説明する文字列。これには任意の文字列を指定できます。license: プラグインのライセンスタイプ。値にはPLUGIN_LICENSE_PROPRIETARY、PLUGIN_LICENSE_GPL、またはPLUGIN_LICENSE_BSDのいずれかを指定できます。init: 1 回だけ実行される初期化関数であり、そのような関数がない場合はNULLです。サーバーはプラグインをロードするときにこの関数を実行し、これはINSTALL PLUGINで実行されるか、mysql.pluginテーブルにリストされているプラグインの場合はサーバー起動時に実行されます。この関数は、プラグインを識別するために使用される内部構造体を指している 1 つの引数を受け取ります。成功した場合はゼロ、および失敗した場合はゼロ以外を返します。deinit: 1 回だけ実行される初期化解除関数であり、そのような関数がない場合はNULLです。サーバーはプラグインをアンロードするときにこの関数を実行し、これはUNINSTALL PLUGINで実行されるか、mysql.pluginテーブルにリストされているプラグインの場合はサーバーのシャットダウン時に実行されます。この関数は、プラグインを識別するために使用される内部構造体を指している 1 つの引数を受け取ります。成功した場合はゼロ、および失敗した場合はゼロ以外を返します。version: プラグインのバージョン番号。プラグインがインストールされている場合は、この値をINFORMATION_SCHEMA.PLUGINSテーブルから取得できます。この値にはメジャー番号とマイナー番号が含まれています。16 進数の定数として値を記述する場合、形式は0xであり、ここでMMNNMMおよびNNはそれぞれメジャー番号とマイナー番号です。たとえば、0x0302はバージョン 3.2 を表します。-
status_vars: プラグインに関連付けられているステータス変数の構造体へのポインタであり、そのような変数がない場合はNULLです。プラグインをインストールすると、これらの変数はSHOW STATUSステートメントの出力として表示されます。status_varsのメンバーは、NULLではない場合、ステータス変数を記述するst_mysql_show_var構造体の配列を指しています。セクション24.2.4.2.2「サーバープラグインのステータス変数およびシステム変数」を参照してください。 -
system_vars: プラグインに関連付けられているシステム変数の構造体へのポインタであり、そのような変数がない場合はNULLです。これらのオプションおよびシステム変数は、プラグイン内の変数を初期化するために使用できます。system_varsのメンバーは、NULLではない場合、システム変数を記述するst_mysql_sys_var構造体の配列を指しています。セクション24.2.4.2.2「サーバープラグインのステータス変数およびシステム変数」を参照してください。 __reserved1: 今後利用するためのプレースホルダ。現時点ではNULLを設定してください。-
flags: プラグインフラグ。個々のビットは各種のフラグに対応しています。この値には、該当するフラグの論理和を設定してください。次のフラグを使用できます。#define PLUGIN_OPT_NO_INSTALL 1UL /* Not dynamically loadable */ #define PLUGIN_OPT_NO_UNINSTALL 2UL /* Not dynamically unloadable */PLUGIN_OPT_NO_INSTALLは、INSTALL PLUGINステートメントを使用してプラグインを実行時にロードできないことを示します。これは、--plugin-loadオプションを使用してサーバー起動時にロードする必要があるプラグインの場合に適しています。PLUGIN_OPT_NO_UNINSTALLは、UNINSTALL PLUGINステートメントを使用してプラグインを実行時にアンロードできないことを示します。このメンバーは MySQL 5.6.3 で追加されました。
サーバーは、プラグインをロードおよびアンロードする場合にのみ、一般プラグインディスクリプタ内の 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 である必要があります。これは、FULLTEXT インデックスの作成時に WITH PARSER 句で使用する場合に、プラグインが正当なものであることを識別する値です。(ほかのプラグインタイプは、この句に対して正当ではありません。)
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_DYNAMIC_PLUGIN シンボルを定義した場合にのみ、_mysql_plugin_interface_version_ シンボルを定義します。これは、プラグインを共有ライブラリとしてビルドするためのコンパイルコマンドの一部として -DMYSQL_DYNAMIC_PLUGIN を指定する必要があることを意味します。
上記のようにマクロが使用された場合は、次のコードが展開され、必要なシンボル (_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 構造体の配列を指しており、各構造には 1 つのステータス変数が記述されていて、すべてのメンバーが 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 値、および対応する変数を示しています。
表 24.1 サーバープラグインのステータス変数のタイプ
| 変数型 | 意味 |
|---|---|
SHOW_BOOL |
ブール変数へのポインタ |
SHOW_INT |
整数変数へのポインタ |
SHOW_LONG |
long 整数変数へのポインタ |
SHOW_LONGLONG |
longlong 整数変数へのポインタ |
SHOW_CHAR |
文字列 |
SHOW_CHAR_PTR |
文字列へのポインタ |
SHOW_ARRAY |
別の st_mysql_show_var 配列へのポインタ |
SHOW_FUNC |
関数へのポインタ |
SHOW_DOUBLE |
double へのポインタ |
SHOW_FUNC タイプの場合、関数が呼び出されると関数は out パラメータに値を設定し、表示される変数に関する情報がこのパラメータによって提供されます。関数のシグネチャーは次のようになります。
#define SHOW_VAR_FUNC_BUFF_SIZE 1024
typedef int (*mysql_show_var_func) (void *thd,
struct st_mysql_show_var *out,
char *buf);
system_vars メンバーは、0 でない場合、st_mysql_sys_var 構造体の配列を指しており、各構造には 1 つのシステム変数が記述されていて (これはコマンド行または構成ファイルからも設定できます)、すべてのメンバーが 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*);
};フラグによって、追加フィールドが必要に応じて付加されます。
利便性のため、プラグイン内の新しいシステム変数の作成をより簡単にするための多数のマクロが定義されています。
マクロでは次のフィールドを使用できます。
name: システム変数の引用符で囲まれていない識別子。varname: 静的変数の識別子。識別子がない場合はnameフィールドと同じです。-
opt: システム変数に追加で使用されるフラグ。次の表は、許容されるフラグを示しています。表 24.2 サーバープラグインのシステム変数フラグ
フラグ値 説明 PLUGIN_VAR_READONLYシステム変数は読み取り専用である PLUGIN_VAR_NOSYSVARシステム変数は実行時にユーザーに表示されない PLUGIN_VAR_NOCMDOPTシステム変数はコマンド行から構成できない PLUGIN_VAR_NOCMDARGコマンド行に引数は不要である (通常はブール変数に使用します) PLUGIN_VAR_RQCMDARGコマンド行に引数が必要である (これはデフォルトです) PLUGIN_VAR_OPCMDARGコマンド行の引数はオプションである PLUGIN_VAR_MEMALLOC文字列変数に使用され、文字列の格納にメモリーが割り当てられることを示す
comment: サーバーヘルプメッセージに表示される説明コメント。この変数が非表示の場合はNULLです。check: チェック関数。デフォルトはNULLです。update: 更新関数。デフォルトはNULLです。default: 変数のデフォルト値。minimum: 変数の最小値。maximum: 変数の最大値。blocksize: 変数のブロックサイズ。値が設定されると、もっとも近いblocksizeの倍数に丸められます。
システム変数には、静的変数を使用して直接アクセスするか、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 に公開する必要があります。これは、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;次の支援マクロを使用すると、さまざまなタイプのシステム変数を宣言できます。
-
1 バイトのブール値 (0 = FALSE、1 = TRUE) である
my_bool型のブールシステム変数。MYSQL_THDVAR_BOOL(name, opt, comment, check, update, default) MYSQL_SYSVAR_BOOL(name, varname, opt, comment, check, update, default) -
NULL で終わる文字列へのポインタである
char*型の文字列システム変数。MYSQL_THDVAR_STR(name, opt, comment, check, update, default) MYSQL_SYSVAR_STR(name, varname, opt, comment, check, update, default) -
各種の整数システム変数。
-
通常は 4 バイトの符号付きワードである
intシステム変数。MYSQL_THDVAR_INT(name, opt, comment, check, update, default, min, max, blk) MYSQL_SYSVAR_INT(name, varname, opt, comment, check, update, default, minimum, maximum, blocksize) -
通常は 4 バイトの符号なしワードである
unsigned intシステム変数。MYSQL_THDVAR_UINT(name, opt, comment, check, update, default, min, max, blk) MYSQL_SYSVAR_UINT(name, varname, opt, comment, check, update, default, minimum, maximum, blocksize) -
通常は 4 バイトまたは 8 バイトの符号付きワードである
longシステム変数。MYSQL_THDVAR_LONG(name, opt, comment, check, update, default, min, max, blk) MYSQL_SYSVAR_LONG(name, varname, opt, comment, check, update, default, minimum, maximum, blocksize) -
通常は 4 バイトまたは 8 バイトの符号なしワードである
unsigned longシステム変数。MYSQL_THDVAR_ULONG(name, opt, comment, check, update, default, min, max, blk) MYSQL_SYSVAR_ULONG(name, varname, opt, comment, check, update, default, minimum, maximum, blocksize) -
通常は 8 バイトの符号付きワードである
long longシステム変数。MYSQL_THDVAR_LONGLONG(name, opt, comment, check, update, default, minimum, maximum, blocksize) MYSQL_SYSVAR_LONGLONG(name, varname, opt, comment, check, update, default, minimum, maximum, blocksize) -
通常は 8 バイトの符号なしワードである
unsigned long longシステム変数。MYSQL_THDVAR_ULONGLONG(name, opt, comment, check, update, default, minimum, maximum, blocksize) MYSQL_SYSVAR_ULONGLONG(name, varname, opt, comment, check, update, default, minimum, maximum, blocksize) -
通常は 4 バイトまたは 8 バイトの符号なしワードである
unsigned longシステム変数。設定可能な値の範囲はtypelib内の要素の数の序数であり、0 から始まります。MYSQL_THDVAR_ENUM(name, opt, comment, check, update, default, typelib) MYSQL_SYSVAR_ENUM(name, varname, opt, comment, check, update, default, typelib) -
通常は 8 バイトの符号なしワードである
unsigned long longシステム変数。各ビットはtypelib内の要素を表します。MYSQL_THDVAR_SET(name, opt, comment, check, update, default, typelib) MYSQL_SYSVAR_SET(name, varname, opt, comment, check, update, default, typelib)
-
内部的には、変更されることがあるすべてのプラグインシステム変数は HASH 構造体に格納されます。
サーバーのコマンド行でのヘルプテキストの表示は、コマンド行オプションに関係するすべての変数の DYNAMIC_ARRAY をコンパイルしてそれらをソートし、それを繰り返して各オプションを表示することによって処理されます。
コマンド行オプションが処理されると、handle_option() 関数 (my_getopt.c) によって argv から削除され、実質的にその役割が終わります。
サーバーはプラグインのインストール処理中 (プラグインが正常にロードされた直後、かつプラグインの初期化関数が呼び出される前) にコマンド行オプションを処理します。
実行時にロードされるプラグインは構成オプションを利用できないため、使用可能なデフォルト値がある必要があります。プラグインをインストールすると、mysqld の初期化時にロードされ、構成オプションをコマンド行または my.cnf 内に設定できます。
プラグインで thd パラメータを読み取り専用にすることを検討してください。
各クライアントプラグインには、クライアントプラグイン API に情報を提供するディスクリプタが必要となります。ディスクリプタの構造体は、すべてのクライアントプラグインに共通する固定された一連のメンバーで始まり、プラグインタイプ固有のメンバーがあとに続きます。
client_plugin.h ファイル内の st_mysql_client_plugin 構造体は、共通メンバーが含まれている「一般的な」ディスクリプタを定義します。
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 * メンバーは、NULL で終わる文字列として指定してください。
type: プラグインの型。これはclient_plugin.hのプラグインタイプ値 (MYSQL_CLIENT_AUTHENTICATION_PLUGINなど) のいずれかである必要があります。interface_version: プラグインインタフェースのバージョン。たとえば、認証プラグインの場合、これはMYSQL_CLIENT_AUTHENTICATION_PLUGIN_INTERFACE_VERSIONです。name: プラグイン名を指定する文字列。これは、MYSQL_DEFAULT_AUTHオプションを指定してmysql_options()を呼び出すか、MySQL クライアントプログラムに--default-authオプションを指定するときにプラグインを参照するための名前です。author: プラグイン作成者を示す文字列。これには任意の文字列を指定できます。desc: プラグインの概要を説明する文字列。これには任意の文字列を指定できます。version: メジャー、マイナー、およびその下のバージョンを示す 3 つの整数の配列であるプラグインバージョン。たとえば、{1,2,3}はバージョン 1.2.3 を示します。license: ライセンスタイプを指定する文字列。mysql_api: 内部で使用されます。プラグインディスクリプタではNULLに指定します。-
init: 1 回だけ実行される初期化関数であり、そのような関数がない場合はNULLです。クライアントライブラリはプラグインをロードするときにこの関数を実行します。関数は、成功した場合はゼロ、および失敗した場合はゼロ以外を返します。エラーが発生した場合、
init関数は最初の 2 つの引数を使用してエラーメッセージを返します。最初の引数はcharバッファーへのポインタであり、2 番目の引数はバッファー長を示します。init関数によって返されるすべてのメッセージは NULL で終わる必要があるため、最大のメッセージ長はバッファー長から 1 を引いた長さです。それに続く引数がmysql_load_plugin()に渡されます。先頭の引数は、以降に存在する引数の数を示し (ない場合は 0)、そのあとに残りの引数が続きます。 deinit: 1 回だけ実行される初期化解除関数であり、そのような関数がない場合はNULLです。クライアントライブラリは、プラグインをアンロードするときにこの関数を実行します。この関数は引数を受け取りません。成功した場合はゼロ、および失敗した場合はゼロ以外を返します。options: プラグインに渡されるオプションを処理するための関数であり、そのような関数がない場合はNULLです。この関数は、オプション名およびその値へのポインタを表す 2 つの引数を受け取ります。関数は、成功した場合はゼロ、および失敗した場合はゼロ以外を返します。
特定のクライアントプラグインタイプでは、共通のディスクリプタメンバーのあとに、そのタイプのプラグインを実装するために必要な追加メンバーが続くことがあります。たとえば、認証プラグインの 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_main
mysql_end_client_plugin;
この宣言では、AUTHENTICATION 引数を使用して、type および interface_version メンバーに MYSQL_CLIENT_AUTHENTICATION_PLUGIN および MYSQL_CLIENT_AUTHENTICATION_PLUGIN_INTERFACE_VERSION を設定しています。
プラグインタイプによっては、ディスクリプタの共通メンバーに続いてほかのメンバーがあることがあります。たとえば、認証プラグインの場合、サーバーとの通信を処理する関数 (上記のディスクリプタでは my_auth_main()) があります。セクション24.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 引数を受け取る関数を含めます。セクション23.7.14「C API クライアントプラグイン関数」を参照してください。