#include <pgsql_exchange.h>

Public Member Functions
	PsqlBindArray ()
	Constructor.

void	add (const bool &value)
	Adds a boolean value to the bind array.

void	add (const char *value)
	Adds a char array to bind array based.

void	add (const data::ConstElementPtr &value)
	Adds a ConstElementPtr to the bind array.

void	add (const data::ElementPtr &value)
	Adds an ElementPtr to the bind array.

void	add (const isc::asiolink::IOAddress &addr)
	Adds the given IOAddress value to the bind array.

void	add (const isc::util::Triplet< uint32_t > &triplet)
	Adds an integer Triplet's value to the bind array.

void	add (const std::string &value)
	Adds a string value to the bind array.

void	add (const std::vector< uint8_t > &data)
	Adds a vector of binary data to the bind array.

template<typename T >
void	add (const T &value)
	Adds the given value to the bind array.

void	add (const uint8_t &byte)
	Adds a uint8_t value to the bind array.

void	add (const uint8_t *data, const size_t len)
	Adds a buffer of binary data to the bind array.

void	addInet4 (const isc::asiolink::IOAddress &value)
	Adds an IPv4 address to the bind array.

void	addInet6 (const isc::asiolink::IOAddress &value)
	Adds an IPv6 address to the bind array.

void	addMax (const isc::util::Triplet< uint32_t > &triplet)
	Adds an integer Triplet's maximum value to the bind array.

void	addMin (const isc::util::Triplet< uint32_t > &triplet)
	Adds an integer Triplet's minimum value to the bind array.

void	addNull (const int format=PsqlBindArray::TEXT_FMT)
	Adds a NULL value to the bind array.

void	addOptional (const util::Optional< std::string > &value)
	Adds an `Optional` string to the bind array.

template<typename T >
void	addOptional (const util::Optional< T > &value)
	Adds an `Optional<type>` value to the bind array.

void	addOptionalInet4 (const util::Optional< isc::asiolink::IOAddress > &value)
	Adds an `Optional` IPv4 address to the bind array.

void	addOptionalInet6 (const util::Optional< isc::asiolink::IOAddress > &value)
	Adds an `Optional` IPv6 address to the bind array.

void	addTempBinary (const std::vector< uint8_t > &data)
	Adds a vector of binary data to the bind array.

void	addTempBuffer (const uint8_t *data, const size_t len)
	Adds a temporary buffer of binary data to the bind array.

void	addTempString (const std::string &str)
	Binds the given string to the bind array.

void	addTimestamp ()
	Adds a timestamp of the current time to the bind array.

void	addTimestamp (const boost::posix_time::ptime &timestamp)
	Adds a timestamp from a ptime to the bind array.

bool	amNull (size_t index=0) const
	Determines if specified value is null.

bool	empty () const
	Indicates it the array is empty.

template<typename T >
T	getInteger (size_t index=0)
	Returns the value as an integer.

int	getType (size_t index=0)
	Returns the column type.

void	insert (const char *value, size_t index)
	Inserts a string value to the bind array before the given index.

void	insert (const std::string &value, size_t index)
	Inserts a string value to the bind array before the given index.

void	popBack ()
	Removes the last entry in the bind array.

size_t	size () const
	Fetches the number of entries in the array.

std::string	toText () const
	Dumps the contents of the array to a string.

Public Attributes
std::vector< int >	formats_
	Vector of "format" for each value.

std::vector< int >	lengths_
	Vector of data lengths for each value.

std::vector< const char * >	values_
	Vector of pointers to the data values.

Static Public Attributes
static const int	BINARY_FMT = 1
	Format value for binary data.

static const char *	FALSE_STR = "FALSE"
	Constant string passed to DB for boolean false values.

static const int	TEXT_FMT = 0
	Format value for text data.

static const char *	TRUE_STR = "TRUE"
	Constant string passed to DB for boolean true values.

Detailed Description

Definition at line 151 of file pgsql_exchange.h.

Constructor & Destructor Documentation

◆ PsqlBindArray()

isc::db::PsqlBindArray::PsqlBindArray ( )

inline

Constructor.

Definition at line 153 of file pgsql_exchange.h.

Member Function Documentation

◆ add() [1/11]

void isc::db::PsqlBindArray::add ( const bool & value )

Adds a boolean value to the bind array.

Converts the given boolean value to its corresponding to PostgreSQL string value and adds it as a TEXT_FMT value to the bind array. This creates an internally scoped string.

Parameters

value the boolean value to add.

Definition at line 119 of file pgsql_exchange.cc.

References add(), FALSE_STR, and TRUE_STR.

Here is the call graph for this function:

◆ add() [2/11]

void isc::db::PsqlBindArray::add ( const char * value )

Adds a char array to bind array based.

Adds a TEXT_FMT value to the end of the bind array, using the given char* as the data source. The value is expected to be NULL terminated. The caller is responsible for ensuring that value remains in scope until the bind array has been discarded.

Parameters

value char array containing the null-terminated text to add.

Exceptions

DbOperationError if value is NULL.

Definition at line 31 of file pgsql_exchange.cc.

References formats_, isc_throw, lengths_, TEXT_FMT, and values_.

Referenced by add(), add(), addMax(), addMin(), addOptional(), and addTempString().

◆ add() [3/11]

void isc::db::PsqlBindArray::add ( const data::ConstElementPtr & value )

Adds a ConstElementPtr to the bind array.

Adds a TEXT_FMT value to the end of the bind array containing the JSON text output by given ElementPtr::toJSON().

Parameters

value ElementPtr containing Element tree to add.

Exceptions

DbOperationError if value is NULL.

Definition at line 279 of file pgsql_exchange.cc.

References addNull(), and addTempString().

Here is the call graph for this function:

◆ add() [4/11]

void isc::db::PsqlBindArray::add ( const data::ElementPtr & value )

Adds an ElementPtr to the bind array.

Adds a TEXT_FMT value to the end of the bind array containing the JSON text output by given ElementPtr::toJSON().

Parameters

value ElementPtr containing Element tree to add.

Exceptions

DbOperationError if value is NULL.

Definition at line 267 of file pgsql_exchange.cc.

References addNull(), and addTempString().

Here is the call graph for this function:

◆ add() [5/11]

void isc::db::PsqlBindArray::add ( const isc::asiolink::IOAddress & addr )

Adds the given IOAddress value to the bind array.

Converts the IOAddress, based on its protocol family, to the corresponding string literal and adds it as a TEXT_FMT value to the bind array. This creates an internally scoped string.

Parameters

addr	IP address value to add.

Definition at line 130 of file pgsql_exchange.cc.

References addTempString(), isc::asiolink::IOAddress::isV4(), isc::asiolink::IOAddress::toText(), and isc::asiolink::IOAddress::toUint32().

Here is the call graph for this function:

◆ add() [6/11]

void isc::db::PsqlBindArray::add ( const isc::util::Triplet< uint32_t > & triplet )

Adds an integer Triplet's value to the bind array.

Stores the current value of a triplet to the bind array. If it is unspecified it stores a NULL.

Parameters

triplet Triplet instance from which to get the value.

Definition at line 146 of file pgsql_exchange.cc.

References add(), addNull(), isc::util::Triplet< T >::get(), and isc::util::Optional< T >::unspecified().

Here is the call graph for this function:

◆ add() [7/11]

void isc::db::PsqlBindArray::add ( const std::string & value )

Adds a string value to the bind array.

Adds a TEXT formatted value to the end of the bind array using the given string as the data source. The caller is responsible for ensuring that string parameter remains in scope until the bind array has been discarded.

Parameters

value std::string containing the value to add.

Definition at line 41 of file pgsql_exchange.cc.

References formats_, lengths_, TEXT_FMT, and values_.

◆ add() [8/11]

void isc::db::PsqlBindArray::add ( const std::vector< uint8_t > & data )

Adds a vector of binary data to the bind array.

Adds a BINARY_FMT value to the end of the bind array using the given vector as the data source. NOTE this does not replicate the vector, so it must remain in scope until the bind array is destroyed.

Parameters

data	vector of binary bytes.

Definition at line 81 of file pgsql_exchange.cc.

References BINARY_FMT, formats_, lengths_, and values_.

◆ add() [9/11]

template<typename T >

void isc::db::PsqlBindArray::add ( const T & value )

inline

Adds the given value to the bind array.

Converts the given value to its corresponding string literal boost::lexical_cast and adds it as a TEXT_FMT value to the bind array. This is intended primarily for numeric types. This creates an internally scoped string.

Parameters

value data value to add.

Definition at line 327 of file pgsql_exchange.h.

References addTempString().

Here is the call graph for this function:

◆ add() [10/11]

void isc::db::PsqlBindArray::add ( const uint8_t & byte )

Adds a uint8_t value to the bind array.

Converts the given uint8_t value to its corresponding numeric string literal and adds it as a TEXT_FMT value to the bind array. This creates an internally scoped string.

Parameters

byte	the one byte value to add.

Definition at line 123 of file pgsql_exchange.cc.

References addTempString().

Here is the call graph for this function:

◆ add() [11/11]

void isc::db::PsqlBindArray::add	(	const uint8_t *	data,
		const size_t	len )

Adds a buffer of binary data to the bind array.

Adds a BINARY_FMT value to the end of the bind array using the given vector as the data source. NOTE this does not replicate the buffer, so it must remain in scope until the bind array is destroyed.

Parameters

data	buffer of binary data.
len	number of bytes of data in buffer

Exceptions

DbOperationError if data is NULL.

Definition at line 96 of file pgsql_exchange.cc.

References BINARY_FMT, formats_, isc_throw, lengths_, and values_.

◆ addInet4()

void isc::db::PsqlBindArray::addInet4 ( const isc::asiolink::IOAddress & value )

Adds an IPv4 address to the bind array.

This is used for inet type columns.

Parameters

value Optional boolean value to add

Exceptions

BadValue if the address is not a IPv4 address.

Definition at line 193 of file pgsql_exchange.cc.

References addTempString(), isc_throw, isc::asiolink::IOAddress::isV4(), and isc::asiolink::IOAddress::toText().

Referenced by addOptionalInet4().

Here is the call graph for this function:

◆ addInet6()

void isc::db::PsqlBindArray::addInet6 ( const isc::asiolink::IOAddress & value )

Adds an IPv6 address to the bind array.

This is used for inet type columns.

Parameters

value Optional boolean value to add

Exceptions

BadValue if the address is not a IPv6 address.

Definition at line 214 of file pgsql_exchange.cc.

References addTempString(), isc_throw, isc::asiolink::IOAddress::isV6(), and isc::asiolink::IOAddress::toText().

Referenced by addOptionalInet6().

Here is the call graph for this function:

◆ addMax()

void isc::db::PsqlBindArray::addMax ( const isc::util::Triplet< uint32_t > & triplet )

Adds an integer Triplet's maximum value to the bind array.

Stores the maximum value of a triplet to the bind array. If it is unspecified it stores a NULL.

Parameters

triplet Triplet instance from which to get the value.

Definition at line 164 of file pgsql_exchange.cc.

References add(), addNull(), isc::util::Triplet< T >::get(), isc::util::Triplet< T >::getMax(), and isc::util::Optional< T >::unspecified().

Here is the call graph for this function:

◆ addMin()

void isc::db::PsqlBindArray::addMin ( const isc::util::Triplet< uint32_t > & triplet )

Adds an integer Triplet's minimum value to the bind array.

Stores the minimum value of a triplet to the bind array. If it is unspecified it stores a NULL.

Parameters

triplet Triplet instance from which to get the value.

Definition at line 155 of file pgsql_exchange.cc.

References add(), addNull(), isc::util::Triplet< T >::get(), isc::util::Triplet< T >::getMin(), and isc::util::Optional< T >::unspecified().

Here is the call graph for this function:

◆ addNull()

void isc::db::PsqlBindArray::addNull ( const int format = PsqlBindArray::TEXT_FMT )

Adds a NULL value to the bind array.

This should be used whenever the value for a parameter specified in the SQL statement should be NULL.

Definition at line 139 of file pgsql_exchange.cc.

References formats_, lengths_, and values_.

Referenced by add(), add(), add(), addMax(), addMin(), addOptional(), addOptional(), addOptionalInet4(), and addOptionalInet6().

◆ addOptional() [1/2]

void isc::db::PsqlBindArray::addOptional ( const util::Optional< std::string > & value )

Adds an Optional string to the bind array.

Optional strings require adding a temp string to the bind array, unlike other types which implicitly do so.

Parameters

value Optional string value to add

Definition at line 184 of file pgsql_exchange.cc.

References addNull(), addTempString(), and isc::util::Optional< T >::unspecified().

Here is the call graph for this function:

◆ addOptional() [2/2]

template<typename T >

void isc::db::PsqlBindArray::addOptional ( const util::Optional< T > & value )

inline

Adds an Optional<type> value to the bind array.

Template Parameters

T	variable type corresponding to the binding type, e.g. `string`, bool, uint8_t, `uint16_t` etc.

Parameters

value Optional of type T.

Definition at line 385 of file pgsql_exchange.h.

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

Here is the call graph for this function:

◆ addOptionalInet4()

void isc::db::PsqlBindArray::addOptionalInet4 ( const util::Optional< isc::asiolink::IOAddress > & value )

Adds an Optional IPv4 address to the bind array.

This is used for inet type columns.

Parameters

value Optional boolean value to add

Exceptions

BadValue if the address is not a IPv4 address.

Definition at line 204 of file pgsql_exchange.cc.

References addInet4(), addNull(), and isc::util::Optional< T >::unspecified().

Here is the call graph for this function:

◆ addOptionalInet6()

void isc::db::PsqlBindArray::addOptionalInet6 ( const util::Optional< isc::asiolink::IOAddress > & value )

Adds an Optional IPv6 address to the bind array.

This is used for inet type columns which expect v4 addresses to be inserted in string form: '3001::1'

Parameters

value Optional boolean value to add

Exceptions

BadValue if the address is not a IPv6 address.

Definition at line 225 of file pgsql_exchange.cc.

References addInet6(), addNull(), and isc::util::Optional< T >::unspecified().

Here is the call graph for this function:

◆ addTempBinary()

void isc::db::PsqlBindArray::addTempBinary ( const std::vector< uint8_t > & data )

Adds a vector of binary data to the bind array.

Adds a BINARY_FMT value to the end of the bind array using the given vector as the data source. This creates an internally scoped copy of the vector.

Parameters

data	vector of binary bytes.

Definition at line 87 of file pgsql_exchange.cc.

References BINARY_FMT, formats_, lengths_, and values_.

◆ addTempBuffer()

void isc::db::PsqlBindArray::addTempBuffer	(	const uint8_t *	data,
		const size_t	len )

Adds a temporary buffer of binary data to the bind array.

Adds a BINARY_FMT value to the end of the bind array using the given vector as the data source. Prior to adding the buffer, it is duplicated as a ConstStringPtr and saved internally. This guarantees the buffer remains in scope until the PsqlBindArray is destroyed, without the caller maintaining the buffer values.

Parameters

data	buffer of binary data.
len	number of bytes of data in buffer

Exceptions

DbOperationError if data is NULL.

Definition at line 106 of file pgsql_exchange.cc.

References BINARY_FMT, formats_, isc_throw, lengths_, and values_.

◆ addTempString()

void isc::db::PsqlBindArray::addTempString ( const std::string & str )

Binds the given string to the bind array.

Prior to add the given string the vector of exchange values, it duplicated as a ConstStringPtr and saved internally. This guarantees the string remains in scope until the PsqlBindArray is destroyed, without the caller maintaining the string values.

Parameters

str	string value to add.

Todo: Eventually this could replace add(std::string&)? This would mean all bound strings would be internally copies rather than perhaps belonging to the originating object such as Host::hostname_. One the one hand it would make all strings handled one-way only, on the other hand it would mean duplicating strings where it isn't strictly necessary.

Definition at line 177 of file pgsql_exchange.cc.

References add().

Referenced by add(), add(), add(), add(), add(), addInet4(), addInet6(), addOptional(), addTimestamp(), and addTimestamp().

Here is the call graph for this function:

◆ addTimestamp() [1/2]

void isc::db::PsqlBindArray::addTimestamp ( )

Adds a timestamp of the current time to the bind array.

Precision is seconds.

Definition at line 260 of file pgsql_exchange.cc.

References addTempString(), and isc::db::PgSqlExchange::convertLocalToDatabaseTime().

Here is the call graph for this function:

◆ addTimestamp() [2/2]

void isc::db::PsqlBindArray::addTimestamp ( const boost::posix_time::ptime & timestamp )

Adds a timestamp from a ptime to the bind array.

Precision is seconds.

Parameters

timestamp Timestamp value to be sent to the database.

Exceptions

BadValue if the timestamp exceeds DatabaseConnection::MAX_DB_TIME.

Definition at line 235 of file pgsql_exchange.cc.

References addTempString(), isc::db::PgSqlExchange::convertLocalToDatabaseTime(), isc_throw, and isc::db::DatabaseConnection::MAX_DB_TIME.

Here is the call graph for this function:

◆ amNull()

bool isc::db::PsqlBindArray::amNull ( size_t index = 0 ) const

Determines if specified value is null.

Parameters

index if array holds more than one value, this index determines which column to use

Returns: true if the column is defined and is null

Definition at line 325 of file pgsql_exchange.cc.

References isc_throw, lengths_, and values_.

◆ empty()

bool isc::db::PsqlBindArray::empty ( ) const

inline

Indicates it the array is empty.

Returns: Returns true if there are no entries in the array, false otherwise.

Definition at line 186 of file pgsql_exchange.h.

References values_.

◆ getInteger()

template<typename T >

T isc::db::PsqlBindArray::getInteger ( size_t index = 0 )

inline

Returns the value as an integer.

Parameters

index if array holds more than one value, this index determines which column to use

Returns: value interpreted as specified integer type

Exceptions

OutOfRange	if the offset is too large
BadValue	if the data is null
boost::bad_lexical_cast	if value is not an integer

Definition at line 479 of file pgsql_exchange.h.

References isc_throw, and values_.

◆ getType()

int isc::db::PsqlBindArray::getType ( size_t index = 0 )

inline

Returns the column type.

Parameters

index if array holds more than one value, this index determines which column to use

Returns: the type of specified column

Exceptions

BadValue if the offset is too large

Definition at line 496 of file pgsql_exchange.h.

References formats_, and isc_throw.

◆ insert() [1/2]

void isc::db::PsqlBindArray::insert	(	const char *	value,
		size_t	index )

Inserts a string value to the bind array before the given index.

Inserts a TEXT_FMT value into the bind array before the element position given by index, using the given char* as the data source. The value is expected to be NULL terminated. The caller is responsible for ensuring that value remains in scope until the bind array has been discarded.

Parameters

value	char array containing the null-terminated text to add.
index	element position before which the string should be inserted.

Exceptions

DbOperationError	if value is NULL.
OutOfRange	if the index is beyond the end of the array.

Definition at line 47 of file pgsql_exchange.cc.

References formats_, isc_throw, lengths_, TEXT_FMT, and values_.

◆ insert() [2/2]

void isc::db::PsqlBindArray::insert	(	const std::string &	value,
		size_t	index )

Inserts a string value to the bind array before the given index.

Inserts a TEXT_FMT value into the bind array before the element position given by index, using the given given string as the data source. This creates an internally scoped copy of the string.

Parameters

value	char array containing the null-terminated text to add.
index	element position before which the string should be inserted.

Exceptions

DbOperationError	if value is NULL.
OutOfRange	if the index is beyond the end of the array.

Definition at line 58 of file pgsql_exchange.cc.

References formats_, isc_throw, lengths_, TEXT_FMT, and values_.

◆ popBack()

void isc::db::PsqlBindArray::popBack ( )

Removes the last entry in the bind array.

Exceptions

OutOfRange if array is empty.

Definition at line 71 of file pgsql_exchange.cc.

References formats_, isc_throw, lengths_, and values_.

◆ size()

size_t isc::db::PsqlBindArray::size ( ) const

inline

Fetches the number of entries in the array.

Returns: Returns size_t containing the number of entries.

Definition at line 179 of file pgsql_exchange.h.

References values_.

Referenced by isc::db::PgSqlConnection::executePreparedStatement().

◆ toText()

std::string isc::db::PsqlBindArray::toText ( ) const

Dumps the contents of the array to a string.

Returns: std::string containing the dump

Definition at line 291 of file pgsql_exchange.cc.

References formats_, lengths_, TEXT_FMT, and values_.

Member Data Documentation

◆ BINARY_FMT

const int isc::db::PsqlBindArray::BINARY_FMT = 1

static

Format value for binary data.

Definition at line 169 of file pgsql_exchange.h.

Referenced by add(), add(), addTempBinary(), and addTempBuffer().

◆ FALSE_STR

const char * isc::db::PsqlBindArray::FALSE_STR = "FALSE"

static

Constant string passed to DB for boolean false values.

Definition at line 175 of file pgsql_exchange.h.

Referenced by add().

◆ formats_

std::vector<int> isc::db::PsqlBindArray::formats_

Vector of "format" for each value.

A value of 0 means the value is text, 1 means the value is binary.

Definition at line 163 of file pgsql_exchange.h.

Referenced by add(), add(), add(), add(), addNull(), addTempBinary(), addTempBuffer(), isc::db::PgSqlConnection::executePreparedStatement(), getType(), insert(), insert(), popBack(), and toText().

◆ lengths_

std::vector<int> isc::db::PsqlBindArray::lengths_

Vector of data lengths for each value.

Definition at line 159 of file pgsql_exchange.h.

Referenced by add(), add(), add(), add(), addNull(), addTempBinary(), addTempBuffer(), amNull(), isc::db::PgSqlConnection::executePreparedStatement(), insert(), insert(), popBack(), and toText().

◆ TEXT_FMT

const int isc::db::PsqlBindArray::TEXT_FMT = 0

static

Format value for text data.

Definition at line 166 of file pgsql_exchange.h.

Referenced by add(), add(), isc::db::PgSqlExchange::dumpRow(), insert(), insert(), and toText().

◆ TRUE_STR

const char * isc::db::PsqlBindArray::TRUE_STR = "TRUE"

static

Constant string passed to DB for boolean true values.

Definition at line 172 of file pgsql_exchange.h.

Referenced by add().

◆ values_

std::vector<const char*> isc::db::PsqlBindArray::values_

Vector of pointers to the data values.

Definition at line 156 of file pgsql_exchange.h.

Referenced by add(), add(), add(), add(), addNull(), addTempBinary(), addTempBuffer(), amNull(), empty(), isc::db::PgSqlConnection::executePreparedStatement(), getInteger(), insert(), insert(), popBack(), size(), and toText().

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

Public Member Functions

Public Attributes

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ PsqlBindArray()

Member Function Documentation

◆ add() [1/11]

◆ add() [2/11]

◆ add() [3/11]

◆ add() [4/11]

◆ add() [5/11]

◆ add() [6/11]

◆ add() [7/11]

◆ add() [8/11]

◆ add() [9/11]

◆ add() [10/11]

◆ add() [11/11]

◆ addInet4()

◆ addInet6()

◆ addMax()

◆ addMin()

◆ addNull()

◆ addOptional() [1/2]

◆ addOptional() [2/2]

◆ addOptionalInet4()

◆ addOptionalInet6()

◆ addTempBinary()

◆ addTempBuffer()

◆ addTempString()

◆ addTimestamp() [1/2]

◆ addTimestamp() [2/2]

◆ amNull()

◆ empty()

◆ getInteger()

◆ getType()

◆ insert() [1/2]

◆ insert() [2/2]

◆ popBack()

◆ size()

◆ toText()

Member Data Documentation

◆ BINARY_FMT

◆ FALSE_STR

◆ formats_

◆ lengths_

◆ TEXT_FMT

◆ TRUE_STR

◆ values_