Represents client side connection over the unix domain socket. More...

#include <client_connection.h>

Classes
struct	ControlCommand
	Encapsulates control command. More...

struct	SocketPath
	Encapsulates socket path. More...

struct	Timeout
	Encapsulates timeout value. More...

Structures used for strong typing.
typedef std::function< void(const boost::system::error_code &ec, const ConstJSONFeedPtr &feed)>	Handler
	Type of the callback invoked when the communication with the server is complete or an error has occurred.

	ClientConnection (const asiolink::IOServicePtr &io_service)
	Constructor.

void	start (const SocketPath &socket_path, const ControlCommand &command, Handler handler, const Timeout &timeout=Timeout(5000))
	Starts asynchronous transaction with a remote endpoint.

Detailed Description

Represents client side connection over the unix domain socket.

This class represents a client side connection between the controlling client and the server exposing control API over a unix domain socket. In particular, this class is used by the Kea Control Agent to establish connections with respective Kea services to forward received commands. As of Kea 1.2 the servers can handle a single connection at the time. In the future, we're planning to support multiple simulatenous connections. In this case, each connection will be handled by a unique instance of the ClientConnection class.

The ClientConnection supports asynchronous connections. A caller creates an instance of the ClientConnection and calls ClientConnection::start to start asynchronous communication with a remote server. The caller provides a pointer to the callback function (handler) which will be called when the communication with the server completes, i.e. the command is sent to the server and the response from the server is received. If an error occurs, the callback is invoked with an error code indicating a reason for the failure.

The documentation of the ClientConnection::start explains the sequence of operations performed by this class.

Even though the ClientConnection is asynchronous in nature, it can also be used in cases requiring synchronous communication. As it has been already mentioned, the servers in Kea 1.2 do not support multiple concurrent connections. The following pseudo code demonstrates how to perform synchronous transaction using this class.

IOService io_service;
ClientConnection conn(io_service);
bool cb_invoked = false;
conn.start(ClientConnection::SocketPath("/tmp/kea.sock"),
           ClientConnection::ControlCommand(command),
           [this, &cb_invoked](const boost::system::error_code& ec,
                  const ConstJSONFeedPtr& feed) {
               cb_invoked = true;
               if (ec) {
                   ... handle error here ...
               } else {
                   ... use feed to retrieve the response ...
               }
           }
);
while (!cb_invoked) {
    io_service.runOne();
}

Definition at line 70 of file client_connection.h.

Member Typedef Documentation

◆ Handler

typedef std::function<void(const boost::system::error_code& ec, const ConstJSONFeedPtr& feed)> isc::config::ClientConnection::Handler

Type of the callback invoked when the communication with the server is complete or an error has occurred.

Definition at line 106 of file client_connection.h.

Constructor & Destructor Documentation

◆ ClientConnection()

isc::config::ClientConnection::ClientConnection ( const asiolink::IOServicePtr & io_service )

explicit

Constructor.

Parameters

io_service Reference to the IO service.

Definition at line 271 of file client_connection.cc.

Member Function Documentation

◆ start()

void isc::config::ClientConnection::start	(	const SocketPath &	socket_path,
		const ControlCommand &	command,
		ClientConnection::Handler	handler,
		const Timeout &	timeout = `Timeout(5000)`
	)

Starts asynchronous transaction with a remote endpoint.

Starts asynchronous connection with the remote endpoint. If the connection is successful, the control command is asynchronously sent to the remote endpoint. When the entire command has been sent, the response is read asynchronously, possibly in multiple chunks.

The timeout is specified in milliseconds. The corresponding timer measures the connection idle time. If the transaction is progressing, the timer is updated accordingly. If the connection idle time is longer than the timeout value the connection is closed and the callback is called with the error code of boost::asio::error::timed_out.

In other cases, the callback is called with the error code returned by the boost asynchronous operations. If the transaction is successful the 'success' status is indicated with the error code. In addition the instance of the JSONFeed is returned to the caller. It can be used to retrieve parsed response from the server. Note that the response may still be malformed, even if no error is signalled in the handler. The JSONFeed::toElement will return a parsing error if the JSON appears to be malformed.

Parameters

socket_path	Path to the socket description that the server is bound to.
command	Control command to be sent to the server.
handler	Pointer to the user supplied callback function which should be invoked when transaction completes or when an error has occurred during the transaction.
timeout	Connection timeout in milliseconds.

Definition at line 276 of file client_connection.cc.

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

Classes