Binlog Functions¶
Introduction¶
Libdrizzle Redux contains functions which give it the capabilities to connect as a MySQL slave or a mysqlbinlog type client and retrieve the events.
Warning
You should start a binlog retrieval on a new connection only. Running on a connection that has already executed queries has an undefined (usually bad) behaviour.
The binlog functions use a callback API so that a function in the user application will be called whenever there is a new event to retrieve.
Structs¶
-
drizzle_binlog_st
¶ The internal struct containing the binlog stream information
-
drizzle_binlog_event_st
¶ The internal struct containing the binlog event header and data
Callback Functions¶
There are two callback functions. The first is called whenever a new event is available to retrieve. The second is triggered whenever an error (or EOF) occurs.
-
void
(drizzle_binlog_fn)
(drizzle_binlog_event_st *event, void *context)¶ This defines the function that will be supplied to accept binlog events
Warning
Event data needs to be copied/processed before exiting the function, it will be erased before the next callback.
Parameters: - event – A pointer to the event struct
- context – A user defined pointer supplied in
drizzle_binlog_init()
-
void
(drizzle_binlog_error_fn)
(drizzle_return_t error, drizzle_st *con, void *context)¶ This defines the function that will be supplied to accept binlog errors
Parameters: - error – The
drizzle_return_t
for the error (orDRIZZLE_RETURN_EOF
when all events have been retrieved - con – The connection object the error occurred on
- context – A user defined pointer supplied in
drizzle_binlog_init()
- error – The
Functions¶
-
drizzle_binlog_st *
drizzle_binlog_init
(drizzle_st *con, drizzle_binlog_fn *binlog_fn, drizzle_binlog_error_fn *error_fn, void *context, bool verify_checksums)¶ Initializes a binlog object for the connection and sets the event callback functions
Parameters: - con – The connection the binlog retrieval will be on
- binlog_fn – The function callback defined in
(drizzle_binlog_fn)()
- error_fn – The function callback defined in
(drizzle_binlog_error_fn)()
- context – A pointer to user data which will be used for the callback functions
- verify_checksums – Set to true if MySQL 5.6 and higher checksums should be verified
-
void
drizzle_binlog_free
(drizzle_binlog_st *binlog)¶ Frees a binlog object created with
drizzle_binlog_init()
Parameters: - binlog – The binlog object to be freed
-
drizzle_return_t
drizzle_binlog_start
(drizzle_binlog_st *binlog, uint32_t server_id, const char *file, uint32_t start_position)¶ Start the binlog transaction. Set the server_id to 0 to disconnect automatically at the end of the last log.
Parameters: - binlog – A binlog object created using
drizzle_binlog_init()
- server_id – A unique server ID (or 0) to connect to the MySQL server with
- file – The start binlog file, can be empty to start at the first known file
- start_position – The position of the binlog file to start at, a value of less than 4 is set to 4 due to the binlog header taking the first 4 bytes
Returns: A Drizzle return type.
DRIZZLE_RETURN_OK
upon success.- binlog – A binlog object created using
-
uint32_t
drizzle_binlog_event_timestamp
(drizzle_binlog_event_st *event)¶ Get the timestamp for the event received by the event callback
Parameters: - event – The event from the binlog stream
Returns: The timestamp for the binlog event
-
drizzle_binlog_event_types_t
drizzle_binlog_event_type
(drizzle_binlog_event_st *event)¶ Get the event type for the event received by the event callback
Parameters: - event – The event from the binlog stream
Returns: The timestamp for the binlog event
-
uint32_t
drizzle_binlog_event_server_id
(drizzle_binlog_event_st *event)¶ Get the server_id for the event received by the event callback
Parameters: - event – The event from the binlog stream
Returns: The server_id for the binlog event
-
uint32_t
drizzle_binlog_event_length
(drizzle_binlog_event_st *event)¶ Get the length of the event data received by the event callback
Parameters: - event – The event from binlog stream
Returns: The event data length
-
uint32_t
drizzle_binlog_event_next_pos
(drizzle_binlog_event_st *event)¶ Get the next event position from the event received by the event callback
Parameters: - event – The event from the binlog stream
Returns: The next event position
-
uint16_t
drizzle_binlog_event_flags
(drizzle_binlog_event_st *event)¶ Get the flags for the event received by the event callback
Parameters: - event – The event from the binlog stream
Returns: The event flags
-
uint16_t
drizzle_binlog_event_extra_flags
(drizzle_binlog_event_st *event)¶ Get the extra flags for the event received by the event callback
Parameters: - event – The event from the binlog stream
Returns: The extra event flags
-
const unsigned char*
drizzle_binlog_event_data
(drizzle_binlog_event_st *event)¶ Get the event data for the event received by the event callback
Parameters: - event – The event from the binlog stream
Returns: A pointer to the event data
-
const unsigned char*
drizzle_binlog_event_raw_data
(drizzle_binlog_event_st *event)¶ Get the raw event data (including header) for the event received by the event callback
Parameters: - event – The event from the binlog stream
Returns: A pointer to the raw event data
-
uint32_t
drizzle_binlog_event_raw_length
(drizzle_binlog_event_st *event)¶ Get the length of the raw event data (including header) for the event received by the event callback
Parameters: - event – The event from the binlog stream
Returns: The length of the raw event data
-
const char *
drizzle_binlog_event_type_str
(drizzle_binlog_event_types_t event_type)¶ Get the event type for the binlog event as string
Parameters: - event_type – A binlog event type
Returns: The event type of the binlog event as string
-
void
drizzle_binlog_get_filename
(drizzle_st *con, char *filename, int file_index)¶ Get the name of a binlog-file
Queries the database for a list of binlog files and copies the filename to the passed buffer If the file_index is invalid or no binlog files exist filename will contain an empty string A valid file_index is in the range [-1 to (number of binlog files -1)]
The memory (de)allocation of the filename buffer must be done by the client
Parameters: - con – Drizzle structure previously initialized with
drizzle_create()
- filename – Buffer to copy filename to
- file_index – Index of the binlog to retrieve
- con – Drizzle structure previously initialized with