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:

 

 

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.

 

 

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.

 

 

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.


 

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 recieve a minimal amount of information from facilities.
SIMCONNECT_ICAO Struct Returned as part of the data within the SIMCONNECT_RECV_FACILITIES_MINIMAL structure.
SIMCONNECT_INPUT_EVENT_DESCRIPTOR Struct Return an item of data for a specific input event.
SIMCONNECT_INPUT_EVENT_TYPE Enum Used with the SimConnect_GetInputEvent call to specify the data type used and help you cast the return value correctly.
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_ENUMERATE_INPUT_EVENT_PARAMS Struct Returned as a response to SimConnect_EnumerateInputEventParams with the available parameters for an input event.
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_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_ENUMERATE_INPUT_EVENTS Struct Used to return a single page of data about an input event.
SIMCONNECT_RECV_GET_INPUT_EVENT Struct Used to return the value of a specific input event.
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_SUBSCRIBE_INPUT_EVENT Struct Used to return the value of a subscribed input event.
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.

Currently not used, and all values will be 0.
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_HIGHEST_MASKABLE 10000000 The highest priority that allows events to be masked.
No longer used in Microsoft Flight Simulator.
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 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'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 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 does not mask any events.

 

 

Deprecated Functions, Enums and Structs

The following items are all deprecated in the Microsoft Flight Simulator SimConnect API.

 

 

Missions

Function Description

 

SimConnect_CompleteCustomMissionAction

 

 Deprecated

 

SimConnect_ExecuteMissionAction

 

 

 

Weather

Function Description
SimConnect_WeatherCreateStation Deprecated.
SimConnect_WeatherCreateThermal
SimConnect_WeatherRemoveStation
SimConnect_WeatherRemoveThermal
SimConnect_WeatherRequestCloudState
SimConnect_WeatherRequestInterpolatedObservation
SimConnect_WeatherRequestObservationAtNearestStation
SimConnect_WeatherRequestObservationAtStation
SimConnect_WeatherSetDynamicUpdateRate
SimConnect_WeatherSetModeCustom
SimConnect_WeatherSetModeGlobal
SimConnect_WeatherSetModeServer
SimConnect_WeatherSetModeTheme
SimConnect_WeatherSetObservation

 

 

Menu

Function Description

SimConnect_MenuAddItem

 Deprecated

SimConnect_MenuAddSubItem

SimConnect_MenuDeleteItem
SimConnect_MenuDeleteSubItem

 

 

Enums/Structs

Function Description

SimConnect_MenuAddItem

 Deprecated
SimConnect_Text
SIMCONNECT_TEXT_TYPE
SIMCONNECT_RECV_EVENT_MULTIPLAYER_CLIENT_STARTED
SIMCONNECT_RECV_EVENT_MULTIPLAYER_SERVER_STARTED
SIMCONNECT_RECV_EVENT_MULTIPLAYER_SESSION_ENDED