radarFxConnector.h

Go to the documentation of this file.

// ******************************************************************************
// ** Copyright (c) 2025 MAK Technologies
// ** All rights reserved.
// ******************************************************************************
 
//! \file radarFxConnector.h
//! \brief Defines the connector class for communicating with a RadarFX server
//! \ingroup vreRadarFxConnector
 
 
#pragma once
 
#include <vreRadarFxConnector/export.h>
 
#include <vreRadarFxShared/locklessQueue.h>
#include <vreRadarFxShared/rfxMessageHandler.h>
#include <vreRadarFxShared/rfxMessageFactory.h>
 
#include <vlutil/vlInetTcpSocket.h>
 
#include <list>
#include <string>
 
class DtExerciseConnection;
class DtThread;
 
namespace makRadarFx
{
//! \brief The default port that the RadarFX server listens on
//!
//! This constant defines the standard network port used for connecting
//! to a RadarFX server when no custom port is specified
const int DtRadarFXPort = 4567;
 
//! \brief Forward declaration of the base message class
class DtBaseMessage;
 
//! \brief Forward declaration of the delegate template class
//! \tparam Ret Return type of the delegate function
//! \tparam Param0 Parameter type for the delegate function
template <typename Ret, typename Param0>
class DtDelegate;
 
//! \brief Manages connection to a RadarFX server and handles message exchange
//!
//! The DtRadarFxConnector class provides a client interface for connecting to a
//! RadarFX server. It manages the connection lifecycle, sends and receives messages,
//! and provides callbacks for connection events. The class includes functionality
//! for automatic reconnection and message queuing.
//!
//! This connector operates with a worker thread that handles the actual network
//! communication while presenting a thread-safe interface to client code.
class RFX_CONNECTOR_DLL DtRadarFxConnector
{
public:
   //! \brief Type definition for connection state change callback delegates
   //!
   //! This delegate type is used for callbacks that are triggered when the
   //! connection state changes (connected or disconnected)
   typedef DtDelegate<void, DtRadarFxConnector*> DtConnectionDelegate;
 
   //! \brief Default constructor
   //!
   //! Initializes a new RadarFx connector with default settings
   DtRadarFxConnector();
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources and stops the worker thread
   virtual ~DtRadarFxConnector();
 
   //! \brief Establishes a connection to a remote RadarFX server
   //! \param address IP address or hostname of the RadarFX server
   //! \param port Network port the server is listening on (defaults to DtRadarFXPort)
   //! \param attemptRetry Whether to automatically retry connection if it fails or disconnects
   //!
   //! Initiates a connection to the specified RadarFX server. When the connection
   //! is established, all registered connection callbacks will be executed.
   //! If attemptRetry is true, the connector will automatically attempt to
   //! reconnect if the initial connection fails or if the connection is lost.
   virtual void connect(const std::string& address, int port = DtRadarFXPort, bool attemptRetry = true);
 
   //! \brief Disconnects from the RadarFX server
   //!
   //! Closes the connection to the server and stops any automatic reconnection
   //! attempts. All registered disconnection callbacks will be executed.
   virtual void disconnect();
 
   //! \brief Checks if the connection is valid
   //! \return True if the connection has been established and is currently valid
   //!
   //! Determines whether there is an active, valid connection to the RadarFX server
   virtual bool isOk();
 
   //! \brief Processes queued messages and updates internal state
   //!
   //! This method must be called periodically (typically once per frame) to
   //! process incoming messages and execute associated callbacks. It also
   //! handles connection retries if enabled.
   virtual void tick();
 
   //! \brief Sends a message to the RadarFX server
   //! \param request Reference to the message to send
   //!
   //! Queues a message to be sent to the RadarFX server. A copy of the message
   //! is made internally, so the original message can safely go out of scope
   //! immediately after sendMessage is called. If the message has no ID or
   //! requester name set, these will be automatically assigned.
   virtual void sendMessage(DtBaseMessage& request);
 
   //! \brief Gets the message handler for incoming message processing
   //! \return Reference to the message handler used by this connector
   //!
   //! Provides access to the message handler that dispatches incoming messages.
   //! Users should register their delegates with this handler to process
   //! specific message types when they are received from the server.
   virtual DtVreMessageHandler& messageHandler() { return myMessageHandler; }
 
   //! \brief Registers a callback for successful connections
   //! \param delegate The callback delegate to register
   //!
   //! Adds a delegate that will be called when a connection to the
   //! RadarFX server is successfully established
   virtual void addConnectedCallback(const DtConnectionDelegate& delegate);
 
   //! \brief Unregisters a previously registered connection callback
   //! \param delegate The callback delegate to unregister
   //!
   //! Removes a delegate from the list of callbacks that are called when
   //! a connection is established
   virtual void removeConnectedCallback(const DtConnectionDelegate& delegate);
 
   //! \brief Registers a callback for disconnections
   //! \param delegate The callback delegate to register
   //!
   //! Adds a delegate that will be called when the connection to the
   //! RadarFX server is lost
   virtual void addDisconnectedCallback(const DtConnectionDelegate& delegate);
 
   //! \brief Unregisters a previously registered disconnection callback
   //! \param delegate The callback delegate to unregister
   //!
   //! Removes a delegate from the list of callbacks that are called when
   //! a disconnection occurs
   virtual void removeDisconnectedCallback(const DtConnectionDelegate& delegate);
 
   //! \brief Gets the message factory used for message creation
   //! \return Reference to the message factory
   //!
   //! Provides access to the message factory that creates and decodes messages.
   //! Users can add custom message decoders to this factory to handle
   //! application-specific message types.
   virtual DtVreMessageFactory& messageFactory() { return myMessageFactory; }
 
   //! \brief Generates a unique message ID
   //! \return A unique identifier for a message
   //!
   //! Provides a unique ID for tracking message responses. This function is
   //! automatically used to assign IDs to messages that don't have one set
   //! (id field is 0) when sendMessage is called.
   virtual unsigned int nextId();
 
   //! \brief Gets a unique name for this client application
   //! \return String containing a unique requester name
   //!
   //! Provides a unique name for the client derived from the IP address and
   //! process ID of the running application. This name is automatically
   //! assigned to messages that don't have a requester name set when
   //! sendMessage is called.
   virtual std::string& requesterName();
 
   //! \brief Gets the default timeout for connection retry attempts
   //! \return Default retry timeout in seconds
   //!
   //! Returns the time in seconds between reconnection attempts when
   //! automatic retry is enabled. The default value is 5 seconds.
   static double defaultRetryTimeout();
 
   //! \brief Sets the default timeout for connection retry attempts
   //! \param val New timeout value in seconds
   //!
   //! Sets the time in seconds between reconnection attempts when
   //! automatic retry is enabled.
   static void setDefaultRetryTimeout(double val);
 
   //! \brief Gets the default heartbeat timeout
   //! \return Default heartbeat timeout in seconds
   //!
   //! Returns the timeout for heartbeat messages used to detect
   //! connection loss. The default value is 2.5 seconds.
   static double defaultHeartbeatTimeout();
 
   //! \brief Sets the default heartbeat timeout
   //! \param val New timeout value in seconds
   //!
   //! Sets the timeout for heartbeat messages used to detect
   //! connection loss.
   static void setDefaultHeatbeatTimeout(double val);
 
protected:
   //! \brief Finds the IP address of the first available network device
   //! \param found Set to true if an address was found, false otherwise
   //! \return Network address of the first available device
   //!
   //! Searches for and returns the IP address of the first available
   //! network device on the system
   DtInetAddr findFirstNetworkDeviceAddress(bool& found) const;
 
   //! \brief Message handler for processing incoming messages
   DtVreMessageHandler myMessageHandler;
 
   //! \brief List of callbacks to invoke when connection is established
   std::list<DtConnectionDelegate> myConnectionCallbacks;
 
   //! \brief List of callbacks to invoke when connection is lost
   std::list<DtConnectionDelegate> myDisconnectionCallbacks;
 
   //! \brief Factory for creating and decoding messages
   DtVreMessageFactory myMessageFactory;
 
   //! \brief Counter for generating unique message IDs
   unsigned int myNextId;
 
   //! \brief Unique name for this client instance
   std::string myRequestorName;
 
   //! \brief Thread-safe queue for outgoing messages
   DtLocklessQueue<DtBaseMessage*> myOutgoingQueue;
 
   //! \brief Thread-safe queue for incoming messages
   DtLocklessQueue<DtBaseMessage*> myIncomingQueue;
 
   //! \brief Worker thread that handles network communication
   DtThread* myWorkerThread;
 
   //! \brief Socket for TCP communication with the server
   DtInetTcpSocket* mySocket;
 
   //! \brief Flag indicating whether to automatically retry connections
   bool myShouldRetryConnect;
 
   //! \brief Time in seconds between connection retry attempts
   double myRetryTimeout;
 
   //! \brief Server address to connect to
   std::string myAddress;
 
   //! \brief Server port to connect to
   int myPort;
 
   //! \brief Worker thread function that runs network communication
   //! \param data Pointer to the DtRadarFxConnector instance
   //! \param stop Pointer to a flag indicating if the thread should stop
   //!
   //! This static function is executed by the worker thread to handle
   //! network communication asynchronously
   static void workerFunction(void* data, volatile bool* stop);
 
   //! \brief Flag indicating if the worker thread should terminate
   bool myShouldQuit;
 
   //! \brief Static storage for default heartbeat timeout
   static double theDefaultHeatbeatTimeout;
 
   //! \brief Static storage for default retry timeout
   static double theDefaultRetryTimeout;
};
} // namespace makRadarFx