Beatle's Blog

Hey All,

In the C++ native client’s documentation, some of the function descriptions list default values for some of the function parameters.  In C++, this means you can use a shortened form of the API function and the default values will be used.  While .Net/C# doesn’t currently support default parameter values, it does support function overloading, and I have used that ability in the new Managed SimConnect Client library to provide overloaded functional equivalents for the C++ shortened forms (I’ve used the same default values as listed in the C++ docs, so you can reference those for API specific defaults).  So when working in Visual Studio, pay attention to the IntelliSense popups, as they will list all the available overloaded versions.

I’ve also added a few “specialized” extra functions for dealing directly with the User Sim Object (basically, these functions don’t take a dwObjectID value, they internally use the constant that specifies you want to talk to the user):

RequestDataOnUserSimObject

SetDataOnUserSimObject

SendClientEventToUser

The parameter list for these APIs is equivalent to their non-User specific versions, except the dwObjectID param isn’t included in the list.

Another variety of overload I’ve used is to accept different types of data to the same API call.  The Text function uses this ability to provide a version of the function that takes a regular string (same as the C++ version) and also a version of the function that takes an array of strings (this version useful with the SIMCONNECT_TEXT_TYPE.MENU flag so you don’t have to embed nul chars(‘\0’) in your string.

A couple of samples

The MapInputEventToClientEvent function is a good example.  It’s full blown version contains 7 function parameters, but the function is valid with as little as the first 3 parameters defined.  In the original managed wrapper, you would always need to enter all 7 parameters like this:

sc.MapInputEventToClientEvent(Groups.GroupID, “shift+a”, Events.ShiftA, 0, SIMCONNECT_UNUSED, 0, false);

but with the new client library, you can use the shortened form:

sc.MapInputEventToClientEvent(Groups.GroupID, “shift+a”, Events.ShiftA);

The Text function can be used to display both scrolling/paging text across the top of the FSX/ESP display and to display a 1 up to 10 selection dialog.  With the original managed wrapper, you would have to define the string for a selection dialog something like this:

string strSelectionDlg1 = “Dialog Title\0Selection Prompt:\0Selection 1\0Selection2\0Selection3\0\0”;

but with the new client library having an overload that takes a string array, you can define that same selection dialog this way:

string[] strSelectionDlg1 = { “Dialog Title”,
                              “Selection Prompt:”,
                              “Selection 1”,
                              “Selection 2”,
                              “Selection 3”};

which is much easier to read.

Stay tuned for more

If you notice any overloads missing or just want to suggest some additional overloads, drop a line in the SimConnect forum on FSDeveloper.com.  And keep an eye here on the blog for additional info on the new Managed Client Library.

Tim “Beatle” Gregson

[This is the first in a small series of posts covering some of the new/different parts of the client library compared to the version in the official SDK.  In this first installment we’ll cover Initializing and Connecting.]

I don’t use the SimConnect.cfg file with its index based selection of a set of connection parameters; for one, that just flat out wouldn’t work for a Silverlight application, and there are several other environments where that doesn’t work well.  So instead, I just take the server information directly via the Open() function.  You application is free to use whatever method it wants to query/store this information.

Here's some prelim docs for the constructor, open, and close functions.

Constructor (Desktop version of client)

new SimConnect(object syncObject, bool bSerializePackets);

Where

syncObject

Synchronization object used to marshal the OnRecvXxx calls onto your applications UI thread.  This can be either a Window/Control for a WinForms app, or the Dispatcher object for a WPF app.  If this value is null, then the OnRecvXxx calls will be made on a background thread, and you will need to do any UI thread syncing where needed. 

Default value is null.

bSerializePackets

If true, the OnRecvXxx handlers will be serialized through a background thread provided by the client library.  If syncObject is non-null, the OnRecvXxx handlers will be UI thread synced from this background thread.  This ensures that the OnRecvXxx handlers are called in the same order the data was received from SimConnect.  Only one OnRecvXxx handler will be active at the same time

If false, the OnRecvXxx handlers are called directly from the IO Completion port handlers (OS/Framework provided background thread).  If syncObject is non-null, the OnRecvXxx handlers will be UI thread synced from this IO Completion port thread.  Multiple OnRecvXxx handlers can be active at the same time (and the same OnRecvXxx handler can be called a second time before the first instance has returned).  You will need to know your multi-threading and reentrant programming requirements when using this option with syncObject = null.  ** Note – this option hasn’t been extensively tested yet, so if you are trying it and things aren’t working, try chaning this back to true and see if that clears up the problem :->  **

Default value is true.

Constructor (SilverLight version of client)

new SimConnect(object syncObject);

Where

syncObject

Synchronization object used to marshal the OnRecvXxx calls onto your applications UI thread.  For SilverLight, this value must be a Dispatcher object.  Silverlight is much touchier about anything much running on a background thread (including updating data bound fields, which WPF is just fine with on a BG thread), so the Dispatcher object is required for SilverLight applications and all OnRecvXxx events will be UI thread sync’d, a null value for this field will throw an exception.

Open function (Desktop version of client)

Open a local connection using the default named pipe

void Open(string strAppName);

Where

strAppName

String name for your client application

Open a TCP/IP connection (IPv4 or IPv6)

void Open(string strAppName, string strHostName, Int32 iPort, Boolean bIsIPV6);

Where

strAppName

String name for your client application

strHostName 

String name for the server to connect to.  This can be either a machine name or the IP address as a dotted string “192.168.2.110”.  Passing either a null or an empty string for this parameter will default to localhost.

iPort

The port number to connect to.  Passing a 0 for this value will default to looking up the port number of the currently running local instance in the registry.  Only valid if passing null, empty string, “localhost”, or “127.0.0.1” as the strHostName parameter.

bIsIPV6 

Boolean value that selects between IPv4 (false) and IPv6 (true).

Open a TCP/IP connection (IPv4 only)

void Open(string strAppName, string strHostName, Int32 iPort);

Where

strAppName

String name for your client application

strHostName 

String name for the server to connect to.  This can be either a machine name or the IP address as a dotted string “192.168.2.110”.  Passing either a null or an empty string for this parameter will default to localhost.

iPort

The port number to connect to.  Passing a 0 for this value will default to looking up the port number of the currently running local instance in the registry.  Only valid if passing null, empty string, “localhost”, or “127.0.0.1” as the strHostName parameter.

Open a named pipe connection

void Open(string strAppName, string strHostName, string strPipeName);

Where

strAppName

String name for your client application

strHostName

String name for the server to connect to.  This can be either a machine name or the IP address as a dotted string “192.168.2.110”.  Passing a null or empty string will default to localhost.

strPipe

String name for the named pipe.  Passing a null or empty string will default to “Microsoft Flight Simulator\\SimConnect” (which works with both FSX and ESP).

Open function (SilverLight version of client)

Open a TCP/IP connection (IPv4 only)

void Open(string strAppName, string strHostName, Int32 iPort);

Where

strAppName

String name for your client application

strHostName 

String name for the server to connect to.  This can be either a machine name or the IP address as a dotted string “192.168.2.110”.  Passing either a null or an empty string for this parameter will default to localhost.

iPort

The port number to connect to.  Passing a 0 for this value will default to looking up the port number of the currently running local instance in the registry.  Only valid if passing null, empty string, “localhost”, or “127.0.0.1” as the strHostName parameter.

Close a connection

void Close();

Hey All,

Today I’m releasing the first public beta of my new Managed SimConnect Client SDK.  This SDK can be used to build managed SimConnect clients, both desktop (Console, WinForm, WPF) and web (Silverlight).  For the impatient, here’s the download link:

http://beatlescloudstorage.blob.core.windows.net/downloads/BeatlesBlog.SimConnect.SDK.Beta1.zip

And here’s a more nicely formatted version of the ReadMe file included in the download:

Welcome to Beta 1

Enclosed is the SDK for the Beatle's Blog Managed SimConnect client library.  This SDK can be used to build both Desktop clients (Console, WinForm, & WPF) and SilverLight clients.  The client libraries included are built using the Any CPU setting, so you should use this setting in your own projects, unless some other requirement of your client needs a different setting.  The client libraries included are written in 100% managed code with no dependencies on any existing libraries/DLLs/etc (except for a minimal number of .Net FrameWork libraries).

Benefits of new client library:

• No reliance on SimConnect.MSI or the native client library it installs.
• Ability to compile projects using the Any CPU build setting.
• Ability to build SilverLight based web clients.
• Simpler Data Structure Definition/Registration system using custom attributes.
• Overloads provided for those APIs where appropriate allowing use of default values like the native library has.
• Ability to pass an instance object to a RequestDataOnSimObject call, allowing the instance to be auto updated as new requested data is received.
• Working support for Client Data API functions
• No SimConnect.CFG file required/used, Server Name and Port provided in the SimConnect.Open(...) call.
• In general, more .Net friendly :->.
• Uses a Ships-With model i.e. you ship the library with your application, installed in the same directory as your application.  An alternate option is to use something like ILMerge.exe to embed the client library directly into your application.
• Client libraries are compatible with FSX SP2, FSX + Acceleration pack, and ESP v1.  Client libraries will NOT connect to FSX RTM or FSX SP1.

A note on Silverlight Support

The SilverLight runtime imposes several restrictions on socket communications.  SilverLight applications can only open a port in the range 4502 through 4534, so you will need to modify your SimConnect.XML file to open one or more IPv4 ports in this range.  Here is a sample SimConnect.XML file:

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

<SimBase.Document Type="SimConnect" version="1,0">
  <Descr>SimConnect Server Configuration</Descr>
  <Filename>SimConnect.xml</Filename>
  <Disabled>False</Disabled>

  <!-- Global (remote) IPv4 Server Configuration (SilverLight compatible) -->
  <SimConnect.Comm>
    <Disabled>False</Disabled>
    <Protocol>IPv4</Protocol>
    <Scope>global</Scope>
    <MaxClients>64</MaxClients>
    <Address>0.0.0.0</Address>
    <Port>4504</Port>
  </SimConnect.Comm>

</SimBase.Document>

Another restriction is that in order to make a cross-domain connection (which would be any SimConnect connection), the machine you are trying to connect to (the machine that Flight Simulator/ESP is running on) must be running a Silverlight Policy File server on port 943.  See the Samples section below for a simple Policy File server that fills this requirement.

Client Library Files

• Libs\BeatlesBlog.SimConnect.DLL

This is the main desktop version of the client library built using .Net 3.5.  If you are building a desktop application, this is the version you most likely want to use.

• Libs\BeatlesBlog.SimConnect20.DLL

This is an alternate version of the desktop client built using .Net 2.0.  This version does not include Named Pipe support (as .Net 2.0 doesn't provide this support).  If some other requirement of your application limits you to only using .Net 2.0, then you should use this version of the library instead.

• Libs\BeatlesBlog.SimConnectSL.DLL

This is a SilverLight version of the Client library built using SilverLight 2.0, but the library should be usable in a SilverLight 3.0 project.

Solution Files

• Samples\SamplesBasic.sln

Solution file contains the 3 basic desktop samples, one each for Console, WinForm, and WPF.  This solution file is compatible with the Visual Studio C# Express product and doesn't require any additional items be installed in order to build.

• Samples\Samples.sln

Solution file contains all of the available sample projects.  Some of these have extra requirements (SilverLight tools, Silverlight ToolKit, Virtual Earth SilverLight Map Control CTP, Virtual Earth 3D Map control).

Basic Sample List (those in SamplesBasic.sln)

• Samples\Console\SimConnectTestConsole

This sample uses the MENU version of the Text(...) function to display a heirarchical set of selection dialogs that allow testing several SimConnect functions.  Built using the .Net framework 3.5.

• Samples\WinForm\SimConnectTestWinForm

This sample displays all of the Aircraft (User and AI) in a detail mode ListView showing Lat, Lon, Alt, Pitch, Bank, Heading.  Menu allows connecting to either a local SimConnect instance (if one is available) or a remote SimConnect instance.  Built using the .Net framework 3.5.

• Samples\WPF\SimConnectTestWPF

This sample displays all of the Aircraft (User and AI) in a data bound ListBox using a custom DataTemplate to display Lat, Lon, Alt, Pitch, Bank, Heading in Degrees and Radians/Feet and Meters.  Built using the .Net framework 3.5.

Enhanced Sample List (those only in Samples.sln)

• Samples\WinForm\WinForm20Map

This sample is a WinForm application built using .Net 2.0 and the BeatlesBlog.SimConnect20.DLL version of the client library.  This sample also uses a Virtual Earth 3D (VE3D) map control, which you can install by going to http://www.bing.com/maps and clicking on the 3D button in the map nav bar.  Once connected, the application creates a custom Camera Controller that provides a "cockpit view" from the user aircraft Lat, Lon, Alt, Pitch, Bank, Heading.

• Samples\WPF\ClientDataTest

This sample shows how to use the Client Data API functionality in the client library.  Built using .Net 3.5

• Samples\SilverLight\SimConnectTestSilverlight

This sample is basically the same as the SimConnectTestWPF sample, but written as a SilverLight application.  There is also an associated ASP.Net webpage project.  Built using SilverLight 2.0.

• Samples\SilverLight\MovingMapSL\MovingMapSL

This sample uses the CTP Virtual Earth Silverlight Map control, available from http://connect.microsoft.com.  There is also an associated ASP.Net webpage project.  Built using SilverLight 2.0.

• Samples\SilverLight\SilverLightPolicyServer

This is the sample Silverlight Policy Server mentioned above.  You must be running this, or a similar utility, on the same machine as Flight Simulator / ESP in order for Silverlight Clients to be able to connect to it.

Documentation

At the moment, the documentation consist of this readme file and the sample projects included in this SDK.  Please keep an eye on my blog for future posts related to the new client library.  Please use the FSDeveloper SimConnect forum for questions, suggestions, and bug reports.

<cough/><cough/>

Yes, it’s been quite awhile since I last posted, sorry about that.  Quick catch up, Aces got shut down and for the time being, I’m still employed at Microsoft.

Just a quick post for now to blow out the cobwebs (and make sure Live Writer is setup correctly).  I should have some more interesting posts in the next few days.

<cough/><cough/>

Tim “Beatle” Gregson

Hey All,

In my last blog post, I mentioned we had a new download area with some new samples and that I had a couple of samples that needed some minor cleaning up and then they would be posted there.  Well one of those has been posted there, the In-Process DLL SimConnect Client sample (actually, it was posted almost 2 months ago, I'm just now getting around to blogging about it :-> ).

I wrote this sample because I noticed we didn't have any in-proc DLL samples in the SDK. 

First off, what does that mean, In-Process?  It means that the DLL SimConnect client is loaded within the ESP/FSX process space instead of within its own process space like an external .EXE based SimConnect client.  This has some good points and some bad points (depending on what you are trying to do). 

The good points are that you register a callback function once, right after the SimConnect_Open call, and that callback will get called directly by the Server Side SimConnect code when messages are available for your client.  This bypasses all of the networking layer (ie no TCP/IP, no Named Pipes, you get a direct function call into your code from the Sim side code).  This also means you don't have to run your own HWND based message pump, you don't need to use a background thread with an Event Handle, you don't need to use a timer based query scheme, etc - in other words, it makes life much easier.

The bad points are that you can't really do standard windows based UI this way - well, you can but its not guaranteed to work (DirectX and GDI get into fights with each other sometimes, especially in full screen mode) unless you put the Sim into Dialog Mode first.  You can still add menu items, use the SimConnect_Text function to display both scrolling text and simple "select one of the below" style dialog boxes.  Another bad point, in some folks eyes anyway, is you can only use C++ to write an In-Proc DLL client.  Also, since your client is running within the ESP/FSX process space, if your client code goes nuts (causes a fault of some sort, or goes into an infinite loop) you can take down the entire Sim.

So, if you want to write a client with lots of UI and/or you want to use managed code, stick with an out-of-proc EXE style client, but if you can live within the above restrictions, then an in-proc DLL style client may be the way to go.

Things that would make a good in-proc DLL style client:

• adding Custom Action support for missions
• transferring data between the Sim and some external app
• interfacing custom hardware to the Sim

What the sample does

The sample is fairly simple in what it does.  It adds a couple of menu items to the AddOn menu (Show Weather Menu and Show Time Menu).  Selecting one of these menu items will use SimConnect_Text to show a "Select on of these options" dialogs, the weather dialog allows you to query the dialog from either the current location or from SeaTac, the time dialog lets you set the time to either 12:00 Local or 00:00 Zulu.  Selecting one of the weather reporting options will query for the Metar string at the requested location, and then use SimConnect_Text to display the Metar string as a scrolling message across the top of the screen.  Selecting one of the time set options will, surprisingly enough, set the time accordingly :->

Hopefully a few of you will find the sample useful.  If you do, or you have any questions about it, drop by the Microsoft ESP Forum to discuss it/ask questions.

Tim "Beatle" Gregson