1#ifndef MYSQL_CLIENT_PLUGIN_INCLUDED
2/* Copyright (C) 2010 Sergei Golubchik and Monty Program Ab
3 Copyright (c) 2010, 2011, Oracle and/or its affiliates.
4
5 This program is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published by
7 the Free Software Foundation; version 2 of the License.
8
9 This program is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 GNU General Public License for more details.
13
14 You should have received a copy of the GNU General Public License
15 along with this program; if not, write to the Free Software
16 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
17
18/**
19 @file
20
21 MySQL Client Plugin API
22
23 This file defines the API for plugins that work on the client side
24*/
25#define MYSQL_CLIENT_PLUGIN_INCLUDED
26
27/*
28 On Windows, exports from DLL need to be declared
29 Also, plugin needs to be declared as extern "C" because MSVC
30 unlike other compilers, uses C++ mangling for variables not only
31 for functions.
32*/
33#undef MYSQL_PLUGIN_EXPORT
34#if defined(_MSC_VER)
35 #ifdef __cplusplus
36 #define MYSQL_PLUGIN_EXPORT extern "C" __declspec(dllexport)
37 #else
38 #define MYSQL_PLUGIN_EXPORT __declspec(dllexport)
39 #endif
40#else /*_MSC_VER */
41 #ifdef __cplusplus
42 #define MYSQL_PLUGIN_EXPORT extern "C"
43 #else
44 #define MYSQL_PLUGIN_EXPORT
45 #endif
46#endif
47
48#ifndef MYSQL_ABI_CHECK
49#include <stdarg.h>
50#include <stdlib.h>
51#endif
52
53/* known plugin types */
54#define MYSQL_CLIENT_reserved1 0
55#define MYSQL_CLIENT_reserved2 1
56#define MYSQL_CLIENT_AUTHENTICATION_PLUGIN 2
57
58#define MYSQL_CLIENT_AUTHENTICATION_PLUGIN_INTERFACE_VERSION 0x0100
59
60#define MYSQL_CLIENT_MAX_PLUGINS 3
61
62#define mysql_declare_client_plugin(X) \
63 MYSQL_PLUGIN_EXPORT struct st_mysql_client_plugin_ ## X \
64 _mysql_client_plugin_declaration_ = { \
65 MYSQL_CLIENT_ ## X ## _PLUGIN, \
66 MYSQL_CLIENT_ ## X ## _PLUGIN_INTERFACE_VERSION,
67#define mysql_end_client_plugin }
68
69/* generic plugin header structure */
70#define MYSQL_CLIENT_PLUGIN_HEADER \
71 int type; \
72 unsigned int interface_version; \
73 const char *name; \
74 const char *author; \
75 const char *desc; \
76 unsigned int version[3]; \
77 const char *license; \
78 void *mysql_api; \
79 int (*init)(char *, size_t, int, va_list); \
80 int (*deinit)(); \
81 int (*options)(const char *option, const void *);
82
83struct st_mysql_client_plugin
84{
85 MYSQL_CLIENT_PLUGIN_HEADER
86};
87
88struct st_mysql;
89
90/******** authentication plugin specific declarations *********/
91#include <mysql/plugin_auth_common.h>
92
93struct st_mysql_client_plugin_AUTHENTICATION
94{
95 MYSQL_CLIENT_PLUGIN_HEADER
96 int (*authenticate_user)(MYSQL_PLUGIN_VIO *vio, struct st_mysql *mysql);
97};
98
99#include <mysql/auth_dialog_client.h>
100
101/******** using plugins ************/
102
103/**
104 loads a plugin and initializes it
105
106 @param mysql MYSQL structure.
107 @param name a name of the plugin to load
108 @param type type of plugin that should be loaded, -1 to disable type check
109 @param argc number of arguments to pass to the plugin initialization
110 function
111 @param ... arguments for the plugin initialization function
112
113 @retval
114 a pointer to the loaded plugin, or NULL in case of a failure
115*/
116struct st_mysql_client_plugin *
117mysql_load_plugin(struct st_mysql *mysql, const char *name, int type,
118 int argc, ...);
119
120/**
121 loads a plugin and initializes it, taking va_list as an argument
122
123 This is the same as mysql_load_plugin, but take va_list instead of
124 a list of arguments.
125
126 @param mysql MYSQL structure.
127 @param name a name of the plugin to load
128 @param type type of plugin that should be loaded, -1 to disable type check
129 @param argc number of arguments to pass to the plugin initialization
130 function
131 @param args arguments for the plugin initialization function
132
133 @retval
134 a pointer to the loaded plugin, or NULL in case of a failure
135*/
136struct st_mysql_client_plugin *
137mysql_load_plugin_v(struct st_mysql *mysql, const char *name, int type,
138 int argc, va_list args);
139
140/**
141 finds an already loaded plugin by name, or loads it, if necessary
142
143 @param mysql MYSQL structure.
144 @param name a name of the plugin to load
145 @param type type of plugin that should be loaded
146
147 @retval
148 a pointer to the plugin, or NULL in case of a failure
149*/
150struct st_mysql_client_plugin *
151mysql_client_find_plugin(struct st_mysql *mysql, const char *name, int type);
152
153/**
154 adds a plugin structure to the list of loaded plugins
155
156 This is useful if an application has the necessary functionality
157 (for example, a special load data handler) statically linked into
158 the application binary. It can use this function to register the plugin
159 directly, avoiding the need to factor it out into a shared object.
160
161 @param mysql MYSQL structure. It is only used for error reporting
162 @param plugin an st_mysql_client_plugin structure to register
163
164 @retval
165 a pointer to the plugin, or NULL in case of a failure
166*/
167struct st_mysql_client_plugin *
168mysql_client_register_plugin(struct st_mysql *mysql,
169 struct st_mysql_client_plugin *plugin);
170
171/**
172 set plugin options
173
174 Can be used to set extra options and affect behavior for a plugin.
175 This function may be called multiple times to set several options
176
177 @param plugin an st_mysql_client_plugin structure
178 @param option a string which specifies the option to set
179 @param value value for the option.
180
181 @retval 0 on success, 1 in case of failure
182**/
183int mysql_plugin_options(struct st_mysql_client_plugin *plugin,
184 const char *option, const void *value);
185#endif
186
187