SimConnect_RequestClientData
The SimConnect_RequestClientData function is used to request that the specified data in an area created by another client be sent to this client.
Syntax
HRESULT SimConnect_RequestClientData(
HANDLE hSimConnect,
SIMCONNECT_CLIENT_DATA_ID ClientDataID,
SIMCONNECT_DATA_REQUEST_ID RequestID,
SIMCONNECT_CLIENT_DATA_DEFINITION_ID DefineID,
SIMCONNECT_CLIENT_DATA_PERIOD Period = SIMCONNECT_CLIENT_DATA_PERIOD_ONCE,
SIMCONNECT_CLIENT_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 |
| ClientDataID | Specifies the ID of the client data area. Before calling this function for the first time on one client area, call SimConnect_MapClientDataNameToID to map an ID to the unique client data area name. This name must match the name specified by the client creating the data area with the SimConnect_MapClientDataNameToID and SimConnect_CreateClientData functions. | Integer |
| RequestID | Specifies the ID of the client-defined request. This is used later by the client to identify which data has been received. This value should be unique for each request, re-using a RequestID will overwrite any previous request using the same ID. | Integer |
| DefineID | Specifies the ID of the client-defined data definition. This definition specifies the data that should be sent to the client. | Integer |
| Period | One member of the SIMCONNECT_CLIENT_DATA_PERIOD enumeration type, specifying how often the data is to be sent by the server and received by the client. | Integer (OPTIONAL) |
| Flags | A DWORD containing one or more of the values from the table below. | 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 table below lists the available values that can be used with the Flags parameter:
| Flag Value | Description |
|---|---|
| 0 | The default, data will be sent strictly according to the defined period. |
| SIMCONNECT_CLIENT_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_CLIENT_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_CLIENT_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. |
Remarks
A data definition must be specified, using the SimConnect_AddToClientDataDefinition function, before this function can be called If the data definition exceeds the size of the client data area on the server, then the extra bytes will be filled with zeros, an error will not be returned.
The data will be returned in a SIMCONNECT_RECV_CLIENT_DATA structure.
See the remarks for SimConnect_RequestDataOnSimObject, as the two functions work in a very similar manner.
This function has been updated for the SP1a release of the SDK, expanding on its functionality.