Kea: isc::config::ClientConnection Class Reference

| Kea 3.2.0-git

isc::config::ClientConnection Class Reference

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 socket to establish connections for respective Kea services. As of Kea 1.2 the servers can handle a single connection at the time. In the future, we're planning to support multiple simultaneous 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("/opt/kea/var/run/kea/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();
}
isc::config::ClientConnection::ClientConnection
ClientConnection(const asiolink::IOServicePtr &io_service)
Constructor.
Definition client_connection.cc:271
isc::config::ConstJSONFeedPtr
boost::shared_ptr< const JSONFeed > ConstJSONFeedPtr
Pointer to the const JSONFeed.
Definition json_feed.h:27
isc::config::ClientConnection::ControlCommand
Encapsulates control command.
Definition client_connection.h:86
isc::config::ClientConnection::SocketPath
Encapsulates socket path.
Definition client_connection.h:78

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.

References ClientConnection().

Referenced by ClientConnection().

Here is the call graph for this function:

## 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:

- client_connection.h
- client_connection.cc