Dmitigr Pgfe  1.1beta
The modern C++ API to PostgreSQL
Public Member Functions | List of all members
Connection Class Referenceabstract

Represents a connection to the PostgreSQL server. More...

#include <dmitigr/pgfe/connection.hpp>

Public Member Functions

virtual ~Connection ()=default
 The destructor. More...
 
General observers
virtual Communication_status communication_status () const =0
 
virtual bool is_connected () const =0
 
virtual bool is_ssl_secured () const =0
 
virtual std::optional< Transaction_block_statustransaction_block_status () const =0
 
virtual bool is_transaction_block_uncommitted () const =0
 
virtual std::optional< std::chrono::system_clock::time_point > session_start_time () const noexcept=0
 
virtual const Connection_optionsoptions () const noexcept=0
 
virtual std::optional< std::int_fast32_t > server_pid () const =0
 
Communication
virtual void connect_async ()=0
 Establishing the connection to the server without blocking on I/O. More...
 
virtual void connect (std::chrono::microseconds timeout=std::chrono::microseconds{-1})=0
 Attempts to connect to the server. More...
 
virtual void disconnect ()=0
 Attempts to disconnect from the server. More...
 
virtual Socket_readiness wait_socket_readiness (Socket_readiness mask, std::chrono::microseconds timeout=std::chrono::microseconds{-1}) const =0
 Waits the readiness of the connection socket if it is unready. More...
 
virtual Socket_readiness socket_readiness (Socket_readiness mask) const =0
 Polls the readiness of the connection socket. More...
 
Messages
virtual void collect_server_messages ()=0
 Collects and queue the messages of all kinds which was sent by the server. More...
 
virtual bool is_server_message_available () const noexcept=0
 
Signals
virtual bool is_signal_available () const noexcept=0
 
virtual const Noticenotice () const noexcept=0
 
virtual std::unique_ptr< Noticepop_notice ()=0
 
virtual void dismiss_notice ()=0
 Dismissing an available Notice. More...
 
virtual const Notificationnotification () const noexcept=0
 
virtual std::unique_ptr< Notificationpop_notification ()=0
 
virtual void dismiss_notification ()=0
 Dismissing an available Notification. More...
 
virtual void set_notice_handler (const std::function< void(std::unique_ptr< Notice > &&)> &handler)=0
 Sets the handler for notices. By default, notice handler just prints notices to the standard error and never throws. More...
 
virtual std::function< void(std::unique_ptr< Notice > &&)> notice_handler () const =0
 
virtual void set_notification_handler (const std::function< void(std::unique_ptr< Notification > &&)> &handler)=0
 Sets the handler for notifications. By default, notification handler isn't set. More...
 
virtual std::function< void(std::unique_ptr< Notification > &&)> notification_handler () const =0
 
virtual void handle_signals ()=0
 Call signals handlers. More...
 
Responses
virtual bool is_awaiting_response () const noexcept=0
 
virtual void wait_response (std::chrono::microseconds timeout=std::chrono::microseconds{-1})=0
 Waits a some kind of Response if it is unavailable and awaited. More...
 
virtual void wait_response_throw (std::chrono::microseconds timeout=std::chrono::microseconds{-1})=0
 Similar to wait_response(), but throws Server_exception if (error() != nullptr) after awaiting. More...
 
virtual void wait_last_response (std::chrono::microseconds timeout=std::chrono::microseconds{-1})=0
 Waits for the Completion or the Error. More...
 
virtual void wait_last_response_throw (std::chrono::microseconds timeout=std::chrono::microseconds{-1})=0
 Similar to wait_last_response(), but throws Server_exception if (error() != nullptr) after awaiting. More...
 
virtual bool is_response_available () const noexcept=0
 
virtual void dismiss_response ()=0
 Dismissing the last available Response. More...
 
virtual const Errorerror () const noexcept=0
 
virtual std::unique_ptr< Errorrelease_error ()=0
 
virtual const Rowrow () const noexcept=0
 
virtual std::unique_ptr< Rowrelease_row ()=0
 
virtual const Completioncompletion () const noexcept=0
 
virtual std::unique_ptr< Completionrelease_completion ()=0
 
virtual Prepared_statementprepared_statement () const =0
 
virtual Prepared_statementprepared_statement (const std::string &name) const =0
 
Requests
virtual bool is_ready_for_async_request () const =0
 
virtual bool is_ready_for_request () const =0
 
virtual void perform_async (const std::string &queries)=0
 Submits SQL queri(-es) to the server. More...
 
virtual void perform (const std::string &queries)=0
 Similar to perform_async(), but waits for the first Response of some kind and throws Server_exception if awaited Response is an Error. More...
 
virtual void prepare_statement_async (const Sql_string *statement, const std::string &name={})=0
 Submits a request to a server to prepare the statement from preparsed SQL string. More...
 
virtual void prepare_statement_async (const std::string &statement, const std::string &name={})=0
 
virtual Prepared_statementprepare_statement (const Sql_string *statement, const std::string &name={})=0
 
virtual Prepared_statementprepare_statement (const std::string &statement, const std::string &name={})=0
 
virtual void describe_prepared_statement_async (const std::string &name)=0
 Submits a request to the server to describe prepared statement. More...
 
virtual Prepared_statementdescribe_prepared_statement (const std::string &name)=0
 
virtual void unprepare_statement_async (const std::string &name)=0
 Submits a request to the server to close the prepared statement. More...
 
virtual void unprepare_statement (const std::string &name)=0
 
template<typename ... Types>
void execute (const Sql_string *const statement, Types &&... parameters)
 Submits requests to the server to prepare and execute the unnamed statement from the preparsed SQL string, and waits the response. More...
 
template<typename ... Types>
void execute (const std::string &statement, Types &&... parameters)
 
virtual void set_result_format (Data_format format)=0
 Sets the default data format of the result of prepared statement execution. More...
 
virtual Data_format result_format () const noexcept=0
 
Utilities
virtual void for_each (const std::function< void(const Row *)> &body)=0
 For each awaited row calls body(row()) just after retrieving. More...
 
virtual void for_each (const std::function< void(std::unique_ptr< Row > &&)> &body)=0
 
virtual void complete (const std::function< void(const Completion *)> &body={})=0
 Waits for the Completion or the Error and calls body(completion()) if the body is given. More...
 
virtual void complete (const std::function< void(std::unique_ptr< Completion > &&)> &body)=0
 
virtual std::string to_quoted_literal (const std::string &literal) const =0
 Quotes the given string to be used as a literal in an SQL query. More...
 
virtual std::string to_quoted_identifier (const std::string &identifier) const =0
 Quotes the given string to be used as an identifier in a SQL query. More...
 
virtual std::unique_ptr< Datato_hex_data (const Data *binary_data) const =0
 Encodes binary data into a textual representation to be used in an SQL query. More...
 
virtual std::string to_hex_string (const Data *binary_data) const =0
 Similar to to_hex_data(const Data*). More...
 

Constructors

virtual std::unique_ptr< Connectionclone () const =0
 
static DMITIGR_PGFE_API std::unique_ptr< Connection > APIENTRY make (const Connection_options *options=nullptr)
 

Detailed Description

Represents a connection to the PostgreSQL server.

Constructor & Destructor Documentation

◆ ~Connection()

virtual ~Connection ( )
virtualdefault

The destructor.

Member Function Documentation

◆ clone()

virtual std::unique_ptr<Connection> clone ( ) const
pure virtual
Returns
The copy of this instance.
Remarks
The communication status of a copy will be Communication_status::disconnected.

◆ collect_server_messages()

virtual void collect_server_messages ( )
pure virtual

Collects and queue the messages of all kinds which was sent by the server.

Requires
(is_connected())
Effects
Possible (is_server_message_available()).
Exception safety guarantee
Basic.

◆ communication_status()

virtual Communication_status communication_status ( ) const
pure virtual
Returns
The communication status.

◆ complete() [1/2]

virtual void complete ( const std::function< void(const Completion *)> &  body = {})
pure virtual

Waits for the Completion or the Error and calls body(completion()) if the body is given.

Parameters
body- a callback function.
Exception safety guarantee
Basic.

◆ complete() [2/2]

virtual void complete ( const std::function< void(std::unique_ptr< Completion > &&)> &  body)
pure virtual

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Remarks
Calls body(release_completion()).

◆ completion()

virtual const Completion* completion ( ) const
pure virtualnoexcept
Returns
The pointer to the instance of type Completion if available, or nullptr otherwise.
Remarks
This method is semantically similar to release_completion() but allows the implementation to reduce memory allocations needed for the each retrieved row.
This method is semantically similar to release_completion() but allows the implementation to avoid extra memory allocation for the retrieved completion response.
The object pointed by the returned value is owned by this instance.
See also
release_completion()

◆ connect()

virtual void connect ( std::chrono::microseconds  timeout = std::chrono::microseconds{-1})
pure virtual

Attempts to connect to the server.

Parameters
timeout- similar to wait_socket_readiness().
Effects
(communication_status() == Communication_status::failure || communication_status() == Communication_status::connected)
Requires
(timeout >= -1)
Exceptions
Client_exceptionwith code of Client_errc::timed_out if the (connection_status() == Communication_status::connected) will not evaluates to true within the specified timeout.
Exception safety guarantee
Basic.
See also
connect_async().

◆ connect_async()

virtual void connect_async ( )
pure virtual

Establishing the connection to the server without blocking on I/O.

This function should be called repeatedly. Until communication_status() becomes Communication_status::connected or Communication_status::failure loop thus: if communication_status() returned Communication_status::establishment_reading, wait until the socket is ready to read, then call connect_async() again; if communication_status() returned Communication_status::establishment_writing, wait until the socket ready to write, then call connect_async() again. To determine the socket readiness use socket_readiness() function.

Effects
Possible change of the returned value of communication_status().
Exception safety guarantee
Basic.
Remarks
If called when (communication_status() == Communication_status::failure), it will dismiss all unhandled server messages!
See also
connect(), communication_status(), socket_readiness().

◆ describe_prepared_statement()

virtual Prepared_statement* describe_prepared_statement ( const std::string &  name)
pure virtual

◆ describe_prepared_statement_async()

virtual void describe_prepared_statement_async ( const std::string &  name)
pure virtual

Submits a request to the server to describe prepared statement.

Awaiting responses
Prepared_statement
Parameters
name- the name of the prepared statement.
Effects
  • (is_awaiting_response()) - just after successful request submission;
  • (prepared_statement(name) != nullptr && prepared_statement(name)->is_described()) - just after successful response collection.
Requires
(is_ready_for_async_request())
Exception safety guarantee
Strong.
See also
describe_prepared_statement().

◆ disconnect()

virtual void disconnect ( )
pure virtual

Attempts to disconnect from the server.

Effects
(communication_status() == Communication_status::disconnected)
Exception safety guarantee
Strong.

◆ dismiss_notice()

virtual void dismiss_notice ( )
pure virtual

Dismissing an available Notice.

Effects
Same as for pop_notice().
Exception safety guarantee
Strong.
Remarks
It's more efficiently than pop_notice().

◆ dismiss_notification()

virtual void dismiss_notification ( )
pure virtual

Dismissing an available Notification.

Effects
Same as pop_notification().
Exception safety guarantee
Strong.
Remarks
It's more efficiently than pop_notification().

◆ dismiss_response()

virtual void dismiss_response ( )
pure virtual

Dismissing the last available Response.

Exception safety guarantee
Strong.
Remarks
It's more efficienlty than release_error(), release_row() or release_completion().

◆ error()

virtual const Error* error ( ) const
pure virtualnoexcept
Returns
The pointer to the instance of type Error if available, or nullptr otherwise.
Remarks
This method is semantically similar to release_error() but allows the implementation to avoid extra memory allocation for the retrieved error response.
The object pointed by the returned value is owned by this instance.
See also
release_error().

◆ execute() [1/2]

void execute ( const Sql_string *const  statement,
Types &&...  parameters 
)
inline

Submits requests to the server to prepare and execute the unnamed statement from the preparsed SQL string, and waits the response.

Awaited responses
Similar to perform_async().
Parameters
statement- the preparsed statement to execute;
parameters- parameters to bind with the parameterized statement.
Requires
(statement && !statement->has_missing_parameters() && is_ready_for_request())
Exception safety guarantee
Basic.
Remarks
See remarks of prepare_statement().

◆ execute() [2/2]

void execute ( const std::string &  statement,
Types &&...  parameters 
)
inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Remarks
The statement will be send as-is without any preparsing.

◆ for_each() [1/2]

virtual void for_each ( const std::function< void(const Row *)> &  body)
pure virtual

For each awaited row calls body(row()) just after retrieving.

Parameters
body- a callback function.
Requires
(body)
Exception safety guarantee
Basic.

◆ for_each() [2/2]

virtual void for_each ( const std::function< void(std::unique_ptr< Row > &&)> &  body)
pure virtual

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Remarks
Calls body(release_row()).

◆ handle_signals()

virtual void handle_signals ( )
pure virtual

Call signals handlers.

Exception safety guarantee
Basic.

◆ is_awaiting_response()

virtual bool is_awaiting_response ( ) const
pure virtualnoexcept
Returns
true if some kind of Response is awaited, or false otherwise.
See also
wait_response().

◆ is_connected()

virtual bool is_connected ( ) const
pure virtual
Returns
true if the communication status is Communication_status::connected.

◆ is_ready_for_async_request()

virtual bool is_ready_for_async_request ( ) const
pure virtual
Returns
true if the instance is ready to issue request to a server in non-blocking manner, or false otherwise.
See also
is_ready_for_request().

◆ is_ready_for_request()

virtual bool is_ready_for_request ( ) const
pure virtual
Returns
true if the instance is ready to issue request to a server, or false otherwise.
See also
is_awaiting_response().

◆ is_response_available()

virtual bool is_response_available ( ) const
pure virtualnoexcept

◆ is_server_message_available()

virtual bool is_server_message_available ( ) const
pure virtualnoexcept

◆ is_signal_available()

virtual bool is_signal_available ( ) const
pure virtualnoexcept
Returns
(notice() || notification())

◆ is_ssl_secured()

virtual bool is_ssl_secured ( ) const
pure virtual
Returns
true if the connection secured by SSL, or false otherwise.

◆ is_transaction_block_uncommitted()

virtual bool is_transaction_block_uncommitted ( ) const
pure virtual
Returns
true if transaction block status is Transaction_block_status::uncommitted, or false otherwise.

◆ make()

static DMITIGR_PGFE_API std::unique_ptr<Connection> APIENTRY make ( const Connection_options options = nullptr)
static
Returns
The new instance of type Connection_options.
Parameters
options- connection options. The value of nullptr means default connection options.

◆ notice()

virtual const Notice* notice ( ) const
pure virtualnoexcept
Returns
The pointer to the instance of type Notice if available, or nullptr otherwise.
Remarks
The object pointed by the returned value is owned by this instance.
See also
pop_notice().

◆ notice_handler()

virtual std::function<void(std::unique_ptr<Notice>&&)> notice_handler ( ) const
pure virtual
Returns
The current notice handler.

◆ notification()

virtual const Notification* notification ( ) const
pure virtualnoexcept
Returns
The pointer to the instance of type Notification if available, or nullptr otherwise.
Remarks
The object pointed by the returned value is owned by this instance.
See also
pop_notification().

◆ notification_handler()

virtual std::function<void(std::unique_ptr<Notification>&&)> notification_handler ( ) const
pure virtual
Returns
The current notification handler.

◆ options()

virtual const Connection_options* options ( ) const
pure virtualnoexcept
Returns
The connection options of this instance.

◆ perform()

virtual void perform ( const std::string &  queries)
pure virtual

Similar to perform_async(), but waits for the first Response of some kind and throws Server_exception if awaited Response is an Error.

Requires
(is_ready_for_request())
Exception safety guarantee
Basic.

◆ perform_async()

virtual void perform_async ( const std::string &  queries)
pure virtual

Submits SQL queri(-es) to the server.

Awaited responses
  • if the query provokes an error: Error;
  • if the query does not provokes producing rows: Completion;
  • if the query provokes producing rows: the set of Row (if any), and finally the Completion.
Parameters
queries- a string, containing the SQL queri(-es). Adjacent queries must be separated by a semicolon.
Effects
(is_awaiting_response())
Requires
(is_ready_for_async_request())
Exception safety guarantee
Strong.
Remarks
Each query specified in queries will provoke producing the separate flow of responses. All queries are executed in one transaction, therefore if one of them provokes an error, then the transaction will be aborted, the queries which were not yet executed will be rejected, and the Error will be the very last of responses.
See also
prepare_statement_async().

◆ pop_notice()

virtual std::unique_ptr<Notice> pop_notice ( )
pure virtual
Returns
The released instance of type Notice if available, or nullptr otherwise.
Effects
notice() returns a pointer to the next instance in the queue, or nullptr if the queue is empty.
Exception safety guarantee
Strong.
Remarks
caller should always rely upon assumption that pointer obtained by notice() becomes invalid after calling this function.
See also
notice().

◆ pop_notification()

virtual std::unique_ptr<Notification> pop_notification ( )
pure virtual
Returns
The released instance of type Notification (with ownership transfer) if available, or nullptr otherwise.
Effects
notification() returns a pointer to the next instance in the queue, or nullptr if the queue is empty.
Exception safety guarantee
Strong.
Remarks
caller should always rely upon assumption that pointer obtained by notification() becomes invalid after calling this function.
See also
notification().

◆ prepare_statement() [1/2]

virtual Prepared_statement* prepare_statement ( const Sql_string statement,
const std::string &  name = {} 
)
pure virtual
Returns
(prepare_statement_async(), wait_response_throw(), prepared_statement())
Requires
(statement && !statement->has_missing_parameters() && is_ready_for_request())
Exception safety guarantee
Basic.
Remarks
See remarks of prepare_statement_async().
See also
unprepare_statement().

◆ prepare_statement() [2/2]

virtual Prepared_statement* prepare_statement ( const std::string &  statement,
const std::string &  name = {} 
)
pure virtual

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Remarks
The statement will be send as-is without any preparsing.

◆ prepare_statement_async() [1/2]

virtual void prepare_statement_async ( const Sql_string statement,
const std::string &  name = {} 
)
pure virtual

Submits a request to a server to prepare the statement from preparsed SQL string.

Awaited responses
Prepared_statement
Parameters
statement- the preparsed statement to prepare;
name- the name of the statement to prepare.
Effects
  • (is_awaiting_response()) - just after successful request submission;
  • (prepared_statement(name) != nullptr && prepared_statement(name)->is_preparsed()) - just after successful response collection.
Requires
(statement && !statement->has_missing_parameters() && is_ready_for_async_request())
Exception safety guarantee
Strong.
Remarks
It is strongly recommended to specify the types of the parameters by using explicit type casts to avoid ambiguities or type mismatch mistakes. For example:
-- Force to use generate_series(int, int) overload.
SELECT generate_series($1::int, $2::int);
This forces parameters $1 and $2 to be treated as of type integer and thus the corresponding overload will be used in this case.
See also
unprepare_statement_async().

◆ prepare_statement_async() [2/2]

virtual void prepare_statement_async ( const std::string &  statement,
const std::string &  name = {} 
)
pure virtual

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Remarks
The statement will be send as-is without any preparsing.

◆ prepared_statement() [1/2]

virtual Prepared_statement* prepared_statement ( ) const
pure virtual
Returns
The pointer to the instance of type Prepared_statement if available, or nullptr otherwise.
Remarks
The object pointed by the returned value is owned by this instance.

◆ prepared_statement() [2/2]

virtual Prepared_statement* prepared_statement ( const std::string &  name) const
pure virtual
Returns
The prepared statement by its name, or nullptr if prepared statement with the given name is unknown by Connection (this case is possible if the statement is prepared by using SQL command PREPARE. Such a statement must be described first).
Parameters
name- the name of the prepared statement.
Remarks
The object pointed by the returned value is owned by this instance.
See also
describe_prepared_statement(), describe_prepared_statement_async().

◆ release_completion()

virtual std::unique_ptr<Completion> release_completion ( )
pure virtual
Returns
The released instance of type Completion if available, or nullptr otherwise.
Exception safety guarantee
Strong.
Remarks
There is no necessity to handle Completion explicitly. It will be dismissed automatically when appropriate. Caller should always rely upon assumption that pointer obtained by completion() becomes invalid after calling this function.

◆ release_error()

virtual std::unique_ptr<Error> release_error ( )
pure virtual
Returns
The released instance of type Error if available, or nullptr otherwise.
Effects
(error() == nullptr)
Exception safety guarantee
Strong.
Remarks
Caller should always rely upon assumption that pointer obtained by error() becomes invalid after calling this function.
See also
dismiss_response(), error().

◆ release_row()

virtual std::unique_ptr<Row> release_row ( )
pure virtual
Returns
The released instance of type Row if available, or nullptr otherwise.
Exception safety guarantee
Strong.
Effects
(row() == nullptr)
Remarks
Each Row must be handled or dismissed explicitly. Caller should always rely upon assumption that pointer obtained by row() becomes invalid after calling this function.
See also
dismiss_response(), row().

◆ result_format()

virtual Data_format result_format ( ) const
pure virtualnoexcept
Returns
The default data format of the result of prepared statement execution.

◆ row()

virtual const Row* row ( ) const
pure virtualnoexcept
Returns
The pointer to the instance of type Row if available, or nullptr otherwise.
Remarks
This method is semantically similar to release_row() but allows the implementation to avoid extra memory allocation for the each retrieved row.
The object pointed by the returned value is owned by this instance.
See also
release_row()

◆ server_pid()

virtual std::optional<std::int_fast32_t> server_pid ( ) const
pure virtual
Returns
The last reported identifier of the server process if available.
See also
Notification::server_pid().

◆ session_start_time()

virtual std::optional<std::chrono::system_clock::time_point> session_start_time ( ) const
pure virtualnoexcept
Returns
The last registered time point when is_connected() started to return true, or std::nullopt if the session wasn't started.

◆ set_notice_handler()

virtual void set_notice_handler ( const std::function< void(std::unique_ptr< Notice > &&)> &  handler)
pure virtual

Sets the handler for notices. By default, notice handler just prints notices to the standard error and never throws.

Parameters
handler- the handler to set.
Exception safety guarantee
Strong.
See also
handle_signals().

◆ set_notification_handler()

virtual void set_notification_handler ( const std::function< void(std::unique_ptr< Notification > &&)> &  handler)
pure virtual

Sets the handler for notifications. By default, notification handler isn't set.

Parameters
handler- the handler to set.
Exception safety guarantee
Strong.
See also
handle_signals().

◆ set_result_format()

virtual void set_result_format ( Data_format  format)
pure virtual

Sets the default data format of the result of prepared statement execution.

Parameters
format- the default data result format to set.
Exception safety guarantee
Strong.

◆ socket_readiness()

virtual Socket_readiness socket_readiness ( Socket_readiness  mask) const
pure virtual

Polls the readiness of the connection socket.

Parameters
mask- similar to wait_socket_readiness().
Returns
wait_socket_readiness(mask, std::chrono::microseconds{});
See also
wait_socket_readiness().

◆ to_hex_data()

virtual std::unique_ptr<Data> to_hex_data ( const Data binary_data) const
pure virtual

Encodes binary data into a textual representation to be used in an SQL query.

Parameters
binary_data- the Data of the binary format to escape.
Returns
The encoded string in the hex format.
Requires
is_connected() && binary_data && (binary_data->format() == Data_format::binary)
Remarks
Using of parameterized prepared statement should be considered as the better alternative to including the encoded binary data into a query. Since the result depends on session properties (such as character encoding), using it with connections with other session properties is not correct.
See also
Prepared_statement.

◆ to_hex_string()

virtual std::string to_hex_string ( const Data binary_data) const
pure virtual

Similar to to_hex_data(const Data*).

◆ to_quoted_identifier()

virtual std::string to_quoted_identifier ( const std::string &  identifier) const
pure virtual

Quotes the given string to be used as an identifier in a SQL query.

Parameters
identifier- the identifier to quote.
Returns
The suitably quoted identifier.
Requires
(is_connected())
Remarks
Since the result depends on session properties (such as character encoding), using it with connections with other session properties is not correct.
See also
Prepared_statement.

◆ to_quoted_literal()

virtual std::string to_quoted_literal ( const std::string &  literal) const
pure virtual

Quotes the given string to be used as a literal in an SQL query.

Returns
The suitably quoted literal.
Parameters
literal- the literal to quote.
Requires
(is_connected())
Remarks
Using of parameterized prepared statement should be considered as the better alternative to including the escaped data into a query. Since the result depends on session properties (such as character encoding), using it with connections with other session properties is not correct.
See also
Prepared_statement.

◆ transaction_block_status()

virtual std::optional<Transaction_block_status> transaction_block_status ( ) const
pure virtual
Returns
The last reported server transaction block status if available.

◆ unprepare_statement()

virtual void unprepare_statement ( const std::string &  name)
pure virtual

◆ unprepare_statement_async()

virtual void unprepare_statement_async ( const std::string &  name)
pure virtual

Submits a request to the server to close the prepared statement.

Awaited responses
Completion
Parameters
name- the name of the prepared statement.
Effects
  • (is_awaiting_response()) - just after successful request submission.
  • (prepared_statement(name) == nullptr) - just after successful response collection.
Requires
(is_ready_for_async_request() && !name.empty())
Exception safety guarantee
Strong.
Remarks
It's not possible to unprepare unnamed prepared statement at the moment.
See also
unprepare_statement().

◆ wait_last_response()

virtual void wait_last_response ( std::chrono::microseconds  timeout = std::chrono::microseconds{-1})
pure virtual

Waits for the Completion or the Error.

Parameters
timeout- similar to wait_socket_readiness().
Requires
(timeout >= -1 && is_connected())
Exception safety guarantee
Basic.

◆ wait_last_response_throw()

virtual void wait_last_response_throw ( std::chrono::microseconds  timeout = std::chrono::microseconds{-1})
pure virtual

Similar to wait_last_response(), but throws Server_exception if (error() != nullptr) after awaiting.

◆ wait_response()

virtual void wait_response ( std::chrono::microseconds  timeout = std::chrono::microseconds{-1})
pure virtual

Waits a some kind of Response if it is unavailable and awaited.

Parameters
timeout- similar to wait_socket_readiness().
Requires
(timeout >= -1 && is_connected() && is_awaiting_response())
Exception safety guarantee
Basic.
Remarks
All signals retrieved upon waiting the response will be handled by signals handlers being set.
See also
is_response_available().

◆ wait_response_throw()

virtual void wait_response_throw ( std::chrono::microseconds  timeout = std::chrono::microseconds{-1})
pure virtual

Similar to wait_response(), but throws Server_exception if (error() != nullptr) after awaiting.

◆ wait_socket_readiness()

virtual Socket_readiness wait_socket_readiness ( Socket_readiness  mask,
std::chrono::microseconds  timeout = std::chrono::microseconds{-1} 
) const
pure virtual

Waits the readiness of the connection socket if it is unready.

Returns
The bit mask indicating actually readiness of the connection socket according to the requested bit mask.
Parameters
mask- the bit mask specifying the requested readiness of the connection socket;
timeout- maximum amount of time to wait before return. A special value of -1 denotes "eternity".
Requires
`((timeout >= -1) && (communication_status() != Communication_status::failure) && (communication_status() != Communication_status::disconnected))`

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