SimConnect_RequestDataOnSimObject

The SimConnect_RequestDataOnSimObject function is used to request when the SimConnect client is to receive data values for a specific object.

Syntax

HRESULT SimConnect_RequestDataOnSimObject(
    HANDLE  hSimConnect,
    SIMCONNECT_DATA_REQUEST_ID  RequestID,
    SIMCONNECT_DATA_DEFINITION_ID  DefineID,
    SIMCONNECT_OBJECT_ID  ObjectID,
    SIMCONNECT_PERIOD  Period,
    SIMCONNECT_DATA_REQUEST_FLAG  Flags = 0,
    DWORD  origin = 0,
    DWORD  interval = 0,
    DWORD  limit = 0
    );

Parameters

Parameter	Description	Type
hSimConnect	Handle to a SimConnect object.	Integer
RequestID	Specifies the ID of the client defined group.	Integer
DefineID	Specifies the ID of the client defined data definition.	Integer
ObjectID	Specifies the ID of the Microsoft Flight Simulator object that the data should be about. This ID can be `SIMCONNECT_OBJECT_ID_USER` (to specify the user's aircraft) or obtained from a `SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE` structure after a call to `SimConnect_RequestDataOnSimObjectType`. Also refer to the note on developing clients for multiplayer mode in the Remarks section below.	Integer
Period	One member of the `SIMCONNECT_PERIOD` enumeration type, specifying how often the data is to be sent by the server and received by the client.	Integer
Flags	A DWORD containing one or more of the values shown in the table below this one.	Integer (OPTIONAL)
origin	The number of Period events that should elapse before transmission of the data begins. The default is zero, which means transmissions will start immediately.	Integer (OPTIONAL)
interval	The number of Period events that should elapse between transmissions of the data. The default is zero, which means the data is transmitted every Period.	Integer (OPTIONAL)
limit	The number of times the data should be transmitted before this communication is ended. The default is zero, which means the data should be transmitted endlessly.	Integer (OPTIONAL)

The following table shows the available values for Flags:

Flag value	Description
0	The default, data will be sent strictly according to the defined period.
`SIMCONNECT_DATA_REQUEST_FLAG_CHANGED`	Data will only be sent to the client when one or more values have changed. If this is the only flag set, then all the variables in a data definition will be returned if just one of the values changes.
`SIMCONNECT_DATA_REQUEST_FLAG_TAGGED`	Requested data will be sent in tagged format (datum ID/value pairs). Tagged format requires that a datum reference ID is returned along with the data value, in order that the client code is able to identify the variable. This flag is usually set in conjunction with the previous flag, but it can be used on its own to return all the values in a data definition in datum ID/value pairs. See the `SIMCONNECT_RECV_SIMOBJECT_DATA` structure for more details.

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_RequestDataOnSimObject(hSimConnect, REQUEST_2, DEFINITION_1, SIMCONNECT_OBJECT_ID_USER, SIMCONNECT_PERIOD_SECOND);
      ....
    case SIMCONNECT_RECV_ID_SIMOBJECT_DATA:
    {
    SIMCONNECT_RECV_SIMOBJECT_DATA *pObjData = (SIMCONNECT_RECV_SIMOBJECT_DATA*) pData;
    switch(pObjData->dwRequestID)
        {
        case REQUEST_2:
            Struct1 *pS = (Struct1*)&pObjData->dwData;
            break;
        }
    break;
    }

Remarks

Changing the Period parameter or changing the content of a data definition has a higher performance cost than changing the origin, interval or limit parameters. So to temporarily turn off data requests, especially for short periods of time, consider setting the interval parameter to a very high value (such as DWORD _MAX). If changes are required to a data definition, consider setting the Period parameter to SIMCONNECT_PERIOD_NEVER (see the SIMCONNECT_PERIOD enumeration) before making the changes, and then turning on the appropriate period after the changes have been made.

It is possible to change the period of a request, by re-sending the SimConnect_RequestDataOnSimObject call with the same RequestID, DefineID and ObjectID parameters, but with a new period. The one exception to this is the new period cannot be SIMCONNECT_PERIOD_ONCE, in this case a request with a new RequestID should be sent.

Data is always transmitted with the SimConnect_RequestDataOnSimObject function, so if timing only notifications are required, use the SimConnect_SubscribeToSystemEvent function.

Note that variable length strings should not be used in data definitions, except where the Period parameter has been set to SIMCONNECT_PERIOD_ONCE.

One method of testing whether the user has changed aircraft type is to use this function to return the title of the user aircraft, and note that if it changes, the user has changed the type of aircraft (all aircraft types have unique title strings, including those simply with different color schemes). An example of requesting the aircraft title is in the Variable Strings working sample. See the Aircraft Configuration Files document for more details on titles.

If boolean data has been requested as part of a data definition, note that the only reliable numeric equivalent is that 0 is returned for False. Non-zero values, especially both 1 and -1, are used to indicate True.

NOTE: Multiplayer Mode - When developing a client for use in multiplayer mode it is not safe to use the ID number for the user aircraft returned by the function SimConnect_RequestDataOnSimObjectType, as the actual number can change depending on several factors, including the number of users involved in the multiplayer flight. Always use the constant SIMCONNECT_OBJECT_ID_USER for the ObjectID parameter if the SimConnect client is to work in multiplayer mode. Also note that in this mode it is good practice to remove any calls associated with periodic data on AI objects and to remove subscriptions to AI objects.