1 | #ifndef MYSQL_CLIENT_PLUGIN_INCLUDED |
2 | /* Copyright (c) 2010, 2024, Oracle and/or its affiliates. |
3 | |
4 | This program is free software; you can redistribute it and/or modify |
5 | it under the terms of the GNU General Public License, version 2.0, |
6 | as published by the Free Software Foundation. |
7 | |
8 | This program is designed to work with certain software (including |
9 | but not limited to OpenSSL) that is licensed under separate terms, |
10 | as designated in a particular file or component or in included license |
11 | documentation. The authors of MySQL hereby grant you an additional |
12 | permission to link the program and your derivative works with the |
13 | separately licensed software that they have either included with |
14 | the program or referenced in the documentation. |
15 | |
16 | Without limiting anything contained in the foregoing, this file, |
17 | which is part of C Driver for MySQL (Connector/C), is also subject to the |
18 | Universal FOSS Exception, version 1.0, a copy of which can be found at |
19 | http://oss.oracle.com/licenses/universal-foss-exception. |
20 | |
21 | This program is distributed in the hope that it will be useful, |
22 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
23 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
24 | GNU General Public License, version 2.0, for more details. |
25 | |
26 | You should have received a copy of the GNU General Public License |
27 | along with this program; if not, write to the Free Software |
28 | Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ |
29 | |
30 | /** |
31 | @file include/mysql/client_plugin.h |
32 | MySQL Client Plugin API. |
33 | This file defines the API for plugins that work on the client side |
34 | */ |
35 | #define MYSQL_CLIENT_PLUGIN_INCLUDED |
36 | |
37 | #ifndef MYSQL_ABI_CHECK |
38 | #include <stdarg.h> |
39 | #include <stdlib.h> |
40 | #endif |
41 | |
42 | /* |
43 | On Windows, exports from DLL need to be declared. |
44 | Also, plugin needs to be declared as extern "C" because MSVC |
45 | unlike other compilers, uses C++ mangling for variables not only |
46 | for functions. |
47 | */ |
48 | |
49 | #if defined(_MSC_VER) |
50 | #if defined(MYSQL_DYNAMIC_CLIENT_PLUGIN) |
51 | #ifdef __cplusplus |
52 | #define MYSQL_CLIENT_PLUGIN_EXPORT extern "C" __declspec(dllexport) |
53 | #else |
54 | #define MYSQL_CLIENT_PLUGIN_EXPORT __declspec(dllexport) |
55 | #endif |
56 | #else /* MYSQL_DYNAMIC_CLIENT_PLUGIN */ |
57 | #ifdef __cplusplus |
58 | #define MYSQL_CLIENT_PLUGIN_EXPORT extern "C" |
59 | #else |
60 | #define MYSQL_CLIENT_PLUGIN_EXPORT |
61 | #endif |
62 | #endif /*MYSQL_DYNAMIC_CLIENT_PLUGIN */ |
63 | #else /*_MSC_VER */ |
64 | |
65 | #if defined(MYSQL_DYNAMIC_CLIENT_PLUGIN) |
66 | #define MYSQL_CLIENT_PLUGIN_EXPORT MY_ATTRIBUTE((visibility("default"))) |
67 | #else |
68 | #define MYSQL_CLIENT_PLUGIN_EXPORT |
69 | #endif |
70 | |
71 | #endif |
72 | |
73 | #ifdef __cplusplus |
74 | extern "C" { |
75 | #endif |
76 | |
77 | /* known plugin types */ |
78 | #define MYSQL_CLIENT_reserved1 0 |
79 | #define MYSQL_CLIENT_reserved2 1 |
80 | #define MYSQL_CLIENT_AUTHENTICATION_PLUGIN 2 |
81 | #define MYSQL_CLIENT_TRACE_PLUGIN 3 |
82 | |
83 | #define MYSQL_CLIENT_AUTHENTICATION_PLUGIN_INTERFACE_VERSION 0x0200 |
84 | #define MYSQL_CLIENT_TRACE_PLUGIN_INTERFACE_VERSION 0x0200 |
85 | |
86 | #define MYSQL_CLIENT_MAX_PLUGINS 4 |
87 | |
88 | #define MYSQL_CLIENT_PLUGIN_AUTHOR_ORACLE "Oracle Corporation" |
89 | |
90 | #define mysql_declare_client_plugin(X) \ |
91 | MYSQL_CLIENT_PLUGIN_EXPORT st_mysql_client_plugin_##X \ |
92 | _mysql_client_plugin_declaration_ = { \ |
93 | MYSQL_CLIENT_##X##_PLUGIN, \ |
94 | MYSQL_CLIENT_##X##_PLUGIN_INTERFACE_VERSION, |
95 | #define mysql_end_client_plugin } |
96 | |
97 | /* generic plugin header structure */ |
98 | #define \ |
99 | int type; \ |
100 | unsigned int interface_version; \ |
101 | const char *name; \ |
102 | const char *author; \ |
103 | const char *desc; \ |
104 | unsigned int version[3]; \ |
105 | const char *license; \ |
106 | void *mysql_api; \ |
107 | int (*init)(char *, size_t, int, va_list); \ |
108 | int (*deinit)(void); \ |
109 | int (*options)(const char *option, const void *); \ |
110 | int (*get_options)(const char *option, void *); |
111 | |
112 | struct st_mysql_client_plugin { |
113 | MYSQL_CLIENT_PLUGIN_HEADER |
114 | }; |
115 | |
116 | struct MYSQL; |
117 | |
118 | /******** authentication plugin specific declarations *********/ |
119 | #include "plugin_auth_common.h" |
120 | |
121 | struct auth_plugin_t { |
122 | MYSQL_CLIENT_PLUGIN_HEADER |
123 | int (*authenticate_user)(MYSQL_PLUGIN_VIO *vio, struct MYSQL *mysql); |
124 | enum net_async_status (*authenticate_user_nonblocking)(MYSQL_PLUGIN_VIO *vio, |
125 | struct MYSQL *mysql, |
126 | int *result); |
127 | }; |
128 | |
129 | // Needed for the mysql_declare_client_plugin() macro. Do not use elsewhere. |
130 | typedef struct auth_plugin_t st_mysql_client_plugin_AUTHENTICATION; |
131 | |
132 | /******** using plugins ************/ |
133 | |
134 | /** |
135 | loads a plugin and initializes it |
136 | |
137 | @param mysql MYSQL structure. |
138 | @param name a name of the plugin to load |
139 | @param type type of plugin that should be loaded, -1 to disable type check |
140 | @param argc number of arguments to pass to the plugin initialization |
141 | function |
142 | @param ... arguments for the plugin initialization function |
143 | |
144 | @retval |
145 | a pointer to the loaded plugin, or NULL in case of a failure |
146 | */ |
147 | struct st_mysql_client_plugin *mysql_load_plugin(struct MYSQL *mysql, |
148 | const char *name, int type, |
149 | int argc, ...); |
150 | |
151 | /** |
152 | loads a plugin and initializes it, taking va_list as an argument |
153 | |
154 | This is the same as mysql_load_plugin, but take va_list instead of |
155 | a list of arguments. |
156 | |
157 | @param mysql MYSQL structure. |
158 | @param name a name of the plugin to load |
159 | @param type type of plugin that should be loaded, -1 to disable type check |
160 | @param argc number of arguments to pass to the plugin initialization |
161 | function |
162 | @param args arguments for the plugin initialization function |
163 | |
164 | @retval |
165 | a pointer to the loaded plugin, or NULL in case of a failure |
166 | */ |
167 | struct st_mysql_client_plugin *mysql_load_plugin_v(struct MYSQL *mysql, |
168 | const char *name, int type, |
169 | int argc, va_list args); |
170 | |
171 | /** |
172 | finds an already loaded plugin by name, or loads it, if necessary |
173 | |
174 | @param mysql MYSQL structure. |
175 | @param name a name of the plugin to load |
176 | @param type type of plugin that should be loaded |
177 | |
178 | @retval |
179 | a pointer to the plugin, or NULL in case of a failure |
180 | */ |
181 | struct st_mysql_client_plugin *mysql_client_find_plugin(struct MYSQL *mysql, |
182 | const char *name, |
183 | int type); |
184 | |
185 | /** |
186 | adds a plugin structure to the list of loaded plugins |
187 | |
188 | This is useful if an application has the necessary functionality |
189 | (for example, a special load data handler) statically linked into |
190 | the application binary. It can use this function to register the plugin |
191 | directly, avoiding the need to factor it out into a shared object. |
192 | |
193 | @param mysql MYSQL structure. It is only used for error reporting |
194 | @param plugin an st_mysql_client_plugin structure to register |
195 | |
196 | @retval |
197 | a pointer to the plugin, or NULL in case of a failure |
198 | */ |
199 | struct st_mysql_client_plugin *mysql_client_register_plugin( |
200 | struct MYSQL *mysql, struct st_mysql_client_plugin *plugin); |
201 | |
202 | /** |
203 | set plugin options |
204 | |
205 | Can be used to set extra options and affect behavior for a plugin. |
206 | This function may be called multiple times to set several options |
207 | |
208 | @param plugin an st_mysql_client_plugin structure |
209 | @param option a string which specifies the option to set |
210 | @param value value for the option. |
211 | |
212 | @retval 0 on success, 1 in case of failure |
213 | **/ |
214 | int mysql_plugin_options(struct st_mysql_client_plugin *plugin, |
215 | const char *option, const void *value); |
216 | |
217 | /** |
218 | get plugin options |
219 | |
220 | Can be used to get options from a plugin. |
221 | This function may be called multiple times to get several options |
222 | |
223 | @param plugin an st_mysql_client_plugin structure |
224 | @param option a string which specifies the option to get |
225 | @param[out] value value for the option. |
226 | |
227 | @retval 0 on success, 1 in case of failure |
228 | **/ |
229 | int mysql_plugin_get_option(struct st_mysql_client_plugin *plugin, |
230 | const char *option, void *value); |
231 | |
232 | #ifdef __cplusplus |
233 | } |
234 | #endif |
235 | |
236 | #endif |
237 | |