MySQL  8.0.16
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, 2018, 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/mysql_lex_string.h" // LEX_STRING
28 #include "mysql_com.h" // mysql_enum_shutdown_level
29 #include "mysql_time.h" // MYSQL_TIME
30 #include "sql_string.h" // String
31 #include "violite.h" /* SSL && enum_vio_type */
32 #ifdef HAVE_OPENSSL
33 #define SSL_handle SSL *
34 #else
35 #define SSL_handle void *
36 #endif
37 
38 #ifdef __cplusplus
39 class THD;
40 #define MYSQL_THD THD *
41 #else
42 #define MYSQL_THD void *
43 #endif
44 
45 #include "mysql/com_data.h"
46 
47 class my_decimal;
48 class Send_field;
49 class Proto_field;
50 class Item_param;
51 template <class T>
52 class List;
53 
54 class Protocol {
55  private:
56  /// Pointer to the Protocol below on the stack.
58 
59  public:
60  virtual ~Protocol() {}
61 
62  /**
63  Remove the reference to the previous protocol and return it.
64 
65  @returns The new top of the Protocol stack.
66  */
70  m_previous_protocol = nullptr;
71  return protocol;
72  }
73 
74  /**
75  Set reference to "this" as the previous protocol on the protocol provided
76  as argument.
77 
78  @param protocol Protocol to become the top of Protocol stack.
79  */
81  DBUG_ASSERT(!protocol->m_previous_protocol);
82  protocol->m_previous_protocol = this;
83  }
84 
85  /**
86  Read packet from client
87 
88  @returns
89  -1 fatal error
90  0 ok
91  1 non-fatal error
92  */
93  virtual int read_packet() = 0;
94 
95  /**
96  Reads the command from the protocol and creates a command.
97 
98  @param com_data out parameter
99  @param cmd out parameter
100 
101  @returns
102  -1 fatal protcol error
103  0 ok
104  1 non-fatal protocol or parsing error
105  */
106  virtual int get_command(COM_DATA *com_data, enum_server_command *cmd) = 0;
107 
108  /**
109  Enum used by type() to specify the protocol type
110  */
112  PROTOCOL_TEXT = 0, // text Protocol type used mostly
113  // for the old (MySQL 4.0 protocol)
114  PROTOCOL_BINARY = 1, // binary protocol type
115  PROTOCOL_LOCAL = 2, // local protocol type(intercepts communication)
116  PROTOCOL_ERROR = 3, // error protocol instance
117  PROTOCOL_PLUGIN = 4 // pluggable protocol type
118  };
119 
120  /**
121  Flags available to alter the way the messages are sent to the client
122  */
123  enum { SEND_NUM_ROWS = 1, SEND_DEFAULTS = 2, SEND_EOF = 4 };
124 
125  virtual enum enum_protocol_type type() const = 0;
126 
127  virtual enum enum_vio_type connection_type() const = 0;
128 
129  /* Data sending functions */
130  virtual bool store_null() = 0;
131  virtual bool store_tiny(longlong from) = 0;
132  virtual bool store_short(longlong from) = 0;
133  virtual bool store_long(longlong from) = 0;
134  virtual bool store_longlong(longlong from, bool unsigned_flag) = 0;
135  virtual bool store_decimal(const my_decimal *, uint, uint) = 0;
136  virtual bool store(const char *from, size_t length,
137  const CHARSET_INFO *fromcs) = 0;
138  virtual bool store(float from, uint32 decimals, String *buffer) = 0;
139  virtual bool store(double from, uint32 decimals, String *buffer) = 0;
140  virtual bool store(MYSQL_TIME *time, uint precision) = 0;
141  virtual bool store_date(MYSQL_TIME *time) = 0;
142  virtual bool store_time(MYSQL_TIME *time, uint precision) = 0;
143  virtual bool store(Proto_field *field) = 0;
144  // Convenience wrappers
145  inline bool store(int from) { return store_long((longlong)from); }
146  inline bool store(uint32 from) { return store_long((longlong)from); }
147  inline bool store(longlong from) { return store_longlong(from, 0); }
148  inline bool store(ulonglong from) {
149  return store_longlong((longlong)from, 1);
150  }
151  /**
152  Send \\0 end terminated string.
153 
154  @param from NullS or \\0 terminated string.
155  @param fromcs Character set of the from string.
156 
157  @note In most cases one should use store(from, length, cs) instead of
158  this function
159 
160  @returns
161  false ok
162  true error
163  */
164  inline bool store(const char *from, const CHARSET_INFO *fromcs) {
165  return from ? store(from, strlen(from), fromcs) : store_null();
166  }
167  inline bool store(String *str) {
168  return store((char *)str->ptr(), str->length(), str->charset());
169  }
170  inline bool store(const LEX_STRING &s, const CHARSET_INFO *cs) {
171  return store(s.str, s.length, cs);
172  }
173 
174  /**
175  Returns the client capabilities stored on the protocol.
176  The available capabilites are defined in mysql_com.h
177  */
178  virtual ulong get_client_capabilities() = 0;
179  /**
180  Checks if the client capabilities include the one
181  specified as parameter.
182 
183  @returns
184  true if it includes the specified capability
185  false otherwise
186  */
187  virtual bool has_client_capability(unsigned long client_capability) = 0;
188 
189  /**
190  Checks if the protocol's connection with the client is still alive.
191  It should always return true unless the protocol closed the connection.
192 
193  @returns
194  true if the connection is still alive
195  false otherwise
196  */
197  virtual bool connection_alive() const = 0;
198 
199  /**
200  Result set sending functions
201 
202  @details Server uses following schema to send result:
203  ... sending metadata ...
204  | start_result_metadata(...)
205  | start_row()
206  | send_field_metadata(...)
207  | end_row()
208  ... same for each field sent ...
209  | end_result_metadata(...)
210  |
211  ... sending result ...
212  | start_row(...)
213  | store_xxx(...)
214  ... store_xxx(..) is called for each field ...
215  | end_row(...)
216  ... same for each row, until all rows are sent ...
217  | send_ok/eof/error(...)
218  However, a protocol implementation might use different schema. For
219  example, Protocol_callback ignores start/end_row when metadata is being
220  sent.
221  */
222 
223  virtual void start_row() = 0;
224  virtual bool end_row() = 0;
225  virtual void abort_row() = 0;
226  virtual void end_partial_result_set() = 0;
227 
228  /**
229  Thread is being shut down, disconnect and free resources
230 
231  @param server_shutdown If false then this is normal thread shutdown. If
232  true then the server is shutting down.
233  */
234  virtual int shutdown(bool server_shutdown = false) = 0;
235  /**
236  Returns the read/writing status
237 
238  @return
239  @retval 1 Read
240  @retval 2 Write
241  @retval 0 Other(Idle, Killed)
242  */
243  virtual uint get_rw_status() = 0;
244  /**
245  Returns if the protocol is compressed or not.
246 
247  @return
248  @retval false Not compressed
249  @retval true Compressed
250  */
251  virtual bool get_compression() = 0;
252  /**
253  Prepares the server for metadata sending.
254  Notifies the client that the metadata sending will start.
255 
256  @param num_cols Number of columns that will be sent
257  @param flags Flags to alter the metadata sending
258  Can be any of the following:
259  SEND_NUM_ROWS, SEND_DEFAULTS, SEND_EOF
260  @param resultcs Charset to convert to
261 
262  @return
263  @retval false Ok
264  @retval true An error occurred
265  */
266 
267  virtual bool start_result_metadata(uint num_cols, uint flags,
268  const CHARSET_INFO *resultcs) = 0;
269  /**
270  Sends field metadata.
271 
272  @param field Field metadata to be send to the client
273  @param charset Field's charset: in case it is different
274  than the one used by the connection it will
275  be used to convert the value to
276  the connection's charset
277 
278  @return
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  @return
290  @retval false Ok
291  @retval true An error occurred
292  */
293  virtual bool end_result_metadata() = 0;
294 
295  /**
296  Send ok message to the client.
297 
298  @param server_status The server status
299  @param statement_warn_count Total number of warnings
300  @param affected_rows Number of rows changed by statement
301  @param last_insert_id Last insert id (Auto_increment id for first
302  row if used)
303  @param message Message to send to the client
304 
305  @return
306  @retval false The message was successfully sent
307  @retval true An error occurred and the messages wasn't sent properly
308  */
309  virtual bool send_ok(uint server_status, uint statement_warn_count,
310  ulonglong affected_rows, ulonglong last_insert_id,
311  const char *message) = 0;
312  /**
313  Send eof message to the client.
314 
315  @param server_status The server status
316  @param statement_warn_count Total number of warnings
317 
318  @return
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  @return
331  @retval false The message was successfully sent
332  @retval true An error occurred and the messages wasn't sent properly
333  */
334 
335  virtual bool send_error(uint sql_errno, const char *err_msg,
336  const char *sql_state) = 0;
337 
338  /**
339  Used for the classic protocol.
340  Makes the protocol send the messages/data to the client.
341 
342  @return
343  @retval false The flush was successful.
344  @retval true An error occurred.
345  */
346  virtual bool flush() = 0;
347 
348  /**
349  Sends prepared statement's id and metadata to the client after prepare.
350 
351  @param stmt_id Statement id.
352  @param column_count Number of columns.
353  @param param_count Number of parameters.
354  @param cond_count Number of conditions raised by the current statement.
355 
356  @return Error status.
357  @retval false The send was successful.
358  @retval true An error occurred.
359  */
360  virtual bool store_ps_status(ulong stmt_id, uint column_count,
361  uint param_count, ulong cond_count) = 0;
362 
363  /**
364  Sends the OUT-parameters to the client.
365 
366  @param parameters List of PS/SP parameters (both input and output).
367  @param is_sql_prepare Used for the legacy protocol. If we're dealing with
368  sql prepare then text protocol wil be used.
369 
370  @return Error status.
371  @retval false Success.
372  @retval true Error.
373  */
374  virtual bool send_parameters(List<Item_param> *parameters,
375  bool is_sql_prepare) = 0;
376 };
377 
378 #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.
virtual bool store_short(longlong from)=0
bool store(const char *from, const CHARSET_INFO *fromcs)
Send \0 end terminated string.
Definition: protocol.h:164
unsigned long long int ulonglong
Definition: my_inttypes.h:69
Definition: field.h:4576
enum_protocol_type
Enum used by type() to specify the protocol type.
Definition: protocol.h:111
char * str
Definition: mysql_lex_string.h:35
Our own string classes, used pervasively throughout the executor.
Definition: protocol.h:115
Definition: mysql_lex_string.h:34
Definition: protocol.h:117
bool store(int from)
Definition: protocol.h:145
virtual int shutdown(bool server_shutdown=false)=0
Thread is being shut down, disconnect and free resources.
char buffer[STRING_BUFFER]
Definition: test_sql_9_sessions.cc:57
virtual enum enum_protocol_type type() const =0
virtual bool store_tiny(longlong from)=0
virtual int read_packet()=0
Read packet from client.
virtual bool store_null()=0
virtual ~Protocol()
Definition: protocol.h:60
virtual bool flush()=0
Used for the classic protocol.
bool store(uint32 from)
Definition: protocol.h:146
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: protocol.h:123
Definition: com_data.h:106
protocol
Definition: memcached.h:112
Using this class is fraught with peril, and you need to be very careful when doing so...
Definition: sql_string.h:159
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
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:80
Definition: protocol.h:112
Placeholder (&#39;?&#39;) of prepared statement.
Definition: item.h:3594
#define DBUG_ASSERT(A)
Definition: my_dbug.h:128
bool store(longlong from)
Definition: protocol.h:147
Protocol * m_previous_protocol
Pointer to the Protocol below on the stack.
Definition: protocol.h:57
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:67
virtual bool store_date(MYSQL_TIME *time)=0
bool store(const LEX_STRING &s, const CHARSET_INFO *cs)
Definition: protocol.h:170
Definition: aggregate_check.h:523
my_decimal class limits &#39;decimal_t&#39; type to what we need in MySQL.
Definition: my_decimal.h:100
virtual bool start_result_metadata(uint num_cols, uint flags, const CHARSET_INFO *resultcs)=0
Prepares the server for metadata sending.
Definition: protocol.h:123
unsigned int uint
Definition: uca-dump.cc:29
virtual void end_partial_result_set()=0
long long int longlong
Definition: my_inttypes.h:70
enum_vio_type
Definition: violite.h:75
virtual bool send_parameters(List< Item_param > *parameters, bool is_sql_prepare)=0
Sends the OUT-parameters to the client.
Definition: m_ctype.h:358
enum_server_command
A list of all MySQL protocol commands.
Definition: my_command.h:47
size_t length
Definition: mysql_lex_string.h:36
Definition: field.h:698
virtual bool store_decimal(const my_decimal *, uint, uint)=0
Definition: protocol.h:116
Definition: mysql_time.h:64
virtual bool store(const char *from, size_t length, const CHARSET_INFO *fromcs)=0
virtual ulong get_client_capabilities()=0
Returns the client capabilities stored on the protocol.
Definition: protocol.h:34
bool store(String *str)
Definition: protocol.h:167
bool store(ulonglong from)
Definition: protocol.h:148
char sql_state[64]
Definition: test_sql_9_sessions.cc:299
Definition: protocol.h:123
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:232
virtual void abort_row()=0
Definition: protocol.h:114
virtual bool store_long(longlong from)=0
COM_DATA cmd
Definition: test_session_info.cc:93
const char * ptr() const
Definition: sql_string.h:240
static int flags[50]
Definition: hp_test1.cc:39
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)=0
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:46
t time
Definition: dbug_analyze.cc:149
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:233
virtual bool store_time(MYSQL_TIME *time, uint precision)=0
For each client connection we create a separate thread with THD serving as a thread/connection descri...
Definition: sql_class.h:776
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.