1 /* Copyright (c) 2011, 2021, Oracle and/or its affiliates.
2
3 This program is free software; you can redistribute it and/or modify
4 it under the terms of the GNU General Public License, version 2.0,
5 as published by the Free Software Foundation.
6
7 This program is also distributed with certain software (including
8 but not limited to OpenSSL) that is licensed under separate terms,
9 as designated in a particular file or component or in included license
10 documentation. The authors of MySQL hereby grant you an additional
11 permission to link the program and your derivative works with the
12 separately licensed software that they have included with MySQL.
13
14 This program is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 GNU General Public License, version 2.0, for more details.
18
19 You should have received a copy of the GNU General Public License
20 along with this program; if not, write to the Free Software
21 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
22
23 /**
24 @addtogroup Replication
25 @{
26
27 @file binlog_event.h
28
29 @brief Contains the classes representing events occuring in the replication
30 stream. Each event is represented as a byte sequence with logical divisions
31 as event header, event specific data and event footer. The header and footer
32 are common to all the events and are represented as two different subclasses.
33 */
34
35 #ifndef BINLOG_EVENT_INCLUDED
36 #define BINLOG_EVENT_INCLUDED
37
38 #include "debug_vars.h"
39 /*
40 The header contains functions macros for reading and storing in
41 machine independent format (low byte first).
42 */
43 #include "byteorder.h"
44 #include "wrapper_functions.h"
45 #include <zlib.h> //for checksum calculations
46 #include <cstdio>
47 #include <iostream>
48 #include <climits>
49
50 #if defined(_WIN32)
51 #include <Winsock2.h>
52 #else
53 #include <sys/times.h>
54 #endif
55 /*
56 The symbols below are a part of the common definitions between
57 the MySQL server and the client. Since they should not be a part of
58 this library but the server, these should be placed in a header file
59 common to the library and the MySQL server code, so that if they are
60 updated in the server code, it is reflected in the libbinlogevent also.
61
62 TODO(WL#7984): Moving the binlog constant in library libbinlogevents into a
63 separate file and make them const variables
64 */
65 #ifndef SYSTEM_CHARSET_MBMAXLEN
66 #define SYSTEM_CHARSET_MBMAXLEN 3
67 #endif
68 #ifndef NAME_CHAR_LEN
69 #define NAME_CHAR_LEN 64 /* Field/table name length */
70 #endif
71 #ifndef NAME_LEN
72 #define NAME_LEN (NAME_CHAR_LEN*SYSTEM_CHARSET_MBMAXLEN)
73 #endif
74 /* Length of the server_version_split array in FDE class */
75 #ifndef ST_SERVER_VER_SPLIT_LEN
76 #define ST_SERVER_VER_SPLIT_LEN 3
77 #endif
78
79 /*
80 Do not decrease the value of BIN_LOG_HEADER_SIZE.
81 Do not even increase it before checking code.
82 */
83 #ifndef BIN_LOG_HEADER_SIZE
84 #define BIN_LOG_HEADER_SIZE 4U
85 #endif
86
87 /**
88 binlog_version 3 is MySQL 4.x; 4 is MySQL 5.0.0.
89 Compared to version 3, version 4 has:
90 - a different Start_event, which includes info about the binary log
91 (sizes of headers); this info is included for better compatibility if the
92 master's MySQL version is different from the slave's.
93 */
94 #define BINLOG_VERSION 4
95
96 /*
97 Constants used by Query_event.
98 */
99
100 /**
101 The maximum number of updated databases that a status of
102 Query-log-event can carry. It can be redefined within a range
103 [1.. OVER_MAX_DBS_IN_EVENT_MTS].
104 */
105 #define MAX_DBS_IN_EVENT_MTS 16
106
107 /**
108 When the actual number of databases exceeds MAX_DBS_IN_EVENT_MTS
109 the value of OVER_MAX_DBS_IN_EVENT_MTS is is put into the
110 mts_accessed_dbs status.
111 */
112 #define OVER_MAX_DBS_IN_EVENT_MTS 254
113
114 /**
115 Max number of possible extra bytes in a replication event compared to a
116 packet (i.e. a query) sent from client to master;
117 First, an auxiliary log_event status vars estimation:
118 */
119 #define MAX_SIZE_LOG_EVENT_STATUS (1U + 4 /* type, flags2 */ + \
120 1U + 8 /* type, sql_mode */ + \
121 1U + 1 + 255 /* type, length, catalog */ + \
122 1U + 4 /* type, auto_increment */ + \
123 1U + 6 /* type, charset */ + \
124 1U + 1 + 255 /* type, length, time_zone */ + \
125 1U + 2 /* type, lc_time_names_number */ + \
126 1U + 2 /* type, charset_database_number */ + \
127 1U + 8 /* type, table_map_for_update */ + \
128 1U + 4 /* type, master_data_written */ + \
129 /* type, db_1, db_2, ... */ \
130 1U + (MAX_DBS_IN_EVENT_MTS * (1 + NAME_LEN)) + \
131 3U + /* type, microseconds */ + \
132 1U + 32*3 + 1 + 60 \
133 /* type, user_len, user, host_len, host */)
134
135
136 /**
137 Uninitialized timestamp value (for either last committed or sequence number).
138 Often carries meaning of the minimum value in the logical timestamp domain.
139 */
140 const int64_t SEQ_UNINIT= 0;
141
142 /** Setting this flag will mark an event as Ignorable */
143 #define LOG_EVENT_IGNORABLE_F 0x80
144
145 /**
146 In case the variable is updated,
147 make sure to update it in $MYSQL_SOURCE_DIR/my_global.h.
148 */
149 #ifndef FN_REFLEN
150 #define FN_REFLEN 512 /* Max length of full path-name */
151 #endif
152
153 /* The number of event types need to be permuted. */
154 static const unsigned int EVENT_TYPE_PERMUTATION_NUM= 23;
155
156 /**
157 Splits server 'version' string into three numeric pieces stored
158 into 'split_versions':
159 X.Y.Zabc (X,Y,Z numbers, a not a digit) -> {X,Y,Z}
160 X.Yabc -> {X,Y,0}
161
162 @param version String representing server version
163 @param split_versions Array with each element containing one split of the
164 input version string
165 */
do_server_version_split(const char * version,unsigned char split_versions[3])166 inline void do_server_version_split(const char *version,
167 unsigned char split_versions[3])
168 {
169 const char *p= version;
170 char *r;
171 unsigned long number;
172 for (unsigned int i= 0; i<=2; i++)
173 {
174 number= strtoul(p, &r, 10);
175 /*
176 It is an invalid version if any version number greater than 255 or
177 first number is not followed by '.'.
178 */
179 if (number < 256 && (*r == '.' || i != 0))
180 split_versions[i]= static_cast<unsigned char>(number);
181 else
182 {
183 split_versions[0]= 0;
184 split_versions[1]= 0;
185 split_versions[2]= 0;
186 break;
187 }
188
189 p= r;
190 if (*r == '.')
191 p++; // skip the dot
192 }
193 }
194
195 /**
196 Calculate the version product from the numeric pieces representing the server
197 version:
198 For a server version X.Y.Zabc (X,Y,Z numbers, a not a digit), the input is
199 {X,Y,Z}. This is converted to XYZ in bit representation.
200
201 @param version_split Array containing the version information of the server
202 @return The version product of the server
203 */
version_product(const unsigned char * version_split)204 inline unsigned long version_product(const unsigned char* version_split)
205 {
206 return ((version_split[0] * 256 + version_split[1]) * 256
207 + version_split[2]);
208 }
209
210
211 /**
212 Replication event checksum is introduced in the following "checksum-home"
213 version. The checksum-aware servers extract FD's version to decide whether
214 the FD event carries checksum info.
215 */
216 extern const unsigned char checksum_version_split[3];
217 extern const unsigned long checksum_version_product;
218 /**
219 @namespace binary_log
220
221 The namespace contains classes representing events that can occur in a
222 replication stream.
223 */
224 namespace binary_log
225 {
226 /*
227 This flag only makes sense for Format_description_event. It is set
228 when the event is written, and *reset* when a binlog file is
229 closed (yes, it's the only case when MySQL modifies an already written
230 part of the binlog). Thus it is a reliable indicator that the binlog was
231 closed correctly. (Stop_event is not enough, there's always a
232 small chance that mysqld crashes in the middle of insert and end of
233 the binlog would look like a Stop_event).
234
235 This flag is used to detect a restart after a crash, and to provide
236 "unbreakable" binlog. The problem is that on a crash storage engines
237 rollback automatically, while binlog does not. To solve this we use this
238 flag and automatically append ROLLBACK to every non-closed binlog (append
239 virtually, on reading, file itself is not changed). If this flag is found,
240 mysqlbinlog simply prints "ROLLBACK". Replication master does not abort on
241 binlog corruption, but takes it as EOF, and replication slave forces a
242 rollback in this case.
243
244 Note, that old binlogs does not have this flag set, so we get a
245 a backward-compatible behaviour.
246 */
247 #define LOG_EVENT_BINLOG_IN_USE_F 0x1
248
249 /**
250 Enumeration type for the different types of log events.
251 */
252 enum Log_event_type
253 {
254 /**
255 Every time you update this enum (when you add a type), you have to
256 fix Format_description_event::Format_description_event().
257 */
258 UNKNOWN_EVENT= 0,
259 START_EVENT_V3= 1,
260 QUERY_EVENT= 2,
261 STOP_EVENT= 3,
262 ROTATE_EVENT= 4,
263 INTVAR_EVENT= 5,
264 LOAD_EVENT= 6,
265 SLAVE_EVENT= 7,
266 CREATE_FILE_EVENT= 8,
267 APPEND_BLOCK_EVENT= 9,
268 EXEC_LOAD_EVENT= 10,
269 DELETE_FILE_EVENT= 11,
270 /**
271 NEW_LOAD_EVENT is like LOAD_EVENT except that it has a longer
272 sql_ex, allowing multibyte TERMINATED BY etc; both types share the
273 same class (Load_event)
274 */
275 NEW_LOAD_EVENT= 12,
276 RAND_EVENT= 13,
277 USER_VAR_EVENT= 14,
278 FORMAT_DESCRIPTION_EVENT= 15,
279 XID_EVENT= 16,
280 BEGIN_LOAD_QUERY_EVENT= 17,
281 EXECUTE_LOAD_QUERY_EVENT= 18,
282
283 TABLE_MAP_EVENT = 19,
284
285 /**
286 The PRE_GA event numbers were used for 5.1.0 to 5.1.15 and are
287 therefore obsolete.
288 */
289 PRE_GA_WRITE_ROWS_EVENT = 20,
290 PRE_GA_UPDATE_ROWS_EVENT = 21,
291 PRE_GA_DELETE_ROWS_EVENT = 22,
292
293 /**
294 The V1 event numbers are used from 5.1.16 until mysql-trunk-xx
295 */
296 WRITE_ROWS_EVENT_V1 = 23,
297 UPDATE_ROWS_EVENT_V1 = 24,
298 DELETE_ROWS_EVENT_V1 = 25,
299
300 /**
301 Something out of the ordinary happened on the master
302 */
303 INCIDENT_EVENT= 26,
304
305 /**
306 Heartbeat event to be send by master at its idle time
307 to ensure master's online status to slave
308 */
309 HEARTBEAT_LOG_EVENT= 27,
310
311 /**
312 In some situations, it is necessary to send over ignorable
313 data to the slave: data that a slave can handle in case there
314 is code for handling it, but which can be ignored if it is not
315 recognized.
316 */
317 IGNORABLE_LOG_EVENT= 28,
318 ROWS_QUERY_LOG_EVENT= 29,
319
320 /** Version 2 of the Row events */
321 WRITE_ROWS_EVENT = 30,
322 UPDATE_ROWS_EVENT = 31,
323 DELETE_ROWS_EVENT = 32,
324
325 GTID_LOG_EVENT= 33,
326 ANONYMOUS_GTID_LOG_EVENT= 34,
327
328 PREVIOUS_GTIDS_LOG_EVENT= 35,
329
330 TRANSACTION_CONTEXT_EVENT= 36,
331
332 VIEW_CHANGE_EVENT= 37,
333
334 /* Prepared XA transaction terminal event similar to Xid */
335 XA_PREPARE_LOG_EVENT= 38,
336
337 /* New MySQL events are to be added right above this comment */
338 MYSQL_END_EVENT,
339
340 /* Add new Percona Server events here - its ids should go downwards
341 * starting from MARIA_EVENTS_BEGIN, i.e. 159, 158 ..
342 * till MYSQL_END_EVENT */
343
344 START_ENCRYPTION_EVENT= 159,
345
346 MARIA_EVENTS_BEGIN= 160,
347
348 ENUM_END_EVENT /* end marker */
349 };
350
351 /**
352 The length of the array server_version, which is used to store the version
353 of MySQL server.
354 We could have used SERVER_VERSION_LENGTH, but this introduces an
355 obscure dependency - if somebody decided to change SERVER_VERSION_LENGTH
356 this would break the replication protocol
357 both of these are used to initialize the array server_version
358 SERVER_VERSION_LENGTH is used for global array server_version
359 and ST_SERVER_VER_LEN for the Start_event_v3 member server_version
360 */
361
362 #define ST_SERVER_VER_LEN 50
363
364 /*
365 Event header offsets;
366 these point to places inside the fixed header.
367 */
368 #define EVENT_TYPE_OFFSET 4
369 #define SERVER_ID_OFFSET 5
370 #define EVENT_LEN_OFFSET 9
371 #define LOG_POS_OFFSET 13
372 #define FLAGS_OFFSET 17
373
374 /** start event post-header (for v3 and v4) */
375 #define ST_BINLOG_VER_OFFSET 0
376 #define ST_SERVER_VER_OFFSET 2
377 #define ST_CREATED_OFFSET (ST_SERVER_VER_OFFSET + ST_SERVER_VER_LEN)
378 #define ST_COMMON_HEADER_LEN_OFFSET (ST_CREATED_OFFSET + 4)
379
380 #define LOG_EVENT_HEADER_LEN 19U /* the fixed header length */
381 #define OLD_HEADER_LEN 13U /* the fixed header length in 3.23 */
382
383 /**
384 Fixed header length, where 4.x and 5.0 agree. That is, 5.0 may have a longer
385 header (it will for sure when we have the unique event's ID), but at least
386 the first 19 bytes are the same in 4.x and 5.0. So when we have the unique
387 event's ID, LOG_EVENT_HEADER_LEN will be something like 26, but
388 LOG_EVENT_MINIMAL_HEADER_LEN will remain 19.
389 */
390 #define LOG_EVENT_MINIMAL_HEADER_LEN 19U
391
392
393 /**
394 Enumeration spcifying checksum algorithm used to encode a binary log event
395 */
396 enum enum_binlog_checksum_alg
397 {
398 /**
399 Events are without checksum though its generator is checksum-capable
400 New Master (NM).
401 */
402 BINLOG_CHECKSUM_ALG_OFF= 0,
403 /** CRC32 of zlib algorithm */
404 BINLOG_CHECKSUM_ALG_CRC32= 1,
405 /** the cut line: valid alg range is [1, 0x7f] */
406 BINLOG_CHECKSUM_ALG_ENUM_END,
407 /**
408 Special value to tag undetermined yet checksum or events from
409 checksum-unaware servers
410 */
411 BINLOG_CHECKSUM_ALG_UNDEF= 255
412 };
413
414 #define CHECKSUM_CRC32_SIGNATURE_LEN 4
415
416 /**
417 defined statically while there is just one alg implemented
418 */
419 #define BINLOG_CHECKSUM_LEN CHECKSUM_CRC32_SIGNATURE_LEN
420 #define BINLOG_CHECKSUM_ALG_DESC_LEN 1 /* 1 byte checksum alg descriptor */
421 #define LOG_EVENT_HEADER_SIZE 20
422
423 /**
424 Calculate a long checksum for a memoryblock.
425
426 @param crc start value for crc
427 @param pos pointer to memory block
428 @param length length of the block
429
430 @return checksum for a memory block
431 */
checksum_crc32(uint32_t crc,const unsigned char * pos,size_t length)432 inline uint32_t checksum_crc32(uint32_t crc, const unsigned char *pos,
433 size_t length)
434 {
435 BAPI_ASSERT(length <= UINT_MAX);
436 return static_cast<uint32_t>(crc32(static_cast<unsigned int>(crc), pos,
437 static_cast<unsigned int>(length)));
438 }
439
440
441 /*
442 Reads string from buf.
443
444 Reads str from buf in the following format:
445 1. Read length stored on buf first index, as it only has 1 byte values
446 bigger than 255 where lost.
447 2. Set str pointer to buf second index.
448 Despite str contains the complete stored string, when it is read until
449 len its value will be truncated if original length was bigger than 255.
450
451 @param buf source pointer
452 @param buf_end
453 @param str destination pointer
454 @param len length to which the buffer should be read
455
456 @retval 1 error
457 @retval 0 success
458 */
read_str_at_most_255_bytes(const char ** buf,const char * buf_end,const char ** str,uint8_t * len)459 inline int read_str_at_most_255_bytes(const char **buf, const char *buf_end,
460 const char **str, uint8_t *len)
461 {
462 if (*buf + *buf[0] >= buf_end)
463 return 1;
464 *len= *buf[0];
465 *str= (*buf) + 1;
466 (*buf)+= *len + 1;
467 return 0;
468 }
469
470 /*
471 Forward declaration of Format_description_event class to be used in class
472 Log_event_header
473 */
474 class Format_description_event;
475
476 /**
477 @class Log_event_footer
478
479 The footer, in the current version of the MySQL server, only contains
480 the checksum algorithm descriptor. The descriptor is contained in the
481 FDE of the binary log. This is common for all the events contained in
482 that binary log, and defines the algorithm used to checksum
483 the events contained in the binary log.
484
485 @anchor Table_common_footer
486 The footer contains the following:
487 <table>
488 <caption>Common-Footer</caption>
489
490 <tr>
491 <th>Name</th>
492 <th>Format</th>
493 <th>Description</th>
494 </tr>
495
496 <tr>
497 <td>checkusm_alg</td>
498 <td>enum_checksum_alg</td>
499 <td>Algorithm used to checksum the events contained in the binary log</td>
500 </table>
501
502 @note checksum *value* is not stored in the event. On master's side, it
503 is calculated before writing into the binary log, depending on the
504 updated event data. On the slave, the checksum value is retrieved
505 from a particular offset and checked for corruption, by computing
506 a new value. It is not required after that. Therefore, it is not
507 required to store the value in the instance as a class member.
508 */
509 class Log_event_footer
510 {
511 public:
512
513 static enum_binlog_checksum_alg get_checksum_alg(const char* buf,
514 unsigned long len);
515
516 static bool event_checksum_test(unsigned char* buf,
517 unsigned long event_len,
518 enum_binlog_checksum_alg alg);
519
520 /* Constructors */
Log_event_footer()521 Log_event_footer()
522 : checksum_alg(BINLOG_CHECKSUM_ALG_UNDEF)
523 {}
524
Log_event_footer(enum_binlog_checksum_alg checksum_alg_arg)525 explicit Log_event_footer(enum_binlog_checksum_alg checksum_alg_arg)
526 : checksum_alg(checksum_alg_arg)
527 {}
528
529 /**
530 @verbatim
531 Master side:
532 The value is set by caller of FD(Format Description) constructor
533 In the FD case it's propagated into the last byte
534 of post_header_len[].
535 Slave side:
536 On the slave side the value is assigned from post_header_len[last]
537 of the last seen FD event.
538 @endverbatim
539 TODO(WL#7546): Revisit this comment when encoder is moved in libbinlogevent
540 */
541 enum_binlog_checksum_alg checksum_alg;
542 };
543
544 /**
545 @class Log_event_header
546
547 The Common-Header always has the same form and length within one
548 version of MySQL. Each event type specifies a format and length
549 of the Post-Header. The length of the Common-Header is the same
550 for all events of the same type.
551
552 @anchor Table_common_header
553 The binary format of Common-Header is as follows:
554 <table>
555 <caption>Common-Header</caption>
556
557 <tr>
558 <th>Name</th>
559 <th>Format</th>
560 <th>Description</th>
561 </tr>
562
563 <tr>
564 <td>when</td>
565 <td>4 byte unsigned integer, represented by type struct timeval</td>
566 <td>The time when the query started, in seconds since 1970.
567 </td>
568 </tr>
569
570 <tr>
571 <td>type_code</td>
572 <td>1 byte enumeration</td>
573 <td>See enum #Log_event_type.</td>
574 </tr>
575
576 <tr>
577 <td>unmasked_server_id</td>
578 <td>4 byte unsigned integer</td>
579 <td>Server ID of the server that created the event.</td>
580 </tr>
581
582 <tr>
583 <td>data_written</td>
584 <td>4 byte unsigned integer</td>
585 <td>The total size of this event, in bytes. In other words, this
586 is the sum of the sizes of Common-Header, Post-Header, and Body.
587 </td>
588 </tr>
589
590 <tr>
591 <td>log_pos</td>
592 <td>4 byte unsigned integer</td>
593 <td>The position of the next event in the master binary log, in
594 bytes from the beginning of the file. In a binlog that is not a
595 relay log, this is just the position of the next event, in bytes
596 from the beginning of the file. In a relay log, this is
597 the position of the next event in the master's binlog.
598 </td>
599 </tr>
600
601 <tr>
602 <td>flags</td>
603 <td>2 byte bitfield</td>
604 <td>16 or less flags depending on the version of the binary log.</td>
605 </tr>
606 </table>
607
608 Summing up the numbers above, we see that the total size of the
609 common header is 19 bytes.
610 */
611 class Log_event_header
612 {
613 public:
614 /*
615 Timestamp on the master(for debugging and replication of
616 NOW()/TIMESTAMP). It is important for queries and LOAD DATA
617 INFILE. This is set at the event's creation time, except for Query
618 and Load (and other events) events where this is set at the query's
619 execution time, which guarantees good replication (otherwise, we
620 could have a query and its event with different timestamps).
621 */
622 struct timeval when;
623
624 /**
625 Event type extracted from the header. In the server, it is decoded
626 by read_log_event(), but adding here for complete decoding.
627 */
628 Log_event_type type_code;
629
630 /*
631 The server id read from the Binlog.
632 */
633 unsigned int unmasked_server_id;
634
635 /* Length of an event, which will be written by write() function */
636 size_t data_written;
637
638 /*
639 The offset in the log where this event originally appeared (it is
640 preserved in relay logs, making SHOW SLAVE STATUS able to print
641 coordinates of the event in the master's binlog). Note: when a
642 transaction is written by the master to its binlog (wrapped in
643 BEGIN/COMMIT) the log_pos of all the queries it contains is the
644 one of the BEGIN (this way, when one does SHOW SLAVE STATUS it
645 sees the offset of the BEGIN, which is logical as rollback may
646 occur), except the COMMIT query which has its real offset.
647 */
648 unsigned long long log_pos;
649
650 /*
651 16 or less flags depending on the version of the binary log.
652 See the definitions above for LOG_EVENT_TIME_F,
653 LOG_EVENT_FORCED_ROTATE_F, LOG_EVENT_THREAD_SPECIFIC_F, and
654 LOG_EVENT_SUPPRESS_USE_F for notes.
655 */
656 uint16_t flags;
657
658 /**
659 The following type definition is to be used whenever data is placed
660 and manipulated in a common buffer. Use this typedef for buffers
661 that contain data containing binary and character data.
662 */
663 typedef unsigned char Byte;
664
665 explicit Log_event_header(Log_event_type type_code_arg= ENUM_END_EVENT)
type_code(type_code_arg)666 : type_code(type_code_arg),
667 data_written(0),
668 log_pos(0),
669 flags(0)
670 {
671 when.tv_sec= 0;
672 when.tv_usec= 0;
673 }
674 /**
675 Log_event_header constructor
676
677 @param buf the buffer containing the complete information
678 including the event and the header data
679
680 @param description_event first constructor of Format_description_event,
681 used to extract the binlog_version
682 */
683 Log_event_header(const char* buf, uint16_t binlog_version);
684
~Log_event_header()685 ~Log_event_header() {}
686 };
687
688 /**
689 This is the abstract base class for binary log events.
690
691 @section Binary_log_event_binary_format Binary Format
692
693 @anchor Binary_log_event_format
694 Any @c Binary_log_event saved on disk consists of the following four
695 components.
696
697 - Common-Header
698 - Post-Header
699 - Body
700 - Footer
701
702 Common header has the same format and length in a given MySQL version. It is
703 documented @ref Table_common_header "here".
704
705 The Body may be of different format and length even for different events of
706 the same type. The binary formats of Post-Header and Body are documented
707 separately in each subclass.
708
709 Footer is common to all the events in a given MySQL version. It is documented
710 @ref Table_common_footer "here".
711
712 @anchor packed_integer
713 - Some events, used for RBR use a special format for efficient representation
714 of unsigned integers, called Packed Integer. A Packed Integer has the
715 capacity of storing up to 8-byte integers, while small integers
716 still can use 1, 3, or 4 bytes. The value of the first byte
717 determines how to read the number, according to the following table:
718
719 <table>
720 <caption>Format of Packed Integer</caption>
721
722 <tr>
723 <th>First byte</th>
724 <th>Format</th>
725 </tr>
726
727 <tr>
728 <td>0-250</td>
729 <td>The first byte is the number (in the range 0-250), and no more
730 bytes are used.</td>
731 </tr>
732
733 <tr>
734 <td>252</td>
735 <td>Two more bytes are used. The number is in the range
736 251-0xffff.</td>
737 </tr>
738
739 <tr>
740 <td>253</td>
741 <td>Three more bytes are used. The number is in the range
742 0xffff-0xffffff.</td>
743 </tr>
744
745 <tr>
746 <td>254</td>
747 <td>Eight more bytes are used. The number is in the range
748 0xffffff-0xffffffffffffffff.</td>
749 </tr>
750
751 </table>
752
753 - Strings are stored in various formats. The format of each string
754 is documented separately.
755
756 */
757 class Binary_log_event
758 {
759 public:
760
761 /*
762 The number of types we handle in Format_description_event (UNKNOWN_EVENT
763 is not to be handled, it does not exist in binlogs, it does not have a
764 format - unless it's START_ENCRYPTION_EVENT - then Format_description_event
765 is not aware of it. That's OK as this event never leaves the server -
766 it's not sent to slave).
767 */
768 static const int LOG_EVENT_TYPES= (MYSQL_END_EVENT - 1);
769
770 /**
771 The lengths for the fixed data part of each event.
772 This is an enum that provides post-header lengths for all events.
773 */
774 enum enum_post_header_length{
775 // where 3.23, 4.x and 5.0 agree
776 QUERY_HEADER_MINIMAL_LEN= (4 + 4 + 1 + 2),
777 // where 5.0 differs: 2 for length of N-bytes vars.
778 QUERY_HEADER_LEN=(QUERY_HEADER_MINIMAL_LEN + 2),
779 STOP_HEADER_LEN= 0,
780 LOAD_HEADER_LEN= (4 + 4 + 4 + 1 +1 + 4),
781 START_V3_HEADER_LEN= (2 + ST_SERVER_VER_LEN + 4),
782 // this is FROZEN (the Rotate post-header is frozen)
783 ROTATE_HEADER_LEN= 8,
784 INTVAR_HEADER_LEN= 0,
785 CREATE_FILE_HEADER_LEN= 4,
786 APPEND_BLOCK_HEADER_LEN= 4,
787 EXEC_LOAD_HEADER_LEN= 4,
788 DELETE_FILE_HEADER_LEN= 4,
789 NEW_LOAD_HEADER_LEN= LOAD_HEADER_LEN,
790 RAND_HEADER_LEN= 0,
791 USER_VAR_HEADER_LEN= 0,
792 FORMAT_DESCRIPTION_HEADER_LEN= (START_V3_HEADER_LEN + 1 + LOG_EVENT_TYPES),
793 XID_HEADER_LEN= 0,
794 BEGIN_LOAD_QUERY_HEADER_LEN= APPEND_BLOCK_HEADER_LEN,
795 ROWS_HEADER_LEN_V1= 8,
796 TABLE_MAP_HEADER_LEN= 8,
797 EXECUTE_LOAD_QUERY_EXTRA_HEADER_LEN= (4 + 4 + 4 + 1),
798 EXECUTE_LOAD_QUERY_HEADER_LEN= (QUERY_HEADER_LEN +\
799 EXECUTE_LOAD_QUERY_EXTRA_HEADER_LEN),
800 INCIDENT_HEADER_LEN= 2,
801 HEARTBEAT_HEADER_LEN= 0,
802 IGNORABLE_HEADER_LEN= 0,
803 ROWS_HEADER_LEN_V2= 10,
804 TRANSACTION_CONTEXT_HEADER_LEN= 18,
805 VIEW_CHANGE_HEADER_LEN= 52,
806 XA_PREPARE_HEADER_LEN= 0,
807 START_ENCRYPTION_HEADER_LEN= 0
808 }; // end enum_post_header_length
809 protected:
810 /**
811 This constructor is used to initialize the type_code of header object
812 m_header.
813 We set the type code to ENUM_END_EVENT so that the decoder
814 asserts if event type has not been modified by the sub classes
815 */
Binary_log_event(Log_event_type type_code)816 explicit Binary_log_event(Log_event_type type_code)
817 : m_header(type_code)
818 {}
819
820 /**
821 This ctor will create a new object of Log_event_header, and initialize
822 the variable m_header, which in turn will be used to initialize Log_event's
823 member common_header.
824 It will also advance the buffer after decoding the header(it is done through
825 the constructor of Log_event_header) and
826 will be pointing to the start of event data
827
828 @param buf Contains the serialized event
829 @param binlog_version The binary log format version
830 @param server_version The MySQL server's version
831 */
832 Binary_log_event(const char **buf, uint16_t binlog_version,
833 const char *server_version);
834 public:
835 #ifndef HAVE_MYSYS
836 /*
837 The print_event_info functions are used in the free standing version of
838 the library only. Since MySQL server does not use them, and it does not
839 link to standard input/output library on Windows 32 bit system ,these
840 methods are commented out when the library(libbinlogevents) is built
841 with the server.
842 */
843 /**
844 Returns short information about the event
845 */
846 virtual void print_event_info(std::ostream& info)= 0;
847 /**
848 Returns detailed information about the event
849 */
850 virtual void print_long_info(std::ostream& info)= 0;
851 #endif
852 virtual ~Binary_log_event() = 0;
853
854 /**
855 * Helper method
856 */
get_event_type()857 enum Log_event_type get_event_type() const
858 {
859 return m_header.type_code;
860 }
861
862 /**
863 Return a const pointer to the header of the log event
864 */
header()865 const Log_event_header *header() const
866 {
867 return &m_header;
868 }
869 /**
870 Return a non-const pointer to the header of the log event
871 */
header()872 Log_event_header *header()
873 {
874 return &m_header;
875 }
876 /**
877 Return a const pointer to the footer of the log event
878 */
footer()879 const Log_event_footer *footer() const
880 {
881 return &m_footer;
882 }
883 /**
884 Return a non-const pointer to the footer of the log event
885 */
footer()886 Log_event_footer *footer()
887 {
888 return &m_footer;
889 }
890
891 private:
892 Log_event_header m_header;
893 Log_event_footer m_footer;
894 };
895
896 /**
897 @class Unknown_event
898
899 An unknown event should never occur. It is never written to a binary log.
900 If an event is read from a binary log that cannot be recognized as
901 something else, it is treated as UNKNOWN_EVENT.
902
903 The Post-Header and Body for this event type are empty; it only has
904 the Common-Header.
905 */
906 class Unknown_event: public Binary_log_event
907 {
908 public:
909 /**
910 This is the minimal constructor, and set the type_code as
911 UNKNOWN_EVENT in the header object in Binary_log_event
912 */
Unknown_event()913 Unknown_event()
914 : Binary_log_event(UNKNOWN_EVENT)
915 {}
916
917 Unknown_event(const char* buf,
918 const Format_description_event *description_event);
919 #ifndef HAVE_MYSYS
920 void print_event_info(std::ostream& info);
921 void print_long_info(std::ostream& info);
922 #endif
923 };
924 } // end namespace binary_log
925 /**
926 @} (end of group Replication)
927 */
928 #endif /* BINLOG_EVENT_INCLUDED */
929