From 5944fb5818acfef6480cec9a836d1ad54604c837 Mon Sep 17 00:00:00 2001 From: Jason Watkins Date: Tue, 14 Apr 2015 12:59:20 -0700 Subject: [PATCH] Expanded doc comments. - Added doc comments to the DataManager class. - Added description of LOG_VERBOSITY levels and reset the value. - Added doc comment to DataMap. - Added doc comments to MessageHandlers class. --- xpcPlugin/DataManager.h | 255 ++++++++++++++++++++++++++++++++++-- xpcPlugin/DataMaps.h | 1 + xpcPlugin/Log.h | 13 +- xpcPlugin/MessageHandlers.h | 24 +++- 4 files changed, 279 insertions(+), 14 deletions(-) diff --git a/xpcPlugin/DataManager.h b/xpcPlugin/DataManager.h index a25a06e..d153da9 100644 --- a/xpcPlugin/DataManager.h +++ b/xpcPlugin/DataManager.h @@ -8,6 +8,7 @@ namespace XPC { + /// Represents named datarefs used by X-Plane Connect enum class DREF { None = 0, @@ -134,41 +135,275 @@ namespace XPC MP7Alt, }; + /// Marshals data between the plugin and X-Plane. + /// + /// \author Jason Watkins + /// \version 1.0 + /// \since 1.0 + /// \date Intial Version: 2015-04-13 + /// \date Last Updated: 2015-04-13 class DataManager { public: + /// Initializes the internal data used by DataManager to translate DREF values + /// into X-Plane internal data. static void Initialize(); + /// Gets a dataref based on its name. + /// + /// \param dref The name of the dref to get. + /// \param values An array in which the result of the operation will be stored. + /// \param size The size of the values array. + /// \returns The number of elements placed in the values array. For scalar + /// drefs, this will be one. For array drefs, this will be the + /// lesser of the size and the number of elements in the dref. + /// + /// \remarks The first time this method is called for a given dataref, it must + /// perform a relatively expensive lookup operation to translate the + /// given string into an X-Plane internal pointer. This value is cached, + /// so subsequent calls will incure minimal extra overhead compared to + /// the other methods in this class. + /// + /// \remarks For simplicity, this method is provided with only one output type. + /// For most integer and double drefs, this is unlikely to cause issues. + /// However, for drefs where the entire integer range may be used, or + /// doubles where high precision is required, using this method may result + /// in a loss of precision. In that case, consider using one of the + /// strongly typed methods instead. static std::size_t Get(std::string dref, float values[], std::size_t size); + /// Gets the value of a double dataref. + /// + /// \param dref The dataref to get. + /// \param aircraft The aircraft number for which to get the data. + /// \returns The value of the dref specified if that dref has the type + /// double; otherwise an undefined value. + /// + /// \remarks This method does not verify the type of the dref requested. It is + /// the responsibility of the caller to check the X-Plane documentation + /// and call the appropriate overload of this method. If the wrong + /// overload is called, the value returned is determined by the X-Plane + /// plugin manager, and is considered undefined by the plugin. + /// + /// \remarks Although any combination of dref and aircraft may be passed to this + /// method, most drefs are not valid for multiplayer aircraft. All drefs + /// that are not prefixed with 'MP' are valid for the player aircraft. + /// 'MP' drefs should be called with aircraft 0. static double GetDouble(DREF dref, std::uint8_t aircraft = 0); + /// Gets the value of a float dataref. + /// + /// \param dref The dataref to get. + /// \param aircraft The aircraft number for which to get the data. + /// \returns The value of the dref specified if that dref has the type + /// float; otherwise an undefined value. + /// + /// \remarks This method does not verify the type of the dref requested. It is + /// the responsibility of the caller to check the X-Plane documentation + /// and call the appropriate overload of this method. If the wrong + /// overload is called, the value returned is determined by the X-Plane + /// plugin manager, and is considered undefined by the plugin. + /// + /// \remarks Although any combination of dref and aircraft may be passed to this + /// method, most drefs are not valid for multiplayer aircraft. All drefs + /// that are not prefixed with 'MP' are valid for the player aircraft. + /// 'MP' drefs should be called with aircraft 0. static float GetFloat(DREF dref, std::uint8_t aircraft = 0); + /// Gets the value of an integer dataref. + /// + /// \param dref The dataref to get. + /// \param aircraft The aircraft number for which to get the data. + /// \returns The value of the dref specified if that dref has the type + /// int; otherwise an undefined value. + /// + /// \remarks This method does not verify the type of the dref requested. It is + /// the responsibility of the caller to check the X-Plane documentation + /// and call the appropriate overload of this method. If the wrong + /// overload is called, the value returned is determined by the X-Plane + /// plugin manager, and is considered undefined by the plugin. + /// + /// \remarks Although any combination of dref and aircraft may be passed to this + /// method, most drefs are not valid for multiplayer aircraft. All drefs + /// that are not prefixed with 'MP' are valid for the player aircraft. + /// 'MP' drefs should be called with aircraft 0. static int GetInt(DREF dref, std::uint8_t aircraft = 0); + /// Gets the value of a float array dataref. + /// + /// \param dref The dataref to get. + /// \param values An array in which the result of the operation will be stored. + /// \param size The size of the values array. + /// \param aircraft The aircraft number for which to get the data. + /// \returns The number of elements placed in the values array. This will + /// be the lesser of the size and the number of elements in the dref. + /// + /// \remarks This method does not verify the type of the dref requested. It is + /// the responsibility of the caller to check the X-Plane documentation + /// and call the appropriate overload of this method. If the wrong + /// overload is called, the value returned is determined by the X-Plane + /// plugin manager, and is considered undefined by the plugin. + /// + /// \remarks Although any combination of dref and aircraft may be passed to this + /// method, most drefs are not valid for multiplayer aircraft. All drefs + /// that are not prefixed with 'MP' are valid for the player aircraft. + /// 'MP' drefs should be called with aircraft 0. static std::size_t GetFloatArray(DREF dref, float values[], std::size_t size, std::uint8_t aircraft = 0); + + /// Gets the value of an int array dataref. + /// + /// \param dref The dataref to get. + /// \param values An array in which the result of the operation will be stored. + /// \param size The size of the values array. + /// \param aircraft The aircraft number for which to get the data. + /// \returns The number of elements placed in the values array. This will + /// be the lesser of the size and the number of elements in the dref. + /// + /// \remarks This method does not verify the type of the dref requested. It is + /// the responsibility of the caller to check the X-Plane documentation + /// and call the appropriate overload of this method. If the wrong + /// overload is called, the value returned is determined by the X-Plane + /// plugin manager, and is considered undefined by the plugin. + /// + /// \remarks Although any combination of dref and aircraft may be passed to this + /// method, most drefs are not valid for multiplayer aircraft. All drefs + /// that are not prefixed with 'MP' are valid for the player aircraft. + /// 'MP' drefs should be called with aircraft 0. static std::size_t GetIntArray(DREF dref, int values[], std::size_t size, std::uint8_t aircraft = 0); - static void Set(DREF dref, double value, std::uint8_t aircraft = 0); - - static void Set(DREF dref, float value, std::uint8_t aircraft = 0); - - static void Set(DREF dref, int value, std::uint8_t aircraft = 0); - - static void Set(DREF dref, float values[], std::size_t size, std::uint8_t aircraft = 0); - - static void Set(DREF dref, int values[], std::size_t size, std::uint8_t aircraft = 0); - + /// Sets the value of a dataref + /// + /// \param dref The name of the dref to set. + /// \param values The value to set the dref to. + /// \param size The number of items stored in values. + /// + /// \remarks The first time this method is called for a given dataref, it must + /// perform a relatively expensive lookup operation to translate the + /// given string into an X-Plane internal pointer. This value is cached, + /// so subsequent calls will incure minimal extra overhead compared to + /// the other methods in this class. + /// + /// \remarks For simplicity, this method is provided with only one input type. + /// For most integer and double drefs, this is unlikely to cause issues. + /// However, for drefs where the entire integer range may be used, or + /// doubles where high precision is required, using this method may result + /// in a loss of precision. In that case, consider using one of the + /// strongly typed methods instead. static void Set(std::string dref, float values[], std::size_t size); + /// Sets the value of a double dataref. + /// + /// \param dref The dataref to set. + /// \param value The value to set the dref to. + /// \param aircraft The aircraft number for which to get the data. + /// + /// \remarks This method does not verify the type of the dref being set. It is + /// the responsibility of the caller to check the X-Plane documentation + /// and call the appropriate overload of this method. If the wrong + /// overload is called, the operation will fail silently. + /// + /// \remarks Although any combination of dref and aircraft may be passed to this + /// method, most drefs are not valid for multiplayer aircraft. All drefs + /// that are not prefixed with 'MP' are valid for the player aircraft. + /// 'MP' drefs should be called with aircraft 0. + static void Set(DREF dref, double value, std::uint8_t aircraft = 0); + + /// Sets the value of a float dataref. + /// + /// \param dref The dataref to set. + /// \param value The value to set the dref to. + /// \param aircraft The aircraft number for which to get the data. + /// + /// \remarks This method does not verify the type of the dref being set. It is + /// the responsibility of the caller to check the X-Plane documentation + /// and call the appropriate overload of this method. If the wrong + /// overload is called, the operation will fail silently. + /// + /// \remarks Although any combination of dref and aircraft may be passed to this + /// method, most drefs are not valid for multiplayer aircraft. All drefs + /// that are not prefixed with 'MP' are valid for the player aircraft. + /// 'MP' drefs should be called with aircraft 0. + static void Set(DREF dref, float value, std::uint8_t aircraft = 0); + + /// Sets the value of an integer dataref. + /// + /// \param dref The dataref to set. + /// \param value The value to set the dref to. + /// \param aircraft The aircraft number for which to get the data. + /// + /// \remarks This method does not verify the type of the dref being set. It is + /// the responsibility of the caller to check the X-Plane documentation + /// and call the appropriate overload of this method. If the wrong + /// overload is called, the operation will fail silently. + /// + /// \remarks Although any combination of dref and aircraft may be passed to this + /// method, most drefs are not valid for multiplayer aircraft. All drefs + /// that are not prefixed with 'MP' are valid for the player aircraft. + /// 'MP' drefs should be called with aircraft 0. + static void Set(DREF dref, int value, std::uint8_t aircraft = 0); + + /// Sets the value of a float array dataref. + /// + /// \param dref The dataref to set. + /// \param values The value to set the dref to. + /// \param size The number of items stored in values. + /// \param aircraft The aircraft number for which to get the data. + /// + /// \remarks This method does not verify the type of the dref being set. It is + /// the responsibility of the caller to check the X-Plane documentation + /// and call the appropriate overload of this method. If the wrong + /// overload is called, the operation will fail silently. + /// + /// \remarks Although any combination of dref and aircraft may be passed to this + /// method, most drefs are not valid for multiplayer aircraft. All drefs + /// that are not prefixed with 'MP' are valid for the player aircraft. + /// 'MP' drefs should be called with aircraft 0. + static void Set(DREF dref, float values[], std::size_t size, std::uint8_t aircraft = 0); + + /// Sets the value of an integer array dataref. + /// + /// \param dref The dataref to set. + /// \param values The value to set the dref to. + /// \param size The number of items stored in values. + /// \param aircraft The aircraft number for which to get the data. + /// + /// \remarks This method does not verify the type of the dref being set. It is + /// the responsibility of the caller to check the X-Plane documentation + /// and call the appropriate overload of this method. If the wrong + /// overload is called, the operation will fail silently. + /// + /// \remarks Although any combination of dref and aircraft may be passed to this + /// method, most drefs are not valid for multiplayer aircraft. All drefs + /// that are not prefixed with 'MP' are valid for the player aircraft. + /// 'MP' drefs should be called with aircraft 0. + static void Set(DREF dref, int values[], std::size_t size, std::uint8_t aircraft = 0); + + /// Sets the landing gear for the specified airplane. + /// + /// \param gear The value to set the gear to. 0 for gear down, 1 for gear up. + /// \param immediate Whether the gear should be forced to the specified position. + /// If immediate is false, only the gear handle dref will be set. + /// \param aircraft The aircraft to set the landing gear status on. static void SetGear(float gear, bool immediate, std::uint8_t aircraft = 0); + /// Sets the position of the specified aircraft on the Earth. + /// + /// \param pos An array containing latitude, longitude and altitude in + /// fractional degrees and meters above sea level. + /// \param aircraft The aircraft to set the position of. static void SetPosition(float pos[3], std::uint8_t aircraft = 0); + /// Sets the orientation of the specified aircraft. + /// + /// \param orient An array containing the pitch, roll, and yaw orientations + /// to set, all in fractional degrees. + /// \param aircraft The aircraft to set the orientation of. static void SetOrientation(float orient[3], std::uint8_t aircraft = 0); + /// Sets flaps on the the player aircraft. + /// + /// \param value The flaps settings. Should be between 0.0 (no flaps) and 1.0 (full flaps). static void SetFlaps(float value); }; } diff --git a/xpcPlugin/DataMaps.h b/xpcPlugin/DataMaps.h index def994f..ef600b7 100644 --- a/xpcPlugin/DataMaps.h +++ b/xpcPlugin/DataMaps.h @@ -6,6 +6,7 @@ namespace XPC { + /// Maps X-Plane dataref lines to XPC DREF values. extern DREF XPData[134][8]; } diff --git a/xpcPlugin/Log.h b/xpcPlugin/Log.h index 3458c3f..136e103 100644 --- a/xpcPlugin/Log.h +++ b/xpcPlugin/Log.h @@ -4,7 +4,18 @@ #define XPC_LOG_H #include -#define LOG_VERBOSITY 999 +// LOG_VERBOSITY determines the level of logging throughout the plugin. +// 0: Minimum logging. Only plugin manager events will be logged. +// 1: Critical errors. When an error that prevents correct operation of the +// plugin, attempt to write useful information to the log. Note that since +// XPC runs inside the X-Plane executable, we try very hard no to crash. +// As a result, these log messages may be the only indication of failure. +// 2: All errors. Any time something unexpected happens, log it. +// 3: Significant actions. Any time something happens outside of normal +// command processing, log it. +// 4: Everything. Log nearly every single action the plugin takes. This may +// have a detrimental impact on X-Plane performance. +#define LOG_VERBOSITY 2 namespace XPC { diff --git a/xpcPlugin/MessageHandlers.h b/xpcPlugin/MessageHandlers.h index 544023a..7db08e2 100644 --- a/xpcPlugin/MessageHandlers.h +++ b/xpcPlugin/MessageHandlers.h @@ -10,13 +10,31 @@ namespace XPC { + /// A function that handles a message. typedef void(*MessageHandler)(Message&); + /// Handles incommming messages and manages connections. + /// + /// \author Jason Watkins + /// \version 1.0 + /// \since 1.0 + /// \date Intial Version: 2015-04-12 + /// \date Last Updated: 2015-04-12 class MessageHandlers { public: + /// The first stop for all messages to the plugin after they are read from the + /// socket. + /// + /// \details After a message is read, HandleMessage analyzes the sender's network address + /// to determine whether the sender is a new client. It then either loads + /// connection details for an existing client, or creates a new connection record + /// for new clients. Finally, the message handler checks the message type and + /// dispatches the message to the appropriate handler. + /// \param msg The message to be processed. static void HandleMessage(Message& msg); + /// Sets the socke that message handlers use to send responses. static void SetSocket(UDPSocket* socket); private: @@ -44,9 +62,9 @@ namespace XPC static std::unordered_map connections; static std::unordered_map handlers; - static std::string connectionKey; - static ConnectionInfo connection; - static UDPSocket* sock; + static std::string connectionKey; // The current connection ip:port string + static ConnectionInfo connection; // The current connection record + static UDPSocket* sock; // Outgoing network socket }; }