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)(); \
82 int (*options)(const char *option, const void *);
83struct st_mysql_client_plugin
84{
85 MYSQL_CLIENT_PLUGIN_HEADER
86};
87#endif
88
89struct st_mysql;
90
91/********* connection handler plugin specific declarations **********/
92
93typedef 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
115typedef 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
124struct 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 *******/
131struct 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*/
152typedef 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 */
160typedef 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*/
183struct st_mysql_client_plugin *
184mysql_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*/
204struct st_mysql_client_plugin * STDCALL
205mysql_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*/
219struct st_mysql_client_plugin * STDCALL
220mysql_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*/
236struct st_mysql_client_plugin * STDCALL
237mysql_client_register_plugin(struct st_mysql *mysql,
238 struct st_mysql_client_plugin *plugin);
239
240extern struct st_mysql_client_plugin *mysql_client_builtins[];
241
242#endif
243
244
245