MySQL  8.0.18
Source Code Documentation
protocol.h
Go to the documentation of this file.
1 #ifndef PROTOCOL_INCLUDED
2 #define PROTOCOL_INCLUDED
3 
4 /* Copyright (c) 2002, 2019, Oracle and/or its affiliates. All rights reserved.
5 
6  This program is free software; you can redistribute it and/or modify
7  it under the terms of the GNU General Public License, version 2.0,
8  as published by the Free Software Foundation.
9 
10  This program is also distributed with certain software (including
11  but not limited to OpenSSL) that is licensed under separate terms,
12  as designated in a particular file or component or in included license
13  documentation. The authors of MySQL hereby grant you an additional
14  permission to link the program and your derivative works with the
15  separately licensed software that they have included with MySQL.
16 
17  This program is distributed in the hope that it will be useful,
18  but WITHOUT ANY WARRANTY; without even the implied warranty of
19  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20  GNU General Public License, version 2.0, for more details.
21 
22  You should have received a copy of the GNU General Public License
23  along with this program; if not, write to the Free Software
24  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
25 
26 #include "my_dbug.h"
27 #include "mysql/com_data.h"
28 #include "mysql/mysql_lex_string.h" // LEX_STRING
29 #include "mysql_com.h" // mysql_enum_shutdown_level
30 #include "mysql_time.h" // MYSQL_TIME
31 #include "sql_string.h" // String
32 #include "violite.h" /* SSL && enum_vio_type */
33 
34 class my_decimal;
35 class Send_field;
36 class Item_param;
37 template <class T>
38 class List;
39 class Field;
40 
41 class Protocol {
42  private:
43  /// Pointer to the Protocol below on the stack.
45 
46  public:
47  virtual ~Protocol() {}
48 
49  /**
50  Remove the reference to the previous protocol and return it.
51 
52  @returns The new top of the Protocol stack.
53  */
57  m_previous_protocol = nullptr;
58  return protocol;
59  }
60 
61  /**
62  Set reference to "this" as the previous protocol on the protocol provided
63  as argument.
64 
65  @param protocol Protocol to become the top of Protocol stack.
66  */
68  DBUG_ASSERT(!protocol->m_previous_protocol);
69  protocol->m_previous_protocol = this;
70  }
71 
72  /**
73  Read packet from client
74 
75  @returns
76  -1 fatal error
77  0 ok
78  1 non-fatal error
79  */
80  virtual int read_packet() = 0;
81 
82  /**
83  Reads the command from the protocol and creates a command.
84 
85  @param com_data out parameter
86  @param cmd out parameter
87 
88  @returns
89  -1 fatal protcol error
90  0 ok
91  1 non-fatal protocol or parsing error
92  */
93  virtual int get_command(COM_DATA *com_data, enum_server_command *cmd) = 0;
94 
95  /**
96  Enum used by type() to specify the protocol type
97  */
99  PROTOCOL_TEXT = 0, // text Protocol type used mostly
100  // for the old (MySQL 4.0 protocol)
101  PROTOCOL_BINARY = 1, // binary protocol type
102  PROTOCOL_LOCAL = 2, // local protocol type(intercepts communication)
103  PROTOCOL_ERROR = 3, // error protocol instance
104  PROTOCOL_PLUGIN = 4 // pluggable protocol type
105  };
106 
107  /**
108  Flags available to alter the way the messages are sent to the client
109  */
110  enum { SEND_NUM_ROWS = 1, SEND_DEFAULTS = 2, SEND_EOF = 4 };
111 
112  virtual enum enum_protocol_type type() const = 0;
113 
114  virtual enum enum_vio_type connection_type() const = 0;
115 
116  /* Data sending functions */
117  virtual bool store_null() = 0;
118  virtual bool store_tiny(longlong from, uint32 zerofill) = 0;
119  virtual bool store_short(longlong from, uint32 zerofill) = 0;
120  virtual bool store_long(longlong from, uint32 zerofill) = 0;
121  virtual bool store_longlong(longlong from, bool unsigned_flag,
122  uint32 zerofill) = 0;
123  virtual bool store_decimal(const my_decimal *, uint, uint) = 0;
124  virtual bool store_string(const char *from, size_t length,
125  const CHARSET_INFO *fromcs) = 0;
126  virtual bool store_float(float from, uint32 decimals, uint32 zerofill) = 0;
127  virtual bool store_double(double from, uint32 decimals, uint32 zerofill) = 0;
128  virtual bool store_datetime(const MYSQL_TIME &time, uint precision) = 0;
129  virtual bool store_date(const MYSQL_TIME &time) = 0;
130  virtual bool store_time(const MYSQL_TIME &time, uint precision) = 0;
131  virtual bool store_field(const Field *field) = 0;
132  // Convenience wrappers
133  bool store(int from) { return store_long(longlong{from}, 0); }
134  bool store(uint32 from) { return store_long(longlong{from}, 0); }
135  bool store(longlong from) { return store_longlong(from, false, 0); }
136  bool store(ulonglong from) {
137  return store_longlong(static_cast<longlong>(from), true, 0);
138  }
139  bool store_tiny(longlong from) { return store_tiny(from, 0); }
140  bool store_short(longlong from) { return store_short(from, 0); }
141  bool store_long(longlong from) { return store_long(from, 0); }
142  bool store_longlong(longlong from, bool unsigned_flag) {
143  return store_longlong(from, unsigned_flag, 0);
144  }
145  /**
146  Send \\0 end terminated string.
147 
148  @param from NullS or \\0 terminated string.
149  @param fromcs Character set of the from string.
150 
151  @note In most cases one should use store(from, length, cs) instead of
152  this function
153 
154  @returns
155  false ok
156  true error
157  */
158  inline bool store(const char *from, const CHARSET_INFO *fromcs) {
159  return from ? store_string(from, strlen(from), fromcs) : store_null();
160  }
161  inline bool store(String *str) {
162  return store_string(str->ptr(), str->length(), str->charset());
163  }
164  inline bool store(const LEX_STRING &s, const CHARSET_INFO *cs) {
165  return store_string(s.str, s.length, cs);
166  }
167 
168  /**
169  Returns the client capabilities stored on the protocol.
170  The available capabilites are defined in mysql_com.h
171  */
172  virtual ulong get_client_capabilities() = 0;
173  /**
174  Checks if the client capabilities include the one
175  specified as parameter.
176 
177  @returns
178  true if it includes the specified capability
179  false otherwise
180  */
181  virtual bool has_client_capability(unsigned long client_capability) = 0;
182 
183  /**
184  Checks if the protocol's connection with the client is still alive.
185  It should always return true unless the protocol closed the connection.
186 
187  @returns
188  true if the connection is still alive
189  false otherwise
190  */
191  virtual bool connection_alive() const = 0;
192 
193  /**
194  Result set sending functions
195 
196  @details Server uses following schema to send result:
197  ... sending metadata ...
198  | start_result_metadata(...)
199  | start_row()
200  | send_field_metadata(...)
201  | end_row()
202  ... same for each field sent ...
203  | end_result_metadata(...)
204  |
205  ... sending result ...
206  | start_row(...)
207  | store_xxx(...)
208  ... store_xxx(..) is called for each field ...
209  | end_row(...)
210  ... same for each row, until all rows are sent ...
211  | send_ok/eof/error(...)
212  However, a protocol implementation might use different schema. For
213  example, Protocol_callback ignores start/end_row when metadata is being
214  sent.
215  */
216 
217  virtual void start_row() = 0;
218  virtual bool end_row() = 0;
219  virtual void abort_row() = 0;
220  virtual void end_partial_result_set() = 0;
221 
222  /**
223  Thread is being shut down, disconnect and free resources
224 
225  @param server_shutdown If false then this is normal thread shutdown. If
226  true then the server is shutting down.
227  */
228  virtual int shutdown(bool server_shutdown = false) = 0;
229  /**
230  Returns the read/writing status
231 
232  @return
233  @retval 1 Read
234  @retval 2 Write
235  @retval 0 Other(Idle, Killed)
236  */
237  virtual uint get_rw_status() = 0;
238  /**
239  Returns if the protocol is compressed or not.
240 
241  @return
242  @retval false Not compressed
243  @retval true Compressed
244  */
245  virtual bool get_compression() = 0;
246  /**
247  Returns compression algorithm name.
248 
249  @return
250  @retval string compression method name
251  @retval NULL if no compression is enabled
252  */
253  virtual char *get_compression_algorithm() = 0;
254  /**
255  Returns compression level.
256 
257  @return
258  @retval uint compression level
259  */
260  virtual uint get_compression_level() = 0;
261  /**
262  Prepares the server for metadata sending.
263  Notifies the client that the metadata sending will start.
264 
265  @param num_cols Number of columns that will be sent
266  @param flags Flags to alter the metadata sending
267  Can be any of the following:
268  SEND_NUM_ROWS, SEND_DEFAULTS, SEND_EOF
269  @param resultcs Charset to convert to
270 
271  @return
272  @retval false Ok
273  @retval true An error occurred
274  */
275 
276  virtual bool start_result_metadata(uint num_cols, uint flags,
277  const CHARSET_INFO *resultcs) = 0;
278  /**
279  Sends field metadata.
280 
281  @param field Field metadata to be send to the client
282  @param charset Field's charset: in case it is different
283  than the one used by the connection it will
284  be used to convert the value to
285  the connection's charset
286 
287  @return
288  @retval false The metadata was successfully sent
289  @retval true An error occurred
290  */
291 
292  virtual bool send_field_metadata(Send_field *field,
293  const CHARSET_INFO *charset) = 0;
294  /**
295  Signals the client that the metadata sending is done.
296  Clears the server after sending the metadata.
297 
298  @return
299  @retval false Ok
300  @retval true An error occurred
301  */
302  virtual bool end_result_metadata() = 0;
303 
304  /**
305  Send ok message to the client.
306 
307  @param server_status The server status
308  @param statement_warn_count Total number of warnings
309  @param affected_rows Number of rows changed by statement
310  @param last_insert_id Last insert id (Auto_increment id for first
311  row if used)
312  @param message Message to send to the client
313 
314  @return
315  @retval false The message was successfully sent
316  @retval true An error occurred and the messages wasn't sent properly
317  */
318  virtual bool send_ok(uint server_status, uint statement_warn_count,
319  ulonglong affected_rows, ulonglong last_insert_id,
320  const char *message) = 0;
321  /**
322  Send eof message to the client.
323 
324  @param server_status The server status
325  @param statement_warn_count Total number of warnings
326 
327  @return
328  @retval false The message was successfully sent
329  @retval true An error occurred and the messages wasn't sent properly
330  */
331  virtual bool send_eof(uint server_status, uint statement_warn_count) = 0;
332  /**
333  Send error message to the client.
334 
335  @param sql_errno The error code to send
336  @param err_msg A pointer to the error message
337  @param sql_state SQL state
338 
339  @return
340  @retval false The message was successfully sent
341  @retval true An error occurred and the messages wasn't sent properly
342  */
343 
344  virtual bool send_error(uint sql_errno, const char *err_msg,
345  const char *sql_state) = 0;
346 
347  /**
348  Used for the classic protocol.
349  Makes the protocol send the messages/data to the client.
350 
351  @return
352  @retval false The flush was successful.
353  @retval true An error occurred.
354  */
355  virtual bool flush() = 0;
356 
357  /**
358  Sends prepared statement's id and metadata to the client after prepare.
359 
360  @param stmt_id Statement id.
361  @param column_count Number of columns.
362  @param param_count Number of parameters.
363  @param cond_count Number of conditions raised by the current statement.
364 
365  @return Error status.
366  @retval false The send was successful.
367  @retval true An error occurred.
368  */
369  virtual bool store_ps_status(ulong stmt_id, uint column_count,
370  uint param_count, ulong cond_count) = 0;
371 
372  /**
373  Sends the OUT-parameters to the client.
374 
375  @param parameters List of PS/SP parameters (both input and output).
376  @param is_sql_prepare Used for the legacy protocol. If we're dealing with
377  sql prepare then text protocol wil be used.
378 
379  @return Error status.
380  @retval false Success.
381  @retval true Error.
382  */
383  virtual bool send_parameters(List<Item_param> *parameters,
384  bool is_sql_prepare) = 0;
385 };
386 
387 #endif /* PROTOCOL_INCLUDED */
virtual bool send_ok(uint server_status, uint statement_warn_count, ulonglong affected_rows, ulonglong last_insert_id, const char *message)=0
Send ok message to the client.
Definition of COM_DATA to be used with the Command service as data input structure.
bool store(const char *from, const CHARSET_INFO *fromcs)
Send \0 end terminated string.
Definition: protocol.h:158
unsigned long long int ulonglong
Definition: my_inttypes.h:55
Definition: field.h:4920
enum_protocol_type
Enum used by type() to specify the protocol type.
Definition: protocol.h:98
char * str
Definition: mysql_lex_string.h:35
Our own string classes, used pervasively throughout the executor.
Definition: protocol.h:102
Definition: mysql_lex_string.h:34
Definition: protocol.h:104
bool store(int from)
Definition: protocol.h:133
virtual int shutdown(bool server_shutdown=false)=0
Thread is being shut down, disconnect and free resources.
virtual enum enum_protocol_type type() const =0
bool store_long(longlong from)
Definition: protocol.h:141
virtual int read_packet()=0
Read packet from client.
virtual bool store_null()=0
virtual ~Protocol()
Definition: protocol.h:47
Definition: protocol.h:110
virtual bool flush()=0
Used for the classic protocol.
virtual char * get_compression_algorithm()=0
Returns compression algorithm name.
Definition: field.h:700
bool store(uint32 from)
Definition: protocol.h:134
virtual bool send_field_metadata(Send_field *field, const CHARSET_INFO *charset)=0
Sends field metadata.
virtual bool store_ps_status(ulong stmt_id, uint column_count, uint param_count, ulong cond_count)=0
Sends prepared statement&#39;s id and metadata to the client after prepare.
virtual bool get_compression()=0
Returns if the protocol is compressed or not.
Definition: com_data.h:106
protocol
Definition: memcached.h:112
Definition: protocol.h:110
Definition: protocol.h:110
Using this class is fraught with peril, and you need to be very careful when doing so...
Definition: sql_string.h:161
virtual bool store_date(const MYSQL_TIME &time)=0
virtual int get_command(COM_DATA *com_data, enum_server_command *cmd)=0
Reads the command from the protocol and creates a command.
virtual bool end_result_metadata()=0
Signals the client that the metadata sending is done.
virtual bool end_row()=0
virtual bool store_tiny(longlong from, uint32 zerofill)=0
Common definition between mysql server & client.
void push_protocol(Protocol *protocol)
Set reference to "this" as the previous protocol on the protocol provided as argument.
Definition: protocol.h:67
virtual bool store_short(longlong from, uint32 zerofill)=0
Definition: protocol.h:99
Placeholder (&#39;?&#39;) of prepared statement.
Definition: item.h:3659
#define DBUG_ASSERT(A)
Definition: my_dbug.h:197
bool store_longlong(longlong from, bool unsigned_flag)
Definition: protocol.h:142
bool store(longlong from)
Definition: protocol.h:135
Protocol * m_previous_protocol
Pointer to the Protocol below on the stack.
Definition: protocol.h:44
virtual enum enum_vio_type connection_type() const =0
virtual uint get_rw_status()=0
Returns the read/writing status.
Protocol * pop_protocol()
Remove the reference to the previous protocol and return it.
Definition: protocol.h:54
bool store(const LEX_STRING &s, const CHARSET_INFO *cs)
Definition: protocol.h:164
Definition: aggregate_check.h:523
my_decimal class limits &#39;decimal_t&#39; type to what we need in MySQL.
Definition: my_decimal.h:91
virtual bool start_result_metadata(uint num_cols, uint flags, const CHARSET_INFO *resultcs)=0
Prepares the server for metadata sending.
virtual bool store_field(const Field *field)=0
unsigned int uint
Definition: uca-dump.cc:29
virtual void end_partial_result_set()=0
long long int longlong
Definition: my_inttypes.h:54
enum_vio_type
Definition: violite.h:75
uint32_t uint32
Definition: my_inttypes.h:66
virtual bool send_parameters(List< Item_param > *parameters, bool is_sql_prepare)=0
Sends the OUT-parameters to the client.
Definition: m_ctype.h:359
virtual bool store_longlong(longlong from, bool unsigned_flag, uint32 zerofill)=0
bool store_short(longlong from)
Definition: protocol.h:140
enum_server_command
A list of all MySQL protocol commands.
Definition: my_command.h:47
size_t length
Definition: mysql_lex_string.h:36
virtual bool store_decimal(const my_decimal *, uint, uint)=0
Definition: protocol.h:103
virtual bool store_long(longlong from, uint32 zerofill)=0
virtual bool store_double(double from, uint32 decimals, uint32 zerofill)=0
Definition: mysql_time.h:64
virtual ulong get_client_capabilities()=0
Returns the client capabilities stored on the protocol.
bool store_tiny(longlong from)
Definition: protocol.h:139
Definition: protocol.h:34
virtual bool store_time(const MYSQL_TIME &time, uint precision)=0
bool store(String *str)
Definition: protocol.h:161
bool store(ulonglong from)
Definition: protocol.h:136
char sql_state[64]
Definition: test_sql_9_sessions.cc:297
virtual bool store_string(const char *from, size_t length, const CHARSET_INFO *fromcs)=0
Vio Lite.
Time declarations shared between the server and client API: you should not add anything to this heade...
virtual bool send_eof(uint server_status, uint statement_warn_count)=0
Send eof message to the client.
const CHARSET_INFO * charset() const
Definition: sql_string.h:234
virtual bool store_float(float from, uint32 decimals, uint32 zerofill)=0
virtual void abort_row()=0
Definition: protocol.h:101
COM_DATA cmd
Definition: test_session_info.cc:95
virtual uint get_compression_level()=0
Returns compression level.
const char * ptr() const
Definition: sql_string.h:243
static int flags[50]
Definition: hp_test1.cc:39
virtual bool store_datetime(const MYSQL_TIME &time, uint precision)=0
virtual bool has_client_capability(unsigned long client_capability)=0
Checks if the client capabilities include the one specified as parameter.
virtual bool send_error(uint sql_errno, const char *err_msg, const char *sql_state)=0
Send error message to the client.
unsigned long ulong
Definition: my_inttypes.h:48
bool length(const dd::Spatial_reference_system *srs, const Geometry *g1, double *length, bool *null) noexcept
Computes the length of linestrings and multilinestrings.
Definition: length.cc:75
size_t length() const
Definition: sql_string.h:235
virtual void start_row()=0
Result set sending functions.
virtual bool connection_alive() const =0
Checks if the protocol&#39;s connection with the client is still alive.