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. |
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 |
---|---|
Returns the ID of the last packet sent to the SimConnect server. | |
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. |
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_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.