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.