Skip to content

Update docs for generated interop code#2311

Open
Sergio0694 wants to merge 3 commits intostaging/3.0from
user/sergiopedri/update-docs
Open

Update docs for generated interop code#2311
Sergio0694 wants to merge 3 commits intostaging/3.0from
user/sergiopedri/update-docs

Conversation

@Sergio0694
Copy link
Member

This pull request updates the documentation for CsWinRT generic interface marshalling, refines the design for runtime callable wrappers (RCWs) and COM callable wrappers (CCWs), and clarifies the separation of type-specific and shared logic for generic interface marshalling. The changes introduce new marshaller interfaces and attributes, update method signatures for improved clarity and correctness, and shift the implementation strategy to use shared runtime adapter types rather than generating per-type adapters.

RCW marshalling and generic interface design

  • Refactored the RCW base class to WindowsRuntimeEnumerator<T, TIIteratorMethods>, which is now generic over both the element type and a type-specific static interface for marshalling the Current method. The base class handles all IEnumerator<T> state management and semantics adaptation.
  • Split the "Methods" logic into a static abstract interface IIteratorMethodsImpl<T> for type-specific marshalling (only Current), and a shared static class IIteratorMethods for non-type-specific methods (HasCurrent, MoveNext).
  • Updated the generated RCW implementation (IEnumerator_stringNativeObject) to use the new generic base class and rely on the shared runtime logic, removing the need to override abstract methods.

Marshaller interfaces and attributes

  • Renamed and updated marshaller interfaces and attributes to clarify their roles: IWindowsRuntimeUnsealedComWrappersCallbackIWindowsRuntimeUnsealedObjectComWrappersCallback, and updated method signatures to return CreatedWrapperFlags for additional wrapper metadata. [1] [2] [3]
  • Updated marshaller attribute and callback implementations to use the new method signatures and fast-path logic, ensuring correct pointer handling and interface resolution. [1] [2]

CCW marshalling and runtime adapter strategy

  • Shifted the CCW adapter implementation to use a generic runtime type IEnumeratorAdapter<T> defined in WinRT.Runtime.dll, replacing the previous strategy of generating per-type adapters and tables. This adapter provides correct semantics adaptation and efficient instance management via a shared ConditionalWeakTable.
  • Updated documentation and example code to reflect the use of runtime-provided adapters and extension methods for type-specific operations, improving maintainability and reducing code generation complexity.

Vtable and method signature corrections

  • Corrected the vtable method signature for get_Current to use HSTRING* for string marshalling and updated the implementation to use the shared runtime adapter and marshaller.

These changes clarify the separation of type-specific and shared logic, improve marshalling correctness, and simplify the code generation and runtime infrastructure for generic interface support in CsWinRT.

Rename and clarify marshalling APIs and generics in documentation: - Arrays: rename WindowsRuntimeArrayMarshaller.ConvertToManaged to UnboxToManaged and update marshaller attribute CreateObject to include CreatedWrapperFlags. - Generic interfaces: make WindowsRuntimeEnumerator generic on a methods implementation type (TIIteratorMethods) and expose HasUnwrappableNativeObjectReference; split type-specific Current into IIteratorMethodsImpl<T> and keep non-generic IIteratorMethods for shared methods. - Rename and extend unsealed object callback API to IWindowsRuntimeUnsealedObjectComWrappersCallback, adding TryCreateObject/CreateObject overloads that return wrapperFlags; update WindowsRuntimeUnsealedObjectMarshaller callback constraint. - RCW/WinRT.Interop changes: generate IIterator_stringMethods implementing IIteratorMethodsImpl<string>, simplify forwarding via non-generic methods types, produce native object types that use the generic base (WindowsRuntimeEnumerator<T, TIIteratorMethods>) and new ComWrappers callback signatures including wrapperFlags and wrapperObject. - CCW/adapter changes: describe a generic IEnumeratorAdapter<T> in the runtime with a ConditionalWeakTable-backed GetInstance, and update CCW vtable patterns to obtain adapters for semantics adjustments. - Misc: update marshaller use to WindowsRuntimeInterfaceMarshaller<T> and various explanatory clarifications throughout the documents.
Replace WindowsRuntimeObjectReference.AsUnsafe with the updated CreateUnsafe API and implement actual marshalling for IEnumerator<T>.Current by calling HStringMarshaller.ConvertToUnmanaged instead of the placeholder. This updates the marshaller to use the new unsafe constructor and provides concrete HSTRING conversion for string enumeration interop.
Update marshalling example to use WindowsRuntimeObjectReference.Create instead of CreateUnsafe and remove the unused ComputeVtables stub. Expand the accompanying explanation to clarify that Create performs a QueryInterface on an opaque IInspectable pointer (required here), while CreateUnsafe assumes the pointer already targets the requested interface and only increments the ref count — which is safe for the ComWrappers TryCreateObject fast path.
@Sergio0694 Sergio0694 requested a review from manodasanW March 4, 2026 00:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant