Connection Functions

Introduction

This section outlines the connection functions

Structs

drizzle_st

The internal drizzle connection object struct

drizzle_options_st

The internal structure containing connection options

Functions

drizzle_st* drizzle_create(const char *host, in_port_t port, const char *user, const char *password, const char *db, drizzle_options_st *options)

Creates a connection connection object. If a path beginning with / is given as the host the library will connect as a UDS socket. Otherwise a TCP/IP connection is made.

Note

a connection does not happen until the first query or an explicit drizzle_connect() call is made

Parameters:
  • host – The socket path, hostname or IP of the server
  • port – The port number of the server (if TCP/IP)
  • user – The username of the server
  • password – The password of the server
  • db – The default DB to connect to on the server
  • options – A pointer to a drizzle_options_st created using drizzle_options_create() or NULL
Returns:

A newly allocated and setup connection object
int drizzle_fd(const drizzle_st *con)

Get file descriptor for connection.

Parameters:
Returns:

File descriptor of connection, or -1 if not active.
int drizzle_timeout(const drizzle_st *con)

Gets the current connection timeout set in the connection object

Parameters:
  • con – A connection object
Returns:

The current timeout
void drizzle_set_timeout(drizzle_st *con, int timeout)

Sets the connection timeout for the connection object

Parameters:
  • con – A connection object
  • timeout – The new timeout to set
drizzle_verbose_t drizzle_verbose(const drizzle_st *con)

Gets the verbosity level set in the connection object

Parameters:
  • con – A connection object
Returns:

The verbosity level from drizzle_verbose_t
void drizzle_set_verbose(drizzle_st *con, drizzle_verbose_t verbose)

Sets the verbosity level for the connection object

Parameters:
void drizzle_set_log_fn(drizzle_st *con, drizzle_log_fn *function, void *context)

Sets a callback function for log handling

Parameters:
  • con – A connection object
  • function – The function to use in the format of drizzle_log_fn()
  • context – A pointer to data to pass to the log function
void drizzle_set_event_watch_fn(drizzle_st *con, drizzle_event_watch_fn *function, void *context)

Set a custom I/O event watcher function for a drizzle structure

Parameters:
  • con – Drizzle structure previously initialized with drizzle_create().
  • function – Function to call when there is an I/O event, in the form of drizzle_event_watch_fn()
  • context – Argument to pass into the callback function.
drizzle_return_t drizzle_set_events(drizzle_st *con, short events)

Set events to be watched for a connection.

Parameters:
  • con – Connection structure previously initialized with drizzle_create().
  • events – Bitfield of poll() events to watch.
Returns:

Standard drizzle return value.
drizzle_return_t drizzle_set_revents(drizzle_st *con, short revents)

Set events that are ready for a connection. This is used with the external event callbacks. See drizzle_set_event_watch_fn().

Parameters:
  • con – Connection structure previously initialized with drizzle_create().
  • revents – Bitfield of poll() events that were detected.
Returns:

Standard drizzle return value.
const char* drizzle_error(const drizzle_st *con)

Get the last error from a connection

Parameters:
  • con – A connection object
Returns:

A string containing the error message
int drizzle_errno(const drizzle_st *con)

Get the last OS error code from a connection

Parameters:
  • con – A connection object
Returns:

The OS error code
uint16_t drizzle_error_code(const drizzle_st *con)

Gets the last error code from a connection

Parameters:
  • con – A connection object
Returns:

The server error code
const char* drizzle_sqlstate(const drizzle_st *con)

Gets the last sqlstate from a connection

Parameters:
  • con – A connection object
Returns:

A string containing the sqlstate
drizzle_options_st *drizzle_options_create(void)

Create a new connection options object

Returns:The new connection options object
void drizzle_options_destroy(drizzle_options_st *options)

Destroys a connection options object

Parameters:
  • options – The options object to be destroyed
void drizzle_socket_set_options(drizzle_options_st *options, int wait_timeout, int keepidle, int keepcnt, int keepintvl)

Sets several options for the socket connection

Parameters:
  • options – An initialized options structure
  • wait_timeout – The timeout (in seconds) for setsockopt calls with option values: SO_SNDTIMEO, SO_RCVTIMEO, SO_LINGER
  • keepidle – The time (in seconds) the connection needs to remain idle before TCP starts sending keepalive probes
  • keepcnt – The maximum number of keepalive probes TCP should send before dropping the connection.
  • keepintvl – The time (in seconds) between individual keepalive probes
void drizzle_socket_set_option(drizzle_st *con, drizzle_socket_option_t option, int value)

Sets the value of a socket option.

Note

The available options to set are:

DRIZZLE_SOCKET_OPTION_TIMEOUT : The timeout (in seconds) for setsockopt calls with option values: SO_SNDTIMEO, SO_RCVTIMEO, SO_LINGER

DRIZZLE_SOCKET_OPTION_KEEPIDLE : The time (in seconds) the connection needs to remain idle before TCP starts sending keepalive probes

DRIZZLE_SOCKET_OPTION_KEEPCNT : The maximum number of keepalive probes TCP should send before dropping the connection.

DRIZZLE_SOCKET_OPTION_KEEPINTVL : The time (in seconds) between individual keepalive probes

Parameters:
  • con – Connection structure previously initialized with drizzle_create().
  • option – the option to set the value for
  • value – the value to set
int drizzle_socket_get_option(drizzle_st *con, drizzle_socket_option_t option)

Gets the value of a socket option. See drizzle_socket_set_options() for a description of the available options

Parameters:
  • con – Connection structure previously initialized with drizzle_create().
  • option – option to get the value for
Returns:

The value of the option, or -1 if the specified option doesn’t exist
void drizzle_options_set_non_blocking(drizzle_options_st *options, bool state)

Sets/unsets non-blocking connect option

Parameters:
  • options – The options object to modify
  • state – Set option to true/false
bool drizzle_options_get_non_blocking(drizzle_options_st *options)

Gets the non-blocking connect option

Parameters:
  • options – The options object to get the value from
Returns:

The state of the non-blocking option
void drizzle_options_set_raw_scramble(drizzle_options_st *options, bool state)

Sets/unsets the raw scramble connect option

Parameters:
  • options – The options object to modify
  • state – Set to true/false
bool drizzle_options_get_raw_scramble(drizzle_options_st *options)

Gets the raw scramble connect option

Parameters:
  • options – The options object to get the value from
Returns:

The state of the raw scramble option
void drizzle_options_set_found_rows(drizzle_options_st *options, bool state)

Sets/unsets the found rows connect option

Parameters:
  • options – The options object to modify
  • state – Set to true/false
bool drizzle_options_get_found_rows(drizzle_options_st *options)

Gets the found rows connect option

Parameters:
  • options – The options object to get the value from
Returns:

The state of the found rows option
void drizzle_options_set_interactive(drizzle_options_st *options, bool state)

Sets/unsets the interactive connect option

Parameters:
  • options – The options object to modify
  • state – Set to true/false
bool drizzle_options_get_interactive(drizzle_options_st *options)

Gets the interactive connect option

Parameters:
  • options – The options object to get the value from
Returns:

The state of the interactive option
void drizzle_options_set_multi_statements(drizzle_options_st *options, bool state)

Sets/unsets the multi-statements connect option

Parameters:
  • options – The options object to modify
Parma state:

Set to true/false
bool drizzle_options_get_multi_statements(drizzle_options_st *options)

Gets the multi-statements connect option

Parameters:
  • options – The options object to get the value from
Returns:

The state of the multi-statements option
void drizzle_options_set_auth_plugin(drizzle_options_st *options, bool state)

Sets/unsets the auth plugin connect option

Parameters:
  • options – The options object to modify
  • state – Set to true/false
bool drizzle_options_get_auth_plugin(drizzle_options_st *options)

Gets the auth plugin connect option

Parameters:
  • options – The options object to get the value from
Returns:

The state of the auth plugin option
void drizzle_options_set_socket_owner(drizzle_options_st *options, drizzle_socket_owner_t owner)

Sets the owner of the socket connection

Parameters:
  • options – The options object to modify
  • owner – The owner of the socket connection
drizzle_socket_owner_t drizzle_options_get_socket_owner(drizzle_options_st *options)

Gets the owner of the socket connection

Parameters:
  • options – The options object to get the value from
Returns:

The owner of the socket connection
const char* drizzle_host(const drizzle_st *con)

Gets the host name from a TCP/IP connection

Parameters:
  • con – A connection object
Returns:

A string containing the host name or NULL for a UDS connection
in_port_t drizzle_port(const drizzle_st *con)

Gets the port number from a TCP/IP connection

Parameters:
  • con – A connection object
Returns:

The port number or 0 for a UDS connection
const char* drizzle_user(const drizzle_st *con)

Gets the user name used at connection time

Parameters:
  • con – A connection object
Returns:

A string containing the user name
const char* drizzle_db(const drizzle_st *con)

Gets the default database used at connection time

Parameters:
  • con – A connection object
Returns:

A string containing the DB name
void *drizzle_context(const drizzle_st *con)

Get application context pointer for a connection.

Parameters:
Returns:

Application context with this connection.
void drizzle_set_context(drizzle_st *con, void *context)

Set application context pointer for a connection.

Parameters:
  • con – Connection structure previously initialized with drizzle_create().
  • context – Application context to use with this connection.
void drizzle_set_context_free_fn(drizzle_st *con, drizzle_context_free_fn *function)

Set callback function when the context pointer should be freed.

Parameters:
  • con – Connection structure previously initialized with drizzle_create().
  • function – Function to call to clean up connection context.
uint8_t drizzle_protocol_version(const drizzle_st *con)

Gets the protocol version used for a connection

Parameters:
  • con – A connection object
Returns:

The protocol version
const char* drizzle_server_version(const drizzle_st *con)

Gets the server version string for a connection

Parameters:
  • con – A connection object
Returns:

A string containing the server version
uint32_t drizzle_server_version_number(const drizzle_st *con)

Gets the server version number for a connection

Parameters:
  • con – A connection object
Returns:

An integer containing the server version number
uint32_t drizzle_thread_id(const drizzle_st *con)

Gets the server thread ID for a connection

Parameters:
  • con – A connection object
Returns:

The server thread ID
const unsigned char *drizzle_scramble(const drizzle_st *con)

Get scramble buffer for a connection.

Parameters:
Returns:

Scramble buffer for connection.
drizzle_capabilities_t drizzle_capabilities(const drizzle_st *con)

Gets the server capabilities for a connection

Parameters:
  • con – A connection object
Returns:

A bit field of capabilities
drizzle_charset_t drizzle_charset(const drizzle_st *con)

Gets the character set ID for the connection

Parameters:
  • con – A connection object
Returns:

The character set used
drizzle_status_t drizzle_status(const drizzle_st *con)

Gets the status of the connection

Parameters:
  • con – A connection object
Returns:

The status of the connection
uint32_t drizzle_max_packet_size(const drizzle_st *con)

Gets the max packet size for a connection

Parameters:
  • con – A connection object
Returns:

The max packet size for the connection
drizzle_return_t drizzle_connect(drizzle_st *con)

Open connection to the specified server

Parameters:
  • con – A connection object
Returns:

A drizzle_return_t status. DRIZZLE_RETURN_OK upon success
drizzle_return_t drizzle_wait(drizzle_st *con)

Wait for I/O on connections.

Parameters:
Returns:

Standard drizzle return value.
drizzle_st *drizzle_ready(drizzle_st *con)

Get next connection that is ready for I/O.

Parameters:
Returns:

Connection that is ready for I/O, or NULL if there are none.
drizzle_return_t drizzle_close(drizzle_st *con)

Gracefully disconnect from a server (leaves the connection object available for a reconnect)

Parameters:
  • con – A connection object
Returns:

A drizzle_return_t response for the quit command sent to the server
drizzle_return_t drizzle_quit(drizzle_st *con)

Gracefully disconnect from a server and free the connection object

Parameters:
  • con – A connection object
Returns:

A drizzle_return_t response for the quit command sent to the server
drizzle_return_t drizzle_select_db(drizzle_st *con, const char *db)

Change the current default database

Parameters:
  • con – A connection object
  • db – The new default database
Returns:

A drizzle_return_t response
drizzle_result_st* drizzle_shutdown(drizzle_st *con, drizzle_return_t *ret_ptr)

Send a shutdown command to the server

Parameters:
  • con – A connection object
  • ret_ptr – A pointer to a drizzle_return_t to store the return status into
Returns:

A newly allocated result object
drizzle_result_st* drizzle_kill(drizzle_st *con, uint32_t connection_id, drizzle_return_t *ret_ptr)

Sends a query kill command to the server

Parameters:
  • con – A connection object
  • connection_id – The connection ID to kill a query from
  • ret_ptr – A pointer to a drizzle_return_t to store the return status into
Returns:

A newly allocated result object
drizzle_result_st* drizzle_ping(drizzle_st *con, drizzle_return_t *ret_ptr)

Sends a ping to the server

Parameters:
  • con – A connection object
  • ret_ptr – A pointer to a drizzle_return_t to store the return status into
Returns:

A newly allocated result object
const char *drizzle_strerror(const drizzle_return_t ret)

Get detailed error description

Parameters:
  • ret – A libdrizzle return value
Returns:

description of libdrizzle error

Callback Functions

These are templates to be used when creating callback functions for the Libdrizzle Redux library.

void drizzle_log_fn(const char *log_buffer, drizzle_verbose_t verbose, void *context)

The format of a callback function for log handling

Parameters:
  • log_buffer – The log message passed to the function
  • verbose – The verbosity level of the message
  • context – A pointer to data set in drizzle_set_log_fn()
drizzle_return_t drizzle_event_watch_fn(drizzle_st *con, short events, void *context)

The format of a function to register or deregister interest in file descriptor events

Parameters:
  • con – Connection that has changed the events it is interested in. Use drizzle_fd() to get the file descriptor.
  • events – A bit mask of POLLIN | POLLOUT, specifying if the connection is waiting for read or write events.
  • context – Application context pointer registered with drizzle_set_event_watch_fn()
Returns:

DRIZZLE_RETURN_OK if successful.