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, uint32_t *end_position, int file_index)¶ Get the name and size of a binlog file in bytes
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 end_position will hold the size of the binlog file and can be used to start reading from the end of the binlog file when passed todrizzle_binlog_start()
The filename parameter is allocated by the function and needs to be freed by the application when finished with. This is the case, regardless of the return status of the function.
Parameters: - con – Drizzle structure previously initialized with
drizzle_create()
- filename – Buffer to copy filename to
- end_position – Variable to save the size of the binlog file into
- file_index – Index of the binlog to retrieve.
Returns: Standard drizzle return value:
- DRIZZLE_RETURN_OK the filename was retrieved successfully.
- DRIZZLE_RETURN_INVALID_ARGUMENT: invalid argument(s)
- DRIZZLE_RETURN_NOT_FOUND: no binlog files were available
- con – Drizzle structure previously initialized with