Connection.h

Go to the documentation of this file.

/*--------------------------------------------------------------------------------------------
Copyright (c) 2019, NDEVR LLC
tyler.parke@ndevr.org
  __    __   ____     _____ __     __  _______
 |  \  |  | |  __ \  |  ___|\ \   / / |   __  \
 |   \ |  | | |  \ \ | |___  \ \ / /  |  |__)  |
 |  . \|  | | |__/ / | |___   \ V /   |   _   /
 |  |\    |_|_____/__|_____|___\_/____|  | \  \
 |__| \__________________________________|  \__\
 
Subject to the terms of the Enterprise+ Agreement, NDEVR hereby grants 
Licensee a limited, non-exclusive, non-transferable, royalty-free license 
(without the right to sublicense) to use the API solely for the purpose of 
Licensee's internal development efforts to develop applications for which 
the API was provided.
 
The above copyright notice and this permission notice shall be included in all 
copies or substantial portions of the Software.
 
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
 
Library: Hardware
File: Connection
Included in API: True
Author(s): Tyler Parke
 *-----------------------------------------------------------------------------------------**/
#pragma once
#include "DLLInfo.h"
#include <NDEVR/SoftwareService.h>
#include <NDEVR/Device.h>
#include <NDEVR/String.h>
#include <NDEVR/TimeSpan.h>
#include <QObject>
class QAbstractSocket;
class QTcpSocket;
class QUdpSocket;
class QSerialPortInfo;
class QSerialPort;
class QBluetoothSocket;
class QBluetoothServiceInfo;
class QBluetoothDeviceInfo;
class QBluetoothAddress;
class QIODevice;
namespace NDEVR
{
    class Log;
    class SocketIODriver;
    /**--------------------------------------------------------------------------------------------------
    \brief Describes the state of the connection.
    **/
    enum class ConnectionState
    {
          e_no_connection
        , e_valid_connection
        , e_awaiting_response
        , e_attempting_connection
        , e_invalid_response
        , e_no_response
        , e_no_services
        , e_access_to_port_denied
        , e_network_error
        , e_resetting
        , e_initializing
        , e_connection_timeout
        , e_invalid_connection
    };
    /**--------------------------------------------------------------------------------------------------
    \brief Describes how to open a connection
    **/
    enum class ConnectionOpenType
    {
        e_not_open = 0x0000,
        e_read_only = 0x0001,
        e_write_only = 0x0002,
        e_read_write = e_read_only | e_write_only,
        e_append = 0x0004,
        e_truncate = 0x0008,
        e_text = 0x0010,
        e_unbuffered = 0x0020,
        e_new_only = 0x0040,
        e_existing_only = 0x0080
    };
    enum class RawConnectionLoggingMode
    {
          e_binary_logging
        , e_ascii_logging
    };
    /**--------------------------------------------------------------------------------------------------
    \brief A structure designed to store information about a specific Connection
    **/
    struct ConnectionInfo
    {
        TranslatedString name;
        String type;
        String address;
        ConnectionOpenType connect_mode = ConnectionOpenType::e_read_write;
        TimeSpan max_timeout = TimeSpan(5.0);
        ProgressInfo* log = nullptr;
        String thread_id;
 
        String id() const
        {
            return type + "|" + address;
        }
        void autoSetName()
        {
            name = TranslatedString(id());
        }
        HARDWARE_API void setID(const String& id);
        bool operator!=(const ConnectionInfo& other) const
        {
            return type != other.type
                || address != other.address
                || max_timeout != other.max_timeout
                || connect_mode != other.connect_mode;
        }
    };
    /**--------------------------------------------------------------------------------------------------
    \brief A category represents the type of connection. For example Bluetooth, Serial Port, TCP, etc
    **/
    struct ConnectionCategory
    {
        TranslatedString name;
        String id;
        String icon;
    };
    /**--------------------------------------------------------------------------------------------------
    \brief Describes settings for performing a Connection search.
    **/
    struct ConnectionSearchParamaters
    {
        enum SearchReturn
        {
              e_continue_searching
            , e_stop_searching
        };
        Buffer<ConnectionCategory> allowed_categories;
        std::function<SearchReturn(const ConnectionInfo&)> on_device_found = nullptr;
        std::function<SearchReturn(const ConnectionInfo&)> on_service_found = nullptr;
        ProgressInfo* log = nullptr;
        TimeSpan timeout = TimeSpan(30.0);
    };
    /**--------------------------------------------------------------------------------------------------
    \brief Provides the unseen backend logic for setting up, tearing down, and sending data over a specific
        type of connection.
    **/
    class HARDWARE_API ConnectionBackend : public QObject
    {
        Q_OBJECT
    public:
        ConnectionBackend(ProgressInfo* log);
        virtual uint04 peek(char* s, uint04 size = Constant<uint04>::Max) const = 0;
        virtual uint04 rx(char* s, uint04 max_size = Constant<uint04>::Max) = 0;
        virtual void tx(const String& command) = 0;
        virtual bool open(const ConnectionInfo& request) = 0;
        virtual void close() = 0;
        virtual bool isOpen() const = 0;
        virtual bool waitForReadyRead(const TimeSpan& span) = 0;
        virtual TranslatedString lastError() const = 0;
        virtual uint04 bytesAvailable() const = 0;
        virtual String threadID() const { return String(); };
    signals:
        void dataAvailableSignal();
        void connectionStateChangedSignal(ConnectionState state);
    protected:
        ProgressInfo* m_log;
    };
    /**--------------------------------------------------------------------------------------------------
    \brief Stores factories that can be registered for creating Connections of various types.
    **/
    class HARDWARE_API ConnectionFactory : public SoftwareService, public SoftwareServiceManager
    {
    public:
        virtual bool handlesType(const String& request) const = 0;
        virtual bool canConnectTo(const ConnectionInfo& request) const;
        virtual ConnectionBackend* createConnection(const ConnectionInfo& request) = 0;
        virtual Buffer<ConnectionInfo> availableConnections(const ConnectionSearchParamaters& params) = 0;
        virtual Buffer<ConnectionCategory> availableConnectionCatagories() = 0;
    public:
        static ConnectionBackend* CreateConnection(const ConnectionInfo& request);
        static void RegisterConnectionFactory(ConnectionFactory* factory);
        static Buffer<ConnectionInfo> AvailableConnections(const ConnectionSearchParamaters& params);
        static Buffer<ConnectionCategory> AvailableConnectionCatagories();
    protected:
        static Buffer<ConnectionFactory*> s_registered_factories;
    };
 
    /**--------------------------------------------------------------------------------------------------
    \brief A standard interface for all types of connections that allow transmitting and recieving of
        data between two devices or services.
    **/
    class HARDWARE_API Connection : public Device
    {
        Q_OBJECT
    public:
        Connection(const Model& model, ProgressInfo* raw_network_log = nullptr, ProgressInfo* command_log = nullptr, QObject* parent = nullptr);
        Connection(const ConnectionInfo& connection, const Model& model, ProgressInfo* raw_network_log = nullptr, ProgressInfo* command_log = nullptr, QObject* parent = nullptr);
        virtual ~Connection();
        //if size == nan, use m_default_rx_buffer_size
        const String& peek(uint04 size = Constant<uint04>::Invalid) const;
        [[nodiscard]] Buffer<String> rx(char deliminator, uint04 size = Constant<uint04>::Invalid);
        [[nodiscard]] Buffer<String> rx(char deliminator, const String& end_sequence, uint04 size = Constant<uint04>::Invalid);
        const String& rx(uint04 size = Constant<uint04>::Invalid);
        const String& rx(TimeSpan wait_time, uint04 size = Constant<uint04>::Invalid);
        [[nodiscard]] const String& rxLine(TimeSpan wait_time, char delimeter = '\n', uint04 size = Constant<uint04>::Invalid);
        virtual void tx(const String& data);
        virtual bool open();
        virtual bool open(const ConnectionInfo& request);
        virtual void close();
        virtual void setConnectionInfo(const ConnectionInfo& request);
        virtual void clearConnectionInfo();
        [[nodiscard]] virtual bool isOpen() const;
        [[nodiscard]] virtual const String& address() const { return m_connection_info.address; }
        [[nodiscard]] virtual const String& type() const { return m_connection_info.type; }
        void setRawDataLog(ProgressInfo* raw_network_log);
        void handleError();
        [[nodiscard]] virtual String threadID() const;
        [[nodiscard]] virtual bool canReadLine(char deliminator = '\n') const;
        virtual void setTXDelay(const TimeSpan& tx_delay) { m_tx_delay = tx_delay; }
        [[nodiscard]] ProgressInfo* rawNetworkLog() { return m_raw_data_log; }
        [[nodiscard]] Time lastRxTime() const { return m_last_rx; }
        [[nodiscard]] Time lastTxTime() const { return m_last_tx; }
        [[nodiscard]] const ProgressInfo* rawNetworkLog() const { return m_raw_data_log; }
        [[nodiscard]] const ConnectionInfo& connectionInfo() const { return m_connection_info; }
        [[nodiscard]] ConnectionState connectionState() const;
        [[nodiscard]] ConnectionBackend* ioDevice() const;
        virtual bool waitForReadyRead(const TimeSpan& span);
        virtual void setDefaultRxBufferSize(uint04 default_rx_buffer_size);
        void setRawLoggingMode(RawConnectionLoggingMode mode) { m_raw_logging_mode = mode; }
        [[nodiscard]] virtual bool ping() const;
    public:
        [[nodiscard]] static bool Ping(const String& address, ProgressInfo* log = nullptr);
        [[nodiscard]] static bool Ping(const String& address, String& response, ProgressInfo* log = nullptr);
        static bool LogNetworkInfo(ProgressInfo* log);
        static bool LogIPInfo(ProgressInfo* log);
    protected:
        virtual void setBackend(ConnectionBackend* device);
        void initConnection();
        void handleErrorString(const TranslatedString& error);
        bool openBackend(ConnectionBackend* io_device, const ConnectionInfo& request);
    public slots:
        virtual void setConnectionState(ConnectionState state);
        void writeConnectionLogMessage(const TranslatedString& message);
    signals:
        void connectSignal();
        void disconnectSignal();
        void connectionStateChangedSignal(ConnectionState state);
        void dataAvailableSignal();
    protected:
        ConnectionInfo m_connection_info;
        Buffer<std::function<void(const String&)>> m_tx_callback;
        Buffer<std::function<void(const String&)>> m_rx_callback;
        mutable String m_connection_rx_buffer;
        Time m_last_rx = Time(0);
        Time m_last_tx = Time(0);
        TimeSpan m_tx_delay = TimeSpan(0);
        ConnectionBackend* m_io_device = nullptr;
        ProgressInfo* m_raw_data_log = nullptr;
        uint04 m_total_tx = 0;
        uint04 m_total_rx = 0;
        uint04 m_default_rx_buffer_size = 2046;
        ConnectionState m_connection_state = ConnectionState::e_no_connection;
        RawConnectionLoggingMode m_raw_logging_mode = RawConnectionLoggingMode::e_ascii_logging;
        bool m_log_tx = true;
        bool m_log_rx = true;
        bool m_show_errors = false;
    };
}