//

// tcp.h - tcp/ip interface

//

// lecnet network library, part of the liblec library

// Copyright (c) 2018 Alec Musasa (alecmus at live dot com)

//

// Released under the MIT license. For full details see the

// file LICENSE.txt

//

#pragma once

#if defined(LECNET_EXPORTS)

#include "lecnet.h"

#else

#include <liblec/lecnet.h>

#endif

#include <string>

#include <vector>

#include <functional>

namespace liblec {

namespace lecnet {

/// <summary>

/// For TCP network connections.

/// </summary>

namespace tcp {

/// <summary>

/// Get the IP addresses of the host machine.

/// </summary>

///

/// <param name="ips">

/// The list of available IP addresses.

/// </param>

///

/// <param name="error">

/// Error information.

/// </param>

void lecnet_api get_host_ips(std::vector<std::string>& ips);

// Correct usage of the liblec::lecnet::tcp::client class is as follows:

//

// if (connect()) {

// while (connecting()) {

// // wait

// }

//

// if (connected()) {

// while (running()) {

// // use server-client connection

// }

// }

// else {

// // connection error

// }

// }

// else {

// // connection error

// }

//

// While running() is true, there are two ways of using the server-client connection

//

// 1. Blocking method (faster)

//

// auto busy_function = []() {

// // wait

// return true;

// };

//

// std::string send, received;

// if (send_data(send, received, busy_function)) {

// // use received data

// }

// else {

// // send/receive error

// }

//

// 2. Non-blocking method (slower)

//

// std::string send, received;

// unsigned long data_id;

// if (send_data_async(send, received, data_id) {

// while (sending(data_id)) {

// // wait

// }

//

// if (get_response(data_id, received)) {

// // use received data

// }

// else {

// // send/receive error

// }

// }

//

/// <summary>

/// TCP client.

/// </summary>

class lecnet_api client {

public:

struct client_params {

/// <param name="address">

/// The server address, e.g. 127.0.0.1.

/// </param>

std::string address = "127.0.0.1";

/// <param name="port">

/// The port to use. Range is 0 to 65535, e.g. 50000.

/// </param>

unsigned short port = 50001;

/// <param name="timeout_seconds">

/// The connect operation timeout in seconds, e.g. 5.

/// </param>

long timeout_seconds = 10;

/// <param name="use_ssl">

/// Whether to use SSL encryption.

/// </param>

bool use_ssl = true;

/// <param name="ca_cert_path">

/// The full path to the CA Certificate, if <see cref="use_ssl"/> is set to true.

/// </param>

std::string ca_cert_path = "ca.crt";

/// <summary>

/// The magic number for prefixing data (must match with server). Useful for

/// checking data integrity.

/// </summary>

unsigned long magic_number = 0;

};

client();

~client();

/// <summary>

/// Connect to a TCP server.

/// </summary>

///

/// <param name="params">

/// Server parameters, as defined in the client_params struct.

/// </param>

///

/// <param name="error">

/// Error information.

/// </param>

///

/// <returns>

/// Returns true if the client thread was created successfully, else false.

/// </returns>

///

/// <remarks>

/// Note that this function returns almost immediately. The actual connection

/// attempt is made on the client thread. To establish the result of the

/// connection attempt wait for <see cref="connecting"/> to return false and then

/// check the status of <see cref="connected"/>. Any error encountered in the

/// connection attempt will be written to the error parameter of

/// <see cref="connected"/>.

/// </remarks>

bool connect(const client_params& params,

std::string& error);

/// <summary>

/// Check if the client is currently trying to connect to a server.

/// </summary>

///

/// <returns>

/// Returns true if the client is in the process of trying to connect to a server,

/// else false.

/// </returns>

///

/// <remarks>

/// After true is returned by <see cref="connect"/>, wait until false is returned

/// by this function, then call <see cref="connected"/> to establish if the

/// connection was successful.

/// </remarks>

bool connecting();

/// <summary>

/// Check if the client is connected to a server.

/// </summary>

///

/// <param name="error">

/// Error information. Note: do not assume this contains any error information

/// just because the client is not connected, e.g. when this function is called

/// immediately after <see cref="connect"/> but before the actual connection is

/// established (in this case false will be returned but error will be empty).

/// If this function is called immediately after false is returned from

/// <see cref="connecting"/> and it returns false as well, then error is

/// guaranteed to have some information about why the connection attempt failed.

/// Error information is erased from memory immediately after a call to this

/// function.

/// </param>

///

/// <returns>

/// Returns true if client is connected to a server, else false.

/// </returns>

///

/// <remarks>

/// It only makes sense to call this function after a successful call to

/// <see cref="connect"/> and waiting until false is returned from

/// <see cref="connecting"/>.

/// </remarks>

bool connected(std::string& error);

/// <summary>

/// Check if the client thread is running.

/// </summary>

///

/// <returns>

/// Returns true if the client thread is running, else false.

/// </returns>

///

/// <remarks>

/// This function is useful to check if the client is still connected to the server

/// after true is returned from <see cref="connected"/>. Once false is returned

/// you can be sure the connection has been lost and a call to

/// <see cref="connect"/> is required to reestablish the connection.

/// </remarks>

bool running();

/// <summary>

/// Send data to the server (synchronously).

/// </summary>

///

/// <param name="data">

/// The data to be sent.

/// </param>

///

/// <param name="received">

/// The feedback data received from the server.

/// </param>

///

/// <param name="timeout_seconds">

/// The timeout of the send/receive operation, in seconds.

/// </param>

///

/// <param name="busy_function">

/// The function to call repeatedly during the send/receive operation (which can

/// possibly timeout depending on the server availability, load and configuration).

/// </param>

///

/// <param name="error">

/// Error information.

/// </param>

///

/// <returns>

/// Returns true if the operation is successful, else false.

/// </returns>

///

/// <remarks>

/// This is a blocking operation.

/// </remarks>

bool send_data(const std::string& data,

std::string& received,

const long& timeout_seconds,

std::function<bool()> busy_function,

std::string& error);

/// <summary>

/// Send data to the server (asyncronously).

/// </summary>

///

/// <param name="data">

/// The data to be sent.

/// </param>

///

/// <param name="timeout_seconds">

/// The timeout of the send/receive operation, in seconds.

/// </param>

///

/// <param name="data_id">

/// The unique ID of the data being sent. This will be required in the

/// subsequent calls to <see cref="sending"/> and <see cref="get_response"/>.

/// </param>

///

/// <param name="error">

/// Error information.

/// </param>

///

/// <returns>

/// Returns true if the operation is successful, else false.

/// </returns>

///

/// <remarks>

/// This is a non-blocking operation and the function returns almost immediately.

/// The actual sending will be executed asynchronously and the progress can be

/// known through <see cref="sending"/>. Note, however, that this process is

/// somewhat slower than using <see cref="send_data"/>.

/// </remarks>

bool send_data_async(const std::string& data,

const long& timeout_seconds,

unsigned long& data_id,

std::string& error);

/// <summary>

/// Check if the data is still being sent.

/// </summary>

///

/// <param name="data_id">

/// The unique ID associated with the data.

/// </param>

///

/// <returns>

/// Returns true if the data is still being sent, else false.

/// </returns>

bool sending(const unsigned long& data_id);

/// <summary>

/// Get the server response.

/// </summary>

///

/// <param name="data_id">

/// The unique ID associated with the data that was sent.

/// </param>

///

/// <param name="received">

/// The data received from the server.

/// </param>

///

/// <param name="error">

/// Error information.

/// </param>

///

/// <returns>

/// Returns true if successful, else false.

/// </returns>

///

/// <remarks>

/// A call to <see cref="send_data_async"/>, and then checking for the status of

/// <see cref="sending"/> is important for this call to make sense. After a

/// successful call to <see cref="send_data_async"/>, wait until

/// <see cref="sending"/> returns false, then call this function. After the

/// response is retrieved using this function it is immediately deleted from

/// memory. A new call to <see cref="send_data_async"/> can then be used before

/// checking for another response.

/// </remarks>

bool get_response(const unsigned long& data_id,

std::string& received,

std::string& error);

/// <summary>

/// Disconnect from server.

/// </summary>

void disconnect();

/// <summary>

/// Get the total network traffic for this client.

/// </summary>

///

/// <param name="traffic">

/// The total network traffic.

/// </param>

void traffic(liblec::lecnet::network_traffic& traffic);

private:

class impl;

impl& _d;

class client_async;

class client_async_ssl;

client(const client&) = delete;

client& operator=(const client&) = delete;

};

// Correct usage of the liblec::lecnet::tcp::server class is as follows:

//

// 1. Make a new class and inherit from liblec::lecnet::tcp::server_async and

// liblec::lecnet::tcp::server_async_ssl. In the inherited classes provide

// implementations for the log() and on_receive() virtual functions

//

// class my_server_class : public liblec::lecnet::tcp::server_async {

// public:

// my_server_class() {};

// ~my_server_class() {};

//

// void log(const std::string& time_stamp,

// const std::string& event) {

// // implementation for log member. Below is a simple example

// std::cout << time_stamp << "\t" << event << std::endl;

// }

//

// std::string on_receive(const client_address& address,

// const std::string& data_received) {

// // implementation for on_receive member. Below is a simple example

// return data_received; // simple echo server

// }

// }

//

// class my_server_class_ssl : public liblec::lecnet::tcp::server_async_ssl {

// ...

// }

//

// 2. Declare a pointer to the server base class and use it as follows

//

// liblec::lecnet::tcp::server* p_server = nullptr;

//

// bool use_ssl = ...;

//

// if (use_ssl)

// p_server = new my_server_class_ssl();

// else

// p_server = new my_server_class();

//

// 3. Proceed as follows

//

// if (p_server->start()) {

// while (p_server->starting()) {

// // wait

// }

//

// while (p_server->running()) {

// // main server loop

// }

// }

// else {

// // error

// }

//

// if (p_server) {

// delete p_server;

// p_server = nullptr;

// }

//

/// <summary>

/// Base class for TCP servers.

/// </summary>

class lecnet_api server {

public:

server() {}

virtual ~server() {}

/// <summary>

/// Client network address.

/// </summary>

typedef std::string client_address;

/// <summary>

/// Client information.

/// </summary>

struct client_info {

};

/// <summary>

/// Server parameters.

/// </summary>

struct server_params {

};

/// <summary>

/// Start server.

/// </summary>

///

/// <param name="params">

/// Server parameters, as defined in the ServerParams struct.

/// </param>

///

/// <returns>

/// Returns true if successful or if server is already running, else false.

/// </returns>

///

/// <remarks>

/// Should return immediately. Run actual server on a seperate thread.

/// </remarks>

virtual bool start(const server_params& params) = 0;

/// <summary>

/// Check if the server is currently in the process of starting.

/// </summary>

///

/// <returns>

/// Returns true if server is starting, else false.

/// </returns>

virtual bool starting() = 0;

/// <summary>

/// Check whether this server is running.

/// </summary>

///

/// <returns>

/// Returns true if the server is running, else false.

/// </returns>

virtual bool running() = 0;

/// <summary>

/// Close a connection.

/// </summary>

///

/// <param name="address">

/// The address of the client to disconnect.

/// </param>

///

/// <remarks>

/// Client can re-connect because the server is still running.

/// </remarks>

virtual void close(const client_address& address) = 0;

/// <summary>

/// Close all connections.

/// </summary>

///

/// <remarks>

/// Clients can re-connect because the server is still running.

/// </remarks>

virtual void close() = 0;

/// <summary>

/// Stop server.

/// </summary>

///

/// <returns>

/// Returns true if successful, else false.

/// </returns>

///

/// <remarks>

/// Clients cannot reconnect until the server is restarted by a fresh call to

/// <see cref="start"/>.

/// </remarks>

virtual bool stop() = 0;

/// <summary>

/// Get information of currently connected clients.

/// </summary>

///

/// <param name="clients_info">

/// The list of client information.

/// </param>

virtual void get_client_info(std::vector<client_info>& clients_info) = 0;

/// <summary>

/// Get total network traffic.

/// </summary>

///

/// <param name="traffic">

/// The total traffic.

/// </param>

virtual void traffic(liblec::lecnet::network_traffic& traffic) = 0;

/// <summary>

/// Called whenever an event is logged.

/// </summary>

///

/// <param name="time_stamp">

/// The event's timestamp.

/// </param>

///

/// <param name="event">

/// A description of the event.

/// </param>

///

/// <remarks>

/// Make sure the code is non-blocking. The function should return almost

/// immediately.

/// </remarks>

virtual void log(const std::string& time_stamp,

const std::string& event) = 0;

/// <summary>

/// Called whenever data is received.

/// </summary>

///

/// <param name="address">

/// The address of the client.

/// </param>

///

/// <param name="data_received">

/// The data received from the client.

/// </param>

///

/// <returns>

/// The data to send back to the client.

/// </returns>

///

/// <remarks>

/// The sooner this function returns the faster the asynchronous server.

/// </remarks>

virtual std::string on_receive(const client_address& address,

const std::string& data_received) = 0;

private:

server(const server&) = delete;

server& operator=(const server&) = delete;

};

/// <summary>

/// Asynchronous (event driven) TCP server class WITHOUT encryption.

/// </summary>

///

/// <remarks>

/// Based on boost asio. Uses a single thread (event driven). This class does not use

/// any encryption. As such, use it with care. Avoid using it on an unsecure network.

/// </remarks>

class lecnet_api server_async : public server {

public:

server_async();

virtual ~server_async();

/// <summary>

/// Start server.

/// </summary>

///

/// <param name="params">

/// Server parameters, as defined in the server_params struct.

/// </param>

///

/// <returns>

/// Returns true if successful or if server is already running, else false.

/// </returns>

///

/// <remarks>

/// server_cert and server_cert_key NOT used by this version.

/// </remarks>

bool start(const server_params& params);

/// <summary>

/// Check if the server is currently in the process of starting.

/// </summary>

///

/// <returns>

/// Returns true if server is starting, else false.

/// </returns>

bool starting();

/// <summary>

/// Check whether this server is running.

/// </summary>

///

/// <returns>

/// Returns true if the server is running, else false.

/// </returns>

bool running();

/// <summary>

/// Close a connection.

/// </summary>

///

/// <param name="address">

/// The address of the client to disconnect.

/// </param>

///

/// <remarks>

/// Client can re-connect because the server is still running.

/// </remarks>

void close(const client_address& address);

/// <summary>

/// Close all connections.

/// </summary>

///

/// <remarks>

/// Clients can re-connect because the server is still running.

/// </remarks>

void close();

/// <summary>

/// Stop server.

/// </summary>

///

/// <returns>

/// Returns true if successful, else false.

/// </returns>

///

/// <remarks>

/// Clients cannot reconnect until the server is restarted by a fresh call to

/// <see cref="start"/>.

/// </remarks>

bool stop();

/// <summary>

/// Get information of currently connected clients.

/// </summary>

///

/// <param name="clients_info">

/// The list of client information.

/// </param>

void get_client_info(std::vector<client_info>& client_info);

/// <summary>

/// Get total network traffic.

/// </summary>

///

/// <param name="traffic">

/// The total traffic.

/// </param>

void traffic(liblec::lecnet::network_traffic& traffic);

/// <summary>

/// Called whenever an event is logged.

/// </summary>

///

/// <param name="time_stamp">

/// The event's timestamp.

/// </param>

///

/// <param name="event">

/// A description of the event.

/// </param>

///

/// <remarks>

/// Make sure the code is non-blocking. The function should return almost

/// immediately.

/// </remarks>

virtual void log(const std::string& time_stamp,

const std::string& event) { return; };

/// <summary>

/// Called whenever data is received.

/// </summary>

///

/// <param name="address">

/// The address of the client.

/// </param>

///

/// <param name="data_received">

/// The data received from the client.

/// </param>

///

/// <returns>

/// The data to send back to the client.

/// </returns>

///

/// <remarks>

/// The sooner this function returns the faster the asynchronous server.

/// </remarks>

virtual std::string on_receive(const client_address& address,

const std::string& data_received) { return std::string(); };

private:

class impl;

impl& _d;

class _session_async;

class _server_async;

server_async(const server_async&) = delete;

server_async& operator=(const server_async&) = delete;

};

/// <summary>

/// Asynchronous (event driven) TCP server class WITH SSL encryption.

/// </summary>

///

/// <remarks>

/// Based on boost asio. Uses a single thread (event driven).

/// </remarks>

class lecnet_api server_async_ssl : public server {

public:

server_async_ssl();

virtual ~server_async_ssl();

/// <summary>

/// Start server.

/// </summary>

///

/// <param name="params">

/// Server parameters, as defined in the ServerParams struct.

/// </param>

///

/// <returns>

/// Returns true if successful or if server is already running, else false.

/// </returns>

///

/// <remarks>

/// If server_cert_key is not specified key file is sought in server_cert

/// </remarks>

bool start(const server_params& params);

/// <summary>

/// Check if the server is currently in the process of starting.

/// </summary>

///

/// <returns>

/// Returns true if server is starting, else false.

/// </returns>

bool starting();

/// <summary>

/// Check whether this server is running.

/// </summary>

///

/// <returns>

/// Returns true if the server is running, else false.

/// </returns>

bool running();

/// <summary>

/// Close a connection.

/// </summary>

///

/// <param name="address">

/// The address of the client to disconnect.

/// </param>

///

/// <remarks>

/// Client can re-connect because the server is still running.

/// </remarks>

void close(const client_address& address);

/// <summary>

/// Close all connections.

/// </summary>

///

/// <remarks>

/// Clients can re-connect because the server is still running.

/// </remarks>

void close();

/// <summary>

/// Stop server.

/// </summary>

///

/// <returns>

/// Returns true if successful, else false.

/// </returns>

///

/// <remarks>

/// Clients cannot reconnect until the server is restarted by a fresh call to

/// <see cref="start"/>.

/// </remarks>

bool stop();

/// <summary>

/// Get information of currently connected clients.

/// </summary>

///

/// <param name="clients_info">

/// The list of client information.

/// </param>

void get_client_info(std::vector<client_info>& client_info);

/// <summary>

/// Get total network traffic.

/// </summary>

///

/// <param name="traffic">

/// The total traffic.

/// </param>

void traffic(liblec::lecnet::network_traffic& traffic);

/// <summary>

/// Called whenever an event is logged.

/// </summary>

///

/// <param name="time_stamp">

/// The event's timestamp.

/// </param>

///

/// <param name="event">

/// A description of the event.

/// </param>

///

/// <remarks>

/// Make sure the code is non-blocking. The function should return almost

/// immediately.

/// </remarks>

virtual void log(const std::string& time_stamp,

const std::string& event) { return; };

/// <summary>

/// Called whenever data is received.

/// </summary>

///

/// <param name="address">

/// The address of the client.

/// </param>

///

/// <param name="data_received">

/// The data received from the client.

/// </param>

///

/// <returns>

/// The data to send back to the client.

/// </returns>

///

/// <remarks>

/// The sooner this function returns the faster the asynchronous server.

/// </remarks>

virtual std::string on_receive(const client_address& address,

const std::string& data_received) { return std::string(); };

private:

class impl;

impl& _d;

class _session_async_ssl;

class _server_async_ssl;

server_async_ssl(const server_async_ssl&) = delete;

server_async_ssl& operator=(const server_async_ssl&) = delete;

};

}

}

}