MSFS SDK Documentation Logo
Flighting
  • SDK Documentation

SimConnect_SubscribeToSystemEvent

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

 

Syntax
HRESULT SimConnect_SubscribeToSystemEvent(
    HANDLE  hSimConnect,
    SIMCONNECT_CLIENT_EVENT_ID  EventID,
    const char*  SystemEventName
    );

 

Parameters
ParameterDescriptionType
hSimConnectHandle to a SimConnect object.Integer
EventIDSpecifies the ID of the client event.Integer
SystemEventNameThe string name for the requested system event, which should be one from the table below (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).String

 

The following table shows the available SystemEventName variables:

System Event NameDescription
1secRequest a notification every second.
4secRequest a notification every four seconds.
6HzRequest notifications six times per second. This is the same rate that joystick movement events are transmitted.
AircraftLoadedRequest 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.
CrashedRequest a notification if the user aircraft crashes.
CrashResetRequest a notification when the crash cut-scene has completed.
CustomMissionActionExecutedRequest a notification when a mission action has been executed.
DialogFrame
FlightLoadedRequest a notification when a flight is loaded. Note that when a flight is ended, a default flight is typically loaded, so these events will occur when flights and missions are started and finished. The filename of the flight loaded is returned in a SIMCONNECT_RECV_EVENT_FILENAME structure.
FlightSavedRequest a notification when a flight is saved correctly. The filename of the flight saved is returned in a SIMCONNECT_RECV_EVENT_FILENAME structure.
FlightPlanActivatedRequest 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.
FlightPlanDeactivatedRequest a notification when the active flight plan is de-activated.
FrameRequest notifications every visual frame. Information is returned in a SIMCONNECT_RECV_EVENT structure.
MissionCompletedRequest a notification when the user has completed a mission. Refer to the SIMCONNECT_MISSION_END enum for more information.
MultiplayerClientStartedUsed 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.
MultiplayerServerStartedUsed 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.
MultiplayerSessionEndedRequest a notification when the mutliplayer 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 wil 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.
ObjectAddedRequest a notification when an AI object is added to the simulation. Refer also to the SIMCONNECT_RECV_EVENT_OBJECT_ADDREMOVE structure.
ObjectRemovedRequest a notification when an AI object is removed from the simulation. Refer also to the SIMCONNECT_RECV_EVENT_OBJECT_ADDREMOVE structure.
PauseRequest notifications when the flight 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.
Pause_EX1

Request notifications when the flight is paused or unpaused, and also immediately returns the current pause state with more detail than the regular Pause system event. The state is returned in the dwData parameter, and will be a combination (OR) of the following defines:

#define PAUSE_STATE_FLAG_OFF                0    // No Pause
#define PAUSE_STATE_FLAG_PAUSE              1    // "full" Pause (sim + traffic + etc...)
#define PAUSE_STATE_FLAG_PAUSE_WITH_SOUND   2    // FSX Legacy Pause (not used anymore)
#define PAUSE_STATE_FLAG_ACTIVE_PAUSE       4    // Pause was activated using the "Active Pause" Button
#define PAUSE_STATE_FLAG_SIM_PAUSE          8    // Pause the player sim but traffic, multi, etc... will still run
PausedRequest a notification when the flight is paused.
PauseFrameRequest notifications for every visual frame that the simulation is paused. Information is returned in a SIMCONNECT_RECV_EVENT structure.
PositionChangedRequest a notification when the user changes the position of their aircraft through a dialog.
RaceEndRequest 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.
RaceLapRequest 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.
SimRequest notifications when the flight 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.
SimStartThe simulator is running. Typically the user is actively controlling the aircraft on the ground or in the air. However, in some cases additional pairs of SimStart/SimStop events are sent. For example, when a flight is reset the events that are sent are SimStop, SimStart, SimStop, SimStart. Also when a flight is started with the SHOW_OPENING_SCREEN value set to zero, then an additional SimStart/SimStop pair are sent before a second SimStart event is sent when the scenery is fully loaded. The opening screen provides the options to change aircraft, departure airport, and so on.
SimStopThe simulator is not running. Typically the user is loading a flight, navigating the shell or in a dialog.
SoundRequests 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.
UnpausedRequest a notification when the flight is un-paused.
ViewRequests 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).
WeatherModeChangedRequest a notification when the weather mode is changed.

 

Return Values

The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Return valueDescription
S_OKThe function succeeded.
E_FAILThe function failed.

 

Example
static enum EVENT_ID {
    EVENT_FLIGHT_LOAD,
    EVENT_RECUR_1SEC,
    EVENT_RECUR_FRAME, 
    };
hr = SimConnect_SubscribeToSystemEvent(hSimConnect, EVENT_FLIGHT_LOAD, "FlightLoaded");
hr = SimConnect_SubscribeToSystemEvent(hSimConnect, EVENT_RECUR_1SEC,  "1sec");
hr = SimConnect_SubscribeToSystemEvent(hSimConnect, EVENT_RECUR_FRAME, "frame");
hr = SimConnect_SetSystemEventState(hSimConnect, EVENT_RECUR_FRAME, SIMCONNECT_STATE_OFF);
Working Samples

 

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.

 

Prev
SimConnect_SetSystemEventState
Next
SimConnect_UnsubscribeFromSystemEvent