Generate safe COM output pointer ABI

[Jevan Saks (jevansaks)]

Summary

• project canonical COM IID + [ComOutPtr] void** interface parameters as implementation-safe out void*
• generate Windows.Win32.ComOutPtr.FromManaged to return the exact requested interface with caller-owned COM reference semantics
• preserve generic out T friendly overloads and adaptive COM/WinRT projection
• preserve flat P/Invoke, no-marshalling, and UseIntPtrForComOutPointers behavior
• cover IClassFactory implementations across source-generated COM, built-in COM, and auto-WinRT enabled/disabled configurations

Fixes #1827

Rationale and compatibility

A native COM method with an IID + ppv parameter pair promises more than simply returning a COM pointer. On success, ppv must point at the exact interface identified by the IID, with that interface's vtable layout and a caller-owned reference. The native caller immediately interprets the returned pointer according to the requested interface and invokes its vtable slots.

The current managed out object projection cannot guarantee that contract for implementations. The COM source generator recognizes IidParameterIndex, but it does not make the sibling IID value available to the custom marshaller for the [ComOutPtr] parameter. The marshaller can obtain a COM pointer for the managed object, but it cannot perform QueryInterface for the IID the caller actually requested. The pointer may therefore represent IUnknown or another interface rather than the requested interface. It can be a valid COM pointer while still exposing the wrong vtable to the native caller.

Until CsWin32 can build on a separately extensible COM source-generator package, or custom marshallers can otherwise receive the value identified by IidParameterIndex, this change projects the implementation-facing parameter as out void*. Implementers can use ComOutPtr.FromManaged to perform QueryInterface for the exact requested IID and transfer the resulting caller-owned interface pointer. This makes the unsafe ABI representation visible, but makes it possible to implement the ABI correctly.

Callers are generally unaffected because CsWin32 continues to generate the friendly generic out T overload, which supplies the IID for T and converts the returned native interface pointer to T. This is a source change for managed implementations that currently declare the parameter as out object.

The prior raw IID, out object calling pattern is no longer available. Callers with only a runtime IID must use the raw output pointer and observe normal COM ownership rules. We are accepting that tradeoff for now and will listen for feedback if the dynamic-IID pattern is important in practice. If the source-generator extensibility described above becomes available, the managed out object projection can be reconsidered without sacrificing exact interface identity.

Validation

• 129 COM generator tests passed
• source-generated COM runtime tests passed on .NET 9 and .NET 10
• built-in COM runtime tests passed on .NET 9 and .NET 10
• auto-WinRT-disabled IClassFactory runtime tests passed on .NET 9 and .NET 10
• affected projects build with zero warnings
• full GitHub build, test, documentation, and CodeQL checks passed
• git diff --check passed