General Functions

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

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

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_CallDispatch
• SimConnect API Reference

---

SimConnect_AddClientEventToNotificationGroup

The SimConnect_AddClientEventToNotificationGroup function is used to add an individual client defined event to a notification group.

Syntax

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

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

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

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

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

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

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:

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.

See Also

• SimConnect API Reference
• SimConnect_GetNextDispatch

---

SimConnect_ClearClientDataDefinition

The SimConnect_ClearClientDataDefinition function is used to clear the definition of the specified client data.

Syntax

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

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

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

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

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

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

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

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 API Reference
• SimConnect_Open

---

SimConnect_CreateClientData

The SimConnect_CreateClientData function is used to request the creation of a reserved data area for this client.

Syntax

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

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

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 API Reference

---

SimConnect_GetNextDispatch

The SimConnect_GetNextDispatch function is used to process the next SimConnect message received, without the use of a callback function.

Syntax

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

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 API Reference
• SimConnect_CallDispatch

---

SimConnect_MapClientDataNameToID

The SimConnect_MapClientDataNameToID function is used to associate an ID with a named client data area.

Syntax

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

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

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 API Reference
• SimConnect_TransmitClientEvent

---

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

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

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 v4 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 v4\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

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

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:

. The minor number will be 0 and the major number 10. Use the LOWORD and HIWORD macros to easily extract the two numbers.

See Also

• SimConnect API Reference
• SimConnect_Close
  

---

SimConnect_RemoveClientEvent

The SimConnect_RemoveClientEvent function is used to remove a client defined event from a notification group.

Syntax

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

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

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

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

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

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 API Reference

---

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

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

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_MenuAddItem
• SimConnect API Reference

---

SimConnect_RequestSystemState

The SimConnect_RequestSystemState function is used to request information from a number of Prepar3D system components.

Syntax

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 API Reference
• SimConnect_SetSystemState

---

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

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 API Reference
• SimConnect_SetSystemState

---

SimConnect_RequestVersion

The SimConnect_RequestVersion function is used to request license type, Prepar3D version, and Prepar3D SimConnect version.

Syntax

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 API Reference

---

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.

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 API Reference

---

SimConnect_SetClientData

The SimConnect_SetClientData function is used to write one or more units of data to a client data area.

Syntax

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

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

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

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

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

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 API Reference
• SimConnect_MapClientEventToSimEvent
• SimConnect_MapInputEventToClientEvent

---

SimConnect_SetSystemState

The SimConnect_SetSystemState function is used to access a number of Prepar3D system components.

Syntax

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 API Reference
• SimConnect_RequestSystemState
• SimConnect_SubscribeToSystemEvent

---

SimConnect_SubscribeToSystemEvent

The SimConnect_SubscribeToSystemEvent function is used to request that a specific system event is notified to the client.

Syntax

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

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

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

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

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

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 API Reference
• SimConnect_MapClientEventToSimEvent
  

---

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:

1. This function accepts a 64-bit user context data parameter.
2. This function sends a SIMCONNECT_RECV structure with a dwID value of SIMCONNECT_RECV_ID_EVENT_64.
3. The received SIMCONNECT_RECV structure should be casted to type SIMCONNECT_RECV_EVENT_64
4. The 64-bit qwData parameter of the SIMCONNECT_RECV_EVENT_64 structure contains the user context data.
5. The 32-bit dwData parameter of the SIMCONNECT_RECV_EVENT_64 structure is unused.

Syntax

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

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 API Reference
• SimConnect_TransmitClientEvent
  
• SimConnect_MapClientEventToSimEvent
  

---

SimConnect_UnsubscribeFromSystemEvent

The SimConnect_UnsubscribeFromSystemEvent function is used to request that notifications are no longer received for the specified system event.

Syntax

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

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_SubscribeToSystemEvent
• SimConnect API Reference
  

---

SimConnect_InsertString

The SimConnect_InsertString function is used to assist in adding variable length narrow strings to a structure.

Syntax

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 API Reference
• SimConnect_RetrieveString
  

---

SimConnect_InsertStringW

The SimConnect_InsertStringW function is used to assist in adding variable length wide strings to a structure.

Syntax

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 API Reference
• SimConnect_RetrieveStringW
  

---

SimConnect_RequestResponseTimes

The SimConnect_RequestResponseTimes function is used to provide some data on the performance of the client-server connection.

Syntax

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

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 API Reference

---

SimConnect_RetrieveString

The SimConnect_RetrieveString function is used to assist in retrieving variable length narrow strings from a structure.

Syntax

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

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 API Reference
• SimConnect_InsertString

---

SimConnect_RetrieveStringW

The SimConnect_RetrieveStringW function is used to assist in retrieving variable length wide strings from a structure.

Syntax

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

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

• SimConnect API Reference
• SimConnect_InsertStringW

---

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

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

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_RequestSynchronousBlock
• SimConnect_SetSynchronousTimeout
• SimConnect API Reference

---

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

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

• SimConnect_RequestSynchronousBlock
• SimConnect_SynchronousUnblock
• SimConnect API Reference

---

Menu Specific Functions

SimConnect_MenuAddItem

The SimConnect_MenuAddItem function is used to add a menu item associated with a client event.

Syntax

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_MenuDeleteItem
• SimConnect_MenuDeleteSubItem
• SimConnect API Reference

---

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:

1. This function accepts a 64-bit user context data parameter.
2. This function sends a SIMCONNECT_RECV structure with a dwID value of SIMCONNECT_RECV_ID_EVENT_64.
3. The received SIMCONNECT_RECV structure should be casted to type SIMCONNECT_RECV_EVENT_64
4. The 64-bit qwData parameter of the SIMCONNECT_RECV_EVENT_64 structure contains the user context data.
5. The 32-bit dwData parameter of the SIMCONNECT_RECV_EVENT_64 structure is unused.

Syntax

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_MenuDeleteItem
• SimConnect_MenuDeleteSubItem
• SimConnect API Reference

---

SimConnect_MenuAddSubItem

The SimConnect_MenuAddSubItem function is used to add a sub-menu item associated with a client event.

Syntax

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:

1. This function accepts a 64-bit user context data parameter.
2. This function sends a SIMCONNECT_RECV structure with a dwID value of SIMCONNECT_RECV_ID_EVENT_64.
3. The received SIMCONNECT_RECV structure should be casted to type SIMCONNECT_RECV_EVENT_64
4. The 64-bit qwData parameter of the SIMCONNECT_RECV_EVENT_64 structure contains the user context data.
5. The 32-bit dwData parameter of the SIMCONNECT_RECV_EVENT_64 structure is unused.

Syntax

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

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
• SimConnect API Reference

---

SimConnect_MenuDeleteSubItem

The SimConnect_MenuDeleteSubItem function is used to remove a specified sub-menu item.

Syntax

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_MenuAddItem
• SimConnect_MenuAddSubItem
• SimConnect_MenuDeleteItem
• SimConnect API Reference

---

SimConnect_Text

The SimConnect_Text function is used to display a text menu, message window, or scrolling or static text, on the screen.

Syntax

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

See Also

• SimConnect_MenuAddItem
• SimConnect API Reference