Mise à  jour : texte original

SimConnect SDK Reference

Overview

• Add the processing for a new complex gauge, or other instrument, to Flight Simulator.
• Replace Flight Simulator processing of one or more events with new logic.
• Record or monitor a flight.
• Extend the mission system of Flight Simulator.
• Create and set the flight plans for AI (non-user) aircraft.
• Set different weather systems.
• Enable new hardware to work with Flight Simulator.
• Control an additional camera that the user can optionally select to view.

See Also

• Event IDs
• SDK Overview
• Simulation Variables

Table of Contents

• Overview
• Setup
• SimConnect API Reference
• SimConnect Structures and Enumerations
• Programming SimConnect Clients using Managed Code
• Working Samples

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 Microsoft ® Visual Studio 2005 or later, or Microsoft ® Visual C++ 2005 Express Edition or later. To build the project make sure you have completed the following steps.

C/C++ Projects

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

DLL Projects

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

   LIBRARY "DLL Project" EXPORTS DLLStart DLLStop

   
   
2. Confirm that the definition file has been added to the project by checking the Linker\Input properties:
   
   
   
   
3. Pay particular attention to the remarks and working samples for SimConnect_CallDispatch.

C#/.NET / VB.NET Projects

1. For C#, or other .NET language add-ons, refer to the special section on Programming SimConnect Clients using Managed Code.
2. Build the application using the function calls described in this document.
3. There are three C# samples, and one VB.NET sample included with the SDK for reference.

All Projects

1. Ensure that Microsoft ® Visual Studio 2005 or later, or Microsoft ® Visual C++ or C# 2005 Express Edition 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.
2. Ensure the SimConnect.ini file is in your My Documents\Flight Simulator X Files folder. You do not usually have to make any changes to this file. The SimConnect.ini file provided ensures that the SimConnect debug window opens to display communication information between the server and the clients.
3. If the client is to work remotely, write a SimConnnect.cfg file for it.
4. Ensure the EXE.xml, DLL.xml files and SimConnect.xml files are in the <Drive>:\Documents and Settings\<alias>\Application Data\Microsoft\FSX folder, and edit these files according to the instructions that follow.
5. Run Flight Simulator X to test your SimConnect client.

Setting x86 Platform Configuration

This section only applies to developers working with on a 64 bit operating system (Microsoft ® Windows Vista ®). If you are using Microsoft ® Visual Studio 2005 or later, open up your SimConnect client project and start from step 4. If you are using Microsoft ® Visual C++ or C# 2005 Express Edition, start from step 1.

1. Select the Tools/Options menu item.
2. Check “Show all settings”.
3. Check “Project and Solutions->Show Advanced Build Configurations”.
4. Open Build->Configuration Manager.
5. Select the combo box under the “Platform” column for the project you want to target.
6. Choose “NEW…”
7. Under “New Platform” select x86.
8. Click OK, then Close. Note that the Toolbar combo box for Platform Configuration has x86 selected.
9. Building will now be restricted to x86-only binaries.

The SimConnect.ini file

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

The SimConnect.cfg file

The SimConnect.cfg file contains communications information for a client. This file is only required if a client is going to access Flight Simulator running on a remote machine, and should be placed in the My Documents folder, or in the same folder as the client application or library, on the computer the client is running on. Also make sure to run the SimConnect.msi installer on the remote client machine which installs the WinSxS library, found in the \lib folder.

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

The EXE.xml and DLL.xml files

These files contain all the clients that will be activated by Flight Simulator X on start up. EXE.xml should contain all the .exe application add-ons, and DLL.xml should contain all the .dll library based add-ons. To activate just your one client, edit the appropriate file so it matches the following table, with the name and path to your client replacing the text in bold. The format of both files is identical. Both files should be in the <Drive>:\Documents and Settings\<alias>\Application Data\Microsoft\FSX folder.

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

Sample DLL.xml file

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

Note

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

The SimConnect.xml file

This file contains communication information for the SimConnect server. Normally it will not need to be changed, but the following table describes the format for the cases where changes may be necessary (usually involving remote connections). The file should be placed in the in the <Drive>:\Documents and Settings\<alias>\Application Data\Microsoft\FSX folder on the computer the server is running on.

Design Considerations

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

The recommended method of writing an add-on is to build it out-of-process, as an application (an .exe file) rather than in-process, as a library (a .dll file). This is because out-of-process applications provide more stability, if they crash they will typically will not crash Flight Simulator, 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. Note that there can be subtle improvements in the modeling of the gauges of an aircraft between versions of Flight Simulator that might change some of the sequences. For example, the operation of the overhead start switch and fuel cut-off switch for jet engines has been modified since Flight Simulator 2004. The Learning Center, accessible from the main menu of Flight Simulator, includes a huge amount of useful information on controlling aircraft within the simulator.

Versioning

SimConnect clients will not work with any version of the simulation released previous to Flight Simulator X.

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

The SimConnect client library used by Flight Simulator 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

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

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

Parameters

pData
  [in]  Pointer to a data buffer, to be treated initially as a SIMCONNECT_RECV structure. If you are going to make a copy of the data buffer (which is maintained by the SimConnect client library) make sure that the defined buffer is large enough (the size of the returned data structure is one member of the SIMCONNECT_RECV structure.
cbData
  [in]  The size of the data buffer, in bytes.

pContext
  [in]  Contains the pointer specified by the client in the SimConnect_CallDispatch function call.

Return Values

This function does not return a value.

Example

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

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

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

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

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

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

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

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

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

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

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

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

Working Samples

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_CallDispatch
• SimConnect API Reference

SimConnect_AddClientEventToNotificationGroup

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

Syntax

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
GroupID
  [in]  Specifies the ID of the client defined group.
EventID
  [in]  Specifies the ID of the client defined event.
bMaskable
  [in, optional]  Boolean, True indicates that the event will be masked by this client and will not be transmitted to any more clients, possibly including Flight Simulator itself (if the priority of the client exceeds that of Flight Simulator). 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.

Example

Working Samples

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

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.

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.

Remarks

This function must be called before a client data area can be written to or read from. Typically this function would be called once for each variable that is going to be read or written. Note that an error will not be given if the size of a data definition exceeds the size of the client area - this is to allow for the case where definitions are specified by one client before the relevant client area is created by another.

The most efficient use of client data areas is to group data that changes at the same time into the same data area. Minor performance improvements are gained by not using tagged data, or the fEpsilon parameter, if they are not needed.

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

See Also

• SimConnect_ClearClientDataDefinition
• SimConnect_CreateClientData
• SimConnect_MapClientDataNameToID
• SimConnect_RequestClientData
• SimConnect_SetClientData
• SimConnect API Reference

SimConnect_AddToDataDefinition

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

Syntax

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
DefineID
  [in]  Specifies the ID of the client defined data definition.
DatumName
  [in]  Specifies the name of the Flight Simulator 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.

Example

static enum DATA_DEFINE_ID {
  DEFINITION_1,
  DEFINITION_2
};

static enum DATA_REQUEST_ID {
    REQUEST_1,
    REQUEST_2,
};

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

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

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

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

// Sections of code in DispatchProc

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

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

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

  switch(pObjData->dwRequestID)
  {
    case REQUEST_1:

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

      break;
  }
break;
}
....


Working Samples

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

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.

Example

Working Samples

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:

See Also

• SimConnect API Reference
• SimConnect_GetNextDispatch

SimConnect_ClearClientDataDefinition

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

Syntax

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.

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

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.

Example

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

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.

Example

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

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.

Example

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

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.

Example

Working Samples

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 API Reference
• SimConnect_Open

SimConnect_CreateClientData

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

Syntax

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.

Remarks

Use this function, along with the other client data functions, to reserve an area of memory for client data on the server, that other clients can have read (or read and write) access to. Specify the contents of the data area with the SimConnect_AddToClientDataDefinition call, and set the actual values with a call to SimConnect_SetClientData. Other clients can receive the data with a call to SimConnect_RequestClientData.

The maximum size of a client data area is set by the constant SIMCONNECT_CLIENTDATA_MAX_SIZE. For the RTM version of Flight Simulator X this was 4K, for the SP1A update to the SDK it is 8K. If an add-on is to work with the RTM version, a 4K limit should be adhered to. There is no maximum number of client data areas, but the total must not exceed 1Mbyte for the SP1A update, or 100K for the RTM version. If a request is made for a client data area greater than SIMCONNECT_CLIENTDATA_MAX_SIZE a SIMCONNECT_EXCEPTION_INVALID_DATA_SIZE exception is returned. If a request is made for a client data area that will exceed the total maximum memory a SIMCONNECT_EXCEPTION_OUT_OF_BOUNDS exception is returned.

One client area can be referenced by any number of client data definitions. Typically the name of the client area, and the data definitions, should be published appropriately so other clients can be written to use them. Care should be taken to give the area a unique name.

Once created, a client data area cannot be deleted or reduced in size. To increase the size of the data area, first close the connection, then re-open it and request the client data area again, using the same name, but with the required size. The additional data area will be initialized to zero, but the previous data will be untouched by this process. Client data persists to the end of the Flight Simulator 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 flight file.

Syntax

Parameters

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

Return Values

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

Remarks

Flight files can be opened using a text editor.

See Also

• SimConnect_FlightSave
• SimConnect_FlightPlanLoad
• SimConnect API Reference

SimConnect_FlightPlanLoad

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

Syntax

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
szFileName
  [in]  Null-terminated string containing the path to the flight plan file. Flight plans have the extension .PLN, but no need to enter an extension here. There is no need to enter the full path to the file (just enter the filename) if the flight file is in the default Flight Simulator X Files directory. The easiest way to create flight plans is to create them from within Flight Simulator 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.

Remarks

Flight plan files can be opened using a text editor.

See Also

• SimConnect_FlightLoad
• SimConnect_FlightSave
• SimConnect API Reference

SimConnect_FlightSave

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

Syntax

Parameters

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

Flags
  [in]  Unused.

Return Values

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

Remarks

Flight files can be opened using a text editor.

See Also

• SimConnect_FlightLoad
• SimConnect_FlightPlanLoad
• SimConnect API Reference

SimConnect_GetLastSentPacketID

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

Syntax

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.

Example

DWORD dwLastID;

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


Working Sample

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

SimConnect_GetNextDispatch

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

Syntax

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.

Example

Working Sample

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 API Reference
• SimConnect_CallDispatch

SimConnect_MapClientDataNameToID

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

Syntax

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
szClientDataName
  [in]  Null-terminated string containing the client data area name. This is the name that another client will use to specify the data area. The name is not case-sensitive. If the name requested is already in use by another addon, a SIMCONNECT_EXCEPTION_ALREADY_CREATED error will be returned.
ClientDataID
  [in] A unique ID for the client data area, specified by the client. If the ID number is already in use, the SIMCONNECT_EXCEPTION_DUPLICATE_ID error will be returned.

Return Values

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

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 Flight Simulator event name.

Syntax

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
EventID
  [in]  Specifies the ID of the client event.
EventName
  [in]  Specifies the Flight Simulator event name. Refer to the Event IDs document for a list of event names (listed under String Name). If the event name includes one or more periods (such as "Custom.Event" in the example below) then they are custom events specified by the client, and will only be recognized by another client (and not Flight Simulator) that has been coded to receive such events. No Flight Simulator events include periods. If no entry is made for this parameter, the event is private to the client.

Alternatively enter a decimal number in the format "#nnnn" or a hex number in the format "#0xnnnn", where these numbers are in the range THIRD_PARTY_EVENT_ID_MIN and THIRD_PARTY_EVENT_ID_MAX, in order to receive events from third-party add-ons to Flight Simulator X.

Return Values

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

Example

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

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

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

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

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


Working Samples

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 API Reference
• SimConnect_TransmitClientEvent

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

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
GroupID
  [in]  Specifies the ID of the client defined input group that the input event is to be added to.
pszInputDefinition
  [in]  Pointer to a null-terminated string containing the definition of the input events (keyboard keys, mouse or joystick events, for example). See the Remarks and example below for a range of possibilities. 
DownEventID
  [in]  Specifies the ID of the down, and default, event. This is the client defined event that is triggered when the input event occurs. If only an up event is required, set this to SIMCONNECT_UNUSED.
DownValue
  [in, optional] Specifies an optional numeric value, which will be returned when the down event occurs.
UpEventID
  [in, optional]  Specifies the ID of the up event. This is the client defined event that is triggered when the up action occurs.
UpValue
  [in, optional]  Specifies an optional numeric value, which will be returned when the up event occurs.

bMaskable
  [in, optional]  If set to true, specifies that the client will mask the event, and no other lower priority clients will receive it. The default is false.

Return Values

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

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

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

For keyboard hits, usually no further information other than the key has been pressed is necessary for the client to process the event appropriately. For joystick events, other than button events, it is also important to know the extent of the movement (or position of the hat switch, or of the slider). This information is returned with the event in the dwData parameter of a SIMCONNECT_RECV_EVENT structure.

For button, hat switch, or keyboard events, one event is transmitted to the client, or two if an up event is specified, when the input event occurs. If joystick axis, rotation or slider events are requested, then an event is transmitted for these six times per second whether the joystick is actually moved or not, unless the value for these is zero, in which case events are not transmitted until the joystick is moved from this position. Joystick and keyboard events are only transmitted when a flight is loaded, not while the user is navigating the shell of the product.

For reference, the default input mappings of joystick buttons to events is specified in the devices.cfg file in the main FSX directory.

See Also

• SimConnect API Reference
• SimConnect_SetInputGroupPriority
• SimConnect_RemoveInputEvent
• SimConnect_ClearInputGroup
• SimConnect_SetInputGroupState

SimConnect_Open

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

Syntax

Parameters

phSimConnect
  [in]  Pointer to a handle to a SimConnect object.
szName
  [in]  Pointer to a null-terminated string containing an appropriate name for the client program.
hWnd
  [in]  Handle to a Windows object. Set this to NULL if the handle is not being used.
UserEventWin32
  [in]  Code number that the client can specify. Set this to 0 if it is not being used.
hEventHandle
  [in] A Windows Event handle. A client can be written to respond to Windows Events, rather than use a polling and callback system, which can be a more efficient process if the client does not have to respond very frequently to changes in data in Flight Simulator.
ConfigIndex
  [in]  The configuration index. The SimConnect.cfg file can contain a number of configurations, identified in sections with the [SimConnect.N] title. Setting this configuration index indicates which configuration settings to use for this SimConnect client. This is useful for applications that communicate with a number of different machines that are running Flight Simulator. The default configuration index is zero. Note the E_INVALIDARG return value.

Return Values

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

Example

Working Samples

Remarks

Most client applications will have one SimConnect_Open call, and one corresponding SimConnect_Close call. However in some applications, multiplayer in particular,  multiple SimConnect_Open calls may be necessary, in which case an array or list of handles will need to be maintained, and closed appropriately.

A client can optionally examine the SIMCOMMENT_RECV_OPEN structure that is returned after a call to SimConnect_Open. This structure gives versioning and build information that should be useful when multiple versions of SimConnect and multiple versions of Flight Simulator that support it, are available.

If a remote client successfully establishes a link with Flight Simulator, 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 number 4 is returned in the dwIndex parameter of the SIMCONNECT_RECV_EXCEPTION structure, for the original RTM verion of Flight Simulator X. For SP1 and subsequent releases the dwIndex parameter will contain the following: (version minor number * 65536) + version major number. For Flight Simulator X SP1 the minor number will be 0 and the major number 10. Use the LOWORD and HIWORD macros to easily extract the two numbers.

See Also

• SimConnect API Reference
• SimConnect_Close
  

SimConnect_RemoveClientEvent

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

Syntax

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.

Example

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

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.

Example

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

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.

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.

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

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
RequestID
  [in]  Specifies the ID of the client defined request. This is used later by the client to identify which data has been received. This value should be unique for each request, re-using a RequestID will overwrite any previous request using the same ID.
DefineID
  [in]  Specifies the ID of the client defined data definition.
ObjectID
  [in]  Specifies the ID of the Flight Simulator object that the data should be about. This ID can be SIMCONNECT_OBJECT_ID_USER (to specify the user's aircraft) or obtained from a SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE structure after a call to SimConnect_RequestDataOnSimObjectType. Also refer to the note on developing clients for multiplayer mode in the Remarks section below.
Period
  [in]  One member of the SIMCONNECT_PERIOD enumeration type, specifying how often the data is to be sent by the server and received by the client.

Flags
  [in, optional]  A DWORD containing one or more of the following values:

Flag value	Description
0	The default, data will be sent strictly according to the defined period.
SIMCONNECT_DATA_REQUEST_FLAG_CHANGED	Data will only be sent to the client when one or more values have changed. If this is the only flag set, then all the variables in a data definition will be returned if just one of the values changes.
SIMCONNECT_DATA_REQUEST_FLAG_TAGGED	Requested data will be sent in tagged format (datum ID/value pairs). Tagged format requires that a datum reference ID is returned along with the data value, in order that the client code is able to identify the variable. This flag is usually set in conjunction with the previous flag, but it can be used on its own to return all the values in a data definition in datum ID/value pairs. See the SIMCONNECT_RECV_SIMOBJECT_DATA structure for more details.

origin
  [in, optional]  The number of Period events that should elapse before transmission of the data begins. The default is zero, which means transmissions will start immediately.

interval
  [in, optional]  The number of Period events that should elapse between transmissions of the data. The default is zero, which means the data is transmitted every Period.

limit
  [in, optional]  The number of times the data should be transmitted before this communication is ended. The default is zero, which means the data should be transmitted endlessly.

Return Values

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

Example

static enum DATA_DEFINE_ID {
  DEFINITION_1,
  DEFINITION_2
};

static enum DATA_REQUEST_ID {
    REQUEST_1,
    REQUEST_2,
};

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

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

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

// Sections of code in DispatchProc

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

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

  switch(pObjData->dwRequestID)
  {
    case REQUEST_2:

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

      break;
  }
break;
}
....


Working Samples

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.

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

Note: Multiplayer Mode

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

See Also

• SimConnect 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

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.

Example

See SimConnect_AddToDataDefinition for an example of when to use this function

Working 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_RequestNotificationGroup

The SimConnect_RequestNotificationGroup function is used to request events are transmitted from a notification group, when the simulation is in Dialog Mode.

Syntax

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.

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

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.

Working Sample

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_MenuAddItem
• SimConnect API Reference

SimConnect_RequestSystemState

Syntax

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:

Return Values

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

Remarks

See Also

• SimConnect API Reference
• SimConnect_SetSystemState

SimConnect_SetClientData

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

Syntax

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.

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.

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

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
DefineID
  [in]  Specifies the ID of the client defined data definition.
ObjectID
  [in]  Specifies the ID of the Flight Simulator 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.

ArrayCount
  [in]  Specifies the number of elements in the data array. A count of zero is interpreted as one element. Ensure that the data array has been initialized completely before transmitting it to Flight Simulator. 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.

Return Values

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

Example

Working Samples

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

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.

Example

Working Samples

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

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.

Example

Working Samples

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

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.

Example

Working Samples

Remarks

SimConnect Priorities

Each notification group has an assigned priority, and the SimConnect server will send events out strictly in the order of priority. No two groups will be set at the same priority. If a request is received for a group to be set at a priority that has already been taken, the group will be assigned the next lowest priority that is available. This includes groups from all the clients that have opened communications with the server.

If a group has an assigned priority above SIMCONNECT_GROUP_PRIORITY_HIGHEST_MASKABLE then it cannot mask events (hide them from other clients). If the group has a priority equal to or below SIMCONNECT_GROUP_PRIORITY_HIGHEST_MASKABLE, then events can be masked (the maskable flag must be set by the SimConnect_AddClientEventToNotificationGroup function to do this). Note that it is possible to mask Flight Simulator events, and therefore intercept them before they reach the simulation engine, and perhaps send new events to the simulation engine after appropriate processing has been done. Flight Simulator's simulation engine is treated as SimConnect client in this regard, with a priority of SIMCONNECT_GROUP_PRIORITY_DEFAULT.

Input group events work in a similar manner. The priority groups are not combined though, a group and an input group can both have the same priority number. The SimConnect server manages two lists: notification groups and input groups.

A typical use of masking is to prevent Flight Simulator itself from receiving an event, in order for the SimConnect client to completely replace the functionality in this case. Another use of masking is with co-operative clients, where there are multiple versions (perhaps a deluxe and standard version, or later and earlier versions), where the deluxe or later version might need to mask events from the other client, if they are both up and running. Flight Simulator 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

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.

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 API Reference
• SimConnect_MapClientEventToSimEvent
• SimConnect_MapInputEventToClientEvent

SimConnect_SetSystemState

Syntax

Parameters

hSimConnect
  Handle to a SimConnect object.
szState
  A null-terminated string identifying the system function. One from the following table:

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.

Working Samples

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 API Reference
• SimConnect_RequestSystemState
• SimConnect_SubscribeToSystemEvent

SimConnect_SubscribeToSystemEvent

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

Syntax

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

Return Values

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

Example

static enum EVENT_ID {
   EVENT_FLIGHT_LOAD,
   EVENT_RECUR_1SEC,
   EVENT_RECUR_FRAME,
};
hr = SimConnect_SubscribeToSystemEvent(hSimConnect, EVENT_FLIGHT_LOAD, "FlightLoaded");

hr = SimConnect_SubscribeToSystemEvent(hSimConnect, EVENT_RECUR_1SEC,  "1sec");
hr = SimConnect_SubscribeToSystemEvent(hSimConnect, EVENT_RECUR_FRAME, "frame");

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


Working Samples

Remarks

A single call to this function is all that is necessary to receive the notifications. For greatest efficiency use SimConnect_SetSystemEventState to turn these requests on and off temporarily, and call SimConnect_UnsubscribeFromSystemEvent once only to permanently terminate the notifications of these events.

See Also

• SimConnect_RequestSystemState
• SimConnect_SetSystemState
• SimConnect API Reference

SimConnect_TransmitClientEvent

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

Syntax

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
ObjectID
  [in]  Specifies the ID of the server defined object. If this parameter is set to SIMCONNECT_OBJECT_ID_USER, then the transmitted event will be sent to the other clients in priority order. If this parameters contains another object ID, then the event will be sent direct to that sim-object, and no other clients will receive it.
EventID
  [in]  Specifies the ID of the client event.
dwData
  [in]  Double word containing any additional number required by the event. This is often zero. If the event is a Flight Simulator 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:

Return Values

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

Examples

Working Sample

Remarks

Typically use this function to transmit an event to other SimConnect clients, including the simulation engine of Flight Simulator, 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 API Reference
• SimConnect_MapClientEventToSimEvent
  

SimConnect_UnsubscribeFromSystemEvent

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

Syntax

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.

Example

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


hr = SimConnect_SubscribeToSystemEvent(hSimConnect, EVENT_RECUR_1SEC);

...

hr = SimConnect_UnsubscribeFromSystemEvent(hSimConnect, EVENT_RECUR_1SEC);

Remarks

There is no limit to the number of system events that can be subscribed to, but use this function to improve performance when a system event notification is no longer needed.

See Also

• SimConnect_SubscribeToSystemEvent
• SimConnect API Reference
  

Helper Functions

SimConnect_InsertString

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

Syntax

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.

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 API Reference
• SimConnect_RetrieveString
  

SimConnect_RequestResponseTimes

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

Syntax

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.

Example

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

SimConnect_RetrieveString

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

Syntax

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.

Example

Working Sample

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

• SimConnect API Reference
• SimConnect_InsertString

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

Parameters

hSimConnect
  [in]  Handle to a SimConnect object.
szContainerTitle
  [in]  Null-terminated string containing the container title. The container title is found in the aircraft.cfg file (see the Aircraft Configuration Files document): for example: title=Airbus A321, title= Aircreation582SL, or title=Boeing 737-800.
szTailNumber
  [in]  Null-terminated string containing the tail number. This should have a maximum of 12 characters.
iFlightNumber
  [in]  Integer containing the flight number. There is no specific maximum length of this number. Any negative number indicates that there is no flight number.
szFlightPlanPath
  [in]  Null-terminated string containing the path to the flight plan file. Flight plans have the extension .pln, but no need to enter an extension here. The easiest way to create flight plans is to create them from within Flight Simulator itself, and then save them off for use with the AI controlled aircraft. There is no need to enter the full path to the file (just enter the filename) if the flight plan is in the default Flight Simulator X 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.

Working Sample

Remarks

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

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

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

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

The Reality Bubble

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

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

Aircraft Flight Plans

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

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

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, title= Aircreation582SL, or title=Boeing 737-800.
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.

Working Sample

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

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, title= Aircreation582SL, or title=Boeing 737-800.
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.

Working Sample

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, Flight Simulator 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

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:

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.

Working Sample

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

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.

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 AI creation functions.

Syntax

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.

Remarks

A client application can only remove AI controlled objects that it created, not objects created by other clients, or Flight Simulator 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

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 Flight Simulator itself, and then save them off for use with the AI controlled aircraft. There is no need to enter the full path (just the filename) if the flight plan is in the default Flight Simulator X 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.

Working Sample

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

Camera Specific Functions

SimConnect_CameraSetRelative6DOF

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

Syntax

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.

Working Sample

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

Facilities Specific Functions

SimConnect_RequestFacilitesList

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

Syntax

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.

Working Sample

Remarks

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

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

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

• 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_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 API Reference
• SimConnect_SubscribeToFacilities
• SimConnect_UnsubscribeToFacilities

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

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.

Working Sample

Remarks

See the remarks for SimConnect_RequestFacilitesList.

See Also

• SimConnect API Reference
• SimConnect_UnsubscribeToFacilities

SimConnect_UnsubscribeToFacilities

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

Syntax

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.

Working Sample

Remarks

See the remarks for SimConnect_RequestFacilitesList.

See Also

• SimConnect API Reference
• SimConnect_SubscribeToFacilities

Menu Specific Functions

SimConnect_MenuAddItem

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

Syntax

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.

Working Sample

Remarks

The menu item will be added to the Add-ons menu. The Add-ons menu will only appear in Flight Simulator 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_MenuDeleteItem
• SimConnect_MenuDeleteSubItem
• SimConnect API Reference

SimConnect_MenuAddSubItem

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

Syntax

Parameters

Return Values

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

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

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.

Working Sample

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
• SimConnect API Reference

SimConnect_MenuDeleteSubItem

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

Syntax

Parameters

Return Values

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

Remarks

If a sub-menu item is deleted from the middle of the sub-menu item list, the list will contract.

See Also

• SimConnect_MenuAddItem
• SimConnect_MenuAddSubItem
• SimConnect_MenuDeleteItem
• SimConnect API Reference

SimConnect_Text

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

Syntax

Parameters

Return Values

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

Working Sample

Remarks

Only one text and one menu request can appear on the screen at one time. Requests are queued as they are received, with only the topmost in the queue being displayed. There is one queue for menus and another for static and scrolling text. When a request is first displayed the SIMCONNECT_TEXT_RESULT_DISPLAYED event will be sent to the client. If a request joins the queue and cannot immediately be displayed the event SIMCONNECT_TEXT_RESULT_QUEUED will be sent. When it is the turn of the new request to be displayed the SIMCONNECT_TEXT_RESULT_DISPLAYED event will be sent. If the request is for a menu, and the user selects one of the menu entries, one of the SIMCONNECT_TEXT_RESULT_MENU_SELECT_N events will be returned (see the SIMCONNECT_TEXT_RESULT enumeration), and the menu closed.

The default location for static or scrolling text is along the top of the screen. A user can move and resize the window that the text is being displayed in, but it is not possible to specify an alternative location for the text programmatically.

See Also

• SimConnect_MenuAddItem
• SimConnect API Reference

Mission Specific Functions

SimConnect_CompleteCustomMissionAction

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

Syntax

Parameters

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

Return Values

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

Working Sample

Remarks

A mission is specified in an xml file (see the Mission Creation documentation). A custom action is defined within this xml file, and will look similar to the following:

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

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

If the client calls SimConnect_ExecuteMissionAction from within the code for a custom action, and it is important that this action completes before any other actions are started (that is, WaitForCompletion is True) then a second custom action should be defined that calls SimConnect_CompleteCustomMissionAction after that action is complete, and with the GUID of the first custom action as its parameter. The 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 mission requires additional processing on its completion the SimConnect client should use the SimConnect_SubscribeToSystemEvent call with the SystemEventName parameter set to "MissionCompleted".

See Also

• SimConnect_ExecuteMissionAction
• SimConnect_SubscribeToSystemEvent
• SimConnect API Reference

SimConnect_ExecuteMissionAction

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

Syntax

Parameters

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

Return Values

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

Working Sample

Remarks

A mission is specified in an xml file (see the Mission Creation documentation).

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

See the remarks for SimConnect_CompleteCustomMissionAction.

See Also

• 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

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.

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_WeatherRemoveStation
• SimConnect API Reference

SimConnect_WeatherCreateThermal

The SimConnect_WeatherCreateThermal function is used to create a thermal at a specific location.

Syntax