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 madeParameters: - 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 usingdrizzle_options_create()
orNULL
Returns: A newly allocated and setup connection object
-
int
drizzle_fd
(const drizzle_st *con)¶ Get file descriptor for connection.
Parameters: - con – Connection structure previously initialized with
drizzle_create()
,drizzle_clone()
, or related functions.
Returns: File descriptor of connection, or -1 if not active.
- con – Connection structure previously initialized with
-
int
drizzle_timeout
(const drizzle_st *con)¶ Gets the current connection timeout set in the connection object
Parameters: - drizzle – 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: - drizzle – 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: - drizzle – 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: - drizzle – A connection object
- verbose – The verbosity level from
drizzle_verbose_t
-
void
drizzle_set_log_fn
(drizzle_st *con, drizzle_log_fn *function, void *context)¶ Sets a callback function for log handling
Parameters: - drizzle – 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 *drizzle, drizzle_event_watch_fn *function, void *context)¶ Set a custom I/O event watcher function for a drizzle structure
Parameters: - drizzle – Drizzle structure previously initialized with
drizzle_create()
ordrizzle_clone()
- 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 – Drizzle structure previously initialized with
-
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()
,drizzle_clone()
, or related functions. - events – Bitfield of poll() events to watch.
Returns: Standard drizzle return value.
- con – Connection structure previously initialized with
-
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()
,drizzle_clone()
, or related functions. - revents – Bitfield of poll() events that were detected.
Returns: Standard drizzle return value.
- con – Connection structure previously initialized with
-
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 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_LINGERDRIZZLE_SOCKET_OPTION_KEEPIDLE
: The time (in seconds) the connection needs to remain idle before TCP starts sending keepalive probesDRIZZLE_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 probesParameters: - con – Connection structure previously initialized with
drizzle_create()
,drizzle_clone()
, or related functions. - option – the option to set the value for
- value – the value to set
- con – Connection structure previously initialized with
-
int
drizzle_socket_get_option
(drizzle_st *con, drizzle_socket_option option)¶ Gets the value of a socket option. See
drizzle_socket_set_options()
for a description of the available optionsParameters: - con – Connection structure previously initialized with
drizzle_create()
,drizzle_clone()
, or related functions. - option – option to get the value for
Returns: The value of the option, or -1 if the specified option doesn’t exist
- con – Connection structure previously initialized with
-
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 *option)¶ 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 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
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: - con – Connection structure previously initialized with
drizzle_create()
,drizzle_clone()
, or related functions.
Returns: Application context with this connection.
- con – Connection structure previously initialized with
-
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()
,drizzle_clone()
, or related functions. - context – Application context to use with this connection.
- con – Connection structure previously initialized with
-
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()
,drizzle_clone()
, or related functions. - function – Function to call to clean up connection context.
- con – Connection structure previously initialized with
-
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: - con – Connection structure previously initialized with
drizzle_create()
,drizzle_clone()
, or related functions.
Returns: Scramble buffer for connection.
- con – Connection structure previously initialized with
-
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: - drizzle – Drizzle structure previously initialized with
drizzle_create()
ordrizzle_clone()
.
Returns: Standard drizzle return value.
- drizzle – Drizzle structure previously initialized with
-
drizzle_st *
drizzle_ready
(drizzle_st *con)¶ Get next connection that is ready for I/O.
Parameters: - drizzle – Drizzle structure previously initialized with
drizzle_create()
ordrizzle_clone()
.
Returns: Connection that is ready for I/O, or NULL if there are none.
- drizzle – Drizzle structure previously initialized with
-
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.- con – Connection that has changed the events it is interested in. Use