vreListener.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file vreListener.h
//! \ingroup vreManager
//! \brief VREngage status listener and message handler
//!
//! This file defines the DtVreStatusListener class and supporting structures,
//! which track the status of VREngage applications in the simulation and
//! provide callbacks for status changes.
 
#pragma once
 
#include "vreManager/export.h"
#include <vrfutil/rwUUID.h>
#include <vlpi/simulationAddress.h>
 
class DtSimMessage;
 
namespace makVrv
{
class DtDe;
}
 
//! \brief Function pointer type for VREngage application status callbacks
//! \param id The unique identifier of the VREngage application
//! \param usr User-defined data pointer provided during callback registration
using DtVreAppStatusCallbackFcn = void (*)(unsigned long id, void* usr);
 
//! \brief Structure to track the status of a VREngage application
//!
//! Contains information about a VREngage application's identity, assigned entity,
//! role, and operational status.
using VreAppStatus = struct VreAppStatus
{
   //! \brief Unique identifier for the VREngage application
   //!
   //! Must be unique across all VREngage stations in an exercise
   //! and must not change over the lifetime of the application.
   DtU64 myId;
 
   //! \brief Name of the VREngage application
   //!
   //! Should be unique across all VREngage stations in an exercise.
   //! Unlike the ID, the name may be changed during an exercise.
   DtString myName;
 
   //! \brief Name of the player using the VREngage application
   //!
   //! Optional identifier for the human user of the application.
   DtString myPlayerName;
 
   //! \brief UUID of the entity being controlled
   //!
   //! Identifies the entity currently controlled by this VREngage station.
   //! May be empty if no entity is currently controlled.
   DtString myUUID;
 
   //! \brief Station/role name for the player
   //!
   //! The station name (role) assumed by the player at the VREngage station
   //! (defined in the .entity file, e.g., "driver", "gunner", "commander").
   DtString myStationName;
 
   //! \brief Flag indicating whether player is in spectator mode
   //!
   //! When true, the player can observe but not interact with the entity.
   bool mySpectatorMode;
 
   //! \brief Timestamp of the last status update
   //!
   //! Used for timeout tracking of heartbeat messages.
   DtTime myLastUpdateTime;
};
 
//! \brief Structure to store callback function and user data
//!
//! Used to maintain registered callbacks for VREngage application status changes.
struct DtCallbackInfo
{
   //! \brief The callback function
   DtVreAppStatusCallbackFcn myFcn;
 
   //! \brief User-defined data to pass to the callback
   void* myUsrData;
};
 
//! \brief List of VREngage application status structures
using VreAppStatusList = std::vector<VreAppStatus>;
 
//! \brief Map of VREngage application IDs to status structures
using VreAppStatusMap = std::map<unsigned long, VreAppStatus>;
 
//! \brief List of callback information structures
using VreAppStatusCallbackList = std::vector<DtCallbackInfo>;
 
//! \brief Tracks the status of VREngage applications
//!
//! This class monitors VREngage application status messages, maintains current
//! status information for all known VREngage applications, handles heartbeat
//! timeouts, and provides callback notifications for status changes.
class VREMANAGER_DLL DtVreStatusListener
{
public:
   //! \brief Constructor
   //! \param de The distributed environment reference
   //!
   //! Initializes a new VREngage status listener with the specified distributed environment.
   DtVreStatusListener(makVrv::DtDe& de);
 
   //! \brief Destructor
   //!
   //! Cleans up resources used by the status listener.
   virtual ~DtVreStatusListener();
 
   //! \brief Gets the map of all known VREngage applications
   //! \return Constant reference to the status map
   //!
   //! Returns a map of application IDs to status structures for all known VREngage applications.
   virtual const VreAppStatusMap& vreAppStatusMap() const;
 
   //! \brief Looks up a VREngage application by ID
   //! \param id The unique identifier of the VREngage application
   //! \return The status structure for the specified application
   //!
   //! Retrieves the status information for a specific VREngage application.
   virtual VreAppStatus lookupVreApp(unsigned long id);
 
   //! \brief Sets the timeout interval for heartbeating VREngage applications
   //! \param timeoutInterval The timeout interval in milliseconds, or -1 to disable timeouts
   //!
   //! Sets the time interval after which an application is considered inactive
   //! if no status updates have been received.
   virtual void setTimeoutInterval(int timeoutInterval);
 
   //! \brief Gets the current timeout interval
   //! \return The timeout interval in milliseconds, or -1 if timeouts are disabled
   //!
   //! Returns the current timeout interval for heartbeating VREngage applications.
   virtual int timeoutInterval();
 
   //! \brief Processes timeouts for inactive applications
   //!
   //! Checks all status objects and deactivates any that have not sent
   //! an update within the timeout interval. For each timed-out application,
   //! the removed callbacks will be invoked.
   virtual void doTimeouts();
 
   //! \brief Processes a status message from a VREngage application
   //! \param msg The simulation message containing status information
   //!
   //! Extracts status information from the message and updates the internal
   //! status tracking. Invokes appropriate callbacks for new, changed, or
   //! removed applications.
   virtual void processStatusMessage(DtSimMessage* msg);
 
   //! \brief Registers a callback for new VREngage application discovery
   //! \param fcn The callback function to register
   //! \param usrData User-defined data to pass to the callback
   //!
   //! Adds a callback that will be invoked when a new VREngage application is discovered.
   virtual void addVreAppAddedCallback(DtVreAppStatusCallbackFcn fcn, void* usrData);
 
   //! \brief Unregisters a callback for new VREngage application discovery
   //! \param fcn The callback function to unregister
   //! \param usrData User-defined data that was registered with the callback
   //!
   //! Removes a previously registered callback for new application discovery.
   virtual void removeVreAppAddedCallback(DtVreAppStatusCallbackFcn fcn, void* usrData);
 
   //! \brief Registers a callback for VREngage application removal
   //! \param fcn The callback function to register
   //! \param usrData User-defined data to pass to the callback
   //!
   //! Adds a callback that will be invoked when a VREngage application is removed
   //! or times out.
   virtual void addVreAppRemovedCallback(DtVreAppStatusCallbackFcn fcn, void* usrData);
 
   //! \brief Unregisters a callback for VREngage application removal
   //! \param fcn The callback function to unregister
   //! \param usrData User-defined data that was registered with the callback
   //!
   //! Removes a previously registered callback for application removal.
   virtual void removeVreAppRemovedCallback(DtVreAppStatusCallbackFcn fcn, void* usrData);
 
   //! \brief Registers a callback for VREngage application status changes
   //! \param fcn The callback function to register
   //! \param usrData User-defined data to pass to the callback
   //!
   //! Adds a callback that will be invoked when a VREngage application's status changes
   //! (e.g., entity assignment, role change, spectator mode toggle).
   virtual void addVreAppChangedCallback(DtVreAppStatusCallbackFcn fcn, void* usrData);
 
   //! \brief Unregisters a callback for VREngage application status changes
   //! \param fcn The callback function to unregister
   //! \param usrData User-defined data that was registered with the callback
   //!
   //! Removes a previously registered callback for application status changes.
   virtual void removeVreAppChangedCallback(DtVreAppStatusCallbackFcn fcn, void* usrData);
 
protected:
   //! \brief Invokes all callbacks in a callback list
   //! \param cbList The list of callbacks to invoke
   //! \param id The ID of the VREngage application related to the callback
   //!
   //! Helper method to invoke all callbacks in a list with the specified application ID.
   virtual void invokeCallbacks(const VreAppStatusCallbackList& cbList, unsigned long id) const;
 
   //! \brief Removes a VREngage application from tracking
   //! \param id The ID of the VREngage application to remove
   //!
   //! Removes an application from the status map and invokes removed callbacks.
   virtual void removeVreApplication(unsigned long id);
 
private:
   //! \brief Copy constructor (not implemented)
   //! \param orig The source object
   DtVreStatusListener(const DtVreStatusListener& orig);
 
   //! \brief Assignment operator (not implemented)
   //! \param orig The source object
   //! \return Reference to this object
   DtVreStatusListener& operator=(const DtVreStatusListener& orig);
 
protected:
   //! \brief Reference to the distributed environment
   makVrv::DtDe& myDe;
 
   //! \brief Map of all known VREngage applications
   //!
   //! Maps application IDs to their status structures.
   VreAppStatusMap myVreAppStatusMap;
 
   //! \brief List of callbacks for application discovery
   VreAppStatusCallbackList myVreAppAddedCbList;
 
   //! \brief List of callbacks for application removal
   VreAppStatusCallbackList myVreAppRemovedCbList;
 
   //! \brief List of callbacks for application status changes
   VreAppStatusCallbackList myVreAppChangedCbList;
 
   //! \brief Timestamp of the last timeout check
   DtTime myLastTimeoutCheck;
 
   //! \brief Timeout interval in milliseconds
   //!
   //! Applications that haven't sent a status update within this interval
   //! will be considered inactive and removed. Set to -1 to disable timeouts.
   int myTimeoutInterval;
};