SetHandleInformation

Handle API


                    BOOL SetHandleInformation(

                      HANDLE hObject,

                      HANDLE_INFORMATION_CLASS HandleInformationClass,

                      ULONG_PTR dwInformation

                    );

The SetHandleInformation function enables or disables certain properties of an open handle to a kernel object.

Parameters

Parameter	Type	Description
`hObject`	`HANDLE`	A handle to the kernel object whose information is to be modified.
`HandleInformationClass`	`HANDLE_INFORMATION_CLASS`	The type of information to set. This parameter can be one of the following values: `HANDLE_FLAG_INHERIT`: The system will pass the handle to child processes if the process handle is inherited. `HANDLE_FLAG_PROTECT_FROM_CLOSE`: The handle cannot be closed by calling the `CloseHandle` function.
`dwInformation`	`ULONG_PTR`	A value that specifies the new setting for the handle information. If `HandleInformationClass` is `HANDLE_FLAG_INHERIT`, then `dwInformation` is a Boolean value: `TRUE` to enable inheritance, `FALSE` to disable it. If `HandleInformationClass` is `HANDLE_FLAG_PROTECT_FROM_CLOSE`, then `dwInformation` is a Boolean value: `TRUE` to protect the handle from closing, `FALSE` to allow closing.

Return Value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

This function is used to manage handle inheritance and to prevent accidental closure of critical handles.

When HANDLE_FLAG_PROTECT_FROM_CLOSE is set to TRUE, the handle can only be implicitly closed when the process terminates. Explicit calls to CloseHandle will fail.

Examples

Disabling Handle Inheritance

#include <windows.h>

int main() {
    HANDLE hFile = CreateFile(L"example.txt", GENERIC_READ, FILE_SHARE_READ, NULL, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL, NULL);

    if (hFile != INVALID_HANDLE_VALUE) {
        // Disable inheritance for the file handle
        if (SetHandleInformation(hFile, HANDLE_FLAG_INHERIT, FALSE)) {
            // Handle inheritance is now disabled
        } else {
            // Handle error
        }
        CloseHandle(hFile);
    }
    return 0;
}

Protecting a Handle from Closing

#include <windows.h>

int main() {
    HANDLE hEvent = CreateEvent(NULL, TRUE, FALSE, L"MyCriticalEvent");

    if (hEvent != NULL) {
        // Protect the event handle from accidental closure
        if (SetHandleInformation(hEvent, HANDLE_FLAG_PROTECT_FROM_CLOSE, TRUE)) {
            // Handle is now protected from closing
            // Note: You cannot call CloseHandle(hEvent) after this unless you first set protection to FALSE
        } else {
            // Handle error
        }
        // To close the handle later, you would first need to call:
        // SetHandleInformation(hEvent, HANDLE_FLAG_PROTECT_FROM_CLOSE, FALSE);
        // CloseHandle(hEvent);
    }
    return 0;
}

CloseHandle	Closes an open object handle.
DuplicateHandle	Duplicates an existing handle.
GetHandleInformation	Retrieves information about a handle.
HANDLE_INFORMATION_CLASS	Enumeration for handle information classes.

Windows API Reference