FlightSim-Streaming/XPlaneConnectCSP
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Expanded doc comments.

Browse Source 
- 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.
This commit is contained in:
Jason Watkins
2015-04-14 12:59:20 -07:00
parent 96d1d68123
commit 5944fb5818
4 changed files with 279 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

255
xpcPlugin/DataManager.h
View File

@@ -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);
};
}

1
xpcPlugin/DataMaps.h
View File

@@ -6,6 +6,7 @@
namespace XPC
{
/// Maps X-Plane dataref lines to XPC DREF values.
extern DREF XPData[134][8];
}

13
xpcPlugin/Log.h
View File

@@ -4,7 +4,18 @@
#define XPC_LOG_H
#include <string>
#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
{

24
xpcPlugin/MessageHandlers.h
View File

@@ -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<std::string, ConnectionInfo> connections;
static std::unordered_map<std::string, MessageHandler> 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
};
}