SIMCONNECT API REFERENCE

This section lists all the API functions, structures, enumerations, and other coding information necessary to build SimConnect clients. Information on each API call includes some example code, however this code does not form a complete program in any sense, but is simply used to highlight the general way the API should be called.

 

Please note that the DevMode menus have an option to open the SimConnect debug tool, which can be very useful to help you find, diagnose, and fix any issues you have with your SimConnect apps:

• SimConnect Inspector

 

 

General

Function	Description
DispatchProc	Written by the developer of the SimConnect client, as a callback function to handle all the communications with the server
SimConnect_Open	Used to send a request to the Flight Simulator server to open up communications with a new client.
SimConnect_Close	Used to request that the communication with the server is ended.
SimConnect_CallDispatch	Used to process the next SimConnect message received through the specified callback function.
SimConnect_GetNextDispatch	Used to process the next SimConnect message received, without the use of a callback function.
SimConnect_RequestSystemState	Used to request information from a number of Flight Simulator system components.
SimConnect_MapClientEventToSimEvent	Used to associate a client defined event ID with a Flight Simulator event name.
SimConnect_SubscribeToSystemEvent	Used to request that a specific system event is notified to the client.
SimConnect_SetSystemEventState	Used to turn requests for event information from the server on and off.
SimConnect_UnsubscribeFromSystemEvent	Used to request that notifications are no longer received for the specified system event.
SimConnect_SetNotificationGroupPriority	Used to set the priority of a notification group.

 

 

Events And Data

Function	Description
SimConnect_RequestDataOnSimObject	Used to request when the SimConnect client is to receive data values for a specific object.
SimConnect_RequestDataOnSimObjectType	Used to retrieve information about simulation objects of a given type that are within a specified radius of the user's aircraft.
SimConnect_AddClientEventToNotificationGroup	Used to add an individual client defined event to a notification group.
SimConnect_RemoveClientEvent	Used to remove a client defined event from a notification group.
SimConnect_TransmitClientEvent	Used to request that the Flight Simulator server transmit to all SimConnect clients the specified client event along with a single event parameter.
SimConnect_TransmitClientEvent_EX1	Used to request that the Flight Simulator server transmit to all SimConnect clients the specified client event with up to five event parmaters.
SimConnect_MapClientDataNameToID	Used to associate an ID with a named client date area.
SimConnect_RequestClientData	Used to request that the data in an area created by another client be sent to this client.
SimConnect_CreateClientData	Used to request the creation of a reserved data area for this client.
SimConnect_AddToClientDataDefinition	Used to add an offset and a size in bytes, or a type, to a client data definition.
SimConnect_AddToDataDefinition	Used to add a Flight Simulator simulation variable name to a client defined object definition.
SimConnect_SetClientData	Used to write one or more units of data to a client data area.
SimConnect_SetDataOnSimObject	Used to make changes to the data properties of an object.
SimConnect_ClearClientDataDefinition	Used to clear the definition of the specified client data.
SimConnect_ClearDataDefinition	Used to remove all simulation variables from a client defined object.
SimConnect_RequestNotificationGroup	Used to request events from a notification group when the simulation is in Dialog Mode.
SimConnect_ClearInputGroup	Used to remove all the input events from a specified input group object.
SimConnect_ClearNotificationGroup	Used to remove all the client defined events from a notification group.
SimConnect_RequestReservedKey	Used to request a specific keyboard TAB-key combination applies only to this client.
SimConnect_SetInputGroupPriority	Used to set the priority for a specified input group object.
SimConnect_SetInputGroupState	Used to turn requests for input event information from the server on and off.
SimConnect_RemoveInputEvent	Used to remove an input event from a specified input group object.

 

 

AI Objects

Function	Description
SimConnect_AICreateEnrouteATCAircraft	Used to create an AI controlled aircraft that is about to start or is already underway on its flight plan.
SimConnect_AICreateNonATCAircraft	Used to create an aircraft that is not flying under ATC control (so is typically flying under VFR rules).
SimConnect_AICreateParkedATCAircraft	Used to create an AI controlled aircraft that is currently parked and does not have a flight plan.
SimConnect_AICreateSimulatedObject	Used to create AI controlled objects other than aircraft.
SimConnect_AIReleaseControl	Used to clear the AI control of a simulated object, typically an aircraft, in order for it to be controlled by a SimConnect client.
SimConnect_AIRemoveObject	Used to remove any object created by the client using one of the AI creation functions.
SimConnect_AISetAircraftFlightPlan	Used to set or change the flight plan of an AI controlled aircraft.

 

 

Flights

Function	Description
SimConnect_FlightLoad	Used to load an existing flight file.
SimConnect_FlightSave	Used to save the current state of a flight to a flight file.
SimConnect_FlightPlanLoad	Used to load an existing flight plan.

 

 

Input Events

Function	Description
SimConnect_EnumerateControllers	This is used to retrieve a list of every device that is currently plugged into the simulation.
SimConnect_EnumerateInputEvents	Used to retrieve a paginated list of all available InputEvents for the current aircraft along with their associated hash (CRC based).
SimConnect_EnumerateInputEventParams	Used to retrieve a list of all parameters from an input event.
SimConnect_GetInputEvent	Used to retrieve the value of a specific input event (identified by its hash).
SimConnect_MapInputEventToClientEvent	Used to connect input events (such as keystrokes, joystick or mouse movements) with the sending of appropriate event notifications. IMPORTANT! This function is deprecated due to a bug and you should always use SimConnect_MapInputEventToClientEvent_EX1.
SimConnect_MapInputEventToClientEvent_EX1	Used to connect input events (such as keystrokes, joystick or mouse movements) with the sending of appropriate event notifications.
SimConnect_SetInputEvent	Used to set the value of a specific input event (identified by its hash).
SimConnect_SubscribeInputEvent	Used to subscribe an input event and generate when the value changes.
SimConnect_UnsubscribeInputEvent	Used to unsubscribe from an input event that has previously been subscribed to.

 

 

Debug

Function	Description
SimConnect_GetLastSentPacketID	Returns the ID of the last packet sent to the SimConnect server.
SimConnect_RequestResponseTimes	Used to provide some data on the performance of the client-server connection.
SimConnect_InsertString	Used to assist in adding variable length strings to a structure.
SimConnect_RetrieveString	Used to assist in retrieving variable length strings from a structure.

 

 

Facilities

Function	Description
SimConnect_AddToFacilityDefinition	This function is used to create a facility data definition.
SimConnect_AddFacilityDataDefinitionFilter	Used add a filter on a node in the FacilityDataDefinition to block sending data according to this filter, thus reduce the amount of data received and limit it to only that which is required.
SimConnect_ClearAllFacilityDataDefinitionFilters	Used to clear all applied facility definition filters.
SimConnect_RequestFacilitesList	Request a list of all the facilities of a given type currently held in the facilities cache.
SimConnect_RequestFacilitiesList_EX1	Alias for the SimConnect_RequestFacilitesList. Should be used with the other _EX1 functions.
SimConnect_RequestFacilityData	Used to request data according to a predefined object, an ICAO and a region.
SimConnect_RequestFacilityData_EX1	This function is practically identical in functionality to the SimConnect_RequestFacilityData function, only it has an additional return value used to identify waypoints when there is an ICAO/Region overlap with VOR or NDB.
SimConnect_RequestJetwayData	Used to request data from an airport about the jetways available.
SimConnect_SubscribeToFacilities	Used to request notifications when a facility of a certain type is added to the facilities cache.
SimConnect_SubscribeToFacilities_EX1	Used to request notifications when a facility of a certain type is added to the facilities cache, as well as provide callbacks for when an element is added/removed.
SimConnect_UnsubscribeToFacilities	Used to request that notifications of additions to the facilities cache are not longer sent.
SimConnect_UnsubscribeToFacilities_EX1	Used to request that notifications of additions or removals to the facilities cache are not longer sent.

 

 

Structures And Enumerations

Name	Structure or Enumeration	Description
SIMCONNECT_CLIENT_DATA_PERIOD	Enum	Used with the SimConnect_RequestClientData call to specify how often data is to be sent to the client.
SIMCONNECT_CONTROLLER_ITEM	Struct	A struct containing information for a single connected controller. Returned as part of the SIMCONNECT_RECV_CONTROLLERS_LIST list.
SIMCONNECT_DATATYPE	Enum	Used with the SimConnect_AddToDataDefinition call to specify the data type that the server should use to return the specified data to the client.
SIMCONNECT_DATA_FACILITY_AIRPORT	Struct	Used to return information on a single airport in the facilities cache.
SIMCONNECT_DATA_FACILITY_NDB	Struct	Used to return information on a single NDB station in the facilities cache.
SIMCONNECT_DATA_FACILITY_VOR	Struct	Used to return information on a single VOR station in the facilities cache.
SIMCONNECT_DATA_FACILITY_WAYPOINT	Struct	Used to return information on a single waypoint in the facilities cache.
SIMCONNECT_DATA_INITPOSITION	Struct	Used to initialize the position of a the user or AI controlled aircraft.
SIMCONNECT_DATA_LATLONALT	Struct	Used to hold a world position.
SIMCONNECT_DATA_PBH	Struct	Used to hold a world orientation.
SIMCONNECT_DATA_MARKERSTATE	Struct	Used to help graphically link flight model data with the graphics model.
SIMCONNECT_DATA_RACE_RESULT	Struct	This is used to hold multiplayer racing results.
SIMCONNECT_DATA_WAYPOINT	Struct	Used to hold all the necessary information on a waypoint.
SIMCONNECT_DATA_XYZ	Struct	Used to hold a 3D co-ordinate.
SIMCONNECT_EXCEPTION	Enum	Used with the SIMCONNECT_RECV_EXCEPTION structure to return information on an error that has occurred.
SIMCONNECT_FACILITY_DATA_TYPE	Enum	Used with the SIMCONNECT_RECV_FACILITY_DATA structure to give the type of data that is being received.
SIMCONNECT_FACILITY_LIST_TYPE	Enum	Used to determine which type of facilities data is being requested or returned.
SIMCONNECT_FACILITY_MINIMAL	Struct	Used to receive a minimal amount of information from facilities.
SIMCONNECT_ICAO	Struct	Returned as part of the data within the SIMCONNECT_RECV_FACILITIES_MINIMAL structure.
SIMCONNECT_JETWAY_DATA	Struct	Returned as part of the data within the SIMCONNECT_RECV_JETWAY_DATA structure.
SIMCONNECT_MISSION_END	Enum	Used to specify the three possible outcomes of a mission.
SIMCONNECT_PERIOD	Enum	Used with the SimConnect_RequestDataOnSimObject call to specify how often data is to be sent to the client.
SIMCONNECT_RECV	Struct	Used with the SIMCONNECT_RECV_ID enumeration to indicate which type of structure has been returned.
SIMCONNECT_RECV_AIRPORT_LIST	Struct	Used to return a list of SIMCONNECT_DATA_FACILITY_AIRPORT structures.
SIMCONNECT_RECV_ASSIGNED_OBJECT_ID	Struct	Used to return an object ID that matches a request ID.
SIMCONNECT_RECV_CLIENT_DATA	Struct	Will be received by the client after a successful call to SimConnect_RequestClientData. The structure is identical to SIMCONNECT_RECV_SIMOBJECT_DATA.
SIMCONNECT_RECV_CONTROLLERS_LIST	Struct	Will be received by the client after a successful call to SimConnect_EnumerateControllers, and will contain a list of SIMCONNECT_CONTROLLER_ITEM structs - one for each connected control device.
SIMCONNECT_RECV_EVENT	Struct	Used to return an event ID to the client along with a single parameter.
SIMCONNECT_RECV_EVENT_EX1	Struct	Used to return an event ID to the client along with up to five parameters.
SIMCONNECT_RECV_EVENT_FILENAME	Struct	Used with the SimConnect_SubscribeToSystemEvent to return a filename and an event ID to the client.
SIMCONNECT_RECV_EVENT_FRAME	Struct	Used with the SimConnect_SubscribeToSystemEvent to return the frame rate and simulation speed to the client.
SIMCONNECT_RECV_EVENT_MULTIPLAYER_CLIENT_STARTED	Struct	This is sent to a client when they have successfully joined a multi-player race.
SIMCONNECT_RECV_EVENT_MULTIPLAYER_SERVER_STARTED	Struct	This is sent to the host when the session is visible to other users in the lobby.
SIMCONNECT_RECV_EVENT_MULTIPLAYER_SESSION_ENDED	Struct	This is sent to a client when they have requested to leave a race, or to all players when the session is terminated by the host.
SIMCONNECT_RECV_EVENT_OBJECT_ADDREMOVE	Struct	Used to return the type and ID of an AI object that has been added or removed from the simulation, by any client.
SIMCONNECT_RECV_EVENT_RACE_END	Struct	This is used in multi-player racing to hold the results for one player at the end of a race.
SIMCONNECT_RECV_EVENT_RACE_LAP	Struct	This is used in multi-player racing to hold the results for one player at the end of a lap.
SIMCONNECT_RECV_EXCEPTION	Struct	Used with the SIMCONNECT_EXCEPTION enumeration type to return information on an error that has occurred.
SIMCONNECT_RECV_FACILITIES_LIST	Struct	Used to provide information on the number of elements in a list of facilities returned to the client, and the number of packets that were used to transmit the data.
SIMCONNECT_RECV_FACILITY_MINIMAL_LIST	Struct	Used to provide minimal information on the number of elements in a list of facilities returned to the client, and the number of packets that were used to transmit the data.
SIMCONNECT_RECV_FACILITY_DATA	Struct	Used to provide information that has been requested from the server using the SimConnect_RequestFacilityData function.
SIMCONNECT_RECV_FACILITY_DATA_END	Struct	Used to signify the end of a data stream from the server after a call to SimConnect_RequestFacilityData.
SIMCONNECT_RECV_ID	Enum	Used within the SIMCONNECT_RECV structure to indicate which type of structure has been returned.
SIMCONNECT_RECV_JETWAY_DATA	Struct	Returned by the SimConnect_RequestJetwayData and contains data relating to one or more jetways.
SIMCONNECT_RECV_LIST_TEMPLATE	Struct	Used to provide information on the number of elements in a list returned to the client, and the number of packets that were used to transmit the data.
SIMCONNECT_RECV_NDB_LIST	Struct	Used to return a list of SIMCONNECT_DATA_FACILITY_NDB structures.
SIMCONNECT_RECV_OPEN	Struct	Used to return information to the client, after a successful call to SimConnect_Open.
SIMCONNECT_RECV_QUIT	Struct	This is an identical structure to the SIMCONNECT_RECV structure.
SIMCONNECT_RECV_RESERVED_KEY	Struct	Used with the SimConnect_RequestReservedKey function to return the reserved key combination.
SIMCONNECT_RECV_SIMOBJECT_DATA	Struct	Will be received by the client after a successful call to SimConnect_RequestDataOnSimObject or SimConnect_RequestDataOnSimObjectType.
SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE	Struct	Will be received by the client after a successful call to SimConnect_RequestDataOnSimObjectType. The structure is identical to SIMCONNECT_RECV_SIMOBJECT_DATA.
SIMCONNECT_RECV_SYSTEM_STATE	Struct	Used with the SimConnect_RequestSystemState function to retrieve specific Flight Simulator systems states and information.
SIMCONNECT_RECV_VOR_LIST	Struct	Used to return a list of SIMCONNECT_DATA_FACILITY_VOR structures.
SIMCONNECT_RECV_WAYPOINT_LIST	Struct	Used to return a list of SIMCONNECT_DATA_FACILITY_WAYPOINT structures.
SIMCONNECT_SIMOBJECT_TYPE	Enum	Used with the SimConnect_RequestDataOnSimObjectType call to request information on specific or nearby objects.
SIMCONNECT_STATE	Enum	Used with the SimConnect_SetSystemEventState call to turn the reporting of events on and off.
SIMCONNECT_TEXT_RESULT	Enum	Used to specify which event has occurred as a result of a call to SimConnect_Text.
SIMCONNECT_VERSION_BASE_TYPE	Struct	The harware version information. Returned as part of the SIMCONNECT_CONTROLLER_ITEM struct.
SIMCONNECT_WAYPOINT_FLAGS	Enum	Used with the SIMCONNECT_DATA_WAYPOINT structure to define waypoints.

 

 

SimConnect Priorities

SimConnect constants define the following priorities:

 

Constant	Priority Val	Description
SIMCONNECT_GROUP_PRIORITY_HIGHEST	1	The very highest priority.
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 Microsoft Flight Simulator 2024 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. Microsoft Flight Simulator 2024'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 Microsoft Flight Simulator 2024 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. Microsoft Flight Simulator 2024 does not mask any events.