MySQL  8.0.22
Source Code Documentation
service_command.h
Go to the documentation of this file.
1 #ifndef MYSQL_SERVICE_COMMAND_INCLUDED
2 #define MYSQL_SERVICE_COMMAND_INCLUDED
3 /* Copyright (c) 2015, 2020, Oracle and/or its affiliates. All rights reserved.
4 
5  This program is free software; you can redistribute it and/or modify
6  it under the terms of the GNU General Public License, version 2.0,
7  as published by the Free Software Foundation.
8 
9  This program is also distributed with certain software (including
10  but not limited to OpenSSL) that is licensed under separate terms,
11  as designated in a particular file or component or in included license
12  documentation. The authors of MySQL hereby grant you an additional
13  permission to link the program and your derivative works with the
14  separately licensed software that they have included with MySQL.
15 
16  This program is distributed in the hope that it will be useful,
17  but WITHOUT ANY WARRANTY; without even the implied warranty of
18  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19  GNU General Public License, version 2.0, for more details.
20 
21  You should have received a copy of the GNU General Public License
22  along with this program; if not, write to the Free Software
23  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
24 
25 /**
26  @file include/mysql/service_command.h
27  Header file for the Command service. This service is to provide means
28  of executing different commands, like COM_QUERY, COM_STMT_PREPARE,
29  in the server.
30 */
31 
32 #include "mysql/com_data.h"
34 
35 #include "decimal.h"
36 #include "mysql_time.h"
37 #ifndef MYSQL_ABI_CHECK
38 #include <stdint.h> /* uint32_t */
39 #include "field_types.h"
40 #include "m_ctype.h"
41 #endif
42 
43 /* POD structure for the field metadata from the server */
44 struct st_send_field {
45  const char *db_name;
46  const char *table_name;
47  const char *org_table_name;
48  const char *col_name;
49  const char *org_col_name;
50  unsigned long length;
51  unsigned int charsetnr;
52  unsigned int flags;
53  unsigned int decimals;
55 };
56 
57 /**
58  Indicates beginning of metadata for the result set
59 
60  @param ctx Plugin's context
61  @param num_cols Number of fields being sent
62  @param flags Flags to alter the metadata sending
63  @param resultcs Charset of the result set
64 
65  @note resultcs is the charset in which the data should be encoded before
66  sent to the client. This is the value of the session variable
67  character_set_results. The implementor most probably will need to save
68  this value in the context and use it as "to" charset in get_string().
69 
70  In case of CS_BINARY_REPRESENTATION, get_string() receives as a parameter
71  the charset of the string, as it is stored on disk.
72 
73  In case of CS_TEXT_REPRESENTATION, the string value might be already a
74  stringified value or non-string data, which is in character_set_results.
75 
76  @returns
77  1 an error occurred, server will abort the command
78  0 ok
79 */
80 typedef int (*start_result_metadata_t)(void *ctx, uint num_cols, uint flags,
81  const CHARSET_INFO *resultcs);
82 
83 /**
84  Field metadata is provided via this callback
85 
86  @param ctx Plugin's context
87  @param field Field's metadata (see field.h)
88  @param charset Field's charset
89 
90  @returns
91  1 an error occurred, server will abort the command
92  0 ok
93 */
94 typedef int (*field_metadata_t)(void *ctx, struct st_send_field *field,
95  const CHARSET_INFO *charset);
96 
97 /**
98  Indicates end of metadata for the result set
99 
100  @param ctx Plugin's context
101  @param server_status Status of server (see mysql_com.h, SERVER_STATUS_*)
102  @param warn_count Number of warnings generated during execution to the
103  moment when the metadata is sent.
104  @returns
105  1 an error occurred, server will abort the command
106  0 ok
107 */
108 typedef int (*end_result_metadata_t)(void *ctx, uint server_status,
109  uint warn_count);
110 
111 /**
112  Indicates the beginning of a new row in the result set/metadata
113 
114  @param ctx Plugin's context
115 
116  @returns
117  1 an error occurred, server will abort the command
118  0 ok
119 */
120 typedef int (*start_row_t)(void *ctx);
121 
122 /**
123  Indicates the end of the current row in the result set/metadata
124 
125  @param ctx Plugin's context
126 
127  @returns
128  1 an error occurred, server will abort the command
129  0 ok
130 */
131 typedef int (*end_row_t)(void *ctx);
132 
133 /**
134  An error occurred during execution
135 
136  This callback indicates that an error occurred during command
137  execution and the partial row should be dropped. Server will raise error
138  and return.
139 
140  @param ctx Plugin's context
141 */
142 typedef void (*abort_row_t)(void *ctx);
143 
144 /**
145  Return client's capabilities (see mysql_com.h, CLIENT_*)
146 
147  @param ctx Plugin's context
148 
149  @return Bitmap of client's capabilities
150 */
151 typedef ulong (*get_client_capabilities_t)(void *ctx);
152 
153 /**
154  Receive NULL value from server
155 
156  @param ctx Plugin's context
157 
158  @returns
159  1 an error occurred, server will abort the command
160  0 ok
161 */
162 typedef int (*get_null_t)(void *ctx);
163 
164 /**
165  Receive TINY/SHORT/LONG value from server
166 
167  @param ctx Plugin's context
168  @param value Value received
169 
170  @note In order to know which type exactly was received, the plugin must
171  track the metadata that was sent just prior to the result set.
172 
173  @returns
174  1 an error occurred, server will abort the command
175  0 ok
176 */
177 typedef int (*get_integer_t)(void *ctx, longlong value);
178 
179 /**
180  Get LONGLONG value from server
181 
182  @param ctx Plugin's context
183  @param value Value received
184  @param is_unsigned TRUE <=> value is unsigned
185 
186  @returns
187  1 an error occurred, server will abort the command
188  0 ok
189 */
190 typedef int (*get_longlong_t)(void *ctx, longlong value, uint is_unsigned);
191 
192 /**
193  Receive DECIMAL value from server
194 
195  @param ctx Plugin's context
196  @param value Value received
197 
198  @returns
199  1 an error occurred, server will abort the command
200  0 ok
201 */
202 typedef int (*get_decimal_t)(void *ctx, const decimal_t *value);
203 
204 /**
205  Receive FLOAT/DOUBLE from server
206 
207  @param ctx Plugin's context
208  @param value Value received
209  @param decimals Number of decimals
210 
211  @note In order to know which type exactly was received, the plugin must
212  track the metadata that was sent just prior to the result set.
213 
214  @returns
215  1 an error occurred, server will abort the command
216  0 ok
217 */
218 typedef int (*get_double_t)(void *ctx, double value, uint32_t decimals);
219 
220 /**
221  Get DATE value from server
222 
223  @param ctx Plugin's context
224  @param value Value received
225 
226  @returns
227  1 an error occurred during storing, server will abort the command
228  0 ok
229 */
230 typedef int (*get_date_t)(void *ctx, const MYSQL_TIME *value);
231 
232 /**
233  Receive TIME value from server
234 
235  @param ctx Plugin's context
236  @param value Value received
237  @param decimals Number of decimals
238 
239  @returns
240  1 an error occurred during storing, server will abort the command
241  0 ok
242 */
243 typedef int (*get_time_t)(void *ctx, const MYSQL_TIME *value, uint decimals);
244 
245 /**
246  Receive DATETIME value from server
247 
248  @param ctx Plugin's context
249  @param value Value received
250  @param decimals Number of decimals
251 
252  @returns
253  1 an error occurred during storing, server will abort the command
254  0 ok
255 */
256 typedef int (*get_datetime_t)(void *ctx, const MYSQL_TIME *value,
257  uint decimals);
258 
259 /**
260  Get STRING value from server
261 
262  @param ctx Plugin's context
263  @param value Data
264  @param length Data length
265  @param valuecs Data charset
266 
267  @note In case of CS_BINARY_REPRESENTATION, get_string() receives as
268  a parameter the charset of the string, as it is stored on disk.
269 
270  In case of CS_TEXT_REPRESENTATION, the string value might be already a
271  stringified value or non-string data, which is in character_set_results.
272 
273  @see start_result_metadata()
274 
275  @returns
276  1 an error occurred, server will abort the command
277  0 ok
278 */
279 typedef int (*get_string_t)(void *ctx, const char *value, size_t length,
280  const CHARSET_INFO *valuecs);
281 
282 /**
283  Command ended with success
284 
285  @param ctx Plugin's context
286  @param server_status Status of server (see mysql_com.h,
287  SERVER_STATUS_*)
288  @param statement_warn_count Number of warnings thrown during execution
289  @param affected_rows Number of rows affected by the command
290  @param last_insert_id Last insert id being assigned during execution
291  @param message A message from server
292 */
293 typedef void (*handle_ok_t)(void *ctx, uint server_status,
294  uint statement_warn_count, ulonglong affected_rows,
295  ulonglong last_insert_id, const char *message);
296 
297 /**
298  Command ended with ERROR
299 
300  @param ctx Plugin's context
301  @param sql_errno Error code
302  @param err_msg Error message
303  @param sqlstate SQL state corresponding to the error code
304 */
305 typedef void (*handle_error_t)(void *ctx, uint sql_errno, const char *err_msg,
306  const char *sqlstate);
307 
308 /**
309  Callback for shutdown notification from the server.
310 
311  @param ctx Plugin's context
312  @param server_shutdown Whether this is a normal connection shutdown (0) or
313  server shutdown (1).
314 */
315 typedef void (*shutdown_t)(void *ctx, int server_shutdown);
316 
318  /*
319  For a statement that returns a result, the flow of called callbacks will be:
320 
321  start_result_metadata()
322  field_metadata()
323  ....
324  end_result_metadata() (in the classic protocol this generates an EOF packet)
325  start_row()
326  get_xxx()
327  ...
328  end_row()
329  start_row()
330  get_xxx()
331  ...
332  end_row()
333  handle_ok() (with data for an EOF packet)
334 
335  For a statement that does NOT return a result, but only status, like
336  INSERT, UPDATE, DELETE, REPLACE, TRUNCATE, CREATE, DROP, ALTER, etc. only
337  handle_ok() will be invoked, in case of success.
338 
339  All statements that result in an error will invoke handle_error().
340 
341  For statements that return a result set, handle_error() might be invoked
342  even after metadata was sent. This will indicate an error during the
343  execution of the statement.
344  */
345 
346  /* Getting metadata */
347 
355 
356  /* Getting data */
357 
367 
368  /* Getting execution status */
369 
373 };
374 
376  CS_TEXT_REPRESENTATION = 1, /* Let the server convert everything to string */
377  CS_BINARY_REPRESENTATION = 2, /* Let the server use native types */
378 };
379 
380 extern "C" struct command_service_st {
382  const union COM_DATA *data, const CHARSET_INFO *client_cs,
383  const struct st_command_service_cbs *callbacks,
384  enum cs_text_or_binary text_or_binary,
385  void *service_callbacks_ctx);
386 } * command_service;
387 
388 #ifdef MYSQL_DYNAMIC_PLUGIN
389 
390 #define command_service_run_command(t, command, data, cset, cbs, t_or_b, ctx) \
391  command_service->run_command((t), (command), (data), (cset), (cbs), \
392  (t_or_b), (ctx))
393 #else
394 
395 /**
396  Executes a server command in a session.
397 
398 
399  There are two cases. Execution in a physical thread :
400  1. initialized by the srv_session service
401  2. NOT initialized by the srv_session service
402 
403  In case of 1, if there is currently attached session, and it is
404  different from the passed one, the former will be automatically
405  detached. The session to be used for the execution will then be
406  attached. After the command is executed, the attached session will
407  not be detached. It will be detached by a next call to run_command()
408  with another session as parameter. In other words, for all sessions
409  used in a physical thread, there will be at most one in attached
410  state.
411 
412  In case of 2, the current state (current_thd) will be
413  preserved. Then the given session will move to attached state and
414  the command will be executed. After the execution the state of the
415  session will be changed to detached and the preserved state
416  (current_thd) will be restored.
417 
418  The client charset is used for commands like COM_QUERY and
419  COM_STMT_PREPARE to know how to threat the char* fields. This
420  charset will be used until the next call of run_command when it may
421  be changed again.
422 
423  @param session The session
424  @param command The command to be executed.
425  @param data The data needed for the command to be executed
426  @param client_cs The charset for the string data input(COM_QUERY for example)
427  @param callbacks Callbacks to be used by the server to encode data and
428  to communicate with the client (plugin) side.
429  @param text_or_binary Select which representation the server will use for the
430  data passed to the callbacks. For more information
431  @see cs_text_or_binary enum
432  @param service_callbacks_ctx Context passed to the command service callbacks
433 
434  @return
435  0 success
436  1 failure
437 */
440  const union COM_DATA *data,
441  const CHARSET_INFO *client_cs,
442  const struct st_command_service_cbs *callbacks,
443  enum cs_text_or_binary text_or_binary,
444  void *service_callbacks_ctx);
445 
446 #endif /* MYSQL_DYNAMIC_PLUGIN */
447 
448 #endif
void(* handle_error_t)(void *ctx, uint sql_errno, const char *err_msg, const char *sqlstate)
Command ended with ERROR.
Definition: service_command.h:305
Definition of COM_DATA to be used with the Command service as data input structure.
unsigned long long int ulonglong
Definition: my_inttypes.h:55
This file contains the field type.
int(* get_integer_t)(void *ctx, longlong value)
Receive TINY/SHORT/LONG value from server.
Definition: service_command.h:177
int(* get_string_t)(void *ctx, const char *value, size_t length, const CHARSET_INFO *valuecs)
Get STRING value from server.
Definition: service_command.h:279
int(* get_double_t)(void *ctx, double value, uint32_t decimals)
Receive FLOAT/DOUBLE from server.
Definition: service_command.h:218
const std::string charset("charset")
struct command_service_st * command_service
unsigned int flags
Definition: service_command.h:52
int(* start_row_t)(void *ctx)
Indicates the beginning of a new row in the result set/metadata.
Definition: service_command.h:120
static int run_command(char *cmd, DYNAMIC_STRING *ds_res)
Definition: mysqltest.cc:1730
class Srv_session * MYSQL_SESSION
Definition: service_srv_session_bits.h:36
const char * db_name
Definition: service_command.h:45
Definition: service_command.h:380
int(* get_date_t)(void *ctx, const MYSQL_TIME *value)
Get DATE value from server.
Definition: service_command.h:230
int(* get_null_t)(void *ctx)
Receive NULL value from server.
Definition: service_command.h:162
int(* start_result_metadata_t)(void *ctx, uint num_cols, uint flags, const CHARSET_INFO *resultcs)
Indicates beginning of metadata for the result set.
Definition: service_command.h:80
void(* handle_ok_t)(void *ctx, uint server_status, uint statement_warn_count, ulonglong affected_rows, ulonglong last_insert_id, const char *message)
Command ended with success.
Definition: service_command.h:293
MYSQL_SESSION session[9]
Definition: test_sql_9_sessions.cc:65
handle_ok_t handle_ok
Definition: service_command.h:370
int(* get_time_t)(void *ctx, const MYSQL_TIME *value, uint decimals)
Receive TIME value from server.
Definition: service_command.h:243
get_datetime_t get_datetime
Definition: service_command.h:365
Definition: com_data.h:106
enum_field_types type
Definition: service_command.h:54
const char * org_table_name
Definition: service_command.h:47
const char * org_col_name
Definition: service_command.h:49
get_client_capabilities_t get_client_capabilities
Definition: service_command.h:354
void(* shutdown_t)(void *ctx, int server_shutdown)
Callback for shutdown notification from the server.
Definition: service_command.h:315
abort_row_t abort_row
Definition: service_command.h:353
int(* field_metadata_t)(void *ctx, struct st_send_field *field, const CHARSET_INFO *charset)
Field metadata is provided via this callback.
Definition: service_command.h:94
get_string_t get_string
Definition: service_command.h:366
int(* get_decimal_t)(void *ctx, const decimal_t *value)
Receive DECIMAL value from server.
Definition: service_command.h:202
get_decimal_t get_decimal
Definition: service_command.h:361
start_result_metadata_t start_result_metadata
Definition: service_command.h:348
Definition: service_command.h:44
end_row_t end_row
Definition: service_command.h:352
get_time_t get_time
Definition: service_command.h:364
enum_field_types
Column types for MySQL.
Definition: field_types.h:52
unsigned int uint
Definition: uca-dump.cc:29
int(* end_result_metadata_t)(void *ctx, uint server_status, uint warn_count)
Indicates end of metadata for the result set.
Definition: service_command.h:108
long long int longlong
Definition: my_inttypes.h:54
get_double_t get_double
Definition: service_command.h:362
get_null_t get_null
Definition: service_command.h:358
int(* get_datetime_t)(void *ctx, const MYSQL_TIME *value, uint decimals)
Receive DATETIME value from server.
Definition: service_command.h:256
cs_text_or_binary
Definition: service_command.h:375
Definition: m_ctype.h:359
end_result_metadata_t end_result_metadata
Definition: service_command.h:350
enum_server_command
A list of all MySQL protocol commands.
Definition: my_command.h:47
get_longlong_t get_longlong
Definition: service_command.h:360
int command_service_run_command(MYSQL_SESSION session, enum enum_server_command command, const union COM_DATA *data, const CHARSET_INFO *client_cs, const struct st_command_service_cbs *callbacks, enum cs_text_or_binary text_or_binary, void *service_callbacks_ctx)
Executes a server command in a session.
command
Definition: version_token.cc:278
Definition: mysql_time.h:81
get_date_t get_date
Definition: service_command.h:363
void(* abort_row_t)(void *ctx)
An error occurred during execution.
Definition: service_command.h:142
unsigned long length
Definition: service_command.h:50
Time declarations shared between the server and client API: you should not add anything to this heade...
unsigned int decimals
Definition: service_command.h:53
A better implementation of the UNIX ctype(3) library.
const string value("\alue\)
shutdown_t shutdown
Definition: service_command.h:372
Definition: service_command.h:317
field_metadata_t field_metadata
Definition: service_command.h:349
get_integer_t get_integer
Definition: service_command.h:359
int(* end_row_t)(void *ctx)
Indicates the end of the current row in the result set/metadata.
Definition: service_command.h:131
static const sasl_callback_t callbacks[]
Definition: auth_ldap_sasl_client.h:44
start_row_t start_row
Definition: service_command.h:351
const char * table_name
Definition: service_command.h:46
Header file for the Server session service.
handle_error_t handle_error
Definition: service_command.h:371
unsigned int charsetnr
Definition: service_command.h:51
const char * col_name
Definition: service_command.h:48
intg is the number of decimal digits (NOT number of decimal_digit_t&#39;s !) before the point frac is the...
Definition: decimal.h:51
ulong(* get_client_capabilities_t)(void *ctx)
Return client&#39;s capabilities (see mysql_com.h, CLIENT_*)
Definition: service_command.h:151
Definition: service_command.h:377
int(* get_longlong_t)(void *ctx, longlong value, uint is_unsigned)
Get LONGLONG value from server.
Definition: service_command.h:190
Definition: service_command.h:376