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:

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.

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 to drizzle_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