Mise à jour : 21 juin 2011                             Traduction en cours

Référence pour le SDK de SimConnect

Attention : un correctif SP1 a été publié pour le SDK de FS X. Il est téléchargeable depuis le site de Microsoft, à l'adresse http://www.microsoft.com/download/en/details.aspx?id=10027. La traduction qui suit ne tient pas encore compte de ce SP1.

Accès à la version anglaise de la référence du SDK SP1 : SimConnect SP1.

Sommaire

Survol

Le SDK SimConnect peut être utilisé par les programmeurs pour écrire des composants additionnels pour Microsoft ® Flight Simulator X. Ces composants peuvent être écrits en C, C + +, ou, si les appels aux API sont utilisés, tout langage Microsoft  .NET tel que C#.net ou VB.net. Typiquement, les composants réaliseront une ou plusieurs des tâches suivantes :

Réglages initiaux

Cette section décrit comment mettre en place un environnement de développement pour SimConnect.

 

Les projets SimConnect

Pour construire des add-ons SimConnect, vous devez utiliser Microsoft ® Visual Studio 2005 ou une version ultérieure, ou Microsoft ® Visual C++ 2005 Express Edition ou ultérieure. Pour construire le projet assurez-vous d'avoir exécuté les étapes suivantes.

Projets C/C++

1. Pour des add-ons en C ou C++, démarrer un nouveau projet Application sur la console Win32 si l'add-on n'a d'interface utilisateur. Démarrez un nouveau projet Win32 ou MFC Application si l'add-on a une interface utilisateur.

2. Inclure le fichier d'entête SimConnect.h.

3. Faites le link vers la bibliothèque SimConnect.lib, en ajoutant SimConnect.lib aux options supplémentaires de la ligne de commande (voir image ci-dessous):

4. Générez l'application en utilisant la fonction appels décrits dans ce document.

Projets DLL

1. Créez et ajoutez un fichier de définition pour le projet. Ceci est nécessaire parce SimConnect attend que les noms exportés DLLStart et DLLStop soient nus (par défaut, des caractères supplémentaires sont ajoutés à ces noms). Le fichier de définition peut être créé en sélectionnant Project/Add New Item (Projet/Ajouter un nouvel élément) dans le menu principal de Visual Studio. Modifier de fichier de définition (.def) afin qu'il ressemble à ceci (où DLL projet est le nom de votre projet) :

LIBRARY "DLL Project"
EXPORTS
DLLStart
DLLStop

2. Confirmez que le fichier de définition a bien été ajouté au projet en contrôlant les propriétés du Linker\Inputs :

3.  Soyez attentif aux remarques et aux exemples opérationnels pour SimConnect_CallDispatch.

Projets C#/.NET

Tous projets

 

Le fichier SimConnect.ini

Le fichier par défaut SimConnect.ini active la fenêtre de debug et désactive le fichier log. Utilisez une point-virgule débuter un commentaire, ou pour rendre inactive une une directive. Le ficheir doit se trouver dans votre dossier My Documents\Flight Simulator X Files.

Directive Values Description
level Verbose, Normal, Warning, Error, Off Fixe le niveau de communication texte à fournir à la console, à la cahîne de debug ou au fichier log (journal).
console Yes, No Ouvre une fenêtre de debug en ligne de commande pour afficher les communications avec le client.
OutputDebugString Yes, No Envoie un texte à la plateforme OutputDebugString du SDK. Se reporter à la documentation sur MSDN pour plus de détails.
file Filename

Emet les communications en sortie vers un fichier log (journal). Si le texte 03U% est inclus dans le nom du fichier, alors le nom du fichier sera incrémenté à chaque démarrage de Flight Simulator,  donnant ainsi un nouveau fichier journal pour chaque essai. Exemple : file = c:\SimConnect%03u.log.

file_next_index Integer L'index du 1er fichier log. Les fichiers log suivants auront leur index incrémenté de 1.

 

Le fichier SimConnect.cfg

Le fichier SimConnect.cfg contient des informations  de communications pour un client. Ce fichier n'est nécessaire que si un client veut accéder à Flight Simulator fonctionnant sur une machine distante, et doit être placé dans le dossier Mes documents, ou dans le même dossier que l'application cliente ou de la bibliothèque, sur l'ordinateur où le client s'exécute. Veillez en outre à lancer l'installateur SimConnect.msi sur la machine cliente distante, ce qui installe la bibliothèque WinSxS, trouvée dans le dossier \lib.

Le fichier SimConnect.cfg peut contenir un nombre de configurations, identifiées dans les sections avec le titre [SimConnect.N]. Le numéro d'index est utilisé comme un paramètre dans la fonction SimConnect_Open. Ceci est utile pour les applications qui communiquent avec un certain nombre de machines différentes qui exécutent Flight Simulator. L'indice de configuration par défaut est zéro, et s'il n'y a qu'une seule configuration dans le fichier, aucun numéro d'index n'est nécessaire.

Directive Values Description
Protocol IPv4, IPv6 Both protocols are available on computers running Microsoft Windows ®, with IPv4 as the default. IPv6 has more security features and is recommended. If IPv6 is not already installed, there is a utility to install it in the SimConnect SDK\config folder.
Address Port   The Address and Port of the SimConnect server should be entered in these fields, these will be the same values as those in the appropriate Comm section of the Simconnect.xml file. A good knowledge of Windows networking and client/server applications will be needed to set these correctly. The address can be the name of a computer in a Domain Controller environment.
MaxReceiveSize Integer The maximum packet size. The default is 8192. If the client receives a packet larger than this size, it will disconnect from the server.
DisableNagle 0, 1 Set to 1 to disable the Nagle packet optimization algorithms.

 

Les fichiers EXE.xml et DLL.xml

Ces fichiers contiennent tous les clients qui seront activés par Flight Simulator X au démarrage. EXE.xml doit contenir toutes les application add-ons  .exe, et DLL.xml doit contenir toutes les bibliothèque .dll des add-ons. Pour activer votre client unique, éditez le fichier approprié afin qu'il corresponde au tableau suivant, avec le nom et le chemin de votre client remplaçant le texte en gras. Les formats des deux fichiers sont identiques. Ces deux fichiers doivent être dans le <Lecteur>:\Documents and Settings\<alias>\Application Data\Microsoft\FSX.

 Pour chaque bibliothèque add-on, saisir les informations suivantes dans DLL.xml, et pour chaque application add-on saisir les informations suivantes dans EXE.xml :

XML Description
< Launch.Addon > Add one Launch.Addon section for each client.
< Disabled > False< /Disabled > Set to True to disable the client.
< Name >Your Client Name < /Name > The client application or library name.
< Path > Path\Client.exe/.dll< /Path > If the client is local, the path relative to the main Microsoft Flight Simulator X folder where the game is installed, and the client application or library name.
If the client is remote, and a share on the remote machine is accessible from the machine on which Flight Simulator X is running, the client will be launched.
Definition: UNC provides a naming convention for identifying network resources. UNC names consist of three parts, a server name, a share name, and an optional file path, that are combined using backslashes as follows:
\\server\share\file_path
<CommandLine>< /CommandLine > This applies to .exe files only. Provides a command line string to the application.
< /Launch.Addon >  

 

Echantillon de fichier DLL.xml

L'exemple suivant de fichier DLL.xml contient deux add-ons, le 1er est activé, et le 2e non. Tous les add-ons peuvent être désactivés en mettant l'entrée globale <Disabled> à True. Si <ManualLoad> est mis à True, alors l'utilisateur recevra un une fenêtre de dialogue lui demandant s'il souhaite charger l'add-on ou non.

<?xml version="1.0" encoding="Windows-1252"?>
<SimBase.Document Type="Launch" version="1,0">
<Descr>Launch</Descr>
<Filename>dll.xml</Filename>
<Disabled>False</Disabled>

<Launch.ManualLoad>False</Launch.ManualLoad>
<Launch.Addon>
   <Name>First addon</Name>
   <Disabled>False</Disabled>
   <Path>First Addon.dll</Path>
</Launch.Addon>

<Launch.Addon>
   <Name>Second addon </Name>
   <Disabled>True</Disabled>
   <Path>Second Addon.dll</Path>
</Launch.Addon>
</SimBase.Document>

Note : tout ce qu'ajouter un fichier dans les fichiers EXE.xml ou DLL.xml fait est de s'assurer qu'il démarre avec Flight Simulator (à condition que Disabled soit mis à False). Il ne garantit pas que le programme se termine lorsque l'utilisateur quitte Flight Simulator. Ceci doit être géré à partir du client lui-même. Pour de nombreuses applications, se terminer en même temps serait souhaitable, mais pour des applications de contrôle, il pourrait aussi bien être souhaitable que le client continue à tourner après la sortie du simulateur. Il est également possible pour l'utilisateur de cliquer et de commencer toute application cliente à tout moment, que Flight Simulator soit en marche ou non. Les deux fichiers XML sont fournis pour commodité seulement, et il n'y a aucune obligation pour ajouter un client ces fichiers.

 

Le fichier SimConnect.xml

Ce fichier contient des informations de communication pour le serveur SimConnect. Normalement, il n'a pas besoin d'être changé, mais le tableau suivant décrit le format pour les cas où des changements peuvent être nécessaires (impliquant généralement des connexions à distance). Le fichier doit être placé dans le dans le <Lecteur>: \Documents and Settings\<alias>\Application Data\Microsoft\FSX sur l'ordinateur qui exécute le serveur.

XML Values Description
< SimBase.Document Type="SimConnect" version="1,0" > String SimConnect version information.
< Descr > SimConnect< /Descr > String Description of this file.
< Filename > SimConnect.xml< /Filename > String This filename.
< Disabled > False< /Disabled > True, False Set to True to disable SimConnect completely.
     
< SimConnect.Comm >   Communications section. If remote connections are required, then additional SimConnect.Comm sections should be added, one for each protocol or scope that should be supported.
< Disabled > False< /Disabled > True, False Set to True to disable this communication section.
< Protocol > Auto< /Protocol > Auto, IPv4, IPv6 IPv6 is selected by an Auto setting in preference to IPv4.
< Scope > local< /Scope >

local,

global,

link-local,

unrestricted

For IPv4, one of local or global. For IPv6, one of local, link-local, global, or unrestricted. Link-local is an IPv6 mechanism for accessing computers on a network that does not involve traversing a router. Unrestriced enables Teredo tunneling. Refer to IPv4 and IPv6 documentation for more details.

< Address > < /Address >

< Port > < /Port >

 

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

True,

False

Set to True to disable the Nagle packet sending algorithms.
< /SimConnect.Comm >    
< /SimBase.Document >    

 

Considérations de conception

La conception d'un add-on SimConnect implique la rédaction d'un client pour communiquer avec un serveur s'exécutant au sein de Flight Simulator. Le client ouvre les communications avec le serveur, puis demande que certains événements et certaines informations de l'objet lui soient transmis. Le client attend ensuite l'information du serveur, puis les traite de manière appropriée.

 La méthode recommandée pour la rédaction d'un add-on est pour le construire indépendamment (out-of-process), comme une application (un fichier .exe) plutôt que dans le processus, comme une bibliothèque (un fichier .dll). Les raisons sont que les applications indépendantes sont plus stables, si elles plantent elles ne plantent généralement pas Flight Simulator, et elles sont plus faciles à construire, tester et déboguer. Les applictions indépendantes supportent également le code managé et donc les applications peuvent être écrites en langages .NET, avec leur support riche d'objets et la facilité de construction de l'interface utilisateur. Les clients SimConnect ne sont actuellement pas thread-safe.

Une seule version de Flight Simulator peut être exécutée sur un ordinateur à la fois, donc un client installé sur une machine locale ne communiquera qu'avec un seul serveur. Cependant il est possible d'avoir une communication client avec plusieurs copies de Flight Simulator, fonctionnant sur un réseau.

La bibliothèque SimConnect du client utilisée par Flight Simulator sera située dans le dossier WinSxS (side-by-side). Quand de nouvelles versions de la bibliothèque client sont publiées, elles seront aussi placées dans ce dossier, ajoutées et non remplaçant les versions précédentes. Cela signifie que des add-ons écrites pour des versions plus anciennes de SimConnect continueront à fonctionner même avec des les versions plus récentes installées.

SimConnect fait un usage intensif des numéros d'identification définis par le client. Il y a des numéros d'identification pour les demandes, les définitions de données, d'événements, groupes, etc. Ces numéros d'identification doivent être uniques pour le client. Réutiliser un ID entraînera que les appels précédents à cet ID deviendra obsolète, et sera ignoré par le serveur.

C'est une bonne idée de vérifier les séquences de contrôle (telles que le démarrage) dans le simulateur lui-même, avant de tenter de coder ces séquences en utilisant des appels SimConnect. Notez qu'il  peut y avoir des améliorations subtiles dans la modélisation des gauges d'un avion entre deux versions de Flight Simulator, ce qui pourrait changer certaines des séquences. Par exemple, le fonctionnement des interrupteurs de plafonnier et de coupure du carburant pour les moteurs à réaction a été modifié depuis Flight Simulator 2004. Le Centre d'apprentissage, accessible depuis le menu principal de Flight Simulator, comprend une quantité énorme d'informations utiles sur le contrôle des avions dans le simulateur.

SimConnect clients ne fonctionnera avec aucune version précédente de Flight Simulator.

La référence des API SimConnect

Cette section répertorie toutes les fonctions, structures, énumérations, et autres informations de codage de l'API nécessaires pour créer des clients SimConnect.

L'information sur chaque appel d'API inclut quelques exemples de code. Ce code ne forme aucunement un programme complet, mais présente simplement les usages de l'appel d'API. Les sections Echantillons fonctionnels (échantillons opérationnels) listent les échantillons de code exécutables.

Function Description
Fonctions générales
 
DispatchProc

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

SimConnect_AddClientEventToNotificationGroup

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

SimConnect_AddToClientDataDefinition Used to add an offset and a size in bytes, to a client data definition.
SimConnect_AddToDataDefinition

Used to add a Flight Simulator simulation variable name to a client defined object definition.

SimConnect_CallDispatch

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

SimConnect_ClearClientDataDefinition Used to clear the definition of the specified client data.
SimConnect_ClearDataDefinition

Used to remove all simulation variables from a client defined object.

SimConnect_ClearInputGroup

Used to remove all the input events from a specified input group object.

SimConnect_ClearNotificationGroup

Used to remove all the client defined events from a notification group.

SimConnect_Close

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

SimConnect_CreateClientData Used to request the creation of a reserved data area for this client.
SimConnect_FlightLoad Used to load an existing flight file.
SimConnect_FlightPlanLoad Used to load an existing flight plan.
SimConnect_FlightSave Used to save the current state of a flight to a flight file.
SimConnect_GetLastSentPacketID

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

SimConnect_GetNextDispatch

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

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

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

SimConnect_MapInputEventToClientEvent

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

SimConnect_Open

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

SimConnect_RemoveClientEvent

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

SimConnect_RemoveInputEvent

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

SimConnect_RequestClientData Used to request that the data in an area created by another client be sent to this client.
SimConnect_RequestDataOnSimObject

Used to request when the SimConnect client is to receive data values for a specific object.

SimConnect_RequestDataOnSimObjectType

Used to retrieve informtion about simulation objects of a given type that are within a specifed radius of the user's aircraft.

SimConnect_RequestNotificationGroup Used to request events are transmitted from a notification group, when the simulation is in Dialog Mode.
SimConnect_RequestReservedKey

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

SimConnect_RequestSystemState Used to request information from a number of Flight Simulator system components.
SimConnect_SetClientData Used to write one or more units of data to a client data area.
SimConnect_SetDataOnSimObject Used to make changes to the data properties of an object.
SimConnect_SetInputGroupPriority

Used to set the priority for a specified input group object.

SimConnect_SetInputGroupState

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

SimConnect_SetNotificationGroupPriority

Used to set the priority of a notification group.

SimConnect_SetSystemEventState

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

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

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

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

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

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

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

AI Object Specific Functions
 
SimConnect_AICreateEnrouteATCAircraft

Used to create an AI controlled aircraft that is about to start or is already underway on its flight plan.

SimConnect_AICreateNonATCAircraft

Used to create an aircraft that is not flying under ATC control (so is typically flying under VFR rules).

SimConnect_AICreateParkedATCAircraft

Used to create an AI controlled aircraft that is currently parked and does not have a flight plan.

SimConnect_AICreateSimulatedObject

Used to create AI controlled objects other than aircraft.

SimConnect_AIReleaseControl

Used to clear the AI control of a simulated object, typically an aircraft, in order for it to be controlled by a SimConnect client.

SimConnect_AIRemoveObject Used to remove any object created by the client using one of the AI creation functions.
SimConnect_AISetAircraftFlightPlan

Used to set or change the flight plan of an AI controlled aircraft.

Camera Specific Functions
 
SimConnect_CameraSetRelative6DOF Used to adjust the user's aircraft view camera.
Menu Specific Functions
 
SimConnect_MenuAddItem

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

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

Used to remove a client defined menu item.

SimConnect_MenuDeleteSubItem Used to remove a specifed sub-menu item.
Mission Specific Functions
 
SimConnect_CompleteCustomMissionAction

Used to complete the mission action specified by a GUID.

SimConnect_ExecuteMissionAction

Used to execute the mission action specified by a GUID.

Weather Specific Functions
 
SimConnect_WeatherCreateStation Used to add a weaher station.
SimConnect_WeatherCreateThermal

Used to create a thermal at a specific location.

SimConnect_WeatherRemoveStation Used to remove a weather station.
SimConnect_WeatherRemoveThermal

Used to remove a thermal.

SimConnect_WeatherRequestCloudState Used to request cloud density information on a given area.
SimConnect_WeatherRequestInterpolatedObservation

Used to send a request for weather data that is interpolated from the weather at the nearest weather stations.

SimConnect_WeatherRequestObservationAtNearestStation

Used to send a request for the weather data from the weather station nearest to the specified lat/lon position. 

SimConnect_WeatherRequestObservationAtStation

Used to send a request for the weather data from a weather station identified by its ICAO code.

SimConnect_WeatherSetDynamicUpdateRate Used to set the rate at which cloud formations change.
SimConnect_WeatherSetModeCustom Used to set the weather mode to user-defined.
SimConnect_WeatherSetModeGlobal Used top set the weather mode to global, so the same weather data is used everywhere.
SimConnect_WeatherSetModeServer Used to switch to a local server for weather observation data.
SimConnect_WeatherSetModeTheme Used to set the weather mode to a particular theme.
SimConnect_WeatherSetObservation

Used to set the weather at a specific weather station, identified from within the Metar data string


Fonctions générales

DispatchProc

La fonction DispatchProc est écrite par le développeurr du client SimConnect, en tant que fonction d'appel en retour (callback) pour gérer toutes les communications avec le serveur.

Syntaxe

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

Paramètres

pData
  [in]  Pointeur vers le tampon de données, à traiter comme une structure SIMCONNECT_RECV . Si vous prévoyez de faire une copie du tampon de données (qui est maintenue par la bibliothèque client de SimConnect), assurez-vous que le tampon défini est suffisamment grand (la taille de la structure de données retournée est un membre de la structure SIMCONNECT_RECV.
cbData
  [in]  La taille du tampon de données, en octets.

pContext
  [in]  Contient le pointeur spécifié par le client dans l'appel à la fonction SimConnect_CallDispatch.

Valeurs retournées

Cette fonction ne retourne aucune valeur.

Exemple

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;
   }
}

Echantillons fonctionnels

Primary samples Client Event
Tracking Errors
Reference samples All but a few of the other samples implement this function.

Remarques

Cette fonction peut être nommée de façon appropriée par le développeur du client. Le nom de la fonction est passé à la bibliothèque côté client avec l'appel de fonction  SimConnect_CallDispatch. Manipulez tous les événements de rappel dans cette fonction. Si vous ne souhaitez pas mettre en œuvre une fonction de rappel, utilisez SimConnect_TransmitClientEvent.

Pour recevoir des notifications cadencées (déclenchées par le temps), consultez la fonction SimConnect_SubscribeToSystemEvent. Pour recevoir des notifications déclenchées par des événements, voir la fonction SimConnect_AddClientEventToNotificationGroup. Pour envoyer un événement à d'autres clients, consultez la fonction SimConnect_TransmitClientEvent.

Voir aussi



SimConnect_AddClientEventToNotificationGroup

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

Syntaxe

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

Paramètres

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.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Exemple

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

Echantillons fonctionnels

Primary samples Client Event
Cockpit Camera
Joystick Input
Menu Items
Send Event A
Send Event B
Send Event C
Tracking Errors
Reference samples Many of the other samples implement this function.

Remarques

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 Exemple above) must be assigned to a notification group before any event notifications will be received from the SimConnect server.

Voir aussi

 

SimConnect_AddToClientDataDefinition

La fonction SimConnect_AddToClientDataDefinition est utilisée pour ajouter un offset et une taille en octets à la définition d'une donnée client.

Syntaxe

HRESULT SimConnect_AddToClientDataDefinition(
  HANDLE  hSimConnect,
  SIMCONNECT_CLIENT_DATA_DEFINITION_ID   DefineID,
  DWORD  dwOffset,
  DWORD  dwSize,
  DWORD  dwReserved = SIMCONNECT_UNUSED
);

Paramètres

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.
dwSize
  [in]  Double word specifiying the size of the new addition, in bytes.
dwReserved
  [in, optional]  Reserved for future use.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK
 La fonction a réussi
E_FAIL La fonction a échoué.

Remarques

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.

Whereas data definitions for client areas are defined in bytes, it is anticipated that most clients will write in specific data types, and cast appropriately when the data is received.

Voir aussi

SimConnect_AddToDataDefinition

La fonction SimConnect_AddToDataDefinition est utilisée pour ajouter un nom de variable simulée par Flight Simulator à une définition d'objet définie par le client.

Syntaxe

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

Paramètres

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 Exemple 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 Exemple. 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 Paramètres 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. 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.
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.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Exemple

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 Exemple 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;
}
....

Echantillons fonctionnels

Primary samples

Request Data
Set Data
Tagged Data
Throttle Contol

Remarques

The maximum number of entries in a data definition is 1000.

Voir aussi


SimConnect_CallDispatch

La fonction SimConnect_CallDispatch est utilisée pour traiter le prochain message SimConnect reçu, à travers la fonction de rappel spécifiée.

Syntaxe

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

Paramètres

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.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Exemple

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

Echantillons fonctionnels

Primary samples

Client Event

Tracking Errors

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

Remarques

Il est important d'appeler cette fonction suffisamment fréquemment afin que la file d'attente d'informations reçues depuis le serveur soit traitée (généralement elle est codée dans une boucle while qui se termine lorsqu'on sort de l'application). Toutefois, si le projet consiste à développer une bibliothèque (DLL) plutôt que d'une application (EXE), alors un seul appel à cette fonction est nécessaire.Cet appel va stocker le nom du rappel dans un cache, et chaque fois qu'un paquet est envoyé au client, la fonction de rappel sera exécutée. Le format d'un projet de DLL est montré dans le tableau suivant :

// Include files are no different than for an EXE
HANDLE hSimConnect = NULL;
void CALLBACK MyDispatchProcDLL(SIMCONNECT_RECV* pData, DWORD cbData, void *pContext)
{
  // Callback code for a DLL is no different than for an EXE
}
//
// The DLLStart function must be present.
//
int __stdcall DLLStart(void)
{
  HRESULT hr;
  if (SUCCEEDED(SimConnect_Open(&hSimConnect, "DLL name", NULL, 0, NULL, 0)))
  {
    printf("\nConnected to Flight Simulator");
    // Place all initialization code for the client in this function
    hr = SimConnect_CallDispatch(hSimConnect, MyDispatchProcDLL, NULL);
  }
  return 0;
}
//
// The DLLStop function must be present.
//
void __stdcall DLLStop(void)
{
  // Close the client
    if (hSimConnect != NULL)
    HRESULT hr = SimConnect_Close(hSimConnect);
}

 

Voir aussi



SimConnect_ClearClientDataDefinition

La fonction SimConnect_ClearClientDataDefinition est utilisée pour effacer la définition de la donnée spécifiée par le client.

Syntaxe

HRESULT SimConnect_ClearClientDataDefinition(
  HANDLE  hSimConnect,
  SIMCONNECT_CLIENT_DATA_DEFINITION_ID   DefineID
);

Paramètres

hSimConnect
  [in]  Handle to a SimConnect object.
DefineID
  [in]  Specifies the ID of the client defined client data definition.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Remarques

Aucune.

Voir aussi


SimConnect_ClearDataDefinition

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

Syntaxe

HRESULT SimConnect_ClearDataDefinition(
  HANDLE  hSimConnect,
  SIMCONNECT_DATA_DEFINITION_ID  DefineID
);

Paramètres

hSimConnect
  [in]  Handle to a SimConnect object.
DefineID
  [in]  Specifies the ID of the client defined data definition.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Exemple

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

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

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

Remarques

Use this funtion to permanently delete a data definition. To temporarily suspend data requests see the Remarques for the SimConnect_RequestDataOnSimObject function .

Voir aussi


SimConnect_ClearInputGroup

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

Syntaxe

HRESULT SimConnect_ClearInputGroup(
  HANDLE  hSimConnect,
  SIMCONNECT_INPUT_GROUP_ID  GroupID
);

Paramètres

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.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Exemple

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

Remarques

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

Voir aussi


SimConnect_ClearNotificationGroup

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

Syntaxe

HRESULT SimConnect_ClearNotificationGroup(
  HANDLE  hSimConnect,
  SIMCONNECT_NOTIFICATION_GROUP_ID  GroupID
);

Paramètres

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.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Exemple

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

hr = SimConnect_ClearNotificationGroup(hSimConnect, GROUP_1);

Remarques

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.

Voir aussi


SimConnect_Close

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

Syntaxe

HRESULT SimConnect_Close(
  HANDLE  hSimConnect
);

Paramètres

hSimConnect
  [in]  Handle to a SimConnect object.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué. This should only happen if a the hSimConnect parameter is erroneous.

Exemple

hr = SimConnect_Close(hSimConnect);

Echantillons fonctionnels

Primary samples

Open and Close

Windows Event

Reference samples
All of the other samples implement this function.

Remarques

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 explictiy in the client code.

Voir aussi



SimConnect_CreateClientData

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

Syntaxe

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

Paramètres

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.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Remarques

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.

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.

Voir aussi



SimConnect_FlightLoad

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

Syntaxe

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

Paramètres

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.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Remarques

Flight files can be opened using a text editor.

Voir aussi


SimConnect_FlightPlanLoad

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

Syntaxe

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

Paramètres

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.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Remarques

Les fichiers Plan de Vol peuvent être ouverts avec un éditeur de texte.

Voir aussi



SimConnect_FlightSave

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

Syntaxe

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

Paramètres

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.

szDescription
  [in]  Null-terminated string containing the text to enter in the Description field of the flight file.

Flags
  [in]  Unused.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Remarques

Flight files can be opened using a text editor.

Voir aussi


SimConnect_GetLastSentPacketID

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

Syntaxe

HRESULT SimConnect_GetLastSentPacketID(
  HANDLE  hSimConnect,
  DWORD*  pdwSendID
);

Paramètres

hSimConnect
  [in]  Handle to a SimConnect object.
pdwSendID
  [out]  Pointer to a double word containing the ID of the last sent packet.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Exemple

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

Echantillon fonctionnel

Primary sample

Tracking Errors

Remarques

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.

Voir aussi


SimConnect_GetNextDispatch

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

Syntaxe

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

Paramètres

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. 

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Exemple

SIMCONNECT_RECV* pData;
DWORD cbData;

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

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

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

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

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

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

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

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

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

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

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

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

Echantillon fonctionnel

Primary sample
No Callback

 

Remarques

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.

Voir aussi


SimConnect_MapClientDataNameToID

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

Syntaxe

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

Paramètres

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.
ClientDataID
  [in] A unique ID for the client data area, specified by the client.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

 

Remarques

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.

Voir aussi


SimConnect_MapClientEventToSimEvent

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

Syntaxe

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

Paramètres

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 SimConnect Name). If the event name includes one or more periods (such as "Client.Event" in the Exemple below) then they are custom events specified by the client, and will only be recognised 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.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Exemple

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

Echantillons fonctionnels

Primary samples

Client Event
Cockpit Camera
Joystick Input
Reserved Key
Send Event A
Send Event B
Send Event C
Set Data
Throttle Control
Tracking Errors

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

Remarques

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

Voir aussi

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.

Syntaxe

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

Paramètres

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 Exemple). See the Remarques and Exemple 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.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Exemple

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

Echantillons fonctionnels

Primary samples

Cockpit Camera

Input Event

Joystick Input

Throttle Control

Reference samples
Set Data

Remarques

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

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

Input Name Description Range of values
Button One of the joystick buttons, configured from 0. Not applicable
POV Point of view switch (often called the hat switch).

0 facing ahead
4500 forward right
9000 right
13500 rear right
18000 rear
22500 rear left
27000 left
31500 forward left

Slider The variable position slider on the joystick. The actual values returned can vary widely on the joystick, though the limits are 32K (pulled back to the limit) to -32K (maximum forward limit).
XAxis, YAxis or ZAxis Movement of the joystick in the X, Y, or Z directions. For most joysticks the movement is left or right for the XAxis and forward or backward for the YAxis, with no values for the ZAxis. The limits in the Y axis are 32K (pulled back) to -32K (pushed forward). The limits in the X axis are -32K (full left) to 32K (full right). Depending on the joystick though, the limits may be significantly less than these values.
RxAxis, RyAxis, or RzAxis Rotation of the joystick about the X, Y, or Z axis. For most joysticks there is only rotational movement around the Z axis, with no values for the X or Y axis. For the Z axis, the limits are -32K (rotated left to the maximum) to 32K (rotated right to the maximum). Again, actual limits depend on the joystick.

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

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

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

Voir aussi


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.

Syntaxe

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

Paramètres

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

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.
E_INVALIDARG A SimConnect section in the Simconnect.cfg file did not contain the config index requested in the parmaters.

Exemple

HRESULT hr;
HANDLE hSimConnect = NULL;

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

Echantillons fonctionnels

Primary samples

Open and Close

Windows Event

Reference samples
All of the other samples implement this function.

Remarques

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

Voir aussi


SimConnect_RemoveClientEvent

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

Syntaxe

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

Paramètres

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.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Exemple

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

hr = SimConnect_RemoveClientEvent(hSimConnect, GROUP_1, EVENT_2);

Remarques

Use this function to permanently remove the client event. There is no reliable procedure to temporarily turn off a client event.

Voir aussi


SimConnect_RemoveInputEvent

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

Syntaxe

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

Paramètres

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.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Exemple

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

Remarques

The input string definitions must match exactly, before anything is removed from the group definition. For Exemple, the string defintiions "A+B" and "a+B" do not match.

Voir aussi



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.

Syntaxe

HRESULT SimConnect_RequestClientData(
  HANDLE  hSimConnect,
  SIMCONNECT_CLIENT_DATA_ID  ClientDataID ,
  SIMCONNECT_DATA_REQUEST_ID  RequestID ,
  SIMCONNECT_CLIENT_DATA_DEFINITION_ID   DefineID,
  DWORD  dwReserved1 = SIMCONNECT_UNUSED,
  DWORD  dwReserved2 = SIMCONNECT_UNUSED
);

Paramètres

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.
dwReserved1
  [in, optional]  Reserved for future use.
dwReserved2
  [in, optional]  Reserved for future use.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Remarques

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.

Voir aussi



SimConnect_RequestDataOnSimObject

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

Syntaxe

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

Paramètres

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.
Period
  [in]  One member of the SIMCONNECT_PERIOD enumeration type, specifying how often the data is to be sent by the server and recieved 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.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Exemple

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

Echantillons fonctionnels

Primary samples

Tagged Data

Reference samples
Weather Station

Remarques

Changing the Period parameter or changing the content of a data definition has a higher performance cost than changing the origin, interval or limit Paramètres. So to termporarily 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 defintions, 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 uniques title strings, including those simply with different color schemes). An Exemple of requesting the aircraft title is in the Variable Strings working sample. See the Aircraft Configuration Files document for more details on titles.

Voir aussi


SimConnect_RequestDataOnSimObjectType

The SimConnect_RequestDataOnSimObjectType function is used to retrieve informtion about simulation objects of a given type that are within a specifed radius of the user's aircraft.

Syntaxe

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

Paramètres

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 then information on all relevant objects will be returned. 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 (200 Km).
type
  [in]  Specifies the type of object to receive information on. One member of the SIMCONNECT_SIMOBJECT_TYPE enumeration type.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Exemple

See SimConnect_AddToDataDefinition for an Exemple of when to use this function


Echantillons fonctionnels

Primary samples

Request Data

Variable Strings

Reference samples

 

Remarques

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.

 

Voir aussi


SimConnect_RequestNotificationGroup

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

Syntaxe

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

Paramètres

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.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Remarques

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.

Voir aussi


SimConnect_RequestReservedKey

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

Syntaxe

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

Paramètres

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 Paramètres.

szKeyChoice2
  [in, optional]  Null-terminated string containing the second key choice.
szKeyChoice3
  [in, optional]  Null-terminated string containing the third key choice.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Echantillon fonctionnel

Primary sample

Reserved Key

Remarques

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 Paramètres 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.

Voir aussi


SimConnect_RequestSystemState

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

Syntaxe

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

Paramètres

hSimConnect
  Handle to a SimConnect object.
RequestID
  The client defined request ID.
szState
  A null-terminated string identifying the system function. One from the following table:

String Description
AircraftLoaded Requests the full path name of the last loaded aircraft flight dynamics file. These files have a .AIR extension.
DialogMode Requests whether the simulation is in Dialog mode or not. See SimConnect_SetSystemState for a description of Dialog mode.
FlightLoaded Requests the full path name of the last loaded flight. Flight files have the extension .FLT.
FlightPlan Requests the full path name of the active flight plan. An empty string will be returned if there is no active flight plan.
Sim Requests the state of the simulation. If 1 is returned, the user is in control of the aircraft, if 0 is returned, the user is navigating the UI. This is the same state that notifications can be subscribed to with the "SimStart" and "SimStop" string with the SimConnect_SubscribeToSystemEvent function.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Remarques

The information requested will be returned in a SIMCONNECT_RECV_SYSTEM_STATE structure.

Voir aussi


SimConnect_SetClientData

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

Syntaxe

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

Paramètres

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.
dwReserved
  [in]  Reserved for future use. Set to zero.
ArrayCount
  [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.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Remarques

A data definition must be specified, using the SimConnect_AddToClientDataDefinition function, before data can be set.

Voir aussi


SimConnect_SetDataOnSimObject

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

Syntaxe

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

Paramètres

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.
Flags
  [in]  Null, or one or more of the following flags.

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


ArrayCount
  [in]  Specifies the number of elements in the data array. A count of zero is interpreted as one element.
cbUnitSize
  [in]  Specifies the size of each element in the data array in bytes.

pDataSet
  [in]  Pointer to the data array.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Exemple

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

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

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

Echantillons fonctionnels

Primary samples

Set Data

Throttle Control

 

Reference samples
AI Objects and Waypoints

Remarques

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.

Voir aussi


SimConnect_SetInputGroupPriority

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

Syntaxe

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

Paramètres

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.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Exemple

hr=SimConnect_SetInputGroupPriority(hSimConnect,INPUT0,SIMCONNECT_GROUP_PRIORITY_HIGHEST);

Echantillons fonctionnels

Primary samples

Input Event

Joystick Input

 

 

Remarques

A priority setting must be made for all input groups, otherwise event notifications will not be sent by the SimConnect server.

Voir aussi


SimConnect_SetInputGroupState

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

Syntaxe

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

Paramètres

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.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Exemple

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

Echantillons fonctionnels

Primary samples

Input Event
Joystick Input
Throttle Control

Reference samples
Set Data

Remarques

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.

Voir aussi


SimConnect_SetNotificationGroupPriority

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

Syntaxe

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

Paramètres

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.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Exemple

hr=SimConnect_SetNotificationGroupPriority(hSimConnect,GROUP0,SIMCONNECT_GROUP_PRIORITY_HIGHEST);

Echantillons fonctionnels

Primary samples

Client Event
Send Event A
Send Event B
Send Event C
Tracking Errors

Remarques

SimConnect Priorities
SimConnect constants define the following priorities:
Priority Value Description
SIMCONNECT_GROUP_PRIORITY_HIGHEST 1 The highest priority.
SIMCONNECT_GROUP_PRIORITY_HIGHEST_MASKABLE 10000000 The hightest priority that allows events to be masked.
SIMCONNECT_GROUP_PRIORITY_STANDARD 1900000000 The standard priority.
SIMCONNECT_GROUP_PRIORITY_DEFAULT 2000000000 The default priority.
SIMCONNECT_GROUP_PRIORITY_LOWEST 4000000000 Priorities lower than this will be ignored.

Each notifiction 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 recieved 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 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 fucntionality in this case. Another use of masking is with co-operative clients, where there are multiple versions (perhaps a delux and standard version, or later and earlier versions), where the delux 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.

Voir aussi


SimConnect_SetSystemEventState

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

Syntaxe

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

Paramètres

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

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Exemple

See the Exemple and Echantillons fonctionnels for SimConnect_SubscribeToSystemEvent.

Remarques

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.

Voir aussi


SimConnect_SetSystemState

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

Syntaxe

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

Paramètres

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

String Description
DialogMode

The dwInteger parameter should be set to 1 to turn Dialog mode on, or 0 to turn it off. Dialog mode enables the display of dialogs when the simulation is running in Full Screen mode. When in dialog mode the 3D area of the screen will turn black, and will only revert to the simulation view when Dialog mode is turned off (not automatically when the dialog is closed). See the Echantillon fonctionnelfor a simple Exemple.

It is safe to set and reset Dialog mode when the simulation is being run in Windows mode.

FlightLoaded The szString parameter should contain the full path name of a flight. This will result in that flight, if it exists, being loaded. Flight files have the extension .FLT.
Sim It is not possible to set this state, so entering this will result in an exception being returned.

dwInteger
  An integer value, set depending on the value of szState (not currently used).

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.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Echantillons fonctionnels

Primary samples

DialogBoxMode

Remarques

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.

Voir aussi


SimConnect_SubscribeToSystemEvent

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

Syntaxe

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

Paramètres

hSimConnect
  [in]  Handle to a SimConnect object.
EventID
  [in]  Specifies the client-defined event ID.
SystemEventName
  [in]  The string name for the requested system event, which should be one from the following table (note that the event names are not case-sensitive). Unless otherwise stated in the Description, notifications of the event are returned in a SIMCONNECT_RECV_EVENT structure (identify the event from the EventID given with this function).

System Event Name
Description
General events
 
1sec Request a notification every second.
4sec Request a notification every four seconds.
6Hz Request notifications six times per second. This is the same rate that joystick movement events are transmitted.
AircraftLoaded Request a notification when the aircraft flight dynamics file is changed. These files have a .AIR extension. The filename is returned in a SIMCONNECT_RECV_EVENT_FILENAME structure.
Crashed Request a notification if the user aircraft crashes.
CrashReset Request a notification when the crash cut-scene has completed.
FlightLoaded Request a notification when a flight is loaded. Note that when a flight is ended, a default flight is typically loaded, so these events will occur when flights and missions are started and finished. The filename of the flight loaded is returned in a SIMCONNECT_RECV_EVENT_FILENAME structure.
FlightSaved Request a notification when a flight is saved correctly. The filename of the flight saved is returned in a SIMCONNECT_RECV_EVENT_FILENAME structure.
FlightPlanActivated Request a notification when a new flight plan is activated. The filename of the activated flight plan is returned in a SIMCONNECT_RECV_EVENT_FILENAME structure.
FlightPlanDeactivated Request a notification when the active flight plan is de-activated.
Frame Request notifications every visual frame. Information is returned in a SIMCONNECT_RECV_EVENT_FRAME structure.
Pause Request notifications when the flight is paused or unpaused, and also immediately returns the current pause state (1 = paused or 0 = unpaused). The state is returned in the dwData parameter.
Paused Request a notification when the flight is paused.
PauseFrame Request notifications for every visual frame that the simulation is paused. Information is returned in a SIMCONNECT_RECV_EVENT_FRAME structure.
PositionChanged Request a notification when the user changes the position of their aicraft through a dialog.
Sim Request notifications when the flight is running or not, and also immediately returns the current state (1 = running or 0 = not running). The state is returned in the dwData parameter.
SimStart The simulator is running. Typically the user is actively controlling the aircraft on the ground or in the air.
SimStop The simulator is not running. Typically the user is loading a flight, navigating the shell or in a dialog.
Sound Requests a notification when the master sound switch is changed. This request will also return the current state of the master sound switch immediately. A flag is returned in the dwData parameter, 0 if the switch is off, SIMCONNECT_SOUND_SYSTEM_EVENT_DATA_MASTER (0x1) if the switch is on.
Unpaused Request a notification when the flight is un-paused.
View

Requests a notification when the user aircraft view is changed. This request will also return the current view immediately. A flag is returned in the dwData parameter, one of:

SIMCONNECT_VIEW_SYSTEM_EVENT_DATA_COCKPIT_2D

SIMCONNECT_VIEW_SYSTEM_EVENT_DATA_COCKPIT_VIRTUAL

SIMCONNECT_VIEW_SYSTEM_EVENT_DATA_ORTHOGONAL (the map view).

WeatherModeChanged Request a notification when the weather mode is changed.
AI Specific events
 
ObjectAdded Request a notification when an AI object is added to the simulation. Refer also to the SIMCONNECT_RECV_EVENT_OBJECT_ADDREMOVE structure.
ObjectRemoved Request a notification when an AI object is removed from the simulation. Refer also to the SIMCONNECT_RECV_EVENT_OBJECT_ADDREMOVE structure.
Mission Specific events
 
MissionCompleted Request a notification when the user has completed a mission. Refer also to the SIMCONNECT_MISSION_END enum.
CustomMissionActionExecuted Request a notification when a mission action has been executed. Refer also to the SimConnect_CompleteCustomMissionAction function.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Exemple

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

Echantillons fonctionnels

Primary samples

Mission Action

System Event

Reference samples
Many of the other samples implement this function.

 

Remarques

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

Voir aussi


SimConnect_TransmitClientEvent

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

Syntaxe

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

Paramètres

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 Paramètres 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 messasge 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 behaviour is set by the SIMCONNECT_EVENT_FLAG_GROUPID_IS_PRIORITY flag, described below.
Flags
  [in] One or more of the following flags:

Flag Description
0 Do nothing.
SIMCONNECT_EVENT_FLAG_SLOW_REPEAT_TIMER The flag will effectively reset the repeat timer to simulate slow repeat. Use this flag to reset the repeat timer that works with various keyboard events and mouse clicks.
SIMCONNECT_EVENT_FLAG_FAST_REPEAT_TIMER The flag will effectively reset the repeat timer to simulate fast repeat.
SIMCONNECT_EVENT_FLAG_GROUPID_IS_PRIORITY
 Indicates to the SimConnect server to treat the GroupID as a priority value. If this parameter is set to SIMCONNECT_GROUP_PRIORITY_HIGHEST then all client notification groups that have subscribed to the event will receive the notification (unless one of them masks it). The event will be transmitted to clients starting at the given priority, though this can result in the client that transmitted the event, receiving it again.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Exemples


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

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

Echantillon fonctionnel

Primary sample

Send Event A

 

Remarques

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.

Voir aussi


SimConnect_UnsubscribeFromSystemEvent

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

Syntaxe

HRESULT SimConnect_UnsubscribeFromSystemEvent(
  HANDLE  hSimConnect,
  SIMCONNECT_CLIENT_EVENT_ID  EventID
);

Paramètres

hSimConnect
  [in]  Handle to a SimConnect object.
EventID
  [in]  Specifies the client-defined event ID.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Exemple

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

Remarques

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.

Voir aussi

Helper Functions

SimConnect_InsertString

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

Syntaxe

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

Paramètres

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.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Remarques

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.

Voir aussi


SimConnect_RequestResponseTimes

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

Syntaxe

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

Paramètres

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.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Exemple

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

Remarques

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.

Voir aussi


SimConnect_RetrieveString

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

Syntaxe

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

Paramètres

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.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Exemple

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

Echantillon fonctionnel

Primary sample

Variable Strings

 

Remarques

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.

Voir aussi

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.

Syntaxe

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

Paramètres

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 Configuation Files document): for Exemple: 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 Exemple, 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.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

 

Echantillon fonctionnel

Primary sample

AI Traffic

Remarques

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 helicopte, 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 Exemple 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.

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

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

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

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

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

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

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

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

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

 

Voir aussi


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

Syntaxe

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

Paramètres

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 Configuation Files document): for Exemple: 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.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

 

Echantillon fonctionnel

Primary sample
AI Objects and Waypoints

Remarques

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 Remarques for SimConnect_AICreateEnrouteATCAircraft.

Voir aussi



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.

Syntaxe

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

Paramètres

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 Configuation Files document): for Exemple: 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 Exemple, KSEA for SeaTac International.
RequestID
  [in]  Specifies the client defined request ID.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

 

Echantillon fonctionnel

Primary sample

AI Traffic

Remarques

Calling this function is no guarrantee 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. Refer to the Remarques for SimConnect_AICreateEnrouteATCAircraft.

Voir aussi



SimConnect_AICreateSimulatedObject

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

Syntaxe

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

Paramètres

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

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

title=Flour_bomb_floating_dock

title=CaspianSeaMonster

title=HumpbackWhale

 

InitPos
  [in]  Specifies the initaial position, using a SIMCONNECT_DATA_INITPOSITION structure.
RequestID
  [in]  Specifies the client defined request ID.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

 

Echantillon fonctionnel

Primary sample
AI Objects and Waypoints

Remarques

This function can be used to create a stationary aircraft (such as an unflyable aircraft on display outside a flight museaum), 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).

Voir aussi

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.

Syntaxe

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

Paramètres

hSimConnect
  [in]  Handle to a SimConnect object.
ObjectID
  [in]  Specifies the server defined object ID.
RequestID
  [in]  Specifies the client defined request ID.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

 

Remarques

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.

 

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.

Voir aussi


SimConnect_AIRemoveObject

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

Syntaxe

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

Paramètres

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.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

 

Remarques

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

Voir aussi



SimConnect_AISetAircraftFlightPlan

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

Syntaxe

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

Paramètres

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.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

 

Echantillon fonctionnel

Primary sample

AI Traffic

Remarques

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.

Voir aussi



Camera Specific Functions

SimConnect_CameraSetRelative6DOF

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

Syntaxe

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

Paramètres

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

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

 

Echantillon fonctionnel

Primary sample

Cockpit Camera

 

Remarques

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

Voir aussi

Menu Specific Functions

SimConnect_MenuAddItem

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

Syntaxe

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

Paramètres

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, that is to be transmitted when the menu item is selected (in the uEventID parameter of the SIMCONNECT_RECV_EVENT sturcture).
dwData
  [in]  Double word containing a data value that the client can specifiy for its own use (it will be returned in the dwData parameter of the SIMCONNECT_RECV_EVENT structure.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

 

Echantillon fonctionnel

Primary sample

Menu Items

Remarques

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.

Voir aussi


SimConnect_MenuAddSubItem

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

Syntaxe

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

Paramètres

hSimConnect
  [in]  Handle to a SimConnect object.
EventID
  [in]  Specifies the client defined menu event ID. This is the ID of the menu item that this item should be added to..
szMenuItem
  [in]  Null-terminated string containing the text for the sub-menu item.
EventID
  [in]  Specifies the client defined sub-menu event ID, that is to be transmitted when the sub-menu item is selected (in the uEventID parameter of the SIMCONNECT_RECV_EVENT sturcture). This ID must be unique across all sub-menu items for the client.
dwData
  [in]  Double word containing a data value that the client can specifiy for its own use (it will be returned in the dwData parameter of the SIMCONNECT_RECV_EVENT structure.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

 

Remarques

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.

Voir aussi



SimConnect_MenuDeleteItem

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

Syntaxe

HRESULT SimConnect_MenuDeleteItem(
  HANDLE  hSimConnect,
  const SIMCONNECT_CLIENT_EVENT_ID  MenuEventID
);

Paramètres

hSimConnect
  [in]  Handle to a SimConnect object.
MenuEventID
  [in]  Specifies the client defined event ID.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

 

Echantillon fonctionnel

Primary sample

Menu Items

Remarques

Menu items should be removed before a client closes. Removing the main menu item will remove any associated sub-menu items. Also see the Remarques for SimConnect_MenuAddItem.

Voir aussi



SimConnect_MenuDeleteSubItem

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

Syntaxe

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

Paramètres

hSimConnect
  [in] Handle to a SimConnect object.
MenuEventID
   [in] Specifies the client defined menu event ID, from which the sub-menu item is to be removed.
SubMenuEventID
   [in] Specifies the client defined sub-menu event ID.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

 

Remarques

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

Voir aussi


Mission Specific Functions

SimConnect_CompleteCustomMissionAction

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

Syntaxe

HRESULT SimConnect_CompleteCustomMissionAction(
  HANDLE  hSimConnect,
  const GUID  guidInstanceId
);

Paramètres

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.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

 

Echantillon fonctionnel

Primary sample
Mission Action

Remarques

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:

<SimMission.CustomAction InstanceId="{GUID }">
<PayLoadString>Any string goes here!</PayLoadString>
<WaitForCompletion>True</WaitForCompletion>
</SimMission.CustomAction>

Custom actions provide a mechanism to add complex processing to the basically data-driven mission system 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, WaifForCompletion 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 Echantillon fonctionnelshows 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".

Voir aussi


SimConnect_ExecuteMissionAction

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

Syntaxe

HRESULT SimConnect_ExecuteMissionAction(
  HANDLE  hSimConnect,
  const GUID  guidInstanceId
);

Paramètres

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.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

 

Echantillon fonctionnel

Primary sample
Mission Action

Remarques

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 Exemple) that are defined within the xml file.

 

See the Remarques forSimConnect_CompleteCustomMissionAction.

Voir aussi


Weather Specifc Functions


SimConnect_WeatherCreateStation

The SimConnect_WeatherCreateStation function creates a weather station at the given ICAO location.

Syntaxe

HRESULT SimConnect_WeatherCreateStation(
  HANDLE  hSimConnect,
  SIMCONNECT_DATA_REQUEST_ID  RequestID ,
  const char*  szICAO,
  const char*  szName,
  float  lat,
  float  lon,
  float  alt
);

Paramètres

hSimConnect
  [in]  Handle to a SimConnect object.

RequestID
  [in]  Specifies the client defined request ID.
szICAO
  [in]  Specifies the ICAO string. This can be an existing airport ICAO string, as long as the airport does not already have a weather station, or it can be a unique new ICAO code to be used just for the purposes of this weather station.
szName
  [in]  Specifies a descriptive name for the new weather station. This name will appear on the weather map in the weather dialogs of Flight Simulator.
lat
  [in]  Specifies the latitude of the station in degrees. The latitude, longitude and altitude Paramètres should be set to 0 if the ICAO code supplied is from an existing airport.
lon
  [in]  Specifies the longitude of the station in degrees.
alt
  [in]  Specifies the altitude of the station in feet, above ground level.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

 

Remarques

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.

Voir aussi

SimConnect_WeatherCreateThermal

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

Syntaxe

HRESULT SimConnect_WeatherCreateThermal(
  HANDLE  hSimConnect,
  SIMCONNECT_DATA_REQUEST_ID  RequestID ,
  float  lat,
  float  lon,
  float  alt,
  float  radius,
  float  height,
  float  coreRate = 3.0f,
  float  coreTurbulence = 0.05f,
  float  sinkRate = 3.0f,
  float  sinkTurbulence = 0.2f,
  float  coreSize = 0.4f,
  float  coreTransitionSize = 0.1f,
  float  sinkLayerSize = 0.4f,
  float  sinkTransitionSize = 0.1f
);

Paramètres

hSimConnect
  [in]  Handle to a SimConnect object.
RequestID
  [in]  Specifies the client defined request ID.
lat
  [in]  Specifies the latitude of the thermal in degrees.
lon
  [in]  Specifies the longitude of the thermal in degrees.
alt
  [in]  Specifies the altitude of the thermal in feet, above ground level.
radius
  [in]  Specifies the radius of the thermal, in meters. The maximum radius of a thermal is 100Km.
height
  [in]  Specifies the height of the thermal, in meters.
coreRate
  [in, optional]  Specifies the lift value, in meters per second, within the Core layer. A positive value will provide an updraft, a negative value a downdraft. The maximum rate is 1000 meters/second. Refer to the diagram in the Remarques section.
coreTurbulence
  [in, optional]  Specifies a variation in meters per second that is applied to the coreRate. For Exemple, if a value of 1.5 is entered, and the core rate is 5 m/s, the actual core rate applied will be randomly varying between 3.5 m/s and 6.5 m/s.
sinkRate
  [in, optional]  Specifies the lift value, in meters per second, within the Sink layer. A positive value will provide an updraft, a negative value a downdraft. The maximum rate is 1000 meters/second. Refer to the diagram in the Remarques section.
coreTurbulence
  [in, optional]  Specifies a variation in meters per second that is applied to the sinkRate. For Exemple, if a value of 1.5 is entered, and the sink rate is 5 m/s, the actual sink rate applied will be randomly varying between 3.5 m/s and 6.5 m/s.
coreSize
  [in, optional]  Specifies the radius in meters of the Core of the thermal.
coreTransitionSize
  [in, optional]  Specifies the width in meters of the transition layer between the Core and the Sink of the thermal. Half of the width of this transition will be outside the Core, and half within.
sinkSize
  [in, optional]  Specifies the radius in meters of the Sink of the thermal.
sinkTransitionSize
  [in, optional]  Specifies the width in meters of the transition layer between the Sink and the atmosphere outside of the thermal. Half of the width of this transition will be outside the radius of the Sink layer, and half within.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

 

Remarques

There is no limit to the number of thermals that can be created. Within the simulator a thermal is defined as a cylinder with a Core layer and a Sink layer:

 Refer also to the Weather Systems documentation.

Voir aussi

SimConnect_WeatherRemoveStation

The SimConnect_WeatherRemoveStation function requests that the weather station identified by the given ICAO string is removed.

Syntaxe

HRESULT SimConnect_WeatherRemoveStation(
  HANDLE  hSimConnect,
  SIMCONNECT_DATA_REQUEST_ID  RequestID ,
  const char*  szICAO
);

Paramètres

hSimConnect
  [in]  Handle to a SimConnect object.

RequestID
  [in]  Specifies the client defined request ID.
szICAO
  [in]  Specifies the ICAO string of the station to remove. The station must be one that was created by the same SimConnect client.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

 

Remarques

If a call is made to remove a weather station created by another client, or an exiting one within Flight Simulator, the error SIMCONNECT_EXCEPTION_WEATHER_UNABLE_TO_REMOVE_STATION will be returned.

 

If the client is closed, then all weather stations created by the client will be removed.

Voir aussi



SimConnect_WeatherRemoveThermal

The SimConnect_WeatherRemoveThermal function removes a thermal.

Syntaxe

HRESULT SimConnect_WeatherRemoveThermal(
  HANDLE  hSimConnect,
  SIMCONNECT_OBJECT_ID  ObjectID
);

Paramètres

hSimConnect
  [in]  Handle to a SimConnect object.
ObjectID
  [in]  Specifies the object ID of the thermal to be removed.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

 

Remarques

A client application can only remove thermals that it created, and not thermals created by other clients or by Flight Simulator. If the client is closed, then all thermals created by the client will be removed.

Voir aussi


SimConnect_WeatherRequestCloudState

The SimConnect_WeatherRequestCloudState function requests cloud density information on a given area.

Syntaxe

HRESULT SimConnect_WeatherRequestCloudState(
  HANDLE  hSimConnect,
  SIMCONNECT_DATA_REQUEST_ID  RequestID ,
  float  minLat,
  float  minLon,
  float  minAlt,
  float  maxLat,
  float  maxLon,
  float  maxAlt,
  DWORD  dwFlags = 0
);

Paramètres

hSimConnect
  [in]  Handle to a SimConnect object.
RequestID
  [in]  Specifies the client-defined request ID.
minLat
  [in]  Specifies the minimum latitude of the required area. This should simply be the lower of the two latitude numbers.
minLon
  [in]  Specifies the minimum longitude of the required area. This should simply be the lower of the two longitude numbers.
minAlt
  [in]  Specifies the minimum altitude of the required area, in feet.
maxLat
  [in]  Specifies the maximum latitude of the required area.
maxLon
  [in]  Specifies the maximum longitude of the required area.
maxAlt
  [in]  Specifies the maximum altitude of the required area, in feet.
dwFlags
  [in, optional]  Double word containing any flags. Reserved for future use.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

 

Remarques

The main purpose of this function is to enable weather radar.

If the call is successful, the cloud state information will be returned in a SIMCONNECT_RECV_CLOUD_STATE structure. This structure will contain a two dimensional array of byte data. The array will be 64 x 64 bytes in size, and each byte will contain a value indicating the cloud density for each cell. A value of zero would mean no clouds, to a maximum of 255. The area defined in this call is divided into 64 by 64 cells, so the size of each cell will be determined by the values given for the Paramètres above. Note that the entire World's weather is not simulated all the time, but only a region around the user aircraf, with a radius of approximately 128 kilometers, is modeled at any one time. A request for cloud data outside this region will simply return zeros.

The defined area can cross the Equator or the Greenwich Meridian, but it cannot cross the Poles or the International Date Line.

Voir aussi



SimConnect_WeatherRequestInterpolatedObservation

The SimConnect_WeatherRequestInterpolatedObservation function is used to send a request for weather data that is interpolated from the weather at the nearest three weather stations.

Syntaxe

HRESULT SimConnect_WeatherRequestInterpolatedObservation(
  HANDLE  hSimConnect,
  SIMCONNECT_DATA_REQUEST_ID  RequestID ,
  float  lat,
  float  lon,
  float  alt
);

Paramètres

hSimConnect
  [in]  Handle to a SimConnect object.
RequestID
  [in]  Specifies the ID of the client defined request. This is used later by the client to identify which data has been received.
lat
  [in]  Specifies latitude in degrees.
lon
  [in]  Specifies longitude in degrees.

alt
  [in]  Specifies altitude in feet above sea level. This differs from most weather data altitudes, which are feet above ground level.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

 

Exemple

DWORD dwRequestID = 1000;
hr = SimConnect_WeatherRequestInterpolatedObservation(hSimConnect, dwRequestID, -80.0, 44.0, 10000);

Remarques

The weather data will be returned in a SIMCONNECT_RECV_WEATHER_OBSERVATION structure. A number of errors apply specifically to weather data, see the SIMCONNECT_RECV_EXCEPTION enumeration.

Interpolated weather data can be used to identify suitable locations for thermals and other local weather systems. The process of using the three nearest stations is not without its drawbacks, as all three stations could be in one direction of the specified point, and not a reasonable spread in different directions. Weather data is returned in Metar data format.

Voir aussi


SimConnect_WeatherRequestObservationAtNearestStation

The SimConnect_WeatherRequestObservationAtNearestStation function is used to send a request for the weather data from the weather station nearest to the specified lat/lon position.

Syntaxe

HRESULT SimConnect_WeatherRequestObservationAtNearestStation(
  HANDLE  hSimConnect,
  SIMCONNECT_DATA_REQUEST_ID  RequestID ,
  float  lat,
  float  lon
);

Paramètres

hSimConnect
  [in]  Handle to a SimConnect object.
RequestID
  [in]  Specifies the ID of the client defined request. This is used later by the client to identify which data has been received.
lat
  [in]  Specifies latitude in degrees.
lon
  [in]  Specifies longitude in degrees.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

 

Exemple

DWORD dwRequestID = 1000;
hr = SimConnect_WeatherRequestObservationAtNearestStation(hSimConnect, dwRequestID, -80.0, 44.0);

Echantillon fonctionnel

Primary sample
Weather Station

Remarques

The weather data will be returned in a SIMCONNECT_RECV_WEATHER_OBSERVATION structure. A number of errors apply specifically to weather data, see the SIMCONNECT_RECV_EXCEPTION enumeration. Weather data is returned in Metar data format.

Voir aussi


SimConnect_WeatherRequestObservationAtStation

The SimConnect_WeatherRequestObservationAtStation function requests the weather data from a weather station identified by its ICAO code.

Syntaxe

HRESULT SimConnect_WeatherRequestObservationAtStation(
  HANDLE  hSimConnect,
  SIMCONNECT_DATA_REQUEST_ID  RequestID ,
  const char*  szICAO
);

Paramètres

hSimConnect
  [in]  Handle to a SimConnect object.
RequestID
  [in]  Specifies the ID of the client defined request. This is used later by the client to identify which data has been received.
szICAO[4]
  [in]  Null-terminated string specifyin the ICAO identification code of the weather station. Typically this is an airport. Set to GLOB to retrieve global weather.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

 

Exemple

DWORD dwRequestID = 1000;
hr = SimConnect_WeatherRequestObservationAtStation(hSimConnect, dwRequestID, "ICAO");

Echantillon fonctionnel

See the Echantillon fonctionnelfor zzz.

Remarques

The weather data will be returned in a SIMCONNECT_RECV_WEATHER_OBSERVATION structure. A number of errors apply specifically to weather data, see the SIMCONNECT_RECV_EXCEPTION enumeration. Weather data is returned in Metar data format.

Voir aussi


SimConnect_WeatherSetDynamicUpdateRate

The SimConnect_WeatherSetDynamicUpdateRate function is used to set the rate at which cloud formations change.

Syntaxe

HRESULT SimConnect_WeatherSetDynamicUpdateRate(
  HANDLE  hSimConnect,
  DWORD  dwRate
);

Paramètres

hSimConnect
  [in]  Handle to a SimConnect object.
dwRate
  [in]  Double word containing the rate. A value of zero indicates that cloud formations do not change at all. Values between 1 and 5 indicate that cloud formations should change from 1 (the slowest) to 5 (the fastest). These settings match those than can be set through the dialogs of Flight Simulator X.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

 

Remarques

Aucune.

Voir aussi



SimConnect_WeatherSetModeCustom

LA fonction SimConnect_WeatherSetModeCustom fixe le mode de météo à "défini par l'utilisateur".

Syntaxe

HRESULT SimConnect_WeatherSetModeCustom(
  HANDLE  hSimConnect
);

Paramètres

hSimConnect
  [in]  Handle to a SimConnect object.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Remarques

L'appel de cette fonction fixe le mode météo à "défini par l'utilisateur" dans l'écran de dialogue de Flight Simulator X, de telle sorte que la météo spécifiée par l'utilisateur, quelle qu'elle soit, soit utilisée.

Voir aussi


SimConnect_WeatherSetModeGlobal

La fonction SimConnect_WeatherSetModeGlobal fixe le mode météo à global, de telle sorte que les données météo s'appliquent partout.

Syntaxe

HRESULT SimConnect_WeatherSetModeGlobal(
  HANDLE  hSimConnect
);

Paramètres

hSimConnect
  [in]  Handle to a SimConnect object.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

 

Remarques

Il n'y a pas de réglage équivalent dans l'écran de dialogue de Flight Simulator X.

Voir aussi



SimConnect_WeatherSetModeServer

The SimConnect_WeatherSetModeServer function is used to switch to a local server for weather observation data.

Syntaxe

HRESULT SimConnect_WeatherSetModeServer(
  HANDLE  hSimConnect,
  DWORD  dwPort,
  DWORD  dwSeconds
);

Paramètres

hSimConnect
  [in]  Handle to a SimConnect object.
dwPort
  [in]  Double word containing the port number of the weather server. Set this to zero to reset the weather to normal operation.
dwSeconds
  [in]  Double word containing the amount of time, in seconds, that should elapse between each update. There is a minimum of 60 seconds.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

Remarques

Appeler cette fonction définit le mode météo en "météo du monde réel" dans l'écran de dialogue Météo de Flight Simulator X. Le dialogue permet seulement deux choix de fréquence de mise à jour de la météo (aucun et toutes les 15 minutes). Par conséquent cet appel donne beaucoup plus de souplesse sur les taux de mise à jour. Le réglage du numéro de port permet d'utiliser un serveur local de météo, plutôt que celui par défaut.

Un certain nombre d'erreurs s'appliquent spécifiquement aux données météorologiques. Consultez l'énumération SIMCONNECT_RECV_EXCEPTION.

Voir aussi



SimConnect_WeatherSetModeTheme

The SimConnect_WeatherSetModeTheme function is used to set the weather to a particular theme.

Syntaxe

HRESULT SimConnect_WeatherSetModeTheme(
  HANDLE  hSimConnect,
  const char*  szThemeName
);

Paramètres

hSimConnect
  [in]  Handle to a SimConnect object.
szThemeName
  [in]  Null-terminated string containing the theme filename. The corresponding files should exist in the Microsoft Flight Simulator X/weather/themes folder. For Exemple, enter "grayrain" to set the same theme as if the user had selected Gray and Rainy from the Weather dialog.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

 

Remarques

Appeler cette fonction définit le mode météo à "thèmes météo" dans l'écran de dialogue météo de Flight Simulator X. Il y a trois fichiers associés à un thème météo dans Flight Simulator X, par exemple : grayrain.wt, grayrain.bmp et grayrain.wtb. Le fichier wt contient la description des Conditions en cours qui apparaîtra dans l'écran de dialogue, le fichier bmp contient l'image qui apparaîtra également dans la boîte de dialogue météo, et le fichier wtb contient les données dans un format de propriétés qui contient les informations météorologiques.

Voir aussi


SimConnect_WeatherSetObservation

The SimConnect_WeatherSetObservation function is used to set the weather at a specific weather station, identified from within the Metar data string.

Syntaxe

HRESULT SimConnect_WeatherSetObservation(
  HANDLE  hSimConnect,
  DWORD  Seconds,
  const char*  szMETAR
);

Paramètres

hSimConnect
  [in]  Handle to a SimConnect object.
Seconds
  [in]  Specifies the time in seconds that the current weather should merge into the new weather.

pszMETAR
  [in]  Null-terminated string containing the METAR data.

Valeurs retournées

La fonction renvoie un HRESULT. Les valeurs possibles incluent, entre autres, celles dans cette table :

Return value Description
S_OK La fonction a réussi
E_FAIL La fonction a échoué.

 

Remarques

A number of errors apply specifically to weather data, see the SIMCONNECT_RECV_EXCEPTION enumeration.

 

Metar Data Format

The data format used in Flight Simulator for setting and retrieving weather is a modification to the Metar standard. The standard format is open and is described on a number of websites. The Metar data used in Flight Simulator follows the following format. Note that each section is separated by a space, and that spaces cannot occur within a section (with one exception noted in the table). The sections must be in the correct order, though many are optional and need not be present.

Section
Format
Mulitple Entries

STATION ID

(has an extension)

CCCC - a three or four character station ID. For Exemple KORD for O'Hare airport in Chicago. The string GLOB can be used to set global weather data.

Flight Simulator extension:

Format is &ANNN

This gives the height of the weather station in meters. This information is returned with a get observation, but when setting this extension must not be present.

No
REPORT TYPE Either METAR or SPECI keywords. No
AUTO Optional AUTO keyword, for a fully automated report. No
COR Optional COR keyword, for a corrected report. No
DATETIME

One of the following four formats (the exact number of characters must be present):

HHMM
DDHHMM
HHMMZ
DDHHMMZ
 (all are UTC whether or not the Z is present).

Note that this parameter is ignored when setting weather data. When getting the data, if it was set originally by the user through a SimConnect client or the Weather dialog then the time that it was set to will be returned. If the data was retrieved from a weather server, then the time stamp given to it by the server will be returned.

No
NIL Optional NIL keyword, indicating that no weather report could be made. No
SURFACE WINDS (has an extension)

One of the following two formats:

DDDSSSUUU (steady)
DDDSSSGXXUUU (gusts)

where:
DDD = Direction (0-360 degrees, or VRB for variable)
SSS = Speed
XX = Gust speed
UUU = Units, one of:
KMH = Kilometers per hour
KT = Knots
MPS = Meters per second

  Flight Simulator extension follows the "&" character

Format of the extension is &DNNNNTS

where
NNNN is the depth in meters (default is 1000 feet or 305m)
T part is turbulence, one of:
N - None (default)
O or L - Light
M - Moderate
H - Heavy
S - Severe

S part is wind shear, one of:
G - Gradual (default)
M - Moderate
S - Steep
I - Instantaneous

The default extension would look like this: &D305NG

 No
WINDS ALOFT (this section is entirely an extension)

Normal Metar strings do not contain winds aloft, so this whole entry is an extension. Winds aloft can be entered in one of two formats, but do not use both. The first format is slightly more flexible than the second, and follows SURFACE WINDS, the second format is at the end of the metar string:

Format 1:

This repeats the surface wind data but instead of specifying a surface layer depth it specifies a base altitude. The extension format is &ANNNNTS. (note the A for altitude instead of D for depth). The format is otherwise the same as for surface winds, including the extension giving the depth, turbulence and windshear.

Format 2:

@@@ A T D S | A T D S | .....

where

A is altitude in 100s of feet (-1500 to 100000)
T is temperature in celcius (-250 to 100)
D is direction in degrees (0 to 360)
S is speed in knots (0 to 400)

Note that there can be more than one WINDS ALOFT entry, typically giving different wind strengths and the other data, for a range of altitudes.

Yes
MIN MAX WIND DIR XXXVYYY

XXX - start of heading range, in degrees
YYY - end of heading range, in degrees
 No
CAVOK Optional CAVOK keyword (meaning Ceiling and Visibility OK). It indicates that no clouds exist below 5,000 feet or below the highest minimum sector altitude, whichever is greater, and no cumulonimbus are present. Also the visibility is 10 kilometers or more and, no precipitation, thunderstorms, sandstorm, duststorm, shallow fog, or low drifting dust, sand or snow is occurring. No
VISIBILITY (has an extension)

Like winds aloft the visibility group can be repeated to describe multiple visibility layers. There is also an extension to the format to allow layer base and depth to be specified.

Use one of the following formats:

Statute Miles:

M1/4SM or <1/4SM (visibility is less that a quarter of a statute mile)
ISM (visibility is measured in an interger number of statue miles)
N/DSM (visibility is measured as a fraction of a statue mile)
I N/DSM (visibility is measured in a whole part and fraction of a statue mile)

where
I = Integer part
N = Numerator
D = Denominator

The minimum fraction that can be entered is 1/8. Note that this is the only exception where a space can occur (between the I and the N) within a section.

Kilometers: NNKM
 Meters: NNNND

where
D is directional variation, one of:
NDV - no directional variation
NE, NW, SE, SW, N, S, E, W - compass point
M meters - same as NDV

Flight Simulator extension:

Format is &BXXXX&DYYYY

XXXX - base of visibility layer in meters
YYYY - depth of visibility layer in meters

Yes
RUNWAY VISUAL RANGE

Use one of the following two formats:

RDD/VVVVFT
RDD/XXXXVYYYYFT

where
DD = Runway ID (1-6 characters)
VVVV = Visual range in feet. May have P (above maximum) or M (below minimum) prefix (following the slash).
XXXX = Varying minimum range in feet.
YYYY = Varying maximum range in feet.

Yes
PRESENT CONDITIONS

IDDPP

where:
I - Intensity or vicinity flag:. -, + or VC. - means light, + means severe, and VC means vicinity. The + and - can be combined with VC. Leave out a + or - to mean moderate.

For Exemple: +VCTSRA means severe thunderstorm with rain in the vicinity.

DD - Descriptor, one of:
MI shallow
PR partial
DC patches
DR low drifting
BL blowing
SH shower
TS thunderstorm
FZ freezing


PP - Phenomena, one of:
DZ drizzle
RA rain
SN snow
SG snow grains
IC ice crystals
PE ice pellets
GR hail
GS small hail/snow pellets
UP unknown

BR mist
FG fog
FU smoke
VA volcanic ash
DU dust
SA sand
HZ haze
PY spray

PO dust whirls
SQ squalls
FC funnel cloud/tornado/waterspout
SS sandstorm

DS duststorm

Yes
PARTIAL OBSCURATION

One of:

FEW///
SCT///
BKN///
FEW000
SCT000
BKN000

These mean few, scattered or broken clouds are obscuring the view.

No
SKY CONDITIONS (has an extension)

Note cloud heights are coded: If NNN is 999 the level is 100,000 feet, otherwise it is 100 x NNN in feet.

CCCNNN

Where NNN is the coded height, and CCC is one of::
CLR or SKC - sky clear
FEW - few clouds
SCT - scattered clouds
BKN - broken clouds
OVC - overcast

NTT - N/8ths cloud coverage of type TT, which is one of:
CI Cirrus
CS Cirro-stratus
CC Cirro-cumulus
AS Alto-stratus
AC Alto-cumulus
SC Strato-cumulus
NS Nimbo-stratus
ST Stratus
CU Cumulus
CB Cumulo-nimbus

Flight Simulator extension:

&TT000FTPQBBBI
where:
TT - Type, one of CU ( Cumulus ) or CB ( Cumulo-nimbus )
000 - Unused.
F - Top of cloud, one of: F (flat), R (round), A (anvil)
T - Turbulence, one of: N - None (default), O - Light, L - Light, M - Moderate, H - Heavy, S - Severe
P - Precipitation, one of: V (very light), L (light), M (moderate), H (heavy) D (dense)
Q - Type of precipitation, one of: N (none), R (rain), F (freezing rain), H (hail), S (snow)
BBB - Coded base height, the precipitation ends at this height, set to 0 for it to land on the ground
I - icing rate, one of: N (none), T (trace), L (light), M (moderate), S (severe)

 No

TEMPERATURE

(has an extension)

TT/DD

TT - temperature in Celsius
DD - dewpoint in Celsius  

Negative values should be preceded with an M.

Flight Simulator extension:

&ANNNNN - altitude of the temperatures in feet.

Yes
ALTIMITER

One of:
ANNNN - altimeter in degrees of mercury (for Exemple, A2992)
QNNNN - altimeter in millibars  

No
@@@ If these three characters are entered in the string, there is a WINDS ALOFT section following the metar string.  

 

Exemples of Metar strings
Metar String Description
KSEA 030405Z 27007KT 15SM SKC 17/13 A2992 KSEA = Station Identifier (Sea-Tac airport)
030405Z = Time (ddhhmmZ)
27007KT = Winds (270 degrees at 7 knots)
15SM = Visibility (15 statute miles)
SKC = Clear skies
17/13 = Temperature /Dewpoint in celsius
A2992 = Altimieter setting (29.92 in Hg)
KSEA 030405Z COR 27015KT 7SM +TSRA BKN055CB 30/17 A2974 Corrected report, same time as above, with 15 knot winds, 7 miles of visibility, severe thunderstorm and rain, broken cumulo-nimbus clouds at 5500 feet.

KSEA&A131 000000Z 00000KT&D985NG 100KM&B-581&D3048 2CU053&CU000FNMN-19N 15/05 Q1013 @@@ 65 15 270 20 | 196 15 270 25 |

Fair weather at Sea-Tac airport. Two eights cumulous clouds at 5300 feet, 20 knot West winds at 6500 feet, 25 knot West winds at 19600 feet.

 

Voir aussi

SimConnect Structures and Enumerations

SimConnect uses the following structures and enumerations.

Name Structure or Enumeration Description
SIMCONNECT_DATATYPE Enum Used with the SimConnect_AddToDataDefinition call to specify the data type that the server should use to return the specified data to the client.
SIMCONNECT_DATA_INITPOSITION Struct Used to initialize the position of a the user or AI controlled aircraft.
SIMCONNECT_DATA_LATLONALT Struct Used to hold a world position.
SIMCONNECT_DATA_MARKERSTATE Struct Used to help graphically link flight model data with the graphics model.
SIMCONNECT_DATA_WAYPOINT Struct Used to hold all the necessary information on a waypoint.
SIMCONNECT_DATA_XYZ Struct Used to hold a 3D co-ordinate.
SIMCONNECT_EXCEPTION Enum Used with the SIMCONNECT_RECV_EXCEPTIONstructure to return information on an error that has occured.
SIMCONNECT_MISSION_END Enum Used to specifiy the three possible outcomes of a mission.
SIMCONNECT_PERIOD Enum Used with the SimConnect_RequestDataOnSimObject call to specify how often data is to be sent to the client.
SIMCONNECT_RECV Struct Used with the SIMCONNECT_RECV_ID enumeration to indicate which type of structure has been returned.
SIMCONNECT_RECV_ASSIGNED_OBJECT_ID Struct Used to return an object ID that matches a request ID.
SIMCONNECT_RECV_CLIENT_DATA Struct Will be received by the client after a successful call to  SimConnect_RequestClientData. The structure is identical to SIMCONNECT_RECV_SIMOBJECT_DATA.
SIMCONNECT_RECV_CLOUD_STATE Struct Used to return an array of cloud state data.
SIMCONNECT_RECV_CUSTOM_ACTION Struct

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

SIMCONNECT_RECV_EVENT Struct Used to return an event ID to the client.
SIMCONNECT_RECV_EVENT_FILENAME Struct Used with the SimConnect_SubscribeToSystemEvent to return a filename and an event ID to the client.
SIMCONNECT_RECV_EVENT_FRAME Struct Used with the SimConnect_SubscribeToSystemEvent to return the frame rate and simulation speed to the client.
SIMCONNECT_RECV_EVENT_OBJECT_ADDREMOVE Struct

Used to return the type and ID of an AI object that has been added or removed from the simulation, by any client.

SIMCONNECT_RECV_EXCEPTION Struct Used with the SIMCONNECT_EXCEPTION enumeration type to return information on an error that has occured.
SIMCONNECT_RECV_ID Enum Used within the SIMCONNECT_RECVstructure to indicate which type of structure has been returned.
SIMCONNECT_RECV_OPEN Struct Used to return information to the client, after a successful call to SimConnect_Open.
SIMCONNECT_RECV_QUIT Struct This is an identical structure to the SIMCONNECT_RECV structure.
SIMCONNECT_RECV_RESERVED_KEY Struct sed with the SimConnect_RequestReservedKey function to return the reserved key combination.
SIMCONNECT_RECV_SIMOBJECT_DATA Struct Will be received by the client after a successful call to  SimConnect_RequestDataOnSimObject or SimConnect_RequestDataOnSimObjectType.
SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE Struct Will be received by the client after a successful call to  SimConnect_RequestDataOnSimObjectType. The structure is identical to SIMCONNECT_RECV_SIMOBJECT_DATA.
SIMCONNECT_RECV_SYSTEM_STATE Struct Used with the SimConnect_RequestSystemState function to retrieve specific Flight Simulator systems states and information.
SIMCONNECT_RECV_WEATHER_OBSERVATION Struct Used to return weather observation data, after calls to one of:
SimConnect_WeatherRequestInterpolatedObservation,
SimConnect_WeatherRequestObservationAtStation, or
SimConnect_WeatherRequestObservationAtNearestStation.
SIMCONNECT_SIMOBJECT_TYPE Enum Used with the SimConnect_RequestDataOnSimObjectType call to request information on specific or nearby objects.
SIMCONNECT_STATE Enum Used with the SimConnect_SetSystemEventState call to turn the reporting of events on and off.
SIMCONNECT_WAYPOINT_FLAGS Enum Used with the SIMCONNECT_DATA_WAYPOINT structure to define waypoints.


SIMCONNECT_DATATYPE

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

Syntaxe

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

  SIMCONNECT_DATATYPE_MAX
};

Members

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


SIMCONNECT_DATATYPE_STRING8,32,64,128,256,260

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

SIMCONNECT_DATATYPE_STRINGV
  Specifies a variable length string.


SIMCONNECT_DATATYPE_INITPOSITION
  Specifies the SIMCONNECT_DATA_INITPOSITION structure.


SIMCONNECT_DATATYPE_MARKERSTATE
  Specifies the SIMCONNECT_DATA_MARKERSTATE structure.


SIMCONNECT_DATATYPE_WAYPOINT
  Specifies the SIMCONNECT_DATA_WAYPOINT structure.


SIMCONNECT_DATATYPE_LATLONALT
  Specifies the SIMCONNECT_DATA_LATLONALT structure.


SIMCONNECT_DATATYPE_XYZ
  Specifies the SIMCONNECT_DATA_XYZ structure.

Echantillons fonctionnels

Primary samples

Request Data

Set Data

Tagged Data

Throttle Contol

Remarques

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

Voir aussi



SIMCONNECT_PERIOD

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

Syntaxe

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

Members

SIMCONNECT_PERIOD_NEVER
  Specifies that the data is not to be sent.


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


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


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


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

Echantillons fonctionnels

Primary samples

Tagged Data

Reference samples
Weather Station

Remarques

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

Voir aussi


SIMCONNECT_EXCEPTION

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

Syntaxe

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

};

Members

General errors

SIMCONNECT_EXCEPTION_NONE
  Specifies SIMCONNECT_EXCEPTION_NONE .


SIMCONNECT_EXCEPTION_ERROR
  Specifies SIMCONNECT_EXCEPTION_ERROR .


SIMCONNECT_EXCEPTION_SIZE_MISMATCH
  Specifies SIMCONNECT_EXCEPTION_SIZE_MISMATCH .


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


SIMCONNECT_EXCEPTION_UNOPENED
  Specifies SIMCONNECT_EXCEPTION_UNOPENED .


SIMCONNECT_EXCEPTION_VERSION_MISMATCH
  Specifies SIMCONNECT_EXCEPTION_VERSION_MISMATCH .


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


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


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


SIMCONNECT_EXCEPTION_EVENT_ID_DUPLICATE
  Specifies that the event ID has been used already.


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


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


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


SIMCONNECT_EXCEPTION_INVALID_DATA_TYPE
  Specifies that the data type requested does not apply to the type of data requested.


SIMCONNECT_EXCEPTION_INVALID_DATA_SIZE
  Specifies SIMCONNECT_EXCEPTION_INVALID_DATA_SIZE .


SIMCONNECT_EXCEPTION_DATA_ERROR
  Specifies SIMCONNECT_EXCEPTION_DATA_ERROR .


SIMCONNECT_EXCEPTION_INVALID_ARRAY
  Specifies SIMCONNECT_EXCEPTION_INVALID_ARRAY .


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


SIMCONNECT_EXCEPTION_INVALID_ENUM
  Specifies that the member of the enumeration provided was not valid.

 

SIMCONNECT_EXCEPTION_DEFINITION_ERROR
  Specifies that there is a problem with a data definition.

SIMCONNECT_EXCEPTION_DUPLICATE_ID
  Specifies that the ID has already been used.

SIMCONNECT_EXCEPTION_DATUM_ID
  Specifies that the datum ID is not recognized.

SIMCONNECT_EXCEPTION_OUT_OF_BOUNDS
  Specifies that the radius given in the SimConnect_RequestDataOnSimObjectType was outside the acceptable range.

Weather system errors

SIMCONNECT_EXCEPTION_WEATHER_INVALID_PORT
  Specifies an invalid port number was requested.


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


SIMCONNECT_EXCEPTION_WEATHER_UNABLE_TO_GET_OBSERVATION
  Specifies that the weather observation requested was not available.


SIMCONNECT_EXCEPTION_WEATHER_UNABLE_TO_CREATE_STATION
  Specifies that the weather station could not be created.


SIMCONNECT_EXCEPTION_WEATHER_UNABLE_TO_REMOVE_STATION
  Specifies that the weather station could not be removed.

 

AI errors

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

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


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


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

Echantillon fonctionnel

Primary sample

Tracking Errors

 

Remarques

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

Voir aussi



SIMCONNECT_MISSION_END

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

Syntaxe

enum SIMCONNECT_MISSION_END{
  SIMCONNECT_MISSION_FAILED,
  SIMCONNECT_MISSION_CRASHED,
  SIMCONNECT_MISSION_SUCCEEDED
};

Members

SIMCONNECT_MISSION_FAILED
  Specifies that the user did not complete the mission successfully

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


SIMCONNECT_MISSION_SUCCEEDED
  Specifies that the user completed the mission successfully.

Echantillon fonctionnel

Primary sample
Mission Action

Remarques

Refer to the mission events that can be requested by the SimConnect_SubscribeToSystemEvent function. Also see the Remarques forSimConnect_CompleteCustomMissionAction.

Voir aussi



SIMCONNECT_RECV

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

Syntaxe

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

Members

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

Echantillons fonctionnels

Primary samples

Client Event
No Callback
Tracking Errors

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

Remarques

This stucture is inherited directly by:

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

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

Voir aussi


SIMCONNECT_RECV_ASSIGNED_OBJECT_ID

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

Syntaxe

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

Members

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

Echantillons fonctionnels

Primary samples AI Objects and Waypoints
AI Traffic

Remarques

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

Voir aussi



SIMCONNECT_RECV_CLIENT_DATA

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

Syntaxe

struct SIMCONNECT_RECV_CLIENT_DATA : public SIMCONNECT_RECV_SIMBOBJECT_DATA{
};

Remarques

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

Voir aussi



SIMCONNECT_RECV_CLOUD_STATE

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

Syntaxe

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

Members

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

Echantillons fonctionnels

Primary samples

 

Remarques

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

Voir aussi



SIMCONNECT_RECV_CUSTOM_ACTION

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

Syntaxe

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

Members

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

Echantillon fonctionnel

Primary sample Mission Action

Remarques

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

 

See the Remarques forSimConnect_CompleteCustomMissionAction.

Voir aussi



SIMCONNECT_RECV_EVENT

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

Syntaxe

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

Members

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

Echantillons fonctionnels

Primary samples

Client Event
Cockpit Camera
Input Event
Joystick Input
Menu Items
No Callback
Send Event A
Send Event B
Send Event C
Throttle Control
Tracking Errors

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

Remarques

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

Voir aussi


SIMCONNECT_RECV_EVENT_FILENAME

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

Syntaxe

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

Members

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

Working Sample

Primary sample

System Event

Remarques

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

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

Voir aussi



SIMCONNECT_RECV_EVENT_FRAME

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

Syntaxe

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

Members

fFrameRate
  The visual frame rate in frames per second.

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

Remarques

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

Voir aussi



SIMCONNECT_RECV_EVENT_OBJECT_ADDREMOVE

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

Syntaxe

struct SIMCONNECT_RECV_EVENT_OBJECT_ADDREMOVE : public SIMCONNECT_RECV_EVENT {
  SIMCONNECT_SIMOBJECT_TYPE  eObjType;
};

Members

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

Echantillon fonctionnel

Primary sample

AI Traffic

Remarques

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

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

Voir aussi



SIMCONNECT_RECV_EXCEPTION

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

Syntaxe

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

Members

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

Echantillons fonctionnels

Primary samples

Cockpit Camera
Tracking Errors
Variable Strings

Remarques

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

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

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

Voir aussi



SIMCONNECT_RECV_ID

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

Syntaxe

enum SIMCONNECT_RECV_ID{
  SIMCONNECT_RECV_ID_NULL,
  SIMCONNECT_RECV_ID_EXCEPTION,
  SIMCONNECT_RECV_ID_OPEN,
  SIMCONNECT_RECV_ID_QUIT,
  SIMCONNECT_RECV_ID_EVENT,
  SIMCONNECT_RECV_ID_EVENT_OBJECT_ADDREMOVE,
  SIMCONNECT_RECV_ID_EVENT_FILENAME,
  SIMCONNECT_RECV_ID_EVENT_FRAME,
  SIMCONNECT_RECV_ID_SIMOBJECT_DATA,
  SIMCONNECT_RECV_ID_SIMOBJECT_DATA_BYTYPE,
  SIMCONNECT_RECV_ID_CLOUD_STATE,
  SIMCONNECT_RECV_ID_WEATHER_OBSERVATION,
  SIMCONNECT_RECV_ID_ASSIGNED_OJBECT_ID,
  SIMCONNECT_RECV_ID_RESERVED_KEY,
  SIMCONNECT_RECV_ID_CUSTOM_ACTION,
  SIMCONNECT_RECV_ID_SYSTEM_STATE,
  SIMCONNECT_RECV_ID_CLIENT_DATA,
};

Members

SIMCONNECT_RECV_ID_NULL
  Specifies that nothing useful has been returned.


SIMCONNECT_RECV_ID_EXCEPTION
  Specifies that a SIMCONNECT_RECV_EXCEPTION structure has been received.


SIMCONNECT_RECV_ID_OPEN
  Specifies that a SIMCONNECT_RECV_OPEN structure has been received.


SIMCONNECT_RECV_ID_QUIT
  Specifies that the user has exited from Flight Simulator.


SIMCONNECT_RECV_ID_EVENT
  Specifies that a SIMCONNECT_RECV_EVENT structure has been received.


SIMCONNECT_RECV_ID_EVENT_OBJECT_ADDREMOVE
  Specifies that a SIMCONNECT_RECV_EVENT_OBJECT_ADDREMOVE structure has been received.


SIMCONNECT_RECV_ID_EVENT_FILENAME
  Specifies that a  SIMCONNECT_RECV_EVENT_FILENAME structure has been received.


SIMCONNECT_RECV_ID_EVENT_FRAME
  Specifies that a  SIMCONNECT_RECV_EVENT_FRAME structure has been received.


SIMCONNECT_RECV_ID_SIMOBJECT_DATA
  Specifies that a SIMCONNECT_RECV_SIMOBJECT_DATA structrure has been received.


SIMCONNECT_RECV_ID_SIMOBJECT_DATA_BYTYPE
  Specifies that a SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE structure has been received.


SIMCONNECT_RECV_ID_WEATHER_OBSERVATION
  Specifies that a SIMCONNECT_RECV_WEATHER_OBSERVATION structure has been received.

 

SIMCONNECT_RECV_ID_CLOUD_STATE
  Specifies that a SIMCONNECT_RECV_CLOUD_STATE structure has been received.

 

SIMCONNECT_RECV_ID_ASSIGNED_OJBECT_ID
  Specifies that a SIMCONNECT_RECV_ASSIGNED_OBJECT_ID structure has been received.


SIMCONNECT_RECV_ID_RESERVED_KEY
  Specifies that a SIMCONNECT_RECV_RESERVED_KEY structure has been received.


SIMCONNECT_RECV_ID_CUSTOM_ACTION
  Specifies that a SIMCONNECT_RECV_CUSTOM_ACTION structure has been received.


SIMCONNECT_RECV_ID_SYSTEM_STATE
  Specifies that a SIMCONNECT_RECV_SYSTEM_STATE structure has been received.


SIMCONNECT_RECV_ID_CLIENT_DATA
  Specifies that a SIMCONNECT_RECV_CLIENT_DATA structure has been received.

Echantillons fonctionnels

Primary samples

Client Event
No Callback
Tracking Errors

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

Remarques

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

Voir aussi


SIMCONNECT_RECV_SIMOBJECT_DATA

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

Syntaxe

struct SIMCONNECT_RECV_SIMOBJECT_DATA : public SIMCONNECT_RECV {
  DWORD  dwRequestID;
  DWORD  dwObjectID;
  DWORD  dwDefineID;
  DWORD  dwFlags;
  DWORD  dwentrynumber;
  DWORD  dwoutof;
  DWORD  dwDefineCount;
  DWORD  dwData;
};

Members

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

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

Echantillons fonctionnels

Primary samples

Request Data
Set Data
Tagged Data
Throttle Control
Variable Strings

Remarques

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

Voir aussi

 

SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE

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

Syntaxe

struct SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE : public SIMCONNECT_RECV_SIMBOBJECT_DATA{
};

Remarques

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

Voir aussi



SIMCONNECT_RECV_OPEN

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

Syntaxe

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

Members

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

Remarques

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

Voir aussi



SIMCONNECT_RECV_RESERVED_KEY

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

Syntaxe

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

Members

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

Echantillon fonctionnel

Primary sample

Reserved Key

Remarques

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

Voir aussi



SIMCONNECT_RECV_SYSTEM_STATE

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

Syntaxe

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

Members

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

Remarques

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

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

Voir aussi


SIMCONNECT_RECV_WEATHER_OBSERVATION

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

Syntaxe

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

Members

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

Echantillon fonctionnel

Primary sample
Weather Station

Remarques

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

Voir aussi



SIMCONNECT_SIMOBJECT_TYPE

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

Syntaxe

enum SIMCONNECT_SIMOBJECT_TYPE{
  SIMCONNECT_SIMOBJECT_TYPE_USER,
  SIMCONNECT_SIMOBJECT_TYPE_ALL,
  SIMCONNECT_SIMOBJECT_TYPE_AIRCRAFT,
  SIMCONNECT_SIMOBJECT_TYPE_HELICOPTER,
  SIMCONNECT_SIMOBJECT_TYPE_BOAT,
  SIMCONNECT_SIMOBJECT_TYPE_GROUND
};

Members

SIMCONNECT_SIMOBJECT_TYPE_USER
  Specifies the user's aircraft.


SIMCONNECT_SIMOBJECT_TYPE_ALL
  Specifies all AI controlled objects.


SIMCONNECT_SIMOBJECT_TYPE_AIRCRAFT
  Specifies all aircraft.


SIMCONNECT_SIMOBJECT_TYPE_HELICOPTER
  Specifies all helicopters.


SIMCONNECT_SIMOBJECT_TYPE_BOAT
  Specifies all AI controlled boats.


SIMCONNECT_SIMOBJECT_TYPE_GROUND
  Specifies all AI controlled ground vehicles.

Echantillons fonctionnels

Primary samples

Request Data

Reference samples

Set Data
Tagged Data
Throttle Contol

 

Remarques

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

See the Remarques and Exemples for  SimConnect_AddToDataDefinition.

Voir aussi



SIMCONNECT_STATE

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

Syntaxe

enum SIMCONNECT_STATE{
  SIMCONNECT_STATE_OFF,
  SIMCONNECT_STATE_ON
};

Members

SIMCONNECT_STATE_OFF
  Specifies off.


SIMCONNECT_STATE_ON
  Specifies on.

Echantillons fonctionnels

Primary samples

Cockpit Camera
Input Event
Joystick Input
Throttle Control

Reference samples
Set Data

 

Remarques

See the Remarques for SimConnect_MapInputEventToClientEvent.

Voir aussi



SIMCONNECT_DATA_INITPOSITION

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

Syntaxe

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

Members

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

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

Echantillons fonctionnels

Primary samples

AI Objects and Waypoints

Set Data

Remarques

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

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

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

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

Voir aussi


SIMCONNECT_DATA_LATLONALT

The SIMCONNECT_DATA_LATLONALT structure is used to hold a world position.

Syntaxe

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

Members

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

Echantillon fonctionnel

Primary sample
 

Remarques

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

Voir aussi



SIMCONNECT_DATA_MARKERSTATE

The SIMCONNECT_DATA_MARKERSTATE structure is used to help graphically link flight model data with the graphics model.

Syntaxe

struct SIMCONNECT_DATA_MARKERSTATE{
  char  szMarkerName[64];
  DWORD  dwMarkerState;
};

Members

szMarkerName[64]
  Null-terminated string containing the marker name. One from the following table:

String
Cg
ModelCenter
Wheel
Skid
Ski
Float
Scrape
Engine
Prop
Eyepoint
LongScale
LatScale
VertScale
AeroCenter
WingApex
RefChord
Datum
WingTip
FuelTank
Forces

 

dwMarkerState
  Double word containing the marker state, set to 1 for on and 0 for off.

Remarques

The SimConnect_AddToDataDefinition call can be used to add a SIMCONNECT_DATA_MARKERSTATE structure to a data definition. Use of this call and structure is to help determine that points specified in the flight model of an aircraft match the graphics model for that aircraft, by turning on the specified marker lights. A SimConnect client created to do this becomes a tool to aid to the accurate development of aircraft models, rather than an add-on that an end user might run.

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

Voir aussi



SIMCONNECT_DATA_WAYPOINT

The SIMCONNECT_DATA_WAYPOINT structure is used to hold all the necessary information on a waypoint.

Syntaxe

struct SIMCONNECT_DATA_WAYPOINT{
  double  Latitude;
  double  Longitude;
  double  Altitude;
  unsigned long  Flags;
  double  ktsSpeed;
  double  percentThrottle;
};

Members

Latitude
   The latitude of the waypoint in degrees.
Longitude
   The longitude of the waypoint in degrees.
Altitude
   The altitude of the waypoint in feet.
Flags
  Specifies the flags set for this waypoint, see SIMCONNECT_WAYPOINT_FLAGS. These flags can be ORed together, for Exemple:
Flags = SIMCONNECT_WAYPOINT_ON_GROUND | SIMCONNECT_WAYPOINT_REVERSE;
ktsSpeed
   Specifies the required speed in knots. If a specific speed is required, then the SIMCONNECT_WAYPOINT_SPEED_REQUESTED flag must be set to True.
percentThrottle
  Specifies the required throttle as a percentage. If a specific throttle percentage is required, then the SIMCONNECT_THROTTLE_REQUESTED flag must be set to True.

Echantillon fonctionnel

Primary sample
AI Objects and Waypoints

Remarques

The SimConnect_AddToDataDefinition call can be used to add a SIMCONNECT_DATA_WAYPOINT structure to a data definition. A list of waypoints is sent to an AI object using the SimConnect_SetDataOnSimObject function. There is no limit to the number of waypoints that can be sent to an object. If just one waypoint is set, the SIMCONNECT_WAYPOINT_WRAP_TO_FIRST flag should not be used.

If a speed is requested at a waypoint, the slower that speed is the closer the object will approach the exact point of the waypoint, requests for high speeds can result in the AI system turning the object some way off of the waypoint. The pitch, bank and heading of objects controlled by the waypoint system are determined by the AI pilot, and cannot be set from a client.

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

Voir aussi



SIMCONNECT_DATA_XYZ

The SIMCONNECT_DATA_XYZ structure is used to hold a 3D co-ordinate.

Syntaxe

struct SIMCONNECT_DATA_XYZ{
  double  x;
  double  y;
  double  z;
};

Members

x
   The position along the x axis.
y
   The position along the y axis.
z
   The position along the z axis.

Echantillon fonctionnel

Primary sample  

Remarques

Voir aussi


SIMCONNECT_WAYPOINT_FLAGS

The SIMCONNECT_WAYPOINT_FLAGS enumeration type is used with the SIMCONNECT_DATA_WAYPOINT structure to define waypoints.

Syntaxe

enum SIMCONNECT_WAYPOINT_FLAGS{
  SIMCONNECT_WAYPOINT_SPEED_REQUESTED = 0x04,
  SIMCONNECT_WAYPOINT_THROTTLE_REQUESTED = 0x08,
  SIMCONNECT_WAYPOINT_COMPUTE_VERTICAL_SPEED = 0x10,
  SIMCONNECT_WAYPOINT_ALTITUDE_IS_AGL = 0x20,
  SIMCONNECT_WAYPOINT_ON_GROUND = 0x00100000,
  SIMCONNECT_WAYPOINT_REVERSE = 0x00200000,
  SIMCONNECT_WAYPOINT_WRAP_TO_FIRST = 0x00400000,
};

Members


SIMCONNECT_WAYPOINT_SPEED_REQUESTED
  Specifies requested speed is valid.


SIMCONNECT_WAYPOINT_THROTTLE_REQUESTED
  Specifies requested throttle percentage is valid.


SIMCONNECT_WAYPOINT_COMPUTE_VERTICAL_SPEED
  Specifies that the vertical should be calculated to reach the required speed when crossing the waypoint.


SIMCONNECT_WAYPOINT_ALTITUDE_IS_AGL
  Specifies the altitude specified is AGL (above ground level).


SIMCONNECT_WAYPOINT_ON_GROUND
  Specifies the waypoint should be on the ground. Make sure this flag is set if the aircraft is to taxi to this point.


SIMCONNECT_WAYPOINT_REVERSE
  Specifies that the aircraft should back up to this waypoint. This is only valid on the first waypoint.


SIMCONNECT_WAYPOINT_WRAP_TO_FIRST
  Specifies that the next waypoint is the first waypoint. This is only valid on the last waypoint.

Echantillon fonctionnel

Primary sample
AI Objects and Waypoints

Remarques

To set multiple waypoint flags simply OR them together. See the Remarques for the SIMCONNECT_DATA_WAYPOINT structure.

Voir aussi



Programming SimConnect Clients using C#

Version du disque FS X

There is a managed wrapper for SimConnect that enables .NET language programmers to write SimConnect clients. This section describes how to set up a managed client project, and the key differences to look out for when programming to the wrapper. There are also a number of managed code samples included with the SDK.

 

Setup for .NET

Ensure that Microsoft ® .NET Framework Version 2.0 is installed. If it is not, uninstall the Flight Simulator X SDK, install the .NET Framework from the following link, then re-install the SDK:

http://www.microsoft.com/downloads/details.aspx?FamilyID=0856EACB-4362-4B0D-8EDD-AAB15C5E04F5&displaylang=en

Notes on .NET client programming

// Open
// Declare a SimConnect object
SimConnect simconnect = null;
try
{
  simconnect = new SimConnect("Managed Data Request", this.Handle, WM_USER_SIMCONNECT, null, 0);
}
catch (COMException ex)
{
  // A connection to the SimConnect server could not be established
}
// Close
if (simconnect != null)
   {simconnect.Dispose();
    simconnect = null;
}

 What would have been a failed HRESULT returned in the native API translates to a COMException.

protected override void DefWndProc(ref Message m)
{
  if (m.Msg == WM_USER_SIMCONNECT)
  {
    if (simconnect != null)
    {
      simconnect.ReceiveMessage();
    }
  }
  else
  {
    base.DefWndProc(ref m);
  }
}

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Ansi, Pack = 1)]
struct Struct1
{
  // this is how you declare a fixed size string
  [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 256)]
  public String title;
  public double latitude;
  public double longitude;
  public double altitude;

};

// define the data structure
// Note that the DATATYPE.STRING256 matches the SizeConst 256 in the MarshalAs statement above
//
simconnect.AddToDataDefinition((uint)DEFINITIONS.Struct1, "Title", null, SIMCONNECT_DATATYPE.STRING256, 0); 
simconnect.AddToDataDefinition((uint)DEFINITIONS.Struct1, "Plane Latitude", "degrees", SIMCONNECT_DATATYPE.FLOAT64, 0);
simconnect.AddToDataDefinition((uint)DEFINITIONS.Struct1, "Plane Longitude", "degrees", SIMCONNECT_DATATYPE.FLOAT64, 0);
simconnect.AddToDataDefinition((uint)DEFINITIONS.Struct1, "Plane Altitude", "feet", SIMCONNECT_DATATYPE.FLOAT64, 0);
//
// IMPORTANT: register it with the simconnect managed wrapper marshaller
// if you skip this step, you will only receive a uint in the .dwData field.
//
simconnect.RegisterDataDefineStruct<Struct1>((uint)DEFINITIONS.Struct1);

Version téléchargée le 20 juin 2011 :

Programming SimConnect Clients using Managed Code

There is a managed wrapper for SimConnect that enables .NET language programmers to write SimConnect clients. This section describes how to set up a managed client project, and the key differences to look out for when programming to the wrapper. There are also a number of managed code samples included with the SDK.

The following sections use C# as the primary example language. If you intend writing a client in VB.NET read this section in conjunction with the VB.NET Managed Data Request sample.

Setup for .NET

http://www.microsoft.com/downloads/details.aspx?FamilyID=0856EACB-4362-4B0D-8EDD-AAB15C5E04F5&displaylang=en

 
Notes on .NET client programming

The managed SimConnect assembly is installed in the GAC (global assembly cache) during the installation of the SimConnect SDK, so it should not be manually placed anywhere for your application to run. However, you do need to reference a copy of this dll in Visual Studio so that it can resolve symbols at compile time. As Visual Studio does not support referencing an assembly stored in the GAC, a copy of the SimConnect.dll outside the simconnect SDK msi is shipped solely for this purpose.

The native function calls SimConnect_Open and SimConnect_Close have been replaced by the SimConnect constructor, and Dispose method respectively. This means that there is no handle required for the function calls, so for the most part the managed calls use the same parameters as the native calls, except without the SimConnect handle. The code to open and close a SimConnect client is:

C#

// Open
// Declare a SimConnect object
SimConnect simconnect = null;
// User-defined win32 event
const int WM_USER_SIMCONNECT = 0x0402;
try
{
  simconnect = new SimConnect("Managed Data Request", this.Handle, WM_USER_SIMCONNECT, null, 0);
}
catch (COMException ex)
{
  // A connection to the SimConnect server could not be established
}

// Close
if (simconnect != null)
{
  simconnect.Dispose();
  simconnect = null;
}

VB.NET

Rem Open

Try
   fsx_simconnect = New SimConnect(" VB Managed Data Request", Me.Handle, WM_USER_SIMCONNECT, Nothing, 0)
Catch ex As Exception
   Rem Failed to connect
End Try
Rem Close
If fsx_simconnect IsNot Nothing Then
   fsx_simconnect.Dispose()
   fsx_simconnect = Nothing
End If

What would have been a failed HRESULT returned in the native API translates to a COMException.

The use of raw memory pointers is not permitted in the managed API. You must define your structs and attribute them properly so that the system marshaller can handle them. See the code in the Managed Data Request sample for C#, and VB Managed Data Request sample for VB.NET.

When the client receives either a SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE or a SIMCONNECT_RECV_SIMOBJECT_DATA structure, the dwData[0] member will contain your struct as System.Object. This should be cast to the proper type.

Partial data return (SIMCONNECT_DATA_REQUEST_FLAG_TAGGED) is unsupported. For a description of this flag see the SimConnect_AddToDataDefinition function.

The top level ReceiveDispatch switch case statement is not necessary. The client should register a handler for the appropriate OnRecvXXX event, and call ReceiveMessage when it is notified that messages are waiting in the queue. For Windows applications use a win32 handle (a Control.Handle) to SimConnect to receive notifications when a message arrives. The code for this is as follows:

 

C#

 protected override void DefWndProc(ref Message m)
{
  if (m.Msg == WM_USER_SIMCONNECT)
  {
    if (simconnect != null)
    {
      simconnect.ReceiveMessage();
    }
  }
  else
  {
    base.DefWndProc(ref m);
  }
}

VB.NET

Protected Overrides Sub DefWndProc(ByRef m As Message)
   If m.Msg = WM_USER_SIMCONNECT Then
      If fsx_simconnect IsNot Nothing Then
         fsx_simconnect.ReceiveMessage()
      End If
   Else
      MyBase.DefWndProc(m)
   End If
End Sub

Constants in the native simconnect.h are declared as static members of the SimConnect class. For example: SIMCONNECT_OBJECT_ID_USER becomes SimConnect.SIMCONNECT_OBJECT_ID_USER

Enums in managed code are scoped. The names of the enum members have been changed, for example, SIMCONNECT_RECV_ID_QUIT in native code is SIMCONNECT_RECV_ID.QUIT in C#, or Microsoft.ESP.SimConnect.SIMCONNECT_RECV_ID.QUIT in VB.NET. Note that in VB.NET the full reference is necessary to locate a structure or enumeration.

Structs are mostly unchanged, with the exception that a char array is represented as a System.String. However, they do need to be registered with the managed wrapper with a call to RegisterDataDefineStruct. If a string is too long during the data marshaling, it will get truncated safely. Some specific information must be provided with each structure, as shown in bold in the example below (also refer to the Managed Data Request or VB Managed Data Request samples):

C#

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Ansi, Pack = 1)]
struct Struct1
{
  // this is how you declare a fixed size string
  [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 256)]
  public String title;
  public double latitude;
  public double longitude;
  public double altitude;
};

// define the data structure
// Note that the DATATYPE.STRING256 matches the SizeConst 256 in the MarshalAs statement above
//
simconnect.AddToDataDefinition((uint)DEFINITIONS.Struct1, "Title", null, SIMCONNECT_DATATYPE.STRING256, 0, SimConnect.SIMCONNECT_UNUSED);
simconnect.AddToDataDefinition((uint)DEFINITIONS.Struct1, "Plane Latitude", "degrees", SIMCONNECT_DATATYPE.FLOAT64, 0, SimConnect.SIMCONNECT_UNUSED);
simconnect.AddToDataDefinition((uint)DEFINITIONS.Struct1, "Plane Longitude", "degrees", SIMCONNECT_DATATYPE.FLOAT64, 0, SimConnect.SIMCONNECT_UNUSED);
simconnect.AddToDataDefinition((uint)DEFINITIONS.Struct1, "Plane Altitude", "feet", SIMCONNECT_DATATYPE.FLOAT64, 0, SimConnect.SIMCONNECT_UNUSED);

//
// IMPORTANT: register it with the simconnect managed wrapper marshaller
// if you skip this step, you will only receive a uint in the .dwData field.
//
simconnect.RegisterDataDefineStruct<Struct1>((uint)DEFINITIONS.Struct1);

VB.NET

<StructLayout(LayoutKind.Sequential, CharSet:=CharSet.Ansi, Pack:=1)> _

Structure Struct1
   Rem This is how you declare a fixed size string
   <MarshalAs(UnmanagedType.ByValTStr, SizeConst:=256)> _
   Public title As String
   Public latitude As Double
   Public longitude As Double
   Public altitude As Double
End Structure

Rem define a data structure, note the last parameter, datumID must be different for each item

fsx_simconnect.AddToDataDefinition(StructDefinitions.Struct1, "Title", "", Microsoft.ESP.SimConnect.SIMCONNECT_DATATYPE.STRING256, 0, 0)

fsx_simconnect.AddToDataDefinition(StructDefinitions.Struct1, "Plane Latitude", "degrees", Microsoft.ESP.SimConnect.SIMCONNECT_DATATYPE.FLOAT64, 0, 1)

fsx_simconnect.AddToDataDefinition(StructDefinitions.Struct1, "Plane Longitude", "degrees", Microsoft.ESP.SimConnect.SIMCONNECT_DATATYPE.FLOAT64, 0, 2)

fsx_simconnect.AddToDataDefinition(StructDefinitions.Struct1, "Plane Altitude", "feet", Microsoft.ESP.SimConnect.SIMCONNECT_DATATYPE.FLOAT64, 0, 3)

Rem IMPORTANT: register it with the simconnect managed wrapper marshaller

Rem if you skip this step, you will only receive an int in the .dwData field.

fsx_simconnect.RegisterDataDefineStruct(Of Struct1)(StructDefinitions.Struct1)

Variable length strings are not supported in the managed layer.

Optional parameters are not supported in the managed layer.

To send data in an array, copy the array to a polymorphic object array. For example, to apply a waypoint list to an AI aircraft, go through the following steps:

C#

// Note that the client code should already have declared a
// data definition, DEFINITIONS.1, and
// calledSimConnect_RequestDataOnSimObjectType to return an AI aircraft ID.
// Step 1: Add a the waypoint list to the data definition

simconnect.AddToDataDefinition(DEFINITIONS.1,"AI WAYPOINT LIST", "number", SIMCONNECT_DATATYPE.WAYPOINT, 0.0f, SimConnect.SIMCONNECT_UNUSED);

// Step 2: Declare an array of the appropriate size
SIMCONNECT_DATA_WAYPOINT[] waypoints = new SIMCONNECT_DATA_WAYPOINT[2];

// Step 3: Populate the array with all the required data
waypoints[0].Flags = (uint)SIMCONNECT_WAYPOINT_FLAGS.SPEED_REQUESTED;
waypoints[0].ktsSpeed = 100;
waypoints[0].Latitude = 10;
waypoints[0].Longitude = 20;
waypoints[0].Altitude = 1000;
waypoints[1].Flags = (uint)SIMCONNECT_WAYPOINT_FLAGS.SPEED_REQUESTED;
waypoints[1].ktsSpeed = 150;
waypoints[1].Latitude = 11;
waypoints[1].Longitude = 21;
waypoints[1].Altitude = 2000;

// Step 4: The managed wrapper marshaling code expects a polymorphic array
Object[] objv = new Object[ waypoints.Length ];
waypoints.CopyTo(objv, 0);

// Step 5: Now make the call to apply the waypoint structure to the AI aircraft
simconnect.SetDataOnSimObject(DEFINITIONS.1, AIAircraftID, SIMCONNECT_DATA_SET_FLAG.DEFAULT, objv); 

VB.NET

REM Note that the client code should already have declared a
REM data definition, StructDefinitions.DEFINITIONS.1, and
REM called fsx_simconnect_RequestDataOnSimObjectType to return an AI aircraft ID.
REM Step 1: Add a the waypoint list to the data definition
fsx_simconnect.AddToDataDefinition(StructDefinitions.DEFINITION1, "AI WAYPOINT LIST", "number", Microsoft.ESP.SimConnect.SIMCONNECT_DATATYPE.WAYPOINT, 0.0F, Microsoft.ESP.SimConnect.SimConnect.SIMCONNECT_UNUSED)

REM Step 2: Declare an array of the appropriate size
Dim waypoints(2) As Microsoft.ESP.SimConnect.SIMCONNECT_DATA_WAYPOINT

REM Step 3: Populate the array with all the required data

waypoints(0).Flags = Microsoft.ESP.SimConnect.SIMCONNECT_WAYPOINT_FLAGS.SPEED_REQUESTED
waypoints(0).ktsSpeed = 100
waypoints(0).Latitude = 10
waypoints(0).Longitude = 20
waypoints(0).Altitude = 1000
waypoints(1).Flags = Microsoft.ESP.SimConnect.SIMCONNECT_WAYPOINT_FLAGS.SPEED_REQUESTED
waypoints(1).ktsSpeed = 100
waypoints(0).Latitude = 11
waypoints(0).Longitude = 21
waypoints(0).Altitude = 1000

REM Step 4: The managed wrapper marshaling code expects a polymorphic array
Dim objv(waypoints.Length) As Object
waypoints.CopyTo(objv, 0)

REM Step 5: Now make the call to apply the waypoint structure to the AI aircraft
fsx_simconnect.SetDataOnSimObject(StructDefinitions.DEFINITION1, AIAircraftID, Microsoft.ESP.SimConnect.SIMCONNECT_DATA_SET_FLAG.DEFAULT, objv)

Echantillons fonctionnels

Click on the Echantillon fonctionnelcolumn to display the source file of a working sample. Many of the samples include the use of functions not listed in the Highlighted Functions column, this list just indicates those functions the sample is designed to specifically demonstrate.

Working Sample Description Highlighted Functions Highlighted Structures
AI Objects and Waypoints Creates a number of AI objects, including an aircraft, a truck, a hot air balloon and a whale. A key press sends waypoints to the aircraft and truck.

SimConnect_SetDataOnSimObject
SimConnect_AICreateSimulatedObject
SimConnect_AICreateNonATCAircraft


SIMCONNECT_DATA_INITPOSITION
SIMCONNECT_DATA_WAYPOINT
SIMCONNECT_RECV_ASSIGNED_OBJECT_ID
AI Traffic Creates a number of aircraft at Yakima Air Term/Mcallister airport and provides them with a flight plan to Spokane Intl. Fails to create a Boeing 747 because it is too large for the airport. Also sets up two parked aircraft, and a key press initiates them with the same flight plan.
Make sure to move the flight plan included with this sample (IFR Yakima Air Term Mcallister to Spokane Intl.pln ) to the default Flight Simulator X Files directory before running this sample. 		SimConnect_AISetAircraftFlightPlan
SimConnect_AICreateEnrouteATCAircraft
SimConnect_AICreateParkedATCAircraft
  		SIMCONNECT_RECV_EVENT_OBJECT_ADDREMOVE
SIMCONNECT_RECV_ASSIGNED_OBJECT_ID
 

Client Event

Request notifications of a simulation event, the applying of the user aircraft's brakes in this case.

SimConnect_MapClientEventToSimEvent

SimConnect_AddClientEventToNotificationGroup

SimConnect_SetNotificationGroupPriority

SimConnect_CallDispatch

 

SIMCONNECT_RECV_EVENT

Cockpit Camera

Banks the user's view camera left and right in response to certain key presses.

SimConnect_CameraSetRelative6DOF

SimConnect_MapInputEventToClientEvent

SimConnect_AddClientEventToNotificationGroup

SimConnect_MapClientEventToSimEvent

SIMCONNECT_RECV_EXCEPTION

 

DialogBoxMode Sets Dialog mode, displays a message box, then resets Dialog mode.

SimConnect_SetSystemState

SimConnect_RequestSystemState

SIMCONNECT_RECV_SYSTEM_STATE
Input Event Applies the user aircraft brakes by pressing the Ctrl-Shift-U key combination.

SimConnect_MapInputEventToClientEvent

SimConnect_SetInputGroupState

SIMCONNECT_RECV_EVENT

Joystick Input

Provides the input data from the joystick X and Y axis position, Z axis rotation, hat switch and slider. A key press selects each input option in turn.

SimConnect_SetInputGroupState

SimConnect_MapClientEventToSimEvent

SimConnect_AddClientEventToNotificationGroup

SimConnect_MapInputEventToClientEvent

 

SIMCONNECT_RECV_EVENT

Menu Items

Adds and removes a menu item.

SimConnect_MenuAddItem

SimConnect_MenuDeleteItem

SimConnect_RemoveClientEvent

SimConnect_AddClientEventToNotificationGroup

 

SIMCONNECT_RECV_EVENT

Mission Action

Interfaces with a mission xml file to provide some additional processing to mission actions, and when missions are completed.

SimConnect_ExecuteMissionAction

SimConnect_CompleteCustomMissionAction

SimConnect_SubscribeToSystemEvent

WaitForSingleObject

SIMCONNECT_RECV_CUSTOM_ACTION

No Callback

Similar to the Client Event sample, but written without a callback function. SimConnect_GetNextDispatch SIMCONNECT_RECV_EVENT

Open and Close

Simply opens and closes a connection with the SimConnect server.

SimConnect_Open

SimConnect_Close

 
Request Data Requests a small selection of data on the user's aircraft, including latitude, longitude and altitude.

SimConnect_AddToDataDefinition

SIMCONNECT_RECV_EVENT

SIMCONNECT_RECV_SIMOBJECT_DATA

Reserved Key

Requests that one of the three keys specified be reserved for this client.

SimConnect_MapClientEventToSimEvent

SimConnect_RequestReservedKey

SIMCONNECT_RECV_RESERVED_KEY

Send Event A

To be used in combination with Send Event B and Send Event C. Transmits custom events to the two other clients.

SimConnect_TransmitClientEvent

SimConnect_MapClientEventToSimEvent

SimConnect_AddClientEventToNotificationGroup

SimConnect_SetNotificationGroupPriority

SIMCONNECT_RECV_EVENT

Send Event B

Receives custom events from Send Event A, at a higher priority than Send Event C.

SimConnect_MapClientEventToSimEvent

SimConnect_AddClientEventToNotificationGroup

SimConnect_SetNotificationGroupPriority

SIMCONNECT_RECV_EVENT

Send Event C

Receives custom events from Send Event A, at a lower priority than Send Event B.

SimConnect_MapClientEventToSimEvent

SimConnect_AddClientEventToNotificationGroup

SimConnect_SetNotificationGroupPriority

SIMCONNECT_RECV_EVENT

Set Data

When a certain key is pressed, the position of the user aircraft is changed.

SimConnect_SetDataOnSimObject

SimConnect_AddToDataDefinition

SimConnect_MapClientEventToSimEvent

SimConnect_MapInputEventToClientEvent

SimConnect_SetInputGroupState

SIMCONNECT_DATA_INITPOSITION

System Event

Notifies the client when a FlightLoaded event has occured. SimConnect_SubscribeToSystemEvent

SIMCONNECT_RECV_EVENT

SIMCONNECT_RECV_EVENT_FILENAME

Tagged Data

Requests the vertical speed and pitot heat switch settings on the user aircraft, but only when this data changes.

SimConnect_RequestDataOnSimObject

SimConnect_AddToDataDefinition

SIMCONNECT_RECV_SIMOBJECT_DATA

Throttle Control

Controls the user aircraft throttle using two specified keys.

SimConnect_SetDataOnSimObject

SimConnect_AddToDataDefinition

SimConnect_MapClientEventToSimEvent

SimConnect_MapInputEventToClientEvent

SimConnect_SetInputGroupState

 

Tracking Errors

Stores information on each call to the server, so that any error caught by the server can easily be located by the client. Primarily useful for debugging rather than retail builds.

SimConnect_GetLastSentPacketID

SimConnect_MapClientEventToSimEvent

SimConnect_AddClientEventToNotificationGroup

SimConnect_SetNotificationGroupPriority

SimConnect_CallDispatch

SIMCONNECT_RECV_EVENT

SIMCONNECT_RECV_EXCEPTION

Variable Strings

Extracts three variable length strings from a structure.

SimConnect_RetrieveString

SimConnect_AddToDataDefinition

SimConnect_RequestDataOnSimObjectType

SIMCONNECT_RECV_EVENT

SIMCONNECT_RECV_EXCEPTION

SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE

Weather Station

Requests weather data from the nearest weather station to the user aircraft, every 10 seconds.

SimConnect_WeatherRequestObservationAtNearestStation

SimConnect_RequestDataOnSimObject

 

SIMCONNECT_RECV_SIMOBJECT_DATA

SIMCONNECT_RECV_WEATHER_OBSERVATION

Windows Event

Uses a Windows Event to improve the waiting time performance of a client.

CreateEvent

SimConnect_Open

WaitForSingleObject

SIMCONNECT_RECV_EVENT
       
Managed Code Samples
 

 

 

Managed Client Event Requests Pitot heat switch and Flaps events.

SimConnect_MapClientEventToSimEvent

SimConnect_AddClientEventToNotificationGroup

SimConnect_SetNotificationGroupPriority

OnRecvEvent

SIMCONNECT_RECV

SIMCONNECT_RECV_EVENT

SIMCONNECT_RECV_EXCEPTION

Managed System Event Requests 4 second and simulation state system notifications.

SimConnect_SubscribeToSystemEvent

SimConnect_UnsubscribeFromSystemEvent

SIMCONNECT_RECV

SIMCONNECT_RECV_EVENT

SIMCONNECT_RECV_EXCEPTION

Managed Data Request Click a button to request the title, latitude, longitude and altitude of the user aircraft.

SimConnect_AddToDataDefinition

RegisterDataDefineStruct

OnRecvSimobjectDataBytype

SIMCONNECT_RECV_SIMOBJECT_DATA

 © 2006 Microsoft Corporation. All rights reserved.

~~@~~