Skip to content

Generate generic <T> overloads for IID_PPV_ARGS pattern on COM methods - #1720

Merged
Jevan Saks (jevansaks) merged 1 commit into
mainfrom
user/jevansa/iid-ppv-args-generic-overloads
Jun 11, 2026
Merged

Jevan Saks (jevansaks) merged 1 commit into
mainfrom
user/jevansa/iid-ppv-args-generic-overloads

Conversation

@jevansaks

@jevansaks Jevan Saks (jevansaks) commented Jun 10, 2026

Copy link
Copy Markdown
Member

Summary

Auto-detect COM methods with the IID_PPV_ARGS pattern (a Guid* parameter immediately followed by a void** [ComOutPtr] parameter) and generate generic <T> overloads where the GUID is derived from typeof(T).GUID and the output pointer is typed as T.

Closes #374
Fixes #1604

Example

Before — callers must construct and pass the IID manually:

shellItem.BindToHandler(pbc, in bhid, typeof(IStream).GUID, out object streamObj);
IStream stream = (IStream)streamObj;

After — the generic overload handles it:

shellItem.BindToHandler<IStream>(pbc, in bhid, out IStream stream);

Generated overload shapes

Mode Signature Constraint
Marshaling (AllowMarshaling=true) BindToHandler<T>(..., out T ppv) where T : class
Non-marshaling (AllowMarshaling=false) BindToHandler<T>(..., out T* ppv) where T : unmanaged

Changes

  • GeneratorOptions.cs — Added FriendlyOverloadOptions.ComOutPtrGenericOverloads (default true)
  • settings.schema.json — Added friendlyOverloads.comOutPtrGenericOverloads for opt-out
  • Generator.cs / Generator.Invariants.cs — Extract IUnknownHelperMethods template method names to avoid duplicating QueryInterface<T>
  • Generator.FriendlyOverloads.cs — Pattern detection (DeclareComOutPtrGenericOverloads) and code generation (BuildComOutPtrGenericOverload)
  • COMTests.cs — 5 new tests for marshaling/non-marshaling, opt-out, template precedence, and IntPtr mode

Design decisions

  • Only matches void** (not typed pointers like ID2D1Effect**) — typed outputs already have their specific type
  • One IID_PPV_ARGS pair per method max to avoid overload explosion
  • CoCreateInstance<T> template retained for co-creatable class CreateInstance<T> integration
  • Template-based overloads take precedence over pattern-based ones
  • Skipped when UseIntPtrForComOutPointers is active (ppv is IntPtr, not castable)

@jevansaks Jevan Saks (jevansaks) added the enhancement New feature or request label Jun 10, 2026
@jevansaks
Jevan Saks (jevansaks) force-pushed the user/jevansa/iid-ppv-args-generic-overloads branch 5 times, most recently from d327d2b to 422814f Compare June 10, 2026 23:51
Auto-detect COM methods with the IID_PPV_ARGS pattern (a Guid* parameter
immediately followed by a void** [ComOutPtr] parameter) and generate
generic <T> overloads where the GUID is derived from typeof(T).GUID and
the output pointer is typed as T.

For marshaling mode: out T ppv where T : class
For non-marshaling mode: out T* ppv where T : unmanaged

Added friendlyOverloads.comOutPtrGenericOverloads option (default true)
to nativemethods.json for opt-out.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@jevansaks
Jevan Saks (jevansaks) force-pushed the user/jevansa/iid-ppv-args-generic-overloads branch from 422814f to 52643a7 Compare June 11, 2026 00:11
@jevansaks
Jevan Saks (jevansaks) marked this pull request as ready for review June 11, 2026 01:19
@jevansaks
Jevan Saks (jevansaks) merged commit f8e8367 into main Jun 11, 2026
19 checks passed
@jevansaks
Jevan Saks (jevansaks) deleted the user/jevansa/iid-ppv-args-generic-overloads branch June 11, 2026 17:18
This was referenced Sep 3, 2026
This was referenced Sep 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

2 participants