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.

 

See Also