Skip to content

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

Description

@antmor

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:

{ "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 More issues with SHGetFileInfo #2160 (the SHGetFileInfo all-or-nothing friendly-overload problem) when a PIDL out-param becomes a SafeHandle return.

Related: #2160

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions