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.