SimConnect_AddToClientDataDefinition
The SimConnect_AddToClientDataDefinition function is used to add an offset and a size in bytes, or a type, to a client data definition.
Syntax
HRESULT SimConnect_AddToClientDataDefinition(
HANDLE hSimConnect,
SIMCONNECT_CLIENT_DATA_DEFINITION_ID DefineID,
DWORD dwOffset,
DWORD dwSizeOrType,
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 client data definition. | Integer |
dwOffset | Double word containing the offset into the client area, where the new addition is to start. Set this to SIMCONNECT_CLIENTDATAOFFSET_AUTO for the offsets to be calculated by the SimConnect server. |
|
dwSizeOrType | Double word containing either the size of the client data in bytes, or one of the constant values defined in the table below (note that these definitions have a negative value, all positive values will be treated as a size parameter). | Integer |
fEpsilon | If data is requested only when it changes (see the flags parameter of SimConnect_RequestClientData, 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). This parameter only applies if one of the six constant values listed above has been set in the dwSizeOrType parameter, if a size has been specified SimConnect has no record of the type of data being sent, so cannot do a meaningful comparison of values. |
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_RequestClientData. There is no need to specify datum IDs if the data is not being returned in tagged format. |
Integer (OPTIONAL) |
The following table shows the different dwSizeOrType constants that can be used:
Constant | Value |
---|---|
SIMCONNECT_CLIENTDATATYPE_INT8 |
-1 |
SIMCONNECT_CLIENTDATATYPE_INT16 |
-2 |
SIMCONNECT_CLIENTDATATYPE_INT32 |
-3 |
SIMCONNECT_CLIENTDATATYPE_INT64 |
-4 |
SIMCONNECT_CLIENTDATATYPE_FLOAT32 |
-5 |
SIMCONNECT_CLIENTDATATYPE_FLOAT64 |
-6 |
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. |
Remarks
This function must be called before a client data area can be written to or read from. Typically this function would be called once for each variable that is going to be read or written. Note that an error will not be given if the size of a data definition exceeds the size of the client area - this is to allow for the case where definitions are specified by one client before the relevant client area is created by another.
The most efficient use of client data areas is to group data that changes at the same time into the same data area. Minor performance improvements are gained by not using tagged data, or the fEpsilon parameter, if they are not needed.
See Also
- SimConnect API Reference
- SimConnect_ClearClientDataDefinition
- SimConnect_CreateClientData
- SimConnect_MapClientDataNameToID
- SimConnect_RequestClientData
- SimConnect_SetClientData