MySQL 9.0.0
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, 2024, 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 designed to work 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 either included with
16 the program or referenced in the documentation.
17
18 This program is distributed in the hope that it will be useful,
19 but WITHOUT ANY WARRANTY; without even the implied warranty of
20 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 GNU General Public License, version 2.0, for more details.
22
23 You should have received a copy of the GNU General Public License
24 along with this program; if not, write to the Free Software
25 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
26
27#include <assert.h>
28
29#include "mysql/com_data.h"
30#include "mysql/mysql_lex_string.h" // LEX_STRING
31#include "mysql_com.h" // mysql_enum_shutdown_level
32#include "mysql_time.h" // MYSQL_TIME
33#include "sql_string.h" // String
34#include "violite.h" /* SSL && enum_vio_type */
35
36class my_decimal;
37class Send_field;
38class Item_param;
39template <class T>
40class List;
41class Field;
42
43struct CHARSET_INFO;
44
45class Protocol {
46 private:
47 /// Pointer to the Protocol below on the stack.
49
50 public:
51 virtual ~Protocol() = default;
52
53 /**
54 Remove the reference to the previous protocol and return it.
55
56 @returns The new top of the Protocol stack.
57 */
59 assert(m_previous_protocol);
60 Protocol *protocol = m_previous_protocol;
61 m_previous_protocol = nullptr;
62 return protocol;
63 }
64
65 /**
66 Set reference to "this" as the previous protocol on the protocol provided
67 as argument.
68
69 @param protocol Protocol to become the top of Protocol stack.
70 */
71 void push_protocol(Protocol *protocol) {
72 assert(!protocol->m_previous_protocol);
73 protocol->m_previous_protocol = this;
74 }
75
76 /**
77 Read packet from client
78
79 @retval -1 fatal error
80 @retval 0 ok
81 @retval 1 non-fatal error
82 */
83 virtual int read_packet() = 0;
84
85 /**
86 Reads the command from the protocol and creates a command.
87
88 @param com_data out parameter
89 @param cmd out parameter
90
91 @returns
92 -1 fatal protocol error
93 0 ok
94 1 non-fatal protocol or parsing error
95 */
96 virtual int get_command(COM_DATA *com_data, enum_server_command *cmd) = 0;
97
98 /**
99 Enum used by type() to specify the protocol type
100 */
102 PROTOCOL_TEXT = 0, // text Protocol type used mostly
103 // for the old (MySQL 4.0 protocol)
104 PROTOCOL_BINARY = 1, // binary protocol type
105 PROTOCOL_LOCAL = 2, // local protocol type(intercepts communication)
106 PROTOCOL_ERROR = 3, // error protocol instance
107 PROTOCOL_PLUGIN = 4 // pluggable protocol type
108 };
109
110 /**
111 Flags available to alter the way the messages are sent to the client
112 */
113 enum { SEND_NUM_ROWS = 1, SEND_DEFAULTS = 2, SEND_EOF = 4 };
114
115 virtual enum enum_protocol_type type() const = 0;
116
117 virtual enum enum_vio_type connection_type() const = 0;
118
119 /* Data sending functions */
120 virtual bool store_null() = 0;
121 virtual bool store_tiny(longlong from, uint32 zerofill) = 0;
122 virtual bool store_short(longlong from, uint32 zerofill) = 0;
123 virtual bool store_long(longlong from, uint32 zerofill) = 0;
124 virtual bool store_longlong(longlong from, bool unsigned_flag,
125 uint32 zerofill) = 0;
126 virtual bool store_decimal(const my_decimal *, uint, uint) = 0;
127 virtual bool store_string(const char *from, size_t length,
128 const CHARSET_INFO *fromcs) = 0;
129 virtual bool store_float(float from, uint32 decimals, uint32 zerofill) = 0;
130 virtual bool store_double(double from, uint32 decimals, uint32 zerofill) = 0;
131 virtual bool store_datetime(const MYSQL_TIME &time, uint precision) = 0;
132 virtual bool store_date(const MYSQL_TIME &time) = 0;
133 virtual bool store_time(const MYSQL_TIME &time, uint precision) = 0;
134 virtual bool store_field(const Field *field) = 0;
135 // Convenience wrappers
136 bool store(int from) { return store_long(longlong{from}, 0); }
137 bool store(uint32 from) { return store_long(longlong{from}, 0); }
138 bool store(longlong from) { return store_longlong(from, false, 0); }
139 bool store(ulonglong from) {
140 return store_longlong(static_cast<longlong>(from), true, 0);
141 }
142 bool store_tiny(longlong from) { return store_tiny(from, 0); }
143 bool store_short(longlong from) { return store_short(from, 0); }
144 bool store_long(longlong from) { return store_long(from, 0); }
145 bool store_longlong(longlong from, bool unsigned_flag) {
146 return store_longlong(from, unsigned_flag, 0);
147 }
148 /**
149 Send \\0 end terminated string.
150
151 @param from NullS or \\0 terminated string.
152 @param fromcs Character set of the from string.
153
154 @note In most cases one should use store(from, length, cs) instead of
155 this function
156
157 @retval false ok
158 @retval true error
159 */
160 inline bool store(const char *from, const CHARSET_INFO *fromcs) {
161 return from ? store_string(from, strlen(from), fromcs) : store_null();
162 }
163 inline bool store(String *str) {
164 return store_string(str->ptr(), str->length(), str->charset());
165 }
166 inline bool store(const LEX_STRING &s, const CHARSET_INFO *cs) {
167 return store_string(s.str, s.length, cs);
168 }
169
170 /**
171 Returns the client capabilities stored on the protocol.
172 The available capabilities are defined in mysql_com.h
173 */
174 virtual ulong get_client_capabilities() = 0;
175 /**
176 Checks if the client capabilities include the one
177 specified as parameter.
178
179 @retval true if it includes the specified capability
180 @retval false otherwise
181 */
182 virtual bool has_client_capability(unsigned long client_capability) = 0;
183
184 /**
185 Checks if the protocol's connection with the client is still alive.
186 It should always return true unless the protocol closed the connection.
187
188 @retval true if the connection is still alive
189 @retval 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 @retval 1 Read
233 @retval 2 Write
234 @retval 0 Other(Idle, Killed)
235 */
236 virtual uint get_rw_status() = 0;
237 /**
238 Returns if the protocol is compressed or not.
239
240 @retval false Not compressed
241 @retval true Compressed
242 */
243 virtual bool get_compression() = 0;
244 /**
245 Returns compression algorithm name.
246
247 @retval string compression method name
248 @retval NULL if no compression is enabled
249 */
250 virtual char *get_compression_algorithm() = 0;
251 /**
252 Returns compression level.
253
254 @returns compression level
255 */
256 virtual uint get_compression_level() = 0;
257 /**
258 Prepares the server for metadata sending.
259 Notifies the client that the metadata sending will start.
260
261 @param num_cols Number of columns that will be sent
262 @param flags Flags to alter the metadata sending
263 Can be any of the following:
264 SEND_NUM_ROWS, SEND_DEFAULTS, SEND_EOF
265 @param resultcs Charset to convert to
266
267 @retval false Ok
268 @retval true An error occurred
269 */
270
271 virtual bool start_result_metadata(uint num_cols, uint flags,
272 const CHARSET_INFO *resultcs) = 0;
273 /**
274 Sends field metadata.
275
276 @param field Field metadata to be send to the client
277 @param charset Field's charset: in case it is different
278 than the one used by the connection it will
279 be used to convert the value to
280 the connection's charset
281
282 @retval false The metadata was successfully sent
283 @retval true An error occurred
284 */
285
286 virtual bool send_field_metadata(Send_field *field,
287 const CHARSET_INFO *charset) = 0;
288 /**
289 Signals the client that the metadata sending is done.
290 Clears the server after sending the metadata.
291
292 @retval false Ok
293 @retval true An error occurred
294 */
295 virtual bool end_result_metadata() = 0;
296
297 /**
298 Send ok message to the client.
299
300 @param server_status The server status
301 @param statement_warn_count Total number of warnings
302 @param affected_rows Number of rows changed by statement
303 @param last_insert_id Last insert id (Auto_increment id for first
304 row if used)
305 @param message Message to send to the client
306
307 @retval false The message was successfully sent
308 @retval true An error occurred and the messages wasn't sent properly
309 */
310 virtual bool send_ok(uint server_status, uint statement_warn_count,
311 ulonglong affected_rows, ulonglong last_insert_id,
312 const char *message) = 0;
313 /**
314 Send eof message to the client.
315
316 @param server_status The server status
317 @param statement_warn_count Total number of warnings
318
319 @retval false The message was successfully sent
320 @retval true An error occurred and the messages wasn't sent properly
321 */
322 virtual bool send_eof(uint server_status, uint statement_warn_count) = 0;
323 /**
324 Send error message to the client.
325
326 @param sql_errno The error code to send
327 @param err_msg A pointer to the error message
328 @param sql_state SQL state
329
330 @retval false The message was successfully sent
331 @retval true An error occurred and the messages wasn't sent properly
332 */
333
334 virtual bool send_error(uint sql_errno, const char *err_msg,
335 const char *sql_state) = 0;
336
337 /**
338 Used for the classic protocol.
339 Makes the protocol send the messages/data to the client.
340
341 @retval false The flush was successful.
342 @retval true An error occurred.
343 */
344 virtual bool flush() = 0;
345
346 /**
347 Sends prepared statement's id and metadata to the client after prepare.
348
349 @param stmt_id Statement id.
350 @param column_count Number of columns.
351 @param param_count Number of parameters.
352 @param cond_count Number of conditions raised by the current statement.
353
354 @return Error status.
355 @retval false The send was successful.
356 @retval true An error occurred.
357 */
358 virtual bool store_ps_status(ulong stmt_id, uint column_count,
359 uint param_count, ulong cond_count) = 0;
360
361 /**
362 Sends the OUT-parameters to the client.
363
364 @param parameters List of PS/SP parameters (both input and output).
365 @param is_sql_prepare Used for the legacy protocol. If we're dealing with
366 sql prepare then text protocol will be used.
367
368 @return Error status.
369 @retval false Success.
370 @retval true Error.
371 */
372 virtual bool send_parameters(List<Item_param> *parameters,
373 bool is_sql_prepare) = 0;
374};
375
376#endif /* PROTOCOL_INCLUDED */
Definition: field.h:577
Dynamic parameters used as placeholders ('?') inside prepared statements.
Definition: item.h:4774
Definition: sql_list.h:467
Definition: protocol.h:33
bool store(uint32 from)
Definition: protocol.h:137
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:138
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:58
bool store_long(longlong from)
Definition: protocol.h:144
bool store(ulonglong from)
Definition: protocol.h:139
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:71
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:145
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:142
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:163
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:48
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:160
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:166
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:101
@ PROTOCOL_ERROR
Definition: protocol.h:106
@ PROTOCOL_PLUGIN
Definition: protocol.h:107
@ PROTOCOL_BINARY
Definition: protocol.h:104
@ PROTOCOL_LOCAL
Definition: protocol.h:105
@ PROTOCOL_TEXT
Definition: protocol.h:102
bool store_short(longlong from)
Definition: protocol.h:143
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:136
virtual bool store_tiny(longlong from, uint32 zerofill)=0
@ SEND_DEFAULTS
Definition: protocol.h:113
@ SEND_NUM_ROWS
Definition: protocol.h:113
@ SEND_EOF
Definition: protocol.h:113
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:4709
Using this class is fraught with peril, and you need to be very careful when doing so.
Definition: sql_string.h:167
my_decimal class limits 'decimal_t' type to what we need in MySQL.
Definition: my_decimal.h:95
Definition of COM_DATA to be used with the Command service as data input structure.
static int flags[50]
Definition: hp_test1.cc:40
enum_server_command
A list of all MySQL protocol commands.
Definition: my_command.h:48
unsigned long long int ulonglong
Definition: my_inttypes.h:56
long long int longlong
Definition: my_inttypes.h:55
uint32_t uint32
Definition: my_inttypes.h:67
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:1081
constexpr value_type zerofill
Definition: classic_protocol_constants.h:274
const std::string charset("charset")
Definition: commit_order_queue.h:34
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:76
Our own string classes, used pervasively throughout the executor.
Definition: m_ctype.h:421
Definition: mysql_lex_string.h:35
char * str
Definition: mysql_lex_string.h:36
size_t length
Definition: mysql_lex_string.h:37
Definition: mysql_time.h:82
Definition: com_data.h:104
Vio Lite.
enum_vio_type
Definition: violite.h:79