SimConnect_CreateClientData
The SimConnect_CreateClientData function is used to request the creation of a reserved data area for this client.
Syntax
HRESULT SimConnect_CreateClientData(
HANDLE hSimConnect,
SIMCONNECT_CLIENT_DATA_ID ClientDataID,
DWORD dwSize,
SIMCONNECT_CREATE_CLIENT_DATA_FLAG Flags
);
Parameters
Parameter | Description | Type |
---|---|---|
hSimConnect | Handle to a SimConnect object. | Integer |
ClientDataID | ID of the client data area. Before calling this function, call SimConnect_MapClientDataNameToID to map an ID to a unique client area name. | Integer |
dwSize | Double word containing the size of the data area in bytes. | Integer |
Flags | Specify the flag SIMCONNECT_CREATE_CLIENT_DATA_FLAG_READ_ONLY if the data area can only be written to by this client (the client creating the data area). By default other clients can write to this data area. |
Integer |
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
Use this function, along with the other client data functions, to reserve an area of memory for client data on the server, that other clients can have read (or read and write) access to. Specify the contents of the data area with the SimConnect_AddToClientDataDefinition call, and set the actual values with a call to SimConnect_SetClientData. Other clients can receive the data with a call to SimConnect_RequestClientData.
The maximum size of a client data area is set by the constant SIMCONNECT_CLIENTDATA_MAX_SIZE
, which is 8K.There is no maximum number of client data areas, but the total must not exceed 1Mbyte. If a request is made for a client data area greater than SIMCONNECT_CLIENTDATA_MAX_SIZE
a SIMCONNECT_EXCEPTION_INVALID_DATA_SIZE
exception is returned. If a request is made for a client data area that will exceed the total maximum memory a SIMCONNECT_EXCEPTION_OUT_OF_BOUNDS
exception is returned.
One client area can be referenced by any number of client data definitions. Typically the name of the client area, and the data definitions, should be published appropriately so other clients can be written to use them. Care should be taken to give the area a unique name.
Once created, a client data area cannot be deleted or reduced in size. To increase the size of the data area, first close the connection, then re-open it and request the client data area again, using the same name, but with the required size. The additional data area will be initialized to zero, but the previous data will be untouched by this process. Client data persists to the end of the Microsoft Flight Simulator session, and is not removed when the client that created it is closed. It is also possible to change a read-only data area to write-able using this technique.
See Also
- SimConnect API Reference
- SimConnect_AddToClientDataDefinition
- SimConnect_ClearClientDataDefinition
- SimConnect_MapClientDataNameToID
- SimConnect_RequestClientData
- SimConnect_SetClientData