Update version to 0.1.8-beta; add RawMessageReceived event and RawSimConnectMessageEventArgs for low-level message handling

Author: AussieScorcher

CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.8-beta] - 2025-08-10
+
+### Added
+
+-   Public `SimConnectClient.Handle` property (was internal) to allow advanced consumers to perform custom native interop scenarios not yet wrapped by the library.
+-   `SimConnectClient.RawMessageReceived` event exposing a low-level hook with raw pointer, size, and message id for diagnostics, custom decoding, or experimentation with unwrapped message types.
+
+### Notes
+
+-   Raw message memory is only valid for the duration of the event callback; copy data immediately if you need to retain it.
+-   This is an additive, non-breaking update.
+
 ## [0.1.7-beta] - 2025-08-10
 
 ### Added

Directory.Build.props

@@ -1,6 +1,6 @@
 <Project>
   <PropertyGroup>
-  <Version>0.1.7-beta</Version>
+  <Version>0.1.8-beta</Version>
     <Authors>BARS</Authors>
     <Company>BARS</Company>
     <Product>SimConnect.NET</Product>

src/SimConnect.NET/Events/RawSimConnectMessageEventArgs.cs

@@ -0,0 +1,44 @@
+// <copyright file="RawSimConnectMessageEventArgs.cs" company="BARS">
+// Copyright (c) BARS. All rights reserved.
+// </copyright>
+
+using System;
+
+namespace SimConnect.NET.Events
+{
+    /// <summary>
+    /// Provides data for the <see cref="SimConnectClient.RawMessageReceived"/> event, exposing the raw
+    /// SimConnect dispatch pointer and size for advanced consumers that need low-level access.
+    /// The data memory referenced by <see cref="DataPointer"/> is only valid for the duration of the event callback.
+    /// </summary>
+    public sealed class RawSimConnectMessageEventArgs : EventArgs
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="RawSimConnectMessageEventArgs"/> class.
+        /// </summary>
+        /// <param name="dataPointer">Pointer to the raw SimConnect message memory.</param>
+        /// <param name="dataSize">Size (in bytes) of the message pointed to by <paramref name="dataPointer"/>.</param>
+        /// <param name="messageId">The SimConnect receive message identifier.</param>
+        public RawSimConnectMessageEventArgs(IntPtr dataPointer, uint dataSize, SimConnectRecvId messageId)
+        {
+            this.DataPointer = dataPointer;
+            this.DataSize = dataSize;
+            this.MessageId = messageId;
+        }
+
+        /// <summary>
+        /// Gets the pointer to the raw SimConnect message memory. Valid only within the event scope.
+        /// </summary>
+        public IntPtr DataPointer { get; }
+
+        /// <summary>
+        /// Gets the size (in bytes) of the raw message.
+        /// </summary>
+        public uint DataSize { get; }
+
+        /// <summary>
+        /// Gets the SimConnect receive message identifier for this message.
+        /// </summary>
+        public SimConnectRecvId MessageId { get; }
+    }
+}

src/SimConnect.NET/SimConnectClient.cs

@@ -61,6 +61,13 @@ public SimConnectClient(string applicationName = "SimConnect.NET Client")
         /// </summary>
         public event EventHandler<SimConnectErrorEventArgs>? ErrorOccurred;
 
+        /// <summary>
+        /// Occurs when any raw SimConnect message is received before it is dispatched to managers.
+        /// Allows advanced consumers to inspect or override low-level processing.
+        /// The underlying memory pointed to by <see cref="RawSimConnectMessageEventArgs.DataPointer"/> is only valid for the duration of the event callback.
+        /// </summary>
+        public event EventHandler<RawSimConnectMessageEventArgs>? RawMessageReceived;
+
         /// <summary>
         /// Gets a value indicating whether the client is connected to SimConnect.
         /// </summary>
@@ -170,7 +177,7 @@ public InputGroupManager InputGroups
         /// Gets the SimConnect handle for advanced operations.
         /// </summary>
         /// <exception cref="InvalidOperationException">Thrown when not connected to SimConnect.</exception>
-        internal IntPtr Handle
+        public IntPtr Handle
         {
             get
             {
@@ -344,10 +351,20 @@ public async Task<bool> ProcessNextMessageAsync(CancellationToken cancellationTo
                     if (ppData != IntPtr.Zero && pcbData > 0)
                     {
                         var recv = Marshal.PtrToStructure<SimConnectRecv>(ppData);
+                        var recvId = (SimConnectRecvId)recv.Id;
 
                         SimConnectLogger.Debug($"Received SimConnect message: Id={recv.Id}, Size={recv.Size}");
 
-                        switch ((SimConnectRecvId)recv.Id)
+                        try
+                        {
+                            this.RawMessageReceived?.Invoke(this, new RawSimConnectMessageEventArgs(ppData, pcbData, recvId));
+                        }
+                        catch (Exception hookEx)
+                        {
+                            SimConnectLogger.Warning($"RawMessageReceived hook threw: {hookEx.Message}");
+                        }
+
+                        switch (recvId)
                         {
                             case SimConnectRecvId.AssignedObjectId:
                                 this.ProcessAssignedObjectId(ppData);