microsoft / microsoft/win32metadata

Add RAII (CloseApi) annotation for PIDL types (ITEMIDLIST) so CsWin32 generates an ILFree SafeHandle

Open
#2,275 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
C++
Stars
1.5k
Forks
149
Avg merge
5d 16h
Merged PRs (30d)
4

Description

### Problem
PIDLs (`PIDLIST_ABSOLUTE`, `PIDLIST_RELATIVE`, `PITEMID_CHILD` -> `ITEMIDLIST*`) are heap allocations that must be released with `ILFree` (`CoTaskMemFree`). Today they are projected as plain pointers with no RAII, so CsWin32 consumers must hand-roll a `SafeHandle`/`try-finally` around every `SHGetIDListFromObject`, `ILCreateFromPath`, `SHGetKnownFolderIDList`, etc. This is error-prone and inconsistent with how other free-based types are modeled.

### Precedent / pattern
`generation/WinSDK/autoTypes.json` already models pointer-typedefs-with-a-free-function. The closest precedent is **`BSTR`**:
```json
{ "Name": "BSTR", "ValueType": "char*", "CloseApi": "SysFreeString", "NativeTypedef": true }
```
`CloseApi` -> CsWin32 emits `[RAIIFree(...)]` -> generates a SafeHandle (per `docs/projections.md`, `NativeTypedefStructsCreator.cs`). Other free-based entries: `HLOCAL`->`LocalFree`, `HMODULE`->`FreeLibrary`, `HDDEDATA`->`DdeFreeDataHandle`.

### Proposed change
Add PIDL typedefs to `autoTypes.json` with `CloseApi: "ILFree/cotaskmemfree"`, generating e.g. `ILFreeSafeHandle`.

### Design questions for maintainers
1. `ILFree` takes `PIDLIST_RELATIVE`; should all three PIDL typedefs share one SafeHandle via `AlsoUsableFor` (as `HMODULE`/`HINSTANCE` do)?
2. These are `[wire_marshal]` typedefs (`typedef ITEMIDLIST_ABSOLUTE* PIDLIST_ABSOLUTE`) - does the scraper model them cleanly as `NativeTypedef`?
3. Interaction with #2160 (the `SHGetFileInfo` all-or-nothing friendly-overload problem) when a PIDL out-param becomes a SafeHandle return.

Related: #2160

Contributor guide

Open the contributing guide

Research direction

Start with generation/WinSDK/autoTypes.json and compare the BSTR, HLOCAL, HMODULE, and HDDEDATA entries. Read docs/projections.md and NativeTypedefStructsCreator.cs to understand CloseApi, NativeTypedef, and AlsoUsableFor, then assess the wire-marshal and #2160 questions. Done means the PIDL entries generate the intended shared or separate SafeHandle behavior without breaking affected out-parameter projections.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp, json
Domain
devtools, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.