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, 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