MySQL binding used in prepared statements. More...

#include <mysql_binding.h>

Public Member Functions
bool	amNull () const
	Checks if the bound value is NULL.

std::vector< uint8_t >	getBlob () const
	Returns value held in the binding as blob.

std::vector< uint8_t >	getBlobOrDefault (const std::vector< uint8_t > &default_value) const
	Returns value held in the binding as blob.

bool	getBool () const
	Returns boolean value held in the binding.

float	getFloat () const
	Returns float value held in the binding.

template<typename T >
T	getInteger () const
	Returns numeric value held in the binding.

template<typename T >
T	getIntegerOrDefault (T default_value) const
	Returns numeric value held in the binding.

data::ElementPtr	getJSON () const
	Returns value held in the binding as JSON.

MYSQL_BIND &	getMySqlBinding ()
	Returns reference to the native binding.

std::string	getString () const
	Returns value held in the binding as string.

std::string	getStringOrDefault (const std::string &default_value) const
	Returns value held in the binding as string.

boost::posix_time::ptime	getTimestamp () const
	Returns timestamp value held in the binding.

boost::posix_time::ptime	getTimestampOrDefault (const boost::posix_time::ptime &default_value) const
	Returns timestamp value held in the binding.

enum_field_types	getType () const
	Returns MySQL column type for the binding.

Static Public Member Functions
static MySqlBindingPtr	condCreateBool (const util::Optional< bool > &value)
	Conditionally creates binding of `uint8_t` type representing a boolean value if provided value is specified.

template<typename T >
static MySqlBindingPtr	condCreateFloat (const util::Optional< T > &value)
	Conditionally creates binding of float type for sending data if provided value is specified.

template<typename T >
static MySqlBindingPtr	condCreateInteger (const util::Optional< T > &value)
	Conditionally creates binding of numeric type for sending data if provided value is specified.

static MySqlBindingPtr	condCreateIPv4Address (const util::Optional< asiolink::IOAddress > &value)
	Conditionally creates binding of `uint32_t` type representing an IPv4 address if provided value is specified.

static MySqlBindingPtr	condCreateString (const util::Optional< std::string > &value)
	Conditionally creates binding of text type for sending data if provided value is unspecified.

static boost::posix_time::ptime	convertFromDatabaseTime (const MYSQL_TIME &database_time)
	Converts database time to POSIX time.

static void	convertFromDatabaseTime (const MYSQL_TIME &expire, uint32_t valid_lifetime, time_t &cltt)
	Converts Database Time to Lease Times.

static void	convertToDatabaseTime (const boost::posix_time::ptime &input_time, MYSQL_TIME &output_time)
	Converts POSIX time value to database time.

static void	convertToDatabaseTime (const time_t cltt, const uint32_t valid_lifetime, MYSQL_TIME &expire)
	Converts Lease Time to Database Times.

static void	convertToDatabaseTime (const time_t input_time, MYSQL_TIME &output_time)
	Converts time_t value to database time.

static MySqlBindingPtr	createBlob (const unsigned long length)
	Creates binding of blob type for receiving data.

template<typename Iterator >
static MySqlBindingPtr	createBlob (Iterator begin, Iterator end)
	Creates binding of blob type for sending data.

static MySqlBindingPtr	createBool ()
	Creates binding having a bool type for receiving data.

static MySqlBindingPtr	createBool (const bool value)
	Creates binding having a bool type for sending data.

static MySqlBindingPtr	createFloat (const float value)
	Creates binding having a float type for sending data.

template<typename T >
static MySqlBindingPtr	createInteger ()
	Creates binding of numeric type for receiving data.

template<typename T >
static MySqlBindingPtr	createInteger (T value)
	Creates binding of numeric type for sending data.

static MySqlBindingPtr	createNull ()
	Creates binding encapsulating a NULL value.

static MySqlBindingPtr	createString (const std::string &value)
	Creates binding of text type for sending data.

static MySqlBindingPtr	createString (const unsigned long length)
	Creates binding of text type for receiving data.

static MySqlBindingPtr	createTimestamp ()
	Creates binding of timestamp type for receiving data.

static MySqlBindingPtr	createTimestamp (const boost::posix_time::ptime &timestamp)
	Creates binding of timestamp type for sending data.

Detailed Description

MySQL binding used in prepared statements.

Kea uses prepared statements to execute queries in a database. Prepared statements include placeholders for the input parameters. These parameters are passed to the prepared statements via a collection of MYSQL_BIND structures. The same structures are used to receive the values from the database as a result of SELECT statements.

The MYSQL_BIND structure contains information about the data type and length. It also contains pointer to the buffer actually holding the data to be passed to the database, a flag indicating if the value is null etc.

The MySqlBinding is a C++ wrapper around this structure which is meant to ease management of the MySQL bindings. The major benefit is that the MySqlBinding class owns the buffer, holding the data as well as other variables which are assigned to the MYSQL_BIND structure. It also automatically detects the appropriate enum_field_types value based on the C++ type used in the binding.

Definition at line 162 of file mysql_binding.h.

Member Function Documentation

◆ amNull()

bool isc::db::MySqlBinding::amNull ( ) const

inline

Checks if the bound value is NULL.

Returns: true if the value in the binding is NULL, false otherwise.

Definition at line 332 of file mysql_binding.h.

References isc::db::MLM_TRUE.

Referenced by getBlobOrDefault(), getIntegerOrDefault(), getJSON(), getStringOrDefault(), and getTimestampOrDefault().

◆ condCreateBool()

MySqlBindingPtr isc::db::MySqlBinding::condCreateBool ( const util::Optional< bool > & value )

static

Conditionally creates binding of uint8_t type representing a boolean value if provided value is specified.

Parameters

value Boolean value for which the binding should be created.

Returns: Pointer to the created binding.

Definition at line 145 of file mysql_binding.cc.

References createNull(), isc::util::Optional< T >::get(), and isc::util::Optional< T >::unspecified().

Here is the call graph for this function:

◆ condCreateFloat()

template<typename T >

static MySqlBindingPtr isc::db::MySqlBinding::condCreateFloat ( const util::Optional< T > & value )

inlinestatic

Conditionally creates binding of float type for sending data if provided value is specified.

Template Parameters

T	Floating point type to be converted to float.

Parameters

value Value to be stored in the database as float.

Returns: Pointer to the created binding.

Definition at line 445 of file mysql_binding.h.

References createNull(), isc::util::Optional< T >::get(), and isc::util::Optional< T >::unspecified().

Here is the call graph for this function:

◆ condCreateInteger()

template<typename T >

static MySqlBindingPtr isc::db::MySqlBinding::condCreateInteger ( const util::Optional< T > & value )

inlinestatic

Conditionally creates binding of numeric type for sending data if provided value is specified.

Template Parameters

T	Numeric type corresponding to the binding type, e.g. `uint8_t`, `uint16_t` etc.

Parameters

value Numeric value to be sent to the database.

Returns: Pointer to the created binding.

Definition at line 425 of file mysql_binding.h.

References createNull(), isc::util::Optional< T >::get(), and isc::util::Optional< T >::unspecified().

Here is the call graph for this function:

◆ condCreateIPv4Address()

MySqlBindingPtr isc::db::MySqlBinding::condCreateIPv4Address ( const util::Optional< asiolink::IOAddress > & value )

static

Conditionally creates binding of uint32_t type representing an IPv4 address if provided value is specified.

Parameters

value IOAddress encapsulating an IPv4 address.

Returns: Pointer to the created binding.

Definition at line 154 of file mysql_binding.cc.

References createNull(), and isc_throw.

Here is the call graph for this function:

◆ condCreateString()

MySqlBindingPtr isc::db::MySqlBinding::condCreateString ( const util::Optional< std::string > & value )

static

Conditionally creates binding of text type for sending data if provided value is unspecified.

Parameters

value String value to be sent to the database.

Returns: Pointer to the created binding.

Definition at line 112 of file mysql_binding.cc.

References createNull(), and createString().

Here is the call graph for this function:

◆ convertFromDatabaseTime() [1/2]

ptime isc::db::MySqlBinding::convertFromDatabaseTime ( const MYSQL_TIME & database_time )

static

Converts database time to POSIX time.

Parameters

database_time Reference to MYSQL_TIME object where database time is stored.

Returns: Database time converted to local POSIX time.

Todo: Use fractional seconds instead of 0 when minimum supported MySQL version has it.

Definition at line 293 of file mysql_binding.cc.

◆ convertFromDatabaseTime() [2/2]

void isc::db::MySqlBinding::convertFromDatabaseTime	(	const MYSQL_TIME &	expire,
		uint32_t	valid_lifetime,
		time_t &	cltt )

static

Converts Database Time to Lease Times.

Within the database, time is stored as "expire" (time of expiry of the lease) and valid lifetime. In the DHCP server, the information is stored client last transmit time and valid lifetime. These are related by the equation:

client last transmit time = expire - valid_lifetime

This method converts from the times in the database into times able to be inserted into the lease object.

Parameters

expire	Reference to MYSQL_TIME object from where the expiry time of the lease is taken.
valid_lifetime	lifetime of the lease.
cltt	Reference to location where client last transmit time is put.

Definition at line 273 of file mysql_binding.cc.

Referenced by isc::db::MySqlConnection::convertFromDatabaseTime(), and getTimestamp().

◆ convertToDatabaseTime() [1/3]

void isc::db::MySqlBinding::convertToDatabaseTime	(	const boost::posix_time::ptime &	input_time,
		MYSQL_TIME &	output_time )

static

Converts POSIX time value to database time.

Parameters

input_time	A POSIX time value representing local time.
output_time	Reference to MYSQL_TIME object where converted time will be put.

Todo: Use fractional seconds instead of 0 when minimum supported MySQL version has it.

Definition at line 213 of file mysql_binding.cc.

References isc_throw.

◆ convertToDatabaseTime() [2/3]

void isc::db::MySqlBinding::convertToDatabaseTime	(	const time_t	cltt,
		const uint32_t	valid_lifetime,
		MYSQL_TIME &	expire )

static

Converts Lease Time to Database Times.

Within the DHCP servers, times are stored as client last transmit time and valid lifetime. In the database, the information is stored as valid lifetime and "expire" (time of expiry of the lease). They are related by the equation:

expire = client last transmit time + valid lifetime

This method converts from the times in the lease object into times able to be added to the database.

Parameters

cltt	Client last transmit time
valid_lifetime	Valid lifetime
expire	Reference to MYSQL_TIME object where the expiry time of the DHCP lease will be put.

Exceptions

isc::BadValue if the sum of the calculated expiration time is greater than the value of LeaseMgr::MAX_DB_TIME.

Definition at line 237 of file mysql_binding.cc.

References isc_throw, and isc::db::DatabaseConnection::MAX_DB_TIME.

◆ convertToDatabaseTime() [3/3]

void isc::db::MySqlBinding::convertToDatabaseTime	(	const time_t	input_time,
		MYSQL_TIME &	output_time )

static

Converts time_t value to database time.

Parameters

input_time	A time_t value representing time.
output_time	Reference to MYSQL_TIME object where converted time will be put.

Definition at line 191 of file mysql_binding.cc.

Referenced by isc::db::MySqlConnection::convertToDatabaseTime(), and isc::db::MySqlConnection::convertToDatabaseTime().

◆ createBlob() [1/2]

MySqlBindingPtr isc::db::MySqlBinding::createBlob ( const unsigned long length )

static

Creates binding of blob type for receiving data.

Parameters

length Length of the buffer into which received data will be stored.

Returns: Pointer to the created binding.

Definition at line 117 of file mysql_binding.cc.

◆ createBlob() [2/2]

template<typename Iterator >

static MySqlBindingPtr isc::db::MySqlBinding::createBlob	(	Iterator	begin,
		Iterator	end )

inlinestatic

Creates binding of blob type for sending data.

Template Parameters

Iterator Type of the iterator.

Parameters

begin	Iterator pointing to the beginning of the input buffer holding the data to be sent to the database.
end	Iterator pointing to the end of the input buffer holding the data to be sent to the database.

Returns: Pointer to the created binding.

Definition at line 378 of file mysql_binding.h.

◆ createBool() [1/2]

MySqlBindingPtr isc::db::MySqlBinding::createBool ( )

static

Creates binding having a bool type for receiving data.

Returns: Pointer to the created binding holding an uint8_t value representing the boolean value.

Definition at line 135 of file mysql_binding.cc.

◆ createBool() [2/2]

MySqlBindingPtr isc::db::MySqlBinding::createBool ( const bool value )

static

Creates binding having a bool type for sending data.

Parameters

value Boolean value to be sent to the database.

Returns: Pointer to the created binding holding an uint8_t value representing the boolean value.

Definition at line 140 of file mysql_binding.cc.

◆ createFloat()

MySqlBindingPtr isc::db::MySqlBinding::createFloat ( const float value )

static

Creates binding having a float type for sending data.

Parameters

value Float value to be sent to the database.

Returns: Pointer to the created binding.

Definition at line 124 of file mysql_binding.cc.

◆ createInteger() [1/2]

template<typename T >

static MySqlBindingPtr isc::db::MySqlBinding::createInteger ( )

inlinestatic

Creates binding of numeric type for receiving data.

Template Parameters

Numeric type corresponding to the binding type, e.g. uint8_t, uint16_t etc.

Returns: Pointer to the created binding.

Definition at line 392 of file mysql_binding.h.

◆ createInteger() [2/2]

template<typename T >

static MySqlBindingPtr isc::db::MySqlBinding::createInteger ( T value )

inlinestatic

Creates binding of numeric type for sending data.

Template Parameters

Numeric type corresponding to the binding type, e.g. uint8_t, uint16_t etc.

Parameters

value Numeric value to be sent to the database.

Returns: Pointer to the created binding.

Definition at line 408 of file mysql_binding.h.

◆ createNull()

MySqlBindingPtr isc::db::MySqlBinding::createNull ( )

static

Creates binding encapsulating a NULL value.

This method is used to create a binding encapsulating a NULL value, which can be used to assign NULL to any type of column.

Returns: Pointer to the created binding.

Definition at line 185 of file mysql_binding.cc.

Referenced by condCreateBool(), condCreateFloat(), condCreateInteger(), condCreateIPv4Address(), and condCreateString().

◆ createString() [1/2]

MySqlBindingPtr isc::db::MySqlBinding::createString ( const std::string & value )

static

Creates binding of text type for sending data.

Parameters

value String value to be sent to the database.

Returns: Pointer to the created binding.

Definition at line 104 of file mysql_binding.cc.

◆ createString() [2/2]

MySqlBindingPtr isc::db::MySqlBinding::createString ( const unsigned long length )

static

Creates binding of text type for receiving data.

Parameters

length Length of the buffer into which received data will be stored.

Returns: Pointer to the created binding.

Definition at line 97 of file mysql_binding.cc.

Referenced by condCreateString().

◆ createTimestamp() [1/2]

MySqlBindingPtr isc::db::MySqlBinding::createTimestamp ( )

static

Creates binding of timestamp type for receiving data.

Returns: Pointer to the created binding.

Definition at line 178 of file mysql_binding.cc.

◆ createTimestamp() [2/2]

MySqlBindingPtr isc::db::MySqlBinding::createTimestamp ( const boost::posix_time::ptime & timestamp )

static

Creates binding of timestamp type for sending data.

Parameters

timestamp Timestamp value to be sent to the database.

Returns: Pointer to the created binding.

Definition at line 170 of file mysql_binding.cc.

◆ getBlob()

std::vector< uint8_t > isc::db::MySqlBinding::getBlob ( ) const

Returns value held in the binding as blob.

Call MySqlBinding::amNull to verify that the value is not null prior to calling this method.

Exceptions

InvalidOperation if the value is NULL or the binding type is not MYSQL_TYPE_BLOB.

Returns: Blob in a vector.

Definition at line 50 of file mysql_binding.cc.

Referenced by getBlobOrDefault().

◆ getBlobOrDefault()

std::vector< uint8_t > isc::db::MySqlBinding::getBlobOrDefault ( const std::vector< uint8_t > & default_value ) const

Returns value held in the binding as blob.

If the value to be returned is null, a default value is returned.

Parameters

default_value Default value.

Exceptions

InvalidOperation if the binding type is not MYSQL_TYPE_BLOB.

Returns: Blob in a vector.

Definition at line 60 of file mysql_binding.cc.

References amNull(), and getBlob().

Here is the call graph for this function:

◆ getBool()

bool isc::db::MySqlBinding::getBool ( ) const

inline

Returns boolean value held in the binding.

Call MySqlBinding::amNull to verify that the value is not null prior to calling this method.

Exceptions

InvalidOperation if the value is NULL or the binding type is not uint8_t.

Returns: Boolean value.

Definition at line 302 of file mysql_binding.h.

◆ getFloat()

float isc::db::MySqlBinding::getFloat ( ) const

Returns float value held in the binding.

Call MySqlBinding::amNull to verify that the value is not null prior to calling this method.

Exceptions

InvalidOperation if the value is NULL or the binding type does not match the template parameter.

Returns: Float value.

Definition at line 68 of file mysql_binding.cc.

◆ getInteger()

template<typename T >

T isc::db::MySqlBinding::getInteger ( ) const

inline

Returns numeric value held in the binding.

Call MySqlBinding::amNull to verify that the value is not null prior to calling this method.

Template Parameters

Numeric type corresponding to the binding type, e.g. uint8_t, uint16_t etc.

Exceptions

InvalidOperation if the value is NULL or the binding type does not match the template parameter.

Returns: Numeric value of a specified type.

Definition at line 253 of file mysql_binding.h.

◆ getIntegerOrDefault()

template<typename T >

T isc::db::MySqlBinding::getIntegerOrDefault ( T default_value ) const

inline

Returns numeric value held in the binding.

If the value to be returned is null, a default value is returned.

Template Parameters

Numeric type corresponding to the binding type, e.g. uint8_t, uint16_t etc.

Parameters

default_value Default value.

Exceptions

InvalidOperation if the binding type does not match the template parameter.

Returns: Numeric value of a specified type.

Definition at line 275 of file mysql_binding.h.

References amNull().

Here is the call graph for this function:

◆ getJSON()

ElementPtr isc::db::MySqlBinding::getJSON ( ) const

Returns value held in the binding as JSON.

Call MySqlBinding::amNull to verify that the value is not null prior to calling this method.

Exceptions

InvalidOperation	if the binding is not `MYSQL_TYPE_STRING`.
data::JSONError	if the string value is not a valid JSON.

Returns: JSON structure or NULL if the string is null.

Definition at line 41 of file mysql_binding.cc.

References amNull(), isc::data::Element::fromJSON(), and getString().

Here is the call graph for this function:

◆ getMySqlBinding()

MYSQL_BIND & isc::db::MySqlBinding::getMySqlBinding ( )

inline

Returns reference to the native binding.

The returned reference is only valid for the lifetime of the object. Make sure that the object is not destroyed as long as the binding is required. In particular, do not destroy this object before database query is complete.

Returns: Reference to native MySQL binding.

Definition at line 180 of file mysql_binding.h.

◆ getString()

std::string isc::db::MySqlBinding::getString ( ) const

Returns value held in the binding as string.

Call MySqlBinding::amNull to verify that the value is not null prior to calling this method.

Exceptions

InvalidOperation if the value is NULL or the binding type is not MYSQL_TYPE_STRING.

Returns: String value.

Definition at line 23 of file mysql_binding.cc.

Referenced by getJSON(), and getStringOrDefault().

◆ getStringOrDefault()

std::string isc::db::MySqlBinding::getStringOrDefault ( const std::string & default_value ) const

Returns value held in the binding as string.

If the value to be returned is null, a default value is returned.

Parameters

default_value Default value.

Exceptions

InvalidOperation if the binding type is not MYSQL_TYPE_STRING.

Returns: String value.

Definition at line 33 of file mysql_binding.cc.

References amNull(), and getString().

Here is the call graph for this function:

◆ getTimestamp()

ptime isc::db::MySqlBinding::getTimestamp ( ) const

Returns timestamp value held in the binding.

Call MySqlBinding::amNull to verify that the value is not null prior to calling this method.

Exceptions

InvalidOperation if the value is NULL or the binding type is not MYSQL_TYPE_TIMESTAMP.

Returns: Timestamp converted to POSIX time.

Definition at line 79 of file mysql_binding.cc.

References convertFromDatabaseTime().

Referenced by getTimestampOrDefault().

Here is the call graph for this function:

◆ getTimestampOrDefault()

ptime isc::db::MySqlBinding::getTimestampOrDefault ( const boost::posix_time::ptime & default_value ) const

Returns timestamp value held in the binding.

If the value to be returned is null, a default value is returned.

Parameters

default_value Default value.

Exceptions

InvalidOperation if the binding type is not MYSQL_TYPE_TIMESTAMP.

Returns: Timestamp converted to POSIX time.

Definition at line 89 of file mysql_binding.cc.

References amNull(), and getTimestamp().

Here is the call graph for this function:

◆ getType()

enum_field_types isc::db::MySqlBinding::getType ( ) const

inline

Returns MySQL column type for the binding.

Returns: column type, e.g. MYSQL_TYPE_STRING.

Definition at line 168 of file mysql_binding.h.

The documentation for this class was generated from the following files:

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ amNull()

◆ condCreateBool()

◆ condCreateFloat()

◆ condCreateInteger()

◆ condCreateIPv4Address()

◆ condCreateString()

◆ convertFromDatabaseTime() [1/2]

◆ convertFromDatabaseTime() [2/2]

◆ convertToDatabaseTime() [1/3]

◆ convertToDatabaseTime() [2/3]

◆ convertToDatabaseTime() [3/3]

◆ createBlob() [1/2]

◆ createBlob() [2/2]

◆ createBool() [1/2]

◆ createBool() [2/2]

◆ createFloat()

◆ createInteger() [1/2]

◆ createInteger() [2/2]

◆ createNull()

◆ createString() [1/2]

◆ createString() [2/2]

◆ createTimestamp() [1/2]

◆ createTimestamp() [2/2]

◆ getBlob()

◆ getBlobOrDefault()

◆ getBool()

◆ getFloat()

◆ getInteger()

◆ getIntegerOrDefault()

◆ getJSON()

◆ getMySqlBinding()

◆ getString()

◆ getStringOrDefault()

◆ getTimestamp()

◆ getTimestampOrDefault()

◆ getType()