1#ifndef MYSQL_CLIENT_PLUGIN_INCLUDED
2/* Copyright (c) 2010, 2025, 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
74extern "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 MYSQL_CLIENT_PLUGIN_HEADER \
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
112struct st_mysql_client_plugin {
113 MYSQL_CLIENT_PLUGIN_HEADER
114};
115
116struct MYSQL;
117
118/******** authentication plugin specific declarations *********/
119#include "plugin_auth_common.h"
120
121struct 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.
130typedef 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*/
147struct 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*/
167struct 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*/
181struct 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*/
199struct 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**/
214int 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**/
229int 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

source code of include/mysql/client_plugin.h