MySQL 8.0.33
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, 2023, 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
35class my_decimal;
36class Send_field;
37class Item_param;
38template <class T>
39class List;
40class Field;
41
42class 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 protocol 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 capabilities 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 will 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:574
Dynamic parameters used as placeholders ('?') inside prepared statements.
Definition: item.h:4536
Definition: sql_list.h:433
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.
Protocol * pop_protocol()
Remove the reference to the previous protocol and return it.
Definition: protocol.h:55
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.
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.
@ SEND_DEFAULTS
Definition: protocol.h:110
@ SEND_NUM_ROWS
Definition: protocol.h:110
@ SEND_EOF
Definition: protocol.h:110
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.
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:4556
Using this class is fraught with peril, and you need to be very careful when doing so.
Definition: sql_string.h:166
my_decimal class limits 'decimal_t' type to what we need in MySQL.
Definition: my_decimal.h:93
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:1054
constexpr value_type zerofill
Definition: classic_protocol_constants.h:271
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:382
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: uca9-dump.cc:74
Definition: com_data.h:111
Vio Lite.
enum_vio_type
Definition: violite.h:78