Overview
The SimConnect SDK can be used by programmers to write add-on components for Prepar3D. Add-on components for Prepar3D can be written in C, C++, or, if the managed API calls are being used, any .NET language such as C#.net or VB.net. Typically the components will perform one or more of the following:
- Add the processing for a new complex gauge, or other instrument, to Prepar3D.
- Replace Prepar3D processing of one or more events with new logic.
- Record or monitor a scenario.
- Extend the scenario system of Prepar3D.
- Create and set the flight plans for AI (non-user) aircraft.
- Set different weather systems.
- Enable new hardware to work with Prepar3D.
- Control an additional camera that the user can optionally select to view.
SimConnect Setup
This section describes how to set up a development environment for SimConnect.
- SimConnect Projects
- The SimConnect.ini file
- The SimConnect.cfg file
- The EXE.xml and DLL.xml files
- The SimConnect.xml file
- Design Considerations
SimConnect Projects
To build SimConnect add-ons, you must use Visual Studio 2013 or later. To build the project make sure you have completed the following steps.
Potential issues when using SimConnect.lib
C++ projects that import SimConnect.lib will need to also import the following libraries:
- user32.lib
- AdvApi32.lib
- Shell32.lib
Steps to add:
- Right click on the project
- Expand linker from the left pane
- Click on Input
- Add these libraries in the Additional Dependencies field
C/C++ Projects
- 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.
- Include the SimConnect.h header file.
- Link to the SimConnect.lib library, by adding SimConnect.lib to the Additional
Options of the Command Line (see image below):
- Build the application using the function calls described in this document.
DLL Projects
- 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 "DLL Project"
EXPORTS
DLLStart
DLLStop - Confirm that the definition file has been added to the project by checking the
Linker\Input properties:
- Pay particular attention to the remarks and working samples for SimConnect_CallDispatch.
C#/.NET / VB.NET Projects
- For C#, or other .NET language add-ons, refer to the special section on Programming SimConnect Clients using Managed Code.
- Build the application using the function calls described in this document.
- There are three C# samples, and one VB.NET sample included with the SDK for reference.
All Projects
- Ensure that Visual Studio 2013 or later have been set to 32-bit only. When installed with a 64-bit operating system, these tools will default to a setting which is incompatible with SimConnect.dll. Go through the steps in the Setting x86 Platform Configuration section if you are working with a 64 bit operating system.
- Ensure the SimConnect.ini file is placed in your %USERPROFILE%\Documents\Prepar3D v3 Files folder. A default version of this files can be found in the SDK\Utilities\SimConnectSDK directory.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.
- If the client is to work remotely, write a SimConnnect.cfg file for it.
- By default, SimConnect is disabled. To enable it, you must copy the necessary configuration files to the correct locations. Default versions of these files can be found in the SDK\Utilities\SimConnectSDK directory. Ensure the EXE.xml, DLL.xml files and SimConnect.xml files are placed in either the %APPDATA%\Lockheed Martin\Prepar3D v3 or %PROGRAMDATA%\Lockheed Martin\Prepar3D v3 folder, and edit these files according to the instructions that follow.
- Run Prepar3D to test your SimConnect client.
Setting x86 Platform Configuration
This section only applies to developers working with on a 64-bit operating system. If you are using Microsoft Visual Studio 2013 or later, open up your SimConnect client project and start from step 4. If you are using Microsoft Visual C++ or C# 2013 Express Edition, start from step 1.
- Select the Tools/Options menu item.
- Check Show all settings.
- Check Project and Solutions->Show Advanced Build Configurations.
- Open Build->Configuration Manager.
- Select the combo box under the Platform column for the project you want to target.
- Choose NEW
- Under New Platform select x86.
- Click OK, then Close. Note that the Toolbar combo box for Platform Configuration has x86 selected.
- Building will now be restricted to x86-only binaries.
Using Legacy SimConnect Versions
Some third party add-on software requires an older version of SimConnect than the most current one. In the same folder as your Prepar3D.exe, go to the "\redist\Interface" folder.
There are multiple different legacy versions of SimConnect available:
-
ESPv1
FSX-RTM (Flight Simulator X)
FSX-RTM-JPN (Flight Simulator X, Japanese)
FSX-SP1 (Flight Simulator X: Service Pack 1)
FSX-SP1-RUS (Flight Simulator X: Service Pack 1, Russian)
FSX-SP2-XPACK (Flight Simulator X: Service Pack 2 with Expansion)
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 placed in your %USERPROFILE%\Documents\Prepar3D v3 Files 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 server client communication to the debugger for display. Either your SimConnect application or Prepar3D must be launched from within an integrated development environment (IDE) debugger in order for this option to work. 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 Prepar3D starts, so giving
a new log file for each test run. Example: file=c:\simconnect%03u.log |
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 Prepar3D running on a remote machine, and should be placed in the Documents folder, or in the same folder as the client application or library, on the computer the client is running on.
Note: SimConnect.msi is no longer needed due to the fact that the WinSxS library has been depreciated.
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 Prepar3D. 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 communication 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
Information, such as how to configure add-ons for your SimConnect add-on, can be found in the Add-Ons section of the documentation. These articles contain examples and precise directions to configure add-ons ranging from low to high complexity.The SimConnect.xml file
The SimConnect.xml file contains communication information for the SimConnect server (the SimConnect.cfg file contains information for a client). The default behavior is that three servers are initiated by the system, for local communication using one of each of the three protocols: Pipe, IPv4, and IPv6. These servers do not require entries in the XML file. 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.
The following table describes the file format. The file should be placed in the in the %APPDATA%\Lockheed Martin\Prepar3D v3 folder, on the computer the server is running on.
XML | Values | Description |
---|---|---|
<SimBase.Document Type="SimConnect" version="1,0"></SimBase.Document> | 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></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. |
Design Considerations
The design of a SimConnect add-on involves writing a client to communicate with a server running within Prepar3D. 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 Prepar3D, and are easier to build, test and debug. Out-of-process also supports Managed code, and therefore applications can be written in .NET languages, with their rich support for objects and ease of building the UI. 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.
Versioning
Only one version of Prepar3D 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 Prepar3D, running on a network.
The SimConnect client library used by Prepar3D will be located in the WinSxS (side-by-side) folder. As new versions of the client library are released, they too will be placed in this folder, alongside and not replacing previous versions. This means that add-ons written for older versions of SimConnect will still run as newer versions are released. If a developer wishes to ensure that their client code will run against an earlier version of SimConnect, they should develop using the header and library provided in the SimConnect SDK/LegacyInterfaces folder. Internal version tagging of each API call ensures that a function call will be routed correctly when multiple options exist.
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 Working Samples sections list run-able sample code.
General Functions | Description |
---|---|
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 Prepar3D 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_ChangeVehicle | Used to change the user's vehicle. |
SimConnect_ChangeVehicleWithExternalSim | Used to change the user's vehicle and override the sim to use a specific External Sim instead. |
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_FlightLoad | Used to load an existing scenario file. |
SimConnect_FlightPlanLoad | Used to load an existing flight plan. |
SimConnect_FlightSave | Used to save the current state of a scenario to a scenario 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 an Prepar3D 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 Prepar3D 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_RequestAttachPointData | Used to request attach point positions and orientations from a simulation 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 vehicle. |
SimConnect_RequestMobileSceneryInRadius | Used to retrieve mobile scenery objects that are within a specified radius of the user's vehicle. |
SimConnect_RequestMobileSceneryDataByID | Used to retrieve data about a specific mobile scenery object using its object ID. |
SimConnect_RequestJoystickDeviceInfo | Used to request the name and number of currently connected joystick devices. |
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_RequestSceneryComplexity | Used to request the current scenery complexity setting. |
SimConnect_RequestSessionDuration | Used to request the duration of the current scenario in seconds. |
SimConnect_RequestShadowFlags | Used to request the current shadow flag settings. |
SimConnect_RequestSystemState | Used to request information from a number of Prepar3D system components. |
SimConnect_RequestTrafficSettings | Used to request the current traffic settings. |
SimConnect_RequestVersion | Used to request license type and version numbers of P3D and SimConnect. |
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 Prepar3D system components. |
SimConnect_SetTrafficSettings | Used to set the current traffic settings. |
SimConnect_SubscribeToSystemEvent | Used to request that a specific system event is notified to the client. |
SimConnect_SubscribeToSystemEventEx | Used to request that a specific system event is notified to the client. Flags allow you to request a blocking callback. |
SimConnect_TransmitClientEvent | Used to request that the Prepar3D 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 | Description |
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 | Description |
SimConnect_AICreateEnrouteATCAircraft | Used to create an AI controlled aircraft that is about to start or is already underway on its flight plan. |
SimConnect_AICreateNonATCAircraft | Used to create an aircraft that is not flying under ATC control (so is typically flying under VFR rules). |
SimConnect_AICreateParkedATCAircraft | Used to create an AI controlled aircraft that is currently parked and does not have a flight plan. |
SimConnect_AICreateSimulatedObject | Used to create AI controlled objects other than aircraft. |
SimConnect_AICreateSimulatedObjectEx | Used to create AI controlled objects other than aircraft. Extended for use with disabled simulations and Owned objects |
SimConnect_AICreateObjectWithExternalSim | Used to create an AI object, overriding the sim to use a specific External Sim instead. |
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_AIReleaseControlEx | Used to clear the AI control of a simulated object, typically an aircraft, in order for it to be controlled by a SimConnect client. Extended to be able to remove the AI entirely. |
SimConnect_AIRemoveObject | Used to remove any object created by the client using one of the SimConnect AI creation functions. |
SimConnect_AISetAircraftFlightPlan | Used to set or change the flight plan of an AI controlled aircraft. |
SimConnect_AISetGroundClamp | Used to enable/disable ground clamping on a specific SimConnect owned SimObject. | Camera Specific Functions | Description |
SimConnect_AddPostProcess | Used to add a post process effect to the specified camera. |
SimConnect_AddPostProcessMainCamera | Used to add a post process effect to the main camera. |
SimConnect_CameraPanToView | Used to smoothly transition the view of the specified camera to the view of the specified target camera. |
SimConnect_CameraSetRelative6DOF | Used to adjust the user's aircraft view camera. |
SimConnect_CameraSetRelative6DofByName | Used to adjust the specified view's camera. |
SimConnect_CameraSmoothRelative6DOF | Used to smoothly transition the view of the main camera to the specified location. |
SimConnect_CameraSmoothRelative6DOFByName | Used to smoothly transition the view of the specified camera to the specified location. |
SimConnect_CameraZoomIn | Used to adjust the zoom of the camera. |
SimConnect_CameraZoomOut | Used to adjust the zoom of the camera. |
SimConnect_ChangeView | Used to change the camera used by the main view. |
SimConnect_CloseView | Used to close a view. |
SimConnect_CreateCameraDefinition | Used to create a new camera definition. |
SimConnect_CreateCameraInstance | Used to create a new camera instance from a camera definition. |
SimConnect_DeleteCameraInstance | Used to remove a camera instance from a camera definition. |
SimConnect_DockView | Used to dock a view. |
SimConnect_MainCameraPanToView | Used to smoothly transition the view of the main camera to the view of the specified target camera. |
SimConnect_MainCameraZoomIn | Used to adjust the zoom of the main camera. |
SimConnect_MainCameraZoomOut | Used to adjust the zoom of the main camera. |
SimConnect_OpenView | Used to open a new view. |
SimConnect_RemovePostProcess | Used to remove a post process effect to the specified camera. |
SimConnect_RemovePostProcessMainCamera | Used to remove a post process effect to the main camera. |
SimConnect_RequestCameraFov | Used to request the field-of-view of a given view (horizontal and vertical). See SIMCONNECT_RECV_CAMERA_FOV. |
SimConnect_RequestCameraRelative6DOF | Used to request the XYZ delta offset from the eyepoint reference point, as well as the pitch, bank, and heading of the main view. |
SimConnect_RequestCameraRelative6DofByName | Used to request the XYZ delta offset from the eyepoint reference point, as well as the pitch, bank, and heading of a given view. |
SimConnect_RequestCameraSensorMode | Used to request the current sensor mode of a given view. |
SimConnect_RequestCameraWindowPosition | Used to request the current window position of a given view. |
SimConnect_RequestCameraWindowSize | Used to request the current window size of a given view. |
SimConnect_RequestMainCameraFov | Used to request the field-of-view of the main view (horizontal and vertical). See SIMCONNECT_RECV_CAMERA_FOV. |
SimConnect_RequestMainCameraSensorMode | Used to request the current sensor mode of the main view. |
SimConnect_SendCameraCommand | Used to simulate user inputs to control camera movement and rotation. |
SimConnect_SetCameraFov | Used to change the FoV (Field of View) of a camera. |
SimConnect_SetCameraHorizontalFov | Used to change the horizontal FoV (Field of View) of a camera. |
SimConnect_SetCameraSensorMode | Used to change the sensor mode of a camera. |
SimConnect_SetCameraVerticalFov | Used to change the vertical FoV (Field of View) of a camera. |
SimConnect_SetCameraWindowPosition | Used to set the window position of the specified view. |
SimConnect_SetCameraWindowSize | Used to set the window size of the specified view. |
SimConnect_SetMainCameraFov | Used to change the FoV (Field of View) of the main camera. |
SimConnect_SetMainCameraHorizontalFov | Used to change the horizontal FoV (Field of View) of the main camera. |
SimConnect_SetMainCameraSensorMode | Used to change the sensor mode of the main camera. |
SimConnect_SetMainCameraVerticalFov | Used to change the vertical FoV (Field of View) of the main camera. |
SimConnect_UndockView | Used to undock a view. |
SimConnect_CaptureImage | Used to capture an image of a view. |
SimConnect_BeginVideoStream | Used to begin a video stream of a view. |
SimConnect_EndVideoStream | Used to end a video stream of a view. | Facilities Data Functions | Description |
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 | Description |
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, message window, or scrolling or static text, on the screen. | Structured Scenario Specific Functions | Description |
SimConnect_CompleteCustomMissionAction | Used to complete the scenario action specified by a GUID. |
SimConnect_ExecuteMissionAction | Used to execute the scenario action specified by a GUID. |
SimConnect_RequestFlightSegmentCount | Used to request the number of Flight Segment objects in the active scenario. |
SimConnect_RequestFlightSegmentDataByGUID | Used to request information about a Flight Segment object in the active scenario. |
SimConnect_RequestFlightSegmentDataByIndex | Used to request information about a Flight Segment object in the active scenario. |
SimConnect_RequestFlightSegmentRangeData | Used to request information about a specific range of a Flight Segment object in the active scenario. |
SimConnect_RequestGoalCount | Used to request the number of Goal/Group Goal objects in the active scenario. |
SimConnect_RequestGoalDataByGUID | Used to request information about a Goal/Group Goal object in the active scenario. |
SimConnect_RequestGoalDataByIndex | Used to request information about a Goal/Group Goal object in the active scenario. |
SimConnect_RequestMissionObjectiveCount | Used to request the number of Mission Objective objects in the active scenario. |
SimConnect_RequestMissionObjectiveDataByGUID | Used to request information about a Goal/Group Goal object in the active scenario. |
SimConnect_RequestMissionObjectiveDataByIndex | Used to request information about a Goal/Group Goal object in the active scenario. |
SimConnect_ResolveGoal | Used to resolve a goal to specified goal state. |
SimConnect_RequestChildGoalDataByIndex | Used to request information about a mission objective or group goal's children. |
SimConnect_GenerateFlightAnalysisDiagrams | Used to generate diagrams as shown in the flight analysis UI which can be used, for example, to examine ILS landing performance. |
SimConnect_RequestLandingTriggerCount | Used to request the number of Area Landing Trigger or Airport Landing Trigger objects in the active scenario. |
SimConnect_RequestLandingTriggerLandingInfoCount | Used to request information about a Landing Trigger object's landings in the active scenario. |
SimConnect_RequestLandingTriggerLandingInfoByIndex | Used to request information about a specific landing of a Landing Trigger object in the active scenario. | Weather Specific Functions | Description |
SimConnect_WeatherCreateStation | Used to add a weather station. |
SimConnect_WeatherCreateThermal | Used to create a thermal at a specific location. |
SimConnect_WeatherRemoveStation | Used to remove a weather station. |
SimConnect_WeatherRemoveThermal | Used to remove a thermal. |
SimConnect_WeatherRequestCloudState | Used to request cloud density information on a given area. |
SimConnect_WeatherRequestInterpolatedObservation | Used to send a request for weather data that is interpolated from the weather at the nearest weather stations. |
SimConnect_WeatherRequestObservationAtNearestStation | Used to send a request for the weather data from the weather station nearest to the specified lat/lon position. |
SimConnect_WeatherRequestObservationAtStation | Used to send a request for the weather data from a weather station identified by its ICAO code. |
SimConnect_WeatherSetDynamicUpdateRate | Used to set the rate at which cloud formations change. |
SimConnect_WeatherSetModeCustom | Used to set the weather mode to user-defined. |
SimConnect_WeatherSetModeGlobal | Used to set the weather mode to global, so the same weather data is used everywhere. |
SimConnect_WeatherSetModeServer | Deprecated. |
SimConnect_WeatherSetModeTheme | Used to set the weather mode to a particular theme. |
SimConnect_WeatherSetObservation | Used to set the weather at a specific weather station, identified from within the Metar data string | Observer View Specific Functions | Description |
SimConnect_CreateObserver | Used to create an observer view. |
SimConnect_RequestObserverData | Used to request all data for a specific observer. |
SimConnect_MoveObserver | Used to move an observer using an xyz translation. |
SimConnect_RotateObserver | Used to rotate an observer around a specified axis. |
SimConnect_SetObserverPosition | Used to place an observer at a specific world position. |
SimConnect_SetObserverRotation | Used to set an observer's specific rotation. |
SimConnect_SetObserverLookAt | Used to have an observer look at a world position. |
SimConnect_SetObserverLookAtEx | Used to have an observer look at a world position round world corrected. |
SimConnect_ObserverTrackLocationOn | Used to have an observer track a world position (round world corrected) using an above ground level altitude and accounting for changes in elevation. |
SimConnect_ObserverTrackLocationOff | Used to disable continuous tracking of the previously specified world position. |
SimConnect_SetObserverFieldOfView | Used to set an observer's field of view. |
SimConnect_SetObserverStepSize | Used to set an observer's linear and angular step size. |
SimConnect_SetObserverFocalLength | Used to set an observer's focal length (in meters). |
SimConnect_SetObserverFocusFixed | Used to switch an observer's focus between local and world. |
SimConnect_SetObserverRegime | Used to switch an observer's regime (terrestrial, tellurian, or ghost). |
SimConnect_SetObserverZoomLevels | Used to set an observer's zoom level. |
SimConnect_ObserverTrackEntityOn | Used to enable continuous tracking of the specified entity. |
SimConnect_ObserverTrackEntityOff | Used to disable continuous tracking of the previously specified entity. |
SimConnect_ObserverAttachToEntityOn | Used to attach an observer to the specified entity. |
SimConnect_ObserverAttachToEntityOff | Used to detach an observer from its attached entity. |
SimConnect_SetObserverSceneryOrigin | Used to switch an observer's scenery origin mode (target or self). | Ground Info Specific Functions - Overview | Description |
SimConnect_RequestGroundInfo | Used to request a grid of ground altitudes at a specific lat/lon. |
SimConnect_RequestGroundInfoOnSimObject | Used to request a recurring grid of ground altitudes based on a SimObjects lat/lon. | Synchronous SimConnect Specific Functions - Overview | Description |
SimConnect_RequestSynchronousBlock | Used to request a blocking callback. |
SimConnect_SynchronousUnblock | Used to release a blocking callback. |
SimConnect_SetSynchronousTimeout | Used to set the error timeout length for blocking callbacks. |
SimConnect_SubscribeToSystemEventEx | Used to request that a specific system event is notified to the client. Flags allow you to request a blocking callback. | External Sim Specific Functions - Overview | Description |
SimConnect_RegisterExternalSim | Used to register this client as an external sim provider. |
SimConnect_UnregisterExternalSim | Used to unregister this client as an external sim provider. |
SimConnect_RegisterExternalSecondarySim | Used to register this client as an external secondary sim provider. |
SimConnect_UnregisterExternalSecondarySim | Used to unregister this client as an external secondarysim provider. |
SimConnect_AttachExternalSecondarySimToSimObject | Used to attach an External Secondary Sim to an existing SimObject. |
SimConnect_DetachExternalSecondarySimFromSimObject | Used to detach an External Secondary Sim from an existing SimObject. |
SimConnect_AICreateObjectWithExternalSim | Used to create an AI object, overriding the sim to use a specific External Sim instead. |
SimConnect_ChangeVehicleWithExternalSim | Used to change the user's vehicle and override the sim to use a specific External Sim instead. | Attach Sim Specific Functions - Overview | Description |
SimConnect_AttachObjectToSimObject | Used to create a SimObject and attach it to an existing SimObject. |
SimConnect_AttachSimObjectToSimObject | Used to attach an existing SimObject to another existing SimObject. |
SimConnect_ReleaseSimObjectFromSimObject | Used to release a SimObject from another SimObject. | Attach Weapon Specific Functions - Overview | Description |
SimConnect_AttachWeaponToObject | Used to create a Weapon and attach it to an existing SimObject. |
SimConnect_ClearWeapons | Used to remove all Weapons from a SimObject. | Effect Specific Functions | Description |
SimConnect_CreateEffect | Used to create an effect at a location or attach it to an existing SimObject. |
SimConnect_RemoveEffect | Used to remove an effect. | Recorder Specific Functions | Description |
SimConnect_PlaybackRecording | Used to playback a specified recording from a specified start time to a specified end time. |
SimConnect_StartRecorder | Used to trigger the Prepar3D Recorder to start recording. |
SimConnect_StopRecorderAndSaveRecording | Used to trigger the Prepar3D Recorder to stop recording and either prompt the user or save the recording with a specified file name. |
SimConnect_RequestRecordingInfo | Used to request information on a recording. |
SimConnect_RequestBookmarkInfo | Used to request bookmark information on a recording. | Deprecated Functions | Description |
SetCameraRenderSettings | Deprecated |
SetCameraColorizationMode | Deprecated |
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
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
{
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 code 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;
}
}
Working 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
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 theclient defined group.
- EventID
- [in] Specifies the ID of theclient 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 Prepar3D itself (if the priority of the client exceeds that of Prepar3D). 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
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);
Working 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 API Reference
- SimConnect_RemoveClientEvent
- SimConnect_SetNotificationGroupPriority
- SimConnect_ClearNotificationGroup
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
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.
See Also
- SimConnect_ClearClientDataDefinition
- SimConnect_CreateClientData
- SimConnect_MapClientDataNameToID
- SimConnect_RequestClientData
- SimConnect_SetClientData
- SimConnect API Reference
SimConnect_AddToDataDefinition
The SimConnect_AddToDataDefinition function is used to add a Prepar3D simulation variable name to a client defined object definition.
Syntax
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 Prepar3D 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).
- 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
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;
}
....
Working 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 API Reference
- SimConnect_ClearDataDefinition
- SimConnect_RequestDataOnSimObject
- SimConnect_RequestDataOnSimObjectType
SimConnect_CallDispatch
The SimConnect_CallDispatch function is used to process the next SimConnect message received, through the specified callback function.
Syntax
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
....
//
while( quit == 0 )
{
hr = SimConnect_CallDispatch(hSimConnect, MyDispatchProc, NULL);
};
Working 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:
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...");
// 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);
}
In order to implement SimConnect as a class, and maintain an object-oriented design of an add-on, the following constructs can be used. Note in particular the static function and the use of the pContext parameter.
{
void Dispatch();
static void DispatchCallback(SIMCONNECT_RECV *pData, DWORD cbData, void *pContext);
void Process(SIMCONNECT_RECV *pData, DWORD cbData);
HANDLE hSimConnect; // use SimConnect_Open to set this value.
};
void CName::Dispatch()
{
::SimConnect_Dispatch(hSimConnect, &CName::DispatchCallback, this);
}
// static function
void CName::DispatchCallback(SIMCONNECT_RECV *pData, DWORD cbData, void *pContext)
{
CName *pThis = reinterpret_cast<CName*>(pContext);
pThis->Process(pData, cbData);
}
void CName::Process(SIMCONNECT_RECV *pData, DWORD cbData)
{
// do processing of SimConnect data
}
See Also
SimConnect_ChangeVehicle
The SimConnect_ChangeVehicle function is used to change the selected vehicle.
Syntax
HANDLE hSimConnect,
const char* Vehicletitle
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- Vehicletitle
- [in] title of the desired vehicle
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. |
Working Samples
Primary samples |
Change Vehicle Managed Change Vehicle |
Remarks
The instant replay does not get reset on the vehicle change which is the normal behavior when changing the vehicle in Prepar3D.
See Also
None.
SimConnect_ClearClientDataDefinition
The SimConnect_ClearClientDataDefinition function is used to clear the definition of the specified client data.
Syntax
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_AddToClientDataDefinition
- SimConnect_CreateClientData
- SimConnect_MapClientDataNameToID
- SimConnect_RequestClientData
- SimConnect_SetClientData
- SimConnect API Reference
SimConnect_ClearDataDefinition
The SimConnect_ClearDataDefinition function is used to remove all simulation variables from a client defined data definition.
Syntax
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
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 API Reference
- SimConnect_AddToDataDefinition
- SimConnect_RequestDataOnSimObject
- SimConnect_RequestDataOnSimObjectType
SimConnect_ClearInputGroup
The SimConnect_ClearInputGroup function is used to remove all the input events from a specified input group object.
Syntax
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
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 API Reference
- SimConnect_MapInputEventToClientEvent
- SimConnect_SetInputGroupPriority
- SimConnect_RemoveInputEvent
- SimConnect_SetInputGroupState
SimConnect_ClearNotificationGroup
The SimConnect_ClearNotificationGroup function is used to remove all the client defined events from a notification group.
Syntax
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
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 API Reference
- SimConnect_AddClientEventToNotificationGroup
- SimConnect_RemoveClientEvent
- SimConnect_SetNotificationGroupPriority
SimConnect_Close
The SimConnect_Close function is used to request that the communication with the server is ended.
Syntax
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. |
Example
Working 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
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 Prepar3D this is 8K. There is no maximum number of client data areas, but the total must not exceed 1Mbyte 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 Prepar3D 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_AddToClientDataDefinition
- SimConnect_ClearClientDataDefinition
- SimConnect_MapClientDataNameToID
- SimConnect_RequestClientData
- SimConnect_SetClientData
- SimConnect API Reference
SimConnect_FlightLoad
The SimConnect_FlightLoad function is used to load an existing scenario file.
Syntax
HANDLE hSimConnect,
const char* szFileName
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szFileName
- [in] Null-terminated string containing the path to the scenario file. The path can either be absolute, or relative to the %USERPROFILE%\Documents\Prepar3D v3 Files folder. Scenario files have the extension .FXML. The extension is not required for .FXML files. To load deprecated .FLT files, the .FLT extension must be specified.
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
Scenario 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
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 scenario file is in the default Prepar3D v3 Files directory. The easiest way to create flight plans is to create them from within Prepar3D 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 scenario to a scenario file.
Syntax
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 scenario file. The path can either be absolute, or relative to the %USERPROFILE%\Documents\Prepar3D v3 Files folder. Scenario files have the extension .FXML. If the extension is not specified, it will still save as an .FXML. If the deprecated .FLT extension is specified, it will be overwritten as an .FXML. It is not possible to save deprecated .FLT files.
- sztitle
- [in] Null-terminated string containing the title of the scenario 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 scenario 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
Scenario 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
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
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);
Working 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
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
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 code 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;
}
}
Working 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
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 add-on, 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_AddToClientDataDefinition
- SimConnect_ClearClientDataDefinition
- SimConnect_CreateClientData
- SimConnect_RequestClientData
- SimConnect_SetClientData
- SimConnect API Reference
SimConnect_MapClientEventToSimEvent
The SimConnect_MapClientEventToSimEvent function associates a client defined event ID with a Prepar3D event name.
Syntax
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 Prepar3D 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 Prepar3D) that has been coded
to receive such events. No Prepar3D 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 Prepar3D.
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
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);
Working 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
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. This value is only acknowledged for keyboard and button events.
- 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. This value is only acknowledged for keyboard and button events.
- 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);
Working 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).
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 joystick number can be retrieved through the SimConnect_RequestJoystickDeviceInfo function. 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. | 0 = up state, 1 = down state |
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 scenario 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 Lockheed Martin\Prepar3D v3 folder. The first time Prepar3D is run, a subset of this file is written out to a file with the same name in the %APPDATA%\Lockheed Martin\Prepar3D v3\Controls folder, containing just the mappings that the current setup is using. Each time Prepar3D 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 Prepar3D is running, as in this case the file will be over-written.
See Also
- SimConnect API Reference
- SimConnect_SetInputGroupPriority
- SimConnect_RemoveInputEvent
- SimConnect_ClearInputGroup
- SimConnect_SetInputGroupState
- SimConnect_RequestJoystickDeviceInfo
SimConnect_Open
The SimConnect_Open function is used to send a request to the Prepar3D server to open up communications with a new client.
Syntax
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. The empty string ("") is a valid entry, NULL is not supported.
- 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 Prepar3D.
- 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 Prepar3D. 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 add-on 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
HANDLE hSimConnect = NULL;
hr = SimConnect_Open(&hSimConnect, "Your Application Name", NULL, 0, 0, SIMCONNECT_OPEN_CONFIGINDEX_LOCAL);
Working 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 Prepar3D that support it, are available.
If a remote client successfully establishes a link with Prepar3D, 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. If this exception is received the dwIndex parameter will contain the following:
See Also
SimConnect_RemoveClientEvent
The SimConnect_RemoveClientEvent function is used to remove a client defined event from a notification group.
Syntax
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
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 API Reference
- SimConnect_AddClientEventToNotificationGroup
- SimConnect_SetNotificationGroupPriority
- SimConnect_ClearNotificationGroup
SimConnect_RemoveInputEvent
The SimConnect_RemoveInputEvent function is used to remove an input event from a specified input group object.
Syntax
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
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 API Reference
- SimConnect_MapInputEventToClientEvent
- SimConnect_SetInputGroupPriority
- SimConnect_ClearInputGroup
- SimConnect_SetInputGroupState
SimConnect_RequestAttachPointData
The SimConnect_RequestAttachPointData function is used to request attach point data from a simulation object.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID,
DWORD dwObjectID,
const char* szAttachPointName,
BOOL bRequestWorldCoordinates = FALSE
);
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.
- dwObjectID
- [in] The ID of the object to request attachpoint information from.
- szAttachPointName
- [in] Specifies the name of the attach point to request data from.
- bRequestWorldCoordinates
- [in, optional] If set to TRUE, the world position and orientation information will be requested as well. If FALSE, world position and orientation information will be returned as zero.
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 data will be returned in a SIMCONNECT_RECV_ATTACHPOINT_DATA structure.
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
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_AddToClientDataDefinition
- SimConnect_ClearClientDataDefinition
- SimConnect_CreateClientData
- SimConnect_MapClientDataNameToID
- SimConnect_SetClientData
- SimConnect API Reference
SimConnect_RequestDataOnSimObject
The SimConnect_RequestDataOnSimObject function is used to request when the SimConnect client is to receive data values for a specific object.
Syntax
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 Prepar3D 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. SIMCONNECT_DATA_REQUEST_FLAG_BLOCK Requested data will be sent using a blocking callback. See SimConnect_RequestSynchronousBlock for more information. - 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
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;
}
....
Working 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.
If an object is removed, and if it has a current periodic data request, a SIMCONNECT_EXCEPTION_UNRECOGNIZED_ID exception will be sent every requested period. This can be avoided by sending a new SimConnect_RequestDataOnSimObject with the period set to SIMCONNECT_PERIOD_NEVER, before the object is removed or once the first exception is generated.
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 working 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 indicate 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 scenario. 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 API Reference
- SimConnect_AddToDataDefinition
- SimConnect_ClearDataDefinition
- SimConnect_RequestDataOnSimObjectType
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.
Syntax
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
Working Samples
Primary samples |
Request Data
Variable Strings |
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.
See Also
- SimConnect API Reference
- SimConnect_AddToDataDefinition
- SimConnect_ClearDataDefinition
- SimConnect_RequestDataOnSimObject
SimConnect_RequestFlightSegmentCount
The SimConnect_RequestFlightSegmentCount function is used to request the number of Flight Segment objects in the active scenario.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID,
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- 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. |
Working Samples
Primary samples | Managed Mission Objects |
Remarks
The information requested will be returned in a SIMCONNECT_RECV_MISSION_OBJECT_COUNT structure.
See Also
SimConnect_RequestFlightSegmentDataByGUID
The SimConnect_RequestFlightSegmentDataByGUID function is used to request information about a Flight Segment object in the active scenario.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID,
const GUID guidInstanceID,
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- RequestID
- [in] Specifies the client defined request ID.
- guidInstanceID
- [in] Specifies the instance ID of the Flight Segment.
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. |
Working Samples
Primary samples | Managed Mission Objects |
Remarks
The information requested will be returned in a SIMCONNECT_RECV_FLIGHT_SEGMENT structure.
See Also
SimConnect_RequestFlightSegmentDataByIndex
The SimConnect_RequestFlightSegmentDataByIndex function is used to request information about a Flight Segment object in the active scenario.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID,
int flightSegmentIndex,
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- RequestID
- [in] Specifies the client defined request ID.
- flightSegmentIndex
- [in] Specifies the index of the requested Flight Segment in the scenario.
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. |
Working Samples
Primary samples | Managed Mission Objects |
Remarks
The information requested will be returned in a SIMCONNECT_RECV_FLIGHT_SEGMENT structure.
See Also
SimConnect_RequestFlightSegmentRangeData
The SimConnect_RequestFlightSegmentRangeData function is used to request information about a specific range of a Flight Segment object in the active scenario.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID,
const GUID guidInstanceID,
int rangeIndex,
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- RequestID
- [in] Specifies the client defined request ID.
- guidInstanceID
- [in] Specifies the instance ID of the Flight Segment.
- rangeIndex
- [in] Specifies the index of the range within the requested Flight Segment in the scenario.
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. |
Working Samples
Primary samples | Managed Mission Objects |
Remarks
The information requested will be returned in a SIMCONNECT_RECV_PARAMETER_RANGE structure.
See Also
- SimConnect API Reference
- SimConnect_RequestFlightSegmentDataByGUID
- SimConnect_RequestFlightSegmentDataByIndex
SimConnect_RequestGoalCount
The SimConnect_RequestGoalCount function is used to request the number of Goal/Group Goal objects in the active scenario.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID,
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- 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. |
Working Samples
Primary samples | Managed Mission Objects |
Remarks
The information requested will be returned in a SIMCONNECT_RECV_MISSION_OBJECT_COUNT structure.
See Also
- SimConnect API Reference
- SimConnect_RequestFlightSegmentCount
- SimConnect_RequestMissionObjectiveCount
SimConnect_RequestGoalDataByGUID
The SimConnect_RequestGoalDataByGUID function is used to request information about a Goal/Group Goal object in the active scenario.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID,
const GUID guidInstanceID,
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- RequestID
- [in] Specifies the client defined request ID.
- guidInstanceID
- [in] Specifies the instance ID of the Goal/Group Goal.
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. |
Working Samples
Primary samples | Managed Mission Objects |
Remarks
The information requested will be returned in a SIMCONNECT_RECV_GOAL structure.
See Also
SimConnect_RequestGoalDataByIndex
The SimConnect_RequestGoalDataByIndex function is used to request information about a Goal/Group Goal object in the active scenario.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID,
int goalIndex,
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- RequestID
- [in] Specifies the client defined request ID.
- goalIndex
- [in] Specifies the index of the requested Goal/Group Goal object in the scenario.
Return Values
The function returns an HRESULT. Possible values include, but are not limited to, those in the following table. /p>
Return value | Description |
---|---|
S_OK | The function succeeded. |
E_FAIL | The function failed. |
Working Samples
Primary samples | Managed Mission Objects |
Remarks
The information requested will be returned in a SIMCONNECT_RECV_GOAL structure.
See Also
SimConnect_RequestChildGoalDataByIndex
The SimConnect_RequestChildGoalDataByIndex function is used to request information about a mission objective or group goal's children.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID,
const GUID parentGuidInstanceID,
int goalIndex,
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- RequestID
- [in] Specifies the client defined request ID.
- parentGuidInstanceID
- [in] Specifies the instance ID of the Mission Objective or Group Goal that will have their children queried.
- goalIndex
- [in] Specifies the index of the child goal to query.
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_GOAL_PAIR structure.
See Also
SimConnect_RequestMissionObjectiveCount
The SimConnect_RequestMissionObjectiveCount function is used to request the number of Mission Objective objects in the active scenario.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID,
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- 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. |
Working Samples
Primary samples | Managed Mission Objects |
Remarks
The information requested will be returned in a SIMCONNECT_RECV_MISSION_OBJECT_COUNT structure.
See Also
SimConnect_RequestMissionObjectiveDataByGUID
The SimConnect_RequestMissionObjectiveDataByGUID function is used to request information about a Mission Objective object in the active scenario.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID,
const GUID guidInstanceID,
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- RequestID
- [in] Specifies the client defined request ID.
- guidInstanceID
- [in] Specifies the instance ID of the Mission Objective.
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. |
Working Samples
Primary samples | Managed Mission Objects |
Remarks
The information requested will be returned in a SIMCONNECT_RECV_MISSION_OBJECTIVE structure.
See Also
SimConnect_RequestMissionObjectiveDataByIndex
The SimConnect_RequestMissionObjectiveDataByIndex function is used to request information about a Mission Objective object in the active scenario.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID,
int missionObjectiveIndex,
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- RequestID
- [in] Specifies the client defined request ID.
- missionObjectiveIndex
- [in] Specifies the index of the requested Mission Objective object in the scenario.
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. |
Working Samples
Primary samples | Managed Mission Objects |
Remarks
The information requested will be returned in a SIMCONNECT_RECV_MISSION_OBJECTIVE structure.
See Also
SimConnect_GenerateFlightAnalysisDiagrams
The SimConnect_GenerateFlightAnalysisDiagrams function is primarily used to generate diagrams as shown in the flight analysis UI which can be used, for example, to examine ILS landing performance. The following images will be generated in your Prepar3D v3 Files in the My Pictures Library:
- FlightAnalysis_Plot_Altitude.bmp: Glide Slope or Distance vs. Altitude Plot (when Glide Slope is not available)
- FlightAnalysis_Map_ILS.bmp: Map View showing any ILS localizers
Syntax
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. |
Remarks
The information requested will be returned in a SIMCONNECT_RECV_EVENT_FLIGHT_ANALYSIS_DIAGRAMS structure.
See Also
SimConnect_RequestLandingTriggerCount
The SimConnect_RequestLandingTriggerCount function is used to request the number of Area Landing Trigger or Airport Landing Trigger objects in the active scenario.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- 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
The information requested will be returned in a SIMCONNECT_RECV_MISSION_OBJECT_COUNT structure.
See Also
- SimConnect API Reference
- SimConnect_RequestLandingTriggerLandingInfoCount
- SimConnect_RequestLandingTriggerLandingInfoByIndex
SimConnect_RequestLandingTriggerLandingInfoCount
The SimConnect_RequestLandingTriggerLandingInfoCount function is used to request information about a landing trigger object's landings in the active scenario.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID,
int landingTriggerIndex
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- RequestID
- [in] Specifies the client defined request ID.
- landingTriggerIndex
- [in] Specifies the index of the requested Landing Trigger object in the scenario.
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_LANDING_TRIGGER_INFO structure.
See Also
- SimConnect API Reference
- SimConnect_RequestLandingTriggerCount
- SimConnect_RequestLandingTriggerLandingInfoByIndex
SimConnect_RequestLandingTriggerLandingInfoByIndex
The SimConnect_RequestLandingTriggerLandingInfoByIndex function is used to request information about a specific landing of a Landing Trigger object in the active scenario.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID,
const GUID landingTriggerInstanceID,
int landingIndex
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- RequestID
- [in] Specifies the client defined request ID.
- landingTriggerInstanceID
- [in] Specifies the instance ID of the Landing Trigger.
- landingIndex
- [in] Specifies the index of the landing within the requested Landing Trigger in the scenario.
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_LANDING_INFO structure.
See Also
- SimConnect API Reference
- SimConnect_RequestLandingTriggerCount
- SimConnect_RequestLandingTriggerLandingInfoCount
SimConnect_RequestJoystickDeviceInfo
The SimConnect_RequestJoystickDeviceInfo function is used to request information on currently connected joystick devices.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- 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
The information requested will be returned in a SIMCONNECT_RECV_JOYSTICK_DEVICE_INFO structure.
This function does not include mouse devices.
See Also
SimConnect_RequestMobileSceneryInRadius
The SimConnect_RequestMobileSceneryInRadius function is used to retrieve mobile scenery objects that are within a specified radius of the user's vehicle. Any request over 20,000 meters will return all mobile scenery objects.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID
DWORD dwRadiusMeters
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- RequestID
- [in] Specifies the client defined request ID.
- dwRadiusMeters
- [in] Specifies the radius (in meters) from the user vehicle from which to obtain mobile scenery.
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_MOBILE_SCENERY_IN_RADIUS structure.
Working Samples
Primary samples | See Managed Mission Objects sample in SimConnect SDK. |
See Also
- SimConnect_RequestMobileSceneryDataByID
- SIMCONNECT_RECV_MOBILE_SCENERY_IN_RADIUS
- SIMCONNECT_DATA_MOBILE_SCENERY_INFO
- SIMCONNECT_RECV_MOBILE_SCENERY_DATA
- SimConnect API Reference
SimConnect_RequestMobileSceneryDataByID
The SimConnect_RequestMobileSceneryDataByID function is used to retrieve data about a specific mobile scenery object using its object ID.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID
SIMCONNECT_OBJECT_ID ObjectID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- RequestID
- [in] Specifies the client defined request ID.
- ObjectID
- [in] Specifies the object ID of the mobile scenery object to retrieve data about.
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_MOBILE_SCENERY_DATA structure.
Working Samples
Primary samples | See Managed Mission Objects sample in SimConnect SDK. |
See Also
- SimConnect_RequestMobileSceneryInRadius
- SIMCONNECT_RECV_MOBILE_SCENERY_IN_RADIUS
- SIMCONNECT_DATA_MOBILE_SCENERY_INFO
- SIMCONNECT_RECV_MOBILE_SCENERY_DATA
- SimConnect API Reference
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
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 API Reference
- SimConnect_AddClientEventToNotificationGroup
- SimConnect_SetNotificationGroupPriority
- SimConnect_ClearNotificationGroup
SimConnect_RequestReservedKey
The SimConnect_RequestReservedKey function is used to request a specific keyboard TAB-key combination applies only to this client.
Syntax
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. |
Working 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 Prepar3D system components.
Syntax
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 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 scenario. Scenario files have the extension .FXML. FlightPlan Requests the full path name of the active flight plan. An empty string will be returned if there is no active flight plan. FullScreenMode Requests whether the simulation is in Full Screen mode or not. 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_RequestVersion
The SimConnect_RequestVersion function is used to request license type, Prepar3D version, and Prepar3D SimConnect version.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- 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
The information requested will be returned in a SIMCONNECT_RECV_VERSION structure.
See Also
SimConnect_RequestSceneryComplexity
The SimConnect_RequestSceneryComplexity function is used to request the current scenery complexity setting.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- 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. |
Working Samples
Primary samples | Scenery Complexity and Shadow Flags |
Remarks
The information requested will be returned in a SIMCONNECT_RECV_SCENERY_COMPLEXITY structure.
See Also
SimConnect_RequestShadowFlags
The SimConnect_RequestShadowFlags function is used to request the current shadow flag settings.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- 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. |
Working Samples
Primary samples | Scenery Complexity and Shadow Flags |
Remarks
The information requested will be returned in a SIMCONNECT_RECV_SHADOW_FLAGS structure.
See Also
SimConnect_RequestSessionDuration
The SimConnect_RequestSessionDuration function is used to request the simulated time in seconds since the last scenario load. When in a scenario, the duration is accumulated between scenario saves/loads, such as saving and loading checkpoints.
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- 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
The information requested will be returned in a SIMCONNECT_RECV_SESSION_DURATION structure.
See Also
SimConnect_RequestTrafficSettings
The SimConnect_RequestTrafficSettings function is used to request the current traffic settings.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- 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. |
Working Samples
Primary samples | None |
Remarks
The information requested will be returned in a SIMCONNECT_RECV_TRAFFIC_SETTINGS structure.
See Also
SimConnect_ResolveGoal
The SimConnect_ResolveGoal function is used to resolve a goal to specified goal state.
HANDLE hSimConnect,
const GUID guidInstanceID,
SIMCONNECT_GOAL_RESOLUTION goalResolution
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- RequestID
- [in] Specifies the client defined request ID.
- guidInstanceID
- [in] Specifies the instance ID of the Flight Segment.
- goalResolution
- [in] Specifies the state, defined in SIMCONNECT_GOAL_RESOLUTION, the goal/group goal should resolve to.
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. |
Working Samples
Primary samples | Managed Mission Objects |
Remarks
This allows the client to do its own processing to determine the passing state of a goal.
See Also
SimConnect_SetClientData
The SimConnect_SetClientData function is used to write one or more units of data to a client data area.
Syntax
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_CLIENT_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_AddToClientDataDefinition
- SimConnect_ClearClientDataDefinition
- SimConnect_CreateClientData
- SimConnect_MapClientDataNameToID
- SimConnect_RequestClientData
- SimConnect API Reference
SimConnect_SetDataOnSimObject
The SimConnect_SetDataOnSimObject function is used to make changes to the data properties of an object.
Syntax
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 Prepar3D 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. SIMCONNECT_DATA_SET_FLAG_UNBLOCK Any currently outstanding blocking callbacks are released. See SimConnect_RequestSynchronousBlock for more information. - 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 Prepar3D. 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
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, 0, sizeof(Init), &Init);
Working 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_AddToDataDefinition
- SimConnect_ClearDataDefinition
- SimConnect_RequestDataOnSimObject
- SimConnect_RequestDataOnSimObjectType
- SimConnect API Reference
SimConnect_SetInputGroupPriority
The SimConnect_SetInputGroupPriority function is used to set the priority for a specified input group object.
Syntax
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
Working 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 API Reference
- SimConnect_MapInputEventToClientEvent
- SimConnect_RemoveInputEvent
- SimConnect_ClearInputGroup
- SimConnect_SetInputGroupState
SimConnect_SetInputGroupState
The SimConnect_SetInputGroupState function is used to turn requests for input event information from the server on and off.
Syntax
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
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);
Working 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 API Reference
- SimConnect_MapInputEventToClientEvent
- SimConnect_SetInputGroupPriority
- SimConnect_RemoveInputEvent
- SimConnect_ClearInputGroup
SimConnect_SetNotificationGroupPriority
The SimConnect_SetNotificationGroupPriority function is used to set the priority for a notification group.
Syntax
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
Working 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 Prepar3D 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. Prepar3D'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 Prepar3D 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. Prepar3D does not mask any events.
See Also
- SimConnect API Reference
- SimConnect_AddClientEventToNotificationGroup
- SimConnect_RemoveClientEvent
- SimConnect_ClearNotificationGroup
SimConnect_SetSystemEventState
The SimConnect_SetSystemEventState function is used to turn requests for event information from the server on and off.
Syntax
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 working 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 Prepar3D system components.
Syntax
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 Working 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. |
Working 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_SetTrafficSettings
The SimConnect_SetTrafficSettings function is used to set the current traffic settings.
Syntax
HANDLE hSimConnect,
UINT uAirlineDensity,
UINT uGADensity,
UINT uRoadTrafficDensity,
UINT uShipsAndFerriesDensity,
UINT uLeisureBoatDensity,
SIMCONNECT_DYNAMIC_FREQUENCY eAirportVehicleDensity,
BOOL bIFROnly
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- uAirlineDensity
- [in] The value that airline traffic density should be set to from 0 to 100.
- uGADensity
- [in] The value that general aviation traffic density should be set to from 0 to 100.
- uRoadTrafficDensity
- [in] The value that road traffic density should be set to from 0 to 100.
- uShipsAndFerries
- [in] The value that ship and ferry traffic density should to be set to from 0 to 100.
- uLeisureBoatDensity
- [in] The value that leisure boat traffic density should be set to from 0 to 100.
- eAirportVehicleDensity
- [in] The value that airport vehicle traffic density should be set to. See also enumeration SIMCONNECT_DYNAMIC_FREQUENCY.
- bIFROnly
- [in] Set to TRUE if only IFR traffic should be present, FALSE otherwise.
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. |
Working Samples
Primary samples | None |
Remarks
The information requested will be returned in a SIMCONNECT_RECV_TRAFFIC_SETTINGS structure.
See Also
SimConnect_SubscribeToSystemEvent
The SimConnect_SubscribeToSystemEvent function is used to request that a specific system event is notified to the client.
Syntax
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).
General System Event Name 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. 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 scenario is loaded. Note that when a scenario is ended, a default scenario is typically loaded, so these events will occur when scenarios are started and finished. The filename of the scenario loaded is returned in a SIMCONNECT_RECV_EVENT_FILENAME structure. FlightSaved Request a notification when a scenario is saved correctly. The filename of the scenario saved is returned in a SIMCONNECT_RECV_EVENT_FILENAME structure. 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 scenario 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 scenario 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 scenario 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 vehicle which is on the ground, underwater or in the air. SimStop The simulator is not running. Typically the user is loading a scenario, navigating the user interface 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 scenario 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 Event Name 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 Event Name MissionCompleted Request a notification when the user has completed a scenario. Refer also to the SIMCONNECT_MISSION_END enum. CustomMissionActionExecuted Request a notification when a scenario action has been executed. Refer also to the SimConnect_CompleteCustomMissionAction function. FlightSegmentReadyForGrading Request a notification when a Flight Segment has been completed and is ready for grading. Multiplayer Racing Event Name 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 multiplayer 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 will 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. Recorder Specific Event Name PlaybackStateChanged Request a notification when the state of Prepar3D playback changes. Either playback has started or ended. Information is returned in a SIMCONNECT_RECV_PLAYBACK_STATE_CHANGED structure. RecorderStateChanged Request a notification when the state of Prepar3D recording changes. Either recording has started or ended. Information is returned in a SIMCONNECT_RECV_RECORDER_STATE_CHANGED structure. Weapon System Event Name PROFESSIONAL PLUS ONLY WeaponFired Request a notification when a detachable weapon is fired. Refer also to the SIMCONNECT_RECV_EVENT_WEAPON structure. WeaponDetonated Request a notification when a detachable weapon is detonated or destroyed. Refer also to the SIMCONNECT_RECV_EVENT_WEAPON structure. CountermeasureFired Request a notification when a countermeasure is deployed. Refer also to the SIMCONNECT_RECV_EVENT_COUNTERMEASURE structure. ObjectDamagedByWeapon Request a notification when an object is damaged by a weapon. Refer also to the SIMCONNECT_RECV_EVENT_OBJECT_DAMAGED_BY_WEAPON 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. |
Example
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);
Working 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_SubscribeToSystemEventEx
- SimConnect_RequestSystemState
- SimConnect_SetSystemState
- SimConnect API Reference
SimConnect_SubscribeToSystemEventEx
The SimConnect_SubscribeToSystemEventEx function is used to request that a specific system event is notified to the client. The Ex specific version of the function adds a Flags parameter.
Syntax
HANDLE hSimConnect,
SIMCONNECT_CLIENT_EVENT_ID EventID,
const char* SystemEventName,
SIMCONNECT_EVENT_SUBSCRIPTION_FLAG Flags
);
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).
- Flags
- [in] One or more of the following flags.
Flags Description SIMCONNECT_EVENT_SUBSCRIPTION_FLAG_BLOCK Specifies that a blocking callback will be used when this system event occurs. See SimConnect_RequestSynchronousBlock for more information.
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
See SimConnect_SubscribeToSystemEvent for description of other parameters.
See Also
- SimConnect_SubscribeToSystemEvent
- SimConnect_RequestSystemState
- SimConnect_SetSystemState
- SimConnect API Reference
SimConnect_TransmitClientEvent
The SimConnect_TransmitClientEvent function is used to request that the Prepar3D server transmit to all SimConnect clients the specified client event.
Syntax
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 Prepar3D 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:
NOTE: For panel control you must specify a group priority of 0.
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
EVENT_OPEN_PANEL
};
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);
NOTE: For panel control you must specify a group priority of 0.
Working 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
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
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
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
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
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
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
char title[1];
}
StructVS *pS = (StructVS*)&pObjData->dwData;
char *psztitle;
DWORD cbtitle;
hr = SimConnect_RetrieveString(pData, cbData, &pS->strings, &psztitle, &cbtitle)))
Working 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
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, or title= Aircreation582SL.
- 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 Prepar3D 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 Prepar3D v3 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. |
Working 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 takeoff 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 Prepar3D or created directly in XML, matching the required format. The simplest flight plan will contain only the departure and destination airports. The ATCWaypoints in a scenario file are not identical to the SIMCONNECT_DATA_WAYPOINT structures. ATCWaypoints in a flightplan can be very far apart, and the AI pilot of Prepar3D requires waypoints to be no more than around five miles apart, so a flightplan such as the one given below will be broken down by the AI component into shorter sections -- using the SIMCONNECT_DATA_WAYPOINT structures.
<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
- SimConnect_AICreateParkedATCAircraft
- SimConnect_AICreateSimulatedObject
- SimConnect_AIRemoveObject
- SimConnect_AISetAircraftFlightPlan
- SimConnect API Reference
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
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): for example: title=Airbus A321, or title= Aircreation582SL,.
- 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. |
Working 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_AICreateEnrouteATCAircraft
- SimConnect_AICreateParkedATCAircraft
- SimConnect_AICreateSimulatedObject
- SimConnect_AIRemoveObject
- SimConnect_AISetAircraftFlightPlan
- SimConnect API Reference
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
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): for example: title=Airbus A321, or title= Aircreation582SL.
- 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. |
Working 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. Use the Dump Airport List tool (refer to the Traffic Toolbox documentation) to see what parking spaces are available at any airport.
Refer also to the remarks for SimConnect_AICreateEnrouteATCAircraft.
See Also
- SimConnect_AICreateEnrouteATCAircraft
- SimConnect_AICreateNonATCAircraft
- SimConnect_AICreateSimulatedObject
- SimConnect_AIRemoveObject
- SimConnect_AISetAircraftFlightPlan
- SimConnect API Reference
SimConnect_AICreateSimulatedObject
The SimConnect_AICreateSimulatedObject function is used to create AI controlled objects other than aircraft.
Syntax
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_FlatNosedBoats title=cargoA
title=cargoA_hoop
title=cargoBMiscellaneous title=Flour_bomb_floating_dock
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. |
Working 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_AICreateEnrouteATCAircraft
- SimConnect_AICreateNonATCAircraft
- SimConnect_AICreateParkedATCAircraft
- SimConnect_AICreateSimulatedObjectEx
- SimConnect_AIRemoveObject
- SimConnect API Reference
SimConnect_AICreateSimulatedObjectEx
The SimConnect_AICreateSimulatedObjectEx function is used to create AI controlled objects other than aircraft.
Syntax
HANDLE hSimConnect,
const char* szContainertitle,
SIMCONNECT_DATA_INITPOSITION InitPos,
SIMCONNECT_DATA_REQUEST_ID RequestID
BOOL isDisabled = FALSE
int OwnerID = -1
);
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_FlatNosedBoats title=cargoA
title=cargoA_hoop
title=cargoBMiscellaneous title=Flour_bomb_floating_dock
title=HumpbackWhale - InitPos
- [in] Specifies the initial position, using a SIMCONNECT_DATA_INITPOSITION structure.
- RequestID
- [in] Specifies the client defined request ID.
- isDisabled
- [in, optional] Specifies whether the simulation starts disabled or not default value is FALSE.
- OwnerID
- [in, optional] Specifies the owner of this simualted object. Default value is -1 which is an invalid object 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. |
Working 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_AICreateEnrouteATCAircraft
- SimConnect_AICreateNonATCAircraft
- SimConnect_AICreateParkedATCAircraft
- SimConnect_AIRemoveObject
- SimConnect API Reference
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
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 API Reference
- SimConnect_AICreateEnrouteATCAircraft
- SimConnect_AICreateNonATCAircraft
- SimConnect_AICreateParkedATCAircraft
- SimConnect_AICreateSimulatedObject
- SimConnect_AISetAircraftFlightPlan
- SimConnect_AIReleaseControlEx
SimConnect_AIReleaseControlEx
The SimConnect_AIReleaseControlEx 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. Optionally, this function can be used to completely remove the AI instead of clearing it. Removing the AI will allow for complete manual control of a SimConnect SimObject.
Syntax
HANDLE hSimConnect,
SIMCONNECT_OBJECT_ID ObjectID,
SIMCONNECT_DATA_REQUEST_ID RequestID
BOOL destroyAI = FALSE
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- ObjectID
- [in] Specifies the server defined object ID.
- RequestID
- [in] Specifies the client defined request ID.
- destroyAI
- [in, optional] Specifies whether to destory the AI or not (default value = 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. |
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 API Reference
- SimConnect_AICreateEnrouteATCAircraft
- SimConnect_AICreateNonATCAircraft
- SimConnect_AICreateParkedATCAircraft
- SimConnect_AICreateSimulatedObject
- SimConnect_AISetAircraftFlightPlan
SimConnect_AIRemoveObject
The SimConnect_AIRemoveObject function is used to remove any object created by the client using one of the SimConnect AI creation functions.
Syntax
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 API Reference
- SimConnect_AICreateEnrouteATCAircraft
- SimConnect_AICreateNonATCAircraft
- SimConnect_AICreateParkedATCAircraft
- SimConnect_AICreateSimulatedObject
SimConnect_AISetAircraftFlightPlan
The SimConnect_AISetAircraftFlightPlan function is used to set or change the flight plan of an AI controlled aircraft.
Syntax
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 Prepar3D v3 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. |
Working 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
- SimConnect API Reference
- SimConnect_AICreateEnrouteATCAircraft
- SimConnect_AICreateNonATCAircraft
- SimConnect_AICreateParkedATCAircraft
SimConnect_AISetGroundClamp
The SimConnect_AISetGroundClamp function is used to enable/disable ground clamping on a SimConnect owned SimObject.
Syntax
HANDLE hSimConnect,
SIMCONNECT_OBJECT_ID ObjectID,
BOOL bGroundClamp,
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- ObjectID
- [in] Specifies the server defined object ID.
- bGroundClamp
- [in] Boolean value that specifies if Ground Clamping should be enabled or disabled for the specified ObjectID. Ground Clamping keeps the object from being pushed below ground level.
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 API Reference
- SimConnect_AICreateEnrouteATCAircraft
- SimConnect_AICreateNonATCAircraft
- SimConnect_AICreateParkedATCAircraft
- SimConnect_AICreateSimulatedObject
- SimConnect_AICreateObjectWithExternalSim
Camera Specific Functions
SimConnect_CameraSetRelative6DOF
The SimConnect_CameraSetRelative6DOF function is used to adjust the user's aircraft view camera.
Syntax
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. |
Working 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_CameraSetRelative6DofByName
The SimConnect_CameraSetRelative6DofByName function is used to adjust the specified view's camera.
Syntax
HANDLE hSimConnect,
const char* szName,
float fDeltaX,
float fDeltaY,
float fDeltaZ,
float fPitchDeg,
float fBankDeg,
float fHeadingDeg
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the camera. This can either match the window title or the name of the camera definition. If the window title is used only the camera for that window will be modified. If the camera definition name is used and more than one window is open corresponding to that definition than all of those windows will be modified.
- 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. |
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_SetCameraSensorMode
The SimConnect_SetCameraSensorMode function is used to change a specific camera's sensor mode.
Syntax
HANDLE hSimConnect,
const char* szName,
SIMCONNECT_CAMERA_SENSOR_MODE eSensorMode
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the camera. This should equal the camera definition name.
- eSensorMode
- [in] The sensor mode.
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_SetMainCameraSensorMode
The SimConnect_SetMainCameraSensorMode function is used to change the main camera's sensor mode.
Syntax
HANDLE hSimConnect,
SIMCONNECT_CAMERA_SENSOR_MODE eSensorMode
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- eSensorMode
- [in] The sensor mode.
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_CreateCameraDefinition
The SimConnect_CreateCameraDefinition function is used to create a new camera definition.
Syntax
HANDLE hSimConnect,
GUID guidCamera,
SIMCONNECT_CAMERA_TYPE szViewType,
const char* sztitle,
SIMCONNECT_DATA_XYZ xyzBias,
SIMCONNECT_DATA_PBH pbhBias
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- guidCamera
- [in] GUID a unique identifier for a new camera defintion.
- szViewType
- [in] The type of view to create. See SIMCONNECT_CAMERA_TYPE.
- sztitle
- [in] Null-terminated string containing the title of the camera.
- xyzBias
- [in] SIMCONNECT_DATA_XYZ containing the offset from the origin.
- pbhBias
- [in] SIMCONNECT_DATA_PBH containing the orientation of the camera.
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. |
Working Samples
Primary samples |
Camera System |
See Also
- SimConnect API Reference
- SimConnect_DeleteCameraInstance
- SimConnect_CreateCameraInstance
- SIMCONNECT_CAMERA_TYPE
SimConnect_CreateCameraInstance
The SimConnect_CreateCameraInstance function is used to create a new camera instance based on a camera definition.
Syntax
HANDLE hSimConnect,
GUID guidCamera,
const char* szName,
SIMCONNECT_OBJECT_ID dwObjectID,
SIMCONNECT_REQUEST_ID RequestID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- guidCamera
- [in] GUID a unique identifier of a already created camera defintion.
- szName
- [in] Null-terminated string containing the name of the camera instance.
- dwObjectID
- [in] SIMCONNECT_OBJECT_ID containing the objectID of the SimObject to attach to the camera. Used with SIMCONNECT_CAMERA_TYPE SIMCONNECT_CAMERA_TYPE_OBJECT_AI_VIRTUAL.
- RequestID
- [in] SIMCONNECT_REQUEST_ID containing the 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. |
Working Samples
Primary samples |
Camera System |
See Also
- SimConnect API Reference
- SimConnect_CreateCameraDefinition
- SimConnect_DeleteCameraInstance
- SIMCONNECT_CAMERA_TYPE
SimConnect_DeleteCameraInstance
The SimConnect_DeleteCameraInstance function is used to remove a camera instance.
Syntax
HANDLE hSimConnect,
GUID guidCamera,
UINT32 instanceId
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- guidCamera
- [in] GUID a unique identifier of a already created camera defintion.
- instanceId
- [in] UINT32 containing the camera instance identifier.
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 API Reference
- SimConnect_CreateCameraDefinition
- SimConnect_CreateCameraInstance
- SIMCONNECT_CAMERA_TYPE
SimConnect_SetCameraHorizontalFov
The SimConnect_SetCameraHorizontalFov function is used to adjust the specified camera's horizontal field of view.
Syntax
HANDLE hSimConnect,
const char* szName,
float hFov
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the camera. This can either match the window title or the name of the camera definition. If the window title is used only the camera for that window will be modified. If the camera definition name is used and more than one window is open corresponding to that definition than all of those windows will be modified.
- hFov
- [in] Float containing the new horizontal FoV. The range of allowable values is between 0 and 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. |
See Also
SimConnect_SetCameraVerticalFov
The SimConnect_SetCameraVerticalFov function is used to adjust the specified camera's vertical field of view.
Syntax
HANDLE hSimConnect,
const char* szName,
float vFov
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the camera. This can either match the window title or the name of the camera definition. If the window title is used only the camera for that window will be modified. If the camera definition name is used and more than one window is open corresponding to that definition than all of those windows will be modified.
- vFov
- [in] Float containing the new vertical FoV. The range of allowable values is between 0 and 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. |
See Also
SimConnect_SetCameraFov
The SimConnect_SetCameraFov function is used to adjust the specified camera's field of view.
Syntax
HANDLE hSimConnect,
const char* szName,
float hFov,
float vFov
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the camera. This can either match the window title or the name of the camera definition. If the window title is used only the camera for that window will be modified. If the camera definition name is used and more than one window is open corresponding to that definition than all of those windows will be modified.
- hFov
- [in] Float containing the new horizontal FoV. The range of allowable values is between 0 and 180 degrees.
- vFov
- [in] Float containing the new vertical FoV. The range of allowable values is between 0 and 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. |
See Also
SimConnect_SetMainCameraHorizontalFov
The SimConnect_SetMainCameraHorizontalFov function is used to adjust the main camera's horizontal field of view.
Syntax
HANDLE hSimConnect,
float hFov
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- hFov
- [in] Float containing the new horizontal FoV. The range of allowable values is between 0 and 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. |
See Also
SimConnect_SetMainCameraVerticalFov
The SimConnect_SetMainCameraVerticalFov function is used to adjust the main camera's vertical field of view.
Syntax
HANDLE hSimConnect,
float vFov
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- vFov
- [in] Float containing the new vertical FoV. The range of allowable values is between 0 and 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. |
See Also
SimConnect_SetMainCameraFov
The SimConnect_SetMainCameraFov function is used to adjust the main camera's field of view.
Syntax
HANDLE hSimConnect,
float hFov,
float vFov
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- hFov
- [in] Float containing the new horizontal FoV. The range of allowable values is between 0 and 180 degrees.
- vFov
- [in] Float containing the new vertical FoV. The range of allowable values is between 0 and 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. |
See Also
SimConnect_CameraZoomIn
The SimConnect_CameraZoomIn function is used to adjust the zoom of the specified camera.
Syntax
HANDLE hSimConnect,
const char* szName
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the camera. This can either match the window title or the name of the camera definition. If the window title is used only the camera for that window will be modified. If the camera definition name is used and more than one window is open corresponding to that definition than all of those windows will be modified.
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_CameraZoomOut
The SimConnect_CameraZoomOut function is used to adjust the zoom of the specified camera.
Syntax
HANDLE hSimConnect,
const char* szName
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the camera. This can either match the window title or the name of the camera definition. If the window title is used only the camera for that window will be modified. If the camera definition name is used and more than one window is open corresponding to that definition than all of those windows will be modified.
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_MainCameraZoomIn
The SimConnect_MainCameraZoomIn function is used to adjust the zoom of the main camera.
Syntax
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. |
See Also
SimConnect_MainCameraZoomOut
The SimConnect_MainCameraZoomOut function is used to adjust the zoom of the main camera.
Syntax
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. |
See Also
SimConnect_ChangeView
The SimConnect_ChangeView function is used to change the camera on the main view.
Syntax
HANDLE hSimConnect,
const char* szName
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the camera to switch to.
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_OpenView
The SimConnect_OpenView function is used to open a new view.
Syntax
HANDLE hSimConnect,
const char* szName
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the view to open.
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. |
Working Samples
Primary samples |
Camera System |
See Also
SimConnect_CloseView
The SimConnect_CloseView function is used to close a view.
Syntax
HANDLE hSimConnect,
const char* szName
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the view to close.
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_UndockView
The SimConnect_UndockView function is used to undock a view.
Syntax
HANDLE hSimConnect,
const char* szName
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the view to undock.
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. |
Working Samples
Primary samples |
Camera System |
See Also
SimConnect_DockView
The SimConnect_DockView function is used to dock a view.
Syntax
HANDLE hSimConnect,
const char* szName
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the view to dock.
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. |
Working Samples
Primary samples |
Camera System |
See Also
SimConnect_SetCameraWindowPosition
The SimConnect_SetCameraWindowPosition function is used to set the window position of a view.
Syntax
HANDLE hSimConnect,
const char* szName,
UINT uX,
UINT uY
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the view to move.
- uX
- [in] New x position of the view.
- uY
- [in] New y position of the view.
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. |
Working Samples
Primary samples |
Camera System |
See Also
SimConnect_SetCameraWindowSize
The SimConnect_SetCameraWindowSize function is used to set the window size of a view.
Syntax
HANDLE hSimConnect,
const char* szName,
UINT uWidth,
UINT uHeight
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the view to size.
- uWidth
- [in] New width of the view.
- uHeight
- [in] New height of the view.
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. |
Working Samples
Primary samples |
Camera System |
See Also
SimConnect_AddPostProcess
The SimConnect_AddPostProcess function is used to apply a post process effect to the specified camera.
Syntax
HANDLE hSimConnect,
const char* szCameraName,
const char* szPostProcessName
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szCameraName
- [in] The name of the camera. This can either match the window title or the name of the camera definition. If the window title is used only the camera for that window will be modified. If the camera definition name is used and more than one window is open corresponding to that definition than all of those windows will be modified.
- szPostProcessName
- [in] The name of the post process effect.
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 API Reference
- SimConnect_AddPostProcessMainCamera
- SimConnect_RemovePostProcess
- SimConnect_RemovePostProcessMainCamera
SimConnect_AddPostProcessMainCamera
The SimConnect_AddPostProcessMainCamera function is used to apply a post process effect to the main camera.
Syntax
HANDLE hSimConnect,
const char* szPostProcessName
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szPostProcessName
- [in] The name of the post process effect.
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 API Reference
- SimConnect_AddPostProcess
- SimConnect_RemovePostProcess
- SimConnect_RemovePostProcessMainCamera
SimConnect_RemovePostProcess
The SimConnect_RemovePostProcess function is used to remove a post process effect from the specified camera.
Syntax
HANDLE hSimConnect,
const char* szCameraName,
const char* szPostProcessName
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szCameraName
- [in] The name of the camera. This can either match the window title or the name of the camera definition. If the window title is used only the camera for that window will be modified. If the camera definition name is used and more than one window is open corresponding to that definition than all of those windows will be modified.
- szPostProcessName
- [in] The name of the post process effect.
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 API Reference
- SimConnect_AddPostProcess
- SimConnect_AddPostProcessMainCamera
- SimConnect_RemovePostProcessMainCamera
SimConnect_RemovePostProcessMainCamera
The SimConnect_RemovePostProcessMainCamera function is used to remove a post process effect from the main camera.
Syntax
HANDLE hSimConnect,
const char* szPostProcessName
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szPostProcessName
- [in] The name of the post process effect.
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 API Reference
- SimConnect_AddPostProcess
- SimConnect_RemovePostProcessMainCamera
- SimConnect_RemovePostProcess
SimConnect_CameraSmoothRelative6DOF
The SimConnect_CameraSmoothRelative6DOF function is used to smoothly transition the view of the main camera to the specified location.
Syntax
HANDLE hSimConnect,
float fDeltaX,
float fDeltaY,
float fDeltaZ,
float fPitchDeg,
float fBankDeg,
float fHeadingDeg,
float fSmoothPanTime = 0
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- fDeltaX
- [in] The new x position of the camera relative to the origin in meters. Valid range: -100.0 - 100.0.
- fDeltaY
- [in] The new y position of the camera relative to the origin in meters. Valid range: -100.0 - 100.0.
- fDeltaZ
- [in] The new z position of the camera relative to the origin in meters. Valid range: -100.0 - 100.0.
- fPitchDeg
- [in] The new pitch of the camera relative to the origin in degrees. Valid range: -90.0 - 90.0.
- fBankDeg
- [in] The new bank of the camera relative to the origin in degrees. Valid range: -90.0 - 90.0.
- fHeadingDeg
- [in] The new heading of the camera relative to the origin in degrees. Valid range: -90.0 - 90.0.
- fSmoothPanTime
- [in, optional] The camera pan duration. If no value is specified the value defined in the Cameras.cfg will be used (defaults to 1.0f).
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 API Reference
- SimConnect_CameraSmoothRelative6DofByName
- SimConnect_CameraPanToView
- SimConnect_MainCameraPanToView
SimConnect_CameraSmoothRelative6DofByName
The SimConnect_CameraSmoothRelative6DofByName function is used to smoothly transition the view of the specified camera to the specified location.
Syntax
HANDLE hSimConnect,
const char* szCameraName,
float fDeltaX,
float fDeltaY,
float fDeltaZ,
float fPitchDeg,
float fBankDeg,
float fHeadingDeg,
float fSmoothPanTime = 0
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szCameraName
- [in] The name of the camera. This can either match the window title or the name of the camera definition. If the window title is used only the camera for that window will be modified. If the camera definition name is used and more than one window is open corresponding to that definition than all of those windows will be modified.
- fDeltaX
- [in] The new x position of the camera relative to the origin in meters. Valid range: -100.0 - 100.0.
- fDeltaY
- [in] The new y position of the camera relative to the origin in meters. Valid range: -100.0 - 100.0.
- fDeltaZ
- [in] The new z position of the camera relative to the origin in meters. Valid range: -100.0 - 100.0.
- fPitchDeg
- [in] The new pitch of the camera relative to the origin in degrees. Valid range: -90.0 - 90.0.
- fBankDeg
- [in] The new bank of the camera relative to the origin in degrees. Valid range: -90.0 - 90.0.
- fHeadingDeg
- [in] The new heading of the camera relative to the origin in degrees. Valid range: -90.0 - 90.0.
- fSmoothPanTime
- [in, optional] The camera pan duration. If no value is specified the value defined in the Cameras.cfg will be used (defaults to 1.0f).
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 API Reference
- SimConnect_CameraSmoothRelative6DOF
- SimConnect_CameraPanToView
- SimConnect_MainCameraPanToView
SimConnect_CameraPanToView
The SimConnect_CameraPanToView function is used to smoothly transition the view of the specified camera to the location of the specified target view.
Syntax
HANDLE hSimConnect,
const char* szCameraName,
const char* szTargetName,
float fSmoothPanTime = 0
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szCameraName
- [in] The name of the camera. This can either match the window title or the name of the camera definition. If the window title is used only the camera for that window will be modified. If the camera definition name is used and more than one window is open corresponding to that definition than all of those windows will be modified.
- szTargetName
- [in] The name of the target view.
- fSmoothPanTime
- [in, optional] The camera pan duration. If no value is specified the value defined in the Cameras.cfg will be used (defaults to 1.0f).
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 API Reference
- SimConnect_CameraSmoothRelative6DOF
- SimConnect_CameraSmoothRelative6DofByName
- SimConnect_MainCameraPanToView
SimConnect_MainCameraPanToView
The SimConnect_MainCameraPanToView function is used to smoothly transition the view of the main camera to the location of the specified target view.
Syntax
HANDLE hSimConnect,
const char* szTargetName,
float fSmoothPanTime = 0
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szTargetName
- [in] The name of the target view.
- fSmoothPanTime
- [in, optional] The camera pan duration. If no value is specified the value defined in the Cameras.cfg will be used (defaults to 1.0f).
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 API Reference
- SimConnect_CameraSmoothRelative6DOF
- SimConnect_CameraSmoothRelative6DofByName
- SimConnect_CameraPanToView
SimConnect_SendCameraCommand
The SimConnect_SendCameraCommand function is used to simulate user inputs to control camera movement and rotation.
Syntax
HANDLE hSimConnect,
cconst GUID guidCamera,
SIMCONNECT_CAMERA_COMMAND eCommand
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- guidCamera
- [in] The GUID of the camera to move/rotate.
- eCommand
- [in] The SIMCONNECT_CAMERA_COMMAND that defines which user input is simulated.
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_RequestCameraFov
The SimConnect_RequestCameraFov function is used to request the field-of-view of the given camera.
Syntax
HANDLE hSimConnect,
const char* szName,
SIMCONNECT_DATA_REQUEST_ID RequestID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the camera to request data from.
- 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. |
See Also
- SimConnect API Reference
- SimConnect_RequestMainCameraFov
- SimConnect_SetCameraFov
- SimConnect_SetMainCameraFov
SimConnect_RequestCameraRelative6DOF
The SimConnect_RequestCameraRelative6DOF function is used to request the XYZ delta offset from the eyepoint reference point in meters, as well as the pitch, bank, and heading in degrees of the main view.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- 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. |
See Also
- SimConnect API Reference
- SimConnect_CameraSetRelative6DOF
- SimConnect_CameraSetRelative6DofByName
- SimConnect_RequestCameraRelative6DofByName
SimConnect_RequestCameraRelative6DofByName
The SimConnect_RequestCameraRelative6DofByName function is used to request the XYZ delta offset from the eyepoint reference point in meters, as well as the pitch, bank, and heading in degrees of a given view.
Syntax
HANDLE hSimConnect,
const char* szName,
SIMCONNECT_DATA_REQUEST_ID RequestID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the camera to request data from.
- 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. |
See Also
- SimConnect API Reference
- SimConnect_CameraSetRelative6DOF
- SimConnect_CameraSetRelative6DofByName
- SimConnect_RequestCameraRelative6DOF
SimConnect_RequestCameraSensorMode
The SimConnect_RequestCameraSensorMode function is used to request the current sensor mode of a given view.
Syntax
HANDLE hSimConnect,
const char* szName,
SIMCONNECT_DATA_REQUEST_ID RequestID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the camera to request data from.
- 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. |
See Also
- SimConnect API Reference
- SimConnect_RequestMainCameraSensorMode
- SimConnect_SetCameraSensorMode
- SimConnect_SetMainCameraSensorMode
SimConnect_RequestCameraWindowPosition
The SimConnect_RequestCameraWindowPosition function is used to request the current window position of a given view.
Syntax
HANDLE hSimConnect,
const char* szName,
SIMCONNECT_DATA_REQUEST_ID RequestID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the camera to request data from.
- 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. |
See Also
- SimConnect API Reference
- SimConnect_RequestCameraWindowSize
- SimConnect_SetCameraWindowPosition
- SimConnect_SetCameraWindowSize
SimConnect_RequestCameraWindowSize
The SimConnect_RequestCameraWindowSize function is used to request the current window size of a given view.
Syntax
HANDLE hSimConnect,
const char* szName,
SIMCONNECT_DATA_REQUEST_ID RequestID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the camera to request data from.
- 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. |
See Also
- SimConnect API Reference
- SimConnect_RequestCameraWindowPosition
- SimConnect_SetCameraWindowPosition
- SimConnect_SetCameraWindowSize
SimConnect_RequestMainCameraFov
The SimConnect_RequestMainCameraFov is used to request the field-of-view of the main view (horizontal and vertical).
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- 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. |
See Also
- SimConnect API Reference
- SimConnect_RequestCameraFov
- SimConnect_SetCameraFov
- SimConnect_SetMainCameraFov
SimConnect_RequestMainCameraSensorMode
The SimConnect_RequestMainCameraSensorMode function is used to request teh current sensor mode of the main view.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- 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. |
See Also
- SimConnect API Reference
- SimConnect_RequestCameraSensorMode
- SimConnect_SetCameraSensorMode
- SimConnect_SetMainCameraSensorMode
SimConnect_CaptureImage
The SimConnect_CaptureImage function is used to capture the image of a specific view.
Syntax
HANDLE hSimConnect,
const char* szFileName,
const char* szFilePath,
UINT uImageFormat,
const char* szViewName
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szFileName
- [in] The name of the file to store image.
- szFilePath
- [in] The path of the file, can be relative or absolute.
- uImageFormat
- [in] Specifies the format of the image. Formats: 0 BMP, 1 PNG, 2 JPEG, 3 TIFF.
- szViewName
- [in] The name of the window to capture the image.
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_BeginVideoStream
The SimConnect_BeginVideoStream function is used to begin network streaming video of a specific view.
Syntax
HANDLE hSimConnect,
const char * szViewName,
SIMCONNECT_DATA_VIDEO_STREAM_INFO StreamInfo
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szViewName
- [in] Name of view. If null, default or active view will be used.
- StreamInfo
- [in] Struct containing information about the video stream
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_DATA_VIDEO_STREAM_INFO
- SimConnect_EndVideoStream
- SimConnect_OpenView
- SimConnect_CloseView
- SimConnect_ChangeView
SimConnect_EndVideoStream
The SimConnect_EndVideoStream function is used to end network streaming video of a specific view.
Syntax
HANDLE hSimConnect,
const char * szViewName,
SIMCONNECT_DATA_VIDEO_STREAM_INFO StreamInfo
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szViewName
- [in] Name of view. If null, default or active view will be used.
- StreamInfo
- [in] Struct containing information about the video stream
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_DATA_VIDEO_STREAM_INFO
- SimConnect_BeginVideoStream
- SimConnect_OpenView
- SimConnect_CloseView
- SimConnect_ChangeView
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
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. |
Working Sample
Primary sample | FacilitiesData |
Reference sample | Managed Facilities Request |
Remarks
The simulation keeps a facilities cache of all the airports, waypoints, NDB, VOR, and TACAN 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:
- SIMCONNECT_RECV_AIRPORT_LIST, which will contain a list of SIMCONNECT_DATA_FACILITY_AIRPORT structures.
- SIMCONNECT_RECV_NDB_LIST, which will contain a list of SIMCONNECT_DATA_FACILITY_NDB structures.
- SIMCONNECT_RECV_VOR_LIST, which will contain a list of SIMCONNECT_DATA_FACILITY_VOR structures.
- SIMCONNECT_RECV_TACAN_LIST, which will contain a list of SIMCONNECT_DATA_FACILITY_TACAN structures.
- SIMCONNECT_RECV_WAYPOINT_LIST, which will contain a list of SIMCONNECT_DATA_FACILITY_WAYPOINT 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
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. |
Working 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
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. |
Working 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
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. |
Working 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
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_MenuAddItem
- SimConnect_MenuDeleteItem
- SimConnect_MenuDeleteSubItem
- SimConnect API Reference
SimConnect_MenuDeleteItem
The SimConnect_MenuDeleteItem function is used to remove a client defined menu item.
Syntax
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. |
Working 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
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, message window, or scrolling or static text, on the screen.
Syntax
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, message, or menu in seconds. If zero is entered, the text, message, or menu will not timeout. For text and messages, 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, and 5 seconds for message windows. These can be changed in the [SimConnect] section of Prepar3D.cfg file using the TextMinPrintTimeSeconds, TextMinScrollTimeSeconds, and TextMinMessageWindowTimeSeconds 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 and message windows 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. |
Working Sample
Primary samples |
Text Menu FacilitiesData |
Remarks
Message windows, text, and menus can all be displayed simultaneously, however only one instance of each is allowed at any given 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 message windows and 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
Structured Scenario Specific Functions
SimConnect_CompleteCustomMissionAction
The SimConnect_CompleteCustomMissionAction function is used to complete the scenario action specified by a GUID.
Syntax
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 object 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. |
Working Sample
Primary sample | Mission Action |
Remarks
A scenario's objects are specified in an XML file. A custom action is defined within this XML file, and will look similar to the following:
<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 scenario system.
The custom action would typically be triggered from within the object 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 working 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 scenario 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 scenario action specified by a GUID.
Syntax
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 object 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. |
Working Sample
Primary sample | Mission Action |
Remarks
A scenario's objects are specified in an XML file.
In order to use SimConnect_ExecuteMissionAction, typically there should be at least one custom action within the object 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
- SimConnect_CompleteCustomMissionAction
- SIMCONNECT_RECV_CUSTOM_ACTION
- SimConnect_SubscribeToSystemEvent
- SimConnect API Reference
Weather Specific Functions
SimConnect_WeatherCreateStation
The SimConnect_WeatherCreateStation function creates a weather station at the given ICAO location.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID,
const char* szICAO,
const char* szName,
float lat,
float lon,
float alt
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- RequestID
- [in] Specifies the client defined request ID.
- szICAO
- [in] Specifies the ICAO string. This can be an existing airport ICAO string, as long as the airport does not already have a weather station, or it can be a unique new ICAO code to be used just for the purposes of this weather station.
- szName
- [in] Specifies a descriptive name for the new weather station. This name will appear on the weather map in the weather dialogs of Prepar3D.
- lat
- [in] Specifies the latitude of the station in degrees. The latitude, longitude and altitude parameters should be set to 0 if the ICAO code supplied is from an existing airport.
- lon
- [in] Specifies the longitude of the station in degrees.
- alt
- [in] Specifies the altitude of the station in feet, above ground level.
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 an attempt is made to create a weather station at an airport that already has one, the error SIMCONNECT_EXCEPTION_WEATHER_UNABLE_TO_CREATE_STATION will be returned.
Once a weather station has been successfully created, its weather output can be set with a call to SimConnect_WeatherSetObservation, and retrieved with a call to SimConnect_WeatherRequestObservationAtStation.
See Also
SimConnect_WeatherCreateThermal
The SimConnect_WeatherCreateThermal function is used to create a thermal at a specific location.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID,
float lat,
float lon,
float alt,
float radius,
float height,
float coreRate = 3.0f,
float coreTurbulence = 0.05f,
float sinkRate = 3.0f,
float sinkTurbulence = 0.2f,
float coreSize = 0.4f,
float coreTransitionSize = 0.1f,
float sinkLayerSize = 0.4f,
float sinkTransitionSize = 0.1f
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- RequestID
- [in] Specifies the client defined request ID.
- lat
- [in] Specifies the latitude of the thermal in degrees.
- lon
- [in] Specifies the longitude of the thermal in degrees.
- alt
- [in] Specifies the altitude of the thermal in feet, above ground level.
- radius
- [in] Specifies the radius of the thermal, in meters. The maximum radius of a thermal is 100Km.
- height
- [in] Specifies the height of the thermal, in meters.
- coreRate
- [in, optional] Specifies the lift value, in meters per second, within the Core layer. A positive value will provide an updraft, a negative value a downdraft. The maximum rate is 1000 meters/second. Refer to the diagram in the Remarks section.
- coreTurbulence
- [in, optional] Specifies a variation in meters per second that is applied to the coreRate. For example, if a value of 1.5 is entered, and the core rate is 5 m/s, the actual core rate applied will be randomly varying between 3.5 m/s and 6.5 m/s.
- sinkRate
- [in, optional] Specifies the lift value, in meters per second, within the Sink layer. A positive value will provide an updraft, a negative value a downdraft. The maximum rate is 1000 meters/second. Refer to the diagram in the Remarks section.
- coreTurbulence
- [in, optional] Specifies a variation in meters per second that is applied to the sinkRate. For example, if a value of 1.5 is entered, and the sink rate is 5 m/s, the actual sink rate applied will be randomly varying between 3.5 m/s and 6.5 m/s.
- coreSize
- [in, optional] Specifies the radius in meters of the Core of the thermal.
- coreTransitionSize
- [in, optional] Specifies the width in meters of the transition layer between the Core and the Sink of the thermal. Half of the width of this transition will be outside the Core, and half within.
- sinkSize
- [in, optional] Specifies the radius in meters of the Sink of the thermal.
- sinkTransitionSize
- [in, optional] Specifies the width in meters of the transition layer between the Sink and the atmosphere outside of the thermal. Half of the width of this transition will be outside the radius of the Sink layer, and half within.
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
There is no limit to the number of thermals that can be created. Within the simulator a thermal is defined as a cylinder with a Core layer and a Sink layer:
Refer also to the Weather Systems documentation.
See Also
- SimConnect API Reference
- SimConnect_WeatherRemoveThermal
- SimConnect_WeatherRequestInterpolatedObservation
- SimConnect_WeatherRequestObservationAtStation
- SimConnect_WeatherRequestObservationAtNearestStation
- SimConnect_WeatherSetObservation
SimConnect_WeatherRemoveStation
The SimConnect_WeatherRemoveStation function requests that the weather station identified by the given ICAO string is removed.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID,
const char* szICAO
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- RequestID
- [in] Specifies the client defined request ID.
- szICAO
- [in] Specifies the ICAO string of the station to remove. The station must be one that was created by the same SimConnect client.
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 call is made to remove a weather station created by another client, or an exiting one within the simulation, the error SIMCONNECT_EXCEPTION_WEATHER_UNABLE_TO_REMOVE_STATION will be returned.
If the client is closed, then all weather stations created by the client will be removed.
See Also
SimConnect_WeatherRemoveThermal
The SimConnect_WeatherRemoveThermal function removes a thermal.
Syntax
HANDLE hSimConnect,
SIMCONNECT_OBJECT_ID ObjectID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- ObjectID
- [in] Specifies the object ID of the thermal to be 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. |
Remarks
A client application can only remove thermals that it created, and not thermals created by other clients or by the simulation itself. If the client is closed, then all thermals created by the client will be removed.
See Also
- SimConnect API Reference
- SimConnect_WeatherCreateThermal
- SimConnect_WeatherRequestInterpolatedObservation
- SimConnect_WeatherRequestObservationAtStation
- SimConnect_WeatherRequestObservationAtNearestStation
- SimConnect_WeatherSetObservation
SimConnect_WeatherRequestCloudState
The SimConnect_WeatherRequestCloudState function requests cloud density information on a given area.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID,
float minLat,
float minLon,
float minAlt,
float maxLat,
float maxLon,
float maxAlt,
DWORD dwFlags = 0
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- RequestID
- [in] Specifies the client-defined request ID.
- minLat
- [in] Specifies the minimum latitude of the required area. This should simply be the lower of the two latitude numbers.
- minLon
- [in] Specifies the minimum longitude of the required area. This should simply be the lower of the two longitude numbers.
- minAlt
- [in] Specifies the minimum altitude of the required area, in feet.
- maxLat
- [in] Specifies the maximum latitude of the required area.
- maxLon
- [in] Specifies the maximum longitude of the required area.
- maxAlt
- [in] Specifies the maximum altitude of the required area, in feet.
- dwFlags
- [in, optional] Double word containing any flags. 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
The main purpose of this function is to enable weather radar.
If the call is successful, the cloud state information will be returned in a SIMCONNECT_RECV_CLOUD_STATE structure. This structure will contain a two dimensional array of byte data. The array will be 64 x 64 bytes in size, and each byte will contain a value indicating the cloud layer density for each cell. A value of zero would mean no cloud layers, to a maximum of 255 layers. The area defined in this call is divided into 64 by 64 cells, so the size of each cell will be determined by the values given for the parameters above. Note that the entire World's weather is not simulated all the time, but only a region around the user aircraft, with a radius of approximately 128 kilometers, is modeled at any one time. A request for cloud data outside this region will simply return zeros.
The defined area can cross the Equator or the Greenwich Meridian, but it cannot cross the Poles or the International Date Line.
See Also
- SimConnect_WeatherSetDynamicUpdateRate
- SimConnect_WeatherSetModeCustom
- SimConnect_WeatherSetModeGlobal
- SimConnect_WeatherSetModeTheme
- SimConnect API Reference
SimConnect_WeatherRequestInterpolatedObservation
The SimConnect_WeatherRequestInterpolatedObservation function is used to send a request for weather data that is interpolated from the weather at the nearest three weather stations.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID,
float lat,
float lon,
float alt
);
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.
- lat
- [in] Specifies latitude in degrees.
- lon
- [in] Specifies longitude in degrees.
- alt
- [in] Specifies altitude in feet above sea level. This differs from most weather data altitudes, which are feet above ground level.
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_WeatherRequestInterpolatedObservation(hSimConnect, dwRequestID, -80.0, 44.0, 10000);
Remarks
The weather data will be returned in a SIMCONNECT_RECV_WEATHER_OBSERVATION structure. A number of errors apply specifically to weather data, see the SIMCONNECT_RECV_EXCEPTION enumeration.
Interpolated weather data can be used to identify suitable locations for thermals and other local weather systems. The process of using the three nearest stations is not without its drawbacks, as all three stations could be in one direction of the specified point, and not a reasonable spread in different directions. Weather data is returned in Metar data format.
Refer to the remarks section for SimConnect_WeatherRequestObservationAtStation for some notes on the SIMCONNECT_EXCEPTION_WEATHER_UNABLE_TO_GET_OBSERVATION exception.
See Also
- SimConnect_WeatherRequestObservationAtStation
- SimConnect_WeatherRequestObservationAtNearestStation
- SimConnect_WeatherSetObservation
- SimConnect API Reference
SimConnect_WeatherRequestObservationAtNearestStation
The SimConnect_WeatherRequestObservationAtNearestStation function is used to send a request for the weather data from the weather station nearest to the specified lat/lon position.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID,
float lat,
float lon
);
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.
- lat
- [in] Specifies latitude in degrees.
- lon
- [in] Specifies longitude 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. |
Example
hr = SimConnect_WeatherRequestObservationAtNearestStation(hSimConnect, dwRequestID, -80.0, 44.0);
Working Sample
Primary sample | Weather Station |
Remarks
The weather data will be returned in a SIMCONNECT_RECV_WEATHER_OBSERVATION structure. A number of errors apply specifically to weather data, see the SIMCONNECT_RECV_EXCEPTION enumeration. Weather data is returned in Metar data format.
Refer to the remarks section for SimConnect_WeatherRequestObservationAtStation for some notes on the SIMCONNECT_EXCEPTION_WEATHER_UNABLE_TO_GET_OBSERVATION exception.
See Also
- SimConnect_WeatherRequestInterpolatedObservation
- SimConnect_WeatherRequestObservationAtStation
- SimConnect_WeatherSetObservation
- SimConnect API Reference
SimConnect_WeatherRequestObservationAtStation
The SimConnect_WeatherRequestObservationAtStation function requests the weather data from a weather station identified by its ICAO code.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID,
const char* szICAO
);
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.
- szICAO[4]
- [in] Null-terminated string specifying the ICAO identification code of the weather station. Typically this is an airport. Set to GLOB to retrieve global weather.
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_WeatherRequestObservationAtStation(hSimConnect, dwRequestID, "ICAO");
Remarks
The weather data will be returned in a SIMCONNECT_RECV_WEATHER_OBSERVATION structure. A number of errors apply specifically to weather data, see the SIMCONNECT_RECV_EXCEPTION enumeration. Weather data is returned in Metar data format.
The exception SIMCONNECT_EXCEPTION_WEATHER_UNABLE_TO_GET_OBSERVATION is returned in a number of cases, including that the station provided as a parameter does not exist. However there is one case where this exception is returned that a client should not treat as an error, and that is when the weather station does not have any valid data to return because it has not been recently updated with its current weather. In this case a client could keep polling for a weather observation until a valid metar string is returned. This could take 10 seconds or more, as there are certain situations when a user can reset the weather through the UI that clears many of the weather stations of their current weather, and it takes some time for the weather engine to regenerate all the weather settings.
See Also
- SimConnect_WeatherRequestInterpolatedObservation
- SimConnect_WeatherRequestObservationAtNearestStation
- SimConnect_WeatherSetObservation
- SimConnect API Reference
SimConnect_WeatherSetDynamicUpdateRate
The SimConnect_WeatherSetDynamicUpdateRate function is used to set the rate at which cloud formations change.
Syntax
HANDLE hSimConnect,
DWORD dwRate
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- dwRate
- [in] Double word containing the rate. A value of zero indicates that cloud formations do not change at all. Values between 1 and 5 indicate that cloud formations should change from 1 (the slowest) to 5 (the fastest). These settings match those than can be set through the dialogs of Prepar3D.
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_WeatherRequestCloudState
- SimConnect_WeatherSetModeCustom
- SimConnect_WeatherSetModeGlobal
- SimConnect_WeatherSetModeTheme
- SimConnect API Reference
SimConnect_WeatherSetModeCustom
The SimConnect_WeatherSetModeCustom function sets the weather mode to user-defined.
Syntax
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. |
Remarks
Calling this function sets the weather mode to "User-defined weather" in the Weather dialog of Prepar3D, so whatever the user has entered for the weather will be used.
See Also
- SimConnect_WeatherRequestCloudState
- SimConnect_WeatherSetDynamicUpdateRate
- SimConnect_WeatherSetModeGlobal
- SimConnect_WeatherSetModeTheme
- SimConnect API Reference
SimConnect_WeatherSetModeGlobal
The SimConnect_WeatherSetModeGlobal function sets the weather mode to global, so the same weather data is used everywhere.
Syntax
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. |
Remarks
There is not an equivalent setting in the weather dialog of Prepar3D.
See Also
- SimConnect_WeatherRequestCloudState
- SimConnect_WeatherSetDynamicUpdateRate
- SimConnect_WeatherSetModeCustom
- SimConnect_WeatherSetModeTheme
- SimConnect API Reference
SimConnect_WeatherSetModeServer
The SimConnect_WeatherSetModeServer function is used to switch to a local server for weather observation data. This has been deprecated.
Syntax
HANDLE hSimConnect,
DWORD dwPort,
DWORD dwSeconds
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- dwPort
- [in] Double word containing the port number of the weather server. Set this to zero to reset the weather to normal operation.
- dwSeconds
- [in] Double word containing the amount of time, in seconds, that should elapse between each update. There is a minimum of 60 seconds.
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
Deprecated.
See Also
- SimConnect_WeatherRequestCloudState
- SimConnect_WeatherRequestInterpolatedObservation
- SimConnect_WeatherRequestObservationAtStation
- SimConnect_WeatherRequestObservationAtNearestStation
- SimConnect_WeatherSetObservation
- SimConnect_WeatherSetDynamicUpdateRate
- SimConnect_WeatherSetModeCustom
- SimConnect_WeatherSetModeGlobal
- SimConnect_WeatherSetModeTheme
- SimConnect API Reference
SimConnect_WeatherSetModeTheme
The SimConnect_WeatherSetModeTheme function is used to set the weather to a particular theme.
Syntax
HANDLE hSimConnect,
const char* szThemeName
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szThemeName
[in] Null-terminated string containing the theme path and filename. The path can be either be:
- an absolute path (e.g. C:/Program Files (x86)/My Company/My Product/myweathertheme)
- a path relative to the Lockheed Martin/Prepar3D v3/ installation folder (e.g. weather/themes/grayrain)
- a path relative to any of the weather theme folders found in any of the weather.cfg configuration files (e.g. grayrain)
- An empty string to set clear weather
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
Calling this function sets the weather mode to "Weather themes" in the Weather dialog of Prepar3D.
There are three files associated with a weather theme, for example: grayrain.wt, grayrain.bmp and grayrain.wtb. The wt file contains the description that will appear in the Current Conditions box in the Weather dialog, the bmp file contains the image that will also appear in the weather dialog, and the wtb file contains data in a propriety format that contains the weather information.
See Also
- SimConnect_WeatherRequestCloudState
- SimConnect_WeatherSetDynamicUpdateRate
- SimConnect_WeatherSetModeCustom
- SimConnect_WeatherSetModeGlobal
- SimConnect API Reference
SimConnect_WeatherSetObservation
The SimConnect_WeatherSetObservation function is used to set the weather at a specific weather station, identified from within the Metar data string.
Syntax
HANDLE hSimConnect,
DWORD Seconds,
const char* szMETAR
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- Seconds
- [in] Specifies the time in seconds that the current weather should merge into the new weather. This delay only applies to clouds in a custom weather setting, not to global or other weather settings (where the change will take place almost immediately).
- pszMETAR
- [in] Null-terminated string containing the METAR 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
Commonly, a SimConnect_WeatherSetModeGlobal or SimConnect_WeatherSetModeCustom should be called after this function. SimConnect_WeatherSetModeGlobal and SimConnect_WeatherSetModeCustom allow the Weather Settings UI to be properly set.
When setting specific station observations, it is possible for station observations nearby the specified station to be automatically adjusted. The weather system interpolates and changes weather layers for surrounding stations to create a visually appropriate and logical environment. If exact replication of the METAR data is required, the station and surrounding stations can be set multiple times to force the interpolated values to match the desired METAR data.
A number of errors apply specifically to weather data, see the SIMCONNECT_RECV_EXCEPTION enumeration.
Metar Data Format
The data format used in the simulation for setting and retrieving weather is a modification to the Metar standard. The standard format is open and is described on a number of websites. The Metar data used in the simulation follows the following format. Note that each section is separated by a space, and that spaces cannot occur within a section (with one exception noted in the table). The sections must be in the correct order, though many are optional and need not be present.
Section | Format | Multiple Entries |
---|---|---|
STATION ID (has an extension) |
CCCC - a three or four character station ID. For example KORD for O'Hare
airport in Chicago. The string GLOB can be used to set global weather data. Prepar3D extension: Format is &ANNN This gives the height of the weather station in meters. This information is returned with a get observation, but when setting this extension must not be present. |
No |
REPORT TYPE | Either METAR or SPECI keywords. | No |
AUTO | Optional AUTO keyword, for a fully automated report. | No |
COR | Optional COR keyword, for a corrected report. | No |
DATETIME |
One of the following four formats (the exact number of characters must be present):
HHMM DDHHMM HHMMZ DDHHMMZ (all are UTC whether or not the Z is present). Note that this parameter is ignored when setting weather data. When getting the data, if it was set originally by the user through a SimConnect client or the Weather dialog then the time that it was set to will be returned. If the data was retrieved from a weather server, then the time stamp given to it by the server will be returned. |
No |
NIL | Optional NIL keyword, indicating that no weather report could be made. | No |
SURFACE WINDS (has an extension) |
One of the following two formats:
DDDSSSUUU (steady) DDDSSSGXXUUU (gusts) where: DDD = Direction (0-360 degrees, or VRB for variable) SSS = Speed XX = Gust speed UUU = Units, one of: KMH = Kilometers per hour KT = Knots MPS = Meters per second Prepar3D extension follows the "&" character Format of the extension is &DNNNNTS where NNNN is the depth (height) in meters. The default is 1000 feet or 305m. T part is turbulence, one of: N - None (default) O or L - Light M - Moderate H - Heavy S - Severe S part is wind shear, one of: G - Gradual (default) M - Moderate S - Steep I - Instantaneous The default extension would look like this: &D305NG |
No |
WINDS ALOFT (this section is an optional extension) |
Normal Metar strings do not contain winds aloft. However, you may specify this entry is an extension.
Winds aloft can be entered in one of two formats, but do not use both. This section is not a replacement for setting the surface winds. The first
format is slightly more flexible than the second, and should directly follow the SURFACE WINDS, the
second format should appear at the end of the metar string. The altitude of a WINDS ALOFT section specifies the top of the layer in which the given wind data is to apply. The bottom of the layer will be determined by the top of any lower layer, either another WINDS ALOFT entry, or the SURFACE WINDS entry. Format 1: This format is the same as the surface wind data format above except for the extension portion. Instead of specifying a surface layer depth, using &DNNNNTS, it specifies the altitude above the referenced weather station's altitude in meters. The extension format is &ANNNNTS. Format 2: @@@ A T D S | A T D S | ..... where A is altitude in 100s of feet (-1500 to 100000) T is temperature in Celsius (-250 to 100) D is direction in degrees (0 to 360) S is speed in knots (0 to 400) Note that there can be more than one WINDS ALOFT entry, typically giving different wind strengths and the other data, for a range of altitudes. |
Yes |
MIN MAX WIND DIR |
XXXVYYY XXX - start of heading range, in degrees YYY - end of heading range, in degrees This entry adds a variance in wind direction to the surface wind. |
No |
CAVOK | Optional CAVOK keyword (meaning Ceiling and Visibility OK). It indicates that no clouds exist below 5,000 feet or below the highest minimum sector altitude, whichever is greater, and no cumulonimbus are present. Also the visibility is 10 kilometers or more and, no precipitation, thunderstorms, sandstorm, duststorm, shallow fog, or low drifting dust, sand or snow is occurring. | No |
VISIBILITY (has an extension) |
Like winds aloft the visibility group can be repeated to describe multiple visibility
layers. There is also an extension to the format to allow layer base and depth to
be specified. Use one of the following formats: Statute Miles: M1/4SM or <1/4SM (visibility is less that a quarter of a statute mile) ISM (visibility is measured in an integer number of statue miles) N/DSM (visibility is measured as a fraction of a statue mile) I N/DSM (visibility is measured in a whole part and fraction of a statue mile) where I = Integer part N = Numerator D = Denominator The minimum fraction that can be entered is 1/8. Note that this is the only exception where a space can occur (between the I and the N) within a section. Kilometers: NNKM Meters: NNNND where D is directional variation, one of: NDV - no directional variation NE, NW, SE, SW, N, S, E, W - compass point M meters - same as NDV Prepar3D extension: Format is &BXXXX&DYYYY XXXX - base of visibility layer in meters YYYY - depth of visibility layer in meters |
Yes |
RUNWAY VISUAL RANGE |
Use one of the following two formats:
RDD/VVVVFT RDD/XXXXVYYYYFT where DD = Runway ID (1-6 characters) VVVV = Visual range in feet. May have P (above maximum) or M (below minimum) prefix (following the slash). XXXX = Varying minimum range in feet. YYYY = Varying maximum range in feet. |
Yes |
PRESENT CONDITIONS |
IDDPP where: I - Intensity or vicinity flag:. -, + or VC. - means light, + means severe, and VC means vicinity. The + and - can be combined with VC. Leave out a + or - to mean moderate. For example: +VCTSRA means severe thunderstorm with rain in the vicinity. DD - Descriptor, one of: MI shallow PR partial DC patches DR low drifting BL blowing SH shower TS thunderstorm FZ freezing PP - Phenomena, one of: DZ drizzle RA rain SN snow SG snow grains IC ice crystals PE ice pellets GR hail GS small hail/snow pellets UP unknown BR mist FG fog FU smoke VA volcanic ash DU dust SA sand HZ haze PY spray PO dust whirls SQ squalls FC funnel cloud/tornado/waterspout SS sandstorm DS duststorm |
Yes |
PARTIAL OBSCURATION |
One of:
FEW/// SCT/// BKN/// FEW000 SCT000 BKN000 These mean few, scattered or broken clouds are obscuring the view. |
No |
SKY CONDITIONS (has an extension) |
Note cloud heights are coded: If NNN is 999 the level is 100,000 feet, otherwise
it is 100 x NNN in feet.
CCCNNN Where NNN is the coded height, and CCC is one of:: CLR or SKC - sky clear FEW - few clouds SCT - scattered clouds BKN - broken clouds OVC - overcast NTT - N/8ths cloud coverage of type TT, which is one of: CI Cirrus CS Cirro-stratus (maps to CI) CC Cirro-cumulus (maps to CI) AS Alto-stratus (maps to ST) AC Alto-cumulus (maps to CU) SC Strato-cumulus (maps to CU) NS Nimbo-stratus (maps to ST) ST Stratus CU Cumulus CB Cumulo-nimbus Note that not all of these cloud types are supported, so a number are mapped to those which are. This does mean that a write followed by a read of Metar data might not give identical strings. Prepar3D extension: &TT000FTPQBBBI where: TT - Cloud type, one of: the list above (for example, CI or CB). If this entry is different from the NNN entry above, this entry will take priority. 000 - Unused. F - Top of cloud, one of: F (flat), R (round), A (anvil) T - Turbulence, one of: N - None (default), O - Light, L - Light, M - Moderate, H - Heavy, S - Severe P - Precipitation, one of: V (very light), L (light), M (moderate), H (heavy) D (dense) Q - Type of precipitation, one of: N (none), R (rain), F (freezing rain), H (hail), S (snow) BBB - Coded base height, the precipitation ends at this height, set to 0 for it to land on the ground I - icing rate, one of: N (none), T (trace), L (light), M (moderate), S (severe) |
No |
TEMPERATURE (has an extension) |
TT/DD TT - temperature in Celsius DD - dewpoint in Celsius Negative values should be preceded by a minus sign. Prepar3D extension: &ANNNNN - altitude of the temperatures in meters. |
Yes |
ALTIMETER |
One of: ANNNN - altimeter in degrees of mercury (for example, A2992) QNNNN - altimeter in millibars |
No |
@@@ | If these three characters are entered in the string, there is a WINDS ALOFT section following the metar string. |
Examples of Metar strings
Metar String | Description |
---|---|
KSEA 030405Z 27007KT 15SM SKC 17/13 A2992 |
KSEA = Station Identifier (Sea-Tac airport)
030405Z = Time (ddhhmmZ) 27007KT = Winds (270 degrees at 7 knots) 15SM = Visibility (15 statute miles) SKC = Clear skies 17/13 = Temperature /Dewpoint in Celsius A2992 = Altimeter setting (29.92 in Hg) |
KSEA COR 030405Z 27015KT 7SM +TSRA BKN055CB 30/17 A2974 | Corrected report, same time as above, with 15 knot winds, 7 miles of visibility, severe thunderstorm and rain, broken cumulo-nimbus clouds at 5500 feet. |
KSEA&A131 000000Z 00000KT&D985NG 100KM&B-581&D3048 2CU053&CU000FNMN-19N 15/05 Q1013 @@@ 65 15 270 20 | 196 15 270 25 | | Fair weather at Sea-Tac airport. Two eights cumulus clouds at 5300 feet, 20 knot West winds at 6500 feet, 25 knot West winds at 19600 feet. |
See Also
- SimConnect_WeatherRequestInterpolatedObservation
- SimConnect_WeatherRequestObservationAtStation
- SimConnect_WeatherRequestObservationAtNearestStation
- SimConnect_WeatherSetModeCustom
- SimConnect_WeatherSetModeGlobal
- SimConnect API Reference
Observer Specific Functions
SimConnect_CreateObserver
The SimConnect_CreateObserver function creates an observer using SIMCONNECT_DATA_OBSERVER.
Syntax
HANDLE hSimConnect,
const char* szName,
SIMCONNECT_DATA_OBSERVER ObserverData,
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] Specifies a descriptive name for the new observer view. This name will appear on the dialogs of Prepar3D.
- ObserverData
- [in] Specifies all data for the observer to be created.
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_RequestObserverData
- SimConnect_MoveObserver
- SimConnect_RotateObserver
- SimConnect_SetObserverPosition
- SimConnect_SetObserverRotation
- SimConnect_SetObserverLookAt
- SimConnect_SetObserverLookAtEx
- SimConnect_ObserverTrackLocationOn
- SimConnect_SetObserverFieldOfView
- SimConnect_SetObserverStepSize
- SimConnect_SetObserverFocalLength
- SimConnect_SetObserverFocusFixed
- SimConnect_SetObserverRegime
- SimConnect_SetObserverZoomLevels
- SimConnect_ObserverTrackEntityOn
- SimConnect_ObserverTrackEntityOff
SimConnect_RequestObserverData
The SimConnect_RequestObserverData function is used to retrieve information about an observer.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID,
const char* szName,
);
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.
- szName
- [in] Name of the observer view that data is being requested.
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 will return a SIMCONNECT_RECV_OBSERVER_DATA structure.
See Also
- SimConnect_CreateObserver
- SimConnect_MoveObserver
- SimConnect_RotateObserver
- SimConnect_SetObserverPosition
- SimConnect_SetObserverRotation
- SimConnect_SetObserverLookAt
- SimConnect_SetObserverLookAtEx
- SimConnect_ObserverTrackLocationOn
- SimConnect_SetObserverFieldOfView
- SimConnect_SetObserverStepSize
- SimConnect_SetObserverFocalLength
- SimConnect_SetObserverFocusFixed
- SimConnect_SetObserverRegime
- SimConnect_SetObserverZoomLevels
- SimConnect_ObserverTrackEntityOn
- SimConnect_ObserverTrackEntityOff
SimConnect_MoveObserver
The SimConnect_MoveObserver function moves an observer using an XYZ translation.
Syntax
HANDLE hSimConnect,
const char* szName,
SIMCONNECT_DATA_XYZ Translation,
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the observer view that should be updated. This name appears on the observer dialogs of Prepar3D.
- Translation
- [in] The xyz translation used to move the observer.
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_RotateObserver
The SimConnect_RotateObserver function rotates the specified observer view.
Syntax
HANDLE hSimConnect,
const char* szName,
DWORD dwAxis,
double dAngleDegrees,
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the observer view that should be updated. This name appears on the observer dialogs of Prepar3D.
- dwAxis
- [in] The axis to rotate around. SIMCONNECT_OBSERVER_AXIS_PITCH is 0, SIMCONNECT_OBSERVER_AXIS_ROLL is 1, and SIMCONNECT_OBSERVER_AXIS_YAW is 2.
- dAngleDegrees
- [in] The angle in degrees to rotate.
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_SetObserverPosition
The SimConnect_SetObserverPosition function creates an observer using SIMCONNECT_DATA_OBSERVER.
Syntax
HANDLE hSimConnect,
const char* szName,
SIMCONNECT_DATA_LATLONALT Position,
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the observer view that should be updated. This name appears on the observer dialogs of Prepar3D.
- Position
- [in] The xyz position to place the observer. In meters.
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_SetObserverRotation
The SimConnect_SetObserverRotation function creates an observer using SIMCONNECT_DATA_OBSERVER.
Syntax
HANDLE hSimConnect,
const char* szName,
SIMCONNECT_DATA_PBH RotationAngles,
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the observer view that should be updated. This name appears on the observer dialogs of Prepar3D.
- RotationAngles
- [in] The pitch, bank, and heading for the observer.
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
Noe.
See Also
SimConnect_SetObserverLookAt
The SimConnect_SetObserverLookAt function creates an observer using SIMCONNECT_DATA_OBSERVER.
Syntax
HANDLE hSimConnect,
const char* szName,
SIMCONNECT_DATA_LATLONALT TargetPosition,
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the observer view that should be updated. This name appears on the observer dialogs of Prepar3D.
- TargetPosition
- [in] The location that the observer should be oriented towards.
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_CreateObserver
- SimConnect_RequestObserverData
- SimConnect_RotateObserver
- SimConnect_SetObserverRotation
- SimConnect_SetObserverFocalLength
- SimConnect_SetObserverFocusFixed
SimConnect_SetObserverLookAtEx
The SimConnect_SetObserverLookAtEx function orients the observer specified to look at the round world corrected position specified. This results in a more accurate orientation at larger distances (greater than 2 miles) when compared to SimConnect_SetObserverLookAt.
Syntax
HANDLE hSimConnect,
const char* szName,
SIMCONNECT_DATA_LATLONALT TargetPosition,
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the observer view that should be updated. This name appears on the observer dialogs of Prepar3D.
- TargetPosition
- [in] The location that the observer should be oriented towards.
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_CreateObserver
- SimConnect_RequestObserverData
- SimConnect_RotateObserver
- SimConnect_SetObserverRotation
- SimConnect_SetObserverFocalLength
- SimConnect_SetObserverFocusFixed
SimConnect_ObserverTrackLocationOn
The SimConnect_ObserverTrackLocationOn function is used to have an observer track a world position (round world corrected) using an above ground level altitude and accounting for changes in elevation.
Syntax
HANDLE hSimConnect,
const char* szName,
SIMCONNECT_DATA_LATLONALT TargetPosition,
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the observer view that should be updated. This name appears on the observer dialogs of Prepar3D.
- TargetPosition
- [in] The location that the observer should be oriented towards. Altitude is AGL. Units are radians/meters.
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_CreateObserver
- SimConnect_RequestObserverData
- SimConnect_RotateObserver
- SimConnect_SetObserverRotation
- SimConnect_SetObserverFocalLength
- SimConnect_SetObserverFocusFixed
- SimConnect_ObserverTrackLocationOff
SimConnect_ObserverTrackLocationOff
The SimConnect_ObserverTrackLocationOff function is used to disable continuous tracking of the previously specified world position.
Syntax
HANDLE hSimConnect,
const char* szName,
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the observer view that should be updated. This name appears on the observer dialogs of Prepar3D.
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_CreateObserver
- SimConnect_RequestObserverData
- SimConnect_RotateObserver
- SimConnect_SetObserverRotation
- SimConnect_SetObserverFocalLength
- SimConnect_SetObserverFocusFixed
- SimConnect_ObserverTrackLocationOn
SimConnect_ObserverAttachToEntityOn
The SimConnect_ObserverAttachToEntityOn function is used to attach an observer to the specified entity at the specified offset from the entity.
Syntax
HANDLE hSimConnect,
const char* szName,
DWORD dwObjectID,
SIMCONNECT_DATA_XYZ relativeXYZ,
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the observer view that should be updated. This name appears on the observer dialogs of Prepar3D.
- dwObjectID
- [in] The ID of the object to attach to.
- relativeXYZ
- [in] The offset that the observer should be from the attached entity.
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_CreateObserver
- SimConnect_RequestObserverData
- SimConnect_RotateObserver
- SimConnect_SetObserverRotation
- SimConnect_SetObserverFocalLength
- SimConnect_SetObserverFocusFixed
- SimConnect_ObserverAttachToEntityOff
SimConnect_ObserverAttachToEntityOff
The SimConnect_ObserverAttachToEntityOff function is used to detach an observer from its attached entity.
Syntax
HANDLE hSimConnect,
const char* szName,
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the observer view that should be updated. This name appears on the observer dialogs of Prepar3D.
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_CreateObserver
- SimConnect_RequestObserverData
- SimConnect_RotateObserver
- SimConnect_SetObserverRotation
- SimConnect_SetObserverFocalLength
- SimConnect_SetObserverFocusFixed
- SimConnect_ObserverAttachToEntityOn
SimConnect_SetObserverFieldOfView
The SimConnect_SetObserverFieldOfView function creates an observer using SIMCONNECT_DATA_OBSERVER.
Syntax
HANDLE hSimConnect,
const char* szName,
float fHorizontal,
float fVertical,
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the observer view that should be updated. This name appears on the observer dialogs of Prepar3D.
- fHorizontal
- [in] The horizontal field of view for the observer. In degrees.
- fVertical
- [in] The vertical field of view for the observer. 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_CreateObserver
- SimConnect_RequestObserverData
- SimConnect_SetObserverFieldOfView
- SimConnect_SetObserverStepSize
- SimConnect_SetObserverFocalLength
- SimConnect_SetObserverFocusFixed
- SimConnect_SetObserverZoomLevels
SimConnect_SetObserverStepSize
The SimConnect_SetObserverStepSize function creates an observer using SIMCONNECT_DATA_OBSERVER.
Syntax
HANDLE hSimConnect,
const char* szName,
float fLinearStep,
float fAngularStep,
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the observer view that should be updated. This name appears on the observer dialogs of Prepar3D.
- fLinearStep
- [in] The linear step for the observer view. In meters.
- fAngularStep
- [in] The angular step for the observer view. 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_CreateObserver
- SimConnect_RequestObserverData
- SimConnect_RotateObserver
- SimConnect_SetObserverRotation
- SimConnect_SetObserverLookAt
- SimConnect_SetObserverLookAtEx
- SimConnect_ObserverTrackLocationOn
- SimConnect_ObserverTrackLocationOff
- SimConnect_SetObserverFieldOfView
- SimConnect_SetObserverFocalLength
- SimConnect_SetObserverFocusFixed
SimConnect_SetObserverFocalLength
The SimConnect_SetObserverFocalLength function creates an observer using SIMCONNECT_DATA_OBSERVER.
Syntax
HANDLE hSimConnect,
const char* szName,
float fFocalLength,
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the observer view that should be updated. This name appears on the observer dialogs of Prepar3D.
- fFocalLength
- [in] The focal length for the observer. In meters.
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_CreateObserver
- SimConnect_RequestObserverData
- SimConnect_SetObserverFieldOfView
- SimConnect_SetObserverStepSize
- SimConnect_SetObserverFocusFixed
- SimConnect_SetObserverZoomLevels
SimConnect_SetObserverFocusFixed
The SimConnect_SetObserverFocusFixed function creates an observer using SIMCONNECT_DATA_OBSERVER.
Syntax
HANDLE hSimConnect,
const char* szName,
BOOL bFocusFixed,
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the observer view that should be updated. This name appears on the observer dialogs of Prepar3D.
- bFocusFixed
- [in] Specifies the observer focal point. If false, the observer automatically shifts focal point to the world (terrain) as the observer is manipulated. If true, the observer locks the focus to a fixed distance relative to the observer's 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
None.
See Also
- SimConnect_CreateObserver
- SimConnect_RequestObserverData
- SimConnect_SetObserverFieldOfView
- SimConnect_SetObserverFocalLength
- SimConnect_SetObserverZoomLevels
SimConnect_SetObserverRegime
The SimConnect_SetObserverRegime function creates an observer using SIMCONNECT_DATA_OBSERVER.
Syntax
HANDLE hSimConnect,
const char* szName,
DWORD eRegime,
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the observer view that should be updated. This name appears on the observer dialogs of Prepar3D.
- eRegime
- [in] The restrictions of the observer. Tellurian (earth-based) is 0, Terrestrial (land-based) is 1, and Ghost (unimpeded) is 2.
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_CreateObserver
- SimConnect_RequestObserverData
- SimConnect_MoveObserver
- SimConnect_SetObserverPosition
SimConnect_SetObserverZoomLevels
The SimConnect_SetObserverZoomLevels function creates an observer using SIMCONNECT_DATA_OBSERVER.
Syntax
HANDLE hSimConnect,
const char* szName,
DWORD dwNumLevels,
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the observer view that should be updated. This name appears on the observer dialogs of Prepar3D.
- dwNumLevels
- [in] The number of zoom levels to being using.
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_CreateObserver
- SimConnect_RequestObserverData
- SimConnect_SetObserverFieldOfView
- SimConnect_SetObserverFocalLength
- SimConnect_SetObserverFocusFixed
SimConnect_ObserverTrackEntityOn
The SimConnect_ObserverTrackEntityOn function sets the observer to continuously track the specified entity.
Syntax
HANDLE hSimConnect,
const char* szName,
DWORD dwObjectID,
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the observer view that will track the specified object.
- dwObjectID
- [in] The ID of the object to track.
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_ObserverTrackEntityOff
The SimConnect_ObserverTrackEntityOff function turns off continuous tracking of the previously specified entity.
Syntax
HANDLE hSimConnect,
const char* szName,
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the observer view that will no longer track the specified 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. |
Remarks
None.
See Also
SimConnect_SetObserverSceneryOrigin
The SimConnect_SetObserverSceneryOrigin function sets scenery origin mode which is used for loading scenery and traffic.
Syntax
HANDLE hSimConnect,
const char* szName,
DWORD eSceneOrigin,
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szName
- [in] The name of the observer view that should be updated. This name appears on the observer dialogs of Prepar3D.
- eSceneOrigin
- [in] The observers scenery origin mode. Self (own origin) is 0, and Target (focal point) is 1.
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
Setting scenery origin to Target can impact performance and memory usage because content will page in relative to the target which can move rapidly in some modes and may be far away for other cameras used by the sim. If the observer is in world focus the target is determined by projecting the view direction to a point on the ground (even when looking at a simulated object). .
See Also
- SimConnect_CreateObserver
- SimConnect_RequestObserverData
- SimConnect_MoveObserver
- SimConnect_SetObserverPosition
Ground Info Specific Functions
Overview
The Ground Info API functions are used to request a grid of ground data around a point. There are two API commands available, one provides a one-shot request for data around a specific point, and the other can do one-shot or repeating requests around a specific SimObject. Both versions return a North/South East/West oriented grid. You can have a maximum of 100 points per requested grid, but you can have more than one grid request outstanding.
SimConnect_RequestGroundInfo
The SimConnect_RequestGroundInfo function is used to request a grid of altitude points based on a bounding box.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID,
double minLat,
double minLon,
double minAlt,
double maxLat,
double maxLon,
double maxAlt,
DWORD dwGridWidth,
DWORD dwGridHeight,
SIMCONNECT_GROUND_INFO_LATLON_FORMAT eLatLonFormat,
SIMCONNECT_GROUND_INFO_ALT_FORMAT eAltFormat,
SIMCONNECT_GROUND_INFO_SOURCE_FLAG eSourceFlags
);
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 request is receiving a reply. This value should be unique, re-using a RequestID will overwrite any previous request using the same ID.
- minLat
- [in] The minimum Latitude defining the bounding box of the request grid.
- minLon
- [in] The minimum Longitude defining the bounding box of the request grid.
- minAlt
- [in] The minimum Altitude defining the bounding box of the request grid.
- maxLat
- [in] The maximum Latitude defining the bounding box of the request grid.
- maxLon
- [in] The maximum Longitude defining the bounding box of the request grid.
- maxAlt
- [in] The maximum Altitude defining the bounding box of the request grid.
- dwGridWidth
- [in] The number of sample points left/right for the returned grid. The product of dwGridWidth times dwGridHeight must be less than or equal to 100.
- dwGridHeight
- [in] The number of sample points forward/back for the returned grid. The product of dwGridWidth times dwGridHeight must be less than or equal to 100.
- eLatLonFormat
- [in] A member of the SIMCONNECT_GROUND_INFO_LATLON_FORMAT enumeration specifying the format used for Latitude or Longitude values.
- eAltFormat
- [in] A member of the SIMCONNECT_GROUND_INFO_ALT_FORMAT enumeration specifying the format used for Altitude values.
- eSourceFlags
- [in] One or more members of the SIMCONNECT_GROUND_INFO_SOURCE_FLAG enumeration specifying sources of ground info to 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. |
See Also
- SimConnect_RequestGroundInfoOnSimObject
- SIMCONNECT_GROUND_INFO_LATLON_FORMAT
- SIMCONNECT_GROUND_INFO_ALT_FORMAT
- SIMCONNECT_GROUND_INFO_SOURCE_FLAG
- SimConnect API Reference
SimConnect_RequestGroundInfoOnSimObject
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID,
DWORD ObjectID,
double offsetLat,
double offsetLon,
double offsetAlt,
DWORD dwGridWidth,
DWORD dwGridHeight,
SIMCONNECT_GROUND_INFO_LATLON_FORMAT eLatLonFormat,
SIMCONNECT_GROUND_INFO_ALT_FORMAT eAltFormat,
SIMCONNECT_GROUND_INFO_SOURCE_FLAG eSourceFlags
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 request is receiving a reply. This value should be unique, re-using a RequestID will overwrite any previous request using the same ID.
- ObjectID
- [in] Specifies the ID of the Prepar3D object that the ground info grid should be based on. 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.
- offsetLat
- [in] Latitude offset from SimObject center point to North/South edges of bounding box.
- offsetLon
- [in] Longitude offset from SimObject center point to East/West edges of bounding box.
- offsetAlt
- [in] Altitude offset from SimObject center point to Top/Bottom edges of bounding box.
- dwGridWidth
- [in] The number of sample points East/West for the returned grid. The product of dwGridWidth times dwGridHeight must be less than or equal to 100.
- dwGridHeight
- [in] The number of sample points North/South for the returned grid. The product of dwGridWidth times dwGridHeight must be less than or equal to 100.
- eLatLonFormat
- [in] A member of the SIMCONNECT_GROUND_INFO_LATLON_FORMAT enumeration specifying the format used for Latitude or Longitude values.
- eAltFormat
- [in] A member of the SIMCONNECT_GROUND_INFO_ALT_FORMAT enumeration specifying the format used for Altitude values.
- eSourceFlags
- [in] One or more members of the SIMCONNECT_GROUND_INFO_SOURCE_FLAG enumeration specifying sources of ground info to use.
- 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 the SimObject has moved. SIMCONNECT_DATA_REQUEST_FLAG_BLOCK Requested data will be sent using a blocking callback. See SimConnect_RequestSynchronousBlock for more information. - 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. |
See Also
- SimConnect_RequestGroundInfo
- SIMCONNECT_GROUND_INFO_LATLON_FORMAT
- SIMCONNECT_GROUND_INFO_ALT_FORMAT
- SIMCONNECT_GROUND_INFO_SOURCE_FLAG
- SIMCONNECT_PERIOD
- SimConnect API Reference
Synchronous SimConnect Specific Functions
Overview
The Synchronous SimConnect API functions are used to synchronize the code running in your SimConnect add-on with the main sim. The Synchronous APIs do this by "pausing" execution of the sim code until it receives a release command from the SimConnect client, or a timeout occurs (default timeout value is 1.5 seconds).
The Synchronous API has 3 specific APIs that allow creating just Synchronous blocks and releases.
There are also extensions to other APIs related to Synchronous SimConnect. The External Sim API uses the Synchronous SimConnect APIs implicitly. The RequestData/SetData, RequestClientData/SetClientData, and RequestGroundInfo APIs have new _FLAG_BLOCK/_FLAG_UNBLOCK flag values to block/unblock the sim side code. There's also an extended SubscribeToSystemEventEx that includes a new flags value with a _FLAG_BLOCK.
The Synchronous API maintains a timeout check and if your add-on code hasn't released the block within the timeout value, then the block is released automatically and an exception is sent to your add-on code. The default value for this timeout is 1.5 seconds.
SimConnect_RequestSynchronousBlock
The SimConnect_RequestSynchronousBlock function is used to request a recurring callback (based on the Period) that is also a blocking callback.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID,
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 request is receiving a reply. This value should be unique, re-using a RequestID will overwrite any previous request using the same ID.
- Period
- [in] One member of the SIMCONNECT_PERIOD enumeration type, specifying how often the reply 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, will assume SIMCONNECT_DATA_REQUEST_FLAG_BLOCK was provided. SIMCONNECT_DATA_REQUEST_FLAG_BLOCK Requested reply will be sent using a blocking callback. - 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. |
See Also
- SimConnect_SynchronousUnblock
- SimConnect_SetSynchronousTimeout
- SIMCONNECT_PERIOD
- SimConnect API Reference
SimConnect_SynchronousUnblock
The SimConnect_SynchronousUnblock function is used to release the block on any blocking callback.
Syntax
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. |
Working Sample
Primary sample | External Sim |
See Also
SimConnect_SetSynchronousTimeout
The SimConnect_SetSynchronousTimeout function is used to set the timeout value for any blocking callbacks (if this time is exceeded without the block being released, the block is released and an exception is sent to the client).
Syntax
HANDLE hSimConnect
float fTimeSeconds
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- fTimeSeconds
- [in] New timeout value for blocking callbacks.
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
External Sim Specific Functions
Overview
The External Sim APIs are used to write your own simulation code in a SimConnect Addon. When using an External Sim, instead of your SimObject behaving like an aircraft, helicopter, boat, ground vehicle, etc, it will behave how ever the code in your external sim add-on wants it to.
There are two primary ways to use/create an External Sim based SimObject:
- Define a complete SimObject container that has a Category=ExternalSim line in the
[General] section of the sim.cfg/aircraft.cfg file and at least an ExternalSimID
= {GUID_STRING} line in the [fltsim.n] sections, for an External Secondary Sim,
you just need an ExternalSecondarySimID = {GUID_STRING} in the [fltsim.n] section.
When using this method you can use the standard Select Aircraft/Vehicle dialog to
select the SimObject for use, or any of the standard AICreateXxx SimConnect functions.
There is a Sample External Sim SimObject
container included in the SDK that you can use as a reference/template for
creating your own External Sim related SimObjects.
- Use the API functions that allow creating AI objects or User objects using an existing
SimObject container but providing your own external sim code to run instead of whatever
would normally run for that SimObject. When using this method, you must use
one of the External Sim related create/attach functions -
SimConnect_AICreateObjectWithExternalSim,
SimConnect_ChangeVehicleWithExternalSim, or
SimConnect_AttachExternalSecondarySimToSimObject.
There are two types of External Sims:
- An External Sim which provides all of the required code to simulate the vehicles
movement. This provides the primary sim code for the SimObject.
- An External Secondary Sim which just provides additional simulation to another SimObject
(the primary sim could be one of the built in categories, or another External Sim).
You could have a tracked vehicle primary sim, and then use an External Secondary
Sim to provide the simulation/drive animation vars/etc for a tank turret, and the
same tank turret External Secondary Sim could also be used with a Wheeled vehicle
primary sim or a Boat vehicle primary sim.
The External Sim APIs use the Synchronous SimConnect functionality implicitly (meaning you need to use one of the Unblock methods in all of the External Sim related callbacks). This is why the Register External Sim function accepts a callback mask, set this to only include the callbacks you actually implement handlers for.
The first thing an External Sim add-on needs to do is use the RegisterExternalSim/RegisterExternalSecondarySim function to let SimConnect know you want to provide External Sim services. To register, you provide a GUID (used to reference this external sim from sim.cfg/aircraft.cfg files or other API functions), a callback mask (set to only the callbacks you actually implement handlers for), and a structure definition ID of the data structure that will be passed to the Simulate callback.
Before your add-on code exits, it should use the UnregisterExternalSim/UnregisterExternalSecondarySim function to let SimConnect know you will no longer be providing services for that GUID.
There are 5 External Sim Callbacks:
- Create - this is called whenever
a SimObject using your External Sim is created.
- Destroy - this is called whenever
a SimObject using your External Sim is destroyed.
- Simulate - this is called every
simulation frame for each SimObject using your External Sim.
- Location Changed -
this is called whenever a SimObject has potentially moved, primarily due to user
UI manipulations.
- Event - this is called whenever
a mapped event occurs. In order to map specific events be sent to your external
sim add-on, you use the MapClientEventToSimEvent
function.
To programmatically create AI objects that use a specific External Sim, you use the AICreateObjectWithExternalSim function to load an existing SimObject but override it to use an External Sim instead.
To programmatically create a User object that uses a specific External Sim, you use the ChangeVehicleWithExternalSim function to load an existing SimObject but override it to use an External Sim instead.
For External Secondary Sims, you don't use a create function, instead you use AttachExternalSecondarySimToSimObject/ DetachExternalSecondarySimFromSimObject to attach/detach an External Secondary sim to/from an existing Simobject.
A primary External Sim can write to any of the defined SimVars. A Secondary External Sim can write to any of the defined SimVars that aren't already being handled by the primary sim.
An External Sim can also make use of the Ground Info APIs to get a small grid of ground data around it's SimObject.
Besides providing the ability to simulate the physics for a SimObject, the External Sim APIs can also be used to create pseudo-multiplayer style add-ons allowing some external data source (an Entity Generator or another sim) to drive SimObjects around the sim world.
SimConnect_RegisterExternalSim
The SimConnect_RegisterExternalSim function is used to register a SimConnect client as an external sim provider.
Syntax
HANDLE hSimConnect,
const GUID guidExternalSimID,
SIMCONNECT_EXTERNAL_SIM_CALLBACK_FLAG CallbackMask,
SIMCONNECT_DATA_DEFINITION_ID DefineID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- guidExternalSimID
- [in] The GUID used to denote this external sim.
- CallbackMask
- [in] One or more members of the SIMCONNECT_EXTERNAL_SIM_CALLBACK_FLAG enumeration that specify which External Sim Callbacks this client wants to receive.
- DefineID
- [in] The data definition ID for any data you would like to have sent with the External Sim Simulate 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. |
Working Sample
Primary sample | External Sim |
See Also
- SimConnect_UnregisterExternalSim
- SimConnect_RegisterExternalSecondarySim
- SimConnect_UnregisterExternalSecondarySim
- SimConnect_AttachExternalSecondarySimToSimObject
- SimConnect_DetachExternalSecondarySimFromSimObject
- SimConnect_AICreateObjectWithExternalSim
- SimConnect_ChangeVehicleWithExternalSim
- SIMCONNECT_EXTERNAL_SIM_CALLBACK_FLAG
- SimConnect API Reference
SimConnect_UnregisterExternalSim
The SimConnect_UnregisterExternalSim function is used to unregister a SimConnect client as an external sim provider.
Syntax
HANDLE hSimConnect,
const GUID guidExternalSimID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- guidExternalSimID
- [in] The GUID used to denote this external sim.
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. |
Working Sample
Primary sample | External Sim |
See Also
- SimConnect_RegisterExternalSim
- SimConnect_RegisterExternalSecondarySim
- SimConnect_UnregisterExternalSecondarySim
- SimConnect_AttachExternalSecondarySimToSimObject
- SimConnect_DetachExternalSecondarySimFromSimObject
- SimConnect_AICreateObjectWithExternalSim
- SimConnect_ChangeVehicleWithExternalSim
- SimConnect API Reference
SimConnect_RegisterExternalSecondarySim
The SimConnect_RegisterExternalSecondarySim function is used to register a SimConnect client as an external secondary sim provider.
Syntax
HANDLE hSimConnect,
const GUID guidExternalSecondarySimID,
SIMCONNECT_EXTERNAL_SIM_CALLBACK_FLAG CallbackMask,
SIMCONNECT_DATA_DEFINITION_ID DefineID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- guidExternalSecondarySimID
- [in] The GUID used to denote this external secondary sim.
- CallbackMask
- [in] One or more members of the SIMCONNECT_EXTERNAL_SIM_CALLBACK_FLAG enumeration that specify which External Sim Callbacks this client wants to receive.
- DefineID
- [in] The data definition ID for any data you would like to have sent with the External Sim Simulate 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. |
See Also
- SimConnect_RegisterExternalSim
- SimConnect_UnregisterExternalSim
- SimConnect_UnregisterExternalSecondarySim
- SimConnect_AttachExternalSecondarySimToSimObject
- SimConnect_DetachExternalSecondarySimFromSimObject
- SimConnect_AICreateObjectWithExternalSim
- SimConnect_ChangeVehicleWithExternalSim
- SIMCONNECT_EXTERNAL_SIM_CALLBACK_FLAG
- SimConnect API Reference
SimConnect_UnregisterExternalSecondarySim
The SimConnect_UnregisterExternalSecondarySim function is used to unregister a SimConnect client as an external secondary sim provider.
Syntax
HANDLE hSimConnect,
const GUID guidExternalSecondarySimID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- guidExternalSecondarySimID
- [in] The GUID used to denote this external secondary sim.
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_RegisterExternalSim
- SimConnect_UnregisterExternalSim
- SimConnect_RegisterExternalSecondarySim
- SimConnect_AttachExternalSecondarySimToSimObject
- SimConnect_DetachExternalSecondarySimFromSimObject
- SimConnect_AICreateObjectWithExternalSim
- SimConnect_ChangeVehicleWithExternalSim
- SimConnect API Reference
SimConnect_AttachExternalSecondarySimToSimObject
The SimConnect_AttachExternalSecondarySimToSimObject function is used to attach an External Secondary Sim to an existing SimObject.
Syntax
HANDLE hSimConnect,
DWORD dwObjectID,
const GUID guidExternalSecondarySimID,
const char * szExternalSimParams,
DWORD dwExternalSimVarCount
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- dwObjectID
- [in] ID of the SimObject to attach to.
- guidExternalSecondarySimID
- [in] The GUID of the external secondary sim you want to attach.
- szExternalSimParams
- [in] A string containing parameters to pass to the external secondary sim. Not used internally, but retrievable through the EXTERNAL PRIMARY SIM DATA simulation variable.
- dwExternalSimVarCount
- [in] Number of variables to allocate for this external secondary sim to use (range 0 to 999).
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_RegisterExternalSim
- SimConnect_UnregisterExternalSim
- SimConnect_RegisterExternalSecondarySim
- SimConnect_UnregisterExternalSecondarySim
- SimConnect_DetachExternalSecondarySimFromSimObject
- SimConnect_AICreateObjectWithExternalSim
- SimConnect_ChangeVehicleWithExternalSim
- SimConnect API Reference
SimConnect_DetachExternalSecondarySimFromSimObject
The SimConnect_DetachExternalSecondarySimFromSimObject function is used to detach an External Secondary Sim from an existing SimObject.
Syntax
HANDLE hSimConnect,
DWORD dwObjectID,
const GUID guidExternalSecondarySimID,
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- dwObjectID
- [in] ID of the SimObject to attach to.
- guidExternalSecondarySimID
- [in] The GUID of the external secondary sim you want to attach.
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_RegisterExternalSim
- SimConnect_UnregisterExternalSim
- SimConnect_RegisterExternalSecondarySim
- SimConnect_UnregisterExternalSecondarySim
- SimConnect_AttachExternalSecondarySimToSimObject
- SimConnect_AICreateObjectWithExternalSim
- SimConnect_ChangeVehicleWithExternalSim
- SimConnect API Reference
SimConnect_AICreateObjectWithExternalSim
The SimConnect_AICreateObjectWithExternalSim function is used to create an AI object and override the sim to use a specific external secondary sim.
Syntax
HANDLE hSimConnect,
const char * szContainertitle,
SIMCONNECT_DATA_INITPOSITION InitPos,
SIMCONNECT_DATA_REQUEST_ID RequestID,
const GUID guidExternalSimID,
const char * szExternalSimParams,
DWORD dwExternalSimVarCount
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szContainertitle
- [in] Null-terminated string containing the container title.
- InitPos
- [in] Specifies the initial position, using a SIMCONNECT_DATA_INITPOSITION structure.
- RequestID
- [in] Specifies the client defined request ID.
- guidExternalSimID
- [in] The GUID of the external secondary sim you want to use to override the default SimObject's sim.
- szExternalSimParams
- [in] A string containing parameters to pass to the external sim. Not used internally, but retrievable through the EXTERNAL PRIMARY SIM DATA simulation variable.
- dwExternalSimVarCount
- [in] Number of variables to allocate for this external sim to use (range 0 to 999).
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_RegisterExternalSim
- SimConnect_UnregisterExternalSim
- SimConnect_RegisterExternalSecondarySim
- SimConnect_UnregisterExternalSecondarySim
- SimConnect_AttachExternalSecondarySimToSimObject
- SimConnect_DetachExternalSecondarySimFromSimObject
- SimConnect_ChangeVehicleWithExternalSim
- SimConnect API Reference
SimConnect_ChangeVehicleWithExternalSim
The SimConnect_ChangeVehicleWithExternalSim function is used to load a new user vehicle and override the sim using a specific external sim.
Syntax
HANDLE hSimConnect,
const char * szContainertitle,
const GUID guidExternalSimID,
const char * szExternalSimParams,
DWORD dwExternalSimVarCount
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szContainertitle
- [in] Null-terminated string containing the container title.
- guidExternalSimID
- [in] The GUID of the external secondary sim you want to use to override the default SimObject's sim.
- szExternalSimParams
- [in] A string containing parameters to pass to the external sim. Not used internally, but retrievable through the EXTERNAL PRIMARY SIM DATA simulation variable.
- dwExternalSimVarCount
- [in] Number of variables to allocate for this external sim to use (range 0 to 999).
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_RegisterExternalSim
- SimConnect_UnregisterExternalSim
- SimConnect_RegisterExternalSecondarySim
- SimConnect_UnregisterExternalSecondarySim
- SimConnect_AttachExternalSecondarySimToSimObject
- SimConnect_DetachExternalSecondarySimFromSimObject
- SimConnect_AICreateObjectWithExternalSim
- SimConnect API Reference
Attach Sim Specific Functions
Overview
The Attach Sim APIs are used to attach one SimObject to another SimObject. There's no physical simulation of the attached objects (i.e. the mass of an attached object doesn't affect the object its attached to, the attached object just suspends simulation and moves with the object its attached to. When an attached object is released, it's primary sim resumes operation.
There are two versions of the attach API, AttachObjectToSimObject will create a new AI object and attach it to the specified SimObject. AttachSimObjectToSimObject is used to attach one existing SimObject to another SimObject (you can both attach the User SimObject to another object or attach other SimObjects to a User SimObject with this function).
SimConnect_AttachObjectToSimObject
The SimConnect_AttachObjectToSimObject function is used to create a new AI SimObject and attach it to an existing SimObject.
Syntax
HANDLE hSimConnect,
DWORD dwObjectID,
SIMCONNECT_DATA_XYZ vecOff1,
SIMCONNECT_DATA_PBH rotOff1,
const char * szContainertitle
SIMCONNECT_DATA_XYZ vecOff2
SIMCONNECT_DATA_PBH rotOff2
SIMCONNECT_DATA_REQUEST_ID RequestID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- dwObjectID
- [in] ObjectID of the existing SimObject to attach to.
- vecOff1
- [in] XYZ offset from existing SimObject model center to attachment point.
- rotOff1
- [in] PBH offset from existing SimObject model body axis to attachment point.
- szContainertitle
- [in] Null-terminated string containing the container title of the AI SimObject you want to create and attach to the existing SimObject. The container title is found in the aircraft.cfg file (see the Aircraft Configuration Files document): for example: title=Airbus A321, or title= Aircreation582SL.
- vecOff2
- [in] XYZ offset from created AI SimObject model center to attachment point..
- rotOff2
- [in] PBH offset from created AI SimObject model body axis to attachment point.
- 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.
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_AttachSimObjectToSimObject
- SimConnect_ReleaseSimObjectFromSimObject
- SimConnect API Reference
SimConnect_AttachSimObjectToSimObject
The SimConnect_AttachSimObjectToSimObject function is used to create a new AI SimObject and attach it to an existing SimObject.
Syntax
HANDLE hSimConnect,
DWORD dwObjectID1,
SIMCONNECT_DATA_XYZ vecOff1,
SIMCONNECT_DATA_PBH rotOff1,
DWORD dwObjectID2
SIMCONNECT_DATA_XYZ vecOff2
SIMCONNECT_DATA_PBH rotOff2
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- dwObjectID1
- [in] ObjectID of the existing SimObject to attach to.
- vecOff1
- [in] XYZ offset from dwObjectID1's model center to attachment point.
- rotOff1
- [in] PBH offset from dwObjectID1's model body axis to attachment point.
- dwObjectID2
- [in] ObjectID of the existing SimObject that is being attached to dwObjectID1.
- vecOff2
- [in] XYZ offset from dwObjectID2's model center to attachment point..
- rotOff2
- [in] PBH offset from dwObjectID2's model body axis to attachment point.
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_AttachObjectToSimObject
- SimConnect_ReleaseSimObjectFromSimObject
- SimConnect API Reference
SimConnect_ReleaseSimObjectFromSimObject
The SimConnect_ReleaseSimObjectFromSimObject function is used to release a SimObject from the SimObject it is attached to.
Syntax
HANDLE hSimConnect,
DWORD dwObjectID1,
DWORD dwObjectID2
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- dwObjectID1
- [in] ObjectID of the existing SimObject that dwObjectID2 is being released from.
- dwObjectID2
- [in] ObjectID of the existing SimObject that is being released from dwObjectID1.
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
Attach Weapon Specific Functions
Overview
The Attach Weapon APIs are used to attach one Weapon to a SimObject. The attach call can be made multiple times to fill out the required number of weapons. The hardpoints must be setup on the SimObject in order to use the Attach Weapon APIs.
SimConnect_AttachWeaponToObject
The SimConnect_AttachWeaponToObject function is used to attach a Weapon to a SimObject.
Syntax
HANDLE hSimConnect,
const char* szContainertitle,
SIMCONNECT_OBJECT_ID dwObjectID
int attachPoint
int numOfRounds
);
Weapon Examples |
---|
title=AIM-9M_Sidewinder title=AGM-88_HARM title=AIM-120_AMRAAM |
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szContainertitle
- [in] null-terminated string containing title of the Weapon being attached to ObjectID.
- dwObjectID
- [in] ObjectID of the existing SimObject.
- attachPoint
- [in] int containing the station index from the object's Attachments.xml file.
- numOfRounds
- [in] int containing the number of rounds of the weapon being attached.
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_ClearWeapons
The SimConnect_ClearWeapons function is used to remove all Weapons from a SimObject.
Syntax
HANDLE hSimConnect,
SIMCONNECT_OBJECT_ID dwObjectID
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- dwObjectID
- [in] ObjectID of the existing SimObject.
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
Effects Specific Functions
Overview
The Effects APIs are used to create effects. Effects can be placed at a location or attached to a SimObject. These effects can also be timed so they don't last forever.
SimConnect_CreateEffect
The SimConnect_CreateEffect function is used to create an effect.
Syntax
HANDLE hSimConnect,
const char* effectName,
SIMCONNECT_DATA_LATLONALT TargetPosition
SIMCONNECT_DATA_XYZ offset
BOOL attachToSimObject
DWORD dwObjectID
SIMCONNECT_DATA_REQUEST_ID RequestID
int effectDuration
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- effectName
- [in] null-terminated string containing the title of the effect to be
created.
Effect Examples title=fx_explosion
title=fx_flamingDebris
- TargetPosition
- [in] SIMCONNECT_DATA_LATLONALT containing the location of the effect.
- offset
- [in] SIMCONNECT_DATA_XYZ containing the offset from the location or the attached point of the SimObject.
- attachToSimObject
- [in] BOOL determining whether to use the TargetPosition or to attach to the SimObject.
- dwObjectID
- [in] ObjectID of an existing SimObject the effect should be attached to.
- RequestID
- [in] RequestID containing the client defined request ID.
- effectDuration
- [in, optional] int containing the number of seconds that the effect will last. (default value = -1, for unlimited)
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 effectId, which can be used by SimConnect_RemoveEffect, will be returned as a SIMCONNECT_RECV_ASSIGNED_OBJECT_ID structure as the dwObjectID parameter.See Also
SimConnect_RemoveEffect
The SimConnect_RemoveEffect function is used to remove an effect.
Syntax
HANDLE hSimConnect,
DWORD effectId
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- effectId
- [in] Double Word containing the identifier of the effect to be 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. |
See Also
Recorder Specific Functions
Overview
The Recorder APIs are used to start and stop the Prepar3D recorder as well as playback specified recordings.
SimConnect_PlaybackRecording
The SimConnect_PlaybackRecording function is used to playback a specified recording from a specified start time to a specified end time.
Syntax
HANDLE hSimConnect,
const char * szFileName
double startTimeInSeconds
double endTimeInSeconds
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szFileName
- [in] The file path of the recording to playback.
- startTimeInSeconds
- [in] The time (in seconds) within the recording where the playback should start (0 is the start of the recording).
- endTimeInSeconds
- [in] The time (in seconds) within the recording where the playback should end (-1 is the end of the recording).
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
You must specify the full path to the recording in order to play it using SimConnect_PlaybackRecording.
See Also
- SimConnect_StartRecorder
- SimConnect_StopRecorderAndSaveRecording
- SimConnect_SubscribeToSystemEvent
- SimConnect API Reference
SimConnect_StartRecorder
The SimConnect_StartRecorder function is used to trigger the Prepar3D Recorder to start recording.
Syntax
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. |
See Also
- SimConnect_PlaybackRecording
- SimConnect_StopRecorderAndSaveRecording
- SimConnect_SubscribeToSystemEvent
- SimConnect API Reference
SimConnect_StopRecorderAndSaveRecording
The SimConnect_StopRecorderAndSaveRecording function is used to trigger the Prepar3D Recorder to stop recording and either prompt the user or save the recording with a specified file name.
Syntax
HANDLE hSimConnect,
const char * szTitle
const char * szDescription
BOOL promptUser
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- szTitle
- [in] The title and file name that the recording will be saved with.
- szDescription
- [in] The description that the recording will be saved with.
- promptUser
- [in] If true, rather than use the specified title and description, the user is prompted to specify the title and description for the recording.
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_PlaybackRecording
- SimConnect_StartRecorder
- SimConnect_SubscribeToSystemEvent
- SimConnect API Reference
SimConnect_RequestRecordingInfo
The SimConnect_RequestRecordingInfo function is used to request information on a given recording file.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID
const char * szFileName
UINT cbszFileName
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- RequestID
- [in] RequestID containing the client defined request ID.
- szFileName
- [in] The file path of the recording.
- cbszFileName
- [in] The size of the file path in bytes (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. |
Remarks
You must specify the full path to the recording.
See Also
- SimConnect_StartRecorder
- SimConnect_StopRecorderAndSaveRecording
- SimConnect_SubscribeToSystemEvent
- SimConnect API Reference
SimConnect_RequestBookmarkInfo
The SimConnect_RequestBookmarkInfo function is used to request bookmark information on a given recording file.
Syntax
HANDLE hSimConnect,
SIMCONNECT_DATA_REQUEST_ID RequestID
const char * szFileName
UINT cbszFileName
);
Parameters
- hSimConnect
- [in] Handle to a SimConnect object.
- RequestID
- [in] RequestID containing the client defined request ID.
- szFileName
- [in] The file path of the recording.
- cbszFileName
- [in] The size of the file path in bytes (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. |
Remarks
You must specify the full path to the recording.
See Also
- SimConnect_StartRecorder
- SimConnect_StopRecorderAndSaveRecording
- SimConnect_SubscribeToSystemEvent
- SimConnect API Reference
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 multiplayer 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_GROUND_INFO | Struct | Used to return info about one ground point entry in the array returned by a call to SimConnect_RequestGroundInfo or SimConnect_RequestGroundInfoOnSimObject |
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_TACAN | Struct | Used to return information on a single TACAN 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_JOYSTICK_DEVICE_INFO | Struct | Used to return information about connected joystick devices by a call to SimConnect_RequestJoystickDeviceInfo |
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_DATA_PBH | Struct | Used to hold a rotation. |
SIMCONNECT_DATA_OBSERVER | Struct | Used to hold all data for a specific observer. |
SIMCONNECT_DATA_OBJECT_DAMAGED_BY_WEAPON | Struct | Used to hold all data for an object damaged by a weapon. |
SIMCONNECT_DATA_VIDEO_STREAM_INFO | Struct | Used to hold all data for a video stream. |
SIMCONNECT_EXCEPTION | Enum | Used with the SIMCONNECT_RECV_EXCEPTION structure to return information on an error that has occurred. |
SIMCONNECT_EXTERNAL_SIM_CALLBACK_FLAG | Enum | Used with the SimConnect_RegisterExternalSim and SimConnect_RegisterExternalSecondarySim functions to specify which External Sim Callbacks you wish to receive. |
SIMCONNECT_GOAL_RESOLUTION | Enum | Used by SimConnect_ResolveGoal to specify the state the specified goal should be resolved to. |
SIMCONNECT_GOAL_STATE | Enum | Used by SIMCONNECT_RECV_GOAL to specify the state of the the goal. |
SIMCONNECT_GROUND_INFO_LATLON_FORMAT | Enum | Used with the Simconnect_RequestGroundInfo and SimConnect_RequestGroundInfoOnSimObject functions to specify the format for latitude and longitude values. |
SIMCONNECT_GROUND_INFO_ALT_FORMAT | Enum | Used with the Simconnect_RequestGroundInfo and SimConnect_RequestGroundInfoOnSimObject functions to specify the format for altitude values. |
SIMCONNECT_GROUND_INFO_SOURCE_FLAG | Enum | Used with the Simconnect_RequestGroundInfo and SimConnect_RequestGroundInfoOnSimObject functions to specify types of ground you wish to receive. |
SIMCONNECT_FACILITY_LIST_TYPE | Enum | Used to determine which type of facilities data is being requested or returned. |
SIMCONNECT_LICENSE_TYPE | Enum | Used to determine which type of License is being run on the Application. |
SIMCONNECT_MISSION_END | Enum | Used to specify the three possible outcomes of a scenario. |
SIMCONNECT_MISSION_OBJECT_TYPE | Enum | Returned by SIMCONNECT_RECV_MISSION_OBJECT_COUNT struct to specify the type of scenario object. |
SIMCONNECT_MISSION_OBJECTIVE_STATUS | Enum | Used by SIMCONNECT_RECV_MISSION_OBJECTIVE to specify the state of the the mission objective. |
SIMCONNECT_PERIOD | Enum | Used with the SimConnect_RequestDataOnSimObject call to specify how often data is to be sent to the client. |
SIMCONNECT_RECV | Struct | Used with the SIMCONNECT_RECV_ID enumeration to indicate which type of structure has been returned. |
SIMCONNECT_RECV_AIRPORT_LIST | Struct | Used to return a list of SIMCONNECT_DATA_FACILITY_AIRPORT structures. |
SIMCONNECT_RECV_ASSIGNED_OBJECT_ID | Struct | Used to return an object ID that matches a request ID. |
SIMCONNECT_RECV_ATTACHPOINT_DATA | Struct | Will be received by the client after a successful call to SimConnect_RequestAttachPointData. |
SIMCONNECT_RECV_CAMERA_6DOF | Struct | Used to return the XYZ delta offset from the eyepoint reference point in meters as well as the pitch, bank, and heading of the camera. |
SIMCONNECT_RECV_CAMERA_FOV | Struct | Used to return the camera's current horizontal and vertical field of view.. |
SIMCONNECT_RECV_CAMERA_SENSOR_MODE | Struct | Used to return the camera's current sensor mode.. |
SIMCONNECT_RECV_CAMERA_WINDOW_POSITION | Struct | Used to return the camera's current window position. |
SIMCONNECT_RECV_CAMERA_WINDOW_SIZE | Struct | Used to return the camera's current window size. |
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 scenario 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 multiplayer 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_EXTERNAL_SIM_BASE | Struct | Base class for External Sim callback data. |
SIMCONNECT_RECV_EXTERNAL_SIM_CREATE | Struct | Used with the External Sim Create Callback. |
SIMCONNECT_RECV_EXTERNAL_SIM_DESTROY | Struct | Used with the External Sim Destroy Callback. |
SIMCONNECT_RECV_EXTERNAL_SIM_SIMULATE | Struct | Used with the External Sim Simulate Callback. |
SIMCONNECT_RECV_EXTERNAL_SIM_LOCATION_CHANGED | Struct | Used with the External Sim Location Changed Callback. |
SIMCONNECT_RECV_EXTERNAL_SIM_EVENT | Struct | Used with the External Sim Event Callback. |
SIMCONNECT_RECV_EVENT_WEAPON | Struct | Used to send a notification of a detachable weapon being fired or detonated. |
SIMCONNECT_RECV_EVENT_COUNTERMEASURE | Struct | Used to send a notification of a deployed countermeasure. |
SIMCONNECT_RECV_EVENT_OBJECT_DAMAGED_BY_WEAPON | Struct | Used to send a notification of an object being damaged by a weapon. |
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_FLIGHT_SEGMENT | Struct | Received by the client after a successful call to SimConnect_RequestFlightSegmentDataByGUID or SimConnect_RequestFlightSegmentDataByIndex. |
SIMCONNECT_RECV_FLIGHT_SEGMENT_READY_FOR_GRADING | Struct | Received by the client with a FlightSegmentReadyForGrading notification. Contains instance ID of the Flight Segment. |
SIMCONNECT_RECV_GOAL | Struct | Received by the client after a successful call to SimConnect_RequestGoalDataByGUID or SimConnect_RequestGoalDataByIndex. |
SIMCONNECT_RECV_GOAL_PAIR | Struct | Received by the client after a successful call to SimConnect_RequestChildGoalDataByIndex. |
SIMCONNECT_RECV_MISSION_OBJECT_COUNT | Struct | Received by the client after a successful call to SimConnect_RequestFlightSegmentCount, SimConnect_RequestGoalCount, SimConnect_RequestMissionObjectiveCount, or SimConnect_RequestLandingTriggerCount. |
SIMCONNECT_RECV_MISSION_OBJECTIVE | Struct | Received by the client after a successful call to SimConnect_RequestMissionObjectiveDataByGUID or SimConnect_RequestMissionObjectiveDataByIndex. |
SIMCONNECT_RECV_PARAMETER_RANGE | Struct | Received by the client after a successful call to SimConnect_RequestFlightSegmentRangeData. |
SIMCONNECT_RECV_PLAYBACK_STATE_CHANGED | Struct | Received by the client with a PlaybackStateChanged notification. Contains whether playback has started or ended and the file name of the recording. |
SIMCONNECT_RECV_RECORDER_STATE_CHANGED | Struct | Received by the client with a RecorderStateChanged notification. Contains whether recording has started or ended.. |
SIMCONNECT_RECV_RECORDING_INFO | Struct | Received by the client after a successful call to SimConnect_RequestRecordingInfo |
SIMCONNECT_RECV_RECORDING_BOOKMARK_INFO | Struct | Received by the client after a successful call to SimConnect_RequestBookmarkInfo |
SIMCONNECT_RECV_LANDING_TRIGGER_INFO | Struct | Received by the client after a successful call to SimConnect_RequestLandingTriggerLandingInfoCount |
SIMCONNECT_RECV_LANDING_INFO | Struct | Received by the client after a successful call to SimConnect_RequestLandingTriggerLandingInfoByIndex |
SIMCONNECT_RECV_GROUND_INFO | Struct | Used with the SimConnect_RequestGroundInfo and SimConnect_RequestGroundInfoOnSimObject functions. |
SIMCONNECT_RECV_JOYSTICK_DEVICE_INFO | Struct | Received by the client after a successful call to SimConnect_RequestJoystickDeviceInfo |
SIMCONNECT_RECV_MOBILE_SCENERY_IN_RADIUS | Struct | Received by the client after a successful call to SimConnect_RequestMobileSceneryInRadius |
SIMCONNECT_RECV_MOBILE_SCENERY_DATA | Struct | Received by the client after a successful call to SimConnect_RequestMobileSceneryDataByID |
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_SCENERY_COMPLEXITY | Struct | Will be received by the client after a successful call to SimConnect_RequestSceneryComplexity. |
SIMCONNECT_RECV_SESSION_DURATION | Struct | Will be received by the client after a successful call to SimConnect_RequestSessionDuration. |
SIMCONNECT_RECV_SHADOW_FLAGS | Struct | Will be received by the client after a successful call to SimConnect_RequestShadowFlags. |
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_SYNCHRONOUS_BLOCK | Struct | Well be received by the client in response to a call to SimConnect_RequestSynchronousBlock. |
SIMCONNECT_RECV_SYSTEM_STATE | Struct | Used with the SimConnect_RequestSystemState function to retrieve specific Prepar3D systems states and information. |
SIMCONNECT_RECV_TACAN_LIST | Struct | Used to return a list of SIMCONNECT_DATA_FACILITY_TACAN structures. |
SIMCONNECT_RECV_TRAFFIC_SETTINGS | Struct | Will be received by the client after a successful call to SimConnect_RequestTrafficSettings. |
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 a call to SimConnect_WeatherRequestInterpolatedObservation, SimConnect_WeatherRequestObservationAtStation, or SimConnect_WeatherRequestObservationAtNearestStation. |
SIMCONNECT_RECV_OBSERVER_DATA | Struct | Will be received by the client after a successful call to SimConnect_RequestObserverData. |
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_CAMERA_SENSOR_MODE | Enum | Used to specify a camera's sensor mode using the SimConnect_SetCameraSensorMode call. |
SIMCONNECT_CAMERA_TYPE | Enum | Used with the SimConnect_CreateCameraDefinition call to create a new camera definition. |
SIMCONNECT_CAMERA_COMMAND | Enum | Used with the SimConnect_SendCameraCommand call to move camera. |
SIMCONNECT_DYNAMIC_FREQUENCY | Enum | Used with the SimConnect_SetTrafficSettings function and the SIMCONNECT_RECV_TRAFFIC_SETTINGS struct. |
SIMCONNECT_SCENERY_COMPLEXITY | Enum | Used with the SimConnect_RequestSceneryComplexity function and the SIMCONNECT_RECV_SCENERY_COMPLEXITY struct. |
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
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 multiplayer racing results.
Syntax
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 scenario 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 scenario. This string will be filled from the Name property of the Player object in the scenario object 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_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
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_PBH,
SIMCONNECT_DATATYPE_OBSERVER,
SIMCONNECT_DATATYPE_MAX
};
Members
SIMCONNECT_DATATYPE_INT32,64
Specifies a 32 bit or 64 bit signed integer.
SIMCONNECT_DATATYPE_FLOAT32,64
Specifies a 32 bit or 64 bit signed 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.
SIMCONNECT_DATATYPE_OBSERVER
Specifies the SIMCONNECT_DATA_OBSERVER
structure.
SIMCONNECT_DATATYPE_VIDEO_STREAM_INFO
Specifies the SIMCONNECT_DATA_VIDEO_STREAM_INFO
structure.
Working 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_GROUND_INFO
The SIMCONNECT_DATA_GROUND_INFO structure is used to return information on
a single ground info point. The SIMCONNECT_RECV_GROUND_INFO
structure contains an array of these, one for each point in the grid array returned
by calls to SimConnect_RequestGroundInfo
or SimConnect_RequestGroundInfoOnSimObject.
Syntax
BOOL bIsValid;
double fLat;
double fLon;
double fAlt;
double fNormalI;
double fNormalJ;
double fNormalK;
DWORD eSurfaceType;
DWORD eSurfaceCondition;
BOOL bIsPlatform;
BOOL bIsPlatformMoving;
};
Members
bIsValid;
Boolean value, true means this data point is valid, false means this data point is invalid.
fLat;
Double floating point value containing the Lattidute of this point (units based on value of SIMCONNECT_RECV_GROUND_INFO.dwFlags).
fLon;
Double floating point value containing the Longitude of this point (units based on value of SIMCONNECT_RECV_GROUND_INFO.dwFlags).
fAlt;
Double floating point value containing the Altitude of this point (units based on value of SIMCONNECT_RECV_GROUND_INFO.dwFlags).
fNormalI;
Double floating point value containing the I component of the normal at this point.
fNormalJ;
Double floating point value containing the J component of the normal at this point.
fNormalK;
Double floating point value containing the K component of the normal at this point.
eSurfaceType;
Double word containing the type of surface at this point.
eSurfaceCondition;
Double word containing the surface conditions as this point.
bIsPlatform;
Boolean value, true means this point refers to a platform instead of the ground.
bIsPlatformMoving;
Boolean value, true if this point refers to a platform and the platform is moving
Remarks
An array of this structure is part of the SIMCONNECT_RECV_GROUND_INFO structure. Each element in the array provides info on one ground point.
See the remarks for SimConect_RequestGroundInfo.
See Also
- SimConnect_RequestGroundInfo
- SimConnect_RequestGroundInfoOnSimObject
- SIMCONNECT_RECV_GROUND_INFO
- SimConnect API Reference
- SimConnect Structures and Enumerations
SIMCONNECT_DATA_FACILITY_AIRPORT
The SIMCONNECT_DATA_FACILITY_AIRPORT structure is used to return information on a single airport in the facilities cache.
Syntax
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, SIMCONNECT_DATA_FACILITY_VOR, and SIMCONNECT_DATA_FACILITY_TACAN, 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
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_AIRPORT
- SIMCONNECT_DATA_FACILITY_VOR
- SIMCONNECT_DATA_FACILITY_TACAN
- SimConnect API Reference
- SimConnect Structures and Enumerations
SIMCONNECT_DATA_FACILITY_TACAN
The SIMCONNECT_DATA_FACILITY_TACAN structure is used to return information on a single TACAN station in the facilities cache.
Syntax
DWORD uChannel;
BOOL bXYBandIsY;
};
Members
uChannel
The specified channel for this station
bXYBandIsY
True if the operating band is Y instead of X.
Remarks
This structure is returned as one element in the SIMCONNECT_RECV_TACAN_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
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_AIRPORT
- SIMCONNECT_DATA_FACILITY_WAYPOINT
- SimConnect API Reference
- SimConnect Structures and Enumerations
SIMCONNECT_DYNAMIC_FREQUENCY
The SIMCONNECT_DYNAMIC_FREQUENCY enumeration type is used with the SimConnect_RequestTrafficSettings and SimConnect_SetTrafficSettings functions.
Syntax
SIMCONNECT_DYNAMIC_FREQUENCY_VERY_SPARSE,
SIMCONNECT_DYNAMIC_FREQUENCY_SPARSE,
SIMCONNECT_DYNAMIC_FREQUENCY_NORMAL,
SIMCONNECT_DYNAMIC_FREQUENCY_DENSE,
SIMCONNECT_DYNAMIC_FREQUENCY_VERY_DENSE,
SIMCONNECT_DYNAMIC_FREQUENCY_EXTREMELY_DENSE,
};
Members
SIMCONNECT_DYNAMIC_FREQUENCY_VERY_SPARSE
The current dynamic scenery frequency setting is set to Very Sparse.
SIMCONNECT_DYNAMIC_FREQUENCY_SPARSE
The current dynamic scenery frequency setting is set to Sparse.
SIMCONNECT_DYNAMIC_FREQUENCY_NORMAL
The current dynamic scenery frequency setting is set to Normal.
SIMCONNECT_DYNAMIC_FREQUENCY_DENSE
The current dynamic scenery frequency setting is set to Dense.
SIMCONNECT_DYNAMIC_FREQUENCY_VERY_DENSE
The current dynamic scenery frequency setting is set to Very Dense.
SIMCONNECT_DYNAMIC_FREQUENCY_EXTREMELY_DENSE
The current dynamic scenery frequency setting is set to Extremely Dense.
Working Samples
Primary samples | None. |
See Also
- SimConnect_RequestTrafficSettings
- SimConnect_SetTrafficSettings
- SimConnect API Reference
- SimConnect Structures and Enumerations
SIMCONNECT_DATA_FACILITY_WAYPOINT
The SIMCONNECT_DATA_FACILITY_WAYPOINT structure used to return information on a single waypoint in the facilities cache.
Syntax
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_DATA_FACILITY_NDB
- SIMCONNECT_DATA_FACILITY_VOR
- SIMCONNECT_DATA_FACILITY_TACAN
- SimConnect API Reference
- SimConnect Structures and Enumerations
SIMCONNECT_DATA_JOYSTICK_DEVICE_INFO
The SIMCONNECT_DATA_JOYSTICK_DEVICE_INFO structure is used to return information about connected joystick devices. The SIMCONNECT_RECV_JOYSTICK_DEVICE_INFO structure contains an array of these, one for each connected joystick device.
Syntax
char szName[128];
DWORD dwNumber;
};
Members
szName[128];
The name of the connected device.
dwNumber;
The joystick number of the connected device. This number can be used by the SimConnect_MapInputEventToClientEvent function.
Remarks
An array of this structure is part of the SIMCONNECT_RECV_JOYSTICK_DEVICE_INFO structure. Each element in the array provides information on a single connected joystick device.
See the remarks for SimConnect_RequestJoystickDeviceInfo.
See Also
- SimConnect_RequestJoystickDeviceInfo
- SimConnect_MapInputEventToClientEvent
- SIMCONNECT_RECV_JOYSTICK_DEVICE_INFO
- SimConnect API Reference
- SimConnect Structures and Enumerations
SIMCONNECT_DATA_MOBILE_SCENERY_INFO
The SIMCONNECT_DATA_MOBILE_SCENERY_INFO structure is used to return identification information about mobile scenery objects in a specified radius from the user vehicle. The SIMCONNECT_RECV_MOBILE_SCENERY_IN_RADIUS structure contains an array of these, one for each mobile scenery object in the specified radius from the user vehicle.
Syntax
char szMobileSceneryName[MAX_PATH];
DWORD dwObjectID;
};
Members
szMobileSceneryName[MAX_PATH];
The name of the mobile scenery object as defined in the scenario.
dwObjectID;
The object ID of the mobile scenery object. This ID can be used in the SimConnect_RequestMobileSceneryDataByID function to request data about the mobile scenery object with this ID.
Remarks
An array of this structure is part of the SIMCONNECT_RECV_MOBILE_SCENERY_IN_RADIUS structure. Each element in the array provides information on a single mobile scenery object.
See the remarks for SimConnect_RequestMobileSceneryInRadius.
See Also
- SimConnect_RequestMobileSceneryInRadius
- SimConnect_RequestMobileSceneryDataByID
- SIMCONNECT_RECV_MOBILE_SCENERY_IN_RADIUS
- SIMCONNECT_RECV_MOBILE_SCENERY_DATA
- SimConnect API Reference
- SimConnect Structures and Enumerations
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
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.
Working 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
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,
SIMCONNECT_EXCEPTION_BLOCK_TIMEOUT = 38,
};
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 add-on. 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.
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.
SIMCONNECT_EXCEPTION_BLOCK_TIMEOUT
Specifies that a synchronous blocking callback didn't release the block
within the timeout period.
Working 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 remrks for SimConnect_GetLastSentPacketID.
See Also
SIMCONNECT_EXTERNAL_SIM_CALLBACK_FLAG
The SIMCONNECT_EXTERNAL_SIM_CALLBACK_FLAG enumeration type is used to specify which External Sim Callbacks the client wishes to receive.
Syntax
SIMCONNECT_EXTERNAL_SIM_CALLBACK_FLAG_CREATE  = 0x00000001,
SIMCONNECT_EXTERNAL_SIM_CALLBACK_FLAG_DESTROY  = 0x00000002,
SIMCONNECT_EXTERNAL_SIM_CALLBACK_FLAG_SIMULATE  = 0x00000004,
SIMCONNECT_EXTERNAL_SIM_CALLBACK_FLAG_LOCATION_CHANGED  = 0x00000008,
SIMCONNECT_EXTERNAL_SIM_CALLBACK_FLAG_EVENT  = 0x00000010,
Members
SIMCONNECT_EXTERNAL_SIM_CALLBACK_FLAG_CREATE
Set this bit to request External Sim Create Callbacks.
SIMCONNECT_EXTERNAL_SIM_CALLBACK_FLAG_DESTROY
Set this bit to request External Sim Destroy Callbacks.
SIMCONNECT_EXTERNAL_SIM_CALLBACK_FLAG_SIMULATE
Set this bit to request External Sim Simulate Callbacks.
SIMCONNECT_EXTERNAL_SIM_CALLBACK_FLAG_LOCATION_CHANGED
Set this bit to request External Sim Location Changed Callbacks.
SIMCONNECT_EXTERNAL_SIM_CALLBACK_FLAG_EVENT
Set this bit to request External Sim Event Callbacks.
Working Sample
Primary sample | External Sim |
See Also
- SimConnect_RegisterExternalSim
- SimConnect_RegisterExternalSecondarySim
- SimConnect API Reference
- SimConnect Structures and Enumerations
SIMCONNECT_GOAL_RESOLUTION
The SIMCONNECT_GOAL_RESOLUTION enumeration type is used by SimConnect_ResolveGoal to specify the state the specified goal should be resolved to.
Syntax
SIMCONNECT_GOAL_RESOLUTION_COMPLETED,
SIMCONNECT_GOAL_RESOLUTION_FAILED,
};
Members
SIMCONNECT_GOAL_RESOLUTION_COMPLETED
The goal will be resolved to Completed.
SIMCONNECT_GOAL_RESOLUTION_FAILED
The goal will be resolved to Failed.
Working Samples
Primary samples | Managed Mission Objects |
See Also
SIMCONNECT_GOAL_STATE
The SIMCONNECT_GOAL_STATE enumeration type is used inside of the SIMCONNECT_RECV_GOAL struct to specify the state of the the goal represented by that struct. settings.
Syntax
SIMCONNECT_GOAL_STATE_GOAL_PENDING,
SIMCONNECT_GOAL_STATE_GOAL_COMPLETED,
SIMCONNECT_GOAL_STATE_GOAL_FAILED,
};
Members
SIMCONNECT_GOAL_STATE_GOAL_PENDING
The state of this goal is Pending.
SIMCONNECT_GOAL_STATE_GOAL_COMPLETED
The state of this goal is Completed.
SIMCONNECT_GOAL_STATE_GOAL_FAILED
The state of this goal is Failed.
Working Samples
Primary samples | Managed Mission Objects |
See Also
- SIMCONNECT_RECV_GOAL
- SimConnect_RequestGoalDataByGUID
- SimConnect_RequestGoalDataByIndex
- SimConnect API Reference
- SimConnect Structures and Enumerations
SIMCONNECT_GROUND_INFO_LATLON_FORMAT
The SIMCONNECT_GROUND_INFO_LATLON_FORMAT enumeration type is used with the SimConnect_RequestGroundInfo and SimConnect_RequestGroundInfoOnSimObject functions to specify the format for latitude and longitude values.
Syntax
SIMCONNECT_GROUND_INFO_LATLON_FORMAT_RADIANS,
SIMCONNECT_GROUND_INFO_LATLON_FORMAT_DEGREES,
SIMCONNECT_GROUND_INFO_LATLON_FORMAT_METERS,
Members
SIMCONNECT_GROUND_INFO_LATLON_FORMAT_RADIANS
Latitude and Longitude values will be in radians.
SIMCONNECT_GROUND_INFO_LATLON_FORMAT_DEGREES
Latitude and Longitude values will be in degrees.
SIMCONNECT_GROUND_INFO_LATLON_FORMAT_METERS
Latitdue and Longitude values will be in meters.
See Also
- SimConnect_RequestGroundInfo
- SimConnect_RequestGroundInfoOnSimObject
- SimConnect API Reference
- SimConnect Structures and Enumerations
SIMCONNECT_GROUND_INFO_ALT_FORMAT
The SIMCONNECT_GROUND_INFO_ALT_FORMAT enumeration type is used with the SimConnect_RequestGroundInfo and SimConnect_RequestGroundInfoOnSimObject functions to specify the format for altitude values.
Syntax
SIMCONNECT_GROUND_INFO_ALT_FORMAT_METERS,
SIMCONNECT_GROUND_INFO_ALT_FORMAT_FEET,
Members
SIMCONNECT_GROUND_INFO_ALT_FORMAT_METERS
Altitude values will be in meters.
SIMCONNECT_GROUND_INFO_ALT_FORMAT_FEET
Altitude values will be in feet.
See Also
- SimConnect_RequestGroundInfo
- SimConnect_RequestGroundInfoOnSimObject
- SimConnect API Reference
- SimConnect Structures and Enumerations
SIMCONNECT_GROUND_INFO_SOURCE_FLAG
The SIMCONNECT_GROUND_INFO_SOURCE_FLAG enumeration type is used with the SimConnect_RequestGroundInfo and SimConnect_RequestGroundInfoOnSimObject functions to specify the format for latitude and longitude values.
Syntax
SIMCONNECT_GROUND_INFO_SOURCE_FLAG_TERRAIN = 0x00010000,
SIMCONNECT_GROUND_INFO_SOURCE_FLAG_PLATFORMS = 0x00020000,
SIMCONNECT_GROUND_INFO_SOURCE_FLAG_BATHYMETRY = 0x00040000,
SIMCONNECT_GROUND_INFO_SOURCE_FLAG_IGNORE_WAVES = 0x00080000,
SIMCONNECT_GROUND_INFO_SOURCE_FLAG_TERRAIN_AVG = SIMCONNECT_GROUND_INFO_SOURCE_FLAG_IGNORE_WAVES,
};
Members
SIMCONNECT_GROUND_INFO_SOURCE_FLAG_TERRAIN
Return altitude based on terrain data if encountered first.
SIMCONNECT_GROUND_INFO_SOURCE_FLAG_PLATFORMS
Return altitude based on platform data if encountered first.
SIMCONNECT_GROUND_INFO_SOURCE_FLAG_BATHYMETRY
Return altitude based on bathymetry data if available, water surface
will be returned if bathymetry data not available.
SIMCONNECT_GROUND_INFO_SOURCE_FLAG_IGNORE_WAVES
SIMCONNECT_GROUND_INFO_SOURCE_FLAG_TERRAIN_AVG
Return average altitude based on terrain data if encountered first.
Returns the average water surface altitude when animated water surfaces are enabled.
See Also
- SimConnect_RequestGroundInfo
- SimConnect_RequestGroundInfoOnSimObject
- SimConnect API Reference
- SimConnect Structures and Enumerations
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
SIMCONNECT_FACILITY_LIST_TYPE_AIRPORT,
SIMCONNECT_FACILITY_LIST_TYPE_WAYPOINT,
SIMCONNECT_FACILITY_LIST_TYPE_NDB,
SIMCONNECT_FACILITY_LIST_TYPE_VOR,
SIMCONNECT_FACILITY_LIST_TYPE_TACAN,
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_TACAN
Specifies that the type of information is for a TACAN, see
SIMCONNECT_DATA_FACILITY_TACAN.
SIMCONNECT_FACILITY_LIST_TYPE_COUNT
Not valid as a list type, but simply the number of list types.
Working Sample
Primary sample | FacilitiesData |
Remarks
See the remarks for SimConnect_RequestFacilitiesList.
See Also
SIMCONNECT_LICENSE_TYPE
The SIMCONNECT_LICENSE_TYPE enumeration type is used to determine which type of Prepar3D license is being used.
Syntax
SIMCONNECT_LICENSE_ACADEMIC,
SIMCONNECT_LICENSE_PROFESSIONAL,
SIMCONNECT_LICENSE_PROFESSIONAL_PLUS,
SIMCONNECT_LICENSE_UNKNOWN,
};
Members
SIMCONNECT_LICENSE_ACADEMIC
Specifies that the type of license being used is Academic. See
SIMCONNECT_RECV_VERSION.
SIMCONNECT_LICENSE_PROFESSIONAL
Specifies that the type of license being used is Professional. See SIMCONNECT_RECV_VERSION.
SIMCONNECT_LICENSE_PROFESSIONAL_PLUS
Specifies that the type of license being used is Professional Plus. See SIMCONNECT_RECV_VERSION.
SIMCONNECT_LICENSE_UNKNOWN
Specifies that the type of license being used could not be determined. See SIMCONNECT_RECV_VERSION.
Remarks
See the remarks for SimConnect_RequestVersion.
See Also
SIMCONNECT_MISSION_END
The SIMCONNECT_MISSION_END enumeration type is used to specify the three possible outcomes of a scenario.
Syntax
SIMCONNECT_MISSION_FAILED,
SIMCONNECT_MISSION_CRASHED,
SIMCONNECT_MISSION_SUCCEEDED
};
Members
SIMCONNECT_MISSION_FAILED
Specifies that the user did not complete the scenario successfully.
SIMCONNECT_MISSION_CRASHED
Specifies that the user aircraft crashed during the scenario.
SIMCONNECT_MISSION_SUCCEEDED
Specifies that the user completed the scenario successfully.
Working Sample
Primary sample | Mission Action |
Remarks
Refer to the scenario events that can be requested by the SimConnect_SubscribeToSystemEvent function. Also see the remarks for SimConnect_CompleteCustomMissionAction.
See Also
SIMCONNECT_MISSION_OBJECT_TYPE
The SIMCONNECT_MISSION_OBJECT_TYPE enumeration type is used inside of the SIMCONNECT_RECV_MISSION_OBJECT_COUNT struct to specify the object type the count is associated with. settings.
Syntax
SIMCONNECT_MISSION_OBJECT_TYPE_GOAL,
SIMCONNECT_MISSION_OBJECT_TYPE_MISSION_OBJECTIVE,
SIMCONNECT_MISSION_OBJECT_TYPE_FLIGHT_SEGMENT,
SIMCONNECT_MISSION_OBJECT_TYPE_LANDING_TRIGGER
};
Members
SIMCONNECT_MISSION_OBJECT_TYPE_GOAL
This count is of Goal/Group Goal scenario objects.
SIMCONNECT_MISSION_OBJECT_TYPE_MISSION_OBJECTIVE
This count is of Mission Objective scenario objects.
SIMCONNECT_MISSION_OBJECT_TYPE_FLIGHT_SEGMENT
This count is of Flight Segment scenario objects.
SIMCONNECT_MISSION_OBJECT_TYPE_LANDING_TRIGGER
This count is of Area or Airport Landing Trigger scenario objects.
Working Samples
Primary samples | Managed Mission Objects |
See Also
- SIMCONNECT_RECV_MISSION_OBJECT_COUNT
- SimConnect_RequestFlightSegmentCount
- SimConnect_RequestGoalCount
- SimConnect_RequestMissionObjectiveCount
- SimConnect API Reference
- SimConnect Structures and Enumerations
SIMCONNECT_LANDING_TYPE
The SIMCONNECT_LANDING_TYPE enumeration type is used inside of the SIMCONNECT_RECV_LANDING_INFO struct to specify the type of landing that the landing trigger accepts.
Syntax
SIMCONNECT_LANDING_TYPE_ANY,
SIMCONNECT_LANDING_TYPE_FULL_STOP,
SIMCONNECT_LANDING_TYPE_TOUCHDOWN
};
Members
SIMCONNECT_LANDING_TYPE_ANY
This landing trigger accepts either full stop or touchdown landings.
SIMCONNECT_LANDING_TYPE_FULL_STOP
This landing trigger accepts full stop landings.
SIMCONNECT_LANDING_TYPE_TOUCHDOWN
This landing trigger accepts touchdown landings.
See Also
- SIMCONNECT_RECV_LANDING_INFO
- SimConnect_RequestLandingTriggerLandingInfoByIndex
- SimConnect API Reference
- SimConnect Structures and Enumerations
SIMCONNECT_MISSION_OBJECTIVE_STATUS
The SIMCONNECT_MISSION_OBJECTIVE_STATUS enumeration type is used inside of the SIMCONNECT_RECV_MISSION_OBJECTIVE struct to specify the state of the the mission objective represented by that struct. settings.
Syntax
SIMCONNECT_MISSION_OBJECTIVE_STATUS_PENDING,
SIMCONNECT_MISSION_OBJECTIVE_STATUS_PASSED,
SIMCONNECT_MISSION_OBJECTIVE_STATUS_FAILED,
};
Members
SIMCONNECT_MISSION_OBJECTIVE_STATUS_PENDING
The state of this mission objective is Pending.
SIMCONNECT_MISSION_OBJECTIVE_STATUS_PASSED
The state of this mission objective is Completed.
SIMCONNECT_MISSION_OBJECTIVE_STATUS_FAILED
The state of this mission objective is Failed.
Working Samples
Primary samples | Managed Mission Objects |
See Also
- SIMCONNECT_RECV_MISSION_OBJECTIVE
- SimConnect_RequestMissionObjectiveDataByGUID
- SimConnect_RequestMissionObjectiveDataByIndex
- SimConnect API Reference
- SimConnect Structures and Enumerations
SIMCONNECT_SCENERY_COMPLEXITY
The SIMCONNECT_SCENERY_COMPLEXITY enumeration type is used with the SimConnect_RequestSceneryComplexity to request the current scenery complexity setting.
Syntax
SIMCONNECT_SCENERY_COMPLEXITY_VERY_SPARSE,
SIMCONNECT_SCENERY_COMPLEXITY_SPARSE,
SIMCONNECT_SCENERY_COMPLEXITY_NORMAL,
SIMCONNECT_SCENERY_COMPLEXITY_DENSE,
SIMCONNECT_SCENERY_COMPLEXITY_VERY_DENSE,
SIMCONNECT_SCENERY_COMPLEXITY_EXTREMELY_DENSE,
};
Members
SIMCONNECT_SCENERY_COMPLEXITY_VERY_SPARSE
The current scenery complexity setting is set to Very Sparse.
SIMCONNECT_SCENERY_COMPLEXITY_SPARSE
The current scenery complexity setting is set to Sparse.
SIMCONNECT_SCENERY_COMPLEXITY_NORMAL
The current scenery complexity setting is set to Normal.
SIMCONNECT_SCENERY_COMPLEXITY_DENSE
The current scenery complexity setting is set to Dense.
SIMCONNECT_SCENERY_COMPLEXITY_VERY_DENSE
The current scenery complexity setting is set to Very Dense.
SIMCONNECT_SCENERY_COMPLEXITY_EXTREMELY_DENSE
The current scenery complexity setting is set to Extremely Dense.
Working Samples
Primary samples | Scenery Complexity and Shadow Flags |
See Also
SIMCONNECT_SHADOW_FLAGS
The SIMCONNECT_SHADOW_FLAGS enumeration type is used with the SimConnect_RequestShadowFlags to request the current shadow flag settings.
Syntax
SIMCONNECT_SHADOW_FLAGS_INTERIOR_CAST = 0x00000001,
SIMCONNECT_SHADOW_FLAGS_INTERIOR_RECEIVE = 0x00000002,
SIMCONNECT_SHADOW_FLAGS_EXTERIOR_CAST = 0x00000004,
SIMCONNECT_SHADOW_FLAGS_EXTERIOR_RECEIVE = 0x00000008,
SIMCONNECT_SHADOW_FLAGS_SIMOBJECTS_CAST = 0x00000010,
SIMCONNECT_SHADOW_FLAGS_SIMOBJECTS_RECEIVE = 0x00000020,
SIMCONNECT_SHADOW_FLAGS_TERRAIN_CAST = 0x00000040,
SIMCONNECT_SHADOW_FLAGS_TERRAIN_RECEIVE = 0x00000080,
SIMCONNECT_SHADOW_FLAGS_VEGETATION_CAST = 0x00000100,
SIMCONNECT_SHADOW_FLAGS_VEGETATION_RECEIVE = 0x00000200,
SIMCONNECT_SHADOW_FLAGS_BUILDINGS_CAST = 0x00000400,
SIMCONNECT_SHADOW_FLAGS_BUILDINGS_RECEIVE = 0x00000800,
SIMCONNECT_SHADOW_FLAGS_CLOUDS_CAST = 0x00001000,
};
Members
SIMCONNECT_SHADOW_FLAGS_INTERIOR_CAST
The user interior model is casting shadows.
SIMCONNECT_SHADOW_FLAGS_INTERIOR_RECEIVE
The user interior model is receiving shadows.
SIMCONNECT_SHADOW_FLAGS_EXTERIOR_CAST
The user exterior model is casting shadows.
SIMCONNECT_SHADOW_FLAGS_EXTERIOR_RECEIVE
The user exterior model is receiving shadows.
SIMCONNECT_SHADOW_FLAGS_SIMOBJECTS_CAST
Other SimObjects are casting shadows.
SIMCONNECT_SHADOW_FLAGS_SIMOBJECTS_RECEIVE
Other SimObjects are receiving shadows.
SIMCONNECT_SHADOW_FLAGS_TERRAIN_CAST
The terrain is casting shadows.
SIMCONNECT_SHADOW_FLAGS_TERRAIN_RECEIVE
The terrain is receiving shadows.
SIMCONNECT_SHADOW_FLAGS_VEGETATION_CAST
Autogen vegetation are casting shadows.
SIMCONNECT_SHADOW_FLAGS_VEGETATION_RECEIVE
Autogen vegetation are receiving shadows.
SIMCONNECT_SHADOW_FLAGS_BUILDINGS_CAST
Autogen buildings are casting shadows.
SIMCONNECT_SHADOW_FLAGS_BUILDINGS_RECEIVE
Autogen buildings are receiving shadows.
SIMCONNECT_SHADOW_FLAGS_CLOUDS_CAST
Clouds are casting shadows.
Working Samples
Primary samples | Scenery Complexity and Shadow Flags |
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
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.
Working 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 used as a base class for all other receive data structures. See SIMCONNECT_RECV_ID for list of possible values for dwID and corresponding SIMCONNECT_RECV_XXX structure used.
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
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_RequestFacilitiesList
- SIMCONNECT_RECV_FACILITIES_LIST
- SIMCONNECT_RECV_NDB_LIST
- SIMCONNECT_RECV_VOR_LIST
- SIMCONNECT_RECV_TACAN_LIST
- SIMCONNECT_RECV_WAYPOINT_LIST
- SimConnect API Reference
- SimConnect Structures and Enumerations
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
DWORD dwRequestID;
DWORD dwObjectID;
};
Members
dwRequestID
Double word containing the client defined request ID.
dwObjectID
Double word containing the server defined object ID.
Working 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
- SIMCONNECT_RECV_EXCEPTION
- SIMCONNECT_RECV_ID
- SIMCONNECT_RECV_SIMOBJECT_DATA
- SimConnect API Reference
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_ATTACHPOINT_DATA
The SIMCONNECT_RECV_ATTACHPOINT_DATA structure will be received by the client after a successful call to SimConnect_RequestAttachPointData.
Syntax
DWORD dwRequestID; DWORD dwObjectID; SIMCONNECT_DATA_XYZ xyzLocalOffset; SIMCONNECT_DATA_PBH pbhLocalRotation; SIMCONNECT_DATA_LATLONALT llaWorldPosition; SIMCONNECT_DATA_PBH pbhWorldRotation; };
Members
dwRequestID
Double word containing the client defined request ID.
dwObjectID
Double word containing the server defined object ID.
xyzLocalOffset
A SIMCONNECT_DATA_XYZ containing the local offset of the attach point in feet.
pbhLocalRotation
A SIMCONNECT_DATA_PBH containing the local rotation of the attach point in radians.
llaWorldPosition
A SIMCONNECT_DATA_LATLONALT containing the world position of the attach point in radians (altitude in feet).
pbhWorldRotation
A SIMCONNECT_DATA_PBH containing the world rotation of the attach point in radians.
Remarks
This structure inherits the SIMCONNECT_RECV structure and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ATTACHPOINT_DATA.
See Also
- SimConnect API Reference
- SIMCONNECT_RECV
- SIMCONNECT_RECV_ID
- SimConnect_RequestAttachPointData
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_CAMERA_6DOF
The SIMCONNECT_RECV_CAMERA_6DOF structure will be received by the client after a successful call to SimConnect_RequestCameraRelative6DOF or SimConnect_RequestCameraRelative6DofByName.
Syntax
DWORD dwRequestID;
float fDeltaXMeters;
float fDeltaYMeters;
float fDeltaZMeters;
float fPitchDeg;
float fBankDeg;
float fHeadingDeg;
};
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_6DOF.
See Also
SIMCONNECT_RECV_CAMERA_FOV
The SIMCONNECT_RECV_CAMERA_FOV structure will be received by the client after a successful call to SimConnect_RequestCameraFov or SimConnect_RequestMainCameraFov.
Syntax
DWORD dwRequestID;
float fHorizontalFov;
float fVerticalFov;
};
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_FOV.
See Also
SIMCONNECT_RECV_CAMERA_SENSOR_MODE
The SIMCONNECT_RECV_CAMERA_SENSOR_MODE structure will be received by the client after a successful call to SimConnect_RequestCameraSensorMode or SimConnect_RequestMainCameraSensorMode.
Syntax
DWORD dwRequestID;
SIMCONNECT_CAMERA_SENSOR_MODE eSensorMode;
};
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_SENSOR_MODE.
See Also
- SimConnect API Reference
- SIMCONNECT_RECV
- SIMCONNECT_RECV_ID
- SIMCONNECT_CAMERA_SENSOR_MODE
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_CAMERA_WINDOW_POSITION
The SIMCONNECT_RECV_CAMERA_WINDOW_POSITION structure will be received by the client after a successful call to SimConnect_RequestCameraWindowPosition.
Syntax
DWORD dwRequestID;
DWORD dwXPosition;
DWORD dwYPosition;
};
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_WINDOW_POSITION.
See Also
SIMCONNECT_RECV_CAMERA_WINDOW_SIZE
The SIMCONNECT_RECV_CAMERA_WINDOW_SIZE structure will be received by the client after a successful call to SimConnect_RequestCameraWindowSize.
Syntax
DWORD dwRequestID;
DWORD dwWidth;
DWORD dwHeight;
};
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_WINDOW_SIZE.
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
};
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 API Reference
- SIMCONNECT_RECV
- SIMCONNECT_RECV_ID
- SIMCONNECT_RECV_SIMOBJECT_DATA
- SimConnect_RequestClientData
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_CLOUD_STATE
The SIMCONNECT_RECV_CLOUD_STATE structure is used to return an array of cloud state data.
Syntax
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
- SIMCONNECT_RECV_EXCEPTION
- SIMCONNECT_RECV_ID
- SIMCONNECT_RECV_WEATHER_OBSERVATION
- SimConnect API Reference
- SimConnect Structures and Enumerations
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
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 scenario object XML file. It
is specified by the scenario designer and can contain anything that the client might
find useful.
Working 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
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).
Working 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:
- SIMCONNECT_RECV_CUSTOM_ACTION
- SIMCONNECT_RECV_EVENT_FILENAME
- SIMCONNECT_RECV_EVENT_FRAME
- SIMCONENCT_RECV_EVENT_OBJECT_ADDREMOVE
- SIMCONNECT_RECV_EVENT_MULTIPLAYER_CLIENT_STARTED
- SIMCONNECT_RECV_EVENT_MULTIPLAYER_SERVER_STARTED
- SIMCONNECT_RECV_EVENT_MULTIPLAYER_SESSION_ENDED
See Also
- SimConnect API Reference
- SIMCONNECT_RECV
- SIMCONNECT_RECV_EXCEPTION
- SIMCONNECT_RECV_ID
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_EVENT_FILENAME
The SIMCONNECT_RECV_EVENT_FILENAME structure is used to return a filename and an event ID to the client.
Syntax
char szFileName[MAX_PATH];
DWORD dwFlags;
};
Members
szFileName[MAX_PATH]
The returned filename.
dwFlags
Reserved, should be 0.
Working 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 API Reference
- SIMCONNECT_RECV
- SIMCONNECT_RECV_EVENT
- SIMCONNECT_RECV_EXCEPTION
- SIMCONNECT_RECV_ID
- SimConnect Structures and Enumerations
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
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 multiplayer race.
Syntax
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
- SIMCONNECT_RECV_EVENT_MULTIPLAYER_SESSION_ENDED
- SIMCONNECT_RECV_EVENT_RACE_END
- SIMCONNECT_RECV_EVENT_RACE_LAP
- SIMCONNECT_RECV_ID
- SimConnect API Reference
- SimConnect Structures and Enumerations
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
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_CLIENT_STARTED
- SIMCONNECT_RECV_EVENT_MULTIPLAYER_SESSION_ENDED
- SIMCONNECT_RECV_EVENT_RACE_END
- SIMCONNECT_RECV_EVENT_RACE_LAP
- SIMCONNECT_RECV_ID
- SimConnect_SubscribeToSystemEvent
- SimConnect API Reference
- SimConnect Structures and Enumerations
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
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 multiplayer 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_MULTIPLAYER_CLIENT_STARTED
- SIMCONNECT_RECV_EVENT_MULTIPLAYER_SERVER_STARTED
- SIMCONNECT_RECV_EVENT_RACE_END
- SIMCONNECT_RECV_EVENT_RACE_LAP
- SIMCONNECT_RECV_ID
- SimConnect_SubscribeToSystemEvent
- SimConnect API Reference
- SimConnect Structures and Enumerations
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
SIMCONNECT_SIMOBJECT_TYPE eObjType;
};
Members
eObjType
Specifies the type of object that was added or removed. One member of
the SIMCONNECT_SIMOBJECT_TYPE enumeration.
Working 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 multiplayer racing to hold the results for one player at the end of a race.
Syntax
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 multiplayer race players can come and go, so index numbers are not a reliable means of identifying 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_MULTIPLAYER_CLIENT_STARTED
- SIMCONNECT_RECV_EVENT_MULTIPLAYER_SERVER_STARTED
- SIMCONNECT_RECV_EVENT_MULTIPLAYER_SESSION_ENDED
- SIMCONNECT_RECV_EVENT_RACE_LAP
- SIMCONNECT_RECV_ID
- SimConnect_SubscribeToSystemEvent
- SimConnect API Reference
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_EVENT_RACE_LAP
The SIMCONNECT_RECV_EVENT_RACE_LAP structure is used in multiplayer racing to hold the results for one player at the end of a lap.
Syntax
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_EVENT_MULTIPLAYER_CLIENT_STARTED
- SIMCONNECT_RECV_EVENT_MULTIPLAYER_SERVER_STARTED
- SIMCONNECT_RECV_EVENT_MULTIPLAYER_SESSION_ENDED
- SIMCONNECT_RECV_EVENT_RACE_END
- SIMCONNECT_RECV_ID
- SimConnect_SubscribeToSystemEvent
- SimConnect API Reference
- SimConnect Structures and Enumerations
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
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.
Working 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 API Reference
- SIMCONNECT_RECV
- SIMCONNECT_RECV_EVENT
- SIMCONNECT_RECV_ID
- SIMCONNECT_RECV_SIMOBJECT_DATA
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_EXTERNAL_SIM_BASE
The SIMCONNECT_RECV_EXTERNAL_SIM_BASE structure is the base structure for all External Sim related structures. Provides the GUID and SimObjectID for this callback.
Syntax
GUID guidExternalSimID;
DWORD dwObjectID;
};
Members
guidExternalSimID
GUID identifying the external sim that should handle this callback.
dwObjectID
Double word containing the ID of the SimObject this callback is related
to.
Remarks
This structure is inherited by
SIMCONNECT_RECV_EXTERNAL_SIM_CREATE,
SIMCONNECT_RECV_EXTERNAL_SIM_DESTROY,
SIMCONNECT_RECV_EXTERNAL_SIM_SIMULATE,
SIMCONNECT_RECV_EXTERNAL_SIM_LOCATION_CHANGED, and
SIMCONNECT_RECV_EXTERNAL_SIM_EVENT.
This structure inherits the SIMCONNECT_RECV structure, so use the SIMCONNECT_RECV_ID enumeration to determine which external sim callback structure has been received.
See the External Sim Overview for more information.
See Also
- SimConnect_RegisterExternalSim
- SimConnect_RegisterExternalSecondarySim
- SimConnect API Reference
- SIMCONNECT_RECV
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_EXTERNAL_SIM_CREATE
The SIMCONNECT_RECV_EXTERNAL_SIM_CREATE structure is used with the External Sim Create callback when a new SimObject is being created that uses an external sim.
Syntax
DWORD dwExternalSimVarCount;
DWORD dwExternalSimVarBase
char szExternalSimData[1];
};
Members
dwExternalSimVarCount
Double word containing the number of External Sim Vars defined in the
vehicles sim.cfg file.
dwExternalSimVarBase
Double word containing the base External Sim Var index for this external
sim (only used by Secondary External Sims).
szExternalSimData
Null terminated string containing the data provided in the vehicles
sim.cfg file.
Remarks
This structure inherits the SIMCONNECT_RECV_EXTERNAL_SIM_BASE structure and adds the additional values used by the External Sim Create Callback.
See the External Sim Overview for more information.
Working Sample
Primary sample | External Sim |
See Also
- SimConnect_RegisterExternalSim
- SimConnect_RegisterExternalSecondarySim
- SimConnect API Reference
- SIMCONNECT_RECV
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_EXTERNAL_SIM_DESTROY
The SIMCONNECT_RECV_EXTERNAL_SIM_DESTROY structure is used with the External Sim Destroy callback when a SimObject that uses an external sim is being destroyed.
Syntax
// no callback specific data
};
Members
No callback specific data defined at this time.
Remarks
This structure inherits the SIMCONNECT_RECV_EXTERNAL_SIM_BASE structure and adds the additional values used by the External Sim Destroy Callback.
See the External Sim Overview for more information.
Working Sample
Primary sample | External Sim |
See Also
- SimConnect_RegisterExternalSim
- SimConnect_RegisterExternalSecondarySim
- SimConnect API Reference
- SIMCONNECT_RECV
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_EXTERNAL_SIM_SIMULATE
The SIMCONNECT_RECV_EXTERNAL_SIM_SIMULATE structure is used with the External Sim Simulate callback when a SimObject that uses an external sim is being simulated.
Syntax
double fDeltaTime;
BOOL bShouldSimulate;
DWORD dwDefineID;
DWORD dwDefineCount;
DWORD dwData;
};
Members
fDeltaTime
Double floating point value specifying the time-delta for this sim frame
bShouldSimulate
Boolean value that denotes whether the external sim should actually
simulate this frame or not (don't simulate when this is false).
dwDefineID
Double word containing the data structure definition ID for the data
starting at dwData.
dwDefineCount
Double word containing the number of Datums (not bytes) being returned
dwData
Start of the returned data structure, take the address of dwData and
cast it to an appropriate pointer.
Remarks
This structure inherits the SIMCONNECT_RECV_EXTERNAL_SIM_BASE structure and adds the additional values used by the External Sim Simulate Callback.
See the External Sim Overview for more information.
Working Sample
Primary sample | External Sim |
See Also
- SimConnect_RegisterExternalSim
- SimConnect_RegisterExternalSecondarySim
- SimConnect API Reference
- SIMCONNECT_RECV
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_EXTERNAL_SIM_LOCATION_CHANGED
The SIMCONNECT_RECV_EXTERNAL_SIM_LOCATION_CHANGED structure is used with the External Sim Location Changed callback when a SimObject that uses an external sim has been moved/relocated.
Syntax
double fLatRadians;
double fLonRadians;
double fAltMeters;
BOOL bPlaceOnGround;
BOOL bZeroSpeed;
};
Members
fLatRadians
Double floating point value containing new locations Latitude value
in radians.
fLonRadians
Double floating point value containing new locations Longitude value
in radians.
fAltMeters
Double floating point value containing new locations Altitude value
in meters.
bPlaceOnGround
Boolean value, true if vehicle should be force placed onto the ground.
bZeroSpeed
Boolean value, true if all vehicle accelerations/velocities should be
reset to zero.
Remarks
This structure inherits the SIMCONNECT_RECV_EXTERNAL_SIM_BASE structure and adds the additional values used by the External Sim Location Changed Callback.
See the External Sim Overview for more information.
Working Sample
Primary sample | External Sim |
See Also
- SimConnect_RegisterExternalSim
- SimConnect_RegisterExternalSecondarySim
- SimConnect API Reference
- SIMCONNECT_RECV
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_EXTERNAL_SIM_EVENT
The SIMCONNECT_RECV_EXTERNAL_SIM_EVENT structure is used with the External Sim Event callback when a SimObject that uses an external sim receives an event. The events the external sim client wishes to receive are mapped by calls to the SimConnect_MapClientEventToSimEvent function.
Syntax
DWORD uEventID;
DWORD dwData
};
Members
uEventID
Double word containing the client defined event ID for this event.
dwExternalSimVarBase
Double word containing any data associated with this event.
Remarks
This structure inherits the SIMCONNECT_RECV_EXTERNAL_SIM_BASE structure and adds the additional values used by the External Sim Event Callback.
See the External Sim Overview for more information.
Working Sample
Primary sample | External Sim |
See Also
- SimConnect_RegisterExternalSim
- SimConnect_RegisterExternalSecondarySim
- SimConnect_MapClientEventToSimEvent
- SimConnect API Reference
- SIMCONNECT_RECV
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_EVENT_WEAPON
The SIMCONNECT_RECV_EVENT_WEAPON structure is sent to a client when they have requested to be notified of a detachable weapon being fired or detonated.
Syntax
DWORD dwRequestID;
char szWeaponTitle[MAX_PATH];
char szWeaponType[MAX_PATH];
DWORD dwObjectID;
DWORD dwAttackerID;
DWORD dwTargetID;
SIMCONNECT_DATA_LATLONALT llaPosition;
DWORD dwResult;
DWORD dwFlags;
};
Members
dwRequestIDDouble word containing the client defined request ID.
szWeaponTitle[MAX_PATH]
Null terminated string containing the weapon title.
szWeaponType[MAX_PATH]
Null terminated string containing the weapon type.
dwObjectID
Double word containing the object ID of the weapon.
dwAttackerID
Double word containing the object ID of the object that fired the weapon.
dwTargetID
Double word containing the object ID of the weapon's designed target.
llaPosition
SIMCONNECT_DATA_LATLONALT structure containing the object position.
dwResult
Result of the weapon event. Specifies if the event was a firing (0), an armed hit (1), or an unarmed hit (2).
dwFlags
Double word containing any flags. Reserved for future use.
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_WEAPON.
See Also
- SIMCONNECT_RECV_EVENT_COUNTERMEASURE
- SIMCONNECT_RECV_EVENT_OBJECT_DAMAGED_BY_WEAPON
- SIMCONNECT_RECV_ID
- SimConnect API Reference
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_EVENT_COUNTERMEASURE
The SIMCONNECT_RECV_EVENT_COUNTERMEASURE structure is sent to a client when they have requested to be notified of a deployed countermeasure.
Syntax
DWORD dwRequestID;
char szCountermeasureName[MAX_PATH];
DWORD dwObjectID;
DWORD dwAttackerID;
SIMCONNECT_DATA_LATLONALT llaPosition;
DWORD dwFlags;
};
Members
dwRequestIDDouble word containing the client defined request ID.
szCountermeasureName[MAX_PATH]
Null terminated string containing the countermeasure name.
dwObjectID
Double word containing the object ID of the countermeasure.
dwAttackerID
Double word containing the object ID of the object that released the countermeasure.
llaPosition
SIMCONNECT_DATA_LATLONALT structure containing the object position.
dwFlags
Double word containing any flags. Reserved for future use.
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_COUNTERMEASURE.
See Also
- SIMCONNECT_RECV_EVENT_WEAPON
- SIMCONNECT_RECV_EVENT_OBJECT_DAMAGED_BY_WEAPON
- SIMCONNECT_RECV_ID
- SimConnect API Reference
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_EVENT_OBJECT_DAMAGED_BY_WEAPON
The SIMCONNECT_RECV_EVENT_OBJECT_DAMAGED_BY_WEAPON structure is sent to a client when they have requested to be notified of an object being damaged by a weapon.
Syntax
DWORD dwRequestID;
SIMCONNECT_DATA_OJBECT_DAMAGED_BY_WEAPON DamageData;
DWORD dwFlags;
};
Members
dwRequestIDDouble word containing the client defined request ID.
DamageData
SIMCONNECT_DATA_OBJECT_DAMAGED_BY_WEAPON structure containing the data of an object damaged by a weapon.
dwFlags
Double word containing any flags. Reserved for future use.
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_OBJECT_DAMAGED_BY_WEAPON.
See Also
- SIMCONNECT_RECV_EVENT_WEAPON
- SIMCONNECT_RECV_EVENT_COUNTERMEASURE
- SIMCONNECT_RECV_ID
- SimConnect API Reference
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_FLIGHT_SEGMENT
Received by the client after a successful call to SimConnect_RequestFlightSegmentDataByGUID or SimConnect_RequestFlightSegmentDataByIndex containing data about the requested flight segment.
Syntax
DWORD dwRequestID;
GUID guidInstanceID;
GUID guidSegmentGoalID;
DWORD dwParameterCount;
DWORD dwTotalRangeCount;
};
Members
dwRequestID
Double word containing the client defined request ID.
guidInstanceID
Guid Instance id of the flight segment.
guidSegmentGoalID
Guid Instance id of the flight segment's goal.
dwParameterCount
Double word containing the number of parameters that are being graded
in this flight segment.
dwTotalRangeCount
Double word containing the total number of ranges combined for all parameters
that are graded with this flight segment.
Working Samples
Primary samples | Managed Mission Objects |
Remarks
This structure inherits the SIMCONNECT_RECV structure and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_FLIGHT_SEGMENT.
See Also
- SimConnect_RequestFlightSegmentDataByGUID
- SimConnect_RequestFlightSegmentDataByIndex
- SimConnect API Reference
- SIMCONNECT_RECV
- SIMCONNECT_RECV_EXCEPTION
- SIMCONNECT_RECV_ID
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_FLIGHT_SEGMENT_READY_FOR_GRADING
Received by the client with a FlightSegmentReadyForGrading notification. Contains instance ID of the Flight Segment.
Syntax
GUID guidInstanceID;
};
Members
guidInstanceID
Guid Instance id of the flight segment that is ready for grading.
Working Samples
Primary samples | Managed Mission Objects |
Remarks
This structure inherits the SIMCONNECT_RECV structure and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_FLIGHT_SEGMENT_READY_FOR_GRADING.
See Also
- SimConnect_SubscribeToSystemEvent
- SimConnect API Reference
- SIMCONNECT_RECV
- SIMCONNECT_RECV_EXCEPTION
- SIMCONNECT_RECV_ID
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_GOAL
Received by the client after a successful call to SimConnect_RequestGoalDataByGUID or SimConnect_RequestGoalDataByIndex.
Syntax
DWORD dwRequestID;
GUID guidInstanceID;
BOOL isOptional;
DWORD dwOrder;
DWORD dwPointValue;
SIMCONNECT_GOAL_STATE eGoalState;
DWORD dwChildGoalCount;
char szGoalText[256];
char szGoalSucceededText[256];
char szGoalFailedText[256];
};
Members
dwRequestID
Double word containing the client defined request ID.
guidInstanceID
Guid Instance id of the goal.
isOptional
Boolean value, true if the goal is optional to scenario completion.
dwOrder
Double word containing the priority order of the goal.
dwPointValue
Double word containing the point value of the goal.
eGoalState
Enum value, defined in SIMCONNECT_GOAL_STATE,
specifying the state of the goal.
dwChildGoalCount
Double word specifying how many child goals are attached to this goal.
szGoalText
Null-terminated string containing the goal text.
szGoalSucceededText
Null-terminated string containing additional text to articulate the
Goal Passed state.
szGoalFailedText
Null-terminated string containing additional text to articulate the
Goal Failed state.
Working Samples
Primary samples | Managed Mission Objects |
Remarks
This structure inherits the SIMCONNECT_RECV structure and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_GOAL.
See Also
- SIMCONNECT_GOAL_STATE
- SimConnect_RequestGoalDataByGUID
- SimConnect_RequestGoalDataByIndex
- SimConnect API Reference
- SIMCONNECT_RECV
- SIMCONNECT_RECV_EXCEPTION
- SIMCONNECT_RECV_ID
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_GOAL_PAIR
Received by the client after a successful call to SimConnect_RequestChildGoalDataByIndex.
Syntax
DWORD dwRequestID;
GUID guidChildInstanceID;
GUID guidParentInstanceID;
};
Members
dwRequestID
Double word containing the client defined request ID.
guidChildInstanceID
Guid Instance id of the child goal.
guidParentInstanceID
Guid Instance id of the parent goal that owns the child.
Remarks
This structure inherits the SIMCONNECT_RECV structure and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_GOAL_PAIR.
See Also
- SimConnect API Reference
- SIMCONNECT_RECV
- SIMCONNECT_RECV_EXCEPTION
- SIMCONNECT_RECV_ID
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_MISSION_OBJECT_COUNT
Received by the client after a successful call to SimConnect_RequestFlightSegmentCount, SimConnect_RequestGoalCount, or SimConnect_RequestMissionObjectiveCount.
Syntax
DWORD dwRequestID;
SIMCONNECT_MISSION_OBJECT_TYPE eMissionObjectType;
DWORD dwCount;
};
Members
dwRequestID
Double word containing the client defined request ID.
eMissionObjectType
The requested object type whose value types reside in the
SIMCONNECT_MISSION_OBJECT_TYPE enumeration.
dwCount
Double word containing the count of the requested object type in the
active scenario.
Working Samples
Primary samples | Managed Mission Objects |
Remarks
This structure inherits the SIMCONNECT_RECV structure and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_MISSION_OBJECT_COUNT.
See Also
- SIMCONNECT_MISSION_OBJECT_TYPE
- SimConnect_RequestFlightSegmentCount
- SimConnect_RequestGoalCount
- SimConnect_RequestMissionObjectiveCount
- SimConnect API Reference
- SIMCONNECT_RECV
- SIMCONNECT_RECV_EXCEPTION
- SIMCONNECT_RECV_ID
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_MISSION_OBJECTIVE
Received by the client after a successful call to SimConnect_RequestMissionObjectiveDataByGUID or SimConnect_RequestMissionObjectiveDataByIndex.
Syntax
DWORD dwRequestID;
GUID guidInstanceID;
BOOL isOptional;
BOOL isObjectivePassed;
SIMCONNECT_MISSION_OBJECTIVE_STATUS eMissionObjectiveStatus;
DWORD dwPassValue;
DWORD dwCurrentScore;
DWORD dwTotalPossiblePoints;
DWORD dwPointValue;
DWORD dwOrder;
DWORD dwChildGoalCount;
char szMissionObjectiveText[256];
};
Members
dwRequestID
Double word containing the client defined request ID.
guidInstanceID
Guid Instance id of the mission objective.
isOptional
Boolean value, true if the mission objective is optional to scenario
completion.
isObjectivePassed
Boolean value, true if the mission objective is passed.
eMissionObjectiveStatus
Enumeration value, defined as
SIMCONNECT_MISSION_OBJECTIVE_STATUS, that specifies the status of
the mission objective .
dwPassValue
Double word containing the value needed to pass the mission objective.
dwCurrentScore
Double word containing the current score of the mission objective.
dwTotalPossiblePoints
Double word containing the maximum total score possible for the mission
objective.
dwPointValue
Double word containing the client defined request ID.
dwOrder
Double word containing the number of points the mission objective is
worth when passed.
dwChildGoalCount
Double word specifying how many child goals are attached to this mission
objective.
szMissionObjectiveText
Null-terminated string containing the mission objective text.
Working Samples
Primary samples | Managed Mission Objects |
Remarks
This structure inherits the SIMCONNECT_RECV structure and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_MISSION_OBJECTIVE.
See Also
- SIMCONNECT_MISSION_OBJECTIVE_STATUS
- SimConnect_RequestMissionObjectiveDataByGUID
- SimConnect_RequestMissionObjectiveDataByIndex
- SimConnect API Reference
- SIMCONNECT_RECV
- SIMCONNECT_RECV_EXCEPTION
- SIMCONNECT_RECV_ID
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_PARAMETER_RANGE
Received by the client after a successful call to SimConnect_RequestFlightSegmentRangeData.
Syntax
DWORD dwRequestID;
DWORD dwExceededCount;
DWORD dwMaxOverMeasured;
DWORD dwMinUnderMeasured;
GUID guidFlightSegmentID;
DWORD dwColorRedComponent;
DWORD dwColorGreenComponent;
DWORD dwColorBlueComponent;
char szRangeName[256];
char szParameterName[256];
char szParameterUnitsString[256];
};
Members
dwRequestID
Double word containing the client defined request ID.
dwExceededCount
Double word containing the number of times this range was exceeded in
either direction, checking every second.
dwMaxOverMeasured
Double word containing the upper bound of this range, in terms of value
above the measured value.
dwMinUnderMeasured
Double word containing the lower bound of this range, in terms of value
below the measured value.
guidFlightSegmentID
The guid instance ID of the flight segment that owns this parameter
range.
dwColorRedComponent
The Red component of the Range Color specified as a byte (0-255).
dwColorGreenComponent
The Green component of the Range Color specified as a byte (0-255).
dwColorBlueComponent
The Blue component of the Range Color specified as a byte (0-255).
szRangeName
Null-terminated string containing the range name.
szParameterName
Null-terminated string containing the parameter name.
szParameterUnitsString
Null-terminated string containing the units that the parameter is in
terms of.
Working Samples
Primary samples | Managed Mission Objects |
Remarks
This structure inherits the SIMCONNECT_RECV structure and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_PARAMETER_RANGE.
See Also
- SimConnect_RequestFlightSegmentRangeData
- SimConnect API Reference
- SIMCONNECT_RECV
- SIMCONNECT_RECV_EXCEPTION
- SIMCONNECT_RECV_ID
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_PLAYBACK_STATE_CHANGED
Received by the client with a PlaybackStateChanged notification. Contains whether playback has started or ended and the file name of the recording.
Syntax
BOOL hasPlaybackStarted;
char szRecordingFileName[256];
};
Members
hasPlaybackStarted
If true, playback has started. If false, playback has completed.
szRecordingFileName
Null-terminated string containing the file name
of the recording that is being played or just finished playing.
Remarks
This structure inherits the SIMCONNECT_RECV_EVENT structure and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_PLAYBACK_STATE_CHANGED.
See Also
- SimConnect_SubscribeToSystemEvent
- SimConnect API Reference
- SIMCONNECT_RECV
- SIMCONNECT_RECV_EXCEPTION
- SIMCONNECT_RECV_ID
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_RECORDER_STATE_CHANGED
Received by the client with a RecorderStateChanged notification. Contains whether recording has started or ended.
Syntax
BOOL hasRecordingStarted;
};
Members
hasRecordingStarted
If true, recording has started. If false, recording has completed.
Remarks
This structure inherits the SIMCONNECT_RECV_EVENT structure and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_RECORDER_STATE_CHANGED.
See Also
- SimConnect_SubscribeToSystemEvent
- SimConnect API Reference
- SIMCONNECT_RECV
- SIMCONNECT_RECV_EXCEPTION
- SIMCONNECT_RECV_ID
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_RECORDING_INFO
Received by the client after a successful call to SimConnect_RequestRecordingInfo
Syntax
DWORD dwRequestID;
double startTime;
double endTime;
DWORD bookmarkCount;
char szTitle[MAX_PATH];
char szDescription[MAX_PATH];
char szUserContainerTitle[MAX_PATH];
char szFilename[MAX_PATH];
};
Members
dwRequestID
Double word containing the client defined request ID.
startTime
The start time of the recording in absolute seconds in simulation zulu time.
endTime
The end time of the recording in absolute seconds in simulation zulu time.
bookmarkCount
The number of bookmarks in the recording.
szTitle
The title of the recording.
szDescription
The description of the recording.
szUserContainerTitle
The container title of the user object used during the recording.
szFilename
The file name of the recording.
Remarks
This structure inherits the SIMCONNECT_RECV structure and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_RECORDING_INFO.
See Also
SIMCONNECT_RECV_RECORDING_BOOKMARK_INFO
Received by the client after a successful call to SimConnect_RequestBookmarkInfo
Syntax
DWORD dwRequestID;
double timeStamp;
DWORD bookmarkIndex;
char szTitle[MAX_PATH];
char szRecordingFilename[MAX_PATH];
};
Members
dwRequestID
Double word containing the client defined request ID.
timeStamp
The time of the bookmark in absolute seconds in simulation zulu time.
bookmarkIndex
The index of the bookmark.
szTitle
The title of the bookmark.
szRecordingFilename
The file name of the recording for the bookmark.
Remarks
This structure inherits the SIMCONNECT_RECV structure and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_RECORDING_BOOKMARK_INFO.
See Also
SIMCONNECT_RECV_LANDING_TRIGGER_INFO
Received by the client after a successful call to SimConnect_RequestLandingTriggerLandingInfoCount.
Syntax
DWORD dwRequestID;
GUID landingTriggerInstanceID;
int landingsCount;
};
Members
dwRequestID
Double word containing the client defined request ID.
landingTriggerInstanceID
Guid Instance id of the landing trigger which can be used in
SimConnect_RequestLandingTriggerLandingInfoByIndex.
landingsCount
The total amount of landings that met the landing trigger's criteria.
Remarks
This structure inherits the SIMCONNECT_RECV structure and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_LANDING_TRIGGER_INFO.
See Also
- SimConnect_RequestLandingTriggerLandingInfoCount
- SimConnect API Reference
- SIMCONNECT_RECV
- SIMCONNECT_RECV_EXCEPTION
- SIMCONNECT_RECV_ID
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_LANDING_INFO
Received by the client after a successful call to SimConnect_RequestLandingTriggerLandingInfoByIndex.
Syntax
DWORD dwRequestID;
GUID LandingTriggerInstanceID;
SIMCONNECT_LANDING_TYPE LandingType;
double Latitude;
double Longitude;
double Altitude;
};
Members
dwRequestID
Double word containing the client defined request ID.
landingTriggerInstanceID
Guid Instance id of the landing trigger.
LandingType
Type of landing trigger specified by the
SIMCONNECT_LANDING_TYPE enumeration.
Latitude
Latitude of the specified landing in degrees.
Longitude
Longitude of the specified landing in degrees.
Altitude
Altitude of the specified landing in feet.
Remarks
This structure inherits the SIMCONNECT_RECV structure and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_LANDING_INFO.
See Also
- SimConnect_RequestLandingTriggerLandingInfoByIndex
- SimConnect API Reference
- SIMCONNECT_RECV
- SIMCONNECT_RECV_EXCEPTION
- SIMCONNECT_RECV_ID
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_GROUND_INFO
The SIMCONNECT_RECV_GROUND_INFO structure is used to return data in response to a call to SimConnect_RequestGroundInfo or SimConnect_RequestGroundInfoOnSimObject.
Syntax
DWORD dwRequestID;
DWORD dwGridWidth;
DWORD dwGridHeight;
DWORD dwArraySize;
DWORD dwFlags;
BOOL bNotAllValid;
SIMCONNECT_DATA_GROUND_INFO rgData[1];
};
Members
dwRequestID;
Double word containing the client defined request ID.
dwGridWidth;
Double word containing the width of the requested grid.
dwGridHeight;
Double word containing the height of the requested grid.
dwArraySize;
Double word containing the number of items in the rgData array
(GridWidth * GridHeight).
dwFlags;
Double word containing the flags that were passed to the
SimConnect_RequestGroundInfo or
SimConnect_RequestGroundInfoOnSimObject function.
bNotAllValid;
Boolean value, true if any of the returned data points is invalid (SIMCONNECT_DATA_GROUND_INFO.bIsValid
is false)
rgData[1];
First element in an array of SIMCONNECT_DATA_GROUND_INFO
items, dwArraySize long.
Remarks
This structure inherits the SIMCONNECT_RECV structure and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_GROUND_INFO.
This structure returns an array of ground info points in response to a call to SimConnect_RequestGroundInfo or SimConnect_RequestGroundInfoOnSimObject.
See the remarks for SimConnect_RequestGroundInfo for more information.
See Also
- SIMCONNECT_DATA_GROUND_INFO
- SimConnect_RequestGroundInfo
- SimConnect_RequestGroundInfoOnSimObject
- SimConnect API Reference
- SimConnect Structures and Enumerations
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
DWORD dwRequestID;
DWORD dwArraySize;
DWORD dwEntry;
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, SIMCONNECT_RECV_TACAN_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_RequestFacilitiesList
- SimConnect API Reference
- SIMCONNECT_RECV
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_JOYSTICK_DEVICE_INFO
The SIMCONNECT_RECV_JOYSTICK_DEVICE_INFO structure is used to provide information on the currently connected joystick devices.
Syntax
DWORD dwRequestID;
DWORD dwArraySize;
SIMCONNECT_DATA_JOYSTICK_DEVICE_INFO rgData[1];
};
Members
dwRequestID
Double word containing the client defined request ID.
dwArraySize
Double word containing the number of joystick devices in the list that are within this packet.
rgData
Array of SIMCONNECT_DATA_JOYSTICK_DEVICE_INFO structures.
Remarks
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_RequestJoystickDeviceInfo.
See Also
- SimConnect_RequestJoystickDeviceInfo
- SimConnect API Reference
- SIMCONNECT_RECV
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_MOBILE_SCENERY_IN_RADIUS
The SIMCONNECT_RECV_MOBILE_SCENERY_IN_RADIUS structure is used to provide identification information on mobile scenery objects within a specified radius of the user vehicle.
Syntax
DWORD dwRequestID;
DWORD dwArraySize;
SIMCONNECT_DATA_MOBILE_SCENERY_INFO rgData[1];
};
Members
dwRequestID
Double word containing the client defined request ID.
dwArraySize
Double word containing the number of mobile scenery objects in the list that are within this packet.
rgData
Array of SIMCONNECT_DATA_MOBILE_SCENERY_INFO structures.
Remarks
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_RequestMobileSceneryInRadius.
See Also
- SimConnect_RequestMobileSceneryInRadius
- SimConnect_RequestMobileSceneryDataByID
- SimConnect API Reference
- SIMCONNECT_RECV
- SIMCONNECT_DATA_MOBILE_SCENERY_INFO
- SIMCONNECT_RECV_MOBILE_SCENERY_DATA
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_MOBILE_SCENERY_DATA
The SIMCONNECT_RECV_MOBILE_SCENERY_DATA structure is used to provide data about a mobile scenery object with the specified object ID.
Syntax
DWORD dwRequestID;
SIMCONNECT_GUID guidInstanceID;
SIMCONNECT_DATA_LATLONALT llaWorldPosition;
SIMCONNECT_DATA_PBH pbhWorldRotation;
BOOL isOnGround;
double speedKnots;
float scale;
DWORD dwObjectID;
};
Members
dwRequestID
Double word containing the client defined request ID.
guidInstanceID
Scenario Instance id of the mobile scenery object.
llaWorldPosition
A SIMCONNECT_DATA_LATLONALT containing the world position of the mobile scenery object in degrees (altitude in feet).
pbhWorldRotation
A SIMCONNECT_DATA_PBH containing the world rotation of the mobile scenery object in radians.
isOnGround
A bool containing whether or not the mobile scenery object is clamped to the ground.
speedKnots
A double containing the speed of the mobile scenery object in knots.
scale
A float containing the scale of the mobile scenery object. 1 is the default scale of the object. Anything else is the default size of the object multiplied by the scale.
dwObjectID
Double word containing the object ID of the mobile scenery object.
Remarks
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_RequestMobileSceneryDataByID.
See Also
- SimConnect_RequestMobileSceneryInRadius
- SimConnect_RequestMobileSceneryDataByID
- SimConnect API Reference
- SIMCONNECT_RECV
- SIMCONNECT_DATA_MOBILE_SCENERY_INFO
- SIMCONNECT_RECV_MOBILE_SCENERY_IN_RADIUS
- SimConnect Structures and Enumerations
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
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_WEATHER_OBSERVATION,
SIMCONNECT_RECV_ID_CLOUD_STATE,
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_TACAN_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,
SIMCONNECT_RECV_ID_OBSERVER_DATA,
SIMCONNECT_RECV_ID_GROUND_INFO,
SIMCONNECT_RECV_ID_SYNCHRONOUS_BLOCK,
SIMCONNECT_RECV_ID_EXTERNAL_SIM_CREATE,
SIMCONNECT_RECV_ID_EXTERNAL_SIM_DESTROY,
SIMCONNECT_RECV_ID_EXTERNAL_SIM_SIMULATE,
SIMCONNECT_RECV_ID_EXTERNAL_SIM_LOCATION_CHANGED,
SIMCONNECT_RECV_ID_EXTERNAL_SIM_EVENT,
SIMCONNECT_RECV_ID_EVENT_WEAPON,
SIMCONNECT_RECV_ID_EVENT_COUNTERMEASURE,
SIMCONNECT_RECV_ID_EVENT_OBJECT_DAMAGED_BY_WEAPON,
SIMCONNECT_RECV_ID_VERSION,
SIMCONNECT_RECV_ID_SCENERY_COMPLEXITY,
SIMCONNECT_RECV_ID_SHADOW_FLAGS,
SIMCONNECT_RECV_ID_TACAN_LIST,
SIMCONNECT_RECV_ID_CAMERA_6DOF,
SIMCONNECT_RECV_ID_CAMERA_FOV,
SIMCONNECT_RECV_ID_CAMERA_SENSOR_MODE,
SIMCONNECT_RECV_ID_CAMERA_WINDOW_POSITION,
SIMCONNECT_RECV_ID_CAMERA_WINDOW_SIZE,
SIMCONNECT_RECV_ID_MISSION_OBJECT_COUNT,
SIMCONNECT_RECV_ID_GOAL,
SIMCONNECT_RECV_ID_MISSION_OBJECTIVE,
SIMCONNECT_RECV_ID_FLIGHT_SEGMENT,
SIMCONNECT_RECV_ID_PARAMETER_RANGE,
SIMCONNECT_RECV_ID_FLIGHT_SEGMENT_READY_FOR_GRADING,
SIMCONNECT_RECV_ID_GOAL_PAIR,
SIMCONNECT_RECV_ID_EVENT_FLIGHT_ANALYSIS_DIAGRAMS,
SIMCONNECT_RECV_ID_LANDING_TRIGGER_INFO,
SIMCONNECT_RECV_ID_LANDING_INFO,
SIMCONNECT_RECV_ID_SESSION_DURATION,
SIMCONNECT_RECV_ID_ATTACHPOINT_DATA,
SIMCONNECT_RECV_ID_PLAYBACK_STATE_CHANGED,
SIMCONNECT_RECV_ID_RECORDER_STATE_CHANGED,
SIMCONNECT_RECV_ID_RECORDING_INFO,
SIMCONNECT_RECV_ID_RECORDING_BOOKMARK_INFO,
SIMCONNECT_RECV_ID_TRAFFIC_SETTINGS,
SIMCONNECT_RECV_ID_JOYSTICK_DEVICE_INFO,
SIMCONNECT_RECV_ID_MOBILE_SCENERY_IN_RADIUS,
SIMCONNECT_RECV_ID_MOBILE_SCENERY_DATA,
};
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 Prepar3D.
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_EVENT_WEATHER_MODE
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_TACAN_LIST
Specifies that a SIMCONNECT_RECV_TACAN_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 structure 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.
SIMCONNECT_RECV_ID_OBSERVER_DATA
Specifies that a SIMCONNECT_RECV_OBSERVER_DATA structure has been received.
SIMCONNECT_RECV_ID_GROUND_INFO
Specifies that a SIMCONNECT_RECV_GROUND_INFO structure has been received.
SIMCONNECT_RECV_ID_SYNCHRONOUS_BLOCK
Specifies that a SIMCONNECT_RECV_SYNCHRONOUS_BLOCK structure has been received.
SIMCONNECT_RECV_ID_EXTERNAL_SIM_CREATE
Specifies that a SIMCONNECT_RECV_EXTERNAL_SIM_CREATE structure has been received.
SIMCONNECT_RECV_ID_EXTERNAL_SIM_DESTROY
Specifies that a SIMCONNECT_RECV_EXTERNAL_SIM_DESTROY structure has been received.
SIMCONNECT_RECV_ID_EXTERNAL_SIM_SIMULATE
Specifies that a SIMCONNECT_RECV_EXTERNAL_SIM_SIMULATE structure has been received.
SIMCONNECT_RECV_ID_EXTERNAL_SIM_LOCATION_CHANGED
Specifies that a SIMCONNECT_RECV_EXTERNAL_SIM_LOCATION_CHANGED structure has been received.
SIMCONNECT_RECV_ID_EXTERNAL_SIM_EVENT
Specifies that a SIMCONNECT_RECV_EXTERNAL_SIM_EVENT structure has been received.
SIMCONNECT_RECV_ID_EVENT_WEAPON
Specifies that a SIMCONNECT_RECV_EVENT_WEAPON structure has been received.
SIMCONNECT_RECV_ID_EVENT_COUNTERMEASURE
Specifies that a SIMCONNECT_RECV_EVENT_COUNTERMEASUREstructure has been received.
SIMCONNECT_RECV_ID_EVENT_OBJECT_DAMAGED_BY_WEAPON
Specifies that a SIMCONNECT_RECV_ID_EVENT_OBJECT_DAMAGED_BY_WEAPONstructure has been received.
SIMCONNECT_RECV_ID_VERSION
Specifies that a SIMCONNECT_RECV_VERSION structure has been received.
SIMCONNECT_RECV_ID_SCENERY_COMPLEXITY
Specifies that a SIMCONNECT_RECV_SCENERY_COMPLEXITY structure has been received.
SIMCONNECT_RECV_ID_SHADOW_FLAGS
Specifies that a SIMCONNECT_RECV_SHADOW_FLAGS structure has been received.
SIMCONNECT_RECV_ID_SESSION_DURATION
Specifies that a SIMCONNECT_RECV_SESSION_DURATION structure has been received.
SIMCONNECT_RECV_ID_TACAN_LIST
Specifies that a SIMCONNECT_RECV_TACAN_LIST structure has been received.
SIMCONNECT_RECV_ID_CAMERA_6DOF
Specifies that a SIMCONNECT_RECV_CAMERA_6DOF structure has been received.
SIMCONNECT_RECV_ID_CAMERA_FOV
Specifies that a SIMCONNECT_RECV_FOV structure has been received.
SIMCONNECT_RECV_ID_CAMERA_SENSOR_MODE
Specifies that a SIMCONNECT_RECV_CAMERA_SENSOR_MODE structure has been received.
SIMCONNECT_RECV_ID_CAMERA_WINDOW_POSITION
Specifies that a SIMCONNECT_RECV_CAMERA_WINDOW_POSITION structure has been received.
SIMCONNECT_RECV_ID_CAMERA_WINDOW_SIZE
Specifies that a SIMCONNECT_RECV_CAMERA_WINDOW_SIZE structure has been received.
SIMCONNECT_RECV_ID_MISSION_OBJECT_COUNT
Specifies that a SIMCONNECT_RECV_MISSION_OBJECT_COUNT structure has been received.
SIMCONNECT_RECV_ID_GOAL
Specifies that a SIMCONNECT_RECV_GOAL structure has been received.
SIMCONNECT_RECV_ID_MISSION_OBJECTIVE
Specifies that a SIMCONNECT_RECV_MISSION_OBJECTIVE structure has been received.
SIMCONNECT_RECV_ID_FLIGHT_SEGMENT
Specifies that a SIMCONNECT_RECV_FLIGHT_SEGMENT structure has been received.
SIMCONNECT_RECV_ID_PARAMETER_RANGE
Specifies that a SIMCONNECT_RECV_PARAMETER_RANGE structure has been received.
SIMCONNECT_RECV_ID_FLIGHT_SEGMENT_READY_FOR_GRADING
Specifies that a SIMCONNECT_RECV_FLIGHT_SEGMENT_READY_FOR_GRADING structure has been received.
SIMCONNECT_RECV_ID_GOAL_PAIR
Specifies that a SIMCONNECT_RECV_GOAL_PAIR structure has been received.
SIMCONNECT_RECV_ID_EVENT_FLIGHT_ANALYSIS_DIAGRAMS
Specifies that a SIMCONNECT_RECV_EVENT_FLIGHT_ANALYSIS_DIAGRAMS structure has been received.
SIMCONNECT_RECV_ID_LANDING_TRIGGER_INFO
Specifies that a SIMCONNECT_RECV_LANDING_TRIGGER_INFO structure has been received.
SIMCONNECT_RECV_ID_LANDING_INFO
Specifies that a SIMCONNECT_RECV_LANDING_INFO structure has been received.
SIMCONNECT_RECV_ID_SESSION_DURATION
Specifies that a SIMCONNECT_RECV_SESSION_DURATION structure has been received.
SIMCONNECT_RECV_ID_ATTACHPOINT_DATA
Specifies that a SIMCONNECT_RECV_ATTACHPOINT_DATA structure has been received.
SIMCONNECT_RECV_ID_PLAYBACK_STATE_CHANGED
Specifies that a SIMCONNECT_RECV_PLAYBACK_STATE_CHANGED structure has been received.
SIMCONNECT_RECV_ID_RECORDER_STATE_CHANGED
Specifies that a SIMCONNECT_RECV_RECORDER_STATE_CHANGED structure has been received.
SIMCONNECT_RECV_ID_RECORDING_INFO
Specifies that a SIMCONNECT_RECV_RECORDING_INFO structure has been received.
SIMCONNECT_RECV_ID_RECORDING_BOOKMARK_INFO
Specifies that a SIMCONNECT_RECV_RECORDING_BOOKMARK_INFO structure has been received.
SIMCONNECT_RECV_ID_TRAFFIC_SETTINGS
Specifies that a SIMCONNECT_RECV_TRAFFIC_SETTINGS structure has been received.
SIMCONNECT_RECV_ID_JOYSTICK_DEVICE_INFO
Specifies that a SIMCONNECT_RECV_JOYSTICK_DEVICE_INFO structure has been received.
SIMCONNECT_RECV_ID_MOBILE_SCENERY_IN_RADIUS
Specifies that a SIMCONNECT_RECV_MOBILE_SCENERY_IN_RADIUS structure has been received.
SIMCONNECT_RECV_ID_MOBILE_SCENERY_DATA
Specifies that a SIMCONNECT_RECV_MOBILE_SCENERY_DATA structure has been received.
SIMCONNECT_RECV_NDB_LIST
The SIMCONNECT_RECV_NDB_LIST structure is used to return a list of SIMCONNECT_DATA_FACILITY_NDB structures.
Syntax
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_RequestFacilitiesList
- SIMCONNECT_RECV_AIRPORT_LIST
- SIMCONNECT_RECV_FACILITIES_LIST
- SIMCONNECT_RECV_VOR_LIST
- SIMCONNECT_RECV_WAYPOINT_LIST
- SimConnect API Reference
- SIMCONNECT_RECV
- SimConnect Structures and Enumerations
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
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.
dwObjectID
Double word containing the server defined object ID.
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.
Working 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 API Reference
- SIMCONNECT_RECV
- SIMCONNECT_RECV_EVENT
- SIMCONNECT_RECV_EXCEPTION
- SIMCONNECT_RECV_ID
- SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE
- SimConnect Structures and Enumerations
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
};
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 API Reference
- SIMCONNECT_RECV
- SIMCONNECT_RECV_ID
- SIMCONNECT_RECV_SIMOBJECT_DATA
- SimConnect_RequestDataOnSimObjectType
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_OPEN
The SIMCONNECT_RECV_OPEN structure is used to return information to the client, after a successful call to SimConnect_Open.
Syntax
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 API Reference
- SIMCONNECT_RECV
- SIMCONNECT_RECV_EXCEPTION
- SIMCONNECT_RECV_ID
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_RESERVED_KEY
The SIMCONNECT_RECV_RESERVED_KEY structure is used with the SimConnect_RequestReservedKey function to return the reserved key combination.
Syntax
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.
Working 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 API Reference
- SIMCONNECT_RECV
- SIMCONNECT_RECV_EXCEPTION
- SIMCONNECT_RECV_ID
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_SCENERY_COMPLEXITY
The SIMCONNECT_RECV_SCENERY_COMPLEXITY structure is used with the SimConnect_RequestSceneryComplexity function to retrieve the current scenery complexity setting.
Syntax
DWORD dwRequestID;
DWORD dwSceneryComplexity;
};
Members
dwRequestID
Double word containing the client defined request ID.
dwSceneryComplexity
Double word containing the current scenery complexity. See ENUM
SIMCONNECT_SCENERY_COMPLEXITY.
Working Samples
Primary samples | Scenery Complexity and Shadow Flags |
Remarks
This structure inherits the SIMCONNECT_RECV structure and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_SCENERY_COMPLEXITY.
See Also
- SimConnect API Reference
- SIMCONNECT_RECV
- SIMCONNECT_RECV_EXCEPTION
- SIMCONNECT_RECV_ID
- SIMCONNECT_SCENERY_COMPLEXITY
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_SHADOW_FLAGS
The SIMCONNECT_RECV_SHADOW_FLAGS structure is used with the SimConnect_RequestShadowFlags function to retrieve the current shadow settings.
Syntax
DWORD dwRequestID;
DWORD dwShadowFlags;
};
Members
dwRequestID
Double word containing the client defined request ID.
dwShadowFlags
Double word containing the current shadow flag settings. See ENUM SIMCONNECT_SHADOW_FLAGS.
Working Samples
Primary samples | Scenery Complexity and Shadow Flags |
Remarks
This structure inherits the SIMCONNECT_RECV structure and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_SHADOW_FLAGS.
See Also
- SimConnect API Reference
- SIMCONNECT_RECV
- SIMCONNECT_RECV_EXCEPTION
- SIMCONNECT_RECV_ID
- SIMCONNECT_SHADOW_FLAGS
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_SESSION_DURATION
The SIMCONNECT_RECV_SESSION_DURATION structure is used with the SimConnect_RequestSessionDuration function to request the simulated time in seconds since the last scenario load. When in a scenario, the duration is accumulated between scenario saves/loads, such as saving and loading checkpoints.
Syntax
DWORD dwRequestID;
double dSessionDuration;
};
Members
dwRequestID
Double word containing the client defined request ID.
dSessionDuration
A 64-bit floating point number containing the current duration in seconds.
Remarks
This structure inherits the SIMCONNECT_RECV structure and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_SESSION_DURATION.
See Also
- SimConnect API Reference
- SIMCONNECT_RECV
- SIMCONNECT_RECV_EXCEPTION
- SIMCONNECT_RECV_ID
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_SYNCHRONOUS_BLOCK
The SIMCONNECT_RECV_SYNCHRONOUS_BLOCK structure is sent in response to a call to SimConnect_RequestSynchronousBlock function.
Syntax
DWORD dwRequestID;
DWORD dwFlags;
};
Members
dwRequestIDDouble word containing the client defined request ID.
dwFlags
Double word containing a subset of the SIMCONNECT_DATA_REQUEST_FLAG enum (currently only the SIMCONNECT_DATA_REQUEST_FLAG_BLOCK is supported).
Remarks
This structure inherits the SIMCONNECT_RECV structure and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_SYNCHRONOUS_BLOCK.
See Also
- SimConnect API Reference
- SimConnect_RequestSynchronousBlock
- SIMCONNECT_RECV
- SIMCONNECT_RECV_ID
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_SYSTEM_STATE
The SIMCONNECT_RECV_SYSTEM_STATE structure is used with the SimConnect_RequestSystemState function to retrieve specific Prepar3D systems states and information.
Syntax
DWORD dwRequestID;
DWORD dwInteger;
float fFloat;
char szString[MAX_PATH];
};
Members
dwRequestIDDouble 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 API Reference
- SIMCONNECT_RECV
- SIMCONNECT_RECV_EXCEPTION
- SIMCONNECT_RECV_ID
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_TACAN_LIST
The SIMCONNECT_RECV_TACAN_LIST structure is used to return a list of SIMCONNECT_DATA_FACILITY_TACAN structures.
Syntax
SIMCONNECT_DATA_FACILITY_TACAN rgData[1];
};
Members
rgData[1]
Array of SIMCONNECT_DATA_FACILITY_TACAN
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_RequestFacilitiesList
- SIMCONNECT_RECV_AIRPORT_LIST
- SIMCONNECT_RECV_FACILITIES_LIST
- SIMCONNECT_RECV_NDB_LIST
- SIMCONNECT_RECV_WAYPOINT_LIST
- SimConnect API Reference
- SIMCONNECT_RECV
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_TRAFFIC_SETTINGS
The SIMCONNECT_RECV_TRAFFIC_SETTINGS structure is used with the SimConnect_RequestTrafficSettings function to retrieve the current traffic settings.
Syntax
DWORD dwRequestID;
UINT uAirlineDensity;
UINT uGADensity;
UINT uRoadTrafficDensity;
UINT uShipsAndFerriesDensity;
UINT uLeisureBoatDensity;
SIMCONNECT_DYNAMIC_FREQUENCY eAirportVehicleDensity;
BOOL bIFROnly;
};
Members
dwRequestID
Double word containing the client defined request ID.
uAirlineDensity
Unsigned integer containing the current airline traffic density from 0 to 100.
uGADensity
Unsigned integer containing the current general aviation traffic density from 0 to 100.
uRoadTrafficDensity
Unsigned integer containing the current road traffic density from 0 to 100.
uShipsAndFerriesDensity
Unsigned integer containing the current ship and ferry density from 0 to 100.
uLeisureBoatDensity
Unsigned integer containing the current leisure boat traffic density from 0 to 100.
eAirportVehicleDensity
Enumeration containing the current airport vehicle traffic density. See also the enumeration SIMCONNECT_DYNAMIC_FREQUENCY.
bIFROnly
Boolean representing if only IFR traffic should be present.
Working Samples
Primary samples | None |
Remarks
This structure inherits the SIMCONNECT_RECV structure and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_TRAFFIC_SETTINGS.
See Also
- SimConnect API Reference
- SIMCONNECT_RECV
- SIMCONNECT_RECV_EXCEPTION
- SIMCONNECT_RECV_ID
- SIMCONNECT_DYNAMIC_FREQUENCY
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_VERSION
The SIMCONNECT_RECV_VERSION structure is used with the SimConnect_RequestVersion function to retrieve license type, Prepar3D version, and Prepar3D SimConnect version.
Syntax
DWORD dwRequestID;
DWORD dwApplicationVersionType;
DWORD dwApplicationVersionMajor;
DWORD dwApplicationVersionMinor;
DWORD dwApplicationBuildMajor;
DWORD dwApplicationBuildMinor;
DWORD dwSimConnectVersionMajor;
DWORD dwSimConnectVersionMinor;
DWORD dwSimConnectBuildMajor;
DWORD dwSimConnectBuildMinor;
};
Members
dwRequestIDDouble word containing the client defined request ID.
dwApplicationVersionType
Double word containing Application Version Type. See ENUM SIMCONNECT_LICENSE_TYPE.
dwApplicationVersionMajor
Double word containing Application Version Major.
dwApplicationVersionMinor
Double word containing Application Build Minor.
dwApplicationBuildMajor
Double word containing Application Build Major.
dwApplicationBuildMinor
Double word containing Application Version Minor.
dwSimConnectVersionMajor
Double word containing SimConnect Version Major.
dwSimConnectVersionMinor
Double word containing SimConnect Version Minor.
dwSimConnectBuildMajor
Double word containing SimConnect Build Major.
dwSimConnectBuildMinor
Double word containing SimConnect Build Minor.
Remarks
This structure inherits the SIMCONNECT_RECV structure and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_VERSION.
See Also
- SimConnect API Reference
- SIMCONNECT_RECV
- SIMCONNECT_RECV_EXCEPTION
- SIMCONNECT_RECV_ID
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_VOR_LIST
The SIMCONNECT_RECV_VOR_LIST structure is used to return a list of SIMCONNECT_DATA_FACILITY_VOR structures.
Syntax
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_RequestFacilitiesList
- SIMCONNECT_RECV_AIRPORT_LIST
- SIMCONNECT_RECV_FACILITIES_LIST
- SIMCONNECT_RECV_NDB_LIST
- SIMCONNECT_RECV_WAYPOINT_LIST
- SimConnect API Reference
- SIMCONNECT_RECV
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_WAYPOINT_LIST
The SIMCONNECT_RECV_WAYPOINT_LIST structure is used to return a list of SIMCONNECT_DATA_FACILITY_WAYPOINT structures.
Syntax
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_RequestFacilitiesList
- SIMCONNECT_RECV_AIRPORT_LIST
- SIMCONNECT_RECV_FACILITIES_LIST
- SIMCONNECT_RECV_NDB_LIST
- SIMCONNECT_RECV_TACAN_LIST
- SIMCONNECT_RECV_VOR_LIST
- SimConnect API Reference
- SIMCONNECT_RECV
- SimConnect Structures and Enumerations
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
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.
Working 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 API Reference
- SIMCONNECT_RECV_CLOUD_STATE
- SIMCONNECT_RECV
- SIMCONNECT_RECV_EVENT
- SIMCONNECT_RECV_EXCEPTION
- SIMCONNECT_RECV_ID
- SIMCONNECT_RECV_SIMOBJECT_DATA
- SimConnect Structures and Enumerations
SIMCONNECT_RECV_OBSERVER_DATA
The SIMCONNECT_RECV_OBSERVER_DATA structure is used to return observer data, after calls to SimConnect_RequestObserverData.
Syntax
DWORD dwRequestID;
char szObserverName[128];
SIMCONNECT_DATA_OBSERVER ObserverData;
};
Members
dwRequestID
The ID of the client defined request.
szObserverName[128]
The name of the observer.
ObserverData
The all data for the observer.
Working Sample
Primary sample | ManagedObserverControl |
Remarks
This structure inherits the SIMCONNECT_RECV structure and is returned when the dwID parameter of SIMCONNECT_RECV is set to SIMCONNECT_RECV_ID_OBSERVER_DATA.
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
SIMCONNECT_SIMOBJECT_TYPE_USER,
SIMCONNECT_SIMOBJECT_TYPE_ALL,
SIMCONNECT_SIMOBJECT_TYPE_AIRCRAFT,
SIMCONNECT_SIMOBJECT_TYPE_HELICOPTER,
SIMCONNECT_SIMOBJECT_TYPE_BOAT,
SIMCONNECT_SIMOBJECT_TYPE_GROUND
};
Members
SIMCONNECT_SIMOBJECT_TYPE_USER
Specifies the user's aircraft.
SIMCONNECT_SIMOBJECT_TYPE_ALL
Specifies all AI controlled objects.
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.
Working 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 Prepar3D 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.
Seethe remarks and examples for SimConnect_AddToDataDefinition.
See Also
- SimConnect API Reference
- SimConnect_RequestDataOnSimObjectType
- SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE
- SimConnect Structures and Enumerations
SIMCONNECT_STATE
The SIMCONNECT_STATE enumeration type is used with the SimConnect_SetSystemEventState call to turn the reporting of events on and off.
Syntax
SIMCONNECT_STATE_OFF,
SIMCONNECT_STATE_ON
};
Members
SIMCONNECT_STATE_OFF
Specifies off.
SIMCONNECT_STATE_ON
Specifies on.
Working 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
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. |
Working 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 and other simulation 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
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
- TACAN LATLONALT
- INNER MARKER LATLONALT
- MIDDLE MARKER LATLONALT
- OUTER MARKER LATLONALT
See Also
SIMCONNECT_DATA_MARKERSTATE
The SIMCONNECT_DATA_MARKERSTATE structure is used to help graphically link flight model data with the graphics model.
Syntax
char szMarkerName[64];
DWORD dwMarkerState;
};
Members
szMarkerName[64]
Null-terminated string containing the marker name. One from the following
table:
String |
---|
Cg |
ModelCenter |
Wheel |
Skid |
Ski |
Float |
Scrape |
Engine |
Prop |
Eyepoint |
LongScale |
LatScale |
VertScale |
AeroCenter |
WingApex |
RefChord |
Datum |
WingTip |
FuelTank |
Forces |
dwMarkerState
Double word containing the marker state, set to 1 for on and 0 for off.
Remarks
The SimConnect_AddToDataDefinition call can be used to add a SIMCONNECT_DATA_MARKERSTATE structure to a data definition. Use of this call and structure is to help determine that points specified in the flight model of an aircraft match the graphics model for that aircraft, by turning on the specified marker lights. A SimConnect client created to do this becomes a tool to aid to the accurate development of aircraft models, rather than an add-on that an end user might run.
This structure can only be used as input, it cannot be used as part of a data request.
See Also
- SimConnect API Reference
- SIMCONNECT_DATATYPE
- SIMCONNECT_DATA_INITPOSITION
- SimConnect Structures and Enumerations
SIMCONNECT_DATA_WAYPOINT
The SIMCONNECT_DATA_WAYPOINT structure is used to hold all the necessary information on a waypoint.
Syntax
double Latitude;
double Longitude;
double Altitude;
unsigned long Flags;
double ktsSpeed;
double percentThrottle;
};
Members
Latitude
The latitude of the waypoint in degrees.
Longitude
The longitude of the waypoint in degrees.
Altitude
The altitude of the waypoint in feet.
Flags
Specifies the flags set for this waypoint, see
SIMCONNECT_WAYPOINT_FLAGS. These flags can be OR'ed together, for example:
Specifies the required speed in knots. If a specific speed is required, then the SIMCONNECT_WAYPOINT_SPEED_REQUESTED flag must be set to True.
percentThrottle
Specifies the required throttle as a percentage. If a specific throttle percentage is required, then the SIMCONNECT_THROTTLE_REQUESTED flag must be set to True.
Working Sample
Primary sample |
AI Objects and Waypoints
Managed AI Waypoints |
Remarks
The SimConnect_AddToDataDefinition call can be used to add a SIMCONNECT_DATA_WAYPOINT structure to a data definition. A list of waypoints is sent to an AI object using the SimConnect_SetDataOnSimObject function. There is no limit to the number of waypoints that can be sent to an object. If just one waypoint is set, the SIMCONNECT_WAYPOINT_WRAP_TO_FIRST flag should not be used.
If a speed is requested at a waypoint, the slower that speed is the closer the object will approach the exact point of the waypoint, requests for high speeds can result in the AI system turning the object some way off of the waypoint. The pitch, bank and heading of objects controlled by the waypoint system are determined by the AI pilot, and cannot be set from a client.
Because of the curvature of the Earth it is recommended that waypoints for AI controlled objects are not more than five miles apart, as if the object is flying it will fly straight from one waypoint to the next -- and hence loose altitude if the waypoints are some distance apart.
This structure can only be used to set data, it cannot be used as part of a data request.
See Also
SIMCONNECT_DATA_XYZ
The SIMCONNECT_DATA_XYZ structure is used to hold a 3D co-ordinate.
Syntax
double x;
double y;
double z;
};
Members
x
The position along the x axis.
y
The position along the y axis.
z
The position along the z axis.
See Also
SIMCONNECT_DATA_PBH
The SIMCONNECT_DATA_PBH structure is used to hold the pitch, bank, and heading.
Syntax
double Pitch;
double Bank;
double Heading;
};
Members
Pitch
The rotation for the pitch.
Bank
The rotation for the bank.
Heading
The rotation for the heading.
See Also
SIMCONNECT_DATA_OBSERVER
The SIMCONNECT_DATA_OBSERVER structure is used to hold all the necessary information on an observer.
Syntax
SIMCONNECT_DATA_LATLONALT Position;
SIMCONNECT_DATA_PBH Rotation;
DWORD Regime;
BOOL RotateOnTarget;
BOOL FocusFixed;
float FocalLength;
float FieldOfViewH;
float FieldOfViewV;
float LinearStep;
float AngularStep;
};
Members
Position
The world location (latitude/longitude/altitude) of the observer.
Rotation
The rotation (pitch/bank/heading) of the observer in degrees.
Regime
The restrictions of the observer. Tellurian (earth-based) is 0, Terrestrial
(land-based) is 1, and Ghost (unimpeded) is 2.
RotateOnTarget
Specifies if the observer should rotate on target. Observer will rotate
about its own origin if false and rotate about its focal point (target) if
true.
FocusFixed
Specifies the observer focal point. If false, the observer automatically
shifts focal point to the world (terrain) as the observer is manipulated. If true,
the observer locks the focus to a fixed distance relative to the observer's position.
FocalLength
Specifies the focal length in meters.
FieldOfViewH
Specifies the horizontal field of view in degrees.
FieldOfViewV
Specifies the vertical field of view in degrees.
LinearStep
Specifies the linear step in meters.
AngularStep
Specifies the angular step in degrees.
Working Sample
Primary sample | Managed Observer Control |
Remarks
None.
See Also
SIMCONNECT_DATA_OBJECT_DAMAGED_BY_WEAPON
The SIMCONNECT_DATA_OBJECT_DAMAGED_BY_WEAPON structure is used to hold data when an object is damaged by a weapon.
Syntax
DWORD dwWeaponID;
DWORD dwAttackerID;
DWORD dwDamagedObjectID;
};
Members
dwWeaponIDDouble word containing the object ID of the weapon.
dwAttackerID
Double word containing the object ID of the object that fired the weapon.
dwDamagedObjectID
Double word containing the object ID of the damaged entity.
Remarks
None.
See Also
- SimConnect API Reference
- SIMCONNECT_DATATYPE
- SimConnect Structures and Enumerations
- SIMCONNECT_RECV_EVENT_WEAPON
- SIMCONNECT_RECV_EVENT_COUNTERMEASURE
- SIMCONNECT_RECV_EVENT_OBJECT_DAMAGED_BY_WEAPON
SIMCONNECT_DATA_VIDEO_STREAM_INFO
The SIMCONNECT_DATA_VIDEO_STREAM_INFO structure is used to hold data for a video stream.
Syntax
char szSourceAddress[48];
char szDestinationAddress[48];
UINT uPort;
UINT uWidth;
UINT uHeight;
UINT uFramerate;
UINT uBitRate;
UINT uFormat;
};
Members
szSourceAddressIP Address of the video stream source. IPv4 address in standard dotted-decimal notation.
szDestinationAddress
IP Address of the video stream destination. IPv4 address in standard dotted-decimal notation.
uPort
Port of the video stream destination. This must be an even number. Source port will be (uPort -1).
uWidth
Width of the video in pixels.
uHeight
Height of the video in pixels.
uFramerate
Target framerate to use for video encoding. Standard video framerates such as 20, 24, or 30 are reccomended. are reccomended.
uBitRate
Target bitrate (bps) to use for video encoding. Reccomended range is 500,000-20,000,000.
uFormat
Format to use for video encoding. Formats: 0 - H.264.
Remarks
Every rendered frame in Prepar3D will be encoded for streaming. To keep frame quality stable, the frame length used for each encoded frame will be ((1 second)/uFramerate). For this reason uFramerate and uBitRate directly effect the quality of each frame, but may not reflect the final streaming bitrate if Prepar3D's framerate differs from the target framerate used for encoding.
Here are some bitrate ranges used by commercial web streaming services:
480p/30fps: 1,000,000-1,7000,000 bps
720p/30fps: 2,000,000-3,6000,000 bps
1080p/30fps: 3,500,000-5,000,000 bps.
uFormat is currently ignored because only one format is supported. More formats may be added in the future, so this value should be set to 0.
If the size of the Prepar3D window being streamed does not match uWidth and uHeight, the rendered image will be upscaled or downscaled to the video stream resolution.
There are several steaming settings in the graphics section of the Prepar3D.cfg:
- VIDEO_CAPTURE_WIDTH (default is 480): Default width value used if uWidth provided is 0
- VIDEO_CAPTURE_HEIGHT (default is 360): Default width value used if uHeight provided is 0
- VIDEO_CAPTURE_FPS (default is 30): Default framerate value used if uFramerate provided is 0
- VIDEO_CAPTURE_BIT_RATE (default is 800000): Default bitrate value used if uBitRate provided is 0
- VIDEO_CAPTURE_TTL (default is 255): Time To Live value used for all stream connections
- VIDEO_CAPTURE_IS_THREADED (default is True): Perform video encoding on a background thread.
- VIDEO_CAPTURE_INFO_SEND_RATE (default is 20): Number of frames between repeated sending of stream info. This allows clients to join midstream.
- VIDEO_CAPTURE_MAX_FRAME_SIZE (default is 5000000): Max buffer size in bytes for a streamed frame
Here is an example session description protocol (sdp) file for viewing a Prepar3D stream sent to localhost:
o=-0 0 IN IP4 127.0.0.1
s=No Name
t=0 0
m=video 1234 RTP/AVP 96
c=IN IP4 127.0.0.1
a=rtpmap:96 H264/90000
a=fmtp:96 packetization - mode = 1
See Also
- SimConnect_BeginVideoStream
- SimConnect_EndVideoStream
- SimConnect API Reference
- SIMCONNECT_DATATYPE
- SimConnect Structures and Enumerations
SIMCONNECT_TEXT_RESULT
The SIMCONNECT_TEXT_RESULT enumeration type is used to specify which event has occurred as a result of a call to SimConnect_Text.
Syntax
SIMCONNECT_TEXT_RESULT_MENU_SELECT_1,
SIMCONNECT_TEXT_RESULT_MENU_SELECT_2,
SIMCONNECT_TEXT_RESULT_MENU_SELECT_3,
SIMCONNECT_TEXT_RESULT_MENU_SELECT_4,
SIMCONNECT_TEXT_RESULT_MENU_SELECT_5,
SIMCONNECT_TEXT_RESULT_MENU_SELECT_6,
SIMCONNECT_TEXT_RESULT_MENU_SELECT_7,
SIMCONNECT_TEXT_RESULT_MENU_SELECT_8,
SIMCONNECT_TEXT_RESULT_MENU_SELECT_9,
SIMCONNECT_TEXT_RESULT_MENU_SELECT_10,
SIMCONNECT_TEXT_RESULT_DISPLAYED =0x00010000,
SIMCONNECT_TEXT_RESULT_QUEUED,
SIMCONNECT_TEXT_RESULT_REMOVED,
SIMCONNECT_TEXT_RESULT_REPLACED,
SIMCONNECT_TEXT_RESULT_TIMEOUT
};
Members
SIMCONNECT_TEXT_RESULT_MENU_SELECT_1 to SIMCONNECT_TEXT_RESULT_MENU_SELECT_10
Specifies that the user has selected the menu item.
SIMCONNECT_TEXT_RESULT_DISPLAYED
Specifies that the menu or text identified by the EventID is now on display.
SIMCONNECT_TEXT_RESULT_QUEUED
Specifies that the menu or text identified by the EventID is waiting in a queue.
SIMCONNECT_TEXT_RESULT_REMOVED
Specifies that the menu or text identified by the EventID has been removed from the queue.
SIMCONNECT_TEXT_RESULT_REPLACED
Specifies that the menu or text identified by the EventID has been replaced in the queue.
SIMCONNECT_TEXT_RESULT_TIMEOUT
Specifies that the menu or text identified by the EventID has timed-out and is no longer on display.
Working Sample
Primary sample | Text Menu |
Remarks
See the remarks for SimConnect_Text.
See Also
SIMCONNECT_TEXT_TYPE
The SIMCONNECT_TEXT_TYPE enumeration type is used to specify which type of text is to be displayed by the SimConnect_Text function
Syntax
SIMCONNECT_TEXT_TYPE_SCROLL_BLACK,
SIMCONNECT_TEXT_TYPE_SCROLL_WHITE,
SIMCONNECT_TEXT_TYPE_SCROLL_RED,
SIMCONNECT_TEXT_TYPE_SCROLL_GREEN,
SIMCONNECT_TEXT_TYPE_SCROLL_BLUE,
SIMCONNECT_TEXT_TYPE_SCROLL_YELLOW,
SIMCONNECT_TEXT_TYPE_SCROLL_MAGENTA,
SIMCONNECT_TEXT_TYPE_SCROLL_CYAN,
SIMCONNECT_TEXT_TYPE_PRINT_BLACK = 0x0100,
SIMCONNECT_TEXT_TYPE_PRINT_WHITE,
SIMCONNECT_TEXT_TYPE_PRINT_RED,
SIMCONNECT_TEXT_TYPE_PRINT_GREEN,
SIMCONNECT_TEXT_TYPE_PRINT_BLUE,
SIMCONNECT_TEXT_TYPE_PRINT_YELLOW,
SIMCONNECT_TEXT_TYPE_PRINT_MAGENTA,
SIMCONNECT_TEXT_TYPE_PRINT_CYAN,
SIMCONNECT_TEXT_TYPE_MENU = 0x0200
SIMCONNECT_TEXT_TYPE_MESSAGE_WINDOW = 0x0300
};
Members
SIMCONNECT_TEXT_TYPE_SCROLL_BLACK to SIMCONNECT_TEXT_TYPE_SCROLL_CYAN
Specifies scrolling text in the named color.
SIMCONNECT_TEXT_TYPE_PRINT_BLACK to SIMCONNECT_TEXT_TYPE_PRINT_CYAN
Specifies static text in the named color.
SIMCONNECT_TEXT_TYPE_MENU
Specifies that the text is for a menu.
SIMCONNECT_TEXT_TYPE_MESSAGE_WINDOW
Specifies that the text is for a message window.
Working Sample
Primary sample | Text Menu |
Remarks
See the remarks for SimConnect_Text.
See Also
SIMCONNECT_WAYPOINT_FLAGS
The SIMCONNECT_WAYPOINT_FLAGS enumeration type is used with the SIMCONNECT_DATA_WAYPOINT structure to define waypoints.
Syntax
SIMCONNECT_WAYPOINT_SPEED_REQUESTED = 0x04,
SIMCONNECT_WAYPOINT_THROTTLE_REQUESTED = 0x08,
SIMCONNECT_WAYPOINT_COMPUTE_VERTICAL_SPEED = 0x10,
SIMCONNECT_WAYPOINT_ALTITUDE_IS_AGL = 0x20,
SIMCONNECT_WAYPOINT_ON_GROUND = 0x00100000,
SIMCONNECT_WAYPOINT_REVERSE = 0x00200000,
SIMCONNECT_WAYPOINT_WRAP_TO_FIRST = 0x00400000,
};
Members
SIMCONNECT_WAYPOINT_SPEED_REQUESTED
Specifies requested speed is valid.
SIMCONNECT_WAYPOINT_THROTTLE_REQUESTED
Specifies requested throttle percentage is valid.
SIMCONNECT_WAYPOINT_COMPUTE_VERTICAL_SPEED
Specifies that the vertical should be calculated to reach the required speed when crossing the waypoint.
SIMCONNECT_WAYPOINT_ALTITUDE_IS_AGL
Specifies the altitude specified is AGL (above ground level).
SIMCONNECT_WAYPOINT_ON_GROUND
Specifies the waypoint should be on the ground. Make sure this flag is set if the aircraft is to taxi to this point.
SIMCONNECT_WAYPOINT_REVERSE
Specifies that the aircraft should back up to this waypoint. This is only valid on the first waypoint.
SIMCONNECT_WAYPOINT_WRAP_TO_FIRST
Specifies that the next waypoint is the first waypoint. This is only valid on the last waypoint.
Working Sample
Primary sample |
AI Objects and Waypoints
Managed AI Waypoints |
Remarks
To set multiple waypoint flags simply OR them together. See the remarks for the SIMCONNECT_DATA_WAYPOINT structure.
See Also
SIMCONNECT_WEATHER_MODE
The SIMCONNECT_WEATHER_MODE enumeration type is used to return the current weather mode, after a call using the SIMCONNECT_RECV_ID_EVENT_WEATHER_MODE setting
Syntax
SIMCONNECT_WEATHER_MODE_THEME,
SIMCONNECT_WEATHER_MODE_RWW, // deprecated
SIMCONNECT_WEATHER_MODE_CUSTOM,
SIMCONNECT_WEATHER_MODE_GLOBAL
};
Members
SIMCONNECT_WEATHER_MODE_THEME
Specifies that the weather has been set to a theme.
SIMCONNECT_WEATHER_MODE_RWW
Specifies that real-world weather has been set. This has been deprecated.
SIMCONNECT_WEATHER_MODE_CUSTOM
Specifies that custom weather has been set.
SIMCONNECT_WEATHER_MODE_GLOBAL
Specifies that the global weather mode has been set.
See Also
SIMCONNECT_CAMERA_SENSOR_MODE
The SIMCONNECT_CAMERA_SENSOR_MODE enumeration type is used with the SimConnect_SetCameraSensorMode and SimConnect_SetMainCameraSensorMode call to specify a camera's sensor mode.
Syntax
SIMCONNECT_CAMERA_SENSOR_NONE,
SIMCONNECT_CAMERA_SENSOR_IR,
SIMCONNECT_CAMERA_SENSOR_IR_BLACK_HOT,
SIMCONNECT_CAMERA_SENSOR_GDATA,
};
Members
SIMCONNECT_CAMERA_SENSOR_NONE
No sensor mode.
SIMCONNECT_CAMERA_SENSOR_IR
IR sensor mode.
See Also
SIMCONNECT_CAMERA_TYPE
The SIMCONNECT_CAMERA_TYPE enumeration type is used with the SimConnect_CreateCameraDefinition call to create a new camera definition.
Syntax
SIMCONNECT_CAMERA_TYPE_OBJECT_PANEL,
SIMCONNECT_CAMERA_TYPE_OBJECT_VIRTUAL,
SIMCONNECT_CAMERA_TYPE_OBJECT_CENTER,
SIMCONNECT_CAMERA_TYPE_OBJECT_PILOT,
SIMCONNECT_CAMERA_TYPE_TOWER,
SIMCONNECT_CAMERA_TYPE_LATLONALT_ORTHOGONAL,
SIMCONNECT_CAMERA_TYPE_OBJECT_AI_VIRTUAL
};
Members
SIMCONNECT_CAMERA_TYPE_OBJECT_PANEL
Specifies the user's cockpit as the camera's origin.
SIMCONNECT_CAMERA_TYPE_OBJECT_VIRTUAL
Specifies the user's virtual cockpit as the camera's origin.
SIMCONNECT_CAMERA_TYPE_OBJECT_CENTER
Specifies the center of the user's vehicle as the camera's origin.
SIMCONNECT_CAMERA_TYPE_OBJECT_PILOT
Specifies the user's pilot as the camera's origin.
SIMCONNECT_CAMERA_TYPE_TOWER
Specifies a control tower as the camera's origin.
SIMCONNECT_CAMERA_TYPE_LATLONALT_ORTHOGONAL
Specifies the center of the user's object as the camera's origin. Viewed from a orthogonal/top-down position.
SIMCONNECT_CAMERA_TYPE_OBJECT_AI_VIRTUAL
Specifies AI object's virtual cockpit as the camera's origin.
See Also
SIMCONNECT_CAMERA_COMMAND
The SIMCONNECT_CAMERA_COMMAND enumeration type is used with the SimConnect_SendCameraCommand call to create move a camera.
Syntax
SIMCONNECT_CAMERA_MOVE_LEFT,
SIMCONNECT_CAMERA_MOVE_RIGHT,
SIMCONNECT_CAMERA_MOVE_UP,
SIMCONNECT_CAMERA_MOVE_DOWN,
SIMCONNECT_CAMERA_MOVE_FORWARD,
SIMCONNECT_CAMERA_MOVE_BACK
SIMCONNECT_CAMERA_PITCH_UP
SIMCONNECT_CAMERA_PITCH_DOWN
SIMCONNECT_CAMERA_YAW_LEFT
SIMCONNECT_CAMERA_YAW_RIGHT
SIMCONNECT_CAMERA_ROLL_LEFT
SIMCONNECT_CAMERA_ROLL_RIGHT
SIMCONNECT_CAMERA_ZOOM_IN
SIMCONNECT_CAMERA_ZOOM_OUT
SIMCONNECT_CAMERA_RESET_ROTATION
};
Members
SIMCONNECT_CAMERA_MOVE_LEFT
Specifies the user's cockpit as the camera's origin.
SIMCONNECT_CAMERA_MOVE_RIGHT
Specifies the user's virtual cockpit as the camera's origin.
SIMCONNECT_CAMERA_MOVE_UP
Simulate a user input to move the camera up.
SIMCONNECT_CAMERA_MOVE_DOWN
Simulate a user input to move the camera down.
SIMCONNECT_CAMERA_MOVE_FORWARD
Simulate a user input to move the camera forward.
SIMCONNECT_CAMERA_MOVE_BACK
Simulate a user input to move the camera back.
SIMCONNECT_CAMERA_PITCH_UP
Simulate a user input to pitch the camera up.
SIMCONNECT_CAMERA_PITCH_DOWN
Simulate a user input to pitch the camera down.
SIMCONNECT_CAMERA_YAW_LEFT
Simulate a user input to rotate the camera left about the vertical axis.
SIMCONNECT_CAMERA_YAW_RIGHT
Simulate a user input to rotate the camera right about the vertical axis.
SIMCONNECT_CAMERA_ROLL_LEFT
Simulate a user input to rotate the camera left about the longitudinal axis.
SIMCONNECT_CAMERA_ROLL_RIGHT
Simulate a user input to rotate the camera right about the longitudinal axis.
SIMCONNECT_CAMERA_ZOOM_IN
Simulate a user input to zoom the camera in.
SIMCONNECT_CAMERA_ZOOM_OUT
Simulate a user input to zoom the camera out.
SIMCONNECT_CAMERA_RESET_ROTATION
Simulate a user input to rest the camera rotation.
See Also
Programming SimConnect Clients using Managed Code
There is a managed wrapper for SimConnect that enables .NET language programmers to write SimConnect clients. This section describes how to set up a managed client project, and the key differences to look out for when programming to the wrapper. There are also a number of managed code samples included with the SDK.
The following sections use C# as the primary example language. If you intend writing a client in VB.NET read this section in conjunction with the VB.NET Managed Data Request sample.
Setup for .NET
- Ensure that .NET Framework Version 4.5.1 is installed. If it is not, uninstall the Prepar3D SDK, install the .NET Framework from the following link here, then re-install the SDK.
- Create a new project using Visual Studio 2013, typically this would be a C# Windows Application, or a VB.NET Windows application.
- Add a new reference to LockheedMartin.Prepar3D.SimConnect.dll in your project. This file can be found in the SDK\Utilities\SimConnect SDK\lib\managed folder.
- Add the following two lines to the projects' using statements (in C#, note
the VB.NET equivalent to using is imports):
using LockheedMartin.Prepar3D.SimConnect;
using System.Runtime.InteropServices;
- Write the application using the functions in the SimConnect library, taking into account the following notes.
Notes on .NET client programming
- Previously, the managed SimConnect assembly was installed in the GAC (global assembly cache) during the installation of the SimConnect SDK, so it did not have to be manually placed anywhere for your application to run. However, you did need to reference a copy of this dll in Visual Studio so that it could resolve symbols at compile time. As Visual Studio does not support referencing an assembly stored in the GAC, a copy of the SimConnect.dll was shipped solely for this purpose. It is no longer handled this way in Prepar3D.
- The native function calls SimConnect_Open
and SimConnect_Close have been replaced by
the SimConnect constructor, and Dispose method respectively. This
means that there is no handle required for the function calls, so for the most part
the managed calls use the same parameters as the native calls, except without the
SimConnect handle. The code to open and close a SimConnect client is:
C#
// Open
// Declare a SimConnect object
SimConnect simconnect = null;
// User-defined win32 event
const int WM_USER_SIMCONNECT = 0x0402;
try
{
simconnect = new SimConnect("Managed Data Request", this.Handle, WM_USER_SIMCONNECT, null, 0);
}
catch (COMException ex)
{
// A connection to the SimConnect server could not be established
}
// Close
if (simconnect != null)
{
simconnect.Dispose();
simconnect = null;
}
VB.NET
Rem Open
Try
simconnect = New SimConnect(" VB Managed Data Request", Me.Handle, WM_USER_SIMCONNECT, Nothing, 0)
Catch ex As Exception
Rem Failed to connect
End Try
Rem Close
If simconnect IsNot Nothing Then
simconnect.Dispose()
simconnect = Nothing
End If
- What would have been a failed HRESULT returned in the native API translates to a COMException.
- The use of raw memory pointers is not permitted in the managed API. You must define your structs and attribute them properly so that the system marshaller can handle them. See the code in the Managed Data Request sample for C#, and VB Managed Data Request sample for VB.NET.
- When the client receives either a SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE or a SIMCONNECT_RECV_SIMOBJECT_DATA structure, the dwData[0] member will contain your struct as System.Object. This should be cast to the proper type.
- Partial data return (SIMCONNECT_DATA_REQUEST_FLAG_TAGGED) is unsupported. For a description of this flag see the SimConnect_AddToDataDefinition function.
- The top level ReceiveDispatch switch case statement is not necessary. The
client should register a handler for the appropriate OnRecvXXX event, and
call ReceiveMessage when it is notified that messages are waiting in the
queue. For Windows applications use a win32 handle (a Control.Handle) to SimConnect
to receive notifications when a message arrives. The code for this is as follows:
C# Winforms
protected override void DefWndProc(ref Message m)
{
if (m.Msg == WM_USER_SIMCONNECT)
{
if (simconnect != null)
{
simconnect.ReceiveMessage();
}
}
else
{
base.DefWndProc(ref m);
}
}
C# WPF
IntPtr handle;
HwndSource handleSource;
// Register WPF window
YourWPFWindow()
{
handle = new WindowInteropHelper(this).Handle; // Get handle of main WPF Window
handleSource = HwndSource.FromHwnd(handle); // Get source of handle in order to add event handlers to it
handleSource.AddHook(HandleSimConnectEvents);
}
~YourWPFWindow()
{
if (handleSource != null)
{
handleSource.RemoveHook(HandleSimConnectEvents);
}
}
private IntPtr HandleSimConnectEvents(IntPtr hWnd, int message, IntPtr wParam, IntPtr lParam, ref bool isHandled)
{
isHandled = false;
switch (message)
{
case WM_USER_SIMCONNECT:
{
if (simConnect != null)
{
simConnect.ReceiveMessage();
isHandled = true;
}
}
break;
default:
break;
}
return IntPtr.Zero;
}
VB.NET
Protected Overrides Sub DefWndProc(ByRef m As Message)
If m.Msg = WM_USER_SIMCONNECT Then
If simconnect IsNot Nothing Then
simconnect.ReceiveMessage()
End If
Else
MyBase.DefWndProc(m)
End If
End Sub
- Constants in the native simconnect.h are declared as static members of the SimConnect class. For example: SIMCONNECT_OBJECT_ID_USER becomes SimConnect.SIMCONNECT_OBJECT_ID_USER
- Enums in managed code are scoped. The names of the enum members have been changed, for example, SIMCONNECT_RECV_ID_QUIT in native code is SIMCONNECT_RECV_ID.QUIT in C#, or LockheedMartin.Prepar3D.SimConnect.SIMCONNECT_RECV_ID.QUIT in VB.NET. Note that in VB.NET the full reference is necessary to locate a structure or enumeration.
- Structs are mostly unchanged, with the exception that a char array is represented
as a System.String. However, they do need to be registered with the managed
wrapper with a call to RegisterDataDefineStruct. If a string is too long
during the data marshaling, it will get truncated safely. Some specific information
must be provided with each structure, as shown in bold in the example below (also
refer to the Managed Data Request or
VB Managed Data Request samples):
C#
[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Ansi, Pack = 1)]
struct Struct1
{
// this is how you declare a fixed size string
[MarshalAs(UnmanagedType.ByValTStr, SizeConst = 256)]
public String title;
public double latitude;
public double longitude;
public double altitude;
};
// define the data structure
// Note that the DATATYPE.STRING256 matches the SizeConst 256 in the MarshalAs statement above
//
simconnect.AddToDataDefinition((uint)DEFINITIONS.Struct1, "title", null, SIMCONNECT_DATATYPE.STRING256, 0, SimConnect.SIMCONNECT_UNUSED);
simconnect.AddToDataDefinition((uint)DEFINITIONS.Struct1, "Plane Latitude", "degrees", SIMCONNECT_DATATYPE.FLOAT64, 0, SimConnect.SIMCONNECT_UNUSED);
simconnect.AddToDataDefinition((uint)DEFINITIONS.Struct1, "Plane Longitude", "degrees", SIMCONNECT_DATATYPE.FLOAT64, 0, SimConnect.SIMCONNECT_UNUSED);
simconnect.AddToDataDefinition((uint)DEFINITIONS.Struct1, "Plane Altitude", "feet", SIMCONNECT_DATATYPE.FLOAT64, 0, SimConnect.SIMCONNECT_UNUSED);
//
// IMPORTANT: register it with the simconnect managed wrapper marshaller
// if you skip this step, you will only receive a uint in the .dwData field.
//
simconnect.RegisterDataDefineStruct<Struct1>((uint)DEFINITIONS.Struct1);
VB.NET
<StructLayout(LayoutKind.Sequential, CharSet:=CharSet.Ansi, Pack:=1)> _
Structure Struct1
Rem This is how you declare a fixed size string
<MarshalAs(UnmanagedType.ByValTStr, SizeConst:=256)> _
Public title As String
Public latitude As Double
Public longitude As Double
Public altitude As Double
End Structure
Rem define a data structure, note the last parameter, datumID must be different for each item
simconnect.AddToDataDefinition(StructDefinitions.Struct1, "title", "", LockheedMartin.Prepar3D.SimConnect.SIMCONNECT_DATATYPE.STRING256, 0, 0)
simconnect.AddToDataDefinition(StructDefinitions.Struct1, "Plane Latitude", "degrees", LockheedMartin.Prepar3D.SimConnect.SIMCONNECT_DATATYPE.FLOAT64, 0, 1)
simconnect.AddToDataDefinition(StructDefinitions.Struct1, "Plane Longitude", "degrees", LockheedMartin.Prepar3D.SimConnect.SIMCONNECT_DATATYPE.FLOAT64, 0, 2)
simconnect.AddToDataDefinition(StructDefinitions.Struct1, "Plane Altitude", "feet", LockheedMartin.Prepar3D.SimConnect.SIMCONNECT_DATATYPE.FLOAT64, 0, 3)
Rem IMPORTANT: register it with the simconnect managed wrapper marshaller
Rem if you skip this step, you will only receive an int in the .dwData field.
simconnect.RegisterDataDefineStruct(Of Struct1)(StructDefinitions.Struct1)
- Variable length strings are not supported in the managed layer.
- Optional parameters are not supported in the managed layer.
- To send data in an array, copy the array to a polymorphic object array. For example,
to apply a waypoint list to an AI aircraft, go through the following steps:
C#
// Note that the client code should already have declared a
// data definition, DEFINITIONS.1, and
// calledSimConnect_RequestDataOnSimObjectType to return an AI aircraft ID.
// Step 1: Add a the waypoint list to the data definition
simconnect.AddToDataDefinition(DEFINITIONS.1,"AI WAYPOINT LIST", "number", SIMCONNECT_DATATYPE.WAYPOINT, 0.0f, SimConnect.SIMCONNECT_UNUSED);
// Step 2: Declare an array of the appropriate size
SIMCONNECT_DATA_WAYPOINT[] waypoints = new SIMCONNECT_DATA_WAYPOINT[2];
// Step 3: Populate the array with all the required data
waypoints[0].Flags = (uint)SIMCONNECT_WAYPOINT_FLAGS.SPEED_REQUESTED;
waypoints[0].ktsSpeed = 100;
waypoints[0].Latitude = 10;
waypoints[0].Longitude = 20;
waypoints[0].Altitude = 1000;
waypoints[1].Flags = (uint)SIMCONNECT_WAYPOINT_FLAGS.SPEED_REQUESTED;
waypoints[1].ktsSpeed = 150;
waypoints[1].Latitude = 11;
waypoints[1].Longitude = 21;
waypoints[1].Altitude = 2000;
// Step 4: The managed wrapper marshaling code expects a polymorphic array
Object[] objv = new Object[ waypoints.Length ];
waypoints.CopyTo(objv, 0);
// Step 5: Now make the call to apply the waypoint structure to the AI aircraft
simconnect.SetDataOnSimObject(DEFINITIONS.1, AIAircraftID, SIMCONNECT_DATA_SET_FLAG.DEFAULT, objv);
VB.NET
REM Note that the client code should already have declared a
REM data definition, StructDefinitions.DEFINITIONS.1, and
REM called simconnect.RequestDataOnSimObjectType to return an AI aircraft ID.
REM Step 1: Add a the waypoint list to the data definition
simconnect.AddToDataDefinition(StructDefinitions.DEFINITION1, "AI WAYPOINT LIST", "number", LockheedMartin.Prepar3D.SimConnect.SIMCONNECT_DATATYPE.WAYPOINT, 0.0F, LockheedMartin.Prepar3D.SimConnect.SimConnect.SIMCONNECT_UNUSED)
REM Step 2: Declare an array of the appropriate size
Dim waypoints(2) As LockheedMartin.Prepar3D.SimConnect.SIMCONNECT_DATA_WAYPOINT
REM Step 3: Populate the array with all the required data
waypoints(0).Flags = LockheedMartin.Prepar3D.SimConnect.SIMCONNECT_WAYPOINT_FLAGS.SPEED_REQUESTED
waypoints(0).ktsSpeed = 100
waypoints(0).Latitude = 10
waypoints(0).Longitude = 20
waypoints(0).Altitude = 1000
waypoints(1).Flags = LockheedMartin.Prepar3D.SimConnect.SIMCONNECT_WAYPOINT_FLAGS.SPEED_REQUESTED
waypoints(1).ktsSpeed = 100
waypoints(0).Latitude = 11
waypoints(0).Longitude = 21
waypoints(0).Altitude = 1000
REM Step 4: The managed wrapper marshaling code expects a polymorphic array
Dim objv(waypoints.Length) As Object
waypoints.CopyTo(objv, 0)
REM Step 5: Now make the call to apply the waypoint structure to the AI aircraft
simconnect.SetDataOnSimObject(StructDefinitions.DEFINITION1, AIAircraftID, LockheedMartin.Prepar3D.SimConnect.SIMCONNECT_DATA_SET_FLAG.DEFAULT, objv)
Working Samples
Click on the Working Sample column to display the source file of a working sample. Many of the samples include the use of functions not listed in the Highlighted Functions column, this list just indicates those functions the sample is designed to specifically demonstrate.
Unmanaged code samples
The following samples are written in C++.
C++ sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
AI Objects and Waypoints | Creates a number of AI objects, including an aircraft, a truck, a hot air balloon and a whale. A key press sends waypoints to the aircraft and truck. |
SimConnect_SetDataOnSimObject SimConnect_AICreateSimulatedObject SimConnect_AICreateNonATCAircraft |
SIMCONNECT_DATA_INITPOSITION SIMCONNECT_DATA_WAYPOINT SIMCONNECT_RECV_ASSIGNED_OBJECT_ID |
C++ sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
AI Traffic |
Creates a number of aircraft at Yakima Air Term/Mcallister airport and provides
them with a flight plan to Spokane Intl. Sets up two parked aircraft, and a key
press initiates them with the same flight plan.
Make sure to move the flight plan included with this sample (IFR Yakima Air Term Mcallister to Spokane Intl.pln ) to the default Prepar3D v3 Files directory before running this sample. |
SimConnect_AISetAircraftFlightPlan SimConnect_AICreateEnrouteATCAircraft SimConnect_AICreateParkedATCAircraft |
SIMCONNECT_RECV_EVENT_OBJECT_ADDREMOVE SIMCONNECT_RECV_ASSIGNED_OBJECT_ID |
C++ sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
Camera System | Modifies camera and containing view/window. |
SimConnect_CreateCameraDefinition SimConnect_CreateCameraInstance SimConnect_OpenView SimConnect_UndockView SimConnect_DockView SimConnect_SetCameraWindowPosition SimConnect_SetCameraWindowSize |
C++ sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
Change Vehicle | Changes the Vehicle that is being used in Prepar3D. | SimConnect_ChangeVehicle |
C++ sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
Client Event | Request notifications of a simulation event, the applying of the user aircraft's brakes in this case. |
SimConnect_MapClientEventToSimEvent SimConnect_AddClientEventToNotificationGroup SimConnect_SetNotificationGroupPriority SimConnect_CallDispatch |
SIMCONNECT_RECV_EVENT |
C++ sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
Cockpit Camera | Banks the user's view camera left and right in response to certain key presses. |
SimConnect_CameraSetRelative6DOF SimConnect_MapInputEventToClientEvent SimConnect_AddClientEventToNotificationGroup SimConnect_MapClientEventToSimEvent |
SIMCONNECT_RECV_EXCEPTION |
C++ sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
DialogBoxMode | Sets Dialog mode, displays a message box, then resets Dialog mode. |
SimConnect_SetSystemState SimConnect_RequestSystemState |
SIMCONNECT_RECV_SYSTEM_STATE |
C++ sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
ExternalSim | Provides a simple example of how to write a SimConnect External Sim. |
SimConnect_RegisterExternalSim SimConnect_UnregisterExternalSim SimConnect_SynchronousUnblock SimConnect_MapClientEventToSimEvent SimConnect_AddToDataDefinition |
SIMCONNECT_RECV_EXTERNAL_SIM_CREATE SIMCONNECT_RECV_EXTERNAL_SIM_DESTROY SIMCONNECT_RECV_EXTERNAL_SIM_SIMULATE SIMCONNECT_RECV_EXTERNAL_SIM_LOCATION_CHANGED SIMCONNECT_RECV_EXTERNAL_SIM_EVENT |
Sample External Sim Container | Sample SimObject container using the Sample External Sim above. Provides a complete SimObject container that can be dropped into the SimObjects\Misc\ folder to test the Sample External Sim. |
C++ sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
FacilitiesData | Uses text menus to select the options for retrieving facilities data, such as airports, VORs, NDBs etc. |
SimConnect_RequestFacilitiesList SimConnect_SubscribeToFacilities SimConnect_UnsubscribeToFacilities SimConnect_Text |
SIMCONNECT_RECV_FACILITIES_LIST SIMCONNECT_TEXT_RESULT SIMCONNECT_TEXT_TYPE |
C++ sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
Input Event | Applies the user aircraft brakes by pressing the Ctrl-Shift-U key combination. |
SimConnect_MapInputEventToClientEvent SimConnect_SetInputGroupState |
SIMCONNECT_RECV_EVENT |
C++ sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
Joystick Input | Provides the input data from the joystick X and Y axis position, Z axis rotation, hat switch and slider. A key press selects each input option in turn. |
SimConnect_SetInputGroupState SimConnect_MapClientEventToSimEvent SimConnect_AddClientEventToNotificationGroup SimConnect_MapInputEventToClientEvent |
SIMCONNECT_RECV_EVENT |
C++ sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
Menu Items | Adds and removes a menu item. |
SimConnect_MenuAddItem SimConnect_MenuDeleteItem SimConnect_RemoveClientEvent SimConnect_AddClientEventToNotificationGroup |
SIMCONNECT_RECV_EVENT |
C++ sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
Mission Action | Interfaces with a scenario object XML file to provide some additional processing to scenario actions, and when scenarios are completed. |
SimConnect_ExecuteMissionAction SimConnect_CompleteCustomMissionAction SimConnect_SubscribeToSystemEvent WaitForSingleObject |
SIMCONNECT_RECV_CUSTOM_ACTION |
C++ sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
No Callback | Similar to the Client Event sample, but written without a callback function. | SimConnect_GetNextDispatch | SIMCONNECT_RECV_EVENT |
C++ sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
Open and Close | Simply opens and closes a connection with the SimConnect server. |
SimConnect_Open SimConnect_Close |
C++ sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
Pause Monitor | Simply monitors the pause state of Prepar3D. |
C++ sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
Request Data | Requests a small selection of data on the user's aircraft, including latitude, longitude and altitude. |
SimConnect_AddToDataDefinition SimConnect_RequestDataOnSimObjectType |
SIMCONNECT_RECV_EVENT SIMCONNECT_RECV_SIMOBJECT_DATA |
C++ sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
Scenery Complexity and Shadow Flags | Requests either the current scenery complexity setting or the current shadow flag settings based on a user event. |
SimConnect_RequestSceneryComplexity SimConnect_RequestShadowFlags |
SIMCONNECT_RECV_EVENT SIMCONNECT_RECV_SCENERY_COMPLEXITY SIMCONNECT_RECV_SHADOW_FLAGS |
C++ sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
Reserved Key | Requests that one of the three keys specified be reserved for this client. |
SimConnect_MapClientEventToSimEvent SimConnect_RequestReservedKey |
SIMCONNECT_RECV_RESERVED_KEY |
C++ sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
Send Event A | To be used in combination with Send Event B and Send Event C. Transmits custom events to the two other clients. |
SimConnect_TransmitClientEvent SimConnect_MapClientEventToSimEvent SimConnect_AddClientEventToNotificationGroup SimConnect_SetNotificationGroupPriority |
SIMCONNECT_RECV_EVENT |
Send Event B | Receives custom events from Send Event A, at a higher priority than Send Event C. |
SimConnect_MapClientEventToSimEvent SimConnect_AddClientEventToNotificationGroup SimConnect_SetNotificationGroupPriority |
SIMCONNECT_RECV_EVENT |
Send Event C | Receives custom events from Send Event A, at a lower priority than Send Event B. |
SimConnect_MapClientEventToSimEvent SimConnect_AddClientEventToNotificationGroup SimConnect_SetNotificationGroupPriority |
SIMCONNECT_RECV_EVENT |
C++ sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
Set Data | When a certain key is pressed, the position of the user aircraft is changed. |
SimConnect_SetDataOnSimObject SimConnect_AddToDataDefinition SimConnect_MapClientEventToSimEvent SimConnect_MapInputEventToClientEvent SimConnect_SetInputGroupState |
SIMCONNECT_DATA_INITPOSITION |
C++ sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
System Event | Notifies the client when a FlightLoaded event has occurred. | SimConnect_SubscribeToSystemEvent |
SIMCONNECT_RECV_EVENT SIMCONNECT_RECV_EVENT_FILENAME |
C++ sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
Tagged Data | Requests the vertical speed and pitot heat switch settings on the user aircraft, but only when this data changes. |
SimConnect_RequestDataOnSimObject SimConnect_AddToDataDefinition |
SIMCONNECT_RECV_SIMOBJECT_DATA |
C++ sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
TextMenu | Displays and clears a text menu. | SimConnect_Text |
SIMCONNECT_TEXT_RESULT SIMCONNECT_TEXT_TYPE |
C++ sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
Throttle Control | Controls the user aircraft throttle using two specified keys. |
SimConnect_SetDataOnSimObject SimConnect_AddToDataDefinition SimConnect_MapClientEventToSimEvent SimConnect_MapInputEventToClientEvent SimConnect_SetInputGroupState |
SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE |
C++ sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
Tracking Errors | Stores information on each call to the server, so that any error caught by the server can easily be located by the client. Primarily useful for debugging rather than retail builds. |
SimConnect_GetLastSentPacketID SimConnect_MapClientEventToSimEvent SimConnect_AddClientEventToNotificationGroup SimConnect_SetNotificationGroupPriority SimConnect_CallDispatch |
SIMCONNECT_RECV_EVENT SIMCONNECT_RECV_EXCEPTION |
C++ sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
Variable Strings | Extracts three variable length strings from a structure. |
SimConnect_RetrieveString SimConnect_AddToDataDefinition SimConnect_RequestDataOnSimObjectType |
SIMCONNECT_RECV_EVENT SIMCONNECT_RECV_EXCEPTION SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE |
C++ sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
Weather Station | Requests weather data from the nearest weather station to the user aircraft, every 10 seconds. |
SimConnect_WeatherRequestObservationAtNearestStation SimConnect_RequestDataOnSimObject |
SIMCONNECT_RECV_SIMOBJECT_DATA SIMCONNECT_RECV_WEATHER_OBSERVATION |
C++ sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
Windows Event | Uses a Windows Event to improve the waiting time performance of a client. |
CreateEvent SimConnect_Open WaitForSingleObject |
SIMCONNECT_RECV_EVENT |
Managed code samples
The following samples are mostly written in C#, with one in VB.NET, and all use the managed layer for SimConnect.
C# sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
Managed AI Waypoints | Sends an array of waypoints to an Extra 300S, and a fuel truck. |
SimConnect_AICreateSimulatedObject SimConnect_AICreateNonATCAircraft SimConnect_AddToDataDefinition SimConnect_SetDataOnSimObject |
SIMCONNECT_DATA_WAYPOINT SIMCONNECT_RECV_ASSIGNED_OBJECT_ID |
C# sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
Managed Change Vehicle | Changes the Vehicle that is being used in Prepar3D. | SimConnect_ChangeVehicle |
C# sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
Managed Client Event | Requests Pitot heat switch and Flaps events. |
SimConnect_MapClientEventToSimEvent SimConnect_AddClientEventToNotificationGroup SimConnect_SetNotificationGroupPriority OnRecvEvent |
SIMCONNECT_RECV SIMCONNECT_RECV_EVENT SIMCONNECT_RECV_EXCEPTION |
C# sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
Managed Data Request | Click a button to request the title, latitude, longitude and altitude of the user aircraft. |
SimConnect_AddToDataDefinition RegisterDataDefineStruct OnRecvSimobjectDataBytype SimConnect_RequestDataOnSimObjectType |
SIMCONNECT_RECV_SIMOBJECT_DATA
SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE |
C# sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
Managed Facilities Request | Provides buttons to request facility data for Airports, Waypoints, NDBs and VORs. |
SimConnect_SubscribeToFacilities SimConnect_UnsubscribeToFacilities |
SIMCONNECT_RECV_FACILITIES_LIST |
C# sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
Managed Observer Control | Creates an observer, updates an observer and request an observer's data. |
SimConnect_CreateObserver SimConnect_RequestObserverData |
SIMCONNECT_DATA_OBSERVER SIMCONNECT_RECV_OBSERVER_DATA |
C# sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
Managed System Event | Requests 4 second and simulation state system notifications. |
SimConnect_SubscribeToSystemEvent SimConnect_UnsubscribeFromSystemEvent |
SIMCONNECT_RECV SIMCONNECT_RECV_EVENT SIMCONNECT_RECV_EXCEPTION |
C# sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
Managed Weapon Station Selection | Shows an example using Windows Presentation Foundation that utilizes databinding to allow the selection and moniyotinh of multiple hardpoints on a SimObject. |
SimConnect_SetSystemState SimConnect_AddToDataDefinition SimConnect_SetDataOnSimObject SimConnect_SubscribeToSystemEvent WPF Databinding WPF Message Loop |
SIMCONNECT_RECV SIMCONNECT_RECV_EVENT SIMCONNECT_RECV_EXCEPTION |
C# Sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
Managed AI Destroyer | Retrieves all the SimObjects within the maximum radius around the User’s vehicle. Checking a box next to the SimObject’s name then sends SetHealth messages across to the SimObject. This allows the killing and subsequent revival of SimObjects to be tested. | None | None |
VB.NET sample | Description | Highlighted Functions | Highlighted Structures or Enumerations |
---|---|---|---|
Managed VB Data Request | Click a button to request the title, latitude, longitude and altitude of the user aircraft. |
SimConnect_AddToDataDefinition RegisterDataDefineStruct OnRecvSimobjectDataBytype |
SIMCONNECT_RECV_SIMOBJECT_DATA SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE |