ifVreStatus.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file ifVreStatus.h
//! \ingroup vreVrfMessages
//! \brief Interface message class for VREngage status information
//!
//! This file defines the DtIfVreStatus class, which is used by VREngage
//! applications to announce their availability as role players and their
//! current entity assignment status.
 
#pragma once
 
#include <vreVrfMessages/export.h>
#include <vrfExtProtocol/simInterfaceContent.h>
#include <vlutil/vlString.h>
 
//! \brief Current version of the VREngage status message
const int DtIfVreStatusVersion = 1;
 
//! \brief Interface message for VREngage status information
//!
//! Instances of DtIfVreStatus messages are sent out by a VREngage application
//! to announce its availability as a role player and its current entity
//! assignment status. These status messages enable coordination between
//! multiple VREngage stations and other simulation components.
 
class VRFMESSAGES_DLL DtIfVreStatus : public DtSimInterfaceContent
{
public:
   //! \brief Default constructor
   //!
   //! Initializes an empty VREngage status message.
   DtIfVreStatus();
 
   //! \brief Virtual destructor
   virtual ~DtIfVreStatus() override;
 
   //! \brief Copy constructor
   //! \param orig The VREngage status message to copy from
   //!
   //! Creates a new VREngage status message by copying an existing one.
   DtIfVreStatus(const DtIfVreStatus& orig);
 
   //! \brief Assignment operator
   //! \param orig The VREngage status message to copy from
   //! \return Reference to this object after assignment
   //!
   //! Copies the contents of another VREngage status message into this one.
   DtIfVreStatus& operator=(const DtIfVreStatus& orig);
 
   //! \brief Gets the interface message type
   //! \return The message type identifier
   //!
   //! Returns DtVreStatusMessageType as defined in vreVrfMessageTypes.h.
   virtual int type() const override;
 
   //! \brief Creates a copy of this message
   //! \return Pointer to the new copy
   //!
   //! Creates a dynamically allocated copy of this message.
   virtual DtSimInterfaceContent* clone() const override;
 
   //! \brief Sets the identifier of the VREngage application
   //! \param id The unique identifier to set
   //!
   //! Sets the unique identifier for the VREngage application.
   //! This must be unique across all VREngage stations in an exercise
   //! and must not change over the lifetime of the application.
   virtual void setId(unsigned long id);
 
   //! \brief Gets the identifier of the VREngage application
   //! \return The VREngage application identifier
   virtual unsigned long id() const;
 
   //! \brief Sets the name of the VREngage application
   //! \param name The application name to set
   //!
   //! Sets the name of the VREngage application. This should be unique across
   //! all participating VREngage applications in an exercise, but unlike the ID,
   //! it may be changed during the lifetime of the application.
   virtual void setName(const DtString& name);
 
   //! \brief Gets the name of the VREngage application
   //! \return The application name
   virtual DtString name() const;
 
   //! \brief Sets the name of the player using the VREngage application
   //! \param name The player name to set
   //!
   //! Sets the optional name of the human player using the VREngage application.
   //! This can be used for display purposes and user identification.
   virtual void setPlayerName(const DtString& name);
 
   //! \brief Gets the name of the player
   //! \return The player name
   virtual DtString playerName() const;
 
   //! \brief Sets the UUID of the entity being controlled
   //! \param uuid The entity UUID to set
   //!
   //! Sets the UUID of the entity currently controlled by this VREngage station.
   //! If no entity is currently controlled, this may be empty.
   virtual void setUUID(const DtString& uuid);
 
   //! \brief Gets the UUID of the entity being controlled
   //! \return The entity UUID
   virtual DtString uuid() const;
 
   //! \brief Sets the station/role name for the player
   //! \param name The station name to set
   //!
   //! Sets the station name (role) assumed by the player at the VREngage station.
   //! Available string identifiers for station names are defined in the
   //! VREngage player definition .entity files (e.g., "driver", "gunner", "commander").
   virtual void setStationName(const DtString& name);
 
   //! \brief Gets the station/role name for the player
   //! \return The station name
   virtual DtString stationName() const;
 
   //! \brief Sets the spectator mode flag
   //! \param mode True for spectator mode, false for active player mode
   //!
   //! Sets whether the player at the VREngage station is in spectator mode.
   //! In spectator mode, the player can observe but not interact with the entity.
   virtual void setSpectatorMode(bool mode);
 
   //! \brief Gets the spectator mode flag
   //! \return True if in spectator mode, false otherwise
   virtual bool spectatorMode() const;
 
   //! \brief Sets the final status message flag
   //! \param yesNo True if this is the final status message, false otherwise
   //!
   //! Sets whether this status message is the final one to be sent by this
   //! VREngage application. When true, it indicates the application is shutting down.
   virtual void setFinalStatusMessage(bool yesNo);
 
   //! \brief Gets the final status message flag
   //! \return True if this is the final status message, false otherwise
   virtual bool finalStatusMessage() const;
 
 
   //! \brief Gets the network representation size
   //! \return Size in bytes of the network representation
   //!
   //! Returns the size of the network buffer needed to store this message.
   virtual int netRepSize() const override;
 
   //! \brief Deserializes the message from a network buffer
   //! \param contentBuffer Pointer to the network buffer
   //! \param contentSize Size of the buffer in bytes
   //! \return True if deserialization was successful
   //!
   //! Fills the message from the provided network buffer.
   virtual bool setFromNet(const char* contentBuffer, unsigned contentSize) override;
 
   //! \brief Serializes the message for network transmission
   //! \return True if serialization was successful
   //!
   //! Prepares the message for network transmission.
   virtual bool setToNet() override;
 
   //! \brief Formats the message data as a string
   //! \param str String to store the formatted message data
   //!
   //! Appends a human-readable representation of the message to the provided string.
   virtual void printDataToString(DtString& str) override;
 
   //! \brief Static creator function for factory registration
   //! \return Pointer to a new instance of DtIfVreStatus
   //!
   //! This static function is used for registration with DtInterfaceContentFactory.
   static DtSimInterfaceContent* creator();
 
 
protected:
   //! \brief Version information for the message
   //!
   //! The high word is a signal that the version exists, and the
   //! low word is the actual version. If this information does not exist,
   //! it is assumed to be an older status message.
   DtU32 myVersion;
 
   //! \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 Flag indicating whether this is the final status message
   //!
   //! When true, indicates this is the final status message to be sent by
   //! this VREngage application before shutting down.
   bool myFinalStatusMessage;
};