Kea  2.3.5-git
isc::db::MySqlBinding Class Reference

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...
 
bool getBool () const
 Returns boolean value held in the binding. More...
 
float getFloat () const
 Returns float value held in the binding. More...
 
template<typename T >
getInteger () const
 Returns numeric value held in the binding. More...
 
template<typename 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

static MySqlBindingPtr condCreateBool (const util::Optional< bool > &value)
 Conditionally creates binding of uint8_t type representing a boolean value if provided value is specified. More...
 
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. More...
 
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. More...
 
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. More...
 
static MySqlBindingPtr condCreateString (const util::Optional< std::string > &value)
 Conditionally creates binding of text type for sending data if provided value is unspecified. 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 boost::posix_time::ptime &input_time, MYSQL_TIME &output_time)
 Converts POSIX time 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...
 
static MySqlBindingPtr createBool ()
 Creates binding having a bool type for receiving data. More...
 
static MySqlBindingPtr createBool (const bool value)
 Creates binding having a bool type for sending data. More...
 
static MySqlBindingPtr createFloat (const float value)
 Creates binding having a float 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 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::MySqlBindingTraits< T >::length, and isc::db::MLM_TRUE.

◆ 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
valueBoolean value for which the binding should be created.
Returns
Pointer to the created binding.

Definition at line 145 of file mysql_binding.cc.

References 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
TFloating point type to be converted to float.
Parameters
valueValue to be stored in the database as float.
Returns
Pointer to the created binding.

Definition at line 445 of file mysql_binding.h.

References 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
TNumeric type corresponding to the binding type, e.g. uint8_t, uint16_t etc.
Parameters
valueNumeric value to be sent to the database.
Returns
Pointer to the created binding.

Definition at line 425 of file mysql_binding.h.

References 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
valueIOAddress encapsulating an IPv4 address.
Returns
Pointer to the created binding.

Definition at line 154 of file mysql_binding.cc.

References isc::util::Optional< T >::get(), isc_throw, isc::asiolink::IOAddress::isV4(), isc::asiolink::IOAddress::toText(), isc::asiolink::IOAddress::toUint32(), and isc::util::Optional< T >::unspecified().

+ 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
valueString value to be sent to the database.
Returns
Pointer to the created binding.

Definition at line 112 of file mysql_binding.cc.

References isc::util::Optional< T >::unspecified().

+ Here is the call graph for this function:

◆ 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
expireReference to MYSQL_TIME object from where the expiry time of the lease is taken.
valid_lifetimelifetime of the lease.
clttReference to location where client last transmit time is put.

Definition at line 273 of file mysql_binding.cc.

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

◆ convertFromDatabaseTime() [2/2]

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

Converts database time to POSIX time.

Parameters
database_timeReference 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.

◆ convertToDatabaseTime() [1/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_timeA time_t value representing time.
output_timeReference 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().

◆ convertToDatabaseTime() [2/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_timeA POSIX time value representing local time.
output_timeReference 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() [3/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
clttClient last transmit time
valid_lifetimeValid lifetime
expireReference to MYSQL_TIME object where the expiry time of the DHCP lease will be put.
Exceptions
isc::BadValueif 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.

◆ createBlob() [1/2]

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

Creates binding of blob type for receiving data.

Parameters
lengthLength 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
IteratorType of the iterator.
Parameters
beginIterator pointing to the beginning of the input buffer holding the data to be sent to the database.
endIterator 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.

Referenced by isc::dhcp::MySqlLeaseMgr::deleteExpiredReclaimedLeases6().

◆ createBool() [2/2]

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

Creates binding having a bool type for sending data.

Parameters
valueBoolean 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
valueFloat 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
Numerictype 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 ( value)
inlinestatic

Creates binding of numeric type for sending data.

Template Parameters
Numerictype corresponding to the binding type, e.g. uint8_t, uint16_t etc.
Parameters
valueNumeric 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.

◆ createString() [1/2]

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

Creates binding of text type for receiving data.

Parameters
lengthLength 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 isc::dhcp::MySqlLeaseMgr::deleteExpiredReclaimedLeases6().

◆ createString() [2/2]

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

Creates binding of text type for sending data.

Parameters
valueString value to be sent to the database.
Returns
Pointer to the created binding.

Definition at line 104 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 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
timestampTimestamp 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
InvalidOperationif 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.

◆ 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_valueDefault value.
Exceptions
InvalidOperationif the binding type is not MYSQL_TYPE_BLOB.
Returns
Blob in a vector.

Definition at line 60 of file mysql_binding.cc.

◆ 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
InvalidOperationif 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
InvalidOperationif 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
Numerictype corresponding to the binding type, e.g. uint8_t, uint16_t etc.
Exceptions
InvalidOperationif 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 ( 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
Numerictype corresponding to the binding type, e.g. uint8_t, uint16_t etc.
Parameters
default_valueDefault value.
Exceptions
InvalidOperationif 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.

◆ 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
InvalidOperationif the binding is not MYSQL_TYPE_STRING.
data::JSONErrorif 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.

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

◆ 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_valueDefault value.
Exceptions
InvalidOperationif the binding type is not MYSQL_TYPE_STRING.
Returns
String value.

Definition at line 33 of file mysql_binding.cc.

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

◆ 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_valueDefault value.
Exceptions
InvalidOperationif the binding type is not MYSQL_TYPE_TIMESTAMP.
Returns
Timestamp converted to POSIX time.

Definition at line 89 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 168 of file mysql_binding.h.


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