Correct close function for FwpmEngineOpen0 handle

[DoctorKrolic]

Fixes: #2172

[jevansaks]

For handles that have domain-specific close functions, we generally follow this pattern to make sure that all projects can reliably generate proper safehandles. See https://github.com/microsoft/win32metadata/pull/2134/files for examples.

CC @riverar

[DoctorKrolic]

Can you please elaborate where is the destinction line? I've come to my original solution by searching for RAIIFree in the repo. In emitter.settings.rsp there are a bunch of entries, which specify close function like this, mostly when function returns a handle, but also several cases, where an output parameter is being annotated with it.

Where can I find invalid values for a handle? In linked PR you declare a domain-specific handle for function, which clearly says in the docs that if function fails INVALID_HANLDE is returned, which is -1 by definition of WinApi. I guess 0 comes since it is a common default for an integer value? In our case docs don't explicitly specify invalid handle values since it is returned by pointer, so NULL is obviously written to the pointer in case of a failure. What should we put for InvalidHandleValues then?

What does NativeTypedef mean in autoTypes.json?

[riverar]

I don't think any of the current projections (C#, Rust) do anything with RAIIFree attributes on method parameters.

Instead, we need to specialize the HANDLE (artificially) for this API. To do so, edit autoTypes.json and add something like:

  {
    "Name": "FWPM_ENGINE_HANDLE_0",
    "ValueType": "void*",
    "CloseApi": "FwpmEngineClose0",
    "InvalidHandleValues": [ -1, 0 ],
    "NativeTypedef": false // This indicates whether this was a real typedef in headers
                           // or an artificial one we created for metadata purposes
  },

Then edit emitter.settings.rsp and remap the engineHandle parameter types for all the Fwpm[...]0 APIs to our new artificial type:

...
FwpmEngineGetOption0::engineHandle=FWPM_ENGINE_HANDLE_0
FwpmEngineOpen0::engineHandle=FWPM_ENGINE_HANDLE_0
FwpmEngineClose0::engineHandle=FWPM_ENGINE_HANDLE_0
...
// You'll need to populate this with all Fwpm* APIs that use this engine handle
// https://learn.microsoft.com/windows/win32/api/fwpmu/

Be sure to pay close attention to _0 _1 and _2 APIs if you come across them. The APIs span multiple OS targets and must remain separate.

[DoctorKrolic]

@jevansaks @riverar PTAL

[riverar]

Reviewing this with fresh eyes, I'm torn whether FWPM_ENGINE_HANDLE_0 should be FWPM_ENGINE_HANDLE (since it's shared across all versions of FWPM), FWPM_ENGINE_HANDLE0 (matching other types in this header), or remain the same. Will defer to @jevansaks and co.

Looks good otherwise.

[DoctorKrolic]

Currently all functions accept the same handle since there is only on FwpmEngineOpen function that opens a session. The question to whether we need _0 suffix boils down to: if a new FwpmEngineOpen1 is theoretically introduced, will it produce other handle incompatible with the one opened with FwpmEngineOpen0 or only change other parameters? Given that this handle is used in pretty much every other function in this API group, I guess, this is extremely unlikely since it will automatically mean that almost the entire function set needs new versions just to accept new handle type. So let me change the name and remove the suffix. Adding it back with the new version of the handle if it happens is easier than just changing the name of existing API from the compatibility point of view

[jevansaks]

Agree with using the simpler name.