SimConnect_AddToDataDefinition

The SimConnect_AddToDataDefinition function is used to add a Microsoft Flight Simulator simulation variable name to a client defined object definition.

Syntax

HRESULT SimConnect_AddToDataDefinition(
    HANDLE  hSimConnect,
    SIMCONNECT_DATA_DEFINITION_ID  DefineID,
    const char*  DatumName,
    const char*  UnitsName,
    SIMCONNECT_DATATYPE  DatumType = SIMCONNECT_DATATYPE_FLOAT64,
    float  fEpsilon = 0,
    DWORD  DatumID = SIMCONNECT_UNUSED
    );

Parameters

Parameter	Description	Type
hSimConnect	Handle to a SimConnect object.	Integer
DefineID	Specifies the ID of the client defined data definition.	Integer
DatumName	Specifies the name of the Microsoft Flight Simulator simulation variable. See the Simulation Variables documents for tables of variable names. If an index is required then it should be appended to the variable name following a colon, see the example for DEFINITION_2 below. Indexes are numbered from 1 (not zero). Simulation variable names are not case-sensitive (so can be entered in upper or lower case).	Integer
UnitsName	Specifies the units of the variable. See Simulation Variable Units for tables of acceptable unit names. It is possible to specify different units to receive the data in, from those specified in the Simulation Variables document. The alternative units must come under the same heading (such as Angular Velocity, or Volume, as specified in the Units of Measurement section of the Simulation Variables document). For strings and structures enter "NULL" for this parameter.	Integer
DatumType	One member of the SIMCONNECT_DATATYPE enumeration type. This parameter is used to determine what datatype should be used to return the data. The default is `SIMCONNECT_DATATYPE_FLOAT64`. Note that the structure data types are legitimate parameters here.	Integer (OPTIONAL)
fEpsilon	If data is requested only when it changes (see the flags parameter of SimConnect_RequestDataOnSimObject) a change will only be reported if it is greater than the value of this parameter (not greater than or equal to). The default is zero, so even the tiniest change will initiate the transmission of data. Set this value appropriately so insignificant changes are not transmitted. This can be used with integer data, the floating point fEpsilon value is first truncated to its integer component before the comparison is made (for example, an fEpsilon value of 2.9 truncates to 2, so a data change of 2 will not trigger a transmission, and a change of 3 will do so).	Float (OPTIONAL)
DatumID	Specifies a client defined datum ID. The default is zero. Use this to identify the data received if the data is being returned in tagged format (see the flags parameter of SimConnect_RequestDataOnSimObject. There is no need to specify datum IDs if the data is not being returned in tagged format.	Integer (OPTIONAL)

Return Values

The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return value	Description
S_OK	The function succeeded.
E_FAIL	The function failed.

Example

static enum DATA_DEFINE_ID {
    DEFINITION_1,
    DEFINITION_2
    };
static enum DATA_REQUEST_ID {
    REQUEST_1,
    REQUEST_2,
    };
struct Struct1
    {
    double  kohlsmann;
    double  altitude;
    double  latitude;
    double  longitude;
    };
      
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_1, "Kohlsman setting hg", "inHg");
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_1, "Indicated Altitude", "feet");
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_1, "Plane Latitude", "degrees");
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_1, "Plane Longitude", "degrees");
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_2, "GENERAL ENG RPM:1", "rpm");
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_2, "GENERAL ENG RPM:2", "revolutions per minute");
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_2, "GENERAL ENG RPM:3", "degrees per second");
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_2, "GENERAL ENG RPM:4", "minutes per round");
      ....
hr = SimConnect_RequestDataOnSimObject(hSimConnect, REQUEST_1, DEFINITION_1, SIMCONNECT_OBJECT_ID_USER, SIMCONNECT_PERIOD_ONCE);
      ....
    case SIMCONNECT_RECV_ID_SIMOBJECT_DATA:
        {
        SIMCONNECT_RECV_SIMOBJECT_DATA *pObjData = (SIMCONNECT_RECV_SIMOBJECT_DATA*)pData;
        switch(pObjData->dwRequestID)
            {
            case REQUEST_1:
                Struct1 *pS = (Struct1*)&pObjData->dwData;
                break;
            }
        break;
        }

Remarks

The maximum number of entries in a data definition is 1000.

L Vars

It is possible to get and/or set an RPN "L" variable through SimConnect using the SimConnect_AddToDataDefinition function, for example:

SimConnect_AddToDataDefinition(hSimConnect, DataDefinitionID, "L:VARIABLE_NAME", "number", SIMCONNECT_DATATYPE_FLOAT64);

However, when working with "L" vars, it is important to note that:

"L" variables are shared by everytheing without any priority, essentially making them "global" in scope. They can be used by audio, animation, cockpit, etc... which means that the "L" vars you get using SimConnect may be the same that are used by - for example - audio, so if you update this var, the audio will also be updated. Futhermore, if two SimConnect clients try to access the same "L" Var, the last one which updates the Var is correct and sets the new value for everything.
It is possible to give a unit to an "L" var, in which case the variable's type will change and a conversion will be made if necessary.
"L" variables are only FLOAT64.