Introduction to Windows API

Handles

A HANDLE type is nothing more than a pointer. It is defined as a PVOID meaning a pointer to void (void * in C). How can something be a pointer to void? This is a way to say that the pointer returned can be of any type, depending on the function that returned it. Internally it is mapped to a specific kernel object that the user does not need to care about. Of course, that might make it a bit harder to understand which type of HANDLE needs to be passed to a function; however, the documentation does a decent job in explaining it. A couple of examples of functions returning a HANDLE are:

1
HANDLE OpenProcess(
2
  [in] DWORD dwDesiredAccess,
3
  [in] BOOL  bInheritHandle,
4
  [in] DWORD dwProcessId
5
);
6

7

8
HANDLE CreateMutexA(
9
  [in, optional] LPSECURITY_ATTRIBUTES lpMutexAttributes,
10
  [in]           BOOL                  bInitialOwner,
11
  [in, optional] LPCSTR                lpName
12
);
13

14

15
HANDLE CreateFileA(
16
  [in]           LPCSTR                lpFileName,
17
  [in]           DWORD                 dwDesiredAccess,
18
  [in]           DWORD                 dwShareMode,
19
  [in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes,
20
  [in]           DWORD                 dwCreationDisposition,
21
  [in]           DWORD                 dwFlagsAndAttributes,
22
  [in, optional] HANDLE                hTemplateFile
23
);

Three completely different meanings for the same object. Handles can be used to track down chains of execution; for example, if a sample opens multiple files and performs operations on them, the execution path might become hard to follow. However, looking at the HANDLE ID in the debugger usually helps.

Using a single unified object (HANDLE) for all the API calls that return a pointer type is a newer approach from Microsoft; previously, each function was returning a different HANDLE type, and some still do for backwards compatibility. For example RegCreateKeyExA 6, which returns a HKEY handle.

1
LSTATUS RegCreateKeyExA(
2
  [in]            HKEY                        hKey,
3
  [in]            LPCSTR                      lpSubKey,
4
                  DWORD                       Reserved,
5
  [in, optional]  LPSTR                       lpClass,
6
  [in]            DWORD                       dwOptions,
7
  [in]            REGSAM                      samDesired,
8
  [in, optional]  const LPSECURITY_ATTRIBUTES lpSecurityAttributes,
9
  [out]           PHKEY                       phkResult,
10
  [out, optional] LPDWORD                     lpdwDisposition
11
);

Once a handle is not needed anymore it is usually closed either with CloseHandle 7 or with a specific close function like InternetCloseHandle 8. There are some cases, like the HANDLE populated by EnumProcessModules that must not be closed, as specified in the documentation 9:

So, when encountering phrases like “a handle to a file” or “a handle to a process”, this can be read as “something that uniquely defines and points to the file/process”. It is possible to act on it; for example WriteFile 10 expects as first argument a HANDLE representing the file it can write to:

1
BOOL WriteFile(
2
  [in]                HANDLE       hFile,
3
  [in]                LPCVOID      lpBuffer,
4
  [in]                DWORD        nNumberOfBytesToWrite,
5
  [out, optional]     LPDWORD      lpNumberOfBytesWritten,
6
  [in, out, optional] LPOVERLAPPED lpOverlapped
7
);