Windows Kernel Handles API Reference

Handles API Reference

This section provides documentation for the Windows Kernel Handles API, which allows developers to interact with and manage various system objects through their unique identifiers, known as handles.

What are Handles?

A handle is a system-defined value that identifies a system resource. The operating system uses handles to manage access to objects such as files, processes, threads, windows, and memory blocks. When an application requests access to a system resource, the system creates an entry in a handle table and returns a handle to the application. The application then uses this handle to refer to the resource in subsequent operations.

Handle Management Functions

`CloseHandle`

BOOL CloseHandle(
HANDLE hObject
);

Closes an open object handle. This function decrements the handle count of the specified object and, if the count becomes zero, deletes the object’s entry from the system's object table.

hObject: [in] A handle to an open object.

Return value: If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.

`GetCurrentProcess`

HANDLE GetCurrentProcess(void);

Returns a pseudo handle for the current process. A pseudo handle is a special constant that, like a pointer, distinguishes between the current process and any other process, including the system.

Return value: The return value is a pseudo handle for the current process.

`GetCurrentThread`

HANDLE GetCurrentThread(void);

Returns a pseudo handle for the current thread. A pseudo handle is a special constant that, like a pointer, distinguishes between the current thread and any other thread.

Return value: The return value is a pseudo handle for the current thread.

`DuplicateHandle`

BOOL DuplicateHandle(
    HANDLE hSourceProcessHandle,
    HANDLE hSourceHandle,
    HANDLE hTargetProcessHandle,
    LPHANDLE lpTargetHandle,
    DWORD dwDesiredAccess,
    BOOL bInheritHandle,
    DWORD dwOptions
);

Duplicates an existing handle in the system. This enables a process to have access to the same object that another process has access to.

hSourceProcessHandle: [in] A handle to the process containing the handle to be duplicated.

hSourceHandle: [in] A handle to the handle to be duplicated.

hTargetProcessHandle: [in] A handle to the process that will receive the duplicated handle.

lpTargetHandle: [out] A pointer to a variable that receives the duplicated handle.

dwDesiredAccess: [in] The access rights for the new handle.

bInheritHandle: [in] If TRUE, the new handle is inherited by the child process of the target process.

dwOptions: [in] Options that affect the behavior of the handle duplication.

Return value: If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.

Key Concepts

Handle Table: A data structure maintained by the kernel for each process, mapping handles to object pointers.
Object Manager: The kernel component responsible for creating, managing, and protecting system objects.
Access Mask: A bitmask that specifies the desired access rights to an object.
Inheritance: The ability for a child process to inherit handles from its parent process.