1 /* Copyright (C) 2010 - 2012 Sergei Golubchik and Monty Program Ab 2 2014 MariaDB Corporation AB 3 4 This library is free software; you can redistribute it and/or 5 modify it under the terms of the GNU Library General Public 6 License as published by the Free Software Foundation; either 7 version 2 of the License, or (at your option) any later version. 8 9 This library 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 GNU 12 Library General Public License for more details. 13 14 You should have received a copy of the GNU Library General Public 15 License along with this library; if not see <http://www.gnu.org/licenses> 16 or write to the Free Software Foundation, Inc., 17 51 Franklin St., Fifth Floor, Boston, MA 02110, USA */ 18 19 /** 20 @file 21 22 MySQL Client Plugin API 23 24 This file defines the API for plugins that work on the client side 25 */ 26 #ifndef MYSQL_CLIENT_PLUGIN_INCLUDED 27 #define MYSQL_CLIENT_PLUGIN_INCLUDED 28 29 #ifndef MYSQL_ABI_CHECK 30 #include <stdarg.h> 31 #include <stdlib.h> 32 #endif 33 34 35 #ifndef PLUGINDIR 36 #define PLUGINDIR "lib/plugin" 37 #endif 38 39 #define plugin_declarations_sym "_mysql_client_plugin_declaration_" 40 41 /* known plugin types */ 42 #define MYSQL_CLIENT_PLUGIN_RESERVED 0 43 #define MYSQL_CLIENT_PLUGIN_RESERVED2 1 44 #define MYSQL_CLIENT_AUTHENTICATION_PLUGIN 2 /* authentication */ 45 46 #define MYSQL_CLIENT_AUTHENTICATION_PLUGIN_INTERFACE_VERSION 0x0100 47 #define MYSQL_CLIENT_MAX_PLUGINS 3 48 49 /* Connector/C specific plugin types */ 50 #define MARIADB_CLIENT_REMOTEIO_PLUGIN 100 /* communication IO */ 51 #define MARIADB_CLIENT_PVIO_PLUGIN 101 52 #define MARIADB_CLIENT_TRACE_PLUGIN 102 53 #define MARIADB_CLIENT_CONNECTION_PLUGIN 103 54 55 #define MARIADB_CLIENT_REMOTEIO_PLUGIN_INTERFACE_VERSION 0x0100 56 #define MARIADB_CLIENT_PVIO_PLUGIN_INTERFACE_VERSION 0x0100 57 #define MARIADB_CLIENT_TRACE_PLUGIN_INTERFACE_VERSION 0x0100 58 #define MARIADB_CLIENT_CONNECTION_PLUGIN_INTERFACE_VERSION 0x0100 59 60 #define MARIADB_CLIENT_MAX_PLUGINS 4 61 62 #define mysql_declare_client_plugin(X) \ 63 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 #ifndef MYSQL_CLIENT_PLUGIN_HEADER 71 #define MYSQL_CLIENT_PLUGIN_HEADER \ 72 int type; \ 73 unsigned int interface_version; \ 74 const char *name; \ 75 const char *author; \ 76 const char *desc; \ 77 unsigned int version[3]; \ 78 const char *license; \ 79 void *mysql_api; \ 80 int (*init)(char *, size_t, int, va_list); \ 81 int (*deinit)(void); \ 82 int (*options)(const char *option, const void *); 83 struct st_mysql_client_plugin 84 { 85 MYSQL_CLIENT_PLUGIN_HEADER 86 }; 87 #endif 88 89 struct st_mysql; 90 91 /********* connection handler plugin specific declarations **********/ 92 93 typedef struct st_ma_connection_plugin 94 { 95 MYSQL_CLIENT_PLUGIN_HEADER 96 /* functions */ 97 MYSQL *(*connect)(MYSQL *mysql, const char *host, 98 const char *user, const char *passwd, 99 const char *db, unsigned int port, 100 const char *unix_socket, unsigned long clientflag); 101 void (*close)(MYSQL *mysql); 102 int (*set_optionsv)(MYSQL *mysql, unsigned int option, ...); 103 int (*set_connection)(MYSQL *mysql,enum enum_server_command command, 104 const char *arg, 105 size_t length, my_bool skipp_check, void *opt_arg); 106 my_bool (*reconnect)(MYSQL *mysql); 107 int (*reset)(MYSQL *mysql); 108 } MARIADB_CONNECTION_PLUGIN; 109 110 #define MARIADB_DB_DRIVER(a) ((a)->ext_db) 111 112 /******************* Communication IO plugin *****************/ 113 #include <ma_pvio.h> 114 115 typedef struct st_mariadb_client_plugin_PVIO 116 { 117 MYSQL_CLIENT_PLUGIN_HEADER 118 struct st_ma_pvio_methods *methods; 119 } MARIADB_PVIO_PLUGIN; 120 121 /******** authentication plugin specific declarations *********/ 122 #include <mysql/plugin_auth_common.h> 123 124 struct st_mysql_client_plugin_AUTHENTICATION 125 { 126 MYSQL_CLIENT_PLUGIN_HEADER 127 int (*authenticate_user)(MYSQL_PLUGIN_VIO *vio, struct st_mysql *mysql); 128 }; 129 130 /******** trace plugin *******/ 131 struct st_mysql_client_plugin_TRACE 132 { 133 MYSQL_CLIENT_PLUGIN_HEADER 134 }; 135 136 /** 137 type of the mysql_authentication_dialog_ask function 138 139 @param mysql mysql 140 @param type type of the input 141 1 - ordinary string input 142 2 - password string 143 @param prompt prompt 144 @param buf a buffer to store the use input 145 @param buf_len the length of the buffer 146 147 @retval a pointer to the user input string. 148 It may be equal to 'buf' or to 'mysql->password'. 149 In all other cases it is assumed to be an allocated 150 string, and the "dialog" plugin will free() it. 151 */ 152 typedef char *(*mysql_authentication_dialog_ask_t)(struct st_mysql *mysql, 153 int type, const char *prompt, char *buf, int buf_len); 154 155 /********************** remote IO plugin **********************/ 156 #ifdef HAVE_REMOTEIO 157 #include <mariadb/ma_io.h> 158 159 /* Remote IO plugin */ 160 typedef struct st_mysql_client_plugin_REMOTEIO 161 { 162 MYSQL_CLIENT_PLUGIN_HEADER 163 struct st_rio_methods *methods; 164 } MARIADB_REMOTEIO_PLUGIN; 165 #endif 166 167 /******** using plugins ************/ 168 169 /** 170 loads a plugin and initializes it 171 172 @param mysql MYSQL structure. only MYSQL_PLUGIN_DIR option value is used, 173 and last_errno/last_error, for error reporting 174 @param name a name of the plugin to load 175 @param type type of plugin that should be loaded, -1 to disable type check 176 @param argc number of arguments to pass to the plugin initialization 177 function 178 @param ... arguments for the plugin initialization function 179 180 @retval 181 a pointer to the loaded plugin, or NULL in case of a failure 182 */ 183 struct st_mysql_client_plugin * 184 mysql_load_plugin(struct st_mysql *mysql, const char *name, int type, 185 int argc, ...); 186 187 /** 188 loads a plugin and initializes it, taking va_list as an argument 189 190 This is the same as mysql_load_plugin, but take va_list instead of 191 a list of arguments. 192 193 @param mysql MYSQL structure. only MYSQL_PLUGIN_DIR option value is used, 194 and last_errno/last_error, for error reporting 195 @param name a name of the plugin to load 196 @param type type of plugin that should be loaded, -1 to disable type check 197 @param argc number of arguments to pass to the plugin initialization 198 function 199 @param args arguments for the plugin initialization function 200 201 @retval 202 a pointer to the loaded plugin, or NULL in case of a failure 203 */ 204 struct st_mysql_client_plugin * STDCALL 205 mysql_load_plugin_v(struct st_mysql *mysql, const char *name, int type, 206 int argc, va_list args); 207 208 /** 209 finds an already loaded plugin by name, or loads it, if necessary 210 211 @param mysql MYSQL structure. only MYSQL_PLUGIN_DIR option value is used, 212 and last_errno/last_error, for error reporting 213 @param name a name of the plugin to load 214 @param type type of plugin that should be loaded 215 216 @retval 217 a pointer to the plugin, or NULL in case of a failure 218 */ 219 struct st_mysql_client_plugin * STDCALL 220 mysql_client_find_plugin(struct st_mysql *mysql, const char *name, int type); 221 222 /** 223 adds a plugin structure to the list of loaded plugins 224 225 This is useful if an application has the necessary functionality 226 (for example, a special load data handler) statically linked into 227 the application binary. It can use this function to register the plugin 228 directly, avoiding the need to factor it out into a shared object. 229 230 @param mysql MYSQL structure. It is only used for error reporting 231 @param plugin an st_mysql_client_plugin structure to register 232 233 @retval 234 a pointer to the plugin, or NULL in case of a failure 235 */ 236 struct st_mysql_client_plugin * STDCALL 237 mysql_client_register_plugin(struct st_mysql *mysql, 238 struct st_mysql_client_plugin *plugin); 239 240 extern struct st_mysql_client_plugin *mysql_client_builtins[]; 241 242 #endif 243 244 245