MySQL  8.0.27
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, 2021, Oracle and/or its affiliates.
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 <assert.h>
27 
28 #include "mysql/com_data.h"
29 #include "mysql/mysql_lex_string.h" // LEX_STRING
30 #include "mysql_com.h" // mysql_enum_shutdown_level
31 #include "mysql_time.h" // MYSQL_TIME
32 #include "sql_string.h" // String
33 #include "violite.h" /* SSL && enum_vio_type */
34 
35 class my_decimal;
36 class Send_field;
37 class Item_param;
38 template <class T>
39 class List;
40 class Field;
41 
42 class Protocol {
43  private:
44  /// Pointer to the Protocol below on the stack.
46 
47  public:
48  virtual ~Protocol() = default;
49 
50  /**
51  Remove the reference to the previous protocol and return it.
52 
53  @returns The new top of the Protocol stack.
54  */
56  assert(m_previous_protocol);
57  Protocol *protocol = m_previous_protocol;
58  m_previous_protocol = nullptr;
59  return protocol;
60  }
61 
62  /**
63  Set reference to "this" as the previous protocol on the protocol provided
64  as argument.
65 
66  @param protocol Protocol to become the top of Protocol stack.
67  */
68  void push_protocol(Protocol *protocol) {
69  assert(!protocol->m_previous_protocol);
70  protocol->m_previous_protocol = this;
71  }
72 
73  /**
74  Read packet from client
75 
76  @retval -1 fatal error
77  @retval 0 ok
78  @retval 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  @retval false ok
155  @retval true error
156  */
157  inline bool store(const char *from, const CHARSET_INFO *fromcs) {
158  return from ? store_string(from, strlen(from), fromcs) : store_null();
159  }
160  inline bool store(String *str) {
161  return store_string(str->ptr(), str->length(), str->charset());
162  }
163  inline bool store(const LEX_STRING &s, const CHARSET_INFO *cs) {
164  return store_string(s.str, s.length, cs);
165  }
166 
167  /**
168  Returns the client capabilities stored on the protocol.
169  The available capabilites are defined in mysql_com.h
170  */
171  virtual ulong get_client_capabilities() = 0;
172  /**
173  Checks if the client capabilities include the one
174  specified as parameter.
175 
176  @retval true if it includes the specified capability
177  @retval false otherwise
178  */
179  virtual bool has_client_capability(unsigned long client_capability) = 0;
180 
181  /**
182  Checks if the protocol's connection with the client is still alive.
183  It should always return true unless the protocol closed the connection.
184 
185  @retval true if the connection is still alive
186  @retval false otherwise
187  */
188  virtual bool connection_alive() const = 0;
189 
190  /**
191  Result set sending functions
192 
193  @details Server uses following schema to send result:
194  ... sending metadata ...
195  | start_result_metadata(...)
196  | start_row()
197  | send_field_metadata(...)
198  | end_row()
199  ... same for each field sent ...
200  | end_result_metadata(...)
201  |
202  ... sending result ...
203  | start_row(...)
204  | store_xxx(...)
205  ... store_xxx(..) is called for each field ...
206  | end_row(...)
207  ... same for each row, until all rows are sent ...
208  | send_ok/eof/error(...)
209  However, a protocol implementation might use different schema. For
210  example, Protocol_callback ignores start/end_row when metadata is being
211  sent.
212  */
213 
214  virtual void start_row() = 0;
215  virtual bool end_row() = 0;
216  virtual void abort_row() = 0;
217  virtual void end_partial_result_set() = 0;
218 
219  /**
220  Thread is being shut down, disconnect and free resources
221 
222  @param server_shutdown If false then this is normal thread shutdown. If
223  true then the server is shutting down.
224  */
225  virtual int shutdown(bool server_shutdown = false) = 0;
226  /**
227  Returns the read/writing status
228 
229  @retval 1 Read
230  @retval 2 Write
231  @retval 0 Other(Idle, Killed)
232  */
233  virtual uint get_rw_status() = 0;
234  /**
235  Returns if the protocol is compressed or not.
236 
237  @retval false Not compressed
238  @retval true Compressed
239  */
240  virtual bool get_compression() = 0;
241  /**
242  Returns compression algorithm name.
243 
244  @retval string compression method name
245  @retval NULL if no compression is enabled
246  */
247  virtual char *get_compression_algorithm() = 0;
248  /**
249  Returns compression level.
250 
251  @returns compression level
252  */
254  /**
255  Prepares the server for metadata sending.
256  Notifies the client that the metadata sending will start.
257 
258  @param num_cols Number of columns that will be sent
259  @param flags Flags to alter the metadata sending
260  Can be any of the following:
261  SEND_NUM_ROWS, SEND_DEFAULTS, SEND_EOF
262  @param resultcs Charset to convert to
263 
264  @retval false Ok
265  @retval true An error occurred
266  */
267 
268  virtual bool start_result_metadata(uint num_cols, uint flags,
269  const CHARSET_INFO *resultcs) = 0;
270  /**
271  Sends field metadata.
272 
273  @param field Field metadata to be send to the client
274  @param charset Field's charset: in case it is different
275  than the one used by the connection it will
276  be used to convert the value to
277  the connection's charset
278 
279  @retval false The metadata was successfully sent
280  @retval true An error occurred
281  */
282 
283  virtual bool send_field_metadata(Send_field *field,
284  const CHARSET_INFO *charset) = 0;
285  /**
286  Signals the client that the metadata sending is done.
287  Clears the server after sending the metadata.
288 
289  @retval false Ok
290  @retval true An error occurred
291  */
292  virtual bool end_result_metadata() = 0;
293 
294  /**
295  Send ok message to the client.
296 
297  @param server_status The server status
298  @param statement_warn_count Total number of warnings
299  @param affected_rows Number of rows changed by statement
300  @param last_insert_id Last insert id (Auto_increment id for first
301  row if used)
302  @param message Message to send to the client
303 
304  @retval false The message was successfully sent
305  @retval true An error occurred and the messages wasn't sent properly
306  */
307  virtual bool send_ok(uint server_status, uint statement_warn_count,
308  ulonglong affected_rows, ulonglong last_insert_id,
309  const char *message) = 0;
310  /**
311  Send eof message to the client.
312 
313  @param server_status The server status
314  @param statement_warn_count Total number of warnings
315 
316  @retval false The message was successfully sent
317  @retval true An error occurred and the messages wasn't sent properly
318  */
319  virtual bool send_eof(uint server_status, uint statement_warn_count) = 0;
320  /**
321  Send error message to the client.
322 
323  @param sql_errno The error code to send
324  @param err_msg A pointer to the error message
325  @param sql_state SQL state
326 
327  @retval false The message was successfully sent
328  @retval true An error occurred and the messages wasn't sent properly
329  */
330 
331  virtual bool send_error(uint sql_errno, const char *err_msg,
332  const char *sql_state) = 0;
333 
334  /**
335  Used for the classic protocol.
336  Makes the protocol send the messages/data to the client.
337 
338  @retval false The flush was successful.
339  @retval true An error occurred.
340  */
341  virtual bool flush() = 0;
342 
343  /**
344  Sends prepared statement's id and metadata to the client after prepare.
345 
346  @param stmt_id Statement id.
347  @param column_count Number of columns.
348  @param param_count Number of parameters.
349  @param cond_count Number of conditions raised by the current statement.
350 
351  @return Error status.
352  @retval false The send was successful.
353  @retval true An error occurred.
354  */
355  virtual bool store_ps_status(ulong stmt_id, uint column_count,
356  uint param_count, ulong cond_count) = 0;
357 
358  /**
359  Sends the OUT-parameters to the client.
360 
361  @param parameters List of PS/SP parameters (both input and output).
362  @param is_sql_prepare Used for the legacy protocol. If we're dealing with
363  sql prepare then text protocol wil be used.
364 
365  @return Error status.
366  @retval false Success.
367  @retval true Error.
368  */
369  virtual bool send_parameters(List<Item_param> *parameters,
370  bool is_sql_prepare) = 0;
371 };
372 
373 #endif /* PROTOCOL_INCLUDED */
Definition: field.h:590
Dynamic parameters used as placeholders ('?') inside prepared statements.
Definition: item.h:4434
Definition: sql_list.h:431
Definition: protocol.h:32
bool store(uint32 from)
Definition: protocol.h:134
virtual bool flush()=0
Used for the classic protocol.
virtual bool store_field(const Field *field)=0
virtual bool store_ps_status(ulong stmt_id, uint column_count, uint param_count, ulong cond_count)=0
Sends prepared statement's id and metadata to the client after prepare.
virtual bool store_null()=0
virtual bool store_float(float from, uint32 decimals, uint32 zerofill)=0
virtual bool store_decimal(const my_decimal *, uint, uint)=0
virtual bool store_short(longlong from, uint32 zerofill)=0
virtual bool store_time(const MYSQL_TIME &time, uint precision)=0
virtual bool store_long(longlong from, uint32 zerofill)=0
bool store(longlong from)
Definition: protocol.h:135
virtual bool store_string(const char *from, size_t length, const CHARSET_INFO *fromcs)=0
virtual ~Protocol()=default
virtual bool store_datetime(const MYSQL_TIME &time, uint precision)=0
virtual bool end_result_metadata()=0
Signals the client that the metadata sending is done.
bool store_long(longlong from)
Definition: protocol.h:141
bool store(ulonglong from)
Definition: protocol.h:136
virtual void abort_row()=0
virtual uint get_compression_level()=0
Returns compression level.
void push_protocol(Protocol *protocol)
Set reference to "this" as the previous protocol on the protocol provided as argument.
Definition: protocol.h:68
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.
bool store_longlong(longlong from, bool unsigned_flag)
Definition: protocol.h:142
virtual char * get_compression_algorithm()=0
Returns compression algorithm name.
virtual int shutdown(bool server_shutdown=false)=0
Thread is being shut down, disconnect and free resources.
virtual int get_command(COM_DATA *com_data, enum_server_command *cmd)=0
Reads the command from the protocol and creates a command.
bool store_tiny(longlong from)
Definition: protocol.h:139
virtual void start_row()=0
Result set sending functions.
virtual bool end_row()=0
virtual bool send_error(uint sql_errno, const char *err_msg, const char *sql_state)=0
Send error message to the client.
bool store(String *str)
Definition: protocol.h:160
virtual bool get_compression()=0
Returns if the protocol is compressed or not.
@ SEND_DEFAULTS
Definition: protocol.h:110
@ SEND_NUM_ROWS
Definition: protocol.h:110
@ SEND_EOF
Definition: protocol.h:110
Protocol * m_previous_protocol
Pointer to the Protocol below on the stack.
Definition: protocol.h:45
virtual int read_packet()=0
Read packet from client.
virtual uint get_rw_status()=0
Returns the read/writing status.
virtual bool store_double(double from, uint32 decimals, uint32 zerofill)=0
virtual enum enum_vio_type connection_type() const =0
virtual bool send_eof(uint server_status, uint statement_warn_count)=0
Send eof message to the client.
virtual bool start_result_metadata(uint num_cols, uint flags, const CHARSET_INFO *resultcs)=0
Prepares the server for metadata sending.
bool store(const char *from, const CHARSET_INFO *fromcs)
Send \0 end terminated string.
Definition: protocol.h:157
virtual bool connection_alive() const =0
Checks if the protocol's connection with the client is still alive.
virtual enum enum_protocol_type type() const =0
bool store(const LEX_STRING &s, const CHARSET_INFO *cs)
Definition: protocol.h:163
virtual bool send_field_metadata(Send_field *field, const CHARSET_INFO *charset)=0
Sends field metadata.
enum_protocol_type
Enum used by type() to specify the protocol type.
Definition: protocol.h:98
@ PROTOCOL_ERROR
Definition: protocol.h:103
@ PROTOCOL_PLUGIN
Definition: protocol.h:104
@ PROTOCOL_BINARY
Definition: protocol.h:101
@ PROTOCOL_LOCAL
Definition: protocol.h:102
@ PROTOCOL_TEXT
Definition: protocol.h:99
bool store_short(longlong from)
Definition: protocol.h:140
virtual bool send_parameters(List< Item_param > *parameters, bool is_sql_prepare)=0
Sends the OUT-parameters to the client.
Protocol * pop_protocol()
Remove the reference to the previous protocol and return it.
Definition: protocol.h:55
virtual bool store_date(const MYSQL_TIME &time)=0
bool store(int from)
Definition: protocol.h:133
virtual bool store_tiny(longlong from, uint32 zerofill)=0
virtual bool has_client_capability(unsigned long client_capability)=0
Checks if the client capabilities include the one specified as parameter.
virtual bool store_longlong(longlong from, bool unsigned_flag, uint32 zerofill)=0
virtual void end_partial_result_set()=0
virtual ulong get_client_capabilities()=0
Returns the client capabilities stored on the protocol.
Definition: field.h:4583
Using this class is fraught with peril, and you need to be very careful when doing so.
Definition: sql_string.h:165
my_decimal class limits 'decimal_t' type to what we need in MySQL.
Definition: my_decimal.h:92
Definition of COM_DATA to be used with the Command service as data input structure.
static int flags[50]
Definition: hp_test1.cc:39
enum_server_command
A list of all MySQL protocol commands.
Definition: my_command.h:47
unsigned long long int ulonglong
Definition: my_inttypes.h:55
long long int longlong
Definition: my_inttypes.h:54
uint32_t uint32
Definition: my_inttypes.h:66
Common definition between mysql server & client.
Time declarations shared between the server and client API: you should not add anything to this heade...
std::string str(const mysqlrouter::ConfigGenerator::Options::Endpoint &ep)
Definition: config_generator.cc:1056
constexpr value_type zerofill
Definition: classic_protocol_constants.h:269
const std::string charset("charset")
Definition: commit_order_queue.h:33
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
Our own string classes, used pervasively throughout the executor.
Definition: m_ctype.h:354
Definition: mysql_lex_string.h:34
char * str
Definition: mysql_lex_string.h:35
size_t length
Definition: mysql_lex_string.h:36
Definition: mysql_time.h:81
unsigned int uint
Definition: uca-dump.cc:29
Definition: com_data.h:111
Vio Lite.
enum_vio_type
Definition: violite.h:77