The SimConnect_SetDataOnSimObject function is used to make changes to the data properties of an object.


HRESULT SimConnect_SetDataOnSimObject(
    HANDLE  hSimConnect,
    DWORD  ArrayCount,
    DWORD  cbUnitSize,
    void*  pDataSet


Parameter Description Type
hSimConnect Handle to a SimConnect object. 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 "multiplayer mode" at the end of the remarks for SimConnect_RequestDataOnSimObject. Integer
Flags Null, or one or more of the flags listed below. Flag
ArrayCount Specifies the number of elements in the data array. A count of zero is interpreted as one element. Ensure that the data array has been initialized completely before transmitting it to Microsoft Flight Simulator. Failure to properly initialize all array elements may result in unexpected behavior. Integer
cbUnitSize Specifies the size of each element in the data array in bytes. Integer
pDataSet Pointer to the data that is to be written. If the data is not in tagged format, this should point to the block of data. If the data is in tagged format this should point to the first tag name (datumID), which is always four bytes long, which should be followed by the data itself. Any number of tag name/value pairs can be specified this way, the server will use the cbUnitSize parameter to determine how much data has been sent. Integer


The table below shows the possible values for the flags parameter:

Return value Description
SIMCONNECT_DATA_SET_FLAG_TAGGED The data to be set is being sent in tagged format. If this flag is not set then the entire client data area should be replaced with new data. Refer to the pDataSet parameter and SimConnect_RequestClientData for more details on the tagged format.


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.


static enum DATA_DEFINE_ID {
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION3, "Initial Position", "NULL", SIMCONNECT_DATATYPE_INITPOSITION, 0);
    Init.Altitude = 5000.0;
    Init.Latitude = 47.64210;
    Init.Longitude = -122.13010;
    Init.Pitch = -0.0;
    Init.Bank = -1.0;
    Init.Heading = 180.0;
    Init.OnGround = 0;
    Init.Airspeed = 0;
SimConnect_SetDataOnSimObject(hSimConnect, DEFINITION3, SIMCONNECT_OBJECT_ID_USER, 0, sizeof(Init), &Init);



The data that is set on an object is defined in a data definition (see the SimConnect_AddToDataDefinition function). This data can include the following structures: SIMCONNECT_DATA_WAYPOINT, SIMCONNECT_DATA_INITPOSITION, and SIMCONNECT_DATA_MARKERSTATE. Any number of waypoints can be given to an AI object using a single call to this function, and any number of marker state structures can also be combined into an array.


The Simulation Variables documents include a column indicating whether variables can be written to or not. An exception will be returned if an attempt is made to write to a variable that cannot be set in this way.


See Also