MySQL binding used in prepared statements. More...

#include <mysql_binding.h>

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

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

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

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

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

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

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

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

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

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

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

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

Static Public Member Functions
template<typename T >
static MySqlBindingPtr	condCreateInteger (T value)
	Conditionally creates binding of numeric type for sending data if provided value is not 0. More...

static MySqlBindingPtr	condCreateString (const std::string &value)
	Conditionally creates binding of text type for sending data if provided value is not empty. More...

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

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

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

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

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

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

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

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

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

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

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

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

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

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 153 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 299 of file mysql_binding.h.

References isc::db::MLM_TRUE.

Referenced by getIntegerOrDefault().

◆ condCreateInteger()

template<typename T >

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

inlinestatic

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

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 392 of file mysql_binding.h.

References createInteger(), and createNull().

Here is the call graph for this function:

◆ condCreateString()

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

static

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

Parameters

value String value to be sent to the database.

Returns: Pointer to the created binding.

Definition at line 95 of file mysql_binding.cc.

◆ convertFromDatabaseTime() [1/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 180 of file mysql_binding.cc.

Referenced by isc::db::MySqlConnection::convertFromDatabaseTime().

◆ convertFromDatabaseTime() [2/2]

boost::posix_time::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 posix time.

Definition at line 200 of file mysql_binding.cc.

◆ convertToDatabaseTime() [1/2]

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 128 of file mysql_binding.cc.

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

◆ convertToDatabaseTime() [2/2]

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 147 of file mysql_binding.cc.

References isc_throw.

◆ 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 100 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 345 of file mysql_binding.h.

◆ 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 359 of file mysql_binding.h.

Referenced by condCreateInteger().

◆ 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 375 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 122 of file mysql_binding.cc.

Referenced by condCreateInteger().

◆ createString() [1/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 80 of file mysql_binding.cc.

◆ createString() [2/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 87 of file mysql_binding.cc.

◆ 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 115 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 107 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 vactor.

Definition at line 44 of file mysql_binding.cc.

◆ 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 vactor.

Definition at line 54 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 244 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 266 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 35 of file mysql_binding.cc.

References isc::data::Element::fromJSON().

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 171 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 17 of file mysql_binding.cc.

◆ 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 27 of file mysql_binding.cc.

◆ getTimestamp()

boost::posix_time::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 62 of file mysql_binding.cc.

◆ getTimestampOrDefault()

boost::posix_time::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 72 of file mysql_binding.cc.

◆ 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 159 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()

◆ condCreateInteger()

◆ condCreateString()

◆ convertFromDatabaseTime() [1/2]

◆ convertFromDatabaseTime() [2/2]

◆ convertToDatabaseTime() [1/2]

◆ convertToDatabaseTime() [2/2]

◆ createBlob() [1/2]

◆ createBlob() [2/2]

◆ createInteger() [1/2]

◆ createInteger() [2/2]

◆ createNull()

◆ createString() [1/2]

◆ createString() [2/2]

◆ createTimestamp() [1/2]

◆ createTimestamp() [2/2]

◆ getBlob()

◆ getBlobOrDefault()

◆ getInteger()

◆ getIntegerOrDefault()

◆ getJSON()

◆ getMySqlBinding()

◆ getString()

◆ getStringOrDefault()

◆ getTimestamp()

◆ getTimestampOrDefault()

◆ getType()