feat(windows): add shared COM, window and shell-stream interop helpers

Win32Com joins threads to the MTA on demand, creates in-process COM objects
and releases wrappers deterministically; PropVariant (x64 layout) with
PropVariantClear; Win32Window validates HWNDs; ShellStream opens files through
SHCreateStreamOnFileEx with STGM_SHARE_DENY_NONE so readers never block writers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
This commit is contained in:
Claude committed 2026-10-02 09:46:02 +00:00
1 parent 800843d2ae
commit 0e6c15cb13
4 files changed
+167

No files matched your search

@@ -0,0 +1,27 @@
using System.Runtime.InteropServices;
using Titano.Core.IO;
namespace Titano.Core.Windows.Interop;
/// <summary>IStream over a file through <c>SHCreateStreamOnFileEx</c>.</summary>
internal static partial class ShellStream
{
private const uint STGM_READ = 0x0;
private const uint STGM_SHARE_DENY_NONE = 0x40;
private const uint FILE_ATTRIBUTE_NORMAL = 0x80;
/// <summary>
/// Opens <paramref name="path"/> read-only while letting other processes read and write it (FileShare.ReadWrite),
/// so a camera tether or a copy in progress is never blocked. Returns an owned IStream pointer the caller must
/// <see cref="Marshal.Release"/>. Failures surface as the matching .NET exception (FileNotFoundException, …).
/// </summary>
public static nint OpenRead(string path)
{
var hr = SHCreateStreamOnFileEx(LongPath.Normalize(path), STGM_READ | STGM_SHARE_DENY_NONE, FILE_ATTRIBUTE_NORMAL, 0, 0, out var stream);
Marshal.ThrowExceptionForHR(hr);
return stream;
}
[LibraryImport("shlwapi.dll", StringMarshalling = StringMarshalling.Utf16)]
private static partial int SHCreateStreamOnFileEx(string file, uint mode, uint attributes, int create, nint template, out nint stream);
}
@@ -0,0 +1,63 @@
using System.Runtime.InteropServices;
namespace Titano.Core.Windows.Interop;
/// <summary>COM apartment, activation and release helpers shared by the WIC, shell and taskbar interop.</summary>
internal static partial class Win32Com
{
public const int RPC_E_CHANGED_MODE = unchecked((int)0x80010106);
public const int REGDB_E_CLASSNOTREG = unchecked((int)0x80040154);
private const uint COINIT_MULTITHREADED = 0x0;
private const uint CLSCTX_INPROC_SERVER = 0x1;
[ThreadStatic]
private static bool t_initialized;
/// <summary>
/// Joins the calling thread to the multithreaded apartment unless it already has one (an STA UI thread keeps
/// its apartment, which free-threaded WIC also accepts). Idempotent per thread. COM stays initialised until the
/// thread exits, as the runtime does for the threads it initialises itself.
/// </summary>
public static void EnsureInitialized()
{
if (t_initialized) return;
var hr = CoInitializeEx(0, COINIT_MULTITHREADED);
if (hr < 0 && hr != RPC_E_CHANGED_MODE) Marshal.ThrowExceptionForHR(hr);
t_initialized = true;
}
/// <summary>Creates an in-process COM object and wraps it; returns the HRESULT (instance is null on failure).</summary>
public static int TryCreateInstance(Guid clsid, Guid iid, out object? instance)
{
EnsureInitialized();
var hr = CoCreateInstance(clsid, 0, CLSCTX_INPROC_SERVER, iid, out var pointer);
if (hr < 0)
{
instance = null;
return hr;
}
try
{
instance = Marshal.GetObjectForIUnknown(pointer);
}
finally
{
// The wrapper holds its own reference.
Marshal.Release(pointer);
}
return hr;
}
/// <summary>Releases the wrapper's reference to the native object now rather than at finalization.</summary>
public static void Release(object? comObject)
{
if (comObject is not null && Marshal.IsComObject(comObject)) Marshal.ReleaseComObject(comObject);
}
[LibraryImport("ole32.dll")]
private static partial int CoInitializeEx(nint reserved, uint coInit);
[LibraryImport("ole32.dll")]
private static partial int CoCreateInstance(in Guid clsid, nint outer, uint context, in Guid iid, out nint instance);
}
@@ -0,0 +1,63 @@
using System.Runtime.InteropServices;
namespace Titano.Core.Windows.Interop;
/// <summary>
/// x64 PROPVARIANT (24 bytes: VARTYPE + three reserved WORDs, then a 16-byte union). Only the integer members
/// Titano reads are mapped; anything the callee allocates is freed by <see cref="Clear"/>.
/// </summary>
[StructLayout(LayoutKind.Explicit, Size = 24)]
internal partial struct PropVariant
{
private const ushort VT_I2 = 2, VT_I4 = 3, VT_UI1 = 17, VT_UI2 = 18, VT_UI4 = 19;
[FieldOffset(0)]
public ushort VarType;
[FieldOffset(8)]
private byte _byte;
[FieldOffset(8)]
private short _int16;
[FieldOffset(8)]
private ushort _uint16;
[FieldOffset(8)]
private int _int32;
[FieldOffset(8)]
private uint _uint32;
/// <summary>Reads an 8/16/32-bit integer value; false for any other type.</summary>
public readonly bool TryGetInt32(out int value)
{
switch (VarType)
{
case VT_UI1:
value = _byte;
return true;
case VT_I2:
value = _int16;
return true;
case VT_UI2:
value = _uint16;
return true;
case VT_I4:
value = _int32;
return true;
case VT_UI4 when _uint32 <= int.MaxValue:
value = (int)_uint32;
return true;
default:
value = 0;
return false;
}
}
/// <summary>Frees whatever the callee allocated and resets the value to VT_EMPTY.</summary>
public static void Clear(ref PropVariant value) => PropVariantClear(ref value);
[LibraryImport("ole32.dll")]
private static partial int PropVariantClear(ref PropVariant value);
}
@@ -0,0 +1,14 @@
using System.Runtime.InteropServices;
namespace Titano.Core.Windows.Interop;
/// <summary>Window handle validation shared by the DWM and taskbar helpers.</summary>
internal static partial class Win32Window
{
/// <summary>True when <paramref name="window"/> names an existing window; rejects null and stale handles up front.</summary>
public static bool Exists(nint window) => window != 0 && IsWindow(window);
[LibraryImport("user32.dll")]
[return: MarshalAs(UnmanagedType.Bool)]
private static partial bool IsWindow(nint window);
}