1 #ifndef MYSQL_CLIENT_PLUGIN_INCLUDED 2 /* Copyright (c) 2010, 2016, 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 31 32 MySQL Client Plugin API 33 34 This file defines the API for plugins that work on the client side 35 */ 36 #define MYSQL_CLIENT_PLUGIN_INCLUDED 37 38 #ifndef MYSQL_ABI_CHECK 39 #include <stdarg.h> 40 #include <stdlib.h> 41 #endif 42 43 /* 44 On Windows, exports from DLL need to be declared. 45 Also, plugin needs to be declared as extern "C" because MSVC 46 unlike other compilers, uses C++ mangling for variables not only 47 for functions. 48 */ 49 50 #undef MYSQL_PLUGIN_EXPORT 51 52 #if defined(_MSC_VER) 53 #if defined(MYSQL_DYNAMIC_PLUGIN) 54 #ifdef __cplusplus 55 #define MYSQL_PLUGIN_EXPORT extern "C" __declspec(dllexport) 56 #else 57 #define MYSQL_PLUGIN_EXPORT __declspec(dllexport) 58 #endif 59 #else /* MYSQL_DYNAMIC_PLUGIN */ 60 #ifdef __cplusplus 61 #define MYSQL_PLUGIN_EXPORT extern "C" 62 #else 63 #define MYSQL_PLUGIN_EXPORT 64 #endif 65 #endif /*MYSQL_DYNAMIC_PLUGIN */ 66 #else /*_MSC_VER */ 67 #define MYSQL_PLUGIN_EXPORT 68 #endif 69 70 71 #ifdef __cplusplus 72 extern "C" { 73 #endif 74 75 /* known plugin types */ 76 #define MYSQL_CLIENT_reserved1 0 77 #define MYSQL_CLIENT_reserved2 1 78 #define MYSQL_CLIENT_AUTHENTICATION_PLUGIN 2 79 #define MYSQL_CLIENT_TRACE_PLUGIN 3 80 81 #define MYSQL_CLIENT_AUTHENTICATION_PLUGIN_INTERFACE_VERSION 0x0100 82 #define MYSQL_CLIENT_TRACE_PLUGIN_INTERFACE_VERSION 0x0100 83 84 #define MYSQL_CLIENT_MAX_PLUGINS 4 85 86 #define mysql_declare_client_plugin(X) \ 87 MYSQL_PLUGIN_EXPORT struct st_mysql_client_plugin_ ## X \ 88 _mysql_client_plugin_declaration_ = { \ 89 MYSQL_CLIENT_ ## X ## _PLUGIN, \ 90 MYSQL_CLIENT_ ## X ## _PLUGIN_INTERFACE_VERSION, 91 #define mysql_end_client_plugin } 92 93 /* generic plugin header structure */ 94 #define MYSQL_CLIENT_PLUGIN_HEADER \ 95 int type; \ 96 unsigned int interface_version; \ 97 const char *name; \ 98 const char *author; \ 99 const char *desc; \ 100 unsigned int version[3]; \ 101 const char *license; \ 102 void *mysql_api; \ 103 int (*init)(char *, size_t, int, va_list); \ 104 int (*deinit)(void); \ 105 int (*options)(const char *option, const void *); 106 107 struct st_mysql_client_plugin 108 { 109 MYSQL_CLIENT_PLUGIN_HEADER 110 }; 111 112 struct st_mysql; 113 114 /******** authentication plugin specific declarations *********/ 115 #include "plugin_auth_common.h" 116 117 struct st_mysql_client_plugin_AUTHENTICATION 118 { 119 MYSQL_CLIENT_PLUGIN_HEADER 120 int (*authenticate_user)(MYSQL_PLUGIN_VIO *vio, struct st_mysql *mysql); 121 }; 122 123 /******** using plugins ************/ 124 125 /** 126 loads a plugin and initializes it 127 128 @param mysql MYSQL structure. 129 @param name a name of the plugin to load 130 @param type type of plugin that should be loaded, -1 to disable type check 131 @param argc number of arguments to pass to the plugin initialization 132 function 133 @param ... arguments for the plugin initialization function 134 135 @retval 136 a pointer to the loaded plugin, or NULL in case of a failure 137 */ 138 struct st_mysql_client_plugin * 139 mysql_load_plugin(struct st_mysql *mysql, const char *name, int type, 140 int argc, ...); 141 142 /** 143 loads a plugin and initializes it, taking va_list as an argument 144 145 This is the same as mysql_load_plugin, but take va_list instead of 146 a list of arguments. 147 148 @param mysql MYSQL structure. 149 @param name a name of the plugin to load 150 @param type type of plugin that should be loaded, -1 to disable type check 151 @param argc number of arguments to pass to the plugin initialization 152 function 153 @param args arguments for the plugin initialization function 154 155 @retval 156 a pointer to the loaded plugin, or NULL in case of a failure 157 */ 158 struct st_mysql_client_plugin * 159 mysql_load_plugin_v(struct st_mysql *mysql, const char *name, int type, 160 int argc, va_list args); 161 162 /** 163 finds an already loaded plugin by name, or loads it, if necessary 164 165 @param mysql MYSQL structure. 166 @param name a name of the plugin to load 167 @param type type of plugin that should be loaded 168 169 @retval 170 a pointer to the plugin, or NULL in case of a failure 171 */ 172 struct st_mysql_client_plugin * 173 mysql_client_find_plugin(struct st_mysql *mysql, const char *name, int type); 174 175 /** 176 adds a plugin structure to the list of loaded plugins 177 178 This is useful if an application has the necessary functionality 179 (for example, a special load data handler) statically linked into 180 the application binary. It can use this function to register the plugin 181 directly, avoiding the need to factor it out into a shared object. 182 183 @param mysql MYSQL structure. It is only used for error reporting 184 @param plugin an st_mysql_client_plugin structure to register 185 186 @retval 187 a pointer to the plugin, or NULL in case of a failure 188 */ 189 struct st_mysql_client_plugin * 190 mysql_client_register_plugin(struct st_mysql *mysql, 191 struct st_mysql_client_plugin *plugin); 192 193 /** 194 set plugin options 195 196 Can be used to set extra options and affect behavior for a plugin. 197 This function may be called multiple times to set several options 198 199 @param plugin an st_mysql_client_plugin structure 200 @param option a string which specifies the option to set 201 @param value value for the option. 202 203 @retval 0 on success, 1 in case of failure 204 **/ 205 int mysql_plugin_options(struct st_mysql_client_plugin *plugin, 206 const char *option, const void *value); 207 208 209 #ifdef __cplusplus 210 } 211 #endif 212 213 #endif 214 215