Core‎ > ‎

SimConnect

Overview

The SimConnect SDK can be used by programmers to write add-on components for Flight Sim World. Add-on components for Flight Sim World can be written in C or C++. Typically the components will perform one or more of the following:
  • Add the processing for a new complex gauge, or other instrument, to Flight Sim World.
  • Replace Flight Sim World processing of one or more events with new logic.
  • Record or monitor a flight.
  • Extend the mission system of Flight Sim World.
  • Create and set the flight plans for AI (non-user) aircraft.
  • Enable new hardware to work with Flight Sim World.
  • Control an additional camera that the user can optionally select to view.

See Also

Setup

This section describes how to set up a development environment for SimConnect.

SimConnect Projects

To build SimConnect add-ons, you must use Visual Studio 2015 or later. To build the project make sure you have completed the following steps.

C/C++ Projects

  1. For C or C++ add-ons, start a new Win32 Console Application project if the add-on will have no user interface. Start a new Win32 Project or MFC Application if the add-on will have a user interface. For the platform, use x64.
  2. Include the SimConnect.h header file.
  3. Link to the SimConnect.lib library, by adding SimConnect.lib to the Additional Dependencies (see image below):
  4. Build the application using the function calls described in this document.

DLL Projects

  1. Create and add a definition file to the project. This is needed because SimConnect expects the exported names DLLStart and DLLStop to be undecorated (by default additional characters are added to these names). The definition file can be created by selecting Project/Add New Item from the main menu in Visual Studio. Edit the definition (.def) file so it looks like this (where DLL Project is the name of your project):

    LIBRARY "DLLProject"
    EXPORTS
    DLLStart
    DLLStop

  2. Confirm that the definition file has been added to the project by checking the Linker\Input properties (see image above)
  3. Pay particular attention to the remarks and reference samples for SimConnect_CallDispatch.

All Projects

  1. Ensure that Visual Studio 2015 or later has been set to 64 bit only.
  2. Ensure the SimConnect.ini file is in your My Documents\Flight Sim World folder. You do not usually have to make any changes to this file. The SimConnect.ini file provided ensures that the SimConnect debug window opens to display communication information between the server and the clients.
  3. If the client is to work remotely, write a SimConnnect.cfg file for it.
  4. Ensure the EXE.xml, DLL.xml files and SimConnect.xml files are in the %APPDATA%\Dovetail Games\FSW folder, and edit these files according to the instructions that follow.
  5. Run Flight Sim World to test your SimConnect client.

The SimConnect.ini file

The default SimConnect.ini file will enable the debug window and disable the log file. Use a semi-colon to start a comment, or comment out a directive. The file should be in your My Documents\Flight Sim World folder.

Directive Values Description
level Verbose, Normal, Warning, Error, Off Set the level of text communication to be provided to the console, debug string, or log file.
console Yes, No Open a command line debug window to display server to client communication.
OutputDebugString Yes, No Sends the output text to the Platform SDK OutputDebugString. Refer to MSDN documentation for more details
file Filename

Output communications to a log file. If the text %03u is included in the filename, then the filename will be incremented each time Flight Sim World starts, so giving a new log file for each test run.

Example: file=c:\temp\simconnect%03u.log

Note that because Flight Sim World does not run with elevated privileges it will not be able to write to the root folder of a drive (i.e. C:\).

file_next_index Integer The index of the first log file. Subsequent log files will have the index number incremented by one.

The SimConnect.cfg file

The SimConnect.cfg file contains communications information for a client (the SimConnect.xml file contains information for a server). This file is only required if a client is going to access Flight Sim World running on a remote machine, and should be placed in the My Documents folder, or in the same folder as the client application or library, on the computer the client is running on.

The SimConnect.cfg file can contain a number of configurations, identified in sections with the [SimConnect.N] title. The index number is used as a parameter in the SimConnect_Open function. This is useful for applications that communicate with a number of different machines that are running Flight Sim World. The default configuration index is zero, and if there is only one configuration in the file, no index number is required.

Directive Values Description
Protocol

Pipe,

IPv4, IPv6

Pipe uses a Named-Pipes communcation system. The IPv4 and IPv6 protocols are available on computers running Windows, with IPv4 as the default. IPv6 has more security features and is recommended. If IPv6 is not already installed, there is a utility to install it in the SimConnect SDK\config folder.

The order in which protocols are evaluated is: Pipe, IPv6, IPv4, Pipe. So, for example, if this entry is set at IPv6, then IPv4 and Pipe will evaluated in that order. The first working protocol found will be used. The advantage of Pipe communication is that it avoids conflict with firewalls and virus protection software when the connection is local, which of course is not the situation if a SimConnect.cfg file is required.

Address

 

Port

  The Address and Port of the SimConnect server should be entered in these fields, these will be the same values as those in the appropriate Comm section of the Simconnect.xml file. A good knowledge of Windows networking and client/server applications will be needed to set these correctly. The address can be the name of a computer in a Domain Controller environment.
MaxReceiveSize Integer The maximum packet size. The default is 8192. If the client receives a packet larger than this size, it will disconnect from the server.
DisableNagle 0, 1 Set to 1 to disable the Nagle packet optimization algorithms.

The EXE.xml and DLL.xml files

These files contain all the clients that will be activated by Flight Sim World on start up. EXE.xml should contain all the .exe application add-ons, and DLL.xml should contain all the .dll library based add-ons. To activate just your one client, edit the appropriate file so it matches the following table, with the name and path to your client replacing the text in bold. The format of both files is identical. Both files should be in the %APPDATA%\Dovetail Games\FSW folder.

For each library add-on enter the following information into DLL.xml, and for each application add-on enter the following information into EXE.xml:

XML Description
< Launch.Addon > Add one Launch.Addon section for each client.
< Disabled > False< /Disabled > Set to True to disable the client.
< Name >Your Client Name < /Name > The client application or library name.
<ManualLoad> Optional, defaults to False. Set this to True to force a dialog to appear, asking the user if they want the addon to be loaded. If this is set to False, no dialog appears.
< Path > Path\Client.exe/.dll< /Path >

If the client is local, the path relative to the main Flight Sim Worldfolder where the simulation is installed, and the client application or library name.

If the client is remote, and a share on the remote machine is accessible from the machine on which Flight Sim World is running, the client will be launched.

Definition: UNC provides a naming convention for identifying network resources. UNC names consist of three parts, a server name, a share name, and an optional file path, that are combined using backslashes as follows:

\\server\share\file_path

<CommandLine>< /CommandLine > This applies to .exe files only. Provides a command line string to the application.
< /Launch.Addon >  

Sample DLL.xml file

The following sample DLL.xml file contains two add-ons, the first enabled and the second disabled. All of the add-ons can be disabled by setting the global <Disabled> entry to True. If the global <ManualLoad> is set to True, then the user will be prompted with a dialog as to whether they would like the add-ons to be loaded or not (this overrides the local <ManualLoad> setting for the individual add-ons).

<?xml version="1.0" encoding="Windows-1252"?>

<SimBase.Document Type="Launch" version="1,0">
<Descr>Launch</Descr>
<Filename>dll.xml</Filename>
<Disabled>False</Disabled>
<Launch.ManualLoad>False</Launch.ManualLoad>


<Launch.Addon>
<Name>First addon</Name>
<Disabled>False</Disabled>

<ManualLoad>False</ManualLoad>
<Path>First Addon.dll</Path>
</Launch.Addon>

 

<Launch.Addon>
<Name>Second addon </Name>
<Disabled>True</Disabled>

<ManualLoad>False</ManualLoad>
<Path>Second Addon.dll</Path>
</Launch.Addon>


</SimBase.Document>

Note

All that including a file in the EXE.xml or DLL.xml file does is ensure that it starts up along with Flight Sim World (as long as Disabled is set to false). It does not ensure that the program is terminated when the user exits from Flight Sim World, this has to be handled from within the client itself. For almost all applications terminating at the same time would be desirable, though for monitoring applications it may well of course be desirable that the client is left running after the simulator exits. It is also possible for the user to click on and start any client application at any time, whether Flight Sim World is running or not. The two xml files are provided for convenience only, it is not a requirement for any client to be added to these files. Note that if Flight Sim World starts an EXE, then Steam will consider the program to be active until both the sim and the addon EXE are terminated.

The SimConnect.xml file

This file contains communication information for the SimConnect server (the SimConnect.cfg file contains information for a client). The default behaviour for the Flight Sim World SDK is that three servers are initiated by the system, for local communcation using one of each of the three protocols: Pipe, IPv4, and IPv6. These servers do not require entries in the xml file. Prior to this SDK, the default behaviour was to open a single server, using the protocol IPv6 in preference to IPv4. The Simconnect.xml file is not needed if this covers the communication requirements. If remote connections are required, then one entry will need to be made in this file to cover each type of remote communication that needs to be supported (see the sample SimConnect.xml file).

The following table describes the file format. The file should be placed in the in the %APPDATA%\Dovetail Games\FSW folder on the computer the server is running on.

XML Values Description
< SimBase.Document Type="SimConnect" version="1,0" > String SimConnect version information.
< Descr > SimConnect< /Descr > String Description of this file.
< Filename > SimConnect.xml< /Filename > String This filename.
< Disabled > False< /Disabled > True, False Set to True to disable SimConnect completely.
     
< SimConnect.Comm >   Communications section. If remote connections are required, then additional SimConnect.Comm sections should be added, one for each protocol or scope that should be supported.
< Disabled > False< /Disabled > True, False Set to True to disable this communication section.
< Protocol >IPv6< /Protocol > Pipe (or Auto),
IPv4,
IPv6
The entry Auto is accepted for backwards compatibility as synonymous with Pipe. The protocol entered here is the only one this particular server will accept.
< Scope > local< /Scope > local,
global,
link-local,
unrestricted
For Pipe or IPv4, one of local or global. For IPv6, one of local, link-local, global, or unrestricted. Link-local is an IPv6 mechanism for accessing computers on a network that does not involve traversing a router. Unrestricted enables Teredo tunneling. Refer to Named-Pipe, IPv4 and IPv6 documentation on MSDN for more details.

< Address > < /Address >

< Port > < /Port >

 

  The server address and port. These should be copied to the identically named fields in the SimConnect.cfg files for the clients.
< MaxClients >< /MaxClients > Integer Define the maximum number of SimConnect clients that can be active at any one time, using this communication section.
< MaxRecvSize >< /MaxRecvSize > Integer The maximum receive packet size, in bytes. The server will disconnect a client that transmits a packet larger than this.
< DisableNagle > True< /DisableNagle > True,
False
Set to True to disable the Nagle packet sending algorithms.
< /SimConnect.Comm >    
< /SimBase.Document >    

Design Considerations

The design of a SimConnect add-on involves writing a client to communicate with a server running within Flight Sim World. The client opens up communications with the server, then requests that certain events and certain object information are passed to it. The client then waits for the information to be received from the server, and then processes it appropriately.

The recommended method of writing an add-on is to build it out-of-process, as an application (an .exe file) rather than in-process, as a library (a .dll file). This is because out-of-process applications provide more stability, if they crash they will typically will not crash Flight Sim World, and are easier to build, test and debug. SimConnect clients are not currently thread-safe.

SimConnect makes extensive use of ID numbers defined by the client. There are ID numbers for requests, data definitions, events, groups, and so on. These ID numbers should be unique for the client. Re-using an ID will result in the previous call using that ID becoming obsolete, and ignored by the server.

It is a good idea to check out control sequences (such as start-up) in the simulator itself, before trying to code those sequences using SimConnect calls. Note that there can be subtle improvements in the modeling of the gauges of an aircraft between versions of the simulation that might change some of the sequences.

Versioning

SimConnect clients will not work with any simulator released previously to Flight Sim World.

Only one version of Flight Sim World can be running on one computer at a time, so a client installed on a local machine will only be communicating with one server. However it is possible to have one client communicate with multiple copies of Flight Sim World, running on a network.

The SimConnect client library used by Flight Sim World will be located in the game's root folder. Only this version will be compatible with the sim, so old versions of the DLL should not be distributed. The syntax of existing functions will not be changed in future versions of SimConnect, although additional functions may be added.

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. This code does not form a complete program in any sense, but simply highlights the uses of the API call. The Reference Samples sections list run-able sample code.


Function Description
General Functions  
DispatchProc

Written by the developer of the SimConnect client, as a callback function to handle all the communications with the server

SimConnect_AddClientEventToNotificationGroup

Used to add an individual client defined event to a notification group.

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 Sim World simulation variable name to a client defined object definition.

SimConnect_CallDispatch

Used to process the next SimConnect message received through the specified callback function.

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_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_Close

Used to request that the communication with the server is ended.

SimConnect_CreateClientData Used to request the creation of a reserved data area for this client.
SimConnect_Draw3DLines Draw simple straight lines at a location in the world.
SimConnect_Draw3DText Draw billboard text at a location in the world.
SimConnect_FlightLoad Used to load an existing flight file.
SimConnect_FlightPlanLoad Used to load an existing flight plan.
SimConnect_FlightSave Used to save the current state of a flight to a flight file.
SimConnect_GetLastSentPacketID

Returns the ID of the last packet sent to the SimConnect server.

SimConnect_GetNextDispatch

Used to process the next SimConnect message received, without the use of a callback function.

SimConnect_MapClientDataNameToID Used to associate an ID with a named client date area.
SimConnect_MapClientEventToSimEvent

Used to associate a client defined event ID with a Flight Sim World event name.

SimConnect_MapInputEventToClientEvent

Used to connect input events (such as keystrokes, joystick or mouse movements) with the sending of appropriate event notifications.

SimConnect_Open

Used to send a request to the Flight Sim World server to open up communications with a new client.

SimConnect_RemoveClientEvent

Used to remove a client defined event from a notification group.

SimConnect_RemoveInputEvent

Used to remove an input event from a specified input group object.

SimConnect_RequestClientData Used to request that the data in an area created by another client be sent to this client.
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_RequestNotificationGroup Used to request events are transmitted from a notification group, when the simulation is in Dialog Mode.
SimConnect_RequestReservedKey

Used to request a specific keyboard TAB-key combination applies only to this client.

SimConnect_RequestSystemState Used to request information from a number of Flight Sim World system components.
SimConnect_SceneryCreateObject Create a single, static scenery object.
SimConnect_SceneryRemoveObject Remove a single static scenery object previously created using SimConnect_SceneryCreateObject.
SimConnect_SceneryMoveObject Reposition a single static scenery object previously created using SimConnect_SceneryCreateObject.
SimConnect_SceneryDetectObject Find the object created using SimConnect_SceneryCreateObject, or the terrain point, at a screen location.
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_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_SetNotificationGroupPriority

Used to set the priority of a notification group.

SimConnect_SetSystemEventState

Used to turn requests for event information from the server on and off.

SimConnect_SetSystemState Used to access a number of Flight Sim World system components.
SimConnect_SubscribeToSystemEvent Used to request that a specific system event is notified to the client.
SimConnect_TransmitClientEvent

Used to request that the Flight Sim World server transmit to all SimConnect clients the specified client event.

SimConnect_UnsubscribeFromSystemEvent Used to request that notifications are no longer received for the specified system event.
Helper Functions  
SimConnect_InsertString

Used to assist in adding variable length strings to a structure.

SimConnect_RequestResponseTimes Used to provide some data on the performance of the client-server connection
SimConnect_RetrieveString

Used to assist in retrieving variable length strings from a structure.

AI Object Specific Functions  
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.

Camera Specific Functions  
SimConnect_CameraSetRelative6DOF Used to adjust the user's aircraft view camera.
SimConnect_CameraGetCurrentView Retrieve details of user's aircraft view camera.
SimConnect_CameraRemove Remove a camera created using SimConnect_CameraSetCurrentView.
SimConnect_CameraSetCurrentView Set the current view according to the supplied details.
Facilities Data Functions  
SimConnect_RequestFacilitiesList Used to request a list of all the facilities of a given type currently held in the facilities cache.
SimConnect_SubscribeToFacilities Used to request notifications when a facility of a certain type is added to the facilities cache.
SimConnect_UnsubscribeToFacilities Used to request that notifications of additions to the facilities cache are not longer sent.
Menu Specific Functions  
SimConnect_MenuAddItem

Used to add a menu item, associated with a client event.

SimConnect_MenuAddSubItem Used to add a sub-menu item, associated with a client event.
SimConnect_MenuDeleteItem

Used to remove a client defined menu item.

SimConnect_MenuDeleteSubItem Used to remove a specified sub-menu item.
SimConnect_Text Used to display a text menu, or scrolling or static text, on the screen.
Mission Specific Functions  
SimConnect_CompleteCustomMissionAction

Used to complete the mission action specified by a GUID.

SimConnect_ExecuteMissionAction

Used to execute the mission action specified by a GUID.

Audio Specific Functions  
SimConnect_VoiceCreate Used to create a voice.
SimConnect_QueueWaveOnVoice Queue a wave via a file.
SimConnect_QueueWaveDataOnVoice Queue a wave via a byte stream.
SimConnect_PlayVoice Start a voice playing.
SimConnect_StopVoice Stop a voice playing.
SimConnect_SetVoiceLooping Enable/disable looping on a voice.
SimConnect_SetVoiceVolume Set volume on a voice (db).
SimConnect_SetVoiceVolumeMin Set the minimum volume for a voice (db).
SimConnect_SetVoiceVolumeMax Set the maximum volume on a voice (db).
SimConnect_SetVoicePitch Set pitch on a voice.
SimConnect_SetVoicePosition Set position on a voice (relative to user or world).
SimConnect_SetVoiceVelocity Set velocity on a voice (relative to user or world).
SimConnect_SetVoiceConeOrientation Set cone orientation on a voice (relative to user or world).
SimConnect_SetVoiceConeAngles Set cone angles on a voice.
SimConnect_SetVoiceConeOuterVol Set cone outer volume on a voice (db).
SimConnect_SetVoiceFlush Stop voice and clear queued data.
SimConnect_VoiceDestroy Used to destroy a voice.
SimConnect_GetVoiceVolume Returns a voice's current volume.
SimConnect_GetVoicePitch Returns a voice's current pitch.
SimConnect_GetVoiceTimeRemaining Returns the time remaining (in seconds) for a voice.


General Functions

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

void CALLBACK DispatchProc(
  SIMCONNECT_RECV*  pData,
  DWORD  cbData,
  void *  pContext
);

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

void CALLBACK MyDispatchProc(SIMCONNECT_RECV* pData, DWORD cbData)
{
  switch(pData->dwID)
  {
    case SIMCONNECT_RECV_ID_OPEN:
      // enter code to handle SimConnect version information received in a SIMCONNECT_RECV_OPEN structure.
      SIMCONNECT_RECV_OPEN *openData = (SIMCONNECT_RECV_OPEN*) pData;
      break;

    case SIMCONNECT_RECV_ID_EVENT:
      // enter code to handle events received in a SIMCONNECT_RECV_EVENT structure.
      SIMCONNECT_RECV_EVENT *evt = (SIMCONNECT_RECV_EVENT*) pData;
      break;

    case SIMCONNECT_RECV_ID_EVENT_FILENAME:
      // enter code to handle event filenames received in a SIMCONNECT_RECV_EVENT_FILENAME
      // structure.
      SIMCONNECT_RECV_EVENT_FILENAME *evt = (SIMCONNECT_RECV_EVENT_FILENAME*) pData;
      break;

    case SIMCONNECT_RECV_ID_EVENT_OBJECT_ADDREMOVE:
      // enter code to handle AI objects that have been added or removed, and received in a SIMCONNECT_RECV_EVENT_OBJECT_ADDREMOVE
      // structure.
      SIMCONNECT_RECV_EVENT_OBJECT_ADDREMOVE *evt = (SIMCONNECT_RECV_EVENT_OBJECT_ADDREMOVE*) pData;
      break;

    case SIMCONNECT_RECV_ID_EVENT_FRAME:
      // enter code to handle frame data received in a SIMCONNECT_RECV_EVENT_FRAME
      // structure.
      SIMCONNECT_RECV_EVENT_FRAME *evt = (SIMCONNECT_RECV_EVENT_FRAME*) pData;
      break;

    case SIMCONNECT_RECV_ID_SIMOBJECT_DATA:
      // enter code to handle object data received in a SIMCONNECT_RECV_SIMOBJECT_DATA structure.
      SIMCONNECT_RECV_SIMOBJECT_DATA *pObjData = (SIMCONNECT_RECV_SIMOBJECT_DATA*) pData;
      break;

    case SIMCONNECT_RECV_ID_SIMOBJECT_DATA_BYTYPE:
      // enter code to handle object data received in a SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE
      // structure.
      SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE *pObjData = (SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE*) pData;
      break;

    case SIMCONNECT_RECV_ID_QUIT:
      // enter code to handle exiting the application
      break;

    case SIMCONNECT_RECV_ID_EXCEPTION:
      // enter code to handle errors received in a SIMCONNECT_RECV_EXCEPTION structure.
      SIMCONNECT_RECV_EXCEPTION *except = (SIMCONNECT_RECV_EXCEPTION*) pData;
      break;

    case SIMCONNECT_RECV_ID_WEATHER_OBSERVATION:
      // enter tode to handle object data received in a
SIMCONNECT_RECV_WEATHER_OBSERVATION structure.
      SIMCONNECT_RECV_WEATHER_OBSERVATION* pWxData = (SIMCONNECT_RECV_WEATHER_OBSERVATION*) pData;
      const char* pszMETAR = (const char*) (pWxData+1);
      break;

    // Enter similar case statements to handle the other types of data that can be received, including:
    // SIMCONNECT_RECV_ID_ASSIGNED_OBJECT_ID,
    // SIMCONNECT_RECV_ID_RESERVED_KEY,
    // SIMCONNECT_RECV_ID_CUSTOM_ACTION
    // SIMCONNECT_RECV_ID_SYSTEM_STATE
    // SIMCONNECT_RECV_ID_CLOUD_STATE

    default:
      // enter code to handle the case where an unexpected message is received
      break;
   }
}

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

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

Syntax

HRESULT SimConnect_AddClientEventToNotificationGroup(
  HANDLE  hSimConnect,
  SIMCONNECT_NOTIFICATION_GROUP_ID  GroupID,
  SIMCONNECT_CLIENT_EVENT_ID  EventID,
  BOOL  bMaskable = FALSE
);

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.
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 Flight Sim World itself (if the priority of the client exceeds that of Flight Sim World). 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

static enum EVENT_ID {
  EVENT_1,
  EVENT_2
  EVENT_3
};
static enum GROUP_ID {
  GROUP_1,
};
hr = SimConnect_AddClientEventToNotificationGroup(hSimConnect, GROUP_1, EVENT_1);
hr = SimConnect_AddClientEventToNotificationGroup(hSimConnect, GROUP_1, EVENT_2);
hr = SimConnect_AddClientEventToNotificationGroup(hSimConnect, GROUP_1, EVENT_3, TRUE);
hr = SimConnect_SetNotificationGroupPriority(hSimConnect, GROUP_1, SIMCONNECT_GROUP_PRIORITY_HIGHEST);

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

HRESULT SimConnect_AddToClientDataDefinition(
  HANDLE  hSimConnect,
  SIMCONNECT_CLIENT_DATA_DEFINITION_ID  DefineID,
  DWORD  dwOffset,
  DWORD  dwSizeOrType,
  float  fEpsilon = 0,
  DWORD  DatumID = SIMCONNECT_UNUSED
);

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.

 

Note that this function has been updated for the SP1a release of the SDK. Clients written for the previous version of this function will still compile and run, this new function simply expands on the functionality provided.

See Also


 

SimConnect_AddToDataDefinition

The SimConnect_AddToDataDefinition function is used to add a Flight Sim World simulation variable name to a client defined object definition.

Syntax

HRESULT SimConnect_AddToDataDefinition(
  HANDLE  hSimConnect,
  SIMCONNECT_DATA_DEFINITION_ID  DefineID,
  const char*  DatumName,
  const char*  UnitsName,
  SIMCONNECT_DATATYPE  DatumType = SIMCONNECT_DATATYPE_FLOAT64,
  float  fEpsilon = 0,
  DWORD  DatumID = SIMCONNECT_UNUSED
);

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 Flight Sim World 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). If querying a Mission System object, pass in the name of a Property e.g. "SimMission.Latched" or "WorldBase.InstanceId".
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

static enum DATA_DEFINE_ID {
  DEFINITION_1,
  DEFINITION_2
};

static enum DATA_REQUEST_ID {
    REQUEST_1,
    REQUEST_2,
};

struct Struct1
{
    double  kohlsmann;
    double  altitude;
    double  latitude;
    double  longitude;
};

// Match string definitions from the Simulation Variables document with the client defined ID

hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_1, "Kohlsman setting hg", "inHg");
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_1, "Indicated Altitude", "feet");
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_1, "Plane Latitude", "degrees");
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_1, "Plane Longitude", "degrees");

hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_2, "GENERAL ENG RPM:1", "rpm");
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_2, "
GENERAL ENG RPM:2", "revolutions per minute");
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_2, "
GENERAL ENG RPM:3", "degrees per second");
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_2, "
GENERAL ENG RPM:4", "minutes per round");

// Sections of code in DispatchProc

// At the right point request the data
// In this example the data is being requested on the user aircraft
....
hr = SimConnect_RequestDataOnSimObject(hSimConnect, REQUEST_1, DEFINITION_1,
SIMCONNECT_OBJECT_ID_USER, SIMCONNECT_PERIOD_ONCE);

....
// When the data is received - cast it to the correct structure type

case SIMCONNECT_RECV_ID_SIMOBJECT_DATA:
{
  SIMCONNECT_RECV_SIMOBJECT_DATA *pObjData = (SIMCONNECT_RECV_SIMOBJECT_DATA*)pData;

  switch(pObjData->dwRequestID)
  {
    case REQUEST_1:

      Struct1 *pS = (Struct1*)&pObjData->dwData;
   
      // Add code to process the structure appropriately

      break;
  }
break;
}
....

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

The SimConnect_CallDispatch function is used to process the next SimConnect message received, through the specified callback function.

Syntax

HRESULT SimConnect_CallDispatch(
  HANDLE  hSimConnect,
  DispatchProc  pfcnDispatch,
  void *  pContext
);

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

int quit = 0;
....
//
while( quit == 0 )
{
  hr = SimConnect_CallDispatch(hSimConnect, MyDispatchProc, NULL);
};

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

 

// Include files are no different than for an EXE

HANDLE hSimConnect = NULL;

void CALLBACK MyDispatchProcDLL(SIMCONNECT_RECV* pData, DWORD cbData, void *pContext)
{
  // Callback code for a DLL is no different than for an EXE
}

//
// The DLLStart function must be present.
//
int __stdcall DLLStart(void)
{
  HRESULT hr;
  if (SUCCEEDED(SimConnect_Open(&hSimConnect, "DLL name", NULL, 0, NULL, 0)))
  {
    printf("\nConnected to Flight Sim World");

    // Place all initialization code for the client in this function

    hr = SimConnect_CallDispatch(hSimConnect, MyDispatchProcDLL, NULL);
  }
  return 0;
}

//
// The DLLStop function must be present.
//
void __stdcall DLLStop(void)
{
  // Close the client
  if (hSimConnect != NULL)
    HRESULT hr = SimConnect_Close(hSimConnect);
}

 

See Also




SimConnect_ClearClientDataDefinition

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

Syntax

HRESULT SimConnect_ClearClientDataDefinition(
  HANDLE  hSimConnect,
  SIMCONNECT_CLIENT_DATA_DEFINITION_ID  DefineID
);

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_ClearDataDefinition

The SimConnect_ClearDataDefinition function is used to remove all simulation variables from a client defined data definition.

Syntax

HRESULT SimConnect_ClearDataDefinition(
  HANDLE  hSimConnect,
  SIMCONNECT_DATA_DEFINITION_ID  DefineID
);

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

static enum DATA_DEFINE_ID {
  DEFINITION_1,
  DEFINITION_2
};
....

// Match string definitions from the Simulation Variables document with the client defined ID

hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_1, "Kohlsman setting hg", "inHg");
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_1, "Indicated Altitude", "feet");
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_1, "Plane Latitude", "degrees");
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_1, "Plane Longitude", "degrees");
....
hr = SimConnect_ClearDataDefinition(hSimConnect, DEFINITION_1);
....

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_ClearInputGroup

The SimConnect_ClearInputGroup function is used to remove all the input events from a specified input group object.

Syntax

HRESULT SimConnect_ClearInputGroup(
  HANDLE  hSimConnect,
  SIMCONNECT_INPUT_GROUP_ID  GroupID
);

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

static enum INPUT_ID {
  INPUT_1,
};
static enum EVENT_ID {
  EVENT_1,
};
hr = SimConnect_MapClientEventToSimEvent(hSimConnect, EVENT_1, "parking_brakes");
hr = SimConnect_MapInputEventToClientEvent(hSimConnect, INPUT_1, "a+B", EVENT_1);
....
hr = SimConnect_ClearInputGroup(hSimConnect, INPUT_1);

Remarks

Use this function to permanently delete an input group. Use the SimConnect_SetInputGroupState function to temporarily suspend input group notifications.

See Also



SimConnect_ClearNotificationGroup

The SimConnect_ClearNotificationGroup function is used to remove all the client defined events from a notification group.

Syntax

HRESULT SimConnect_ClearNotificationGroup(
  HANDLE  hSimConnect,
  SIMCONNECT_NOTIFICATION_GROUP_ID  GroupID
);

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

static enum EVENT_ID {
  EVENT_1,
  EVENT_2
  EVENT_3
};
static enum GROUP_ID {
  GROUP_1,
};
hr = SimConnect_AddClientEventToNotificationGroup(hSimConnect, GROUP_1, EVENT_1);
hr = SimConnect_AddClientEventToNotificationGroup(hSimConnect, GROUP_1, EVENT_2);
hr = SimConnect_AddClientEventToNotificationGroup(hSimConnect, GROUP_1, EVENT_3, TRUE);

hr = SimConnect_ClearNotificationGroup(hSimConnect, GROUP_1);

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_Close

The SimConnect_Close function is used to request that the communication with the server is ended.

Syntax

HRESULT SimConnect_Close(
  HANDLE  hSimConnect
);

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. This should only happen if a the hSimConnect parameter is erroneous.

Example

hr = SimConnect_Close(hSimConnect);

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

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

Syntax

HRESULT SimConnect_CreateClientData(
  HANDLE  hSimConnect,
  SIMCONNECT_CLIENT_DATA_ID  ClientDataID,
  DWORD  dwSize,
  SIMCONNECT_CREATE_CLIENT_DATA_FLAG  Flags
);

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 Flight Sim World this was 4K, for the SP1A update to the SDK it is 8K. If an add-on is to work with the RTM version, a 4K limit should be adhered to. There is no maximum number of client data areas, but the total must not exceed 1Mbyte for the SP1A update, or 100K 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 Flight Sim World 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_Draw3DLines

The SimConnect_Draw3DLines function is used to put simple wireframe shapes into the world.

Syntax

HRESULT SimConnect_Draw3DLines(
  HANDLE  hSimConnect,
  SIMCONNECT_DATA_DEFINITION_ID  DefineID,
  SIMCONNECT_DATA_LATLONALT  LinePosition,
  bool  bAltIsAGL
  DWORD  ArrayCount
  DWORD  cbUnitSize
  void *  pDataSet
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
DefineID
  [in]  Specifies the ID of this line set.
LinePosition
  [in]  Position in the world for this line set to appear at.
bAltIsAGL
  [in]  Specify whether the altitude given in LinePosition is AGL or AMSL.
ArrayCount
  [in]  The number of points in the array being sent.
cbUnitSize
  [in]  The size of each point. Used for version checking.
pDataSet
  [in]  A pointer to an array of SIMCONNECT_VERTEX3D structures.

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 draws simple, unlit, line vectors in 3D space. It is intended to show things like boundary boxes and does not support animation or solid vector objects.

Each point is defined as an offset in meters from the shape's location. Lines are drawn between each point in the array and the next, except where a point is defined as being the last in a segment, and each line can have it's own colour.

There is a limit of 1000 points in the vertex array.

A line set can be replaced by sending a second request with the same DefineID, and removed by sending an empty list with the original DefineID.

See Also




SimConnect_Draw3DText

The SimConnect_Draw3DText function is used to put simple billboard text similar to aircraft labels into the world.

Syntax

HRESULT SimConnect_Draw3DText(
  HANDLE  hSimConnect,
  SIMCONNECT_DATA_DEFINITION_ID  DefineID,
  SIMCONNECT_DATA_LATLONALT  TextPosition,
  DWORD  dwColorARGB
  const char *  szText
  bool  bAltIsAGL
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
DefineID
  [in]  Specifies the ID of this text.
TextPosition
  [in]  Position in the world for this text to appear at.
szText
  [in]  The text to show.
dwColorARGB
  [in]  The colour of the text.
bAltIsAGL
  [in]  Specify whether the altitude given in TextPosition is AGL or AMSL.

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 draws simple, unlit, small text in the world which will always face the screen. It is intended for use in labelling items of interest.

Text can be replaced by sending a second request with the same DefineID, and removed by sending an empty string with the original DefineID.

See Also




SimConnect_FlightLoad

The SimConnect_FlightLoad function is used to load an existing flight file.

Syntax

HRESULT SimConnect_FlightLoad(
  HANDLE  hSimConnect,
  const char*  szFileName
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
szFileName
  [in]  Null-terminated string containing the path to the flight file. The path can either be absolute, or relative to the My Documents\Flight Sim World folder. Flight files have the extension .FLT, but no need to enter an extension here.

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

Flight files can be opened using a text editor.

See Also




SimConnect_FlightPlanLoad

The SimConnect_FlightPlanLoad function is used to load an existing flight plan file.

Syntax

HRESULT SimConnect_FlightPlanLoad(
  HANDLE  hSimConnect,
  const char*  szFileName
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
szFileName
  [in]  Null-terminated string containing the path to the flight plan file. Flight plans have the extension .PLN, but no need to enter an extension here. There is no need to enter the full path to the file (just enter the filename) if the flight file is in the default Flight Sim World Files directory. The easiest way to create flight plans is to create them from within Flight Sim World itself, and then save them off for use by the user or AI controlled aircraft.

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

Flight plan files can be opened using a text editor.

See Also




SimConnect_FlightSave

The SimConnect_FlightSave function is used to save the current state of a flight to a flight file.

Syntax

HRESULT SimConnect_FlightSave(
  HANDLE  hSimConnect,
  const char*  szFileName,
  const char*  szTitle,
  const char*  szDescription,
  DWORD  Flags
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
szFileName
  [in]  Null-terminated string containing the path to the flight file. The path can either be absolute, or relative to the My Documents\Flight Sim World folder. Flight files have the extension .FLT, but no need to enter an extension here.

szTitle
  [in]  Null-terminated string containing the title of the flight file. If this is NULL then the szFileName parameter is used as the title.szDescription
  [in]  Null-terminated string containing the text to enter in the Description field of the flight file.

Flags
  [in]  Unused.

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

Flight files can be opened using a text editor.

See Also



SimConnect_GetLastSentPacketID

The SimConnect_GetLastSentPacketID function returns the ID of the last packet sent to the SimConnect server.

Syntax

HRESULT SimConnect_GetLastSentPacketID(
  HANDLE  hSimConnect,
  DWORD*  pdwSendID
);

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

DWORD dwLastID;

hr = SimConnect_MapClientEventToSimEvent(hSimConnect, EVENT_MY_EVENT, "Custom.Event");
hr = SimConnect_TransmitClientEvent(hSimConnect, 0, EVENT_MY_EVENT, 0, SIMCONNECT_GROUP_PRIORITY_HIGHEST, 0);
// Get the Send ID of the last transmission to the server
hr = SimConnect_GetLastSentPacketID(hSimConnect, &dwLastID);

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

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

Syntax

HRESULT SimConnect_GetNextDispatch(
  HANDLE  hSimConnect,
  SIMCONNECT_RECV**  ppData,
  DWORD*  pcbData
);

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

SIMCONNECT_RECV* pData;
DWORD cbData;

hr = SimConnect_GetNextDispatch(hSimConnect, &pData, &cbData);
if (SUCCEEDED(hr))
{
  switch(pData->dwID)
  {
    case SIMCONNECT_RECV_ID_OPEN:
      // enter code to handle SimConnect version information received in a SIMCONNECT_RECV_OPEN structure.
      SIMCONNECT_RECV_OPEN *openData = (SIMCONNECT_RECV_OPEN*) pData;
      break;

    case SIMCONNECT_RECV_ID_EVENT:
      // enter code to handle events received in a SIMCONNECT_RECV_EVENT structure.
      SIMCONNECT_RECV_EVENT *evt = (SIMCONNECT_RECV_EVENT*) pData;
      break;

    case SIMCONNECT_RECV_ID_EVENT_FILENAME:
      // enter code to handle event filenames received in a SIMCONNECT_RECV_EVENT_FILENAME
      // structure.
      SIMCONNECT_RECV_EVENT_FILENAME *evt = (SIMCONNECT_RECV_EVENT_FILENAME*) pData;
      break;

    case SIMCONNECT_RECV_ID_EVENT_OBJECT_ADDREMOVE:
      // enter code to handle AI objects that have been added or removed, and received in a SIMCONNECT_RECV_EVENT_OBJECT_ADDREMOVE
      // structure.
      SIMCONNECT_RECV_EVENT_OBJECT_ADDREMOVE *evt = (SIMCONNECT_RECV_EVENT_OBJECT_ADDREMOVE*) pData;
      break;

    case SIMCONNECT_RECV_ID_EVENT_FRAME:
      // enter code to handle frame data received in a SIMCONNECT_RECV_EVENT_FRAME
      // structure.
      SIMCONNECT_RECV_EVENT_FRAME *evt = (SIMCONNECT_RECV_EVENT_FRAME*) pData;
      break;

    case SIMCONNECT_RECV_ID_SIMOBJECT_DATA:
      // enter code to handle object data received in a SIMCONNECT_RECV_SIMOBJECT_DATA structure.
      SIMCONNECT_RECV_SIMOBJECT_DATA *pObjData = (SIMCONNECT_RECV_SIMOBJECT_DATA*) pData;
      break;

    case SIMCONNECT_RECV_ID_SIMOBJECT_DATA_BYTYPE:
      // enter code to handle object data received in a SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE
      // structure.
      SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE *pObjData = (SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE*) pData;
      break;

    case SIMCONNECT_RECV_ID_QUIT:
      // enter code to handle exiting the application
      break;

    case SIMCONNECT_RECV_ID_EXCEPTION:
      // enter code to handle errors received in a SIMCONNECT_RECV_EXCEPTION structure.
      SIMCONNECT_RECV_EXCEPTION *except = (SIMCONNECT_RECV_EXCEPTION*) pData;
      break;

    case SIMCONNECT_RECV_ID_WEATHER_OBSERVATION:
      // enter tode to handle object data received in a
SIMCONNECT_RECV_WEATHER_OBSERVATION structure.
      SIMCONNECT_RECV_WEATHER_OBSERVATION* pWxData = (SIMCONNECT_RECV_WEATHER_OBSERVATION*) pData;
      const char* pszMETAR = (const char*) (pWxData+1);
      break;

    // Enter similar case statements to handle the other types of data that can be received, including:
    // SIMCONNECT_RECV_ID_ASSIGNED_OBJECT_ID,
    // SIMCONNECT_RECV_ID_RESERVED_KEY,
    // SIMCONNECT_RECV_ID_CUSTOM_ACTION
    // SIMCONNECT_RECV_ID_SYSTEM_STATE
    // SIMCONNECT_RECV_ID_CLOUD_STATE

    default:
      // enter code to handle the case where an unexpected message is received
      break;
   }
}

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

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

Syntax

HRESULT SimConnect_MapClientDataNameToID(
  HANDLE  hSimConnect,
  const char*  szClientDataName,
  SIMCONNECT_CLIENT_DATA_ID  ClientDataID
);

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 addon, 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_MapClientEventToSimEvent

The SimConnect_MapClientEventToSimEvent function associates a client defined event ID with a Flight Sim World event name.

Syntax

HRESULT SimConnect_MapClientEventToSimEvent(
  HANDLE  hSimConnect,
  SIMCONNECT_CLIENT_EVENT_ID  EventID,
  const char*  EventName
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
EventID
  [in]  Specifies the ID of the client event.
EventName
  [in]  Specifies the Flight Sim World 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 Flight Sim World) that has been coded to receive such events. No Flight Sim World 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 Flight Sim World.

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

static enum EVENT_ID {
  EVENT_PAUSE,
  EVENT_BRAKES,
  EVENT_CUSTOM,
  EVENT_PRIVATE,
};

// Attach the client event EVENT_BRAKES to the simulation event "brakes"
hr = SimConnect_MapClientEventToSimEvent(hSimConnect, EVENT_BRAKES, "brakes");

// Attach the client event EVENT_PAUSE to the simulation event "pause_toggle"
hr = SimConnect_MapClientEventToSimEvent(hSimConnect, EVENT_PAUSE, "pause_toggle");

// Create a custom event, for use when communicating with other clients
hr = SimConnect_MapClientEventToSimEvent(hSimConnect, EVENT_CUSTOM, "Custom.Event");

// Create a private event for use within this client only
hr = SimConnect_MapClientEventToSimEvent(hSimConnect, EVENT_PRIVATE);

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

HRESULT SimConnect_MapInputEventToClientEvent(
  HANDLE  hSimConnect,
  SIMCONNECT_INPUT_GROUP_ID  GroupID,
  const char*  pszInputDefinition,
  SIMCONNECT_CLIENT_EVENT_ID  DownEventID,
  DWORD  DownValue = 0,
  SIMCONNECT_CLIENT_EVENT_ID  UpEventID =(SIMCONNECT_CLIENT_EVENT_ID)SIMCONNECT_UNUSED,
  DWORD  UpValue = 0,
  BOOL  bMaskable = FALSE
);

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.
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.

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


static enum INPUT_ID {
      INPUT_1,
};

static enum EVENT_ID {
     EVENT_1,
     EVENT_2,
     EVENT_3  
};

hr = SimConnect_MapClientEventToSimEvent(hSimConnect, EVENT_1, "parking_brakes");

// Set similar mappings for EVENT_2 and EVENT_3

//
Lower case a and upper case B are hit together
hr = SimConnect_MapInputEventToClientEvent(hSimConnect, INPUT_1, "a+B", EVENT_1);

// Ctrl, upper case A and upper case U are hit together
hr = SimConnect_MapInputEventToClientEvent(hSimConnect, INPUT_1, "Ctrl+A+U", EVENT_1);

// Ctrl, shift, lower case a, has been hit
hr = SimConnect_MapInputEventToClientEvent(hSimConnect, INPUT_1, "shift+ctrl+a", EVENT_2);

// Ctrl, shift, lower case a, will trigger an EVENT_2 when it is pressed, and an EVENT_3 when released
hr = SimConnect_MapInputEventToClientEvent(hSimConnect, INPUT_1, "shift+ctrl+a", EVENT_2, 0, EVENT_3);

// The first configured button of joystick 0 is hit
hr = SimConnect_MapInputEventToClientEvent(hSimConnect, INPUT_1, "joystick:0:button:0", EVENT_2);

// The second configured button of joystick 0 is hit
hr = SimConnect_MapInputEventToClientEvent(hSimConnect, INPUT_1, "joystick:0:button:1", EVENT_3);

// The first configured joystick has had its first configured point of view (or hat) switch pressed
hr = SimConnect_MapInputEventToClientEvent(hSimConnect, INPUT_1, "joystick:0:POV:0", EVENT_3);

// The first configured joystick has been moved along the x axis
hr = SimConnect_MapInputEventToClientEvent(hSimConnect, INPUT_1, "joystick:0:XAxis", EVENT_3);


hr = SimConnect_SetInputGroupPriority(hSimConnect, INPUT_1, SIMCONNECT_GROUP_PRIORITY_HIGHEST);

Reference 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).

 

Note that if you request "mouse" inputs using this function, this is taken as requesting mouse-yoke input, not general mouse movements or inputs. To receive pure mouse input regardless of mouse-yoke mode, use a pszInputDefinition of "rawmouse". Mouse button and movement data will be returned using the event DownEventID, in a SIMCONNECT_RECV_EVENT_RAWMOUSE structure. Keyboard control, shift and alt key states are also returned. Rawmouse events are evaluate per-frame.

 

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 input name can be one in the following table:

 

Input Name Description Range of values
Button One of the joystick buttons, configured from 0. Not applicable
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 flight 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 Flight Sim World folder. The first time Flight Sim World is run, a subset of this file is written out to a file with the same name in the %APPDATA%/Dovetail Games/FSW/Controls folder, containing just the mappings that the current setup is using. Each time Flight Sim World 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 Flight Sim World is running, as in this case the file will be over-written. Standard.xml replaces the file devices.cfg used in earlier versions of Flight Sim World.

 

See Also



SimConnect_Open

The SimConnect_Open function is used to send a request to the Flight Sim World server to open up communications with a new client.

Syntax

HRESULT SimConnect_Open(
  HANDLE*  phSimConnect,
  LPCSTR  szName,
  HWND  hWnd,
  DWORD  UserEventWin32,
  HANDLE  hEventHandle,
  DWORD  ConfigIndex
);

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.
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 Flight Sim World.
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 Flight Sim World. 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 addon 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

HRESULT hr;
HANDLE hSimConnect = NULL;

hr = SimConnect_Open(&hSimConnect, "Your Application Name", NULL, 0, 0, SIMCONNECT_OPEN_CONFIGINDEX_LOCAL);

Reference 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 Flight Sim World that support it, are available.

 

If a remote client successfully establishes a link with Flight Sim World, 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.

See Also



SimConnect_RemoveClientEvent

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

Syntax

HRESULT SimConnect_RemoveClientEvent(
  HANDLE  hSimConnect,
  SIMCONNECT_NOTIFICATION_GROUP_ID  GroupID,
  SIMCONNECT_CLIENT_EVENT_ID  EventID
);

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

static enum EVENT_ID {
  EVENT_1,
  EVENT_2
  EVENT_3
};
static enum GROUP_ID {
  GROUP_1,
};
hr = SimConnect_AddClientEventToNotificationGroup(hSimConnect, GROUP_1, EVENT_1);
hr = SimConnect_AddClientEventToNotificationGroup(hSimConnect, GROUP_1, EVENT_2);
hr = SimConnect_AddClientEventToNotificationGroup(hSimConnect, GROUP_1, EVENT_3, TRUE);

hr = SimConnect_RemoveClientEvent(hSimConnect, GROUP_1, EVENT_2);

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_RemoveInputEvent

The SimConnect_RemoveInputEvent function is used to remove an input event from a specified input group object.

Syntax

HRESULT SimConnect_RemoveInputEvent(
  HANDLE  hSimConnect,
  SIMCONNECT_INPUT_GROUP_ID  GroupID,
  const char*  pszInputDefinition
);

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

static enum INPUT_ID {
  INPUT_1,
};
static enum EVENT_ID {
  EVENT_1,
};
hr = SimConnect_MapClientEventToSimEvent(hSimConnect, EVENT_1, "parking_brakes");
hr = SimConnect_MapInputEventToClientEvent(hSimConnect, INPUT_1, "a+B", EVENT_1);
....
hr = SimConnect_RemoveInputEvent(hSimConnect, INPUT_1, "a+B");

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_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

HRESULT SimConnect_RequestClientData(
  HANDLE  hSimConnect,
  SIMCONNECT_CLIENT_DATA_ID  ClientDataID,
  SIMCONNECT_DATA_REQUEST_ID  RequestID,
  SIMCONNECT_CLIENT_DATA_DEFINITION_ID  DefineID,
  SIMCONNECT_CLIENT_DATA_PERIOD  Period = SIMCONNECT_CLIENT_DATA_PERIOD_ONCE,
  SIMCONNECT_CLIENT_DATA_REQUEST_FLAG  Flags = 0,
  DWORD  origin = 0,
  DWORD  interval = 0,
  DWORD  limit = 0
);

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_RequestDataOnSimObject

The SimConnect_RequestDataOnSimObject function is used to request when the SimConnect client is to receive data values for a specific object.

Syntax

HRESULT SimConnect_RequestDataOnSimObject(
  HANDLE  hSimConnect,
  SIMCONNECT_DATA_REQUEST_ID  RequestID,
  SIMCONNECT_DATA_DEFINITION_ID  DefineID,
  SIMCONNECT_OBJECT_ID  ObjectID,
  SIMCONNECT_PERIOD  Period,
  SIMCONNECT_DATA_REQUEST_FLAG  Flags = 0,
  DWORD  origin = 0,
  DWORD  interval = 0,
  DWORD  limit = 0
);

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 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.
ObjectID
  [in]  Specifies the ID of the Flight Sim World object that the data should be about. This ID can be SIMCONNECT_OBJECT_ID_USER (to specify the user's aircraft) or obtained from a SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE structure after a call to SimConnect_RequestDataOnSimObjectType. Also refer to the note on developing clients for multiplayer mode in the Remarks section below.
Period
  [in]  One member of the SIMCONNECT_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_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_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_SIMOBJECT_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.

Example

static enum DATA_DEFINE_ID {
  DEFINITION_1,
  DEFINITION_2
};

static enum DATA_REQUEST_ID {
    REQUEST_1,
    REQUEST_2,
};

struct Struct1
{
    double  kohlsmann;
    double  altitude;
    double  latitude;
    double  longitude;
};

 

// Match string definitions from the Simulation Variables document with the client defined ID

hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_1, "Kohlsman setting hg", "inHg");
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_1, "Indicated Altitude", "feet");
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_1, "Plane Latitude", "degrees");
hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION_1, "Plane Longitude", "degrees");

// Sections of code in DispatchProc

....
SimConnect_RequestDataOnSimObject(hSimConnect, REQUEST_2, DEFINITION_1, SIMCONNECT_OBJECT_ID_USER, SIMCONNECT_PERIOD_SECOND);
....
// When the data is received - cast it to the correct structure type

case SIMCONNECT_RECV_ID_SIMOBJECT_DATA:
{
  SIMCONNECT_RECV_SIMOBJECT_DATA *pObjData = (SIMCONNECT_RECV_SIMOBJECT_DATA*) pData;

  switch(pObjData->dwRequestID)
  {
    case REQUEST_2:

      Struct1 *pS = (Struct1*)&pObjData->dwData;
   
      // Add code to process the structure appropriately

      break;
  }
break;
}
....

Reference Samples

 

Primary samples

Tagged Data

Reference samples Weather Station

 

Remarks

Changing the Period parameter or changing the content of a data definition has a higher performance cost than changing the origin, interval or limit parameters. So to temporarily turn off data requests, especially for short periods of time, consider setting the interval parameter to a very high value (such as DWORD _MAX). If changes are required to a data definition, consider setting the Period parameter to SIMCONNECT_PERIOD_NEVER (see the SIMCONNECT_PERIOD enumeration) before making the changes, and then turning on the appropriate period after the changes have been made.

 

It is possible to change the period of a request, by resending the SimConnect_RequestDataOnSimObject call with the same RequestID, DefineID and ObjectID parameters, but with a new period. The one exception to this is the new period cannot be SIMCONNECT_PERIOD_ONCE, in this case a request with a new RequestID should be sent.

 

Data is always transmitted with the SimConnect_RequestDataOnSimObject function, so if timing only notifications are required, use the SimConnect_SubscribeToSystemEvent function.

 

Note that variable length strings should not be used in data definitions, except where the Period parameter has been set to SIMCONNECT_PERIOD_ONCE.

 

One method of testing whether the user has changed aircraft type is to use this function to return the title of the user aircraft, and note that if it changes, the user has changed the type of aircraft (all aircraft types have unique title strings, including those simply with different color schemes). An example of requesting the aircraft title is in the Variable Strings reference sample. See the Aircraft Configuration Files document for more details on titles.

 

If boolean data has been requested as part of a data definition, note that the only reliable numeric equivalent is that 0 is returned for False. Non-zero values, especially both 1 and -1, are used to indiate True.

 

Note: Multiplayer Mode

When developing a client for use in multiplayer mode it is not safe to use the ID number for the user aircraft returned by the function SimConnect_RequestDataOnSimObjectType, as the actual number can change depending on several factors, including the number of users involved in the multiplayer flight. Always use the constant SIMCONNECT_OBJECT_ID_USER for the ObjectID parameter if the SimConnect client is to work in multiplayer mode. Also note that in this mode it is good practice to remove any calls associated with periodic data on AI objects and to remove subscriptions to AI objects.

See Also




SimConnect_RequestDataOnSimObjectType

The SimConnect_RequestDataOnSimObjectType function is used to retrieve information about simulation objects of a given type that are within a specified radius of the user's aircraft, or for Mission System objects.

Syntax

HRESULT SimConnect_RequestDataOnSimObjectType(
  HANDLE  hSimConnect,
  SIMCONNECT_DATA_REQUEST_ID  RequestID,
  SIMCONNECT_DATA_DEFINITION_ID  DefineID,
  DWORD  dwRadiusMeters,
  SIMCONNECT_SIMOBJECT_TYPE  type
);

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 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.
dwRadiusMeters
  [in]  Double word containing the radius in meters. If this is set to zero only information on the user aircraft will be returned, although this value is ignored if type is set to SIMCONNECT_SIMOBJECT_TYPE_USER. The error SIMCONNECT_EXCEPTION_OUT_OF_BOUNDS will be returned if a radius is given and it exceeds the maximum allowed (200000 meters, or 200 Km).
type
  [in]  Specifies the type of object to receive information on. One member of the SIMCONNECT_SIMOBJECT_TYPE 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

See SimConnect_AddToDataDefinition for an example of when to use this function


Reference Samples

 

Primary samples

Request Data

Variable Strings

Mission Data

Reference samples

 

 

Remarks

The data will be returned on all the relevant objects within the specified radius, but they will not be returned in any specific order. It is the responsibility of the client program to sort the returned data into order, if that is required. Information is returned in a SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE structure, one structure per object.

 

Also refer to the note on multiplayer mode in the remarks for SimConnect_RequestDataOnSimObject.

 

If requesting data for SIMCONNECT_SIMOBJECT_TYPE_ALL_CRAFT, no Mission System data will be returned. To get a list of all mission objects, explicitly pass a value of SIMCONNECT_SIMOBJECT_TYPE_MISSION.

See Also



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

HRESULT SimConnect_RequestNotificationGroup(
  HANDLE  hSimConnect,
  SIMCONNECT_NOTIFICATION_GROUP_ID  GroupID,
  DWORD  dwReserved = 0,
  DWORD  Flags = 0
);

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_RequestReservedKey

The SimConnect_RequestReservedKey function is used to request a specific keyboard TAB-key combination applies only to this client.

Syntax

HRESULT SimConnect_RequestReservedKey(
  HANDLE  hSimConnect,
  SIMCONNECT_CLIENT_EVENT_ID  EventID,
  const char*  szKeyChoice1,
  const char*  szKeyChoice2 = "",
  const char*  szKeyChoice3 = ""
);

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.

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

The SimConnect_RequestSystemState function is used to request information from a number of Flight Sim World system components.

Syntax

HRESULT SimConnect_RequestSystemState(
  HANDLE  hSimConnect,
  SIMCONNECT_DATA_REQUEST_ID  RequestID,
  const char*  szState,
);


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
AircraftConfigLoaded Requests the full path name of the last loaded aircraft config file. These files have a .CFG extension.
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 flight. Flight files have the extension .FLT.
FlightPlan Requests the full path name of the active flight plan. An empty string will be returned if there is no active flight plan.
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_SceneryCreateObject

The SimConnect_SceneryCreateObject function is used to create a single, static scenery object from appropriate XML.

Syntax

HRESULT SimConnect_SceneryCreateObject(
  HANDLE  hSimConnect,
  SIMCONNECT_DATA_REQUEST_ID  RequestID,
  SIMCONNECT_OBJECT_ID  ObjectID,
  const char*  szSimPropXml,
);


Parameters

hSimConnect
  Handle to a SimConnect object.
RequestID
  The client defined request ID.
ObjectID
  The client defined object ID.
szState
  A null-terminated string describing the object. This is the same format as would be created by the Object Placement Tool:

 

<SceneryObjects.LibraryObject>
    <WorldPosition>N48* 30.15',W123* 0.66',+000000.00</WorldPosition>
    <AltitudeIsAGL>True</AltitudeIsAGL>
    <Orientation>0.000, 0.000, 0.000</Orientation>
    <Scale>1.000</Scale>
    <ImageComplexity>Very Sparse</ImageComplexity>
    <MDLGuid>{3EBEDF9F-F072-11D2-9C84-00105A0CE62A}</MDLGuid>
</SceneryObjects.LibraryObject>

 

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.

Reference Samples

 

Primary samples

Scenery

 

Remarks

The information requested will be returned in a SIMCONNECT_RECV_ASSIGNED_OBJECT_ID structure.

See Also



SimConnect_SceneryRemoveObject

The SimConnect_SceneryRemoveObject function is used to remove a previously-created static scenery object.

Syntax

HRESULT SimConnect_SceneryRemoveObject(
  HANDLE  hSimConnect,
  SIMCONNECT_OBJECT_ID  ObjectID
);


Parameters

hSimConnect
  Handle to a SimConnect object.
ObjectID
  The object ID passed to the SimConnect_SceneryCreateObject call.

 

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.

Reference Samples

 

Primary samples

Scenery

 

Remarks

Scenery objects are not removed when a flight ends, they should be explicitly removed by the client when it closes.

See Also



SimConnect_SceneryMoveObject

The SimConnect_SceneryMoveObject function is used to reposition a previously-created static scenery object.

Syntax

HRESULT SimConnect_SceneryMoveObject(
  HANDLE  hSimConnect,
  SIMCONNECT_OBJECT_ID  ObjectID,
  SIMCONNECT_DATA_INITPOSITION  NewPosition
);


Parameters

hSimConnect
  Handle to a SimConnect object.
ObjectID
  The object ID returned in the response to the SimConnect_SceneryCreateObject call.
NewPosition
  The new position of the object. The OnGround and Airspeed fields are ignored.

 

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.

Reference Samples

 

Primary samples

Scenery

 

Remarks

In general, use an AI object for moving scenery items. This call is intended for infrequent repositioning of static scenery elements.

See Also



SimConnect_SceneryDetectObject

The SimConnect_SceneryDetectObject function is used to find a previously-created static scenery object, or the terrain latitude/longitude, at the pixel position given.

Syntax

HRESULT SimConnect_SceneryDetectObject(
  HANDLE  hSimConnect,
  SIMCONNECT_DATA_REQUEST_ID  RequestID,
  int  OffsetX,
  int  OffsetY,
  bool  TerrainOnly
);


Parameters

hSimConnect
  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 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.
OffsetX
  The horizontal pixel location to test for created scenery objects or terrain.
OffsetY
  The vertical pixel location to test for created scenery objects or terrain.
TerrainOnly
  Set to true to return only terrain locations, ignoring created objects.

 

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.

Reference Samples

 

Primary samples

FSWChanges

 

Remarks

Passing in coordinates of -1, -1 will be taken as meaning the center of the simulator window.

The function returns a SIMCONNECT_RECV_OBJECT_AT_POINT structure.

See Also




SimConnect_SetClientData

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

Syntax

HRESULT SimConnect_SetClientData(
  HANDLE  hSimConnect,
  SIMCONNECT_CLIENT_DATA_ID  ClientDataID,
  SIMCONNECT_CLIENT_DATA_DEFINITION_ID  DefineID,
  DWORD  Flags,
  DWORD  dwReserved,
  DWORD  cbUnitSize,
  void*  pDataSet
);

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_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_SetDataOnSimObject

The SimConnect_SetDataOnSimObject function is used to make changes to the data properties of an object.

Syntax

HRESULT SimConnect_SetDataOnSimObject(
  HANDLE  hSimConnect,
  SIMCONNECT_DATA_DEFINITION_ID  DefineID,
  SIMCONNECT_OBJECT_ID  ObjectID,
  SIMCONNECT_DATA_SET_FLAG  Flags,
  DWORD  ArrayCount,
  DWORD  cbUnitSize,
  void*  pDataSet
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
DefineID
  [in]  Specifies the ID of the client defined data definition.
ObjectID
  [in]  Specifies the ID of the Flight Sim World object that the data should be about. This ID can be SIMCONNECT_OBJECT_ID_USER (to specify the user's aircraft) or obtained from a SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE structure after a call to SimConnect_RequestDataOnSimObjectType. Also refer to the note on multiplayer mode in the remarks for SimConnect_RequestDataOnSimObject.
Flags
  [in]  Null, or one or more of the following flags.

Flag Description
SIMCONNECT_DATA_SET_FLAG_TAGGED The data to be set is being sent in tagged format. Refer to SimConnect_RequestDataOnSimObject for more details on the tagged format.


ArrayCount
  [in]  Specifies the number of elements in the data array. A count of zero is interpreted as one element. Ensure that the data array has been initialized completely before transmitting it to Flight Sim World. Failure to properly initialize all array elements may result in unexpected behavior.
cbUnitSize
  [in]  Specifies the size of each element in the data array in bytes.

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 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.

Example

static enum DATA_DEFINE_ID {
  DEFINITION3
};
  
// Link DEFINITION3 with the SIMCONNECT_DATA_INITPOSITION structure

hr = SimConnect_AddToDataDefinition(hSimConnect, DEFINITION3, "Initial Position", "NULL",
         SIMCONNECT_DATATYPE_INITPOSITION, 0);

SIMCONNECT_DATA_INITPOSITION Init;
   Init.Altitude = 5000.0;
   Init.Latitude = 47.64210;
   Init.Longitude = -122.13010;
   Init.Pitch = -0.0;
   Init.Bank = -1.0;
   Init.Heading = 180.0;
   Init.OnGround = 0;
   Init.Airspeed = 0;
SimConnect_SetDataOnSimObject(hSimConnect, DEFINITION3, SIMCONNECT_OBJECT_ID_USER, 0, sizeof(Init), &Init);

Reference Samples

 

Primary samples

Set Data

Throttle Control

 

Reference samples AI Objects and Waypoints
Managed AI Waypoints

Remarks

The data that is set on an object is defined in a data definition (see the SimConnect_AddToDataDefinition function). This data can include the following structures: SIMCONNECT_DATA_WAYPOINT, SIMCONNECT_DATA_INITPOSITION, and SIMCONNECT_DATA_MARKERSTATE. Any number of waypoints can be given to an AI object using a single call to this function, and any number of marker state structures can also be combined into an array.

 

The Simulation Variables document includes a column indicating whether variables can be written to or not. An exception will be returned if an attempt is made to write to a variable that cannot be set in this way.

See Also



SimConnect_SetInputGroupPriority

The SimConnect_SetInputGroupPriority function is used to set the priority for a specified input group object.

Syntax

HRESULT SimConnect_SetInputGroupPriority(
  HANDLE  hSimConnect,
  SIMCONNECT_INPUT_GROUP_ID  GroupID,
  DWORD  uPriority
);

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

hr=SimConnect_SetInputGroupPriority(hSimConnect,INPUT0,SIMCONNECT_GROUP_PRIORITY_HIGHEST);

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

The SimConnect_SetInputGroupState function is used to turn requests for input event information from the server on and off.

Syntax

HRESULT SimConnect_SetInputGroupState(
  HANDLE  hSimConnect,
  SIMCONNECT_INPUT_GROUP_ID  GroupID,
  DWORD  dwState
);

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

static enum INPUT_ID {
  INPUT_1,
  INPUT_2
};
static enum EVENT_ID {
  EVENT_1,
  EVENT_2
};
....
hr = SimConnect_MapClientEventToSimEvent(hSimConnect, EVENT_1, "parking_brakes");
hr = SimConnect_MapInputEventToClientEvent(hSimConnect, INPUT_1, "ctrl+U+Q", EVENT_1);
hr = SimConnect_SetInputGroupState(hSimConnect, INPUT_1, SIMCONNECT_STATE_ON);

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

The SimConnect_SetNotificationGroupPriority function is used to set the priority for a notification group.

Syntax

HRESULT SimConnect_SetNotificationGroupPriority(
  HANDLE  hSimConnect,
  SIMCONNECT_NOTIFICATION_GROUP_ID  GroupID,
  DWORD  uPriority
);

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

hr=SimConnect_SetNotificationGroupPriority(hSimConnect,GROUP0,SIMCONNECT_GROUP_PRIORITY_HIGHEST);

Reference 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 Flight Sim World 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. Flight Sim World'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 Flight Sim World 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. Flight Sim World does not mask any events.

See Also



SimConnect_SetSystemEventState

The SimConnect_SetSystemEventState function is used to turn requests for event information from the server on and off.

Syntax

HRESULT SimConnect_SetSystemEventState(
  HANDLE  hSimConnect,
  SIMCONNECT_CLIENT_EVENT_ID  EventID,
  SIMCONNECT_STATE  dwState
);

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 reference 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_SetSystemState

The SimConnect_SetSystemState function is used to access a number of Flight Sim World system components.

Syntax

HRESULT SimConnect_SetSystemState(
  HANDLE  hSimConnect,
  const char*  szState,
  DWORD  dwInteger,
  float  fFloat,
  char*  szString
);


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

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

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).

 

System Event Name Description
General events
 
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. Note that this event, as well as the 1sec and 4sec events, are only sent while the sim is running i.e. they are not sent if a dialog is being shown.
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.
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 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.
FlightSaved Request a notification when a flight is saved correctly. The filename of the flight saved is returned in a SIMCONNECT_RECV_EVENT_FILENAME structure.
FlightStarted Request a notification when a flight is started. Specifically, this notification is sent when the "Loading" dialog reaches 100% and the simulation is about to begin.
FlightEnded Request a notification when a flight is ended. Although a default flight file may have been loaded, an actual flight session may not start immediately if the user has simply ended the flight and returned to the main menu. This callback allows resources to be cleaned up.
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.
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 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.
Paused Request a notification when the flight 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 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.
SimStart The 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 (defined in the FSW.CFG file) 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.
SimStop The simulator is not running. Typically the user is loading a flight, navigating the shell 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 flight 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.
AI Specific events
 
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 events
 
MissionCompleted Request a notification when the user has completed a mission. Refer also to the SIMCONNECT_MISSION_END enum.
MissionActionExecuted Request a notification when any mission action or trigger has been executed. This is largely for monitoring tools.
CustomMissionActionExecuted Request a notification when a custom mission action has been completed. Refer also to the SimConnect_CompleteCustomMissionAction function.
Multi-player Racing Events
 
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 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.
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.

 

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

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");

// The recurring events will be on by default, so set one of them to off.
hr = SimConnect_SetSystemEventState(hSimConnect, EVENT_RECUR_FRAME, SIMCONNECT_STATE_OFF);

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

The SimConnect_TransmitClientEvent function is used to request that the Flight Sim World server transmit to all SimConnect clients the specified client event.

Syntax

HRESULT SimConnect_TransmitClientEvent(
  HANDLE  hSimConnect,
  SIMCONNECT_OBJECT_ID  ObjectID,
  SIMCONNECT_CLIENT_EVENT_ID  EventID,
  DWORD  dwData,
  SIMCONNECT_NOTIFICATION_GROUP_ID  GroupID,
  SIMCONNECT_EVENT_FLAG  Flags
);

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 Flight Sim World 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:

 

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


// 1. Transmitting a custom event to other clients
static enum EVENT_ID {
 EVENT_MY_EVENT
 EVENT_DME
};
hr = SimConnect_MapClientEventToSimEvent(hSimConnect, EVENT_MY_EVENT, "Custom.Event");
// Send EVENT_MY_EVENT to all current SimConnect clients.
SimConnect_TransmitClientEvent(hSimConnect, 0, EVENT_MY_EVENT, 0, SIMCONNECT_GROUP_PRIORITY_HIGHEST, SIMCONNECT_EVENT_FLAG_GROUPID_IS_PRIORITY);

// 2. Setting an event value
hr = SimConnect_MapClientEventToSimEvent(hSimConnect, EVENT_DME, "DME_SELECT");
// Set the selected DME to 2
SimConnect_TransmitClientEvent(hSimConnect, 0, EVENT_DME, 2, SIMCONNECT_GROUP_PRIORITY_DEFAULT, SIMCONNECT_EVENT_FLAG_GROUPID_IS_PRIORITY);

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

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

Syntax

HRESULT SimConnect_UnsubscribeFromSystemEvent(
  HANDLE  hSimConnect,
  SIMCONNECT_CLIENT_EVENT_ID  EventID
);

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

static enum EVENT_ID {
   EVENT_FLIGHT_LOAD,
   EVENT_RECUR_1SEC,
   EVENT_RECUR_FRAME,
};

hr = SimConnect_SubscribeToSystemEvent(hSimConnect, EVENT_RECUR_1SEC);

...

hr = SimConnect_UnsubscribeFromSystemEvent(hSimConnect, EVENT_RECUR_1SEC);

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


Helper Functions

SimConnect_InsertString

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

Syntax

HRESULT SimConnect_InsertString(
  char*  pDest,
  DWORD  cbDest,
  void**  ppEnd,
  DWORD*  pcbStringV,
  const char*  pSource
);

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 strings. Its counterpart is the SimConnect_RetrieveString function.

See Also



SimConnect_RequestResponseTimes

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

Syntax

HRESULT SimConnect_RequestResponseTimes(
  HANDLE  hSimConnect,
  DWORD  nCount,
  float*  fElapsedSeconds
);

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

int quit = 0;
bool fTesting = true;
....
while( quit == 0 )
{
 hr = SimConnect_CallDispatch(hSimConnect, MyDispatchProc, NULL);
  Sleep(0);
  if (fTesting)
  {
    fTesting = false;
    float fElapsedSeconds[5];
    hr = SimConnect_RequestResponseTimes(hSimConnect, 5, &fElapsedSeconds[0]);
    \\ Enter code to display the contents of fElapsedSeconds
  }
}

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_RetrieveString

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

Syntax

HRESULT SimConnect_RetrieveString(
  SIMCONNECT_RECV*  pData,
  DWORD  cbData,
  void*  pStringV,
  char**  ppszString,
  DWORD*  pcbString
);

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

struct StructVS {
  char title[1];
}
StructVS *pS = (StructVS*)&pObjData->dwData;
char *pszTitle;
DWORD cbTitle;
hr = SimConnect_RetrieveString(pData, cbData, &pS->strings, &pszTitle, &cbTitle)))

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


AI Object Specific Functions

SimConnect_AICreateEnrouteATCAircraft

The SimConnect_AICreateEnrouteATCAircraft function is used to create an AI controlled aircraft that is about to start or is already underway on its flight plan.

Syntax

HRESULT SimConnect_AICreateEnrouteATCAircraft(
  HANDLE  hSimConnect,
  const char*  szContainerTitle,
  const char*  szTailNumber,
  int  iFlightNumber,
  const char*  szFlightPlanPath,
  double  dFlightPlanPosition,
  BOOL  bTouchAndGo,
  SIMCONNECT_DATA_REQUEST_ID  RequestID
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
szContainerTitle
  [in]  Null-terminated string containing the container title. The container title is found in the aircraft.cfg file (see the Aircraft Configuration Files document): for example: title=Airbus A321, title= Aircreation582SL, or title=Boeing 737-800.
szTailNumber
  [in]  Null-terminated string containing the tail number. This should have a maximum of 12 characters.
iFlightNumber
  [in]  Integer containing the flight number. There is no specific maximum length of this number. Any negative number indicates that there is no flight number.
szFlightPlanPath
  [in]  Null-terminated string containing the path to the flight plan file. Flight plans have the extension .pln, but no need to enter an extension here. The easiest way to create flight plans is to create them from within Flight Sim World itself, and then save them off for use with the AI controlled aircraft. There is no need to enter the full path to the file (just enter the filename) if the flight plan is in the default Flight Sim World Files directory.
dFlightPlanPosition
  [in]  Double floating point number containing the flight plan position. The number before the point contains the waypoint index, and the number afterwards how far along the route to the next waypoint the aircraft is to be positioned. The first waypoint index is 0. For example, 0.0 indicates that the aircraft has not started on the flight plan, 2.5 would indicate the aircraft is to be initialized halfway between the third and fourth waypoints (which would have indexes 2 and 3). The waypoints are those recorded in the flight plan, which may just be two airports, and do not include any taxiway points on the ground. Also there is a threshold that will ignore requests to have an aircraft taxiing or taking off, or landing. So set the value after the point to ensure the aircraft will be in level flight. See the section on Aircraft Flight Plans.
bTouchAndGo
  [in]  Flag, True indicating that landings should be touch and go, and not full stop landings.
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.

Reference Sample

 

Primary sample

AI Traffic

Remarks

An enroute aircraft can be on the ground or airborne when it is created by this function. Typically this will be an aircraft flying under IFR rules, and in constant radio contact with ATC. A number of errors, including SIMCONNECT_EXCEPTION_CREATE_AIRCRAFT_FAILED, apply to AI objects (refer to the SIMCONNECT_EXCEPTION enum for more details).

 

A SIMCONNECT_RECV_ID_EVENT_OBJECT_ADDREMOVE event notification can be subscribed to (see the SimConnect_SubscribeToSystemEvent function), which will return a SIMCONNECT_RECV_EVENT_OBJECT_ADDREMOVE structure whenever any client, including the one making the change, successfully adds or removes an AI controlled object.

 

This function should be used for fixed-wing aircraft flying between airports on land. There is no internal AI pilot for helicopters, gliders or hot-air balloons. In order to add a helicopter, glider or balloon not controlled by the user, the SimConnect client must implement full control of the aircraft. Set up these objects with a call to SimConnect_AICreateSimulatedObject.

 

For float-planes the recommended procedure is to control them using waypoints, and not the ATC system, as there is no concept of a "parking space" after a water landing. So, the waypoints of the route of the float-plane should include the route that it should follow before take off and after landing. For all these cases of controlling aircraft using the client, or using waypoints, set up the object using the SimConnect_AICreateNonATCAircraft call.

 

The Reality Bubble

In order to improve performance, only a certain area around the user's aircraft is actually simulated at any one time. As the user flies the aircraft that area (referred to in the simulator as the "reality bubble") moves along with the aircraft. Simulated objects outside of the area are removed altogether, and new AI aircraft are not created if they fall outside these bounds. The reality bubble is in fact more of a box, and is aligned to lines of latitude and longitude, so the box becomes narrower near the poles than it is as the equator. The following diagram shows how the reality bubble works. There are always nine boxes (approximately 64Km square at the equator) that are simulated, and the user aircraft is always in the center box. As the aircraft flies over a boundary line, then the areas that are simulated change. In the following diagram, the green areas are simulated (active aircraft, airports, ground vehicles, shipping traffic and so on), and the grey areas are not.

 

 

Note that if an aircraft, or other simulation object, falls outside this area and is deleted by the system, the client will no longer receive information on the object (typically requested by the SimConnect_RequestDataOnSimObject function). Consider using the SimConnect_SubscribeToSystemEvent function to request notifications for "ObjectRemoved" to test for these situations. No automatic notification is given when information is requested on an object, and then subsequently that object is removed.

 

Aircraft Flight Plans

The following table contains an example flight plan from Sea-Tac International airport (KSEA) to San Francisco International airport (KSFO), following high-altitude airways. There are six waypoints, including the departure and destination airports. A flight plan can be created by Flight Sim World or created directly in XML, matching the required format. The simplest flight plan will contain only the departure and destination airports.

 

<?xml version="1.0" encoding="UTF-8"?>

<SimBase.Document Type="AceXML" version="1,0">
    <Descr>AceXML Document</Descr>
    <WorldBase.FlightPlan>
        <Title>KSEA to KSFO</Title>
        <FPType>IFR</FPType>
        <RouteType>HighAlt</RouteType>
        <CruisingAlt>31000</CruisingAlt>
        <DepartureID>KSEA</DepartureID>
        <DepartureLLA>N47 25' 53.27",W122 18' 28.83",+000433.00</DepartureLLA>
        <DestinationID>KSFO</DestinationID>
        <DestinationLLA>N37 36' 26.00",W122 22' 49.59",+000013.00</DestinationLLA>
        <Descr>KSEA, KSFO</Descr>
        <DeparturePosition>34R</DeparturePosition>
        <DepartureName>Seattle-Tacoma Intl</DepartureName>
        <DestinationName>San Francisco Intl</DestinationName>
        <AppVersion>
            <AppVersionMajor>10</AppVersionMajor>
            <AppVersionBuild>60327</AppVersionBuild>
        </AppVersion>


        <ATCWaypoint id="KSEA">
            <ATCWaypointType>Airport</ATCWaypointType>
            <WorldPosition>N47 25' 53.27",W122 18' 28.83",+000433.00</WorldPosition>
            <ICAO>
                <ICAOIdent>KSEA</ICAOIdent>
            </ICAO>
        </ATCWaypoint>


        <ATCWaypoint id="SEA">
            <ATCWaypointType>VOR</ATCWaypointType>
            <WorldPosition>N47 26' 7.36",W122 18' 34.59",+000000.00</WorldPosition>
            <ICAO>
                <ICAORegion>K1</ICAORegion>
                <ICAOIdent>SEA</ICAOIdent>
            </ICAO>
        </ATCWaypoint>


        <ATCWaypoint id="LMT">
            <ATCWaypointType>VOR</ATCWaypointType>
            <WorldPosition>N42 9' 11.34",W121 43' 39.10",+000000.00</WorldPosition>
            <ATCAirway>J65</ATCAirway>
            <ICAO>
                <ICAORegion>K1</ICAORegion>
                <ICAOIdent>LMT</ICAOIdent>
            </ICAO>
        </ATCWaypoint>


        <ATCWaypoint id="RBL">
            <ATCWaypointType>VOR</ATCWaypointType>
            <WorldPosition>N40 5' 56.07",W122 14' 10.88",+000000.00</WorldPosition>
            <ATCAirway>J65</ATCAirway>
            <ICAO>
                <ICAORegion>K2</ICAORegion>
                <ICAOIdent>RBL</ICAOIdent>
            </ICAO>
        </ATCWaypoint>


        <ATCWaypoint id="OAK">
            <ATCWaypointType>VOR</ATCWaypointType>
            <WorldPosition>N37 43' 33.30",W122 13' 24.92",+000000.00</WorldPosition>
            <ATCAirway>J3</ATCAirway>
            <ICAO>
                <ICAORegion>K2</ICAORegion>
                <ICAOIdent>OAK</ICAOIdent>
            </ICAO>
        </ATCWaypoint>


        <ATCWaypoint id="KSFO">
            <ATCWaypointType>Airport</ATCWaypointType>
            <WorldPosition>N37 36' 26.00",W122 22' 49.59",+000013.00</WorldPosition>
            <ICAO>
                <ICAOIdent>KSFO</ICAOIdent>
            </ICAO>
        </ATCWaypoint>


    </WorldBase.FlightPlan>
</SimBase.Document>

 

See Also




SimConnect_AICreateNonATCAircraft

The SimConnect_AICreateNonATCAircraft function is used to create an aircraft that is not flying under ATC control (so is typically flying under VFR rules).

Syntax

HRESULT SimConnect_AICreateNonATCAircraft(
  HANDLE  hSimConnect,
  const char*  szContainerTitle,
  const char*  szTailNumber,
  SIMCONNECT_DATA_INITPOSITION  InitPos,
  SIMCONNECT_DATA_REQUEST_ID  RequestID
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
szContainerTitle
  [in]  Null-terminated string containing the container title. The container title is case-sensitive and can be found in the aircraft.cfg file (see the Aircraft Configuration Files document).
szTailNumber
  [in]  Null-terminated string containing the tail number. This should have a maximum of 12 characters.
InitPos
  [in]  Specifies the initial position, using a SIMCONNECT_DATA_INITPOSITION structure.
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.

Reference Sample

 

Primary sample AI Objects and Waypoints
Managed AI Waypoints

Remarks

A non-ATC aircraft can be on the ground or airborne when it is created by this function. A number of errors, including SIMCONNECT_EXCEPTION_CREATE_AIRCRAFT_FAILED, apply to AI objects (refer to the SIMCONNECT_EXCEPTION enum for more details).

 

Refer to the remarks for SimConnect_AICreateEnrouteATCAircraft.

See Also




SimConnect_AICreateParkedATCAircraft

The SimConnect_AICreateParkedATCAircraft function is used to create an AI controlled aircraft that is currently parked and does not have a flight plan.

Syntax

HRESULT SimConnect_AICreateParkedATCAircraft(
  HANDLE  hSimConnect,
  const char*  szContainerTitle,
  const char*  szTailNumber,
  const char*  szAirportID,
  SIMCONNECT_DATA_REQUEST_ID  RequestID
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
szContainerTitle
  [in]  Null-terminated string containing the container title. The container title is case-sensitive and can found in the aircraft.cfg file (see the Aircraft Configuration Files document).
szTailNumber
  [in]  Null-terminated string containing the tail number. This should have a maximum of 12 characters.
szAirportID
  [in]  Null-terminated string containing the airport ID. This is the ICAO identification string, for example, KSEA for SeaTac International.
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.

Reference Sample

 

Primary sample

AI Traffic

Remarks

Calling this function is no guarantee that there is sufficient parking space at the specified airport. An error will be returned if there is insufficient parking space, and an aircraft will not be created. A number of errors, including SIMCONNECT_EXCEPTION_CREATE_AIRCRAFT_FAILED, apply to AI objects (refer to the SIMCONNECT_EXCEPTION enum for more details). After creating an aircraft with this function, a call to SimConnect_AISetAircraftFlightPlan will set the aircraft in motion.

 

When allocating a parking space to an aircraft, the simulation uses a radius based on half the wingspan defined in the [aircraft_geometry] section of the Aircraft Configuration File.

 

Refer also to the remarks for SimConnect_AICreateEnrouteATCAircraft.

See Also




SimConnect_AICreateSimulatedObject

The SimConnect_AICreateSimulatedObject function is used to create AI controlled objects other than aircraft.

Syntax

HRESULT SimConnect_AICreateSimulatedObject(
  HANDLE  hSimConnect,
  const char*  szContainerTitle,
  SIMCONNECT_DATA_INITPOSITION  InitPos,
  SIMCONNECT_DATA_REQUEST_ID  RequestID
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
szContainerTitle
  [in]  Null-terminated string containing the container title. The container title is case-sensitive and can be found in the sim.cfg file, for example:

 

Object Types Examples
Ground Vehicles title=Automobile
title=FuelTruck
title=VEH_air_bagcart1
title=VEH_air_bagcart_FlatNosed
Boats title=cargoA
title=cargoA_hoop
title=cargoB
Miscellaneous

title=Flour_bomb_floating_dock

title=CaspianSeaMonster

title=HumpbackWhale

 


InitPos
  [in]  Specifies the initial position, using a SIMCONNECT_DATA_INITPOSITION structure.
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.

Reference Sample

 

Primary sample AI Objects and Waypoints
Managed AI Waypoints

Remarks

This function can be used to create a stationary aircraft (such as an unflyable aircraft on display outside a flight museum), but is typically intended to create simulation objects other than aircraft (such as ground vehicles, boats, and a number of special objects such as humpback whales and hot-air balloons). A number of errors apply to AI objects (refer to the SIMCONNECT_EXCEPTION enum for more details).

See Also


SimConnect_AIReleaseControl

The SimConnect_AIReleaseControl function is used to clear the AI control of a simulated object, typically an aircraft, in order for it to be controlled by a SimConnect client.

Syntax

HRESULT SimConnect_AIReleaseControl(
  HANDLE  hSimConnect,
  SIMCONNECT_OBJECT_ID  ObjectID,
  SIMCONNECT_DATA_REQUEST_ID  RequestID
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
ObjectID
  [in]  Specifies the server defined object ID.
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

This function should be used to transfer the control of an aircraft, or other object, from the AI system to the SimConnect client. If this is not done the AI system and client may fight each other with unpredictable results. To prevent the simulation engine from updating the latitude, longitude, altitude and attitude of an aircraft, refer to the range of KEY_FREEZE..... Event IDs.

 

The object ID can be obtained in a number of ways, refer to the SimConnect_RequestDataOnSimObjectType call, and also the use of the SIMCONNECT_RECV_ASSIGNED_OBJECT_ID structure.

See Also




SimConnect_AIRemoveObject

The SimConnect_AIRemoveObject function is used to remove any object created by the client using one of the AI creation functions.

Syntax

HRESULT SimConnect_AIRemoveObject(
  HANDLE  hSimConnect,
  SIMCONNECT_OBJECT_ID  ObjectID,
  SIMCONNECT_DATA_REQUEST_ID  RequestID
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
ObjectID
  [in]  Specifies the server defined object ID (refer to the SIMCONNECT_RECV_ASSIGNED_OBJECT_ID structure).
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

A client application can only remove AI controlled objects that it created, not objects created by other clients, or by the simulation itself.

See Also




SimConnect_AISetAircraftFlightPlan

The SimConnect_AISetAircraftFlightPlan function is used to set or change the flight plan of an AI controlled aircraft.

Syntax

HRESULT SimConnect_AISetAircraftFlightPlan(
  HANDLE  hSimConnect,
  SIMCONNECT_OBJECT_ID  ObjectID,
  const char*  szFlightPlanPath,
  SIMCONNECT_DATA_REQUEST_ID  RequestID
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
ObjectID
  [in]  Specifies the server defined object ID.
szFlightPlanPath
  [in]  Null-terminated string containing the path to the flight plan file. Flight plans have the extension .pln, but no need to enter an extension here. The easiest way to create flight plans is to create them from within the simulation, and then save them off for use with the AI controlled aircraft. There is no need to enter the full path (just the filename) if the flight plan is in the default Flight Sim World Files directory. See the section on Aircraft Flight Plans.
RequestID
  [in]  Specifies 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.

Reference Sample

 

Primary sample

AI Traffic

Remarks

A number of errors, including SIMCONNECT_EXCEPTION_CREATE_FLIGHTPLAN_FAILED, apply to AI objects (refer to the SIMCONNECT_EXCEPTION enum for more details).

 

Typically this function would be used some time after the aircraft was created using the SimConnect_AICreateParkedATCAircraft call.

See Also




Camera Specific Functions

SimConnect_CameraSetRelative6DOF

The SimConnect_CameraSetRelative6DOF function is used to adjust the user's aircraft view camera.

Syntax

HRESULT SimConnect_CameraSetRelative6DOF(
  HANDLE  hSimConnect,
  float  fDeltaX,
  float  fDeltaY,
  float  fDeltaZ,
  float  fPitchDeg,
  float  fBankDeg,
  float  fHeadingDeg
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
fDeltaX
  [in]  Float containing the delta in the x-axis from the eyepoint reference point. See the [views] section of the Aircraft Configuration Files document for a description of the eyepoint.
fDeltaY
  [in]  Float containing the delta in the y-axis from the eyepoint reference point.
fDeltaZ
  [in]  Float containing the delta in the z-axis from the eyepoint reference point.
fPitchDeg
  [in]  Float containing the pitch in degrees (rotation about the x axis). A positive value points the nose down, a negative value up. The range of allowable values is +90 to -90 degrees.
fBankDeg
  [in]  Float containing the bank angle in degrees (rotation about the z axis). The range of allowable values is +180 to -180 degrees.
fHeadingDeg
  [in]  Float containing the heading in degrees (rotation about the y axis). A positive value rotates the view right, a negative value left. If the user is viewing the 2D cockpit, the view will change to the Virtual Cockpit 3D view if the angle exceeds 45 degrees from the view ahead. The Virtual Cockpit view will change back to the 2D cockpit view if the heading angle drops below 45 degrees. The range of allowable values is +180 to -180 degrees.

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.

Reference Sample

 

Primary sample

Cockpit Camera

 

Remarks

Any one of the six parameters can be set to SIMCONNECT_CAMERA_IGNORE_FIELD which indicates that the value for the camera should be taken unmodified from the reference point.

See Also

 

SimConnect_CameraGetCurrentView

The SimConnect_CameraGetCurrentView function is used to fetch details of the user's aircraft view camera.

Syntax

HRESULT SimConnect_CameraGetCurrentView(
  HANDLE  hSimConnect,
  SIMCONNECT_DATA_REQUEST_ID  RequestID
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
RequestID
  [in]  Specifies the client defined request ID. This will be returned along with the data.

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 function returns an SIMCONNECT_RECV_CAMERA_VIEW structure.

See Also

 


SimConnect_CameraRemove

The SimConnect_CameraRemove function is used to delete a camera created with SimConnect_CameraSetCurrentView.

Syntax

HRESULT SimConnect_CameraRemove(
  HANDLE  hSimConnect,
  const GUID  gCustomCameraGUID
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
gCustomCameraGUID
  [in]  The GUID of a camera object previously created with SimConnect_CameraSetCurrentView.

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_CameraSetCurrentView

The SimConnect_CameraSetCurrentView function is used to set the current camera view according to the supplied details.

Syntax

HRESULT SimConnect_CameraSetCurrentView(
  HANDLE  hSimConnect,
  SIMCONNECT_DATA_CAMERA_VIEW  ViewToSet
  bool  bActivate
  bool  bForce
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
ViewToSet
  [in]  Specifies the the parameters for the new view, or an existing view with the same GUID, see SIMCONNECT_DATA_CAMERA_VIEW.
bActivate
  [in]  Activate or deactivate the supplied camera.
bForce
  [in]  Lock the camera to the supplied settings.

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



Facilities Specific Functions

SimConnect_RequestFacilitiesList

The SimConnect_RequestFacilitiesList function is used to request a list of all the facilities of a given type currently held in the facilities cache.

Syntax

HRESULT SimConnect_RequestFacilitiesList(
  HANDLE  hSimConnect,
  SIMCONNECT_FACILITY_LIST_TYPE  type,
  SIMCONNECT_DATA_REQUEST_ID  RequestID
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
type
  [in]  Specifies one member of the SIMCONNECT_FACILITY_LIST_TYPE enumeration type.
RequestID
  [in]  Specifies the client defined request ID. This will be returned along with the data.

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.

Reference Sample

 

Primary sample

FacilitiesData

Reference sample

Managed Facilities Request

Remarks

The simulation keeps a facilities cache of all the airports, waypoints, NDB and VOR stations within a certain radius of the user aircraft. This radius varies depending on where the aircraft is in the world, but is at least large enough to encompass the whole of the reality bubble for airports and waypoints, and can be over 200 miles for VOR and NDB stations. As the user aircraft moves facilities will be added to, and removed from, the cache. However, in the interests pf performance, hysteresis is built into the system.

 

To receive event notifications when a facility is added, use the SimConnect_SubscribeToFacilities function. When this function is first called, a full list from the cache will be sent, thereafter just the additions will be transmitted. No notification is given when a facility is removed from the cache. the Obviously to terminate these notifications use the SimConnect_UnsubscribeToFacilities function.

 

When requesting types of facility information, one function call has to be made for each of the four types of data. The data will be returned in one of the four structures:

The four list structures inherit the data from the SIMCONNECT_RECV_FACILITIES_LIST structure. Given that the list of returned facilities could be large, it may be split across several packets, and each packet must be interpreted separately by the client.

See Also




SimConnect_SubscribeToFacilities

The SimConnect_SubscribeToFacilities function is used to request notifications when a facility of a certain type is added to the facilities cache.

Syntax

HRESULT SimConnect_SubscribeToFacilities(
  HANDLE  hSimConnect,
  SIMCONNECT_FACILITY_LIST_TYPE  type,
  SIMCONNECT_DATA_REQUEST_ID  RequestID
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
type
  [in]  Specifies one member of the SIMCONNECT_FACILITY_LIST_TYPE enumeration type.
RequestID
  [in]  Specifies the client defined request ID. This will be returned along with the data.

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.

Reference Sample

 

Primary samples

FacilitiesData

Managed Facilities Request

 

Remarks

See the remarks for SimConnect_RequestFacilitiesList.

See Also




SimConnect_UnsubscribeToFacilities

The SimConnect_UnsubscribeToFacilities function is used to request that notifications of additions to the facilities cache are not longer sent.

Syntax

HRESULT SimConnect_UnsubscribeToFacilities(
  HANDLE  hSimConnect,
  SIMCONNECT_FACILITY_LIST_TYPE  type
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
type
  [in] Specifies one member of the SIMCONNECT_FACILITY_LIST_TYPE 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.

Reference Sample

 

Primary samples

FacilitiesData

Managed Facilities Request

 

Remarks

See the remarks for SimConnect_RequestFacilitiesList.

See Also



Menu Specific Functions

SimConnect_MenuAddItem

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

Syntax

HRESULT SimConnect_MenuAddItem(
  HANDLE  hSimConnect,
  const char*  szMenuItem,
  SIMCONNECT_CLIENT_EVENT_ID  MenuEventID,
  DWORD  dwData
);

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.

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

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

Syntax

HRESULT SimConnect_MenuAddSubItem(
  HANDLE  hSimConnect,
  SIMCONNECT_CLIENT_EVENT_ID  MenuEventID,
  const char*  szMenuItem,
  SIMCONNECT_CLIENT_EVENT_ID  SubMenuEventID,
  DWORD  dwData
);


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_MenuDeleteItem

The SimConnect_MenuDeleteItem function is used to remove a client defined menu item.

Syntax

HRESULT SimConnect_MenuDeleteItem(
  HANDLE  hSimConnect,
  const SIMCONNECT_CLIENT_EVENT_ID  MenuEventID
);

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.

Reference 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

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

Syntax

HRESULT SimConnect_MenuDeleteSubItem(
  HANDLE  hSimConnect,
  SIMCONNECT_CLIENT_EVENT_ID  MenuEventID,
  const SIMCONNECT_CLIENT_EVENT_ID   SubMenuEventID
);


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_Text

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

Syntax

HRESULT SimConnect_Text(
  HANDLE  hSimConnect,
  SIMCONNECT_TEXT_TYPE  type,
  float  fTimeSeconds,
  SIMCONNECT_CLIENT_EVENT_ID  EventID,
  DWORD  cbUnitSize,
  void*  pDataSet
);


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 or menu, in seconds. If zero is entered, the text or menu will not timeout. For text only, 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. These can be changed in the [SimConnect] section of FSW.cfg file using the TextMinPrintTimeSeconds and TextMinScrollTimeSeconds 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 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.

Reference Sample

 

Primary samples

Text Menu

FacilitiesData

Remarks

Only one text and one menu request can appear on the screen at one 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 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.

See Also



Mission Specific Functions

SimConnect_CompleteCustomMissionAction

The SimConnect_CompleteCustomMissionAction function is used to complete the mission action specified by a GUID.

Syntax

HRESULT SimConnect_CompleteCustomMissionAction(
  HANDLE  hSimConnect,
  const GUID  guidInstanceId
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
guidInstanceId
  [in]  GUID of the custom action. The GUID should be found in the associated mission xml file.

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.

Reference Sample

 

Primary sample Mission Action

Remarks

A mission is specified in an xml file. A custom action is defined within this xml file, and will look similar to the following:

 

<SimMission.CustomAction InstanceId="{ GUID }">

<PayLoadString>Any string goes here!</PayLoadString>

<WaitForCompletion>True</WaitForCompletion>

</SimMission.CustomAction>

 

Custom actions provide a mechanism to add complex processing to the basically data-driven mission system.

 

The custom action would typically be triggered from within the mission xml file (a trigger referencing the GUID of the custom action), though it could be called from within the SimConnect client with a call to SimConnect_ExecuteMissionAction. It is only necessary to call SimConnect_CompleteCustomMissionAction if the WaitForCompletion value is set to True.

 

If the client calls SimConnect_ExecuteMissionAction from within the code for a custom action, and it is important that this action completes before any other actions are started (that is, WaitForCompletion is True) then a second custom action should be defined that calls SimConnect_CompleteCustomMissionAction after that action is complete, and with the GUID of the first custom action as its parameter. The reference sample shows this process.

 

In order to received notifications that a custom action is to be executed, the SimConnect client should use the SimConnect_SubscribeToSystemEvent call with the SystemEventName parameter set to "CustomMissionActionExecuted". This will result in the GUID of the custom action, and the PayLoadString, being sent to the client in a SIMCONNECT_RECV_CUSTOM_ACTION structure.

 

If a mission requires additional processing on its completion the SimConnect client should use the SimConnect_SubscribeToSystemEvent call with the SystemEventName parameter set to "MissionCompleted".

See Also




SimConnect_ExecuteMissionAction

The SimConnect_ExecuteMissionAction function is used to execute the mission action specified by a GUID.

Syntax

HRESULT SimConnect_ExecuteMissionAction(
  HANDLE  hSimConnect,
  const GUID  guidInstanceId
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
guidInstanceId
  [in]  GUID of the Mission Action. The GUID should be found in the associated mission xml file.

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.

Reference Sample

 

Primary sample Mission Action

Remarks

A mission is specified in an xml file.

 

In order to use SimConnect_ExecuteMissionAction, typically there should be at least one custom action within the mission xml file. The custom action will initiate the sending of a notification to the SimConnect client, and the client can then both do some processing of its own and run, by calling SimConnect_ExecuteMissionAction, one or more actions (spoken text, for example) that are defined within the xml file.

 

See the remarks for SimConnect_CompleteCustomMissionAction.

See Also


Audio Specific Functions


SimConnect_VoiceCreate

The SimConnect_VoiceCreate function creates a new voice in the appropriate subgroup.

Syntax

HRESULT SimConnect_VoiceCreate(
  HANDLE  hSimConnect,
  UINT16  index,
  UINT16  subGroup,
  BOOL  is3d
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
index
  [in]  The voice index (0-127).
subGroup
  [in]  The subgroup for the voice (see notes).
is3d
  [in]  TRUE if the voice has a 3D position.

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 128 voices can be created. The sound group can be one of the following:

Number Description
1 Engine sounds
2 Cockpit sounds
3 Environmental sounds
4 Voice sounds
5 Music
6 UI sounds

See Also

SimConnect_QueueWaveOnVoice

The SimConnect_QueueWaveOnVoice function queues a WAV file, specified by a filename, on a voice.

Syntax

HRESULT SimConnect_QueueWaveOnVoice(
  HANDLE  hSimConnect,
  UINT16  index,
  DWORD  cbUnitSize,
  void *  pDataSet
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
index
  [in]  The voice index.
cbUnitSize
  [in]  Length of filename string including trailing zero.
pDataSet
  [in]  Pointer to filename 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

The queued data does not play automatically.

See Also

SimConnect_QueueWaveDataOnVoice

The SimConnect_QueueWaveDataOnVoice function queues wave data on a voice. The format expected is the same as a standard .WAV file.

Syntax

HRESULT SimConnect_QueueWaveDataOnVoice(
  HANDLE  hSimConnect,
  UINT16  index,
  DWORD  cbUnitSize,
  void *  pDataSet
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
index
  [in]  The voice index.
cbUnitSize
  [in]  Length of wave data.
pDataSet
  [in]  Pointer to data.

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 queued data does not play automatically.

See Also

SimConnect_PlayVoice

The SimConnect_PlayVoice function starts playing any queued data for a voice.

Syntax

HRESULT SimConnect_PlayVoice(
  HANDLE  hSimConnect,
  UINT16  index
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
index
  [in]  The voice index.

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_StopVoice

The SimConnect_StopVoice function stops a voice playing.

Syntax

HRESULT SimConnect_StopVoice(
  HANDLE  hSimConnect,
  UINT16  index
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
index
  [in]  The voice index.

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_SetVoiceLooping

The SimConnect_SetVoiceLooping function enables or disables looping on a voice.

Syntax

HRESULT SimConnect_SetVoiceLooping(
  HANDLE  hSimConnect,
  UINT16  index,
  BOOL  looping
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
index
  [in]  The voice index.
looping
  [in]  TRUE if the voice should loop.

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_SetVoiceVolume

The SimConnect_SetVoiceVolume function sets the volume on a voice.

Syntax

HRESULT SimConnect_SetVoiceVolume(
  HANDLE  hSimConnect,
  UINT16  index,
  float  vol
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
index
  [in]  The voice index.
vol
  [in]  The volume in decibels.

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_SetVoiceVolumeMin

The SimConnect_SetVoiceVolumeMin function sets the minimum volume for a voice.

Syntax

HRESULT SimConnect_SetVoiceVolumeMin(
  HANDLE  hSimConnect,
  UINT16  index,
  float  vol
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
index
  [in]  The voice index.
vol
  [in]  The volume in decibels.

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_SetVoiceVolumeMax

The SimConnect_SetVoiceVolumeMax function sets the maximum volume for a voice.

Syntax

HRESULT SimConnect_SetVoiceVolumeMax(
  HANDLE  hSimConnect,
  UINT16  index,
  float  vol
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
index
  [in]  The voice index.
vol
  [in]  The volume in decibels.

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_SetVoicePitch

The SimConnect_SetVoicePitch function sets the pitch for a voice.

Syntax

HRESULT SimConnect_SetVoicePitch(
  HANDLE  hSimConnect,
  UINT16  index,
  float  pitch
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
index
  [in]  The voice index.
pitch
  [in]  Frequency change, expressed as source frequency / target frequency.

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_SetVoicePosition

The SimConnect_SetVoicePosition function sets the 3D position of a voice.

Syntax

HRESULT SimConnect_SetVoicePosition(
  HANDLE  hSimConnect,
  UINT16  index,
  float  x, y, z,
  BOOL  userCentered
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
index
  [in]  The voice index.
x, y, z
  [in]  The position.
userCentered
  [in]  TRUE if the position is relative to the user's aircraft.

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

Needs to be called every frame.

See Also

SimConnect_SetVoiceVelocity

The SimConnect_SetVoiceVelocity function sets the 3D velocity of a voice.

Syntax

HRESULT SimConnect_SetVoiceVelocity(
  HANDLE  hSimConnect,
  UINT16  index,
  float  x, y, z,
  BOOL  userCentered
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
index
  [in]  The voice index.
x, y, z
  [in]  The velocity.
userCentered
  [in]  TRUE if the velocity is relative to the user's aircraft.

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

Needs to be called every frame.

See Also

SimConnect_SetVoiceConeOrientation

The SimConnect_SetVoiceConeOrientation function sets the orientation of the voice's cone (if used).

Syntax

HRESULT SimConnect_SetVoiceConeOrientation(
  HANDLE  hSimConnect,
  UINT16  index,
  float  x, y, z,
  BOOL  userCentered
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
index
  [in]  The voice index.
x, y, z
  [in]  Orientation as a normalized vector.
userCentered
  [in]  TRUE if the orientation is relative to the user's aircraft.

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

Needs to be called every frame.

See Also

SimConnect_SetVoiceConeAngles

The SimConnect_SetVoiceConeAngles function sets inner and outer cone angles for a voice.

Syntax

HRESULT SimConnect_SetVoiceConeAngles(
  HANDLE  hSimConnect,
  UINT16  index,
  UINT16  inner,
  UINT16  outer
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
index
  [in]  The voice index.
inner
  [in]  The angle of the inner cone in degrees.
outer
  [in]  The angle of the outer cone in degrees.

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_SetVoiceConeOuterVol

The SimConnect_SetVoiceConeOuterVol function sets the volume for the outer cone.

Syntax

HRESULT SimConnect_SetVoiceConeOuterVol(
  HANDLE  hSimConnect,
  UINT16  index,
  float  vol
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
index
  [in]  The voice index.
vol
  [in]  Volume in decibels.

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_SetVoiceFlush

The SimConnect_SetVoiceFlush function stops the voice and clears all queued data.

Syntax

HRESULT SimConnect_SetVoiceFlush(
  HANDLE  hSimConnect,
  UINT16  index
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
index
  [in]  The voice index.

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_VoiceDestroy

The SimConnect_VoiceDestroy function destroys a voice.

Syntax

HRESULT SimConnect_VoiceDestroy(
  HANDLE  hSimConnect,
  UINT16  index
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
index
  [in]  The voice index.

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_GetVoiceVolume

The SimConnect_GetVoiceVolume function is used to request the current volume for a voice.

Syntax

HRESULT SimConnect_GetVoiceVolume(
  HANDLE  hSimConnect,
  SIMCONNECT_DATA_REQUEST_ID  RequestID,
  UINT16  index
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
RequestID
  [in]  Specifies the client defined request ID. This will be returned along with the data.
index
  [in]  The voice index.

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 function returns an SIMCONNECT_RECV_AUDIO_RESPONSE structure.

See Also

SimConnect_GetVoicePitch

The SimConnect_GetVoicePitch function is used to request the current pitch of a voice.

Syntax

HRESULT SimConnect_GetVoicePitch(
  HANDLE  hSimConnect,
  SIMCONNECT_DATA_REQUEST_ID  RequestID,
  UINT16  index
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
RequestID
  [in]  Specifies the client defined request ID. This will be returned along with the data.
index
  [in]  The voice index.

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 function returns an SIMCONNECT_RECV_AUDIO_RESPONSE structure.

See Also

SimConnect_GetVoiceTimeRemaining

The SimConnect_GetVoiceTimeRemaining function is used to request the time remaining on a voice (in seconds).

Syntax

HRESULT SimConnect_GetVoiceTimeRemaining(
  HANDLE  hSimConnect,
  SIMCONNECT_DATA_REQUEST_ID  RequestID,
  UINT16  index
);

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
RequestID
  [in]  Specifies the client defined request ID. This will be returned along with the data.
index
  [in]  The voice index.

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 function returns an SIMCONNECT_RECV_AUDIO_RESPONSE structure.

See Also

SimConnect Structures and Enumerations

SimConnect uses the following 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_DATA_RACE_RESULT Struct

Used to hold mutiplayer racing results.

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_CAMERA_VIEW Struct Used to pass information on a camera view.
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_MARKERSTATE Struct Used to help graphically link flight model data with the graphics model.
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_VERTEX3D Struct Used to define an array of points for simple line rendering.
SIMCONNECT_EXCEPTION Enum

Used with the SIMCONNECT_RECV_EXCEPTION structure to return information on an error that has occurred.

SIMCONNECT_FACILITY_LIST_TYPE

Enum

Used to determine which type of facilities data is being requested or returned.
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_AUDIO_RESPONSE Struct Used to return audio data.
SIMCONNECT_RECV_ASSIGNED_OBJECT_ID Struct

Used to return an object ID that matches a request ID.

SIMCONNECT_RECV_CAMERA_VIEW Struct Will be received by the client after a successful call to SimConnect_CameraGetCurrentView.
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_CLOUD_STATE Struct Used to return an array of cloud state data.
SIMCONNECT_RECV_CUSTOM_ACTION Struct

Used specifically with the mission system, providing details on the custom action that has been triggered.

SIMCONNECT_RECV_EVENT Struct

Used to return an event ID to the client.

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 Sent to a client when they have successfully joined a multi-player race.
SIMCONNECT_RECV_EVENT_MULTIPLAYER_SERVER_STARTED Struct Sent to the host when the session is visible to other users in the lobby.
SIMCONNECT_RECV_EVENT_MULTIPLAYER_SESSION_ENDED Struct 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 Used to hold the results for one player at the end of a race.
SIMCONNECT_RECV_EVENT_RACE_LAP Struct Used 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_ID Enum

Used within the SIMCONNECT_RECV structure to indicate which type of structure has been returned.

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 Sim World 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_RECV_WEATHER_OBSERVATION Struct

Used to return weather observation data, after calls to one of:

SimConnect_WeatherRequestInterpolatedObservation, SimConnect_WeatherRequestObservationAtStation, or SimConnect_WeatherRequestObservationAtNearestStation.
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_TEXT_TYPE Enum Used to specify which type of text is to be displayed by the SimConnect_Text function
SIMCONNECT_WAYPOINT_FLAGS Enum Used with the SIMCONNECT_DATA_WAYPOINT structure to define waypoints.
SIMCONNECT_WEATHER_MODE Enum Used to return the current weather mode, after a call using the SIMCONNECT_RECV_ID_EVENT_WEATHER_MODE setting.



SIMCONNECT_CLIENT_DATA_PERIOD

The SIMCONNECT_CLIENT_DATA_PERIOD enumeration type is used with the SimConnect_RequestClientData call to specify how often data is to be sent to the client.

Syntax

enum SIMCONNECT_CLIENT_DATA_PERIOD{
  SIMCONNECT_PERIOD_NEVER,
  SIMCONNECT_PERIOD_ONCE,
  SIMCONNECT_PERIOD_VISUAL_FRAME,
  SIMCONNECT_PERIOD_ON_SET,
  SIMCONNECT_PERIOD_SECOND,
};

Members

SIMCONNECT_PERIOD_NEVER
  Specifies that the data is not to be sent.


SIMCONNECT_PERIOD_ONCE
  Specifies that the data should be sent once only. Note that this is not an efficient way of receiving data frequently, use one of the other periods if there is a regular frequency to the data request.


SIMCONNECT_PERIOD_VISUAL_FRAME
  Specifies that the data should be sent every visual (rendered) frame.


SIMCONNECT_PERIOD_ON_SET
  Specifies that the data should be sent whenever it is set.


SIMCONNECT_PERIOD_SECOND
  Specifies that the data should be sent once every second.

Remarks

Although the period definitions are specific, data is always transmitted at the end of a frame, so even if you have specified that data should be sent every second, the data will actually be transmitted at the end of the frame that comes on or after one second has elapsed.

See Also



SIMCONNECT_DATA_RACE_RESULT

The SIMCONNECT_DATA_RACE_RESULT structure is used to hold mutiplayer racing results.

Syntax

struct SIMCONNECT_DATA_RACE_RESULT{
  DWORD  dwNumberOfRacers;
  GUID  MissionGUID;
  char  szPlayerName[MAX_PATH];
  char  szSessionType[MAX_PATH];
  char  szAircraft[MAX_PATH];
  char  szPlayerRole[MAX_PATH];
  double  fTotalTime;
  double  fPenaltyTime;
  DWORD  dwIsDisqualified;
};

Members

dwNumberOfRacers
   The total number of racers.
MissionGUID
   The GUID of the mission that has been selected by the host.
szPlayerName[MAX_PATH]
   Null terminated string containing the name of the player.
szSessionType[MAX_PATH]
   Null terminated string containing the type of the multiplayer session, currently one of: "LAN" or "GAMESPY".
szAircraft[MAX_PATH]
   Null terminated string containing the aircraft type, which is the title field from the Aircraft Configuration File.
szPlayerRole[MAX_PATH]
   Null terminated string containing the player's role (or name) in the mission. This string wil be filled from the Name property of the Player object in the mission file.
fTotalTime
   If this structure is a member of a SIMCONNECT_RECV_EVENT_RACE_END structure, then this contains the final race time in seconds, or 0 for DNF (Did Not Finish). If this structure is a member of a SIMCONNECT_RECV_EVENT_RACE_LAP structure, then this contains the lap time in seconds.
fPenaltyTime
   If this structure is a member of a SIMCONNECT_RECV_EVENT_RACE_END structure, then this contains the final penalty time in seconds. If this structure is a member of a SIMCONNECT_RECV_EVENT_RACE_LAP structure, then this contains the total penalty time in seconds received so far (not just for this lap).
dwIsDisqualified
   A boolean value, 0 indicating the player has not been disqualified, non-zero indicating they have been disqualified.

Remarks

This structure is never sent on its own, but is always a member of either a SIMCONNECT_RECV_EVENT_RACE_END structure or a SIMCONNECT_RECV_EVENT_RACE_LAP structure.

See Also





SIMCONNECT_VERTEX3D

The SIMCONNECT_VERTEX3D structure is used to send an array of points for vector line rendering.

Syntax

struct SIMCONNECT_VERTEX3D {
  float  xOffset;
  float  yOffset;
  float  zOffset;
  BOOL  LastInSegment;
  DWORD  colourARGB;
};

Members

xOffset, yOffset, zOffset
   Offset from the shape's defined world position, in meters.
LastInSegment
   If TRUE, this point will not have a line drawn between it and the next one.
colourARGB
   The colour to be used for the line between this point and the previous one.

Remarks

See Also




SIMCONNECT_DATATYPE

The SIMCONNECT_DATATYPE enumeration type is used with the SimConnect_AddToDataDefinition call to specify the data type that the server should use to return the specified data to the client.

Syntax

enum SIMCONNECT_DATATYPE{
  SIMCONNECT_DATATYPE_INVALID,
  SIMCONNECT_DATATYPE_INT32,
  SIMCONNECT_DATATYPE_INT64,
  SIMCONNECT_DATATYPE_FLOAT32,
  SIMCONNECT_DATATYPE_FLOAT64,
  SIMCONNECT_DATATYPE_STRING8,
  SIMCONNECT_DATATYPE_STRING32,
  SIMCONNECT_DATATYPE_STRING64,
  SIMCONNECT_DATATYPE_STRING128,
  SIMCONNECT_DATATYPE_STRING256,
  SIMCONNECT_DATATYPE_STRING260,
  SIMCONNECT_DATATYPE_STRINGV,
  SIMCONNECT_DATATYPE_INITPOSITION,
  SIMCONNECT_DATATYPE_MARKERSTATE,
  SIMCONNECT_DATATYPE_WAYPOINT,
  SIMCONNECT_DATATYPE_LATLONALT,
  SIMCONNECT_DATATYPE_XYZ,

  SIMCONNECT_DATATYPE_MAX
};

Members

SIMCONNECT_DATATYPE_FLOAT32,64
  Specifies a 32 bit or 64 bit floating point number.


SIMCONNECT_DATATYPE_STRING8,32,64,128,256,260

  Specifies strings of the given length (8 characters to 260 characters)

SIMCONNECT_DATATYPE_STRINGV
  Specifies a variable length string.


SIMCONNECT_DATATYPE_INITPOSITION
  Specifies the SIMCONNECT_DATA_INITPOSITION structure.


SIMCONNECT_DATATYPE_MARKERSTATE
  Specifies the SIMCONNECT_DATA_MARKERSTATE structure.


SIMCONNECT_DATATYPE_WAYPOINT
  Specifies the SIMCONNECT_DATA_WAYPOINT structure.


SIMCONNECT_DATATYPE_LATLONALT
  Specifies the SIMCONNECT_DATA_LATLONALT structure.


SIMCONNECT_DATATYPE_XYZ
  Specifies the SIMCONNECT_DATA_XYZ structure.

Reference Samples

 

Primary samples

Request Data

Set Data

Tagged Data

Throttle Control

Remarks

The three structures in the list of data types can only be used as input (using SimConnect_SetDataOnSimObject) and not to receive requested data.

See Also


SIMCONNECT_DATA_CAMERA_VIEW

The SIMCONNECT_DATA_CAMERA_VIEW structure is used to pass information on a camera view.

Syntax

struct SIMCONNECT_DATA_CAMERA_VIEW
{
  GUID  cameraDefinitionId;
  char  szCameraName[32];
  SIMCONNECT_VIEW_SYSTEM_EVENT_DATA  ViewType;
  DWORD  SourceObjectID;
  SIMCONNECT_DATA_LATLONALT  EyePosition;
  double  EyePosAGL;
  DWORD  TargetObjectID;
  SIMCONNECT_DATA_LATLONALT  TargetPosition;
  double  TargetPosAGL;
  double  OffsetPitch;
  double  OffsetBank;
  double  OffsetHeading;
  double  AbsPitch;
  double  AbsBank;
  double  AbsHeading;
  SIMCONNECT_DATA_XYZ  BiasOffset;
  SIMCONNECT_DATA_XYZ  TargetObjectOffset;
  double  Zoom;
  BOOL  IsCinematic;
  BOOL  IsInternal;
  BOOL  CanTransition;
  BOOL  PlayerSelectable;
};

Members

cameraDefinitionID
  GUID of the camera concerned.
szCameraName
  String containing the camera name.
ViewType
  Bitfield value describing the type of camera (see SimConnect_SubscribeToSystemEvent).
SourceObjectID
  Object the camera is attached to, can be SIMCONNECT_UNUSED, SIMCONNECT_OBJECT_ID_USER, or a game object id.
EyePosition
  Latitude, Longitude, Altitude of the eyepoint.
EyePosAGL
  Eyepoint altitude relative to ground level (get) or whether to treat the EyePosition altitude as AGL (set) if non-zero.
TargetObjectID
  Object the camera is looking at, can be SIMCONNECT_UNUSED or a game object id.
TargetPosition
  Latitude, Longitude, Altitude of the target point.
TargetPosAGL
  Whether to treat the TargetPosition altitude as AGL (set) if non-zero.
OffsetPitch
  Pitch angle of the view, including user adjusments.
OffsetBank
  Bank angle of the view, including user adjusments.
OffsetHeading
  Heading angle of the view, including user adjusments.
AbsPitch
  Pitch angle of the view, without user adjusments.
AbsBank
  Bank angle of the view, without user adjusments.
AbsHeading
  Heading angle of the view, without user adjusments.
BiasOffset
  XYZ offsets of the view from the eyepoint.
TargetObjectOffset
  XYZ offsets of the target object (for cinematic mission cameras only).
IsCinematic
  Is this a cinematic camera.
IsInternal
  Is this an in-cockpit camera.
CanTransition
  Can this camera transition.
PlayerSelectable
  Can the player select this camera.

See Also



SIMCONNECT_DATA_FACILITY_AIRPORT

The SIMCONNECT_DATA_FACILITY_AIRPORT structure is used to return information on a single airport in the facilities cache.

Syntax

struct SIMCONNECT_DATA_FACILITY_AIRPORT{
  char  Icao[9];
  double  Latitude;
  double  Longitude;
  double  Altitude;
};

Members

Icao[9]
   ICAO of the facility.
Latitude
   Latitude of the airport in facility.
Longitude
   Longitude of the airport in facility.
Altitude
   Altitude of the facility in meters.

Remarks

This structure is returned as one element in the SIMCONNECT_RECV_AIRPORT_LIST structure. Note that this structure is inherited by SIMCONNECT_DATA_FACILITY_WAYPOINT, SIMCONNECT_DATA_FACILITY_NDB and SIMCONNECT_DATA_FACILITY_VOR, so the latitude, longitude, and altitude will apply to those facilities in that case.

 

See the remarks for SimConnect_RequestFacilitiesList.

See Also



SIMCONNECT_DATA_FACILITY_NDB

The SIMCONNECT_DATA_FACILITY_NDB structure is used to return information on a single NDB station in the facilities cache.

Syntax

struct SIMCONNECT_DATA_FACILITY_NDB : public SIMCONNECT_DATA_FACILITY_WAYPOINT{
  DWORD  fFrequency;
};

Members

fFrequency
   Frequency of the station in Hz.

Remarks

This structure is returned as one element in the SIMCONNECT_RECV_NDB_LIST structure. It inherits all the members of the SIMCONNECT_DATA_FACILITY_WAYPOINT structure.

 

See the remarks for SimConnect_RequestFacilitiesList.

See Also



SIMCONNECT_DATA_FACILITY_VOR

The SIMCONNECT_DATA_FACILITY_VOR structure is used to return information on a single VOR station in the facilities cache.

Syntax

struct SIMCONNECT_DATA_FACILITY_VOR: public SIMCONNECT_DATA_FACILITY_NDB{
  DWORD  Flags;
  float  fLocalizer;
  double  GlideLat;
  double  GlideLon;
  double  GlideAlt;
  float  fGlideSlopeAngle;
};

Members

Flags
  Flags indicating whether the other fields are valid or not.

Flag Value Description
SIMCONNECT_RECV_ID_VOR_LIST_HAS_NAV_SIGNAL 0x1 Set if the station has a NAV transmitter, and if so, GlideLat, GlideLon and GlideAlt contain valid data.
SIMCONNECT_RECV_ID_VOR_LIST_HAS_LOCALIZER 0x2 Set if the station transmits an ILS localizer angle, and if so fLocalizer contains valid data.
SIMCONNECT_RECV_ID_VOR_LIST_HAS_GLIDE_SLOPE 0x4 Set if the station transmits an ILS approach angle, and if so fGlideSlopeAngle contains valid data.
SIMCONNECT_RECV_ID_VOR_LIST_HAS_DME 0x8 Set if the station t transmits a DME signal, and if so the inherited DME fFrequency contains valid data.


fLocalizer
   The ILS localizer angle in degrees.
GlideLat
   The latitude of the glide slope transmitter in degrees.
GlideLon
  The longitude of the glide slope transmitter in degrees.
GlideAlt
  The altitude of the glide slope transmitter in degrees.
fGlideSlopeAngle
   The ILS approach angle in degrees.

Remarks

This structure is returned as one element in the SIMCONNECT_RECV_VOR_LIST structure. It inherits all the members from SIMCONNECT_DATA_FACILITY_NDB.

 

See the remarks for SimConnect_RequestFacilitiesList.

See Also




SIMCONNECT_DATA_FACILITY_WAYPOINT

The SIMCONNECT_DATA_FACILITY_WAYPOINT structure used to return information on a single waypoint in the facilities cache.

Syntax

struct SIMCONNECT_DATA_FACILITY_WAYPOINT : public SIMCONNECT_DATA_FACILITY_AIRPORT {
  float  fMagVar;
};

Members

fMagVar
   The magnetic variation of the waypoint in degrees.

Remarks

This structure is returned as one element in the SIMCONNECT_RECV_WAYPOINT_LIST structure. It inherits all the members of the SIMCONNECT_DATA_FACILITY_AIRPORT structure.

 

See the remarks for SimConnect_RequestFacilitiesList.

See Also



SIMCONNECT_PERIOD

The SIMCONNECT_PERIOD enumeration type is used with the SimConnect_RequestDataOnSimObject call to specify how often data is to be sent to the client.

Syntax

enum SIMCONNECT_PERIOD{
  SIMCONNECT_PERIOD_NEVER,
  SIMCONNECT_PERIOD_ONCE,
  SIMCONNECT_PERIOD_VISUAL_FRAME,
  SIMCONNECT_PERIOD_SIM_FRAME,
  SIMCONNECT_PERIOD_SECOND,
};

Members

SIMCONNECT_PERIOD_NEVER
  Specifies that the data is not to be sent.


SIMCONNECT_PERIOD_ONCE
  Specifies that the data should be sent once only. Note that this is not an efficient way of receiving data frequently, use one of the other periods if there is a regular frequency to the data request.


SIMCONNECT_PERIOD_VISUAL_FRAME
  Specifies that the data should be sent every visual (rendered) frame.


SIMCONNECT_PERIOD_SIM_FRAME
  Specifies that the data should be sent every simulated frame, whether that frame is rendered or not.


SIMCONNECT_PERIOD_SECOND
  Specifies that the data should be sent once every second.

Reference Samples

 

Primary samples

Tagged Data

 

Reference samples Weather Station

Remarks

Although the period definitions are specific, data is always transmitted at the end of a frame, so even if you have specified that data should be sent every second, the data will actually be transmitted at the end of the frame that comes on or after one second has elapsed.

See Also




SIMCONNECT_EXCEPTION

The SIMCONNECT_EXCEPTION enumeration type is used with the SIMCONNECT_RECV_EXCEPTION structure to return information on an error that has occurred.

Syntax

enum SIMCONNECT_EXCEPTION{
  SIMCONNECT_EXCEPTION_NONE = 0,
  SIMCONNECT_EXCEPTION_ERROR = 1,
  SIMCONNECT_EXCEPTION_SIZE_MISMATCH = 2,
  SIMCONNECT_EXCEPTION_UNRECOGNIZED_ID = 3,
  SIMCONNECT_EXCEPTION_UNOPENED = 4,
  SIMCONNECT_EXCEPTION_VERSION_MISMATCH = 5,
  SIMCONNECT_EXCEPTION_TOO_MANY_GROUPS = 6,
  SIMCONNECT_EXCEPTION_NAME_UNRECOGNIZED = 7,
  SIMCONNECT_EXCEPTION_TOO_MANY_EVENT_NAMES = 8,
  SIMCONNECT_EXCEPTION_EVENT_ID_DUPLICATE = 9,
  SIMCONNECT_EXCEPTION_TOO_MANY_MAPS = 10,
  SIMCONNECT_EXCEPTION_TOO_MANY_OBJECTS = 11,
  SIMCONNECT_EXCEPTION_TOO_MANY_REQUESTS = 12,
  SIMCONNECT_EXCEPTION_WEATHER_INVALID_PORT = 13,
  SIMCONNECT_EXCEPTION_WEATHER_INVALID_METAR = 14,
  SIMCONNECT_EXCEPTION_WEATHER_UNABLE_TO_GET_OBSERVATION = 15,
  SIMCONNECT_EXCEPTION_WEATHER_UNABLE_TO_CREATE_STATION = 16,
  SIMCONNECT_EXCEPTION_WEATHER_UNABLE_TO_REMOVE_STATION = 17,
  SIMCONNECT_EXCEPTION_INVALID_DATA_TYPE = 18,
  SIMCONNECT_EXCEPTION_INVALID_DATA_SIZE = 19,
  SIMCONNECT_EXCEPTION_DATA_ERROR = 20,
  SIMCONNECT_EXCEPTION_INVALID_ARRAY = 21,
  SIMCONNECT_EXCEPTION_CREATE_OBJECT_FAILED = 22,
  SIMCONNECT_EXCEPTION_LOAD_FLIGHTPLAN_FAILED = 23,
  SIMCONNECT_EXCEPTION_OPERATION_INVALID_FOR_OJBECT_TYPE = 24,
  SIMCONNECT_EXCEPTION_ILLEGAL_OPERATION = 25,
  SIMCONNECT_EXCEPTION_ALREADY_SUBSCRIBED = 26,
  SIMCONNECT_EXCEPTION_INVALID_ENUM = 27,
  SIMCONNECT_EXCEPTION_DEFINITION_ERROR = 28,
  SIMCONNECT_EXCEPTION_DUPLICATE_ID = 29,
  SIMCONNECT_EXCEPTION_DATUM_ID = 30,
  SIMCONNECT_EXCEPTION_OUT_OF_BOUNDS = 31,

  SIMCONNECT_EXCEPTION_ALREADY_CREATED = 32,
  SIMCONNECT_EXCEPTION_OBJECT_OUTSIDE_REALITY_BUBBLE = 33,
  SIMCONNECT_EXCEPTION_OBJECT_CONTAINER = 34,
  SIMCONNECT_EXCEPTION_OBJECT_AI = 35,
  SIMCONNECT_EXCEPTION_OBJECT_ATC = 36,
  SIMCONNECT_EXCEPTION_OBJECT_SCHEDULE = 37,
};

Members

General errors

SIMCONNECT_EXCEPTION_NONE
  Specifies that there has not been an error. This value is not currently used.


SIMCONNECT_EXCEPTION_ERROR
  An unspecific error has occurred. This can be from incorrect flag settings, null or incorrect parameters, the need to have at least one up or down event with an input event, failed calls from the SimConnect server to the operating system, among other reasons.


SIMCONNECT_EXCEPTION_SIZE_MISMATCH
  Specifies the size of the data provided does not match the size required. This typically occurs when the wrong string length, fixed or variable, is involved.


SIMCONNECT_EXCEPTION_UNRECOGNIZED_ID
  Specifies that the client event, request ID, data definition ID, or object ID was not recognized.


SIMCONNECT_EXCEPTION_UNOPENED
  Specifies that communication with the SimConnect server has not been opened. This error is not currently used.


SIMCONNECT_EXCEPTION_VERSION_MISMATCH
  Specifies a versioning error has occurred. Typically this will occur when a client built on a newer version of the SimConnect client dll attempts to work with an older version of the SimConnect server.


SIMCONNECT_EXCEPTION_TOO_MANY_GROUPS
  Specifies that the maximum number of groups allowed has been reached. The maximum is 20.


SIMCONNECT_EXCEPTION_NAME_UNRECOGNIZED
  Specifies that the simulation event name (such as "brakes") is not recognized.


SIMCONNECT_EXCEPTION_TOO_MANY_EVENT_NAMES
  Specifies that the maximum number of event names allowed has been reached. The maximum is 1000.


SIMCONNECT_EXCEPTION_EVENT_ID_DUPLICATE
  Specifies that the event ID has been used already. This can occur with calls to SimConnect_MapClientEventToSimEvent, or SimConnect_SubscribeToSystemEvent.


SIMCONNECT_EXCEPTION_TOO_MANY_MAPS
  Specifies that the maximum number of mappings allowed has been reached. The maximum is 20.


SIMCONNECT_EXCEPTION_TOO_MANY_OBJECTS
  Specifies that the maximum number of objects allowed has been reached. The maximum is 1000.


SIMCONNECT_EXCEPTION_TOO_MANY_REQUESTS
  Specifies that the maximum number of requests allowed has been reached. The maximum is 1000.


SIMCONNECT_EXCEPTION_INVALID_DATA_TYPE
  Specifies that the data type requested does not apply to the type of data requested. Typically this occurs with a fixed length string of the wrong length.


SIMCONNECT_EXCEPTION_INVALID_DATA_SIZE
  Specifies that the size of the data provided is not what is expected. This can occur when the size of a structure provided does not match the size given, or a null string entry is made for a menu or sub-menu entry text, or data with a size of zero is added to a data definition. It can also occur with an invalid request to SimConnect_CreateClientData.


SIMCONNECT_EXCEPTION_DATA_ERROR
  Specifies a generic data error. This error is used by the SimConnect_WeatherCreateThermal function to report incorrect parameters, such as negative radii or values greater than the maximum allowed. It is also used by the SimConnect_FlightSave and SimConnect_FlightLoad functions to report incorrect file types. It is also used by other functions to report that flags or reserved parameters have not been set to zero.


SIMCONNECT_EXCEPTION_INVALID_ARRAY
  Specifies an invalid array has been sent to the SimConnect_SetDataOnSimObject function.


SIMCONNECT_EXCEPTION_ALREADY_SUBSCRIBED
  Specifies that the client has already subscribed to that event.


SIMCONNECT_EXCEPTION_INVALID_ENUM
  Specifies that the member of the enumeration provided was not valid. Currently this is only used if an unknown type is provided to SimConnect_RequestDataOnSimObjectType.


SIMCONNECT_EXCEPTION_DEFINITION_ERROR
  Specifies that there is a problem with a data definition. Currently this is only used if a variable length definition is sent with SimConnect_RequestDataOnSimObject.


SIMCONNECT_EXCEPTION_DUPLICATE_ID
  Specifies that the ID has already been used. This can occur with menu IDs, or with the IDs provided to SimConnect_AddToDataDefinition, SimConnect_AddClientEventToNotificationGroup or SimConnect_MapClientDataNameToID.


SIMCONNECT_EXCEPTION_DATUM_ID
  Specifies that the datum ID is not recognized. This currently occurs with a call to the SimConnect_SetDataOnSimObject function.


SIMCONNECT_EXCEPTION_OUT_OF_BOUNDS
  Specifies that the radius given in the SimConnect_RequestDataOnSimObjectType was outside the acceptable range, or with an invalid request to SimConnect_CreateClientData.

 

SIMCONNECT_EXCEPTION_ALREADY_CREATED
  Specifies that a client data area with the name requested by a call to SimConnect_MapClientDataNameToID has already been created by another addon. Try again with a different name.

 

Weather system errors

SIMCONNECT_EXCEPTION_WEATHER_INVALID_PORT
  Specifies an invalid port number was requested.


SIMCONNECT_EXCEPTION_WEATHER_INVALID_METAR
  Specifies that the metar data supplied did not match the required format. See the section Metar Data Format for details on the format required.


SIMCONNECT_EXCEPTION_WEATHER_UNABLE_TO_GET_OBSERVATION
  Specifies that the weather observation requested was not available. Refer to the remarks section for SimConnect_WeatherRequestObservationAtStation for some notes on this exception.


SIMCONNECT_EXCEPTION_WEATHER_UNABLE_TO_CREATE_STATION
  Specifies that the weather station could not be created.


SIMCONNECT_EXCEPTION_WEATHER_UNABLE_TO_REMOVE_STATION
  Specifies that the weather station could not be removed.

 

AI errors

SIMCONNECT_EXCEPTION_CREATE_OBJECT_FAILED
  Specifies that the attempt to create an AI object failed.


SIMCONNECT_EXCEPTION_LOAD_FLIGHTPLAN_FAILED
  Specifies that the specified flight plan could not be found, or did not load correctly.


SIMCONNECT_EXCEPTION_OPERATION_INVALID_FOR_OBJECT_TYPE
  Specifies that the operation requested does not apply to the object type, for example trying to set a flight plan on an object that is not an aircraft will result in this error.


SIMCONNECT_EXCEPTION_ILLEGAL_OPERATION
  Specifies that the AI operation requested cannot be completed, such as requesting that an object be removed when the client did not create that object. This error also applies to the Weather system.

 

SIMCONNECT_EXCEPTION_OBJECT_OUTSIDE_REALITY_BUBBLE
  Specifies that an attempt to create an ATC controlled AI object failed because the location of the object is outside the reality bubble.


SIMCONNECT_EXCEPTION_OBJECT_CONTAINER
  Specifies that an attempt to create an AI object failed because of an error with the container system for the object.


SIMCONNECT_EXCEPTION_OBJECT_AI
  Specifies that an attempt to create an AI object failed because of an error with the AI system for the object.


SIMCONNECT_EXCEPTION_OBJECT_ATC
  Specifies that an attempt to create an AI object failed because of an error with the ATC system for the object.


SIMCONNECT_EXCEPTION_OBJECT_SCHEDULE
  Specifies that an attempt to create an AI object failed because of a scheduling problem.

Reference Sample

 

Primary sample

Tracking Errors

 

Remarks

In the context of SimConnect, exceptions are error codes, and should not be confused with the C# or system concepts of exceptions. Refer to the remarks for SimConnect_GetLastSentPacketID.

See Also



SIMCONNECT_FACILITY_LIST_TYPE

The SIMCONNECT_FACILITY_LIST_TYPE enumeration type is used to determine which type of facilities data is being requested or returned.

Syntax

enum SIMCONNECT_FACILITY_LIST_TYPE{
  SIMCONNECT_FACILITY_LIST_TYPE_AIRPORT,
  SIMCONNECT_FACILITY_LIST_TYPE_WAYPOINT,
  SIMCONNECT_FACILITY_LIST_TYPE_NDB,
  SIMCONNECT_FACILITY_LIST_TYPE_VOR,
  SIMCONNECT_FACILITY_LIST_TYPE_COUNT
};

Members

SIMCONNECT_FACILITY_LIST_TYPE_AIRPORT
  Specifies that the type of information is for an airport, see SIMCONNECT_DATA_FACILITY_AIRPORT.


SIMCONNECT_FACILITY_LIST_TYPE_WAYPOINT
  Specifies that the type of information is for a waypoint, see SIMCONNECT_DATA_FACILITY_WAYPOINT.


SIMCONNECT_FACILITY_LIST_TYPE_NDB
  Specifies that the type of information is for an NDB, see SIMCONNECT_DATA_FACILITY_NDB.


SIMCONNECT_FACILITY_LIST_TYPE_VOR
  Specifies that the type of information is for a VOR, see SIMCONNECT_DATA_FACILITY_VOR.


SIMCONNECT_FACILITY_LIST_TYPE_COUNT
  Not valid as a list type, but simply the number of list types.

Reference Sample

 

Primary sample

FacilitiesData

 

Remarks

See the remarks for SimConnect_RequestFacilitiesList.

See Also




SIMCONNECT_MISSION_END

The SIMCONNECT_MISSION_END enumeration type is used to specify the three possible outcomes of a mission.

Syntax

enum SIMCONNECT_MISSION_END{
  SIMCONNECT_MISSION_FAILED,
  SIMCONNECT_MISSION_CRASHED,
  SIMCONNECT_MISSION_SUCCEEDED
};

Members

SIMCONNECT_MISSION_FAILED
  Specifies that the user did not complete the mission successfully

.
SIMCONNECT_MISSION_CRASHED
  Specifies that the user aircraft crashed during the mission.


SIMCONNECT_MISSION_SUCCEEDED
  Specifies that the user completed the mission successfully.

Reference Sample

 

Primary sample Mission Action

Remarks

Refer to the mission events that can be requested by the SimConnect_SubscribeToSystemEvent function. Also see the remarks for SimConnect_CompleteCustomMissionAction.

See Also




SIMCONNECT_RECV

The SIMCONNECT_RECV structure is used with the SIMCONNECT_RECV_ID enumeration to indicate which type of structure has been returned. 

Syntax

struct SIMCONNECT_RECV{
  DWORD  dwSize;
  DWORD  dwVersion;
  DWORD  dwID;
};

Members

dwSize
   The total size of the returned structure in bytes (that is, not usually the size of the SIMCONNECT_RECV structure, but of the structure that inherits it).
dwVersion
   The version number of the SimConnect server.
dwID
   The ID of the returned structure. One member of SIMCONNECT_RECV_ID.

Reference Samples

 

Primary samples

Client Event

No Callback

Tracking Errors

Reference samples All but a few of the other samples implement this structure.

Remarks

This structure is inherited directly by:

The structure is also inherited by SIMCONNECT_RECV_QUIT, which does not add any new members. This structure is received when the user quits Flight Sim World.

 

This structure is inherited by the SIMCONNECT_RECV_EVENT structure, which is inherited by several other structures:

See Also




SIMCONNECT_RECV_AIRPORT_LIST

The SIMCONNECT_RECV_AIRPORT_LIST structure is used to return a list of SIMCONNECT_DATA_FACILITY_AIRPORT structures.

Syntax

struct SIMCONNECT_RECV_AIRPORT_LIST : public SIMCONNECT_RECV_FACILITIES_LIST{
  SIMCONNECT_DATA_FACILITY_AIRPORT  rgData[1];
};

Members

rgData[1]
  Array of SIMCONNECT_DATA_FACILITY_AIRPORT structures.

Remarks

This structure inherits the SIMCONNECT_RECV_FACILITIES_LIST structure, which identifies the number of elements in the list, and the number of packets needed to transmit all the data.

 

See the remarks for SimConnect_RequestFacilitiesList.

See Also




SIMCONNECT_RECV_AUDIO_RESPONSE

The SIMCONNECT_RECV_AUDIO_RESPONSE structure is used to return audio data.

Syntax

struct SIMCONNECT_RECV_AUDIO_RESPONSE : public SIMCONNECT_RECV{
  DWORD  dwRequestID;
  float  val;
};

Members

dwRequestID
  Double word containing the client defined request ID.

val
  Requested value.

Remarks

None.

See Also




SIMCONNECT_RECV_ASSIGNED_OBJECT_ID

The SIMCONNECT_RECV_ASSIGNED_OBJECT_ID structure is used to return an object ID that matches a request ID.

Syntax

struct SIMCONNECT_RECV_ASSIGNED_OBJECT_ID : public SIMCONNECT_RECV {
  DWORD  dwRequestID;
  DWORD  dwObjectID;
};

Members

dwRequestID
  Double word containing the client defined request ID.
dwObjectID
  Double word containing the server defined object ID.

Reference Samples

 

Primary samples

AI Objects and Waypoints

AI Traffic


Managed AI Waypoints

Remarks

This structure inherits the SIMCONNECT_RECV structure and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_ASSIGNED_OBJECT_ID.

See Also




SIMCONNECT_RECV_CLIENT_DATA

The SIMCONNECT_RECV_CLIENT_DATA structure will be received by the client after a successful call to SimConnect_RequestClientData. It is an identical structure to SIMCONNECT_RECV_SIMOBJECT_DATA.

Syntax

struct SIMCONNECT_RECV_CLIENT_DATA : public SIMCONNECT_RECV_SIMBOBJECT_DATA{
};

Remarks

This structure inherits the SIMCONNECT_RECV_SIMOBJECT_DATA structure and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_CLIENT_DATA.

See Also




SIMCONNECT_RECV_CAMERA_VIEW

The SIMCONNECT_RECV_CAMERA_VIEW structure is used to return an object ID that matches a request ID.

Syntax

struct SIMCONNECT_RECV_CAMERA_VIEW : public SIMCONNECT_RECV {
  DWORD  dwRequestID;
  SIMCONNECT_DATA_CAMERA_VIEW  dView;
};

Members

dwRequestID
  Double word containing the client defined request ID.
dView
  View data for the current camera, see SIMCONNECT_DATA_CAMERA_VIEW.

Remarks

This structure inherits the SIMCONNECT_RECV structure and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_CAMERA_DATA

See Also




SIMCONNECT_RECV_CLOUD_STATE

The SIMCONNECT_RECV_CLOUD_STATE structure is used to return an array of cloud state data.

Syntax

struct SIMCONNECT_RECV_CLOUD_STATE : public SIMCONNECT_RECV {
  DWORD  dwRequestID;
  DWORD  dwArraySize;
  BYTE  rgbData[1];
};

Members

dwRequestID
  Double word containing the client defined request ID.
dwArraySize
  Double word starting the cloud data array. The array will be 64 x 64 bytes in size, and each byte will contain a value indicating the cloud density for each cell. A value of zero would mean no clouds, to a maximum of 255. The size of each cell is determined by a call to SimConnect_WeatherRequestCloudState.
rgbData[1]
  Byte array containing the cloud data.

Remarks

This structure inherits the SIMCONNECT_RECV structure and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_CLOUD_STATE.

See Also




SIMCONNECT_RECV_CUSTOM_ACTION

The SIMCONNECT_RECV_CUSTOM_ACTION structure is used specifically with the mission system, providing details on the custom action that has been triggered.

Syntax

struct SIMCONNECT_RECV_CUSTOM_ACTION : public SIMCONNECT_RECV_EVENT {
  GUID  guidInstanceId;
  DWORD  dwWaitForCompletion;
  char  szPayLoad[1];
};

Members

guidInstanceId
   GUID of the action that executed.
dwWaitForCompletion
   The value of the Wait-for-completion flag on the action.
szPayLoad
   A variable length string that is defined in the mission xml file. It is specified by the mission designer and can contain anything that the client might find useful.

Reference Sample

 

Primary sample Mission Action

Remarks

This structure inherits the SIMCONNECT_RECV_EVENT structure, which inherits the SIMCONNECT_RECV structure, and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_CUSTOM_ACTION.

 

See the remarks for SimConnect_CompleteCustomMissionAction.

See Also




SIMCONNECT_RECV_EVENT

The SIMCONNECT_RECV_EVENT structure is used to return an event ID to the client.

Syntax

struct SIMCONNECT_RECV_EVENT : public SIMCONNECT_RECV {
  DWORD  uGroupID;
  DWORD  uEventID;
  DWORD  dwData;
};

Members

uGroupID
  The ID of the client defined group, or the special case value: UNKNOWN_GROUP (which equals DWORD_MAX).
uEventID
  The ID of the client defined event that has been requested (such as EVENT_1 or EVENT_BRAKES from the examples in this document).
dwData
   This value is usually zero, but some events require further qualification. For example, joystick movement events require a movement value in addition to the notification that the joystick has been moved (see SimConnect_MapInputEventToClientEvent for more information).

Reference Samples

 

Primary samples

Client Event

Cockpit Camera

Input Event

Joystick Input

Menu Items

No Callback

Send Event A

Send Event B

Send Event C

Throttle Control

Tracking Errors

Reference samples All but a few of the other samples implement this structure.

Remarks

This structure inherits the SIMCONNECT_RECV structure and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_EVENT. This structure is inherited by several other structures:

See Also




SIMCONNECT_RECV_EVENT_FILENAME

The SIMCONNECT_RECV_EVENT_FILENAME structure is used to return a filename and an event ID to the client.

Syntax

struct SIMCONNECT_RECV_EVENT_FILENAME : public SIMCONNECT_RECV_EVENT {
  char  szFileName[MAX_PATH];
  DWORD  dwFlags;
};

Members

szFileName[MAX_PATH]
  The returned filename.
dwFlags
  Reserved, should be 0.

Reference Sample

 

Primary sample

System Event

Remarks

This structure inherits the SIMCONNECT_RECV_EVENT structure, and is used to attach a filename to the returned event.

When the SIMCONNECT_RECV structure dwID parameter is set to SIMCONNECT_RECV_EVENT_FILENAME, this structure is returned.

See Also




SIMCONNECT_RECV_EVENT_FRAME

The SIMCONNECT_RECV_EVENT_FRAME structure is used with the SimConnect_SubscribeToSystemEvent call to return the frame rate and simulation speed to the client.

Syntax

struct SIMCONNECT_RECV_EVENT_FRAME : public SIMCONNECT_RECV_EVENT {
  float  fFrameRate;
  float  fSimSpeed;
};

Members

fFrameRate
  The visual frame rate in frames per second.

fSimSpeed
  The simulation rate. For example if the simulation is running at four times normal speed - 4X - then 4.0 will be returned.

Remarks

This structure inherits the SIMCONNECT_RECV_EVENT structure, which inherits the SIMCONNECT_RECV structure, and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_EVENT_FRAME. Set the requested system event to "Frame" or "PauseFrame" with the SimConnect_SubscribeToSystemEvent function to receive this data.

See Also



SIMCONNECT_RECV_EVENT_MULTIPLAYER_CLIENT_STARTED

The SIMCONNECT_RECV_EVENT_MULTIPLAYER_CLIENT_STARTED structure is sent to a client when they have successfully joined a multi-player race.

Syntax

struct SIMCONNECT_RECV_EVENT_MULTIPLAYER_CLIENT_STARTED : public SIMCONNECT_RECV_EVENT {};

Members

This structure takes no parameters in addition to those inherited from the SIMCONNECT_RECV_EVENT structure.

Remarks

This event is not transmitted to the host of the session, only to the client that has joined in.

 

To receive these events, refer to the SimConnect_SubscribeToSystemEvent function.

See Also




SIMCONNECT_RECV_EVENT_MULTIPLAYER_SERVER_STARTED

The SIMCONNECT_RECV_EVENT_MULTIPLAYER_SERVER_STARTED structure is sent to the host when the session is visible to other users in the lobby.

Syntax

struct SIMCONNECT_RECV_EVENT_MULTIPLAYER_SERVER_STARTED : public SIMCONNECT_RECV_EVENT {};

Members

This structure takes no parameters in addition to those inherited from the SIMCONNECT_RECV_EVENT structure.

Remarks

This event is sent only to the host of the session.

See Also




SIMCONNECT_RECV_EVENT_MULTIPLAYER_SESSION_ENDED

The SIMCONNECT_RECV_EVENT_MULTIPLAYER_SESSION_ENDED structure 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.

Syntax

struct SIMCONNECT_RECV_EVENT_MULTIPLAYER_SESSION_ENDED : public SIMCONNECT_RECV_EVENT {};

Members

This structure takes no parameters in addition to those inherited from the SIMCONNECT_RECV_EVENT structure.

Remarks

This is the only event that is broadcast to all the players in a multi-player race, in the situation where the host terminates, or simply leaves, the race. If a client ends their own participation in the race, they will be the only one to receive the event.

See Also




SIMCONNECT_RECV_EVENT_OBJECT_ADDREMOVE

The SIMCONNECT_RECV_EVENT_OBJECT_ADDREMOVE structure is used to return the type and ID of an AI object that has been added or removed from the simulation, by any client.

Syntax

struct SIMCONNECT_RECV_EVENT_OBJECT_ADDREMOVE : public SIMCONNECT_RECV_EVENT {
  SIMCONNECT_SIMOBJECT_TYPE  eObjType;
};

Members

eObjType
  Specifies the type of object that was added or removed. One member of the SIMCONNECT_SIMOBJECT_TYPE enumeration.

Reference Sample

 

Primary sample

AI Traffic

Remarks

This structure inherits the SIMCONNECT_RECV_EVENT structure, which inherits the SIMCONNECT_RECV structure, and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_EVENT_ADDREMOVE. A client can determine whether the object was added or removed from its own event ID that was provided as a parameter to the SimConnect_SubscribeToSystemEvent function.

 

The ID of the object added or removed is returned in the dwData parameter (a member of the SIMCONNECT_RECV_EVENT structure).

See Also




SIMCONNECT_RECV_EVENT_RACE_END

The SIMCONNECT_RECV_EVENT_RACE_END structure is used in multi-player racing to hold the results for one player at the end of a race.

Syntax

struct SIMCONNECT_RECV_EVENT_RACE_END : public SIMCONNECT_RECV_EVENT {
  DWORD  dwRacerNumber;
  SIMCONNECT_DATA_RACE_RESULT  RacerData;
};

Members

dwRacerNumber
   The index of the racer the results are for. Players are indexed from 0.
RacerData
  A SIMCONNECT_DATA_RACE_RESULT structure.

Remarks

In a multi-player race players can come and go, so index numbers are not a reliable means of identifiying the players. The szPlayerName and szPlayerRole parameters of the SIMCONNECT_DATA_RACE_RESULT structure should be used to identify each player.

See Also




SIMCONNECT_RECV_EVENT_RACE_LAP

The SIMCONNECT_RECV_EVENT_RACE_LAP structure is used in multi-player racing to hold the results for one player at the end of a lap.

Syntax

struct SIMCONNECT_RECV_EVENT_RACE_LAP : public SIMCONNECT_RECV_EVENT {
  DWORD  dwLapIndex;
  SIMCONNECT_DATA_RACE_RESULT  RacerData;
};

Members

dwLapIndex
   The index of the lap the results are for. Laps are indexed from 0.
RacerData
  A SIMCONNECT_DATA_RACE_RESULT structure.

Remarks

None.

See Also




SIMCONNECT_RECV_EXCEPTION

The SIMCONNECT_RECV_EXCEPTION structure is used with the SIMCONNECT_EXCEPTION enumeration type to return information on an error that has occurred.

Syntax

struct SIMCONNECT_RECV_EXCEPTION : public SIMCONNECT_RECV {
  DWORD  dwException;
  DWORD  dwSendID;
  DWORD  dwIndex;
};

Members

dwException
   One member of the SIMCONNECT_EXCEPTION enumeration type, indicating which error has occurred.
dwSendID
   The ID of the packet that contained the error, see Remarks below.
dwIndex
  The index number (starting at 1) of the first parameter that caused an error. Special case: UNKNOWN_INDEX = 0.

Reference Samples

 

Primary samples

Cockpit Camera

Tracking Errors

Variable Strings

Remarks

This structure inherits the SIMCONNECT_RECV structure and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_EXCEPTION.

In order to match the dwSendID parameter returned here, with the ID of a request, use the SimConnect_GetLastSentPacketID call after each request is made.

Note that the HRESULT errors returned after each API call do not involve any communication with the SimConnect server, but are simply client-side errors that are returned immediately. Test for exceptions to check for server-side errors.

See Also




SIMCONNECT_RECV_FACILITIES_LIST

The SIMCONNECT_RECV_FACILITIES_LIST structure is 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.

Syntax

struct SIMCONNECT_RECV_FACILITIES_LIST : public SIMCONNECT_RECV{
  DWORD  dwRequestID;
  DWORD  dwArraySize;
  DWORD  dwREntry;
  DWORD  dwOutOf;
};

Members

dwRequestID
  Double word containing the client defined request ID.
dwArraySize
  Double word containing the number of elements in the list that are within this packet. For example, if there are 25 airports returned in the SIMCONNECT_RECV_AIRPORT_LIST structure, then this field will contain 25, but if there are 400 airports in the list and the data is returned in two packets, then this value will contain the number of entries within each packet.
dwEntry
  Double word containing the index number of this list packet. This number will be from 0 to dwOutOf - 1.
dwOutOf
  Double word containing the total number of packets used to transmit the list.

Remarks

This structure is inherited by SIMCONNECT_RECV_AIRPORT_LIST, SIMCONNECT_RECV_NDB_LIST, SIMCONNECT_RECV_VOR_LIST and SIMCONNECT_RECV_WAYPOINT_LIST.

 

This structure inherits the SIMCONNECT_RECV structure, so use the SIMCONNECT_RECV_ID enumeration to determine which list structure has been received.

 

See the remarks for SimConnect_RequestFacilitiesList.

See Also



SIMCONNECT_RECV_ID

The SIMCONNECT_RECV_ID enumeration type is used within the SIMCONNECT_RECV structure to indicate which type of structure has been returned.

Syntax

enum SIMCONNECT_RECV_ID{
  SIMCONNECT_RECV_ID_NULL,
  SIMCONNECT_RECV_ID_EXCEPTION,
  SIMCONNECT_RECV_ID_OPEN,
  SIMCONNECT_RECV_ID_QUIT,
  SIMCONNECT_RECV_ID_EVENT,
  SIMCONNECT_RECV_ID_EVENT_OBJECT_ADDREMOVE,
  SIMCONNECT_RECV_ID_EVENT_FILENAME,
  SIMCONNECT_RECV_ID_EVENT_FRAME,
  SIMCONNECT_RECV_ID_SIMOBJECT_DATA,
  SIMCONNECT_RECV_ID_SIMOBJECT_DATA_BYTYPE,
  SIMCONNECT_RECV_ID_CLOUD_STATE,
  SIMCONNECT_RECV_ID_WEATHER_OBSERVATION,
  SIMCONNECT_RECV_ID_ASSIGNED_OJBECT_ID,
  SIMCONNECT_RECV_ID_RESERVED_KEY,
  SIMCONNECT_RECV_ID_CUSTOM_ACTION,
  SIMCONNECT_RECV_ID_SYSTEM_STATE,
  SIMCONNECT_RECV_ID_CLIENT_DATA,
  SIMCONNECT_RECV_ID_EVENT_WEATHER_MODE,
  SIMCONNECT_RECV_ID_AIRPORT_LIST,
  SIMCONNECT_RECV_ID_VOR_LIST,
  SIMCONNECT_RECV_ID_NDB_LIST,
  SIMCONNECT_RECV_ID_WAYPOINT_LIST,
  SIMCONNECT_RECV_ID_EVENT_MULTIPLAYER_SERVER_STARTED,
  SIMCONNECT_RECV_ID_EVENT_MULTIPLAYER_CLIENT_STARTED,
  SIMCONNECT_RECV_ID_EVENT_MULTIPLAYER_SESSION_ENDED,
  SIMCONNECT_RECV_ID_EVENT_RACE_END,
  SIMCONNECT_RECV_ID_EVENT_RACE_LAP
};

Members

SIMCONNECT_RECV_ID_NULL
  Specifies that nothing useful has been returned.


SIMCONNECT_RECV_ID_EXCEPTION
  Specifies that a SIMCONNECT_RECV_EXCEPTION structure has been received.


SIMCONNECT_RECV_ID_OPEN
  Specifies that a SIMCONNECT_RECV_OPEN structure has been received.


SIMCONNECT_RECV_ID_QUIT
  Specifies that the user has exited from Flight Sim World.


SIMCONNECT_RECV_ID_EVENT
  Specifies that a SIMCONNECT_RECV_EVENT structure has been received.


SIMCONNECT_RECV_ID_EVENT_OBJECT_ADDREMOVE
  Specifies that a SIMCONNECT_RECV_EVENT_OBJECT_ADDREMOVE structure has been received.


SIMCONNECT_RECV_ID_EVENT_FILENAME
  Specifies that a  SIMCONNECT_RECV_EVENT_FILENAME structure has been received.


SIMCONNECT_RECV_ID_EVENT_FRAME
  Specifies that a  SIMCONNECT_RECV_EVENT_FRAME structure has been received.


SIMCONNECT_RECV_ID_SIMOBJECT_DATA
  Specifies that a SIMCONNECT_RECV_SIMOBJECT_DATA structure has been received.


SIMCONNECT_RECV_ID_SIMOBJECT_DATA_BYTYPE
  Specifies that a SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE structure has been received.


SIMCONNECT_RECV_ID_WEATHER_OBSERVATION
  Specifies that a SIMCONNECT_RECV_WEATHER_OBSERVATION structure has been received.

 

SIMCONNECT_RECV_ID_CLOUD_STATE
  Specifies that a SIMCONNECT_RECV_CLOUD_STATE structure has been received.

 

SIMCONNECT_RECV_ID_ASSIGNED_OJBECT_ID
  Specifies that a SIMCONNECT_RECV_ASSIGNED_OBJECT_ID structure has been received.


SIMCONNECT_RECV_ID_RESERVED_KEY
  Specifies that a SIMCONNECT_RECV_RESERVED_KEY structure has been received.


SIMCONNECT_RECV_ID_CUSTOM_ACTION
  Specifies that a SIMCONNECT_RECV_CUSTOM_ACTION structure has been received.


SIMCONNECT_RECV_ID_SYSTEM_STATE
  Specifies that a SIMCONNECT_RECV_SYSTEM_STATE structure has been received.


SIMCONNECT_RECV_ID_CLIENT_DATA
  Specifies that a SIMCONNECT_RECV_CLIENT_DATA structure has been received.


SIMCONNECT_RECV_ID_CLIENT_DATA
  Specifies that the dwData parameter will contain one value of the SIMCONNECT_WEATHER_MODE enumeration.


SIMCONNECT_RECV_ID_AIRPORT_LIST
  Specifies that a SIMCONNECT_RECV_AIRPORT_LIST structure has been received.


SIMCONNECT_RECV_ID_VOR_LIST
  Specifies that a SIMCONNECT_RECV_VOR_LIST structure has been received.


SIMCONNECT_RECV_ID_NDB_LIST
  Specifies that a SIMCONNECT_RECV_NDB_LIST structure has been received.


SIMCONNECT_RECV_ID_WAYPOINT_LIST
  Specifies that a SIMCONNECT_RECV_WAYPOINT_LIST structure has been received.

 

SIMCONNECT_RECV_ID_EVENT_MULTIPLAYER_SERVER_STARTED
  Specifies that a SIMCONNECT_RECV_EVENT_MULTIPLAYER_SERVER_STARTED structrure has been received.

SIMCONNECT_RECV_ID_EVENT_MULTIPLAYER_CLIENT_STARTED
  Specifies that a SIMCONNECT_RECV_EVENT_MULTIPLAYER_CLIENT_STARTED structure has been received.

SIMCONNECT_RECV_ID_EVENT_MULTIPLAYER_SESSION_ENDED
  Specifies that a SIMCONNECT_RECV_EVENT_MULTIPLAYER_SESSION_ENDED structure has been received.

SIMCONNECT_RECV_ID_EVENT_RACE_END
  Specifies that a SIMCONNECT_RECV_EVENT_RACE_END structure has been received.

SIMCONNECT_RECV_ID_EVENT_RACE_LAP
  Specifies that a SIMCONNECT_RECV_EVENT_RACE_LAP structure has been received.


Reference Samples

 

Primary samples

Client Event

No Callback

Tracking Errors

Reference samples All but a few of the other samples implement this enumeration.

Remarks

Typically a DispatchProc or SimConnect_GetNextDispatch implementation of a client will include a case statement for each of the above members that the client might receive.

See Also




SIMCONNECT_RECV_OBJECT_AT_POINT

The SIMCONNECT_RECV_OBJECT_AT_POINT structure is used to return the location and type of scenery under an X/Y location in the window.

Syntax

struct SIMCONNECT_RECV_OBJECT_AT_POINT : public SIMCONNECT_RECV {
  DWORD  dwRequestID;
  DWORD  dwObjectID;
  SIMCONNECT_DETECT_TYPE  DetectType;
  double  Latitude;
  double  Longitude;
  double  Altitude;
  double  AltitudeAGL;
  double  Pitch;
  double  Bank;
  double  Heading;
};

Members

dwRequestID
  Double word containing the client defined request ID.
dwObjectID
  Client-defined Object ID for the scenery object, if any.
DetectType
  Enumerated value describing whether the point given collided with an object, the ground or nothing using SIMCONNECT_DETECTED_OBJECT, SIMCONNECT_DETECTED_TERRAIN or SIMCONNECT_DETECTED_NONE.
Latitude
  Latitude of the terrain or object under the point given.
Longitude
  Longitude of the terrain or object under the point given.
Altitude
  Altitude of the terrain or object under the point given.
AltitudeAGL
  Altitude above ground level of the object's center point. For terrain, this will always be 0.
Pitch
  Pitch of the object under the point given. For terrain, this will always be 0.
Bank
  Bank of the object under the point given. For terrain, this will always be 0.
Heading
  Heading of the object under the point given. For terrain, this will always be 0.

Remarks

This structure inherits the SIMCONNECT_RECV structure and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_LOCATION_DATA.

See Also




SIMCONNECT_RECV_NDB_LIST

The SIMCONNECT_RECV_NDB_LIST structure is used to return a list of SIMCONNECT_DATA_FACILITY_NDB structures.

Syntax

struct SIMCONNECT_RECV_NDB_LIST : public SIMCONNECT_RECV_FACILITES_LIST{
  SIMCONNECT_DATA_FACILITY_NDB  rgData[1];
};

Members

rgData[1]
  Array of SIMCONNECT_DATA_FACILITY_NDB structures.

Remarks

This structure inherits the SIMCONNECT_RECV_FACILITIES_LIST structure, which identifies the number of elements in the list, and the number of packets needed to transmit all the data.

 

See the remarks for SimConnect_RequestFacilitiesList.

See Also



SIMCONNECT_RECV_SIMOBJECT_DATA

The SIMCONNECT_RECV_SIMOBJECT_DATA structure will be received by the client after a successful call to SimConnect_RequestDataOnSimObject or SimConnect_RequestDataOnSimObjectType.

Syntax

struct SIMCONNECT_RECV_SIMOBJECT_DATA : public SIMCONNECT_RECV {
  DWORD  dwRequestID;
  DWORD  dwObjectID;
  DWORD  dwDefineID;
  DWORD  dwFlags;

  DWORD  dwentrynumber;
  DWORD  dwoutof;
  DWORD  dwDefineCount;
  DWORD  dwData;
};

Members

dwRequestID
  The ID of the client defined request.
dwDefineID
  The ID of the client defined data definition.
dwFlags
  The flags that were set for this data request, see SimConnect_RequestDataOnSimObject for a description of the flags. This parameter will always be set to zero if the call was SimConnect_RequestDataOnSimObjectType.

dwentrynumber
   If multiple objects are being returned, this is the index number of this object out of a total of dwoutof. This will always be 1 if the call was SimConnect_RequestDataOnSimObject, and can be 0 or more if the call was SimConnect_RequestDataOnSimObjectType.
dwoutof
   The total number of objects being returned. Note that dwentrynumber and dwoutof start with 1 not 0, so if two objects are being  returned dwentrynumber and dwoutof pairs will be 1,2 and 2,2 for the two objects. This will always be 1 if the call was SimConnect_RequestDataOnSimObject, and can be 0 or more if the call was SimConnect_RequestDataOnSimObjectType.
dwDefineCount
   The number of 8-byte elements in the dwData array.
dwData
   A data array containing information on a specified object in 8-byte (double word) elements. The length of the array is dwDefineCount.

Reference Samples

 

Primary samples

Request Data

Set Data

Tagged Data

Throttle Control

Variable Strings

Remarks

This structure inherits the SIMCONNECT_RECV structure and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_SIMOBJECT_DATA.

See Also




SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE

The SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE structure will be received by the client after a successful call to SimConnect_RequestDataOnSimObjectType. It is an identical structure to SIMCONNECT_RECV_SIMOBJECT_DATA.

Syntax

struct SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE : public SIMCONNECT_RECV_SIMBOBJECT_DATA{
};

Remarks

This structure inherits the SIMCONNECT_RECV_SIMOBJECT_DATA structure and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_SIMOBJECT_DATA_BYTYPE.

See Also




SIMCONNECT_RECV_OPEN

The SIMCONNECT_RECV_OPEN structure is used to return information to the client, after a successful call to SimConnect_Open.

Syntax

struct SIMCONNECT_RECV_OPEN : public SIMCONNECT_RECV {
  char  szApplicationName[256];
  DWORD  dwApplicationVersionMajor;
  DWORD  dwApplicationVersionMinor;
  DWORD  dwApplicationBuildMajor;
  DWORD  dwApplicationBuildMinor;
  DWORD  dwSimConnectVersionMajor;
  DWORD  dwSimConnectVersionMinor;
  DWORD  dwSimConnectBuildMajor;
  DWORD  dwSimConnectBuildMinor;
  DWORD  dwReserved1;
  DWORD  dwReserved2;
};

Members

szApplicationName[256]
  Null-terminated string containing the application name.
dwApplicationVersionMajor
  Double word containing the application version major number.
dwApplicationVersionMinor
  Double word containing the application version minor number.
dwApplicationBuildMajor
  Double word containing the application build major number.
dwApplicationBuildMinor
  Double word containing the application build minor number.
dwSimConnectVersionMajor
  Double word containing the SimConnect version major number.
dwSimConnectVersionMinor
  Double word containing the SimConnect version minor number.
dwSimConnectBuildMajor
  Double word containing the SimConnect build major number.
dwSimConnectBuildMinor
  Double word containing the SimConnect build minor number.
dwReserved1
  Reserved.
dwReserved2
  Reserved.

Remarks

This structure inherits the SIMCONNECT_RECV structure and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_OPEN.

See Also




SIMCONNECT_RECV_RESERVED_KEY

The SIMCONNECT_RECV_RESERVED_KEY structure is used with the SimConnect_RequestReservedKey function to return the reserved key combination.

Syntax

struct SIMCONNECT_RECV_RESERVED_KEY : public SIMCONNECT_RECV {
  char  szChoiceReserved[30];
  char  szReservedKey[50];
};

Members

szChoiceReserved[30]
  Null-terminated string containing the key that has been reserved. This will be identical to the string entered as one of the choices for the SimConnect_RequestReservedKey function.
szReservedKey[50]
  Null-terminated string containing the reserved key combination. This will be an uppercase string containing all the modifiers that apply. For example, if the client program requests "q", and the choice is accepted, then this parameter will contain "TAB+Q". If the client program requests "Q", then this parameter will contain "SHIFT+TAB+Q". This string could then appear, for example, in a dialog from the client application, informing a user of the appropriate help key.

Reference Sample

 

Primary sample

Reserved Key

Remarks

This structure inherits the SIMCONNECT_RECV structure and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_RESERVED_KEY.

See Also




SIMCONNECT_RECV_SYSTEM_STATE


The SIMCONNECT_RECV_SYSTEM_STATE structure is used with the SimConnect_RequestSystemState function to retrieve specific Flight Sim World systems states and information.

Syntax

typedef struct SIMCONNECT_RECV_SYSTEM_STATE : public SIMCONNECT_RECV {
  DWORD  dwRequestID;
  DWORD  dwInteger;
  float  fFloat;
  char   szString[MAX_PATH];
};


Members

dwRequestID
  Double word containing the client defined request ID.
dwInteger
  Double word containing an integer, or boolean, value.
fFloat
  A float value.
szString
  Null-terminated string.

Remarks

This structure inherits the SIMCONNECT_RECV structure and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_SYSTEM_STATE.

 

Typically only one of the received integer, float or string will contain information, which one will depend on the request and can be identified by the request ID. Refer to the descriptions of the SimConnect_SetSystemState and SimConnect_RequestSystemState functions.

See Also




SIMCONNECT_RECV_VOR_LIST

The SIMCONNECT_RECV_VOR_LIST structure is used to return a list of SIMCONNECT_DATA_FACILITY_VOR structures.

Syntax

struct SIMCONNECT_RECV_VOR_LIST : public SIMCONNECT_RECV_FACILITIES_LIST{
  SIMCONNECT_DATA_FACILITY_VOR  rgData[1];
};

Members

rgData[1]
  Array of SIMCONNECT_DATA_FACILITY_VOR structures.

Remarks

This structure inherits the SIMCONNECT_RECV_FACILITIES_LIST structure, which identifies the number of elements in the list, and the number of packets needed to transmit all the data.

 

See the remarks for SimConnect_RequestFacilitiesList.

See Also



SIMCONNECT_RECV_WAYPOINT_LIST

The SIMCONNECT_RECV_WAYPOINT_LIST structure is used to return a list of SIMCONNECT_DATA_FACILITY_WAYPOINT structures.

Syntax

struct SIMCONNECT_RECV_WAYPOINT_LIST : public SIMCONNECT_RECV_FACILITIES_LIST{
  SIMCONNECT_DATA_FACILITY_WAYPOINT  rgData[1];
};

Members

rgData[1]
  Array of SIMCONNECT_DATA_FACILITY_WAYPOINT structures.

Remarks

This structure inherits the SIMCONNECT_RECV_FACILITIES_LIST structure, which identifies the number of elements in the list, and the number of packets needed to transmit all the data.

 

See the remarks for SimConnect_RequestFacilitiesList.

See Also



SIMCONNECT_RECV_WEATHER_OBSERVATION

The SIMCONNECT_RECV_WEATHER_OBSERVATION structure is used to return weather observation data, after calls to one of: SimConnect_WeatherRequestInterpolatedObservation, SimConnect_WeatherRequestObservationAtStation, or SimConnect_WeatherRequestObservationAtNearestStation

Syntax

struct SIMCONNECT_RECV_WEATHER_OBSERVATION : public SIMCONNECT_RECV {
  DWORD  dwRequestID;
  char  szMETAR[1];
};

Members

dwRequestID
  The ID of the client defined request.
szMETAR[1]
  Null-terminated string containing the Metar weather data. The maximum length of this string is 2000 chars. See the section Metar Data Format for details on the format required.

Reference Sample

 

Primary sample Weather Station

Remarks

This structure inherits the SIMCONNECT_RECV structure and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_WEATHER_OBSERVATION.

See Also




SIMCONNECT_SIMOBJECT_TYPE

The SIMCONNECT_SIMOBJECT_TYPE enumeration type is used with the SimConnect_RequestDataOnSimObjectType call to request information on specific or nearby objects.

Syntax

enum SIMCONNECT_SIMOBJECT_TYPE{
  SIMCONNECT_SIMOBJECT_TYPE_USER,
  SIMCONNECT_SIMOBJECT_TYPE_ALL_CRAFT,
  SIMCONNECT_SIMOBJECT_TYPE_AIRCRAFT,
  SIMCONNECT_SIMOBJECT_TYPE_HELICOPTER,
  SIMCONNECT_SIMOBJECT_TYPE_BOAT,
  SIMCONNECT_SIMOBJECT_TYPE_GROUND,
  SIMCONNECT_SIMOBJECT_TYPE_MISSION
};

Members

SIMCONNECT_SIMOBJECT_TYPE_USER
  Specifies the user's aircraft.


SIMCONNECT_SIMOBJECT_TYPE_ALL_CRAFT
  Specifies all AI controlled objects. The older definition of SIMCONNECT_SIMOBJECT_TYPE_ALL still exists for compatibility.


SIMCONNECT_SIMOBJECT_TYPE_AIRCRAFT
  Specifies all aircraft.


SIMCONNECT_SIMOBJECT_TYPE_HELICOPTER
  Specifies all helicopters.


SIMCONNECT_SIMOBJECT_TYPE_BOAT
  Specifies all AI controlled boats.


SIMCONNECT_SIMOBJECT_TYPE_GROUND
  Specifies all AI controlled ground vehicles.


SIMCONNECT_SIMOBJECT_TYPE_MISSION
  Specifies all Mission System objects i.e. Actions, Triggers, Goals.

Reference Samples

 

Primary samples

Request Data

 

Reference samples

Set Data

Tagged Data

Throttle Control

 

Remarks

This enum is used to specify the return of the object IDs of all objects created using the AI creation functions, whether they are created by this client, other clients, or Flight Sim World itself. It can also be used to specify the return the object ID of the user aircraft. However it cannot be used to specify the IDs of objects like cars moving on freeways, which are not controlled by the AI component.

 

See the remarks and examples for  SimConnect_AddToDataDefinition.

See Also




SIMCONNECT_STATE

The SIMCONNECT_STATE enumeration type is used with the SimConnect_SetSystemEventState call to turn the reporting of events on and off.

Syntax

enum SIMCONNECT_STATE{
  SIMCONNECT_STATE_OFF,
  SIMCONNECT_STATE_ON
};

Members

SIMCONNECT_STATE_OFF
  Specifies off.


SIMCONNECT_STATE_ON
  Specifies on.

Reference Samples

 

Primary samples

Cockpit Camera

Input Event

Joystick Input

Throttle Control

Reference samples Set Data

 

Remarks

See the remarks for SimConnect_MapInputEventToClientEvent.

See Also




SIMCONNECT_DATA_INITPOSITION

The SIMCONNECT_DATA_INITPOSITION structure is used to initialize the position of the user aircraft, AI controlled aircraft, or other simulation object.

Syntax

struct SIMCONNECT_DATA_INITPOSITION{
  double  Latitude;
  double  Longitude;
  double  Altitude;
  double  Pitch;
  double  Bank;
  double  Heading;
  DWORD  OnGround;
  DWORD  Airspeed;
};

Members

Latitude
   Latitude in degrees.
Longitude
   Longitude in degrees.
Altitude
   Altitude in feet.
Pitch
   Pitch in degrees.
Bank
   Bank in degrees.
Heading
   Heading in degrees.
OnGround
   Set this to 1 to place the object on the ground, or 0 if the object is to be airborne.
Airspeed
  The airspeed in knots, or one of the following special values:

 

Define Value Description
INITPOSITION_AIRSPEED_CRUISE -1 The aircraft's design cruising speed.
INITPOSITION_AIRSPEED_KEEP -2 Maintain the current airspeed.

 

Reference Samples

 

Primary samples

AI Objects and Waypoints

Set Data


Managed AI Waypoints

Remarks

The primary use of this structure is to initialize the positioning of the user aircraft, because it also optimizes some of the terrain systems and other Flight Sim World systems. Simply setting parameters such as latitude, longitude and altitude does not perform this kind of optimization. This structure should not be used to incrementally move the user aircraft (as this will unnecessarily initiate the reloading of scenery), in this case change the latitude, longitude, altitude and other parameters of the aircraft appropriately (using the variables described in the Simulation Variables document).

 

This structure can be used to incrementally move or reposition an AI controlled aircraft, or any other aircraft not controlled by the user, as the terrain system optimizations are not performed in this case.

 

This structure is used by the functions: SimConnect_AICreateNonATCAircraft, SimConnect_AICreateSimulatedObject and SimConnect_AddToDataDefinition.

 

This structure can only be used to set data, it cannot be used as part of a data request.

See Also




SIMCONNECT_DATA_LATLONALT

The SIMCONNECT_DATA_LATLONALT structure is used to hold a world position.

Syntax

struct SIMCONNECT_DATA_LATLONALT{
  double  Latitude;
  double  Longitude;
  double  Altitude;
};

Members

Latitude
   The latitude of the position in degrees.
Longitude
   The longitude of the position in degrees.
Altitude
   The altitude of the position in feet.

Remarks

This structure is used when one of the following simulation variables is requested (with a call to SimConnect_RequestDataOnSimObject):

  • ADF LATLONALT
  • NAV DME LATLONALT
  • NAV GS LATLONALT
  • NAV VOR LATLONALT
  • INNER MARKER LATLONALT
  • MIDDLE MARKER LATLONALT
  • OUTER MARKER LATLONALT

See Also