10.2 C API Binary Log Data Structures

C API functions for processing a replication event stream from a server require a connection handler (a MYSQL * pointer) and a pointer to a MYSQL_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 the MYSQL_RPL structure members. Connection handlers are described in Section 5.2, “C API Basic Data Structures”.

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

• Before calling mysql_binlog_open(), the caller must set the MYSQL_RPL members from file_name_length through flags. In addition, if flags has the MYSQL_RPL_GTID flag set, the caller must set the members from gtid_set_encoded_size through gtid_set_arg.

• After a successful mysql_binlog_fetch() call, the caller examines the size and buffer 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 with file_name; see the file_name description.

• file_name

  The name of the binary log file to read:

  • If file_name is NULL, the client library sets it to the empty string and sets file_name_length to 0.

  • If file_name is not NULL, file_name_length must either be the length of the name or 0. If file_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, set file_name to NULL or the empty string, and start_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 cause mysql_binlog_fetch() to skip heartbeat events.

  • MYSQL_RPL_GTID

    Set this flag to read GTID (global transaction ID) data. If set, you must initialize the MYSQL_RPL structure GTID-related members from gtid_set_encoded_size to gtid_set_arg before calling mysql_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 the mysqlbinlog.cc source file. For information about GTID-based replication, see Replication 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 for mysql_binlog_open() to call to fill the command packet GTID set, or NULL if there is no such function. The callback function, if used, should have this calling signature:

  void my_callback(MYSQL_RPL *rpl, unsigned char *packet_gtid_set);

• gtid_set_arg

  Either a pointer to GTID set data (if fix_gtid_set is NULL), or a pointer to a value to be made available for use within the callback function (if fix_gtid_set is not NULL). 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 successful mysql_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 successful mysql_binlog_fetch() call, a pointer to the binary log event contents.