`RAIIFree` implies `InvalidHandleValue`

[kennykerr]

Taking another stab at supporting RAIIFree in Rust, but the following structs have the RAIIFree attribute but lack at least one InvalidHandleValue attribute. Is that intentional? Are we meant to assume that zero is thus the invalid value?

• HIORING
• PTP_CLEANUP_GROUP
• PTP_POOL
• SOCKET

[kennykerr]

Conversely, there are many structs that have at least one InvalidHandleValue attribute but lack a corresponding RAIIFree attribute. Is that intentional?

• HCONN
• HCOMDB
• ADS_SEARCH_HANDLE
• HIFTIMESTAMPCHANGE
• HAMSICONTEXT
• HAMSISESSION
• JET_LS
• JET_OSSNAPID
• OLE_HANDLE
• HRSRC
• PSID
• HACCESSOR
• BCRYPT_ALG_HANDLE
• BCRYPT_HANDLE
• PRJ_DIR_ENTRY_BUFFER_HANDLE
• PRJ_NAMESPACE_VIRTUALIZATION_CONTEXT
• HCS_CALLBACK
• JET_API_PTR
• JET_HANDLE
• JET_INSTANCE
• JET_SESID
• JET_TABLEID
• HDC
• HGDIOBJ
• HMONITOR
• HCERTSTORE
• HCERTSTOREPROV
• HCRYPTPROV_LEGACY
• HCRYPTPROV_OR_NCRYPT_KEY_HANDLE
• NCRYPT_HANDLE
• NCRYPT_HASH_HANDLE
• NCRYPT_SECRET_HANDLE
• HIMC
• HIMCC
• HSAVEDUILANGUAGES
• CO_DEVICE_CATALOG_COOKIE
• CO_MTA_USAGE_COOKIE
• LPM_HANDLE
• RHANDLE
• HRASCONN
• HTASK
• HPSS
• HPSSWALK
• HACMDRIVER
• HACMDRIVERID
• HACMOBJ
• HACMSTREAM
• HMIDI
• HMIDIIN
• HMIDIOUT
• HMIDISTRM
• HMIXER
• HMIXEROBJ
• HWAVE
• HWAVEIN
• HWAVEOUT
• HCONV
• HCONVLIST
• HDDEDATA
• HSZ
• HTTP_PUSH_WAIT_HANDLE
• WEB_SOCKET_HANDLE
• HPTPROVIDER
• SERVICE_STATUS_HANDLE
• HRAWINPUT
• CF_CONNECTION_KEY
• FEATURE_STATE_CHANGE_SUBSCRIPTION
• FH_SERVICE_PIPE_HANDLE
• HWINWATCH
• PFLT_CONTEXT
• HGESTUREINFO
• HTOUCHINPUT
• HRECOALT
• HRECOCONTEXT
• HRECOGNIZER
• HRECOLATTICE
• HRECOWORDLIST
• HDROP
• HPSXA
• HUIAEVENT
• HUIANODE
• HUIAPATTERNOBJECT
• HUIATEXTRANGE
• AUTHZ_ACCESS_CHECK_RESULTS_HANDLE
• AUTHZ_AUDIT_EVENT_HANDLE
• AUTHZ_AUDIT_EVENT_TYPE_HANDLE
• AUTHZ_CAP_CHANGE_SUBSCRIPTION_HANDLE
• AUTHZ_CLIENT_CONTEXT_HANDLE
• AUTHZ_RESOURCE_MANAGER_HANDLE
• AUTHZ_SECURITY_EVENT_PROVIDER_HANDLE
• HINTERACTIONCONTEXT
• HDPA
• HDSA
• HSYNTHETICPOINTERDEVICE
• DPI_AWARENESS_CONTEXT
• HANDLE_SDP_TYPE
• DHPDEV
• DHSURF
• HBM
• HDEV
• HDRVOBJ
• HFASTMUTEX
• HSURF
• HDIAGNOSTIC_DATA_QUERY_SESSION
• HDIAGNOSTIC_EVENT_CATEGORY_DESCRIPTION
• HDIAGNOSTIC_EVENT_PRODUCER_DESCRIPTION
• HDIAGNOSTIC_EVENT_TAG_DESCRIPTION
• HDIAGNOSTIC_RECORD
• HDIAGNOSTIC_REPORT
• NCRYPT_DESCRIPTOR_HANDLE
• NCRYPT_STREAM_HANDLE
• PSECURITY_DESCRIPTOR
• SAFER_LEVEL_HANDLE
• SC_HANDLE
• APARTMENT_SHUTDOWN_REGISTRATION_COOKIE
• HSTRING_BUFFER
• ROPARAMIIDHANDLE
• SPGRAMMARHANDLE
• SPPHRASEPROPERTYHANDLE
• SPPHRASERULEHANDLE
• SPRECOCONTEXTHANDLE
• SPRULEHANDLE
• SPSTATEHANDLE
• HCMNOTIFICATION
• SPTRANSITIONID
• SPWORDHANDLE
• HSWDEVICE
• HKL
• LPPROC_THREAD_ATTRIBUTE_LIST
• PTP_CALLBACK_INSTANCE
• PTP_IO
• PTP_TIMER
• PTP_WAIT
• PTP_WORK
• HDRVR
• HIC
• HMMIO
• HVIDEO
• HDWP

[riverar]

• HIORING

Disassembling kernelbase![...]::VerifyValidIoRingHandle reveals it returns INVALID_HANDLE_VALUE when provided -1 and 0, so will add that.

• PTP_CLEANUP_GROUP

Documented as an opaque struct pointer. We can minimally add 0 to the invalid handle value list here.

• PTP_POOL

Same as above.

• SOCKET

Will add -1 per INVALID_SOCKET.

[riverar]

Regarding the longer list of types that have InvalidHandleValue markings but not RAIIFree, this is just an artifact of the RAII effort not being complete. Will try to get those all covered.

Live checklist:

• [ ] HCONN (❌ Not own-able by application)
• [x] HCOMDB
• [ ] ADS_SEARCH_HANDLE (〰️Pending discussion on encoding IDirectorySearch::CloseSearchHandle)
• [x] HIFTIMESTAMPCHANGE
• [ ] HAMSICONTEXT (〰️Pending discussion on encoding AmsiUninitialize / AmsiCloseSession)
• [ ] HAMSISESSION (〰️Pending discussion on encoding AmsiUninitialize / AmsiCloseSession)
• [ ] JET_LS (❌ Arbitrary application-specific data)
• [ ] JET_OSSNAPID (❌ Lifetime managed through series of prepare, freeze, thaw, and end or abort functions)
• [ ] OLE_HANDLE (❌ Not own-able by application)
• [ ] HRSRC (❌ Not own-able by application)
• [x] PSID
• [ ] HACCESSOR (Pending discussion on encoding IAccessor::ReleaseAccessor)
• [x] BCRYPT_ALG_HANDLE (⚠️ Already existed)
• [x] BCRYPT_HANDLE
• [ ] PRJ_DIR_ENTRY_BUFFER_HANDLE (❌ Not own-able by application)
• [ ] PRJ_NAMESPACE_VIRTUALIZATION_CONTEXT (〰️ Needs further discussion PrjStopVirtualizing)
• [ ] HCS_CALLBACK (❌ Undocumented)
• [ ] JET_API_PTR (❌ Polymorphic, base handle type for JET_xxx handles)
• [ ] JET_HANDLE (〰️Pending discussion on encoding JetCloseFileInstance)
• [x] JET_INSTANCE
• [x] JET_SESID
• [ ] JET_TABLEID (〰️Pending discussion on encoding JetCloseTable)
• [ ] HDC (❌ Handle type too broad, handle can be passed into DeleteDC or ReleaseDC)
• [x] HGDIOBJ
• [ ] HMONITOR (❌ Not own-able by application)
• [ ] HCERTSTORE (❌ Has additional behavioral parameter)
• [ ] HCERTSTOREPROV (❌ Needs further callback semantics investigation CertStoreProvFreeFindCTL)
• [ ] HCRYPTPROV_LEGACY (❌ Unused and should always be NULL)
• [ ] HCRYPTPROV_OR_NCRYPT_KEY_HANDLE (❌ Polymorphic)
• [x] NCRYPT_HANDLE
• [ ] NCRYPT_HASH_HANDLE (❌ Needs further investigation)
• [ ] NCRYPT_SECRET_HANDLE (❌ Needs further investigation)
• [x] HIMC
• [ ] HIMCC (❌ Lifetime managed through ImmLockIMCC and ImmUnlockIMCC functions, needs closer investigation)
• [ ] HSAVEDUILANGUAGES (❌ Not own-able by application)
• [x] CO_DEVICE_CATALOG_COOKIE
• [x] CO_MTA_USAGE_COOKIE
• [x] LPM_HANDLE
• [ ] RHANDLE (❌ Undocumented)
• [ ] HRASCONN (❌ Handle type is too broad, RasHangUpA and RasHangUpW exist)
• [ ] HTASK
• [ ] HPSS
• [x] HPSSWALK
• [x] HACMDRIVER
• [ ] HACMDRIVERID (❌ Needs further investigation)
• [ ] HACMOBJ
• [x] HACMSTREAM
• [ ] HMIDI
• [x] HMIDIIN
• [x] HMIDIOUT
• [x] HMIDISTRM
• [x] HMIXER
• [ ] HMIXEROBJ (❌ Handle type too broad)
• [ ] HWAVE
• [x] HWAVEIN
• [x] HWAVEOUT
• [x] HCONV
• [x] HCONVLIST
• [x] HDDEDATA
• [ ] HSZ
• [ ] HTTP_PUSH_WAIT_HANDLE
• [x] WEB_SOCKET_HANDLE
• [x] HPTPROVIDER
• [ ] SERVICE_STATUS_HANDLE
• [ ] HRAWINPUT (❌ Not own-able by application)
• [x] CF_CONNECTION_KEY
• [x] FEATURE_STATE_CHANGE_SUBSCRIPTION
• [x] FH_SERVICE_PIPE_HANDLE
• [ ] HWINWATCH
• [ ] PFLT_CONTEXT (❌ Further investigation needed within WDK context)
• [x] HGESTUREINFO
• [x] HTOUCHINPUT
• [x] HRECOALT
• [x] HRECOCONTEXT
• [x] HRECOGNIZER
• [ ] HRECOLATTICE (❌ Needs further investigation)
• [x] HRECOWORDLIST
• [ ] HDROP (❌ Not own-able by application)
• [x] HPSXA
• [x] HUIAEVENT
• [x] HUIANODE
• [x] HUIAPATTERNOBJECT
• [x] HUIATEXTRANGE
• [x] AUTHZ_ACCESS_CHECK_RESULTS_HANDLE
• [x] AUTHZ_AUDIT_EVENT_HANDLE
• [ ] AUTHZ_AUDIT_EVENT_TYPE_HANDLE (❌ Needs further investigation)
• [x] AUTHZ_CAP_CHANGE_SUBSCRIPTION_HANDLE
• [x] AUTHZ_CLIENT_CONTEXT_HANDLE
• [x] AUTHZ_RESOURCE_MANAGER_HANDLE
• [ ] AUTHZ_SECURITY_EVENT_PROVIDER_HANDLE (〰️Pending discussion on backwards params AuthzUnregisterSecurityEventSource)
• [x] HINTERACTIONCONTEXT
• [x] HDPA
• [x] HDSA
• [x] HSYNTHETICPOINTERDEVICE
• [ ] DPI_AWARENESS_CONTEXT (❌ Needs further investigation)
• [ ] HANDLE_SDP_TYPE (❌ Needs further investigation)
• [ ] DHPDEV (❌ Driver-defined device instance information)
• [ ] DHSURF (❌ Further investigation needed within WDK context)
• [ ] HBM (❌ Further investigation needed within WDK context)
• [ ] HDEV (❌ Further investigation needed within WDK context)
• [ ] HDRVOBJ (❌ Further investigation needed within WDK context)
• [ ] HFASTMUTEX (❌ Further investigation needed within WDK context)
• [ ] HSURF (❌ Further investigation needed within WDK context)
• [x] HDIAGNOSTIC_DATA_QUERY_SESSION
• [x] HDIAGNOSTIC_EVENT_CATEGORY_DESCRIPTION
• [x] HDIAGNOSTIC_EVENT_PRODUCER_DESCRIPTION
• [x] HDIAGNOSTIC_EVENT_TAG_DESCRIPTION
• [x] HDIAGNOSTIC_RECORD
• [x] HDIAGNOSTIC_REPORT
• [ ] NCRYPT_DESCRIPTOR_HANDLE (❌ Needs further investigation)
• [ ] NCRYPT_STREAM_HANDLE (❌ Needs further investigation)
• [ ] PSECURITY_DESCRIPTOR (❌ Needs further investigation)
• [ ] SAFER_LEVEL_HANDLE (❌ Needs further investigation)
• [x] SC_HANDLE (⚠️ Already existed)
• [ ] APARTMENT_SHUTDOWN_REGISTRATION_COOKIE
• [x] HSTRING_BUFFER
• [x] ROPARAMIIDHANDLE
• [ ] SPGRAMMARHANDLE (❌ Further investigation needed within Microsoft Speech API context)
• [ ] SPPHRASEPROPERTYHANDLE (❌ Further investigation needed within Microsoft Speech API context)
• [ ] SPPHRASERULEHANDLE (❌ Further investigation needed within Microsoft Speech API context)
• [ ] SPRECOCONTEXTHANDLE (❌ Further investigation needed within Microsoft Speech API context)
• [ ] SPRULEHANDLE (❌ Further investigation needed within Microsoft Speech API context)
• [ ] SPSTATEHANDLE (❌ Further investigation needed within Microsoft Speech API context)
• [x] HCMNOTIFICATION
• [ ] SPTRANSITIONID (❌ Further investigation needed within Microsoft Speech API context)
• [ ] SPWORDHANDLE (❌ Further investigation needed within Microsoft Speech API context)
• [x] HSWDEVICE
• [x] HKL
• [x] LPPROC_THREAD_ATTRIBUTE_LIST
• [ ] PTP_CALLBACK_INSTANCE (❌ Not own-able by application)
• [x] PTP_IO
• [x] PTP_TIMER
• [x] PTP_WAIT
• [x] PTP_WORK
• [ ] HDRVR (❌ Further investigation needed, complex free via CloseDriver)
• [x] HIC
• [ ] HMMIO (❌ Further investigation needed, complex free via mmioClose)
• [ ] HVIDEO (❌ Further investigation needed within Media Foundation context)
• [ ] HDWP (❌ Not own-able by application)