Merge branch 'next'

Author: mpaperno

CHANGELOG.md

@@ -1,6 +1,66 @@
 # WASimCommander - Change Log
 
-## 1.2.0.0 (07-Nov-2022)
+## 1.3.0.0 (15-Nov-2024)
+
+### WASimModule
+* The server will now handle connection, ping, and custom calculator events initiated with `SimConnect_TransmitClientEvent_EX1()` (as well as the older `TransmitClientEvent()` version). ([8f42b51d])
+* Updated reference list of KEY event names for MSFS SDK v0.23.1.0 ([b115d8b6]) and v0.24.3.0 ([495274d5]).
+
+### WASimClient (C++) and WASimClient_CLI (managed .NET)
+* Added ability to use "custom named simulator events" (such as "Custom.Event") directly from `WASimClient`, w/out needing a separate `SimConnect` session ([61912e66]):
+  * Added `registerCustomKeyEvent()` method for mapping event names to numeric IDs (similar in purpose to `SimConnect_MapClientEventToSimEvent()` function). See [documentation][registerCustomKeyEvent] for details.
+  * `sendKeyEvent()` can now be used to trigger registered custom events (similar to `SimConnect_TransmitClientEvent[_EX1]()` functions), by ID or name. See [documentation][sendKeyEvent] for details.
+  * Note: This is a client-side feature, not involving the server-side `WASimModule` at all, provided for convenience.
+  * Added basic test/example of usage in `CPP_BasicConsole` and `CS_BasicConsole` project code.
+  * Many thanks to [Hans Billiet] for the motivation and [original code][hb-custom-events]!
+* Added ability to set Sim Vars using `string` values using the new [setVariable(var, stringValue)] overload or `setSimVarVariable()` methods (see below). ([9603c9f4])
+  This is also a client-only side feature since the only way to set string values is with SimConnect (or the in-game JS API).
+* Added convenience methods for setting Sim Vars ('A' type) specifically. There are 4 overloads of [setSimVarVariable()] for setting numeric or string values, with or w/out an index. ([62991392])
+* Fixed that the key event name lookup cache used with `sendKeyEvent(eventName)` string overload wasn't entirely thread-safe. Thanks to [Hans Billiet] for reporting! ([03753d8b])
+* Added new [`DataRequest()` constructor][DataRequest_5] overloads for calculated result type w/out `valueSize` argument where the size is determined based on the desired calculation result type. ([9f7aa9c5])
+
+### WASimClient_CLI (managed .NET)
+* Fixed possible `null` `String` references in `RegisteredEvent` and `VariableRequest` structs when created with some constructor overloads (for example when attempting to send a `new VariableRequest(localVariableId)`). Thanks to [Hans Billiet] for reporting! ([1632ed18])
+* Added .NET8 builds to SDK distribution. This is also now the default .NET version for the VS solution's Release & Debug build configurations.
+
+### WASimUI
+* Can now set Sim Var string type values in the "Variables" section. The "string" unit type must be selected to show the text value entry box. ([8616c608])
+* Updated database of imported Event IDs and Simulator Variables from published online SDK docs as of Mar-1-2024. ([35a495c6])
+
+### Documentation
+* Split [WASimClient's][WASimClient_docs] "high level API" methods overview into more specific groups.
+* Added/improved some details about `WASimClient`'s event callbacks and possible concurrency issues. ([e474c7fd])
+
+### Other
+* All distributed pre-built libraries and module are built against MSFS SDK v0.24.3.0.
+
+**[Full Change Log](https://github.com/mpaperno/WASimCommander/compare/v1.2.0.0...v1.3.0.0)**
+
+[8f42b51d]: https://github.com/mpaperno/WASimCommander/commit/8f42b51d1d94f704e001940abe2ff3f1434a9481
+[b115d8b6]: https://github.com/mpaperno/WASimCommander/commit/b115d8b64e77eaf8112de7a15c9d0dfc2fa29904
+[03753d8b]: https://github.com/mpaperno/WASimCommander/commit/03753d8b834bfd0239aee2df1043c3b0377d4a55
+[1632ed18]: https://github.com/mpaperno/WASimCommander/commit/1632ed1883108f0ba5ff03610ce4fc902d84387c
+[35a495c6]: https://github.com/mpaperno/WASimCommander/commit/35a495c6a3dc9beb13ffc05bdeab105f3b7a9fae
+[61912e66]: https://github.com/mpaperno/WASimCommander/commit/61912e66f5e51791d51fce42bb96de38f7d5b6a0
+[e474c7fd]: https://github.com/mpaperno/WASimCommander/commit/e474c7fdb9074d29064392354e2829c3d2267dee
+[9603c9f4]: https://github.com/mpaperno/WASimCommander/commit/9603c9f4fffed62be94a44a42a0ae8fda7c218c6
+[62991392]: https://github.com/mpaperno/WASimCommander/commit/62991392226c05a972b4db7b3f8aaaf5329a60e8
+[8616c608]: https://github.com/mpaperno/WASimCommander/commit/8616c6080308f4dbb1963ce6787ab0221babab20
+[9f7aa9c5]: https://github.com/mpaperno/WASimCommander/commit/9f7aa9c588fb5976363692c3ca160cfe4bbd97fd
+[495274d5]: https://github.com/mpaperno/WASimCommander/commit/495274d5ca509d6663f7575f8888360ccd6907f8
+[custom-key-events]: https://github.com/mpaperno/WASimCommander/compare/dbd4c469611750a8a9e7222740428fd4851b516f..e98fbd42b8e6aea34e0e013d261c8a48ebd47fcf
+[hb-custom-events]: https://github.com/HansBilliet/WASimCommander/compare/b1519c988bf44ce43af8a50880092391566af48a...83adc91fb73fa29dcc07f1461435dafe41f7d366
+[registerCustomKeyEvent]: https://wasimcommander.max.paperno.us/class_w_a_sim_commander_1_1_client_1_1_w_a_sim_client.html#a6e7bf0b7c6b741081bc2ce43d937ba11
+[sendKeyEvent]: https://wasimcommander.max.paperno.us/class_w_a_sim_commander_1_1_client_1_1_w_a_sim_client.html#adf5b8df4cb657fefaa97f97b0ebea42c
+[setVariable(var, stringValue)]: https://wasimcommander.max.paperno.us/class_w_a_sim_commander_1_1_client_1_1_w_a_sim_client.html#a725be5c00b1d6861826c898d095db118
+[setSimVarVariable()]: https://wasimcommander.max.paperno.us/class_w_a_sim_commander_1_1_client_1_1_w_a_sim_client.html#a5f0f7e3575c605a44516a407251567fe
+[DataRequest_5]: https://wasimcommander.max.paperno.us/struct_w_a_sim_commander_1_1_data_request.html#a5d2d8f43b6e0aeb0de5771af73a995da
+[WASimClient_docs]: https://wasimcommander.max.paperno.us/class_w_a_sim_commander_1_1_client_1_1_w_a_sim_client.html
+[Hans Billiet]: https://github.com/HansBilliet
+
+
+---
+## 1.2.0.0 (07-Nov-2023)
 
 ### WASimModule
 * Fix binary data representation in results for named variable requests with 1-4 byte integer value sizes (`int8` - `int32` types) -- the result data would be encoded as a float type instead. ([8c7724e6])

README.md

@@ -46,10 +46,10 @@ On a more practical note, I am using it with the [MSFS Touch Portal Plugin](http
     - With or without a returned result; Result returned as numeric and string types.
     - Formatted results from `format_calculator_string()` using 
       [RPN String Formatting](https://docs.flightsimulator.com/html/Additional_Information/Reverse_Polish_Notation.htm#strings)
-- **Get Variable**: Return numeric result from any type of variable accessible to a standalone WASM module 
+- **Get Variable**: Return value result from any type of variable accessible to a standalone WASM module 
     (basically everything but Gauge and Instrument types, but also including Token vars). 
     - With optional Unit specifier for variable types which support it.
-- **Set Variable**: Set the numeric value of any settable variable type, with optional Unit specifier for variable types which support it.
+- **Set Variable**: Set the value of any settable variable type, with optional Unit specifier for variable types which support it.
 - **Create Variable**: Create (and get/set) a new Local variable if it doesn't already exist.
 - **List Local Variables**: Get a list of all available 'L' variables with their names and current IDs.
 - **Lookup**: Return a numeric ID for a SimVar/Local/Token variable, Unit, or Key Event name.
@@ -69,6 +69,7 @@ On a more practical note, I am using it with the [MSFS Touch Portal Plugin](http
     - Event names can be completely custom (including a `.` (period) as per SimConnect convention), or derive from the connected Client's name (to ensure uniqueness).
 - **Send Simulator "Key Events"** directly by ID or name (instead of going through the SimConnect mapping process or executing calculator code). Much more efficient than the other methods.
     - **New in v1.1.0:** Send Key Events with up to 5 values (like the new `SimConnect_TransmitClientEvent_EX1()`).
+    - **New in v1.3.0:** Send Custom Key Events (the ones with a "." in the name that are defined by particular models) by name or ID with up to 5 values.
 - **Remote Logging**: Log messages (errors, warnings, debug, etc) can optionally be sent to the Client, with specific minimum level (eg. only warnings and errors).
 - **Ping** the Server to check that the WASM module is installed and running before trying to connect or use its features.
 
@@ -131,6 +132,30 @@ API features. The main `WASimClient` interactions all happen in the `MainWindow:
 
 More to come... or [Just Read The Source](https://github.com/mpaperno/WASimCommander/tree/main/src) :-)
 
+#### Using .NET Libraries
+
+Please note that when using the .NET builds in your project, it is **vital to include the `Ijwhost.dll`** in your runtime directory along with `WASimCommander.WASimClient.dll`.
+
+While the latter will get copied to your build output automatically as a dependency, the `Ijwhost.dll` will *not*. This will result in a runtime error that says
+`Could not load file or assembly 'WASimCommander.WASimClient.dll'. The specified module could not be found.` even though it is clearly there in the runtime directory.
+
+Likewise you will probably want to copy the default `client_conf.ini` configuration file to your build output/runtime as well (this file defines some default options like logging).
+
+Both files should be included in the build as "content" files. This can be done via the VS UI or by editing the project file directly.
+As an example, assuming you copied the WASimCommander managed libraries to a `./lib` folder of your source, the following two entries
+from a .csproj file illustrate the settings:
+
+```xml
+  <ContentWithTargetPath Include=".\lib\WASimCommander\Ijwhost.dll">
+    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+    <TargetPath>Ijwhost.dll</TargetPath>
+  </ContentWithTargetPath>
+  <ContentWithTargetPath Include=".\lib\WASimCommander\client_conf.ini">
+    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+    <TargetPath>client_conf.ini</TargetPath>
+  </ContentWithTargetPath>
+```
+
 -------------
 ### Troubleshooting
 

build/build.ps1

@@ -8,7 +8,7 @@
 Param(
   [string[]]$Targets = "all",
   [string]$RootPath = "..",
-  [string[]]$Configuration = @("Debug", "Debug-DLL", "Release-DLL", "Release-net6", "Release-net7", "Release-netfw", "Release"),
+  [string[]]$Configuration = @("Debug", "Debug-DLL", "Release-DLL", "Release-net5", "Release-net6", "Release-net7", "Release-netfw", "Release"),
   [string]$Platform = "x64",
   [string[]]$Projects = "all",
   [string]$BuildType = "Clean,Rebuild",
@@ -35,7 +35,7 @@ $ModulePackage = "${PackagePath}\module"
 $DocsDistroPath = "$RootPath\..\gh-pages"
 
 $testApps = @{
-	"$BuildPath\CS_BasicConsole\Release-$Platform\$Platform\Release\net6.0-windows" = "$PackagePath\bin\CS_BasicConsole";
+	"$BuildPath\CS_BasicConsole\Release-net8-$Platform\$Platform\Release-net8\net8.0-windows" = "$PackagePath\bin\CS_BasicConsole";
 	"$BuildPath\CPP_BasicConsole\Release-$Platform" = "$PackagePath\bin\CPP_BasicConsole"
 	"$SrcPath\Testing\Py_BasicConsole" = "$PackagePath\bin\Py_BasicConsole"
 }
@@ -148,15 +148,18 @@ if ($LastExitCode -ge 8) { Write-Output($LastExitCode); Exit 1  }
 # Managed DLL
 $csLibPath = "${LibPath}\managed"
 
-# .NET 5 (default Release build)
-robocopy "$BuildPath\${CLIENT_NAME}_CLI\Release-$Platform" "${csLibPath}\net5" *.dll *.pdb *.xml *.ini $copyOptions
+# .NET 5
+robocopy "$BuildPath\${CLIENT_NAME}_CLI\Release-net5-$Platform" "${csLibPath}\net5" *.dll *.pdb *.xml *.ini $copyOptions
 if ($LastExitCode -ge 8) { Write-Output($LastExitCode); Exit 1  }
 # .NET 6
 robocopy "$BuildPath\${CLIENT_NAME}_CLI\Release-net6-$Platform" "${csLibPath}\net6" *.dll *.pdb *.xml *.ini $copyOptions
 if ($LastExitCode -ge 8) { Write-Output($LastExitCode); Exit 1  }
 # .NET 7
 robocopy "$BuildPath\${CLIENT_NAME}_CLI\Release-net7-$Platform" "${csLibPath}\net7" *.dll *.pdb *.xml *.ini $copyOptions
 if ($LastExitCode -ge 8) { Write-Output($LastExitCode); Exit 1  }
+# .NET 8 (default Release build)
+robocopy "$BuildPath\${CLIENT_NAME}_CLI\Release-$Platform" "${csLibPath}\net8" *.dll *.pdb *.xml *.ini $copyOptions
+if ($LastExitCode -ge 8) { Write-Output($LastExitCode); Exit 1  }
 # .NET Framework
 robocopy "$BuildPath\${CLIENT_NAME}_CLI\Release-netfw-$Platform" "${csLibPath}\net46" *.dll *.pdb *.xml *.ini $copyOptions
 if ($LastExitCode -ge 8) { Write-Output($LastExitCode); Exit 1  }

build/version.ps1

@@ -1,6 +1,6 @@
 
 $VER_MAJOR = 1
-$VER_MINOR = 2
+$VER_MINOR = 3
 $VER_PATCH = 0
 $VER_BUILD = 0
 $VER_COMIT = 0

docs/CNAME

@@ -0,0 +1 @@
+wasimcommander.max.paperno.us

docs/Doxyfile

@@ -183,12 +183,14 @@ CLANG_OPTIONS          = -std=c++17 \
 GENERATE_HTML          = YES
 HTML_OUTPUT            = html
 HTML_HEADER            = header.html
-HTML_FOOTER            =
+HTML_FOOTER            = footer.html
 HTML_EXTRA_STYLESHEET  = doxyawesome/doxygen-awesome.css \
                          customdoxygen.css
 HTML_EXTRA_FILES       = doxyawesome/doxygen-awesome-darkmode-toggle.js \
                          doxyawesome/doxygen-awesome-paragraph-link.js \
-                         .nojekyll
+                         .nojekyll \
+                         CNAME
+
 HTML_COLORSTYLE_HUE    = 235
 HTML_COLORSTYLE_SAT    = 19
 HTML_COLORSTYLE_GAMMA  = 185

docs/footer.html

@@ -4,13 +4,13 @@
 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
   <ul>
     $navpath
-    <li class="footer">$generatedby <a href="https://www.doxygen.org/index.html"><img class="footer" src="$relpath^doxygen.svg" width="104" height="31" alt="doxygen"/></a> $doxygenversion </li>
+    <li class="footer">Generated for $projectname &#160;$projectnumber by <a href="https://www.doxygen.org/index.html"><img class="footer" src="$relpath^doxygen.svg" width="104" height="31" alt="doxygen"/></a> $doxygenversion </li>
   </ul>
 </div>
 <!--END GENERATE_TREEVIEW-->
 <!--BEGIN !GENERATE_TREEVIEW-->
 <hr class="footer"/><address class="footer"><small>
-$generatedby&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="$relpath^doxygen.svg" width="104" height="31" alt="doxygen"/></a> $doxygenversion
+Generated for $projectname &#160;$projectnumber by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="$relpath^doxygen.svg" width="104" height="31" alt="doxygen"/></a> $doxygenversion
 </small></address>
 <!--END !GENERATE_TREEVIEW-->
 </body>

docs/version.Doxyfile

@@ -3,5 +3,5 @@
 # THIS FILE IS GENERATED BY A SCRIPT, CHANGES WILL NOT PERSIST. EDIT THE CORRESPONDING .in TEMPLATE FILE INSTEAD.
 
 PROJECT_NAME   = "WASimCommander"
-PROJECT_NUMBER = v1.2.0.0
+PROJECT_NUMBER = v1.3.0.0
 PROJECT_BRIEF  = "Remote access to the Microsoft Flight Simulator 2020 Gauge API."