10.2 C API Binary Log Data Structures (original) (raw)

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 inSection 5.2, “C API Basic Data Structures”.

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

• Before callingmysql_binlog_open(), the caller must set the MYSQL_RPL members fromfile_name_length throughflags. In addition, ifflags has theMYSQL_RPL_GTID flag set, the caller must set the members from gtid_set_encoded_size through gtid_set_arg.
• After a successfulmysql_binlog_fetch() call, the caller examines the size 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:
  • If file_name isNULL, the client library sets it to the empty string and sets file_name_length to 0.
  • If file_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 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 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 from gtid_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, 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 (iffix_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 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.