MySQL  8.0.20
Source Code Documentation
client_plugin.h
Go to the documentation of this file.
1 #ifndef MYSQL_CLIENT_PLUGIN_INCLUDED
2 /* Copyright (c) 2019, 2020, Oracle and/or its affiliates. All rights reserved.
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 also distributed 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 included with MySQL.
14 
15  Without limiting anything contained in the foregoing, this file,
16  which is part of C Driver for MySQL (Connector/C), is also subject to the
17  Universal FOSS Exception, version 1.0, a copy of which can be found at
18  http://oss.oracle.com/licenses/universal-foss-exception.
19 
20  This program is distributed in the hope that it will be useful,
21  but WITHOUT ANY WARRANTY; without even the implied warranty of
22  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
23  GNU General Public License, version 2.0, for more details.
24 
25  You should have received a copy of the GNU General Public License
26  along with this program; if not, write to the Free Software
27  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
28 
29 /**
30  @file include/mysql/client_plugin.h
31  MySQL Client Plugin API.
32  This file defines the API for plugins that work on the client side
33 */
34 #define MYSQL_CLIENT_PLUGIN_INCLUDED
35 
36 #ifndef MYSQL_ABI_CHECK
37 #include <stdarg.h>
38 #include <stdlib.h>
39 #endif
40 
41 /*
42  On Windows, exports from DLL need to be declared.
43  Also, plugin needs to be declared as extern "C" because MSVC
44  unlike other compilers, uses C++ mangling for variables not only
45  for functions.
46 */
47 
48 #undef MYSQL_PLUGIN_EXPORT
49 
50 #if defined(_MSC_VER)
51 #if defined(MYSQL_DYNAMIC_PLUGIN)
52 #ifdef __cplusplus
53 #define MYSQL_PLUGIN_EXPORT extern "C" __declspec(dllexport)
54 #else
55 #define MYSQL_PLUGIN_EXPORT __declspec(dllexport)
56 #endif
57 #else /* MYSQL_DYNAMIC_PLUGIN */
58 #ifdef __cplusplus
59 #define MYSQL_PLUGIN_EXPORT extern "C"
60 #else
61 #define MYSQL_PLUGIN_EXPORT
62 #endif
63 #endif /*MYSQL_DYNAMIC_PLUGIN */
64 #else /*_MSC_VER */
65 #define MYSQL_PLUGIN_EXPORT
66 #endif
67 
68 #ifdef __cplusplus
69 extern "C" {
70 #endif
71 
72 /* known plugin types */
73 #define MYSQL_CLIENT_reserved1 0
74 #define MYSQL_CLIENT_reserved2 1
75 #define MYSQL_CLIENT_AUTHENTICATION_PLUGIN 2
76 #define MYSQL_CLIENT_TRACE_PLUGIN 3
77 
78 #define MYSQL_CLIENT_AUTHENTICATION_PLUGIN_INTERFACE_VERSION 0x0101
79 #define MYSQL_CLIENT_TRACE_PLUGIN_INTERFACE_VERSION 0x0100
80 
81 #define MYSQL_CLIENT_MAX_PLUGINS 4
82 
83 #define MYSQL_CLIENT_PLUGIN_AUTHOR_ORACLE "Oracle Corporation"
84 
85 #define mysql_declare_client_plugin(X) \
86  MYSQL_PLUGIN_EXPORT st_mysql_client_plugin_##X \
87  _mysql_client_plugin_declaration_ = { \
88  MYSQL_CLIENT_##X##_PLUGIN, \
89  MYSQL_CLIENT_##X##_PLUGIN_INTERFACE_VERSION,
90 #define mysql_end_client_plugin }
91 
92 /* generic plugin header structure */
93 #define MYSQL_CLIENT_PLUGIN_HEADER \
94  int type; \
95  unsigned int interface_version; \
96  const char *name; \
97  const char *author; \
98  const char *desc; \
99  unsigned int version[3]; \
100  const char *license; \
101  void *mysql_api; \
102  int (*init)(char *, size_t, int, va_list); \
103  int (*deinit)(void); \
104  int (*options)(const char *option, const void *);
105 
108 };
109 
110 struct MYSQL;
111 
112 /******** authentication plugin specific declarations *********/
113 #include "plugin_auth_common.h"
114 
117  int (*authenticate_user)(MYSQL_PLUGIN_VIO *vio, struct MYSQL *mysql);
118  enum net_async_status (*authenticate_user_nonblocking)(MYSQL_PLUGIN_VIO *vio,
119  struct MYSQL *mysql,
120  int *result);
121 };
122 
123 // Needed for the mysql_declare_client_plugin() macro. Do not use elsewhere.
125 
126 /******** using plugins ************/
127 
128 /**
129  loads a plugin and initializes it
130 
131  @param mysql MYSQL structure.
132  @param name a name of the plugin to load
133  @param type type of plugin that should be loaded, -1 to disable type check
134  @param argc number of arguments to pass to the plugin initialization
135  function
136  @param ... arguments for the plugin initialization function
137 
138  @retval
139  a pointer to the loaded plugin, or NULL in case of a failure
140 */
142  const char *name, int type,
143  int argc, ...);
144 
145 /**
146  loads a plugin and initializes it, taking va_list as an argument
147 
148  This is the same as mysql_load_plugin, but take va_list instead of
149  a list of arguments.
150 
151  @param mysql MYSQL structure.
152  @param name a name of the plugin to load
153  @param type type of plugin that should be loaded, -1 to disable type check
154  @param argc number of arguments to pass to the plugin initialization
155  function
156  @param args arguments for the plugin initialization function
157 
158  @retval
159  a pointer to the loaded plugin, or NULL in case of a failure
160 */
162  const char *name, int type,
163  int argc, va_list args);
164 
165 /**
166  finds an already loaded plugin by name, or loads it, if necessary
167 
168  @param mysql MYSQL structure.
169  @param name a name of the plugin to load
170  @param type type of plugin that should be loaded
171 
172  @retval
173  a pointer to the plugin, or NULL in case of a failure
174 */
176  const char *name,
177  int type);
178 
179 /**
180  adds a plugin structure to the list of loaded plugins
181 
182  This is useful if an application has the necessary functionality
183  (for example, a special load data handler) statically linked into
184  the application binary. It can use this function to register the plugin
185  directly, avoiding the need to factor it out into a shared object.
186 
187  @param mysql MYSQL structure. It is only used for error reporting
188  @param plugin an st_mysql_client_plugin structure to register
189 
190  @retval
191  a pointer to the plugin, or NULL in case of a failure
192 */
194  struct MYSQL *mysql, struct st_mysql_client_plugin *plugin);
195 
196 /**
197  set plugin options
198 
199  Can be used to set extra options and affect behavior for a plugin.
200  This function may be called multiple times to set several options
201 
202  @param plugin an st_mysql_client_plugin structure
203  @param option a string which specifies the option to set
204  @param value value for the option.
205 
206  @retval 0 on success, 1 in case of failure
207 **/
209  const char *option, const void *value);
210 
211 #ifdef __cplusplus
212 }
213 #endif
214 
215 #endif
struct st_mysql_client_plugin * mysql_client_register_plugin(struct MYSQL *mysql, struct st_mysql_client_plugin *plugin)
adds a plugin structure to the list of loaded plugins
Definition: client_plugin.cc:379
get_options & argc
Definition: do_ctype.cc:51
struct result result
Definition: result.h:37
struct st_mysql_client_plugin * mysql_load_plugin(struct MYSQL *mysql, const char *name, int type, int argc,...)
loads a plugin and initializes it
Definition: client_plugin.cc:534
static struct st_mysql_daemon plugin
Definition: test_services_host_application_signal.cc:130
net_async_status
Definition: plugin_auth_common.h:130
Definition: client_plugin.h:106
int mysql_plugin_options(struct st_mysql_client_plugin *plugin, const char *option, const void *value)
set plugin options
Definition: client_plugin.cc:572
structure to define some default "config_option" option settings
Definition: innodb_config.h:180
case opt name
Definition: sslopt-case.h:32
This file defines constants and data structures that are the same for both client- and server-side au...
Definition: client_plugin.h:115
static MYSQL mysql
Definition: mysql.cc:152
struct st_mysql_client_plugin * mysql_client_find_plugin(struct MYSQL *mysql, const char *name, int type)
finds an already loaded plugin by name, or loads it, if necessary
Definition: client_plugin.cc:545
const string value("\alue\)
Provides plugin access to communication channel.
Definition: plugin_auth_common.h:140
Definition: mysql.h:295
struct st_mysql_client_plugin * mysql_load_plugin_v(struct MYSQL *mysql, const char *name, int type, int argc, va_list args)
loads a plugin and initializes it, taking va_list as an argument
Definition: client_plugin.cc:400
#define MYSQL_CLIENT_PLUGIN_HEADER
Definition: client_plugin.h:93