MySQL 8.4 C API Developer Guide  / C API Binary Log Interface  /  C API Binary Log Data Structures

10.2 C API Binary Log Data Structures

C API functions for processing a replication event stream from a server require a connection handler (aMYSQL * pointer) and a pointer to aMYSQL_RPL structure that describes the steam of replication events to read from the server binary log. For example:

MYSQL *mysql = mysql_real_connect(...);MYSQL_RPL rpl;# ... initialize MYSQL_RPL members ...int result = mysql_binlog_open(mysql, &rpl);

This section describes theMYSQL_RPL structure members. Connection handlers are described inSection 5.2, “C API Basic Data Structures”.

The applicableMYSQL_RPL members depend on the binary log operation to be performed:

  • Before callingmysql_binlog_open(), the caller must set theMYSQL_RPL members fromfile_name_length throughflags. In addition, ifflags has theMYSQL_RPL_GTID flag set, the caller must set the members fromgtid_set_encoded_size throughgtid_set_arg.

  • After a successfulmysql_binlog_fetch() call, the caller examines thesize andbuffer members.

MYSQL_RPL structure member descriptions:

  • file_name_length

    The length of the name of the binary log file to read. This member is used in conjunction withfile_name; see thefile_name description.

  • file_name

    The name of the binary log file to read:

    • Iffile_name isNULL, the client library sets it to the empty string and setsfile_name_length to 0.

    • Iffile_name is notNULL,file_name_length must either be the length of the name or 0. Iffile_name_length is 0, the client library sets it to the length of the name, in which case,file_name must be given as a null-terminated string.

    To read from the beginning of the binary log without having to know the name of the oldest binary log file, setfile_name toNULL or the empty string, andstart_position to 4.

  • start_position

    The position at which to start reading the binary log. The position of the first event in any given binary log file is 4.

  • server_id

    The server ID to use for identifying to the server from which the binary log is read.

  • flags

    The union of flags that affect binary log reading, or 0 if no flags are set. These flag values are permitted:

    • MYSQL_RPL_SKIP_HEARTBEAT

      Set this flag to causemysql_binlog_fetch() to skip heartbeat events.

    • MYSQL_RPL_GTID

      Set this flag to read GTID (global transaction ID) data. If set, you must initialize theMYSQL_RPL structure GTID-related members fromgtid_set_encoded_size togtid_set_arg before callingmysql_binlog_open().

      It is beyond the scope of this documentation to describe in detail how client programs use those GTID-related members. For more information, examine themysqlbinlog.cc source file. For information about GTID-based replication, seeReplication with Global Transaction Identifiers.

  • gtid_set_encoded_size

    The size of GTID set data, or 0.

  • fix_gtid_set

    The address of a callback function formysql_binlog_open() to call to fill the command packet GTID set, orNULL if there is no such function. The callback function, if used, should have this calling signature:

    voidmy_callback(MYSQL_RPL *rpl, unsigned char *packet_gtid_set);

  • gtid_set_arg

    Either a pointer to GTID set data (iffix_gtid_set isNULL), or a pointer to a value to be made available for use within the callback function (iffix_gtid_set is notNULL).gtid_set_arg is a generic pointer, so it can point to any kind of value (for example, a string, a structure, or a function). Its interpretation within the callback depends on how the callback intends to use it.

  • size

    After a successfulmysql_binlog_fetch() call, the size of the returned binary log event. The value is 0 for an EOF event, greater than 0 for a non-EOF event.

  • buffer

    After a successfulmysql_binlog_fetch() call, a pointer to the binary log event contents.