vrengageStatusPublisher.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file vrengageStatusPublisher.h
//! \ingroup vrfcgf
//! \brief Defines the status publisher for VREngage applications
//!
//! This file contains the DtVreStatusPublisher class which is responsible for
//! broadcasting status information about a VREngage application to other
//! applications in the distributed simulation environment, such as VR-Forces GUI.
//! The publisher sends periodic heartbeat messages containing application identity,
//! player information, and entity state.
 
#pragma once
 
#include "vrePlayerStation/export.h"
#include <vlpi/entityIdentifier.h>
#include <vlutil/vlString.h>
#include <vlutil/vlTime.h>
 
namespace makVre
{
 
//! \brief Status publisher for VREngage applications
//!
//! This class is responsible for broadcasting status information about a
//! VREngage application to other applications in the distributed simulation
//! environment, such as VR-Forces GUI and other control applications. It sends
//! periodic heartbeat messages containing application identity, player information,
//! and entity state.
//!
//! The status publisher maintains information such as the application ID, name,
//! player name, controlled entity ID, station name, and operational mode. This
//! information can be updated at runtime, and the publisher will automatically
//! track changes and send updated status messages when necessary.
class PLAYERSTATION_DLL DtVreStatusPublisher
{
public:
   //! \brief Constructor
   //!
   //! Initializes a new status publisher with default values for all properties.
   //! The heartbeat interval is initialized to a default value, and the publisher
   //! is marked as modified to ensure a status message is sent on the next tick.
   DtVreStatusPublisher();
 
   //! \brief Virtual destructor
   //!
   //! Ensures proper cleanup of derived classes.
   virtual ~DtVreStatusPublisher();
 
   //! \brief Sends a status message immediately
   //!
   //! This method immediately broadcasts a status message containing the current
   //! state of the publisher. It resets the last sent time and clears the modified
   //! flag. This method is called automatically by tick() when necessary, but can
   //! also be called manually to force an immediate status update.
   virtual void sendStatus();
 
   //! \brief Sets the heartbeat interval
   //! \param heartbeatInterval Interval in milliseconds between status messages
   //!
   //! This method sets the interval at which status messages are automatically
   //! sent. The interval is specified in milliseconds. If the publisher has not
   //! been modified since the last status message, a new status message will be
   //! sent every heartbeatInterval milliseconds.
   virtual void setHeartbeatInterval(int heartbeatInterval);
 
   //! \brief Gets the current heartbeat interval
   //! \return Current heartbeat interval in milliseconds
   //!
   //! This method returns the current interval at which status messages are
   //! automatically sent.
   virtual int heartbeatInterval();
 
   //! \brief Updates the publisher and sends status messages when necessary
   //!
   //! This method is called periodically (typically by the simulation manager)
   //! to update the publisher and send status messages when necessary. It checks
   //! if the publisher has been modified or if the heartbeat interval has elapsed,
   //! and sends a status message if either condition is true.
   //!
   //! \note This method should be called regularly to ensure timely status updates.
   virtual void tick();
 
   //! \brief Sets the application ID
   //! \param id Unique identifier for this application
   //!
   //! This method sets the unique identifier for this VREngage application.
   //! The ID should be unique across all participating VREngage applications
   //! in an exercise. Setting a new ID marks the publisher as modified.
   virtual void setId(unsigned long id);
 
   //! \brief Gets the application ID
   //! \return Current application ID
   //!
   //! This method returns the unique identifier for this VREngage application.
   virtual unsigned long id() const;
 
   //! \brief Sets the application name
   //! \param name Name for this application
   //!
   //! This method sets the name for this VREngage application. The name should
   //! be unique across all participating VREngage applications in an exercise,
   //! but may be changed over the lifetime of an application. Setting a new name
   //! marks the publisher as modified.
   virtual void setName(const std::string& name);
 
   //! \brief Gets the application name
   //! \return Current application name
   //!
   //! This method returns the name for this VREngage application.
   virtual std::string name() const;
 
   //! \brief Sets the player name
   //! \param name Name of the player using this application
   //!
   //! This method sets the name of the player using this VREngage application.
   //! The player name is optional and can be used to identify the human user
   //! controlling the application. Setting a new player name marks the publisher
   //! as modified.
   virtual void setPlayerName(const DtString& name);
 
   //! \brief Gets the player name
   //! \return Current player name
   //!
   //! This method returns the name of the player using this VREngage application.
   virtual DtString playerName() const;
 
   //! \brief Sets the controlled entity ID
   //! \param entityId Identifier of the entity controlled by this application
   //!
   //! This method sets the identifier of the entity controlled by this VREngage
   //! application. This is typically the primary entity that the player is
   //! controlling or inhabiting. Setting a new entity ID marks the publisher as
   //! modified and updates the static entity ID.
   virtual void setEntityId(const DtEntityIdentifier& entityId);
 
   //! \brief Gets the controlled entity ID
   //! \return Current entity ID
   //!
   //! This method returns the identifier of the entity controlled by this
   //! VREngage application.
   virtual DtEntityIdentifier entityId() const;
 
   //! \brief Gets the static controlled entity ID
   //! \return Current static entity ID
   //!
   //! This static method provides access to the entity ID from anywhere in the
   //! application without needing a reference to the status publisher instance.
   static DtEntityIdentifier getEntityId();
 
   //! \brief Sets the station name (player role)
   //! \param name Name of the station/role this player is operating
   //!
   //! This method sets the station name, which identifies the player's role.
   //! Available string identifiers for roles are defined in VR-Engage player
   //! definition lua files (e.g., "Pilot", "Human", "LAV Driver", etc.).
   //! Setting a new station name marks the publisher as modified.
   virtual void setStationName(const std::string& name);
 
   //! \brief Gets the station name (player role)
   //! \return Current station name
   //!
   //! This method returns the station name, which identifies the player's role.
   virtual std::string stationName() const;
 
   //! \brief Sets the spectator mode flag
   //! \param mode True if the player is in spectator mode, false otherwise
   //!
   //! This method sets the flag indicating whether the player is in spectator mode.
   //! In spectator mode, the player is observing the simulation but not actively
   //! controlling an entity. Setting a new spectator mode marks the publisher as
   //! modified.
   virtual void setSpectatorMode(bool mode);
 
   //! \brief Gets the spectator mode flag
   //! \return True if the player is in spectator mode, false otherwise
   //!
   //! This method returns the flag indicating whether the player is in spectator mode.
   virtual bool spectatorMode() const;
 
   //! \brief Sets the final status flag
   //! \param status True if this is the final status message, false otherwise
   //!
   //! This method sets the flag indicating if this is a final status message
   //! for the VREngage application. A final status message indicates that the
   //! application is shutting down and will no longer be sending status updates.
   //! Setting the final status flag to true marks the publisher as modified.
   virtual void setFinalStatus(bool status);
 
   //! \brief Gets the final status flag
   //! \return True if this is the final status message, false otherwise
   //!
   //! This method returns the flag indicating if this is a final status message
   //! for the VREngage application.
   virtual bool finalStatus() const;
 
protected:
   //! \brief Copy constructor
   //! \param orig Original status publisher to copy
   //!
   //! This copy constructor creates a new status publisher that is a copy of
   //! the specified original. It is protected to prevent unintended copying.
   DtVreStatusPublisher(const DtVreStatusPublisher& orig);
 
   //! \brief Assignment operator
   //! \param orig Original status publisher to assign from
   //! \return Reference to this status publisher
   //!
   //! This assignment operator assigns the state of the specified original
   //! status publisher to this status publisher. It is protected to prevent
   //! unintended assignment.
   DtVreStatusPublisher& operator=(const DtVreStatusPublisher& orig);
 
protected:
   //! \brief Interval in milliseconds between status messages
   int myHeartbeatInterval;
 
   //! \brief Time when the last status message was sent
   DtTime myTimeLastSent;
 
   //! \brief Flag indicating if the publisher has been modified since the last message
   bool myHasBeenModified;
 
   //! \brief Unique identifier for this application
   unsigned long long myId;
 
   //! \brief Name of this application
   std::string myName;
 
   //! \brief Name of the player using this application
   std::string myPlayerName;
 
   //! \brief Identifier of the entity controlled by this application
   DtEntityIdentifier myEntityId;
 
   //! \brief Name of the station/role this player is operating
   std::string myStationName;
 
   //! \brief Flag indicating whether the player is in spectator mode
   bool mySpectatorMode;
 
   //! \brief Flag indicating if this is a final status message
   bool myFinalStatus;
 
   //! \brief Static entity identifier for global access
   //!
   //! This static member provides access to the entity ID from anywhere in the
   //! application without needing a reference to the status publisher instance.
   static DtEntityIdentifier theEntityId;
};
 
} // namespace makVre