Add RAII for PIDL types (BSTR-style) and FreeWith(CoTaskMemFree) for CoTaskMem string out-params

[antmor]

Summary

Two related improvements so CsWin32 consumers get RAII/free guidance for shell PIDLs and CoTaskMem-allocated strings instead of hand-rolling cleanup.

1. PIDL RAII (autoTypes.json) - BSTR-style typedef

Model PIDLIST_RELATIVE, PIDLIST_ABSOLUTE, and PITEMID_CHILD as NativeTypedef handles following the BSTR precedent (a distinct typedef wrapping its real pointee, char*, with a CloseApi):

{ "Name": "PIDLIST_ABSOLUTE", "ValueType": "Windows.Win32.UI.Shell.Common.ITEMIDLIST*", "CloseApi": "CoTaskMemFree", "AlsoUsableFor": "PIDLIST_RELATIVE", "NativeTypedef": true }

• Keeps the strong ITEMIDLIST* pointee (no void*), analogous to BSTR's char*.
• CloseApi = CoTaskMemFree -> CsWin32 generates a SafeHandle.
• AlsoUsableFor links absolute/child to relative (as HMODULE/HINSTANCE do).
• Namespace is inherited from the CloseApi (as BSTR/HANDLE do).

2. FreeWith(CoTaskMemFree) for CoTaskMem string out-params (emitter.settings.rsp)

The unique_cotaskmem_string cases - PWSTR/LPOLESTR out-params that must be freed with CoTaskMemFree, mirroring the existing SHGetKnownFolderPath::ppszPath precedent:

• SHGetNameFromIDList::ppszName
• StringFromCLSID::lplpsz
• StringFromIID::lplpsz
• IShellItem::GetDisplayName::ppszName

Open questions / please validate in CI

1. Struct-pointer ValueType (ITEMIDLIST*) has no existing precedent (all current entries use primitives/void*/IntPtr). Confirm the generator/emitter accepts a fully-qualified struct-pointer payload.
2. CoTaskMemFree namespace: if it resolves to multiple namespaces the same-namespace check throws; also inheriting System.Com relocates the PIDL typedefs from UI.Shell.Common - the winmd baseline diff will show this. If undesirable, alternatives are an explicit Namespace or using ILFree (fewer partitions).

Testing

Local DoAll.ps1 scrape is blocked in my environment by a VS 2026 / MSVC 14.51 vs pinned libclang 17 mismatch (__builtin_verbose_trap), unrelated to this change. Relying on CI (pr-validation) for the winmd/API diff.

[Jevan Saks (jevansaks)]

Thanks for the contribution antmor! I see this is still a draft, are you still working on this? Did you want feedback on it?

[github-actions]

📋 API Surface Diff

+38 additions / -8 deletions vs main branch (full validation run)

Click to expand API diff

diff --git "a/bin\\baseline.apidump.cs" "b/bin\\current.apidump.cs"
index 955e3d9f..8bff2913 100644
--- "a/bin\\baseline.apidump.cs"
+++ "b/bin\\current.apidump.cs"
@@ -636669,7 +636669,7 @@ public static class Apis
 	[DllImport ("OLE32.dll", ExactSpelling = true, PreserveSig = false)]
 	[SupportedOSPlatform ("windows5.0")]
 	[Documentation ("https://learn.microsoft.com/windows/win32/api/combaseapi/nf-combaseapi-stringfromclsid")]
-	public unsafe static extern HRESULT StringFromCLSID ([In][Const] Guid* rclsid, [Out] PWSTR* lplpsz);
+	public unsafe static extern HRESULT StringFromCLSID ([In][Const] Guid* rclsid, [Out][FreeWith ("CoTaskMemFree")] PWSTR* lplpsz);
 
 	[DllImport ("OLE32.dll", ExactSpelling = true, PreserveSig = false)]
 	[SupportedOSPlatform ("windows5.0")]
@@ -636679,7 +636679,7 @@ public static class Apis
 	[DllImport ("OLE32.dll", ExactSpelling = true, PreserveSig = false)]
 	[SupportedOSPlatform ("windows5.0")]
 	[Documentation ("https://learn.microsoft.com/windows/win32/api/combaseapi/nf-combaseapi-stringfromiid")]
-	public unsafe static extern HRESULT StringFromIID ([In][Const] Guid* rclsid, [Out] PWSTR* lplpsz);
+	public unsafe static extern HRESULT StringFromIID ([In][Const] Guid* rclsid, [Out][FreeWith ("CoTaskMemFree")] PWSTR* lplpsz);
 
 	[DllImport ("OLE32.dll", ExactSpelling = true, PreserveSig = false)]
 	[SupportedOSPlatform ("windows5.0")]
@@ -889878,7 +889878,7 @@ public static class Apis
 	[DllImport ("SHELL32.dll", ExactSpelling = true, PreserveSig = false)]
 	[SupportedOSPlatform ("windows6.0.6000")]
 	[Documentation ("https://learn.microsoft.com/windows/win32/api/shobjidl_core/nf-shobjidl_core-shgetnamefromidlist")]
-	public unsafe static extern HRESULT SHGetNameFromIDList ([In] ITEMIDLIST* pidl, [In] SIGDN sigdnName, [Out] PWSTR* ppszName);
+	public unsafe static extern HRESULT SHGetNameFromIDList ([In] ITEMIDLIST* pidl, [In] SIGDN sigdnName, [Out][FreeWith ("CoTaskMemFree")] PWSTR* ppszName);
 
 	[DllImport ("SHELL32.dll", ExactSpelling = true, PreserveSig = false)]
 	[SupportedOSPlatform ("windows6.1")]
@@ -890031,11 +890031,6 @@ public static class Apis
 	[Documentation ("https://learn.microsoft.com/windows/win32/api/shlobj_core/nf-shlobj_core-ilcombine")]
 	public unsafe static extern ITEMIDLIST* ILCombine ([Optional][In] ITEMIDLIST* pidl1, [Optional][In] ITEMIDLIST* pidl2);
 
-	[DllImport ("SHELL32.dll", ExactSpelling = true, PreserveSig = false)]
-	[SupportedOSPlatform ("windows5.1.2600")]
-	[Documentation ("https://learn.microsoft.com/windows/win32/api/shlobj_core/nf-shlobj_core-ilfree")]
-	public unsafe static extern void ILFree ([Optional][In] ITEMIDLIST* pidl);
-
 	[DllImport ("SHELL32.dll", ExactSpelling = true, PreserveSig = false)]
 	[SupportedOSPlatform ("windows5.1.2600")]
 	[Documentation ("https://learn.microsoft.com/windows/win32/api/shlobj_core/nf-shlobj_core-ilgetnext")]
@@ -894467,6 +894462,7 @@ public enum CommandStateChangeConstants
 // ═══════════════════════════════════════════════════════════════
 
 using System.Runtime.InteropServices;
+using Windows.Win32.Foundation.Metadata;
 
 namespace Windows.Win32.UI.Shell.Common;
 
@@ -894486,6 +894482,11 @@ public static class Apis
 	public const uint PERCEIVEDFLAG_WMSDK = 32u;
 
 	public const uint PERCEIVEDFLAG_ZIPFOLDER = 64u;
+
+	[DllImport ("SHELL32.dll", ExactSpelling = true, PreserveSig = false)]
+	[SupportedOSPlatform ("windows5.1.2600")]
+	[Documentation ("https://learn.microsoft.com/windows/win32/api/shlobj_core/nf-shlobj_core-ilfree")]
+	public unsafe static extern void ILFree ([Optional][In] ITEMIDLIST* pidl);
 }
 
 using Windows.Win32.Foundation;
@@ -894615,6 +894616,44 @@ using Windows.Win32.Foundation.Metadata;
 
 namespace Windows.Win32.UI.Shell.Common;
 
+[RAIIFree ("ILFree")]
+[AlsoUsableFor ("PIDLIST_RELATIVE")]
+[InvalidHandleValue (0L)]
+[NativeTypedef]
+public struct PIDLIST_ABSOLUTE
+{
+	public unsafe ITEMIDLIST* Value;
+}
+
+using Windows.Win32.Foundation.Metadata;
+
+namespace Windows.Win32.UI.Shell.Common;
+
+[RAIIFree ("ILFree")]
+[InvalidHandleValue (0L)]
+[NativeTypedef]
+public struct PIDLIST_RELATIVE
+{
+	public unsafe ITEMIDLIST* Value;
+}
+
+using Windows.Win32.Foundation.Metadata;
+
+namespace Windows.Win32.UI.Shell.Common;
+
+[RAIIFree ("ILFree")]
+[AlsoUsableFor ("PIDLIST_RELATIVE")]
+[InvalidHandleValue (0L)]
+[NativeTypedef]
+public struct PITEMID_CHILD
+{
+	public unsafe ITEMIDLIST* Value;
+}
+
+using Windows.Win32.Foundation.Metadata;
+
+namespace Windows.Win32.UI.Shell.Common;
+
 [Documentation ("https://learn.microsoft.com/windows/win32/api/shtypes/ne-shtypes-shcolstate")]
 public enum SHCOLSTATE
 {
@@ -904145,7 +904184,7 @@ public interface IShellItem : IUnknown
 	unsafe HRESULT GetParent ([Out] IShellItem* ppsi);
 
 	[Documentation ("https://learn.microsoft.com/windows/win32/api/shobjidl_core/nf-shobjidl_core-ishellitem-getdisplayname")]
-	unsafe HRESULT GetDisplayName ([In] SIGDN sigdnName, [Out] PWSTR* ppszName);
+	unsafe HRESULT GetDisplayName ([In] SIGDN sigdnName, [Out][FreeWith ("CoTaskMemFree")] PWSTR* ppszName);
 
 	[Documentation ("https://learn.microsoft.com/windows/win32/api/shobjidl_core/nf-shobjidl_core-ishellitem-getattributes")]
 	unsafe HRESULT GetAttributes ([In] SFGAO_FLAGS sfgaoMask, [Out] SFGAO_FLAGS* psfgaoAttribs);

This comment is automatically updated on each push.