rwrContactInfoList.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file rwrContactInfoList.h
//! \ingroup vreVrfobjparam
//! \brief Radar Warning Receiver (RWR) contact information list
//!
//! This file defines the DtRwrContactInfoList class, which manages collections of
//! radar warning receiver contact information in VREngage. It provides functionality
//! for tracking detected radar emitters and their properties.
#pragma once
 
#include "vreVrfobjparam/export.h"
 
#include <readerWriter/rwList.h>
#include <readerWriter/noArgumentCallbackList.h>
 
class DtReaderWriterRegistry;
class DtString;
class DtRwRwrContactInfo;
 
namespace makVre
{
//! \brief Type identifier string for the RWR contact info list
const char DtRwrContactInfoListType[] = "DtRwrContactInfoList";
 
//! \brief A reader-writer list of RWR contact information elements
//!
//! This class manages a collection of DtRwRwrContactInfo elements, representing
//! radar contacts detected by a Radar Warning Receiver. It provides methods for
//! adding, removing, and finding contact information, as well as notification
//! mechanisms for tracking changes to the list.
//!
//! Use the DtRwList::add() and remove() methods to add and remove elements.
//! The list can be iterated through using DtList iteration methods.
//! The list will delete all of its contents when destroyed, so use caution
//! if holding pointers to any of the list elements.
//!
//! If you need to monitor the change state of a list, use a DtRwrContactInfoListChangeMonitor.
class VREVRFOBJPARAM_DLL DtRwrContactInfoList : public DtRwList
{
public:
   //! \brief Default constructor
   //!
   //! Creates a new RWR contact information list with default values.
   DtRwrContactInfoList();
 
   //! \brief Constructor with name
   //! \param name The name of this list
   //! \param parentRegistry Parent registry for reader/writer functionality (optional)
   //!
   //! Creates a new RWR contact information list with the specified name.
   DtRwrContactInfoList(const DtString& name, DtReaderWriterRegistry* parentRegistry = NULL);
 
   //! \brief Constructor with name as symbol string
   //! \param name The name of this list as a symbol string
   //! \param parentRegistry Parent registry for reader/writer functionality (optional)
   //!
   //! Creates a new RWR contact information list with the specified name.
   DtRwrContactInfoList(const DtSymbolString& name, DtReaderWriterRegistry* parentRegistry = NULL);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the list, including deleting all contact information elements.
   virtual ~DtRwrContactInfoList() override;
 
   //! \brief Copy constructor with name
   //! \param name The name of the new list
   //! \param orig The source list to copy from
   //! \param parentRegistry Parent registry for reader/writer functionality (optional)
   //!
   //! Creates a new RWR contact information list as a deep copy of the provided original,
   //! cloning all list items onto the new list.
   DtRwrContactInfoList(
      const DtString& name, const DtRwrContactInfoList& orig, DtReaderWriterRegistry* parentRegistry = NULL);
 
   //! \brief Copy constructor with name as symbol string
   //! \param name The name of the new list as a symbol string
   //! \param orig The source list to copy from
   //! \param parentRegistry Parent registry for reader/writer functionality (optional)
   //!
   //! Creates a new RWR contact information list as a deep copy of the provided original,
   //! cloning all list items onto the new list.
   DtRwrContactInfoList(
      const DtSymbolString& name, const DtRwrContactInfoList& orig, DtReaderWriterRegistry* parentRegistry = NULL);
 
   //! \brief Assignment operator
   //! \param orig The source list to copy from
   //! \return Reference to this list after assignment
   //!
   //! Assigns the contents of the provided list to this one. This is a deep copy;
   //! all items on the target list are deleted, and new items are cloned onto the list.
   DtRwrContactInfoList& operator=(const DtRwrContactInfoList& orig);
 
   //! \brief Creates a complete clone of the list and all items
   //! \param name The name for the cloned list
   //! \param parentRegistry Parent registry for reader/writer functionality (optional)
   //! \return Pointer to a new list that is a clone of this one
   //!
   //! Creates a complete clone of this list and all items on it.
   virtual DtRwrContactInfoList* clone(const DtString& name, DtReaderWriterRegistry* parentRegistry = NULL);
 
   //! \brief Creates a complete clone of the list and all items
   //! \param name The name for the cloned list as a symbol string
   //! \param parentRegistry Parent registry for reader/writer functionality (optional)
   //! \return Pointer to a new list that is a clone of this one
   //!
   //! Creates a complete clone of this list and all items on it.
   virtual DtRwrContactInfoList* clone(const DtSymbolString& name, DtReaderWriterRegistry* parentRegistry = NULL);
 
   //! \brief Clears the list
   //!
   //! Removes and deletes all contact information elements from the list.
   //! This method calls the non-virtual emptyList() function.
   virtual void clear();
 
   //! \brief Removes and deletes a contact information element
   //! \param contactInfo Pointer to the contact information to remove and delete
   //!
   //! If the specified contact info is on the list, removes it from the list
   //! and deletes the contact info object.
   virtual void removeAndDelete(DtRwRwrContactInfo* contactInfo);
 
   //! \brief Commented-out method for finding contact info by contact ID
   //!
   //! Would find the first contact info in the list with the specified contact,
   //! and return a pointer to it, or NULL if not found.
   // virtual DtRwRwrContactInfo* findContactInfoByContact(const DtUUID& contact);
 
   //! \brief Commented-out method for getting all contact IDs
   //!
   //! Would return a set of all the contact IDs in the list.
   // virtual std::set<DtUUID> contacts() const;
 
   //! \brief Factory method to create new RWR contact information elements
   //! \return Pointer to a newly created RWR contact information element
   //!
   //! Creates a new DtRwRwrContactInfo or derivative object. This base class
   //! implementation creates the base DtRwRwrContactInfo type.
   //!
   //! The getData() method uses this factory when adding new items to the list
   //! that are read from an input file. All items on the list should be of the
   //! type created by this method.
   //!
   //! \note If you need to add custom data to your RWR contact information,
   //! create a derived version of DtRwRwrContactInfo, override this class, and
   //! return your new RWR contact info from this method.
   virtual DtRwRwrContactInfo* createRwrContactInfo();
 
   //! \brief Adds a callback for list modification notifications
   //! \param fcn The callback function to add
   //! \param usr User data pointer to pass to the callback
   //!
   //! Registers a callback that will be invoked when the list or any of its
   //! contents change.
   //!
   //! \note If you want list modified notification in an asynchronous way, consider
   //! using a DtRwrContactInfoListChangeMonitor instead.
   virtual void addModifiedCallback(DtNoArgumentCallbackList::DtCallbackFunctionType fcn, void* usr);
 
   //! \brief Removes a callback for list modification notifications
   //! \param fcn The callback function to remove
   //! \param usr User data pointer that was registered with the callback
   //!
   //! Unregisters a previously registered modification callback.
   virtual void removeModifiedCallback(DtNoArgumentCallbackList::DtCallbackFunctionType fcn, void* usr);
 
   //! \brief Notifies that the list has been modified
   //!
   //! Call this method after making changes to the contents of the list.
   //! This will invoke all registered modification callbacks.
   virtual void listModified();
 
   //! \brief Equality operator
   //! \param other The list to compare with
   //! \return True if the lists are equal, false otherwise
   //!
   //! Compares this list with another to determine if they are equal.
   bool operator==(const DtRwrContactInfoList& other) const;
 
   //! \brief Gets the XML type identifier
   //! \return String identifying this type in XML archives
   //!
   //! Returns the type identifier used when archiving to an XML stream.
   static const char* theXmlType();
 
   //! \brief Gets the XML type identifier for this instance
   //! \return String identifying this type in XML archives
   //!
   //! Returns the type identifier used when archiving this instance to an XML stream.
   virtual const char* xmlType() const override { return theXmlType(); }
 
protected:
   //! \brief Copies contents from another list
   //! \param orig The source list to copy from
   //!
   //! Helper method used by constructors to copy contents from another list.
   //! Performs a deep copy of all list elements.
   void copyList(const DtRwrContactInfoList& orig);
 
   //! \brief Removes and deletes all list elements
   //!
   //! Helper method used by the destructor and clear() to remove and delete
   //! all elements from the list.
   void emptyList();
 
   //! \brief Processes input data to populate the list
   //! \param args Input arguments to process
   //! \param searchPaths Search paths for resolving file references
   //! \param variableBindings Variable bindings for resolving script variables
   //! \return Object pointer containing the processed data
   //!
   //! Constructs contact information elements and reads their data from
   //! the input arguments.
   virtual DtlObjPtr getData(DtlObjPtr args,
      const DtReaderWriter::SearchPaths& searchPaths,
      const DtVariableBindingsList& variableBindings) override;
 
   //! \brief Gets the reader/writer type identifier
   //! \return String identifying this reader/writer type
   //!
   //! Returns the type identifier for this reader/writer class.
   //! This can be used in place of dynamic-casting and is also used by
   //! the OPD editor to determine which type of control to create.
   virtual const char* readerWriterType() const override;
 
   //! \brief List of callbacks for modification notifications
   //!
   //! Stores the list of callback functions to be invoked when the list
   //! or its contents are modified.
   DtNoArgumentCallbackList myModifiedCallbackList;
 
protected:
};
 
//! \brief Monitor class for tracking changes to an RWR contact information list
//!
//! This class provides a mechanism for monitoring a DtRwrContactInfoList for changes.
//! When instantiated, this class registers a callback with the list and maintains
//! internal state as to whether the callback has been invoked since the last time
//! listChanged() was called.
class VREVRFOBJPARAM_DLL DtRwrContactInfoListChangeMonitor
{
private:
   //! \brief Default constructor (not implemented)
   //!
   //! Default constructor is private and not implemented to prevent
   //! creation of instances without a list to monitor.
   DtRwrContactInfoListChangeMonitor();
 
   //! \brief Copy constructor (not implemented)
   //! \param orig The source monitor to copy from
   //!
   //! Copy constructor is private and not implemented to prevent copying.
   DtRwrContactInfoListChangeMonitor(const DtRwrContactInfoListChangeMonitor& orig);
 
   //! \brief Assignment operator (not implemented)
   //! \param orig The source monitor to copy from
   //! \return Reference to this monitor after assignment
   //!
   //! Assignment operator is private and not implemented to prevent assignment.
   DtRwrContactInfoListChangeMonitor& operator=(DtRwrContactInfoListChangeMonitor& orig);
 
public:
   //! \brief Constructor with list to monitor
   //! \param contactInfoList Reference to the list to monitor for changes
   //!
   //! Creates a new monitor that will track changes to the specified RWR contact list.
   DtRwrContactInfoListChangeMonitor(DtRwrContactInfoList& contactInfoList);
 
   //! \brief Destructor
   //!
   //! Cleans up resources used by the monitor, including unregistering callbacks.
   ~DtRwrContactInfoListChangeMonitor();
 
   //! \brief Checks if the list has been changed
   //! \return True if the list has been changed, false otherwise
   //!
   //! Returns whether the list has been changed since the last time the changed
   //! state was reset. Does not reset the changed value.
   bool listChanged() const;
 
   //! \brief Resets the list changed state
   //!
   //! Resets the listChanged state of the monitor to false.
   //! This will not affect any other monitors on the same list.
   void markUnchanged();
 
   //! \brief Checks and resets the list changed state
   //! \return True if the list has been changed, false otherwise
   //!
   //! Returns whether the list has been changed since the last time the changed
   //! state was reset, and resets the list changed state to false.
   bool checkAndResetListChanged();
 
protected:
   //! \brief Static callback function for list changes
   //! \param usr User data pointer (instance of this monitor)
   //!
   //! Static callback function registered with the list to be notified of changes.
   static void listChangedCallback(void* usr);
 
   //! \brief Processes list changed notifications
   //!
   //! Internal method called when the list has changed to update the internal state.
   void processListChanged();
 
   //! \brief Reference to the monitored list
   //!
   //! Reference to the RWR contact information list being monitored for changes.
   DtRwrContactInfoList& myContactInfoList;
 
   //! \brief Flag indicating if the list has changed
   //!
   //! Stores whether the list has changed since the last time the changed state was reset.
   bool myListChanged;
};
} // namespace makVre