Overview
To view a list of all general SimConnect functions, see the General Functions table.DispatchProc
The DispatchProc function is a written by the developer of the SimConnect client, as a callback function to handle all the communications with the server.
Syntax
SIMCONNECT_RECV* pData,
DWORD cbData,
void * pContext
);
Parameters
- pData
- [in] Pointer to a data buffer, to be treated initially as a SIMCONNECT_RECV structure. If you are going to make a copy of the data buffer (which is maintained by the SimConnect client library) make sure that the defined buffer is large enough (the size of the returned data structure is one member of the SIMCONNECT_RECV structure.
- cbData
- [in] The size of the data buffer, in bytes.
- pContext
- [in] Contains the pointer specified by the client in the SimConnect_CallDispatch function call.
Return Values
This function does not return a value.
Example
{
switch(pData->dwID)
{
case SIMCONNECT_RECV_ID_OPEN:
// enter code to handle SimConnect version information received in a SIMCONNECT_RECV_OPEN structure.
SIMCONNECT_RECV_OPEN *openData = (SIMCONNECT_RECV_OPEN*) pData;
break;
case SIMCONNECT_RECV_ID_EVENT:
// enter code to handle events received in a SIMCONNECT_RECV_EVENT structure.
SIMCONNECT_RECV_EVENT *evt = (SIMCONNECT_RECV_EVENT*) pData;
break;
case SIMCONNECT_RECV_ID_EVENT_64:
// enter code to handle events received in a SIMCONNECT_RECV_EVENT_64 structure.
SIMCONNECT_RECV_EVENT_64 *evt = (SIMCONNECT_RECV_EVENT_64*) pData;
break;
case SIMCONNECT_RECV_ID_EVENT_FILENAME:
// enter code to handle event filenames received in a SIMCONNECT_RECV_EVENT_FILENAME
// structure.
SIMCONNECT_RECV_EVENT_FILENAME *evt = (SIMCONNECT_RECV_EVENT_FILENAME*) pData;
break;
case SIMCONNECT_RECV_ID_EVENT_OBJECT_ADDREMOVE:
// enter code to handle AI objects that have been added or removed, and received in a SIMCONNECT_RECV_EVENT_OBJECT_ADDREMOVE
// structure.
SIMCONNECT_RECV_EVENT_OBJECT_ADDREMOVE *evt = (SIMCONNECT_RECV_EVENT_OBJECT_ADDREMOVE*) pData;
break;
case SIMCONNECT_RECV_ID_EVENT_FRAME:
// enter code to handle frame data received in a SIMCONNECT_RECV_EVENT_FRAME
// structure.
SIMCONNECT_RECV_EVENT_FRAME *evt = (SIMCONNECT_RECV_EVENT_FRAME*) pData;
break;
case SIMCONNECT_RECV_ID_SIMOBJECT_DATA:
// enter code to handle object data received in a SIMCONNECT_RECV_SIMOBJECT_DATA structure.
SIMCONNECT_RECV_SIMOBJECT_DATA *pObjData = (SIMCONNECT_RECV_SIMOBJECT_DATA*) pData;
break;
case SIMCONNECT_RECV_ID_SIMOBJECT_DATA_BYTYPE:
// enter code to handle object data received in a SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE
// structure.
SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE *pObjData = (SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE*) pData;
break;
case SIMCONNECT_RECV_ID_QUIT:
// enter code to handle exiting the application
break;
case SIMCONNECT_RECV_ID_EXCEPTION:
// enter code to handle errors received in a SIMCONNECT_RECV_EXCEPTION structure.
SIMCONNECT_RECV_EXCEPTION *except = (SIMCONNECT_RECV_EXCEPTION*) pData;
break;
case SIMCONNECT_RECV_ID_WEATHER_OBSERVATION:
// enter code to handle object data received in a SIMCONNECT_RECV_WEATHER_OBSERVATION structure.
SIMCONNECT_RECV_WEATHER_OBSERVATION* pWxData = (SIMCONNECT_RECV_WEATHER_OBSERVATION*) pData;
const char* pszMETAR = (const char*) (pWxData+1);
break;
// Enter similar case statements to handle the other types of data that can be received, including:
// SIMCONNECT_RECV_ID_ASSIGNED_OBJECT_ID,
// SIMCONNECT_RECV_ID_RESERVED_KEY,
// SIMCONNECT_RECV_ID_CUSTOM_ACTION
// SIMCONNECT_RECV_ID_SYSTEM_STATE
// SIMCONNECT_RECV_ID_CLOUD_STATE
default:
// enter code to handle the case where an unexpected message is received
break;
}
}
Working Samples
Primary samples |
Client Event Tracking Errors |
Reference samples | All but a few of the other samples implement this function. |
Remarks
This function can be named appropriately by the client developer. The name of the function is passed to the client-side library with the SimConnect_CallDispatch function call. Handle all the callback events in this function. If you do not wish to implement a callback function use SimConnect_GetNextDispatch.
To receive time based notifications, see the SimConnect_SubscribeToSystemEvent function. To receive event based notifications see the SimConnect_AddClientEventToNotificationGroup function. To send an event to be received by other clients, see the SimConnect_TransmitClientEvent function.
See Also
SimConnect_AddClientEventToNotificationGroup
The SimConnect_AddClientEventToNotificationGroup function is used to add an individual client defined event to a notification group.
Syntax
HANDLE hSimConnect,
SIMCONNECT_NOTIFICATION_GROUP_ID GroupID,
SIMCONNECT_CLIENT_EVENT_ID EventID,
BOOL bMaskable = FALSE
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- GroupID
- [in] Specifies the ID of theclient defined group.
- EventID
- [in] Specifies the ID of theclient defined event.
- bMaskable
- [in, optional] Boolean, True indicates that the event will be masked by this client and will not be transmitted to any more clients, possibly including Prepar3D itself (if the priority of the client exceeds that of Prepar3D). False is the default. See the explanation of SimConnect Priorities.
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. |
Example
EVENT_1,
EVENT_2
EVENT_3
};
static enum GROUP_ID {
GROUP_1,
};
hr = SimConnect_AddClientEventToNotificationGroup(hSimConnect, GROUP_1, EVENT_1);
hr = SimConnect_AddClientEventToNotificationGroup(hSimConnect, GROUP_1, EVENT_2);
hr = SimConnect_AddClientEventToNotificationGroup(hSimConnect, GROUP_1, EVENT_3, TRUE);
hr = SimConnect_SetNotificationGroupPriority(hSimConnect, GROUP_1, SIMCONNECT_GROUP_PRIORITY_HIGHEST);
Working Samples
Primary samples |
Client Event Cockpit Camera Joystick Input Menu Items Send Event A Send Event B Send Event C Tracking Errors |
Reference samples | Many of the other samples implement this function. |
Remarks
The maximum number of events that can be added to a notification group is 1000. A notification group is simply a convenient way of setting the appropriate priority for a range of events, and all client events (such as EVENT_1, EVENT_2, EVENT_3 in the example above) must be assigned to a notification group before any event notifications will be received from the SimConnect server.
See Also
- SimConnect API Reference
- SimConnect_RemoveClientEvent
- SimConnect_SetNotificationGroupPriority
- SimConnect_ClearNotificationGroup
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
HANDLE hSimConnect,
SIMCONNECT_CLIENT_DATA_DEFINITION_ID DefineID,
DWORD dwOffset,
DWORD dwSizeOrType,
float fEpsilon = 0,
DWORD DatumID = SIMCONNECT_UNUSED
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- DefineID
- [in] Specifies the ID of the client-defined client data definition.
- dwOffset
- [in] 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
- [in] Double word containing either the size of the client data in bytes, or one of the following defined values (note that these definitions have a negative value, all positive values will be treated as a size parameter.
-
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 - fEpsilon
- [in, optional] 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.
- DatumID
- [in, optional] 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.
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_ClearClientDataDefinition
- SimConnect_CreateClientData
- SimConnect_MapClientDataNameToID
- SimConnect_RequestClientData
- SimConnect_SetClientData
- SimConnect API Reference
SimConnect_AddToDataDefinition
The SimConnect_AddToDataDefinition function is used to add a Prepar3D simulation variable name to a client defined object definition.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_DEFINITION_ID DefineID,
const char* DatumName,
const char* UnitsName,
SIMCONNECT_DATATYPE DatumType = SIMCONNECT_DATATYPE_FLOAT64,
float fEpsilon = 0,
DWORD DatumID = SIMCONNECT_UNUSED
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- DefineID
- [in] Specifies the ID of the client defined data definition.
- DatumName
- [in] Specifies the name of the Prepar3D simulation variable. See the Simulation Variables document for a table of variable names. If an index is required then it should be appended to the variable name following a colon, see the example for DEFINITION_2 below. Indexes are numbered from 1 (not zero). Simulation variable names are not case-sensitive (so can be entered in upper or lower case).
- UnitsName
- [in] Specifies the units of the variable. See the Simulation Variables document for a table of acceptable unit names. It is possible to specify different units to receive the data in, from those specified in the Simulation Variables document. See DEFINITION_2 below for an example. The alternative units must come under the same heading (such as Angular Velocity, or Volume, as specified in the Units of Measurement section of the Simulation Variables document). For strings and structures enter "NULL" for this parameter.
- DatumType
- [in, optional] One member of the SIMCONNECT_DATATYPE enumeration type. This parameter is used to determine what datatype should be used to return the data. The default is SIMCONNECT_DATATYPE_FLOAT64. Note that the structure data types are legitimate parameters here.
- fEpsilon
- [in, optional] If data is requested only when it changes (see the flags parameter of SimConnect_RequestDataOnSimObject), 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).
- DatumID
- [in, optional] 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_RequestDataOnSimObject). There is no need to specify datum IDs if the data is not being returned in 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. |
Example
DEFINITION_1,
DEFINITION_2
};
static enum DATA_REQUEST_ID {
REQUEST_1,
REQUEST_2,
};
struct Struct1
{
double kohlsmann;
double altitude;
double latitude;
double longitude;
};
// Match string definitions from the Simulation Variables document with the client defined ID
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_1, "Kohlsman setting hg", "inHg");
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_1, "Indicated Altitude", "feet");
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_1, "Plane Latitude", "degrees");
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_1, "Plane Longitude", "degrees");
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_2, "GENERAL ENG RPM:1", "rpm");
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_2, "GENERAL ENG RPM:2", "revolutions per minute");
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_2, "GENERAL ENG RPM:3", "degrees per second");
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_2, "GENERAL ENG RPM:4", "minutes per round");
// Sections of code in DispatchProc
// At the right point request the data
// In this example the data is being requested on the user aircraft
....
hr = SimConnect_RequestDataOnSimObject(hSimConnect, REQUEST_1, DEFINITION_1,SIMCONNECT_OBJECT_ID_USER, SIMCONNECT_PERIOD_ONCE);
....
// When the data is received -- cast it to the correct structure type
case SIMCONNECT_RECV_ID_SIMOBJECT_DATA:
{
SIMCONNECT_RECV_SIMOBJECT_DATA *pObjData = (SIMCONNECT_RECV_SIMOBJECT_DATA*)pData;
switch(pObjData->dwRequestID)
{
case REQUEST_1:
Struct1 *pS = (Struct1*)&pObjData->dwData;
// Add code to process the structure appropriately
break;
}
break;
}
....
Working Samples
Primary samples |
Request Data
Set Data Tagged Data Throttle Control |
Remarks
The maximum number of entries in a data definition is 1000.
See Also
- SimConnect API Reference
- SimConnect_ClearDataDefinition
- SimConnect_RequestDataOnSimObject
- SimConnect_RequestDataOnSimObjectType
SimConnect_CallDispatch
The SimConnect_CallDispatch function is used to process the next SimConnect message received, through the specified callback function.
Syntax
HANDLE hSimConnect,
DispatchProc pfcnDispatch,
void * pContext
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- pfcnDispatch
- [in] Specifies the callback function. For a definition of the function see DispatchProc.
- pContext
- [in] Specifies a pointer that the client can define that will be returned in the callback. This is used in particular by managed code clients to pass a this pointer to the callback.
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. |
Example
....
//
while( quit == 0 )
{
hr = SimConnect_CallDispatch(hSimConnect, MyDispatchProc, NULL);
};
Working Samples
Primary samples |
Client Event Tracking Errors |
Reference samples | All but a few of the other samples implement this function. |
Remarks
It is important to call this function sufficiently frequently that the queue of information received from the server is processed (typically it is coded within a while loop that terminates when the application is exited). However, if the project involves developing a library (DLL) rather than an application (EXE) then only one call to this function is necessary. This call will store the name of the callback in a cache, and whenever a packet is sent to the client, the callback function will be run. The format of a DLL project is shown in the following table:
HANDLE hSimConnect = NULL;
void CALLBACK MyDispatchProcDLL(SIMCONNECT_RECV* pData, DWORD cbData, void *pContext)
{
// Callback code for a DLL is no different than for an EXE
}
//
// The DLLStart function must be present.
//
int __stdcall DLLStart(void)
{
HRESULT hr;
if (SUCCEEDED(SimConnect_Open(&hSimConnect, "DLL name", NULL, 0, NULL, 0)))
{
printf("\nConnected...");
// Place all initialization code for the client in this function
hr = SimConnect_CallDispatch(hSimConnect, MyDispatchProcDLL, NULL);
}
return 0;
}
//
// The DLLStop function must be present.
//
void __stdcall DLLStop(void)
{
// Close the client
if (hSimConnect != NULL)
HRESULT hr = SimConnect_Close(hSimConnect);
}
In order to implement SimConnect as a class, and maintain an object-oriented design of an add-on, the following constructs can be used. Note in particular the static function and the use of the pContext parameter.
{
void Dispatch();
static void DispatchCallback(SIMCONNECT_RECV *pData, DWORD cbData, void *pContext);
void Process(SIMCONNECT_RECV *pData, DWORD cbData);
HANDLE hSimConnect; // use SimConnect_Open to set this value.
};
void CName::Dispatch()
{
::SimConnect_Dispatch(hSimConnect, &CName::DispatchCallback, this);
}
// static function
void CName::DispatchCallback(SIMCONNECT_RECV *pData, DWORD cbData, void *pContext)
{
CName *pThis = reinterpret_cast<CName*>(pContext);
pThis->Process(pData, cbData);
}
void CName::Process(SIMCONNECT_RECV *pData, DWORD cbData)
{
// do processing of SimConnect data
}
See Also
SimConnect_ClearClientDataDefinition
The SimConnect_ClearClientDataDefinition function is used to clear the definition of the specified client data.
Syntax
HANDLE hSimConnect,
SIMCONNECT_CLIENT_DATA_DEFINITION_ID DefineID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- DefineID
- [in] Specifies the ID of the client defined client data definition.
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
None.
See Also
- SimConnect_AddToClientDataDefinition
- SimConnect_CreateClientData
- SimConnect_MapClientDataNameToID
- SimConnect_RequestClientData
- SimConnect_SetClientData
- SimConnect API Reference
SimConnect_ClearDataDefinition
The SimConnect_ClearDataDefinition function is used to remove all simulation variables from a client defined data definition.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_DEFINITION_ID DefineID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- DefineID
- [in] Specifies the ID of the client defined data definition.
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. |
Example
DEFINITION_1,
DEFINITION_2
};
....
// Match string definitions from the Simulation Variables document with the client defined ID
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_1, "Kohlsman setting hg", "inHg");
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_1, "Indicated Altitude", "feet");
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_1, "Plane Latitude", "degrees");
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_1, "Plane Longitude", "degrees");
....
hr = SimConnect_ClearDataDefinition(hSimConnect, DEFINITION_1);
....
Remarks
Use this function to permanently delete a data definition. To temporarily suspend data requests see the remarks for the SimConnect_RequestDataOnSimObject function.
See Also
- SimConnect API Reference
- SimConnect_AddToDataDefinition
- SimConnect_RequestDataOnSimObject
- SimConnect_RequestDataOnSimObjectType
SimConnect_ClearInputGroup
The SimConnect_ClearInputGroup function is used to remove all the input events from a specified input group object.
Syntax
HANDLE hSimConnect
SIMCONNECT_INPUT_GROUP_ID GroupID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- GroupID
- [in] Specifies the ID of the client defined input group that is to have all its events removed.
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. |
Example
INPUT_1,
};
static enum EVENT_ID {
EVENT_1,
};
hr = SimConnect_MapClientEventToSimEvent(hSimConnect, EVENT_1, "parking_brakes");
hr = SimConnect_MapInputEventToClientEvent(hSimConnect, INPUT_1, "a+B", EVENT_1);
....
hr = SimConnect_ClearInputGroup(hSimConnect, INPUT_1);
Remarks
Use this function to permanently delete an input group. Use the SimConnect_SetInputGroupState function to temporarily suspend input group notifications.
See Also
- SimConnect API Reference
- SimConnect_MapInputEventToClientEvent
- SimConnect_SetInputGroupPriority
- SimConnect_RemoveInputEvent
- SimConnect_SetInputGroupState
SimConnect_ClearNotificationGroup
The SimConnect_ClearNotificationGroup function is used to remove all the client defined events from a notification group.
Syntax
HANDLE hSimConnect,
SIMCONNECT_NOTIFICATION_GROUP_ID GroupID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- GroupID
- [in] Specifies the ID of the client defined group that is to have all its events removed.
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. |
Example
EVENT_1,
EVENT_2
EVENT_3
};
static enum GROUP_ID {
GROUP_1,
};
hr = SimConnect_AddClientEventToNotificationGroup(hSimConnect, GROUP_1, EVENT_1);
hr = SimConnect_AddClientEventToNotificationGroup(hSimConnect, GROUP_1, EVENT_2);
hr = SimConnect_AddClientEventToNotificationGroup(hSimConnect, GROUP_1, EVENT_3, TRUE);
hr = SimConnect_ClearNotificationGroup(hSimConnect, GROUP_1);
Remarks
There is a maximum of 20 notification groups in any SimConnect client. Use this function if the maximum has been reached, but one or more are not longer required.
See Also
- SimConnect API Reference
- SimConnect_AddClientEventToNotificationGroup
- SimConnect_RemoveClientEvent
- SimConnect_SetNotificationGroupPriority
SimConnect_Close
The SimConnect_Close function is used to request that the communication with the server is ended.
Syntax
HANDLE hSimConnect
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
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. |
Example
Working Samples
Primary samples |
Open and Close Windows Event |
Reference samples | All of the other samples implement this function. |
Remarks
When a SimConnect client is closed, the server will remove all objects, menu items, group definitions and so on, defined or requested by that client, so there is no need to remove them explicitly in the client code.
See Also
SimConnect_CreateClientData
The SimConnect_CreateClientData function is used to request the creation of a reserved data area for this client.
Syntax
HANDLE hSimConnect,
SIMCONNECT_CLIENT_DATA_ID ClientDataID,
DWORD dwSize,
SIMCONNECT_CREATE_CLIENT_DATA_FLAG Flags
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- ClientDataID
- [in] ID of the client data area. Before calling this function, call SimConnect_MapClientDataNameToID to map an ID to a unique client area name.
- dwSize
- [in] Double word containing the size of the data area in bytes.
- Flags
- [in] 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.
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. For the RTM version of Prepar3D this is 8K. There is no maximum number of client data areas, but the total must not exceed 1Mbyte for the RTM version. 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 Prepar3D 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_AddToClientDataDefinition
- SimConnect_ClearClientDataDefinition
- SimConnect_MapClientDataNameToID
- SimConnect_RequestClientData
- SimConnect_SetClientData
- SimConnect API Reference
SimConnect_GetLastSentPacketID
The SimConnect_GetLastSentPacketID function returns the ID of the last packet sent to the SimConnect server.
Syntax
HANDLE hSimConnect,
DWORD* pdwSendID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- pdwSendID
- [out] Pointer to a double word containing the ID of the last sent packet.
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. |
Example
hr = SimConnect_MapClientEventToSimEvent(hSimConnect, EVENT_MY_EVENT, "Custom.Event");
hr = SimConnect_TransmitClientEvent(hSimConnect, 0, EVENT_MY_EVENT, 0, SIMCONNECT_GROUP_PRIORITY_HIGHEST, 0);
// Get the Send ID of the last transmission to the server
hr = SimConnect_GetLastSentPacketID(hSimConnect, &dwLastID);
Working Sample
Primary sample | Tracking Errors |
Remarks
This function should be used in conjunction with returned structures of type SIMCONNECT_RECV_EXCEPTION to help pinpoint errors (exceptions) returned by the server. This is done by matching the send ID returned with the exception, with the number returned by this function and stored appropriately. This function is primarily intended to be used while debugging and testing the client application, rather than in a final retail build.
See Also
SimConnect_GetNextDispatch
The SimConnect_GetNextDispatch function is used to process the next SimConnect message received, without the use of a callback function.
Syntax
HANDLE hSimConnect,
SIMCONNECT_RECV** ppData,
DWORD* pcbData
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- ppData
- [in] Pointer to a pointer to a data buffer, initially to be treated as a SIMCONNECT_RECV structure. If you are going to make a copy of the data buffer (which is maintained by the SimConnect client library) make sure that the defined buffer is large enough (the size of the returned data structure is one member of the SIMCONNECT_RECV structure.
- pcbData
- [in] Pointer to the size of the data buffer, in bytes.
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. |
Example
DWORD cbData;
hr = SimConnect_GetNextDispatch(hSimConnect, &pData, &cbData);
if (SUCCEEDED(hr))
{
switch(pData->dwID)
{
case SIMCONNECT_RECV_ID_OPEN:
// enter code to handle SimConnect version information received in a SIMCONNECT_RECV_OPEN structure.
SIMCONNECT_RECV_OPEN *openData = (SIMCONNECT_RECV_OPEN*) pData;
break;
case SIMCONNECT_RECV_ID_EVENT:
// enter code to handle events received in a SIMCONNECT_RECV_EVENT> structure.
SIMCONNECT_RECV_EVENT *evt = (SIMCONNECT_RECV_EVENT*) pData;
break;
case SIMCONNECT_RECV_ID_EVENT_FILENAME:
// enter code to handle event filenames received in a SIMCONNECT_RECV_EVENT_FILENAME
// structure.
SIMCONNECT_RECV_EVENT_FILENAME *evt = (SIMCONNECT_RECV_EVENT_FILENAME*) pData;
break;
case SIMCONNECT_RECV_ID_EVENT_OBJECT_ADDREMOVE:
// enter code to handle AI objects that have been added or removed, and received in a SIMCONNECT_RECV_EVENT_OBJECT_ADDREMOVE
// structure.
SIMCONNECT_RECV_EVENT_OBJECT_ADDREMOVE *evt = (SIMCONNECT_RECV_EVENT_OBJECT_ADDREMOVE*) pData;
break;
case SIMCONNECT_RECV_ID_EVENT_FRAME:
// enter code to handle frame data received in a SIMCONNECT_RECV_EVENT_FRAME
// structure.
SIMCONNECT_RECV_EVENT_FRAME *evt = (SIMCONNECT_RECV_EVENT_FRAME*) pData;
break;
case SIMCONNECT_RECV_ID_SIMOBJECT_DATA:
// enter code to handle object data received in a SIMCONNECT_RECV_SIMOBJECT_DATA structure.
SIMCONNECT_RECV_SIMOBJECT_DATA *pObjData = (SIMCONNECT_RECV_SIMOBJECT_DATA*) pData;
break;
case SIMCONNECT_RECV_ID_SIMOBJECT_DATA_BYTYPE:
// enter code to handle object data received in a SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE
// structure.
SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE *pObjData = (SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE*) pData;
break;
case SIMCONNECT_RECV_ID_QUIT:
// enter code to handle exiting the application
break;
case SIMCONNECT_RECV_ID_EXCEPTION:
// enter code to handle errors received in a SIMCONNECT_RECV_EXCEPTION structure.
SIMCONNECT_RECV_EXCEPTION *except = (SIMCONNECT_RECV_EXCEPTION*) pData;
break;
case SIMCONNECT_RECV_ID_WEATHER_OBSERVATION:
// enter code to handle object data received in a SIMCONNECT_RECV_WEATHER_OBSERVATION structure.
SIMCONNECT_RECV_WEATHER_OBSERVATION* pWxData = (SIMCONNECT_RECV_WEATHER_OBSERVATION*) pData;
const char* pszMETAR = (const char*) (pWxData+1);
break;
// Enter similar case statements to handle the other types of data that can be received, including:
// SIMCONNECT_RECV_ID_ASSIGNED_OBJECT_ID,
// SIMCONNECT_RECV_ID_RESERVED_KEY,
// SIMCONNECT_RECV_ID_CUSTOM_ACTION
// SIMCONNECT_RECV_ID_SYSTEM_STATE
// SIMCONNECT_RECV_ID_CLOUD_STATE
default:
// enter code to handle the case where an unexpected message is received
break;
}
}
Working Sample
Primary sample | No Callback |
Remarks
It is important to call this function sufficiently frequently that the queue of information received from the server is processed. If there are no messages in the queue, the dwID parameter will be set to SIMCONNECT_RECV_ID_NULL.
See Also
SimConnect_MapClientDataNameToID
The SimConnect_MapClientDataNameToID function is used to associate an ID with a named client data area.
Syntax
HANDLE hSimConnect,
const char* szClientDataName,
SIMCONNECT_CLIENT_DATA_ID ClientDataID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szClientDataName
- [in] Null-terminated string containing the client data area name. This
is the name that another client will use to specify the data area. The name is not
case-sensitive. If the name requested is already in use by another add-on, a SIMCONNECT_EXCEPTION_ALREADY_CREATED
error will be returned.
- ClientDataID
- [in] A unique ID for the client data area, specified by the client. If the ID number is already in use, the SIMCONNECT_EXCEPTION_DUPLICATE_ID error will be returned.
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 should be called once for each client data area: the client setting up the data should call it just before a call to SimConnect_CreateClientData, and the clients requesting the data should call it before any calls to SimConnect_RequestClientData are made. The name given to a client data area must be unique, however by mapping an ID number to the name, calls to the functions to set and request the data are made more efficient.
See Also
- SimConnect_AddToClientDataDefinition
- SimConnect_ClearClientDataDefinition
- SimConnect_CreateClientData
- SimConnect_RequestClientData
- SimConnect_SetClientData
- SimConnect API Reference
SimConnect_MapClientEventToSimEvent
The SimConnect_MapClientEventToSimEvent function associates a client defined event ID with a Prepar3D event name.
Syntax
HANDLE hSimConnect,
SIMCONNECT_CLIENT_EVENT_ID EventID,
const char* EventName
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- EventID
- [in] Specifies the ID of the client event.
- EventName
- [in] Specifies the Prepar3D event name. Refer to the
Event IDs document for a list of event names (listed under String Name).
If the event name includes one or more periods (such as "Custom.Event"
in the example below) then they are custom events specified by the client, and will
only be recognized by another client (and not Prepar3D) that has been coded
to receive such events. No Prepar3D events include periods. If no entry is
made for this parameter, the event is private to the client.
Alternatively enter a decimal number in the format "#nnnn" or a hex number in the format "#0xnnnn", where these numbers are in the range THIRD_PARTY_EVENT_ID_MIN and THIRD_PARTY_EVENT_ID_MAX, in order to receive events from third-party add-ons to Prepar3D.
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. |
Example
EVENT_PAUSE,
EVENT_BRAKES,
EVENT_CUSTOM,
EVENT_PRIVATE,
};
// Attach the client event EVENT_BRAKES to the simulation event "brakes"
hr = SimConnect_MapClientEventToSimEvent(hSimConnect, EVENT_BRAKES, "brakes");
// Attach the client event EVENT_PAUSE to the simulation event "pause_toggle"
hr = SimConnect_MapClientEventToSimEvent(hSimConnect, EVENT_PAUSE, "pause_toggle");
// Create a custom event, for use when communicating with other clients
hr = SimConnect_MapClientEventToSimEvent(hSimConnect, EVENT_CUSTOM, "Custom.Event");
// Create a private event for use within this client only
hr = SimConnect_MapClientEventToSimEvent(hSimConnect, EVENT_PRIVATE);
Working Samples
Primary samples |
Client Event Cockpit Camera Joystick Input Reserved Key Send Event A Send Event B Send Event C Set Data Throttle Control Tracking Errors |
Reference samples | All but a few of the other samples implement this function. |
Remarks
Client events, such as EVENT_BRAKES, must be added to a group event (to set the appropriate priority) before event notifications will be received from the SimConnect server (see the SimConnect_AddClientEventToNotificationGroup function).
See Also
SimConnect_MapInputEventToClientEvent
The SimConnect_MapInputEventToClientEvent function is used to connect input events (such as keystrokes, joystick or mouse movements) with the sending of appropriate event notifications.
Syntax
HANDLE hSimConnect,
SIMCONNECT_INPUT_GROUP_ID GroupID,
const char* pszInputDefinition,
SIMCONNECT_CLIENT_EVENT_ID DownEventID,
DWORD DownValue = 0,
SIMCONNECT_CLIENT_EVENT_ID UpEventID =(SIMCONNECT_CLIENT_EVENT_ID)SIMCONNECT_UNUSED,
DWORD UpValue = 0,
BOOL bMaskable = FALSE
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- GroupID
- [in] Specifies the ID of the client defined input group that the input event is to be added to.
- pszInputDefinition
- [in] Pointer to a null-terminated string containing the definition of the input events (keyboard keys, mouse or joystick events, for example). See the Remarks and example below for a range of possibilities.
- DownEventID
- [in] Specifies the ID of the down, and default, event. This is the client defined event that is triggered when the input event occurs. If only an up event is required, set this to SIMCONNECT_UNUSED.
- DownValue
- [in, optional] Specifies an optional numeric value, which will be returned when the down event occurs. This value is only acknowledged for keyboard and button events.
- UpEventID
- [in, optional] Specifies the ID of the up event. This is the client defined event that is triggered when the up action occurs.
- UpValue
- [in, optional] Specifies an optional numeric value, which will be returned when the up event occurs. This value is only acknowledged for keyboard and button events.
- bMaskable
- [in, optional] If set to true, specifies that the client will mask the event, and no other lower priority clients will receive it. The default is false.
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. |
Example
static enum INPUT_ID {
INPUT_1,
};
static enum EVENT_ID {
EVENT_1,
EVENT_2,
EVENT_3
};
hr = SimConnect_MapClientEventToSimEvent(hSimConnect, EVENT_1, "parking_brakes");
// Set similar mappings for EVENT_2 and EVENT_3
// Lower case a and upper case B are hit together
hr = SimConnect_MapInputEventToClientEvent(hSimConnect, INPUT_1, "a+B", EVENT_1);
// Ctrl, upper case A and upper case U are hit together
hr = SimConnect_MapInputEventToClientEvent(hSimConnect, INPUT_1, "Ctrl+A+U", EVENT_1);
// Ctrl, shift, lower case a, has been hit
hr = SimConnect_MapInputEventToClientEvent(hSimConnect, INPUT_1, "shift+ctrl+a", EVENT_2);
// Ctrl, shift, lower case a, will trigger an EVENT_2 when it is pressed, and an EVENT_3 when released
hr = SimConnect_MapInputEventToClientEvent(hSimConnect, INPUT_1, "shift+ctrl+a", EVENT_2, 0, EVENT_3);
// The first configured button of joystick 0 is hit
hr = SimConnect_MapInputEventToClientEvent(hSimConnect, INPUT_1, "joystick:0:button:0", EVENT_2);
// The second configured button of joystick 0 is hit
hr = SimConnect_MapInputEventToClientEvent(hSimConnect, INPUT_1, "joystick:0:button:1", EVENT_3);
// The first configured joystick has had its first configured point of view (or hat) switch pressed
hr = SimConnect_MapInputEventToClientEvent(hSimConnect, INPUT_1, "joystick:0:POV:0", EVENT_3);
// The first configured joystick has been moved along the x axis
hr = SimConnect_MapInputEventToClientEvent(hSimConnect, INPUT_1, "joystick:0:XAxis", EVENT_3);
hr = SimConnect_SetInputGroupPriority(hSimConnect, INPUT_1, SIMCONNECT_GROUP_PRIORITY_HIGHEST);
Working Samples
Primary samples |
Cockpit Camera Input Event Joystick Input Throttle Control |
Reference samples | Set Data |
Remarks
The maximum number of events that can be added to an input group is 1000.
For the keyboard the input definition can include a maximum of two modifiers (Shift, Ctrl, Alt) and two keys (case sensitive).
For joysticks the input definition is in the form "joystick:n:input[:i]". Where n is the joystick number (starting from 0), input is the input name, and i is an optional index number that might be required by the input name (joystick:0:button:0 for example). The joystick number can be retrieved through the SimConnect_RequestJoystickDeviceInfo function. The input name can be one in the following table:
Input Name | Description | Range of values |
---|---|---|
Button | One of the joystick buttons, configured from 0. | 0 = up state, 1 = down state |
POV | Point of view switch (often called the hat switch). |
0 facing ahead 4500 forward right 9000 right 13500 rear right 18000 rear 22500 rear left 27000 left 31500 forward left |
Slider | The variable position slider on the joystick. | The actual values returned can vary widely on the joystick, though the limits are 32K (pulled back to the limit) to -32K (maximum forward limit). |
XAxis, YAxis or ZAxis | Movement of the joystick in the X, Y, or Z directions. For most joysticks the movement is left or right for the XAxis and forward or backward for the YAxis, with no values for the ZAxis. | The limits in the Y axis are 32K (pulled back) to -32K (pushed forward). The limits in the X axis are -32K (full left) to 32K (full right). Depending on the joystick though, the limits may be significantly less than these values. |
RxAxis, RyAxis, or RzAxis | Rotation of the joystick about the X, Y, or Z axis. For most joysticks there is only rotational movement around the Z axis, with no values for the X or Y axis. | For the Z axis, the limits are -32K (rotated left to the maximum) to 32K (rotated right to the maximum). Again, actual limits depend on the joystick. |
For keyboard hits, usually no further information other than the key has been pressed is necessary for the client to process the event appropriately. For joystick events, other than button events, it is also important to know the extent of the movement (or position of the hat switch, or of the slider). This information is returned with the event in the dwData parameter of a SIMCONNECT_RECV_EVENT structure.
For button, hat switch, or keyboard events, one event is transmitted to the client, or two if an up event is specified, when the input event occurs. If joystick axis, rotation or slider events are requested, then an event is transmitted for these six times per second whether the joystick is actually moved or not, unless the value for these is zero, in which case events are not transmitted until the joystick is moved from this position. Joystick and keyboard events are only transmitted when a scenario is loaded, not while the user is navigating the shell of the product.
For reference, the default input mappings of joystick buttons to events is specified in the Standard.xml file in the root Lockheed Martin\Prepar3D v5 folder. The first time Prepar3D is run, a subset of this file is written out to a file with the same name in the %APPDATA%\Lockheed Martin\Prepar3D v5\Controls folder, containing just the mappings that the current setup is using. Each time Prepar3D is run the smaller file is read in, and is the first used to find a mapping for a device. If a mapping is not found the larger file in the root folder is opened and searched (and a successful mapping added to the internal copy of the file). A generic mapping is used if no match is found. The file is written out again when the simulation is exited, obviously containing any new mappings. It is usually safe for a third-party to update the smaller version of Standard.xml with correct and appropriate mappings, as long as this does not happen while Prepar3D is running, as in this case the file will be over-written.
See Also
- SimConnect API Reference
- SimConnect_SetInputGroupPriority
- SimConnect_RemoveInputEvent
- SimConnect_ClearInputGroup
- SimConnect_SetInputGroupState
- SimConnect_RequestJoystickDeviceInfo
SimConnect_Open
The SimConnect_Open function is used to send a request to the Prepar3D server to open up communications with a new client.
Syntax
HANDLE* phSimConnect,
LPCSTR szName,
HWND hWnd,
DWORD UserEventWin32,
HANDLE hEventHandle,
DWORD ConfigIndex
);
Parameters
- phSimConnect
- [in] Pointer to a handle to a SimConnect object.
- szName
- [in] Pointer to a null-terminated string containing an appropriate name for the client program. The empty string ("") is a valid entry, NULL is not supported.
- hWnd
- [in] Handle to a Windows object. Set this to NULL if the handle is not being used.
- UserEventWin32
- [in] Code number that the client can specify. Set this to 0 if it is not being used.
- hEventHandle
- [in] A Windows Event handle. A client can be written to respond to Windows Events, rather than use a polling and callback system, which can be a more efficient process if the client does not have to respond very frequently to changes in data in Prepar3D.
- ConfigIndex
- [in] The configuration index. The SimConnect.cfg file can contain a number of configurations, identified in sections with the [SimConnect] or [SimConnect.N] titles. Setting this configuration index indicates which configuration settings to use for this SimConnect client. This is useful for applications that communicate with a number of different machines that are running Prepar3D. The default configuration index is zero (matching a [SimConnect] entry in a SimConnect.cfg file). Note the E_INVALIDARG return value.
To ensure that a configuration file is not read accidentally, for example when creating a .dll add-on that is only to work locally, enter SIMCONNECT_OPEN_CONFIGINDEX_LOCAL for this parameter, which will force local operation regardless of the existence of any configuration files.
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. |
E_INVALIDARG | A SimConnect section in the Simconnect.cfg file did not contain the config index requested in the parameters. |
Example
HANDLE hSimConnect = NULL;
hr = SimConnect_Open(&hSimConnect, "Your Application Name", NULL, 0, 0, SIMCONNECT_OPEN_CONFIGINDEX_LOCAL);
Working Samples
Primary samples |
Open and Close Windows Event |
Reference samples | All of the other samples implement this function. |
Remarks
Most client applications will have one SimConnect_Open call, and one corresponding SimConnect_Close call. However in some applications, multiplayer in particular, multiple SimConnect_Open calls may be necessary, in which case an array or list of handles will need to be maintained, and closed appropriately.
A client can optionally examine the SIMCOMMENT_RECV_OPEN structure that is returned after a call to SimConnect_Open. This structure gives versioning and build information that should be useful when multiple versions of SimConnect and multiple versions of Prepar3D that support it, are available.
If a remote client successfully establishes a link with Prepar3D, but at some later time the network connection is lost, SimConnect functions will return the NTSTATUS error STATUS_REMOTE_DISCONNECT (0xC000013CL).
The SIMCONNECT_EXCEPTION_VERSION_MISMATCH exception will be returned if a versioning error has occurred, typically when a client built on a newer version of the SimConnect client dll attempts to work with an older version of the SimConnect server. If this exception is received the dwIndex parameter will contain the following:
See Also
SimConnect_RemoveClientEvent
The SimConnect_RemoveClientEvent function is used to remove a client defined event from a notification group.
Syntax
HANDLE hSimConnect,
SIMCONNECT_NOTIFICATION_GROUP_ID GroupID,
SIMCONNECT_CLIENT_EVENT_ID EventID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- GroupID
- [in] Specifies the ID of the client defined group.
- EventID
- [in] Specifies the ID of the client defined event ID that is to be removed from the group.
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. |
Example
EVENT_1,
EVENT_2
EVENT_3
};
static enum GROUP_ID {
GROUP_1,
};
hr = SimConnect_AddClientEventToNotificationGroup(hSimConnect, GROUP_1, EVENT_1);
hr = SimConnect_AddClientEventToNotificationGroup(hSimConnect, GROUP_1, EVENT_2);
hr = SimConnect_AddClientEventToNotificationGroup(hSimConnect, GROUP_1, EVENT_3, TRUE);
hr = SimConnect_RemoveClientEvent(hSimConnect, GROUP_1, EVENT_2);
Remarks
Use this function to permanently remove the client event. There is no reliable procedure to temporarily turn off a client event.
See Also
- SimConnect API Reference
- SimConnect_AddClientEventToNotificationGroup
- SimConnect_SetNotificationGroupPriority
- SimConnect_ClearNotificationGroup
SimConnect_RemoveInputEvent
The SimConnect_RemoveInputEvent function is used to remove an input event from a specified input group object.
Syntax
HANDLE hSimConnect,
SIMCONNECT_INPUT_GROUP_ID GroupID,
const char* pszInputDefinition
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- GroupID
- [in] Specifies the ID of the client defined input group from which the event is to be removed.
- pszInputDefinition
- [in] Pointer to a null-terminated string containing the input definition.
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. |
Example
INPUT_1,
};
static enum EVENT_ID {
EVENT_1,
};
hr = SimConnect_MapClientEventToSimEvent(hSimConnect, EVENT_1, "parking_brakes");
hr = SimConnect_MapInputEventToClientEvent(hSimConnect, INPUT_1, "a+B", EVENT_1);
....
hr = SimConnect_RemoveInputEvent(hSimConnect, INPUT_1, "a+B");
Remarks
The input string definitions must match exactly, before anything is removed from the group definition. For example, the string definitions "A+B" and "a+B" do not match.
See Also
- SimConnect API Reference
- SimConnect_MapInputEventToClientEvent
- SimConnect_SetInputGroupPriority
- SimConnect_ClearInputGroup
- SimConnect_SetInputGroupState
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
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
- hSimConnect
- [in] Handle to a SimConnect object.
- ClientDataID
- [in] 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.
- RequestID
- [in] 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.
- DefineID
- [in] Specifies the ID of the client-defined data definition. This definition specifies the data that should be sent to the client.
- Period
- [in, optional] 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.
- Flags
- [in, optional] A DWORD containing one or more of the following values:
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. - origin
- [in, optional] The number of Period events that should elapse before transmission of the data begins. The default is zero, which means transmissions will start immediately.
- interval
- [in, optional] 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.
- limit
- [in, optional] 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.
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.
See Also
- SimConnect_AddToClientDataDefinition
- SimConnect_ClearClientDataDefinition
- SimConnect_CreateClientData
- SimConnect_MapClientDataNameToID
- SimConnect_SetClientData
- SimConnect API Reference
SimConnect_RequestJoystickDeviceInfo
The SimConnect_RequestJoystickDeviceInfo function is used to request information on currently connected joystick devices.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- RequestID
- [in] Specifies the client defined request ID.
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
The information requested will be returned in a SIMCONNECT_RECV_JOYSTICK_DEVICE_INFO structure.
This function does not include mouse devices.
See Also
SimConnect_RequestNotificationGroup
The SimConnect_RequestNotificationGroup function is used to request events are transmitted from a notification group, when the simulation is in Dialog Mode.
Syntax
HANDLE hSimConnect,
SIMCONNECT_NOTIFICATION_GROUP_ID GroupID,
DWORD dwReserved = 0,
DWORD Flags = 0
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- GroupID
- [in] Specifies the ID of the client defined group.
- dwReserved
- [in, optional] Reserved for future use.
- Flags
- [in, optional] Reserved for future use.
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
In this version this function has the specific purpose of enabling the sending of events, particularly joystick events, when the simulation is in Dialog Mode.
See Also
- SimConnect API Reference
- SimConnect_AddClientEventToNotificationGroup
- SimConnect_SetNotificationGroupPriority
- SimConnect_ClearNotificationGroup
SimConnect_RequestReservedKey
The SimConnect_RequestReservedKey function is used to request a specific keyboard TAB-key combination applies only to this client.
Syntax
HANDLE hSimConnect,
SIMCONNECT_CLIENT_EVENT_ID EventID,
const char* szKeyChoice1,
const char* szKeyChoice2 = "",
const char* szKeyChoice3 = ""
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- EventID
- [in] Specifies the client defined event ID.
- szKeyChoice1
- [in] Null-terminated string containing the first key choice. Refer to the document Key Strings for a full list of choices that can be entered for these three parameters.
- szKeyChoice2
- [in, optional] Null-terminated string containing the second key choice.
- szKeyChoice3
- [in, optional] Null-terminated string containing the third key choice.
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. |
Working Sample
Primary sample | Reserved Key |
Remarks
A successful call to this function will result in a SIMCONNECT_RECV_RESERVED_KEY structure being returned, with the key that has been assigned to this client. The first of the three that can be assigned will be the choice, unless all three are already taken, in which case a null string will be returned.
The szKeyChoice parameters should be a single character (such as "A"), which is requesting that the key combination TAB-A is reserved for this client. All reserved keys are TAB-key combinations.
See Also
SimConnect_RequestSystemState
The SimConnect_RequestSystemState function is used to request information from a number of Prepar3D system components.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID,
const char* szState
);
Parameters
- hSimConnect
Handle to a SimConnect object.
RequestID
The client defined request ID.
szState
A null-terminated string identifying the system function. One from the following table:
String Description AircraftLoaded Requests the full path name of the last loaded aircraft flight dynamics file. These files have a .AIR extension. DialogMode Requests whether the simulation is in Dialog mode or not. See SimConnect_SetSystemState for a description of Dialog mode. FlightLoaded Requests the full path name of the last loaded scenario. Scenario files have the extension .FXML. FlightPlan Requests the full path name of the active flight plan. An empty string will be returned if there is no active flight plan. FullScreenMode Requests whether the simulation is in Full Screen mode or not. Sim Requests the state of the simulation. If 1 is returned, the user is in control of the aircraft, if 0 is returned, the user is navigating the UI. This is the same state that notifications can be subscribed to with the "SimStart" and "SimStop" string with the SimConnect_SubscribeToSystemEvent function.
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
The information requested will be returned in a SIMCONNECT_RECV_SYSTEM_STATE structure.
See Also
SimConnect_RequestSystemStateW
The SimConnect_RequestSystemStateW function is used to request information from a number of Prepar3D system components. This version of the function supports unicode string results.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID,
const wchar_t* szState
);
Parameters
- hSimConnect
Handle to a SimConnect object.
RequestID
The client defined request ID.
szState
A null-terminated string identifying the system function
See SimConnect_RequestSystemStateW for
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
The information requested will be returned in a SIMCONNECT_RECV_SYSTEM_STATE_W structure. See SimConnect_SubscribeToSystemEvent for description of other parameters.
See Also
SimConnect_RequestVersion
The SimConnect_RequestVersion function is used to request license type, Prepar3D version, and Prepar3D SimConnect version.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- RequestID
- [in] Specifies the client defined request ID.
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
The information requested will be returned in a SIMCONNECT_RECV_VERSION structure.
See Also
SimConnect_RequestSessionDuration
The SimConnect_RequestSessionDuration function is used to request the simulated time in seconds since the last scenario load. When in a scenario, the duration is accumulated between scenario saves/loads, such as saving and loading checkpoints.
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- RequestID
- [in] Specifies the client defined request ID.
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
The information requested will be returned in a SIMCONNECT_RECV_SESSION_DURATION structure.
See Also
SimConnect_SetClientData
The SimConnect_SetClientData function is used to write one or more units of data to a client data area.
Syntax
HANDLE hSimConnect,
SIMCONNECT_CLIENT_DATA_ID ClientDataID,
SIMCONNECT_CLIENT_DATA_DEFINITION_ID DefineID,
DWORD Flags,
DWORD dwReserved,
DWORD cbUnitSize,
void* pDataSet
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- ClientDataID
- [in] Specifies the ID of the client data area.
- DefineID
- [in] Specifies the ID of the client defined client data definition.
- Flags
- [in] Null, or one or more of the following flags.
Flag Description SIMCONNECT_CLIENT_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. - dwReserved
- [in] Reserved for future use. Set to zero.
- cbUnitSize
- [in] Specifies the size of the data set in bytes. The server will check that this size matches exactly the size of the data definition provided in the DefineID parameter. An exception will be returned if this is not the case.
- pDataSet
- [in] Pointer to the data that is to be written. If the data is not in tagged format, this should point to the block of client 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.
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 data can be set.
See Also
- SimConnect_AddToClientDataDefinition
- SimConnect_ClearClientDataDefinition
- SimConnect_CreateClientData
- SimConnect_MapClientDataNameToID
- SimConnect_RequestClientData
- SimConnect API Reference
SimConnect_SetInputGroupPriority
The SimConnect_SetInputGroupPriority function is used to set the priority for a specified input group object.
Syntax
HANDLE hSimConnect,
SIMCONNECT_INPUT_GROUP_ID GroupID,
DWORD uPriority
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- GroupID
- [in] Specifies the ID of the client defined input group that the priority setting is to apply to.
- uPriority
- [in] Specifies the priority setting for the input group. See the explanation of SimConnect Priorities.
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. |
Example
Working Samples
Primary samples |
Input Event
Joystick Input |
Remarks
A priority setting must be made for all input groups, otherwise event notifications will not be sent by the SimConnect server.
See Also
- SimConnect API Reference
- SimConnect_MapInputEventToClientEvent
- SimConnect_RemoveInputEvent
- SimConnect_ClearInputGroup
- SimConnect_SetInputGroupState
SimConnect_SetInputGroupState
The SimConnect_SetInputGroupState function is used to turn requests for input event information from the server on and off.
Syntax
HANDLE hSimConnect,
SIMCONNECT_INPUT_GROUP_ID GroupID,
DWORD dwState
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- GroupID
- [in] Specifies the ID of the client defined input group that is to have its state changed.
- dwState
- [in] Double word containing the new state. One member of the SIMCONNECT_STATE enumeration type.
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. |
Example
INPUT_1,
INPUT_2
};
static enum EVENT_ID {
EVENT_1,
EVENT_2
};
....
hr = SimConnect_MapClientEventToSimEvent(hSimConnect, EVENT_1, "parking_brakes");
hr = SimConnect_MapInputEventToClientEvent(hSimConnect, INPUT_1, "ctrl+U+Q", EVENT_1);
hr = SimConnect_SetInputGroupState(hSimConnect, INPUT_1, SIMCONNECT_STATE_ON);
Working Samples
Primary samples |
Input Event
Joystick Input Throttle Control |
Reference samples | Set Data |
Remarks
The default state for input groups is to be inactive, so make sure to call this function each time an input group is to become active.
See Also
- SimConnect API Reference
- SimConnect_MapInputEventToClientEvent
- SimConnect_SetInputGroupPriority
- SimConnect_RemoveInputEvent
- SimConnect_ClearInputGroup
SimConnect_SetNotificationGroupPriority
The SimConnect_SetNotificationGroupPriority function is used to set the priority for a notification group.
Syntax
HANDLE hSimConnect,
SIMCONNECT_NOTIFICATION_GROUP_ID GroupID,
DWORD uPriority
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- GroupID
- [in] Specifies the ID of the client defined group.
- uPriority
- [in] Requests the group's priority. See the explanation of SimConnect Priorities.
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. |
Example
Working Samples
Primary samples |
Client Event Send Event A Send Event B Send Event C Tracking Errors |
Remarks
SimConnect Priorities
SimConnect constants define the following priorities:
Priority | Value | Description |
---|---|---|
SIMCONNECT_GROUP_PRIORITY_HIGHEST | 1 | The highest priority. |
SIMCONNECT_GROUP_PRIORITY_HIGHEST_MASKABLE | 10000000 | The highest priority that allows events to be masked. |
SIMCONNECT_GROUP_PRIORITY_STANDARD | 1900000000 | The standard priority. |
SIMCONNECT_GROUP_PRIORITY_DEFAULT | 2000000000 | The default priority. |
SIMCONNECT_GROUP_PRIORITY_LOWEST | 4000000000 | Priorities lower than this will be ignored. |
Each notification group has an assigned priority, and the SimConnect server will send events out strictly in the order of priority. No two groups will be set at the same priority. If a request is received for a group to be set at a priority that has already been taken, the group will be assigned the next lowest priority that is available. This includes groups from all the clients that have opened communications with the server.
If a group has an assigned priority above SIMCONNECT_GROUP_PRIORITY_HIGHEST_MASKABLE then it cannot mask events (hide them from other clients). If the group has a priority equal to or below SIMCONNECT_GROUP_PRIORITY_HIGHEST_MASKABLE, then events can be masked (the maskable flag must be set by the SimConnect_AddClientEventToNotificationGroup function to do this). Note that it is possible to mask Prepar3D events, and therefore intercept them before they reach the simulation engine, and perhaps send new events to the simulation engine after appropriate processing has been done. Prepar3D's simulation engine is treated as SimConnect client in this regard, with a priority of SIMCONNECT_GROUP_PRIORITY_DEFAULT.
Input group events work in a similar manner. The priority groups are not combined though, a group and an input group can both have the same priority number. The SimConnect server manages two lists: notification groups and input groups.
A typical use of masking is to prevent Prepar3D itself from receiving an event, in order for the SimConnect client to completely replace the functionality in this case. Another use of masking is with co-operative clients, where there are multiple versions (perhaps a deluxe and standard version, or later and earlier versions), where the deluxe or later version might need to mask events from the other client, if they are both up and running. Prepar3D does not mask any events.
See Also
- SimConnect API Reference
- SimConnect_AddClientEventToNotificationGroup
- SimConnect_RemoveClientEvent
- SimConnect_ClearNotificationGroup
SimConnect_SetSystemEventState
The SimConnect_SetSystemEventState function is used to turn requests for event information from the server on and off.
Syntax
HANDLE hSimConnect,
SIMCONNECT_CLIENT_EVENT_ID EventID,
SIMCONNECT_STATE dwState
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- EventID
- [in] Specifies the ID of the client event that is to have its state changed.
- dwState
- [in] Double word containing the state (one member of SIMCONNECT_STATE).
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. |
Example
See the example and working samples for SimConnect_SubscribeToSystemEvent.
Remarks
If this function is not called, the default is for the state to be on. This is different from input events, which have a default state of off.
Use this function to turn system events temporarily on and off, rather than make multiple calls to SimConnect_SubscribeToSystemEvent and SimConnect_UnsubscribeFromSystemEvent, which is less efficient.
See Also
SimConnect_SetSystemState
The SimConnect_SetSystemState function is used to access a number of Prepar3D system components.
Syntax
HANDLE hSimConnect,
const char* szState,
DWORD dwInteger,
float fFloat,
char* szString
);
Parameters
- hSimConnect
Handle to a SimConnect object.
szState
A null-terminated string identifying the system function. One from the following table:
String Description DialogMode The dwInteger parameter should be set to 1 to turn Dialog mode on, or 0 to turn it off. Dialog mode enables the display of dialogs when the simulation is running in full-screen mode. When in dialog mode the 3D area of the screen will turn black, and will only revert to the simulation view when Dialog mode is turned off (not automatically when the dialog is closed). See the Working Sample for a simple example.
It is safe to set and reset Dialog mode when the simulation is being run in Windows mode.Sim It is not possible to set this state, so entering this will result in an exception being returned. - dwInteger
- An integer value, set depending on the value of szState.
- fFloat
- A float value, set depending on the value of szState (not currently used).
- szString
- A string value, set depending on the value of szState (not currently used).
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. |
Working Samples
Primary samples |
DialogBoxMode |
Remarks
The integer, float and string set with this function match those in the SIMCONNECT_RECV_SYSTEM_STATE structure (which is returned if the information is requested with the SimConnect_RequestSystemState call.
See Also
SimConnect_SubscribeToSystemEvent
The SimConnect_SubscribeToSystemEvent function is used to request that a specific system event is notified to the client.
Syntax
HANDLE hSimConnect,
SIMCONNECT_CLIENT_EVENT_ID EventID,
const char* SystemEventName
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- EventID
- [in] Specifies the client-defined event ID.
- SystemEventName
- [in] The string name for the requested system event, which should be one from
the following table (note that the event names are not case-sensitive). Unless otherwise
stated in the Description, notifications of the event are returned in a
SIMCONNECT_RECV_EVENT structure (identify the event from the EventID
given with this function).
General System Event Name 1sec Request a notification every second. 4sec Request a notification every four seconds. 6Hz Request notifications six times per second. This is the same rate that joystick movement events are transmitted. AircraftLoaded Request a notification when the aircraft flight dynamics file is changed. These files have a .AIR extension. The filename is returned in a SIMCONNECT_RECV_EVENT_FILENAME structure or a SIMCONNECT_RECV_EVENT_FILENAME_W if subscribed with the SimConnect_SubscribeToSystemEventW function. Crashed Request a notification if the user aircraft crashes. CrashReset Request a notification when the crash cut-scene has completed. FlightLoaded Request a notification when a scenario is loaded. Note that when a scenario is ended, a default scenario is typically loaded, so these events will occur when scenarios are started and finished. The filename of the scenario loaded is returned in a SIMCONNECT_RECV_EVENT_FILENAME structure or a SIMCONNECT_RECV_EVENT_FILENAME_W if subscribed with the SimConnect_SubscribeToSystemEventW function. FlightSaved Request a notification when a scenario is saved correctly. The filename of the scenario saved is returned in a SIMCONNECT_RECV_EVENT_FILENAME structure or a SIMCONNECT_RECV_EVENT_FILENAME_W if subscribed with the SimConnect_SubscribeToSystemEventW function. FlightPlanActivated Request a notification when a new flight plan is activated. The filename of the activated flight plan is returned in a SIMCONNECT_RECV_EVENT_FILENAME structure or a SIMCONNECT_RECV_EVENT_FILENAME_W if subscribed with the SimConnect_SubscribeToSystemEventW function. FlightPlanDeactivated Request a notification when the active flight plan is de-activated. Frame Request notifications every visual frame. Information is returned in a SIMCONNECT_RECV_EVENT_FRAME structure. Pause Request notifications when the scenario is paused or unpaused, and also immediately returns the current pause state (1 = paused or 0 = unpaused). The state is returned in the dwData parameter. Paused Request a notification when the scenario is paused. PauseFrame Request notifications for every visual frame that the simulation is paused. Information is returned in a SIMCONNECT_RECV_EVENT_FRAME structure. PositionChanged Request a notification when the user changes the position of their aircraft through a dialog. Sim Request notifications when the scenario is running or not, and also immediately returns the current state (1 = running or 0 = not running). The state is returned in the dwData parameter. SimStart The simulator is running. Typically the user is actively controlling the vehicle which is on the ground, underwater or in the air. SimStop The simulator is not running. Typically the user is loading a scenario, navigating the user interface or in a dialog. Sound Requests a notification when the master sound switch is changed. This request will also return the current state of the master sound switch immediately. A flag is returned in the dwData parameter, 0 if the switch is off, SIMCONNECT_SOUND_SYSTEM_EVENT_DATA_MASTER (0x1) if the switch is on. Unpaused Request a notification when the scenario is un-paused. View Requests a notification when the user aircraft view is changed. This request will also return the current view immediately. A flag is returned in the dwData parameter, one of:
SIMCONNECT_VIEW_SYSTEM_EVENT_DATA_COCKPIT_2D
SIMCONNECT_VIEW_SYSTEM_EVENT_DATA_COCKPIT_VIRTUAL
SIMCONNECT_VIEW_SYSTEM_EVENT_DATA_ORTHOGONAL (the map view).WeatherModeChanged Request a notification when the weather mode is changed. TextEventCreated Request a notification when a SimConnect message is sent using SimConnect_Text. Refer also to the SIMCONNECT_RECV_EVENT_TEXT structure. TextEventDestroyed Request a notification when a SimConnect text window is being destroyed. Refer also to the SIMCONNECT_RECV_EVENT_TEXT_DESTROYED structure. AI Specific Event Name ObjectAdded Request a notification when an AI object is added to the simulation. Refer also to the SIMCONNECT_RECV_EVENT_OBJECT_ADDREMOVE structure. ObjectRemoved Request a notification when an AI object is removed from the simulation. Refer also to the SIMCONNECT_RECV_EVENT_OBJECT_ADDREMOVE structure. Mission Specific Event Name MissionCompleted Request a notification when the user has completed a scenario. Refer also to the SIMCONNECT_MISSION_END enum. CustomMissionActionExecuted Request a notification when a scenario action has been executed. Refer also to the SimConnect_CompleteCustomMissionAction function. FlightSegmentReadyForGrading Request a notification when a Flight Segment has been completed and is ready for grading. Multiplayer Racing Event Name MultiplayerClientStarted Used by a client to request a notification that they have successfully joined a multiplayer race. The event is returned as a SIMCONNECT_RECV_EVENT_MULTIPLAYER_CLIENT_STARTED structure. This event is only sent to the client, not the host of the session. MultiplayerServerStarted Used by a host of a multiplayer race to request a notification when the race is open to other players in the lobby. The event is returned in a SIMCONNECT_RECV_EVENT_MULTIPLAYER_SERVER_STARTED structure. MultiplayerSessionEnded Request a notification when the multiplayer race session is terminated. The event is returned in a SIMCONNECT_RECV_EVENT_MULTIPLAYER_SESSION_ENDED structure. If a client player leaves a race, this event will be returned just to the client. If a host leaves or terminates the session, then all players will receive this event. This is the only event that will be broadcast to all players. RaceEnd Request a notification of the race results for each racer. The results will be returned in SIMCONNECT_RECV_EVENT_RACE_END structures, one for each player. RaceLap Request a notification of the race results for each racer. The results will be returned in SIMCONNECT_RECV_EVENT_RACE_LAP structures, one for each player. Recorder Specific Event Name PlaybackStateChanged Request a notification when the state of Prepar3D playback changes. Either playback has started or ended. Information is returned in a SIMCONNECT_RECV_PLAYBACK_STATE_CHANGED structure. RecorderStateChanged Request a notification when the state of Prepar3D recording changes. Either recording has started or ended. Information is returned in a SIMCONNECT_RECV_RECORDER_STATE_CHANGED structure. Weapon System Event Name PROFESSIONAL PLUS ONLY WeaponFired Request a notification when a detachable weapon is fired. Refer also to the SIMCONNECT_RECV_EVENT_WEAPON structure. WeaponDetonated Request a notification when a detachable weapon is detonated or destroyed. Refer also to the SIMCONNECT_RECV_EVENT_WEAPON structure. CountermeasureFired Request a notification when a countermeasure is deployed. Refer also to the SIMCONNECT_RECV_EVENT_COUNTERMEASURE structure. ObjectDamagedByWeapon Request a notification when an object is damaged by a weapon. Refer also to the SIMCONNECT_RECV_EVENT_OBJECT_DAMAGED_BY_WEAPON structure.
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. |
Example
EVENT_FLIGHT_LOAD,
EVENT_RECUR_1SEC,
EVENT_RECUR_FRAME,
};
hr = SimConnect_SubscribeToSystemEvent(hSimConnect, EVENT_FLIGHT_LOAD, "FlightLoaded");
hr = SimConnect_SubscribeToSystemEvent(hSimConnect, EVENT_RECUR_1SEC, "1sec");
hr = SimConnect_SubscribeToSystemEvent(hSimConnect, EVENT_RECUR_FRAME, "frame");
// The recurring events will be on by default, so set one of them to off.
hr = SimConnect_SetSystemEventState(hSimConnect, EVENT_RECUR_FRAME, SIMCONNECT_STATE_OFF);
Working Samples
Primary samples |
Mission Action
System Event |
Reference samples | Many of the other samples implement this function. |
Remarks
A single call to this function is all that is necessary to receive the notifications. For greatest efficiency use SimConnect_SetSystemEventState to turn these requests on and off temporarily, and call SimConnect_UnsubscribeFromSystemEvent once only to permanently terminate the notifications of these events.
See Also
- SimConnect_SubscribeToSystemEventEx
- SimConnect_RequestSystemState
- SimConnect_SetSystemState
- SimConnect API Reference
SimConnect_SubscribeToSystemEventEx
The SimConnect_SubscribeToSystemEventEx function is used to request that a specific system event is notified to the client. The Ex specific version of the function adds a Flags parameter.
Syntax
HANDLE hSimConnect,
SIMCONNECT_CLIENT_EVENT_ID EventID,
const char* SystemEventName,
SIMCONNECT_EVENT_SUBSCRIPTION_FLAG Flags
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- EventID
- [in] Specifies the client-defined event ID.
- SystemEventName
- [in] The string name for the requested system event, which should be one from the following table (note that the event names are not case-sensitive). Unless otherwise stated in the Description, notifications of the event are returned in a SIMCONNECT_RECV_EVENT structure (identify the event from the EventID given with this function).
- Flags
- [in] One or more of the following flags.
Flags Description SIMCONNECT_EVENT_SUBSCRIPTION_FLAG_BLOCK Specifies that a blocking callback will be used when this system event occurs. See SimConnect_RequestSynchronousBlock for more information.
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
See SimConnect_SubscribeToSystemEvent for description of other parameters.
See Also
- SimConnect_SubscribeToSystemEvent
- SimConnect_RequestSystemState
- SimConnect_SetSystemState
- SimConnect API Reference
SimConnect_SubscribeToSystemEventW
The SimConnect_SubscribeToSystemEventW function is used to request that a specific system event is notified to the client. This version of the function supports unicode string results.
Syntax
HANDLE hSimConnect,
SIMCONNECT_CLIENT_EVENT_ID EventID,
const wchar_t* SystemEventName,
SIMCONNECT_EVENT_SUBSCRIPTION_FLAG Flags
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- EventID
- [in] Specifies the client-defined event ID.
- SystemEventName
- [in] The string name for the requested system event, which should be one from the following table (note that the event names are not case-sensitive). Unless otherwise stated in the Description, notifications of the event are returned in a SIMCONNECT_RECV_EVENT structure (identify the event from the EventID given with this function).
- Flags
- [in] One or more of the following flags.
Flags Description SIMCONNECT_EVENT_SUBSCRIPTION_FLAG_BLOCK Specifies that a blocking callback will be used when this system event occurs. See SimConnect_RequestSynchronousBlock for more information.
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
See SimConnect_SubscribeToSystemEvent for description of other parameters.
See Also
- SimConnect_SubscribeToSystemEvent
- SimConnect_RequestSystemState
- SimConnect_SetSystemState
- SimConnect API Reference
SimConnect_TransmitClientEvent
The SimConnect_TransmitClientEvent function is used to request that the Prepar3D server transmit to all SimConnect clients the specified client event.
Syntax
HANDLE hSimConnect,
SIMCONNECT_OBJECT_ID ObjectID,
SIMCONNECT_CLIENT_EVENT_ID EventID,
DWORD dwData,
SIMCONNECT_NOTIFICATION_GROUP_ID GroupID,
SIMCONNECT_EVENT_FLAG Flags
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- ObjectID
- [in] Specifies the ID of the server defined object. If this parameter is set to SIMCONNECT_OBJECT_ID_USER, then the transmitted event will be sent to the other clients in priority order. If this parameters contains another object ID, then the event will be sent direct to that sim-object, and no other clients will receive it.
- EventID
- [in] Specifies the ID of the client event.
- dwData
- [in] Double word containing any additional number required by the event. This is often zero. If the event is a Prepar3D event, then refer to the Event IDs document for information on this additional value. If the event is a custom event, then any value put in this parameter will be available to the clients that receive the event.
- GroupID
- [in] The default behavior is that this specifies the GroupID of the event. The SimConnect server will use the priority of this group to send the message to all clients with a lower priority. To receive the event notification other SimConnect clients must have subscribed to receive the event. See the explanation of SimConnect Priorities. The exception to the default behavior is set by the SIMCONNECT_EVENT_FLAG_GROUPID_IS_PRIORITY flag, described below.
- Flags
- [in] One or more of the following flags:
NOTE: For panel control you must specify a group priority of 0.
Flag | Description |
---|---|
0 | Do nothing. |
SIMCONNECT_EVENT_FLAG_SLOW_REPEAT_TIMER | The flag will effectively reset the repeat timer to simulate slow repeat. Use this flag to reset the repeat timer that works with various keyboard events and mouse clicks. |
SIMCONNECT_EVENT_FLAG_FAST_REPEAT_TIMER | The flag will effectively reset the repeat timer to simulate fast repeat. |
SIMCONNECT_EVENT_FLAG_GROUPID_IS_PRIORITY |
Indicates to the SimConnect server to treat the GroupID as a priority value. If this flag is set, and the GroupID parameter is set to SIMCONNECT_GROUP_PRIORITY_HIGHEST then all client notification groups that have subscribed to the event will receive the notification (unless one of them masks it). The event will be transmitted to clients starting at the priority specified in the GroupID parameter, though this can result in the client that transmitted the event, receiving it again. |
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. |
Examples
// 1. Transmitting a custom event to other clients
static enum EVENT_ID {
EVENT_MY_EVENT
EVENT_DME
EVENT_OPEN_PANEL
};
hr = SimConnect_MapClientEventToSimEvent(hSimConnect, EVENT_MY_EVENT, "Custom.Event");
// Send EVENT_MY_EVENT to all current SimConnect clients.
SimConnect_TransmitClientEvent(hSimConnect, 0, EVENT_MY_EVENT, 0, SIMCONNECT_GROUP_PRIORITY_HIGHEST, SIMCONNECT_EVENT_FLAG_GROUPID_IS_PRIORITY);
// 2. Setting an event value
hr = SimConnect_MapClientEventToSimEvent(hSimConnect, EVENT_DME, "DME_SELECT");
// Set the selected DME to 2
SimConnect_TransmitClientEvent(hSimConnect, 0, EVENT_DME, 2, SIMCONNECT_GROUP_PRIORITY_DEFAULT, SIMCONNECT_EVENT_FLAG_GROUPID_IS_PRIORITY);
NOTE: For panel control you must specify a group priority of 0.
Working Sample
Primary sample | Send Event A |
Remarks
Typically use this function to transmit an event to other SimConnect clients, including the simulation engine, although the client that transmits the event can also receive it. The order in which client notification groups are informed of the event is determined by the priority of each group. The higher the priority of the group, the earlier it will receive the event notification. Refer to the explanation of the maskable parameter for the SimConnect_AddClientEventToNotificationGroup call, which describes when the event may be masked and not transmitted to lower priority groups. Also see the explanation of SimConnect Priorities.
See Also
SimConnect_TransmitClientEvent64
The SimConnect_TransmitClientEvent64 function is used to request that the Prepar3D server transmit to all SimConnect clients the specified client event. This function behaves the same as SimConnect_TransmitClientEvent with the following exceptions:
- This function accepts a 64-bit user context data parameter.
- This function sends a SIMCONNECT_RECV structure with a dwID value of SIMCONNECT_RECV_ID_EVENT_64.
- The received SIMCONNECT_RECV structure should be casted to type SIMCONNECT_RECV_EVENT_64
- The 64-bit qwData parameter of the SIMCONNECT_RECV_EVENT_64 structure contains the user context data.
- The 32-bit dwData parameter of the SIMCONNECT_RECV_EVENT_64 structure is unused.
Syntax
HANDLE hSimConnect,
SIMCONNECT_OBJECT_ID ObjectID,
SIMCONNECT_CLIENT_EVENT_ID EventID,
QWORD qwData,
SIMCONNECT_NOTIFICATION_GROUP_ID GroupID,
SIMCONNECT_EVENT_FLAG Flags
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- ObjectID
- [in] Specifies the ID of the server defined object. If this parameter is set to SIMCONNECT_OBJECT_ID_USER, then the transmitted event will be sent to the other clients in priority order. If this parameters contains another object ID, then the event will be sent direct to that sim-object, and no other clients will receive it.
- EventID
- [in] Specifies the ID of the client event.
- qwData
- [in] Quad word containing any additional number required by the event. This is often zero. If the event is a Prepar3D event, then refer to the Event IDs document for information on this additional value. If the event is a custom event, then any value put in this parameter will be available to the clients that receive the event.
- GroupID
- [in] The default behavior is that this specifies the GroupID of the event. The SimConnect server will use the priority of this group to send the message to all clients with a lower priority. To receive the event notification other SimConnect clients must have subscribed to receive the event. See the explanation of SimConnect Priorities. The exception to the default behavior is set by the SIMCONNECT_EVENT_FLAG_GROUPID_IS_PRIORITY flag, described below.
- Flags
- [in] One or more of the following flags:
NOTE: For panel control you must specify a group priority of 0.
Flag | Description |
---|---|
0 | Do nothing. |
SIMCONNECT_EVENT_FLAG_SLOW_REPEAT_TIMER | The flag will effectively reset the repeat timer to simulate slow repeat. Use this flag to reset the repeat timer that works with various keyboard events and mouse clicks. |
SIMCONNECT_EVENT_FLAG_FAST_REPEAT_TIMER | The flag will effectively reset the repeat timer to simulate fast repeat. |
SIMCONNECT_EVENT_FLAG_GROUPID_IS_PRIORITY |
Indicates to the SimConnect server to treat the GroupID as a priority value. If this flag is set, and the GroupID parameter is set to SIMCONNECT_GROUP_PRIORITY_HIGHEST then all client notification groups that have subscribed to the event will receive the notification (unless one of them masks it). The event will be transmitted to clients starting at the priority specified in the GroupID parameter, though this can result in the client that transmitted the event, receiving it again. |
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. |
Examples
// 1. Transmitting a custom event to other clients
static enum EVENT_ID {
EVENT_MY_EVENT
EVENT_DME
EVENT_OPEN_PANEL
};
hr = SimConnect_MapClientEventToSimEvent(hSimConnect, EVENT_MY_EVENT, "Custom.Event");
// Send EVENT_MY_EVENT to all current SimConnect clients.
SimConnect_TransmitClientEvent64(hSimConnect, 0, EVENT_MY_EVENT, 0, SIMCONNECT_GROUP_PRIORITY_HIGHEST, SIMCONNECT_EVENT_FLAG_GROUPID_IS_PRIORITY);
// 2. Setting an event value
hr = SimConnect_MapClientEventToSimEvent(hSimConnect, EVENT_DME, "DME_SELECT");
// Set the selected DME to 2
SimConnect_TransmitClientEvent64(hSimConnect, 0, EVENT_DME, 2, SIMCONNECT_GROUP_PRIORITY_DEFAULT, SIMCONNECT_EVENT_FLAG_GROUPID_IS_PRIORITY);
NOTE: For panel control you must specify a group priority of 0.
Remarks
Typically use this function to transmit an event to other SimConnect clients, including the simulation engine, although the client that transmits the event can also receive it. The order in which client notification groups are informed of the event is determined by the priority of each group. The higher the priority of the group, the earlier it will receive the event notification. Refer to the explanation of the maskable parameter for the SimConnect_AddClientEventToNotificationGroup call, which describes when the event may be masked and not transmitted to lower priority groups. Also see the explanation of SimConnect Priorities.
See Also
SimConnect_UnsubscribeFromSystemEvent
The SimConnect_UnsubscribeFromSystemEvent function is used to request that notifications are no longer received for the specified system event.
Syntax
HANDLE hSimConnect,
SIMCONNECT_CLIENT_EVENT_ID EventID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- EventID
- [in] Specifies the client-defined event ID.
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. |
Example
EVENT_FLIGHT_LOAD,
EVENT_RECUR_1SEC,
EVENT_RECUR_FRAME,
};
hr = SimConnect_SubscribeToSystemEvent(hSimConnect, EVENT_RECUR_1SEC);
....
hr = SimConnect_UnsubscribeFromSystemEvent(hSimConnect, EVENT_RECUR_1SEC);
Remarks
There is no limit to the number of system events that can be subscribed to, but use this function to improve performance when a system event notification is no longer needed.
See Also
SimConnect_InsertString
The SimConnect_InsertString function is used to assist in adding variable length narrow strings to a structure.
Syntax
BYTE* pDest,
DWORD cbDest,
void** ppEnd,
DWORD* pcbStringV,
const char* pSource
);
Parameters
- pDest
- [in] Pointer to where the source string is to be written in the destination object.
- cbDest
- [in] The size of the remaining space in the destination object.
- ppEnd
- [in,out] Pointer to a pointer, (usually a pointer to a char pointer). On return the pointer locates the end of the string in the structure, and hence the starting position for any other string to be included in the structure.
- pcbStringV
- [in,out] Pointer to a DWORD. On returning this DWORD will contain the size of the source string in bytes.
- pSource
- [in] Pointer to the source string.
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 does not communicate with the SimConnect server, but is a helper function to assist in the handling of variable length narrow strings. Its counterpart is the SimConnect_RetrieveString function.
See Also
SimConnect_InsertStringW
The SimConnect_InsertStringW function is used to assist in adding variable length wide strings to a structure.
Syntax
BYTE* pDest,
DWORD cbDest,
void** ppEnd,
DWORD* pcbStringV,
const wchar_t* pSource
);
Parameters
- pDest
- [in] Pointer to where the source string is to be written in the destination object.
- cbDest
- [in] The size of the remaining space in the destination object.
- ppEnd
- [in,out] Pointer to a pointer, (usually a pointer to a wchar_t pointer). On return the pointer locates the end of the string in the structure, and hence the starting position for any other string to be included in the structure.
- pcbStringV
- [in,out] Pointer to a DWORD. On returning this DWORD will contain the size of the source string in bytes.
- pSource
- [in] Pointer to the source string.
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 does not communicate with the SimConnect server, but is a helper function to assist in the handling of variable length wide strings. Its counterpart is the SimConnect_RetrieveStringW function.
See Also
SimConnect_RequestResponseTimes
The SimConnect_RequestResponseTimes function is used to provide some data on the performance of the client-server connection.
Syntax
HANDLE hSimConnect,
DWORD nCount,
float* fElapsedSeconds
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- nCount
- [in] Integer containing the number of elements in the array of floats. This should be set to five for the full range of timings, but can be less if only the first few are of interest. There is no point creating an array of greater than five floats.
- fElapsedSeconds
- [in] An array of nCount floats, containing the times. The five elements will contain the following: 0 - total round trip time, 1 - time from the request till the packet is sent, 2 - time from the request till the packet is received by the server, 3 - time from the request till the response is made by the server, 4 - time from the server response to the client receives the packet.
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. |
Example
bool fTesting = true;
....
while( quit == 0 )
{
hr = SimConnect_CallDispatch(hSimConnect, MyDispatchProc, NULL);
Sleep(0);
if (fTesting)
{
fTesting = false;
float fElapsedSeconds[5];
hr = SimConnect_RequestResponseTimes(hSimConnect, 5, &fElapsedSeconds[0]);
\\ Enter code to display the contents of fElapsedSeconds
}
}
Remarks
This function should not be used as part of a final application, as it is costly in performance, but is available to help provide some performance data that can be used while building an testing a client application.
See Also
SimConnect_RetrieveString
The SimConnect_RetrieveString function is used to assist in retrieving variable length narrow strings from a structure.
Syntax
SIMCONNECT_RECV* pData,
DWORD cbData,
void* pStringV,
char** ppszString,
DWORD* pcbString
);
Parameters
- pData
- [in] Pointer to a SIMCONNECT_RECV structure, containing the data.
- cbData
- [in] The size of the structure that inherits the SIMCONNECT_RECV structure, in bytes.
- pStringV
- [in] Pointer to a the start of the variable length string within the structure.
- ppszString
- [in, out] Specifies a pointer to a pointer to a character buffer that should be large enough to contain the maximum length of string that might be returned. On return this buffer should contain the retrieved string.
- pcbString
- [in, out] Pointer to a DWORD. On return this contains the length of the string in bytes.
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. |
Example
char title[1];
}
StructVS *pS = (StructVS*)&pObjData->dwData;
char *psztitle;
DWORD cbtitle;
hr = SimConnect_RetrieveString(pData, cbData, &pS->strings, &psztitle, &cbtitle)))
Working Sample
Primary sample | Variable Strings |
Remarks
This function does not communicate with the SimConnect server, but is a helper function to assist in the handling of variable length narrow strings. Its counterpart is the SimConnect_InsertString function. Note that this function works in the case where an empty string is in the structure returned by the server.
See Also
SimConnect_RetrieveStringW
The SimConnect_RetrieveStringW function is used to assist in retrieving variable length wide strings from a structure.
Syntax
SIMCONNECT_RECV* pData,
DWORD cbData,
void* pStringV,
wchar_t** ppszString,
DWORD* pcbString
);
Parameters
- pData
- [in] Pointer to a SIMCONNECT_RECV structure, containing the data.
- cbData
- [in] The size of the structure that inherits the SIMCONNECT_RECV structure, in bytes.
- pStringV
- [in] Pointer to a the start of the variable length string within the structure.
- ppszString
- [in, out] Specifies a pointer to a pointer to a character buffer that should be large enough to contain the maximum length of string that might be returned. On return this buffer should contain the retrieved string.
- pcbString
- [in, out] Pointer to a DWORD. On return this contains the length of the string in bytes.
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. |
Example
char title[1];
}
StructVS *pS = (StructVS*)&pObjData->dwData;
wchar_t *psztitle;
DWORD cbtitle;
hr = SimConnect_RetrieveStringW(pData, cbData, &pS->strings, &psztitle, &cbtitle)))
Working Sample
Primary sample | Variable Strings |
Remarks
This function does not communicate with the SimConnect server, but is a helper function to assist in the handling of variable length wide strings. Its counterpart is the SimConnect_InsertStringW function. Note that this function works in the case where an empty string is in the structure returned by the server.
See Also
Synchronous SimConnect Specific Functions
Overview
The Synchronous SimConnect API functions are used to synchronize the code running in your SimConnect add-on with the main sim. The Synchronous APIs do this by "pausing" execution of the sim code until it receives a release command from the SimConnect client, or a timeout occurs (default timeout value is 1.5 seconds).
The Synchronous API has 3 specific APIs that allow creating just Synchronous blocks and releases.
There are also extensions to other APIs related to Synchronous SimConnect. The External Sim API uses the Synchronous SimConnect APIs implicitly. The RequestData/SetData, RequestClientData/SetClientData, and RequestGroundInfo APIs have new _FLAG_BLOCK/_FLAG_UNBLOCK flag values to block/unblock the sim side code. There's also an extended SubscribeToSystemEventEx that includes a new flags value with a _FLAG_BLOCK.
The Synchronous API maintains a timeout check and if your add-on code hasn't released the block within the timeout value, then the block is released automatically and an exception is sent to your add-on code. The default value for this timeout is 1.5 seconds.
SimConnect_RequestSynchronousBlock
The SimConnect_RequestSynchronousBlock function is used to request a recurring callback (based on the Period) that is also a blocking callback.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID,
SIMCONNECT_PERIOD Period,
SIMCONNECT_DATA_REQUEST_FLAG Flags = 0,
DWORD origin = 0,
DWORD interval = 0,
DWORD limit = 0
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- RequestID
- [in] Specifies the ID of the client defined request. This is used later by the client to identify which request is receiving a reply. This value should be unique, re-using a RequestID will overwrite any previous request using the same ID.
- Period
- [in] One member of the SIMCONNECT_PERIOD enumeration type, specifying how often the reply is to be sent by the server and received by the client.
- Flags
- [in, optional] A DWORD containing one or more of the following values:
Flag value Description 0 The default, will assume SIMCONNECT_DATA_REQUEST_FLAG_BLOCK was provided. SIMCONNECT_DATA_REQUEST_FLAG_BLOCK Requested reply will be sent using a blocking callback. - origin
- [in, optional] The number of Period events that should elapse before transmission of the data begins. The default is zero, which means transmissions will start immediately.
- interval
- [in, optional] 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.
- limit
- [in, optional] 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.
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. |
See Also
- SimConnect_SynchronousUnblock
- SimConnect_SetSynchronousTimeout
- SIMCONNECT_PERIOD
- SimConnect API Reference
SimConnect_SynchronousUnblock
The SimConnect_SynchronousUnblock function is used to release the block on any blocking callback.
Syntax
HANDLE hSimConnect
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
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. |
Working Sample
Primary sample | External Sim |
See Also
SimConnect_SetSynchronousTimeout
The SimConnect_SetSynchronousTimeout function is used to set the timeout value for any blocking callbacks (if this time is exceeded without the block being released, the block is released and an exception is sent to the client).
Syntax
HANDLE hSimConnect
float fTimeSeconds
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- fTimeSeconds
- [in] New timeout value for blocking callbacks.
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. |
See Also
Menu Specific Functions
SimConnect_MenuAddItem
The SimConnect_MenuAddItem function is used to add a menu item associated with a client event.
Syntax
HANDLE hSimConnect,
const char* szMenuItem,
SIMCONNECT_CLIENT_EVENT_ID MenuEventID,
DWORD dwData
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szMenuItem
- [in] Null-terminated string containing the text for the menu item.
- MenuEventID
- [in] Specifies the client defined event ID, which is to be transmitted when the menu item is selected (in the uEventID parameter of the SIMCONNECT_RECV_EVENT structure).
- dwData
- [in] Double word containing a data value that the client can specify for its own use (it will be returned in the dwData parameter of the SIMCONNECT_RECV_EVENT structure.
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. |
Working Sample
Primary sample | Menu Items |
Remarks
The menu item will be added to the Add-ons menu. The Add-ons menu will only appear if there is at least one menu entry. Sub-menu items can be associated with this menu item, see SimConnect_MenuAddSubItem. If the text for the menu item should change, then remove the menu item first before adding the menu item with the correct text (see SimConnect_MenuDeleteItem).
Each client can add a number of main menu items.
See Also
SimConnect_MenuAddItem64
The SimConnect_MenuAddItem64 function is used to add a menu item associated with a client event. This function behaves the same as SimConnect_MenuAddItem with the following exceptions:
- This function accepts a 64-bit user context data parameter.
- This function sends a SIMCONNECT_RECV structure with a dwID value of SIMCONNECT_RECV_ID_EVENT_64.
- The received SIMCONNECT_RECV structure should be casted to type SIMCONNECT_RECV_EVENT_64
- The 64-bit qwData parameter of the SIMCONNECT_RECV_EVENT_64 structure contains the user context data.
- The 32-bit dwData parameter of the SIMCONNECT_RECV_EVENT_64 structure is unused.
Syntax
HANDLE hSimConnect,
const char* szMenuItem,
SIMCONNECT_CLIENT_EVENT_ID MenuEventID,
QWORD qwData
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szMenuItem
- [in] Null-terminated string containing the text for the menu item.
- MenuEventID
- [in] Specifies the client defined event ID, which is to be transmitted when the menu item is selected (in the uEventID parameter of the SIMCONNECT_RECV_EVENT_64 structure).
- qwData
- [in] Quad word containing a data value that the client can specify for its own use (it will be returned in the qwData parameter of the SIMCONNECT_RECV_EVENT_64 structure.
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. |
Working Sample
Primary sample | Menu Items |
Remarks
The menu item will be added to the Add-ons menu. The Add-ons menu will only appear if there is at least one menu entry. Sub-menu items can be associated with this menu item, see SimConnect_MenuAddSubItem64. If the text for the menu item should change, then remove the menu item first before adding the menu item with the correct text (see SimConnect_MenuDeleteItem).
Each client can add a number of main menu items.
See Also
SimConnect_MenuAddSubItem
The SimConnect_MenuAddSubItem function is used to add a sub-menu item associated with a client event.
Syntax
HANDLE hSimConnect,
SIMCONNECT_CLIENT_EVENT_ID MenuEventID,
const char* szMenuItem,
SIMCONNECT_CLIENT_EVENT_ID SubMenuEventID,
DWORD dwData
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- EventID
- [in] Specifies the client defined menu event ID. This is the ID of the menu item that this item should be added to.
- szMenuItem
- [in] Null-terminated string containing the text for the sub-menu item.
- EventID
- [in] Specifies the client defined sub-menu event ID, which is to be transmitted when the sub-menu item is selected (in the uEventID parameter of the SIMCONNECT_RECV_EVENT structure). This ID must be unique across all sub-menu items for the client.
- dwData
- [in] Double word containing a data value that the client can specify for its own use (it will be returned in the dwData parameter of the SIMCONNECT_RECV_EVENT structure.
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 maximum of 16 sub-menu items may be added to any one main menu item. Sub-menu items are always added to the end of the sub-menu item list. An exception, SIMCONNECT_EXCEPTION_TOO_MANY_OBJECTS, will be returned if an attempt is made to add more than 16 sub-menu items.
See Also
- SimConnect_MenuAddItem
- SimConnect_MenuDeleteItem
- SimConnect_MenuDeleteSubItem
- SimConnect API Reference
SimConnect_MenuAddSubItem64
The SimConnect_MenuAddSubItem64 function is used to add a sub-menu item associated with a client event. This function behaves the same as SimConnect_MenuAddSubItem with the following exceptions:
- This function accepts a 64-bit user context data parameter.
- This function sends a SIMCONNECT_RECV structure with a dwID value of SIMCONNECT_RECV_ID_EVENT_64.
- The received SIMCONNECT_RECV structure should be casted to type SIMCONNECT_RECV_EVENT_64
- The 64-bit qwData parameter of the SIMCONNECT_RECV_EVENT_64 structure contains the user context data.
- The 32-bit dwData parameter of the SIMCONNECT_RECV_EVENT_64 structure is unused.
Syntax
HANDLE hSimConnect,
SIMCONNECT_CLIENT_EVENT_ID MenuEventID,
const char* szMenuItem,
SIMCONNECT_CLIENT_EVENT_ID SubMenuEventID,
QWORD qwData
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- EventID
- [in] Specifies the client defined menu event ID. This is the ID of the menu item that this item should be added to.
- szMenuItem
- [in] Null-terminated string containing the text for the sub-menu item.
- EventID
- [in] Specifies the client defined sub-menu event ID, which is to be transmitted when the sub-menu item is selected (in the uEventID parameter of the SIMCONNECT_RECV_EVENT_64 structure). This ID must be unique across all sub-menu items for the client.
- qwData
- [in] Quad word containing a data value that the client can specify for its own use (it will be returned in the qwData parameter of the SIMCONNECT_RECV_EVENT_64 structure.
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 maximum of 16 sub-menu items may be added to any one main menu item. Sub-menu items are always added to the end of the sub-menu item list. An exception, SIMCONNECT_EXCEPTION_TOO_MANY_OBJECTS, will be returned if an attempt is made to add more than 16 sub-menu items.
See Also
- SimConnect_MenuAddItem64
- SimConnect_MenuDeleteItem
- SimConnect_MenuDeleteSubItem
- SimConnect API Reference
SimConnect_MenuDeleteItem
The SimConnect_MenuDeleteItem function is used to remove a client defined menu item.
Syntax
HANDLE hSimConnect,
const SIMCONNECT_CLIENT_EVENT_ID MenuEventID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- MenuEventID
- [in] Specifies the client defined event ID.
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. |
Working Sample
Primary sample | Menu Items |
Remarks
Menu items should be removed before a client closes. Removing the main menu item will remove any associated sub-menu items. Also see the remarks for SimConnect_MenuAddItem.
See Also
SimConnect_MenuDeleteSubItem
The SimConnect_MenuDeleteSubItem function is used to remove a specified sub-menu item.
Syntax
HANDLE hSimConnect,
SIMCONNECT_CLIENT_EVENT_ID MenuEventID,
const SIMCONNECT_CLIENT_EVENT_ID SubMenuEventID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- MenuEventID
- [in] Specifies the client defined menu event ID, from which the sub-menu item is to be removed.
- SubMenuEventID
- [in] Specifies the client defined sub-menu event ID.
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
If a sub-menu item is deleted from the middle of the sub-menu item list, the list will contract.
See Also
SimConnect_Text
The SimConnect_Text function is used to display a text menu, message window, or scrolling or static text, on the screen.
Syntax
HANDLE hSimConnect,
SIMCONNECT_TEXT_TYPE type,
float fTimeSeconds,
SIMCONNECT_CLIENT_EVENT_ID EventID,
DWORD cbUnitSize,
void* pDataSet
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- type
- [in] One member of the SIMCONNECT_TEXT_TYPE enumeration type.
- fTimeSeconds
- [in] The timeout value for the text, message, or menu in seconds. If zero is entered, the text, message, or menu will not timeout. For text and messages, this timeout value can be overridden if there are other text requests waiting in the queue (see the Remarks below). If the timeout requested exceeds the minimum display time, and another text request is waiting, the timeout value is overridden and the text will only be displayed for the minimum display time. The default minimum display time is two seconds for static text and 10 seconds for scrolling text, and 5 seconds for message windows. These can be changed in the [SimConnect] section of Prepar3D.cfg file using the TextMinPrintTimeSeconds, TextMinScrollTimeSeconds, and TextMinMessageWindowTimeSeconds settings.
- EventID
- [in] Specifies the client defined event ID, which will be returned along with the SIMCONNECT_TEXT_RESULT (in the dwData parameter) of a SIMCONNECT_RECV_EVENT structure.
- cbUnitSize
- [in] Specifies the size of pDataSet in bytes.
- pDataSet
- [in] Specifies the array of string data for the menu or text. For text and message windows simply enter the string. For a menu, the format of the string is a list of null-terminated string entries, with the menu title and prompt as the first two entries, for example: "Title\0Prompt\0Menu item 1\0Menu item 2\0", with a maximum of ten menu items. If an empty string is sent in pDataSet along with an EventID that matches a menu or text in the queue (see Remarks below), that entry will be removed from the queue, with the SIMCONNECT_TEXT_RESULT_REMOVED event being returned to the client. If a new set of menu items, or new text string, is sent with an EventID that matches an entry in the queue, that entry will be replaced in the queue, with the SIMCONNECT_TEXT_RESULT_REPLACED event being returned to the client. The entry will not lose its place in the queue. This change will take place even if the text or menu is being rendered on the screen.
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. |
Working Sample
Primary samples |
Text Menu FacilitiesData |
Remarks
Message windows, text, and menus can all be displayed simultaneously, however only one instance of each is allowed at any given time. Requests are queued as they are received, with only the topmost in the queue being displayed. There is one queue for menus and another for static and scrolling text. When a request is first displayed the SIMCONNECT_TEXT_RESULT_DISPLAYED event will be sent to the client. If a request joins the queue and cannot immediately be displayed the event SIMCONNECT_TEXT_RESULT_QUEUED will be sent. When it is the turn of the new request to be displayed the SIMCONNECT_TEXT_RESULT_DISPLAYED event will be sent. If the request is for a menu, and the user selects one of the menu entries, one of the SIMCONNECT_TEXT_RESULT_MENU_SELECT_N events will be returned (see the SIMCONNECT_TEXT_RESULT enumeration), and the menu closed.
The default location for message windows and static or scrolling text is along the top of the screen. A user can move and resize the window that the text is being displayed in, but it is not possible to specify an alternative location for the text programmatically.
When a message is sent, a TextEventCreated event is fired and can be listened for with SimConnect_SubscribeToSystemEvent