Windows 10 系统编程

1.1.1. 谁应该阅读本书

1.1.2. 使用本书需要了解什么

1.1.3. 示例代码

1.2.1. Windows 架构概述

1. 进程
   

   进程是一个包含和管理对象, 代表程序的运行实例. “进程运行”这个术语经常被使用, 但并不准确. 进程不运行——进程进行管理. 线程才是执行代码并技术上运行的单位. 从高层次的角度来看, 一个进程拥有以下内容:

   • 一个可执行程序, 其中包含用于在进程内执行代码的初始代码和数据.
   • 一个私有的虚拟地址空间, 用于为进程内代码所需的任何目的分配内存.
   • 一个访问令牌 (有时称为*主令牌*), 这是一个存储进程默认安全上下文的对象, 由在进程内执行代码的线程使用 (除非线程通过模拟使用不同的令牌).
   • 一个到 Executive (内核) 对象的私有句柄表, 例如事件, 信号量和文件.
   • 一个或多个执行线程. 一个正常的 user-mode 进程创建时带有一个线程 (执行进程的主要入口点). 没有线程的 user-mode 进程基本上是无用的, 在正常情况下会被内核销毁.

   一个进程的这些元素如图 1-1 所示.

   

   Figure 1: 进程的重要组成部分

   一个进程由其进程 ID (Process ID) 唯一标识, 只要该内核进程对象存在, 该 ID 就保持唯一. 一旦它被销毁, 相同的 ID 可能会被新进程重用. 重要的是要认识到, 可执行文件本身并不是进程的唯一标识符. 例如, 可能同时有五个 `notepad.exe` 的实例在运行. 每个进程都有自己的地址空间, 自己的线程, 自己的句柄表, 自己唯一的进程 ID 等. 所有这五个进程都使用相同的镜像文件 (`notepad.exe`)作为它们的初始代码和数据. 图 1-2 显示了任务管理器“详细信息”选项卡的屏幕截图, 其中显示了五个 `Notepad.exe` 的实例, 每个都有自己的属性.

   

   Figure 2: notepad 的五个实例

2. 动态链接库
   

   动态链接库 (Dynamic Link Libraries, DLLs) 是可执行文件, 可以包含代码, 数据和资源 (至少其中之一). DLLs 在进程初始化时 (称为*静态链接*) 或之后显式请求时 (称为*动态链接*) 动态加载到进程中. 我们将在第 15 章更详细地探讨 DLLs. DLLs 不像可执行文件那样包含标准的 `main` 函数, 因此不能直接运行. DLLs 允许在多个使用相同 DLL 的进程之间共享其物理内存中的代码, 这对于存储在 `System32` 目录中的所有标准 Windows DLLs 都是如此. 其中一些 DLLs, 称为*子系统 DLLs*, 实现了已文档化的 Windows API, 这是本书的重点.

   图 1-3 显示了两个使用共享 DLL 的进程, 这些 DLL 映射到相同的物理 (和虚拟) 地址.

   

   Figure 3: 共享 DLLs 代码

3. 虚拟内存
   

   每个进程都有其自己的虚拟, 私有, 线性地址空间. 这个地址空间开始时是空的 (或接近空的, 因为可执行镜像和 `NtDll.Dll` 通常是首先被映射的). 一旦主 (第一个) 线程开始执行, 内存很可能会被分配, 更多的 DLLs 会被加载等等. 这个地址空间是私有的, 这意味着其他进程不能直接访问它. 地址空间范围从零开始 (尽管技术上地址的前 64KB 不能被分配), 一直到一个最大值, 这个最大值取决于进程的“位数” (32位或64位), 操作系统的“位数”和一个链接器标志, 如下所示:

   • 对于 32 位 Windows 系统上的 32 位进程, 进程地址空间大小默认为 2 GB.
   • 对于使用增加用户地址空间设置的 32 位 Windows 系统上的 32 位进程, 该进程地址空间大小可以大到 3 GB (取决于确切的设置). 要获得扩展的地址空间范围, 创建该进程的可执行文件必须在其头部用 `LARGEADDRESSAWARE` 链接器标志标记. 如果没有, 它仍然会被限制为 2 GB.
   • 对于 64 位进程 (自然是在 64 位 Windows 系统上), 地址空间大小为 8 TB (Windows 8及更早版本) 或 128 TB (Windows 8.1及更高版本).
   • 对于 64 位 Windows 系统上的 32 位进程, 如果可执行镜像链接了 `LARGEADDRESSAWARE` 标志, 则地址空间大小为 4 GB. 否则, 大小仍为 2 GB.

   `LARGEADDRESSAWARE` 标志的要求源于一个 2 GB 地址范围只需要 31 位, 留下了最高有效位 (MSB) 供应用程序使用. 指定此标志表示程序没有将第 31 位用于任何用途, 因此将该位设置为 1 (这会发生在地址大于 2 GB 的情况下) 不是问题.

   内存本身被称为 虚拟 内存, 这意味着地址范围与它在物理内存 (RAM) 中的确切位置之间存在间接关系. 进程中的缓冲区可能映射到物理内存, 或者可能暂时驻留在文件 (如页面文件) 中. “虚拟”一词指的是从执行的角度来看, 无需知道要访问的内存是否在 RAM 中; 如果内存确实映射到 RAM, CPU 将直接访问数据. 如果没有, CPU 将引发一个*页面错误*异常, 这将导致内存管理器的页面错误处理程序从相应的文件中获取数据, 将其复制到 RAM, 对映射缓冲区的页表条目进行必要的更改, 并指示 CPU 重试.

4. 线程
   

   实际执行代码的实体是线程. 线程包含在进程内, 使用进程暴露的资源来完成工作 (例如虚拟内存和内核对象的句柄). 线程拥有的最重要的属性如下:

   • 当前访问模式, 用户模式或内核模式.
   • 执行上下文, 包括处理器寄存器.
   • 一个栈, 用于局部变量分配和调用管理.
   • 线程局部存储 (TLS) 数组, 它提供了一种以统一访问语义存储线程私有数据的方法.
   • 基础优先级和当前 (动态) 优先级.
   • 处理器亲和性, 指示线程允许在哪些处理器上运行.

   线程最常见的状态有:

   • 运行中 - 当前正在 (逻辑) 处理器上执行代码.
   • 就绪 - 等待被调度执行, 因为所有相关处理器都繁忙或不可用.
   • 等待 - 等待某个事件发生才能继续. 一旦事件发生, 线程将移至*就绪*状态.

1.2.2. 通用系统架构

1.2.3. Windows 应用程序开发

1. 你的第一个应用程序
   

   本节描述了使用 Visual Studio 编写一个简单应用程序, 编译并成功运行它的基本知识. 如果你已经知道这些, 可以跳过本节.

   首先, 你需要安装适当的 Windows 开发工具. 以下是按顺序排列的软件简短列表:

   1. Visual Studio 2017 或 2019, 任何版本, 包括免费的社区版 (可从 https://visualstudio.microsoft.com/downloads/ 获取). 早期版本的 Visual Studio 也可以正常工作, 但通常最好使用最新版本, 因为这些版本包括编译器改进以及可用性增强. 在安装程序的主窗口中, 确保至少选择了*使用 C++ 的桌面开发*工作负载, 如图 1-5 所示.

   

   Figure 5: Visual Studio 安装程序主窗口

   1. Windows Software Development Kit (SDK) 是一个可选的安装项, 它提供 (可能) 更新的头文件和库, 以及各种工具.

   一旦安装了 Visual Studio 2017/2019, 运行它并选择创建一个新项目.

   • 在 Visual Studio 2017 中, 从菜单中选择 文件 / 新建项目…, 找到 C++ / 桌面 节点, 然后选择 Windows 控制台应用程序 项目模板, 如图 1-6 所示.
   • 在 Visual Studio 2019 中, 从启动窗口选择*创建新项目*, 分别在项目类型和语言中用 `console` 和 `C++` 进行筛选, 然后选择*控制台应用* (确保列出的语言是 C++). 这如图 1-7 所示.

   

   Figure 6: Visual Studio 2017 中的新项目对话框

   

   Figure 7: Visual Studio 2019 中的新项目对话框

   将项目命名为 `HelloWin`, 如果需要可以更改目标文件夹, 然后单击确定. 项目应该被创建, 并在编辑器中打开一个 `HelloWin.cpp` 文件, 其中包含一个最小的 `main` 函数.

   在文件顶部添加一个 `#include` 用于 `windows.h`:

   #include <windows.h>
   

   如果你的项目有预编译头 (每个 C/C++ 源文件的顶部都有一个 `#include "pch.h"`), 请将 `windows.h` 的 `#include` 添加到此文件中, 以便在第一次编译后, 后续的编译会更快.

   你也可以根据喜好将其包含在 C/C++ 文件中, 但该包含必须在 `pch.h` 包含之后.

   再添加一个 `#include` 用于 `stdio.h` 以便访问 `printf` 函数:

   #include <stdio.h>
   

   在第一个应用程序中, 我们将通过调用 `GetNativeSystemInfo` 函数来获取一些系统信息. 这是 `main` 函数的代码:

   int main() {
       SYSTEM_INFO si;
       ::GetNativeSystemInfo(&si);
   
       printf("Number of Logical Processors: %d\n", si.dwNumberOfProcessors);
       printf("Page size: %d Bytes\n", si.dwPageSize);
       printf("Processor Mask: 0x%p\n", (PVOID)si.dwActiveProcessorMask);
       printf("Minimum process address: 0x%p\n", si.lpMinimumApplicationAddress);
       printf("Maximum process address: 0x%p\n", si.lpMaximumApplicationAddress);
   
       return 0;
   }
   

   从*生成*菜单中, 选择*生成解决方案*来编译和链接项目 (技术上是解决方案中的所有项目). 一切都应该无错误地编译和链接. 按 `Ctrl+F5` 在不附加调试器的情况下启动可执行文件. (或者使用*调试*菜单并选择*开始执行(不调试)*). 应该会打开一个控制台窗口, 显示类似以下的输出:

   Number of Logical Processors: 12
   Page size: 4096 Bytes
   Processor Mask: 0x00000FFF
   Minimum process address: 0x00010000
   Maximum process address: 0x7FFEFFFF
   

   如果你通过按 F5 (调试菜单, 开始调试) 运行应用程序, 控制台窗口将出现并在应用程序退出时迅速消失. 使用 `Ctrl+F5` 会添加一个方便的“按任意键继续”提示, 让你在关闭窗口前查看控制台输出.

   Visual Studio 通常会创建两个解决方案平台 (x86 和 x64), 可以通过位于主工具栏中的解决方案平台组合框轻松切换. 默认情况下, x86 被选中, 这会产生上面的输出. 如果你将平台切换到 x64 并重新生成 (假设你正在运行 Intel/AMD 64 位版本的 Windows), 你会得到稍微不同的输出:

   Number of Logical Processors: 12
   Page size: 4096 Bytes
   Processor Mask: 0x0000000000000FFF
   Minimum process address: 0x0000000000010000
   Maximum process address: 0x00007FFFFFFEFFFF
   

   这些差异源于 64 位进程使用 8 字节大小的指针, 而 32 位进程使用 4 字节的指针. 来自 `SYSTEM<sub>INFO</sub>` 结构的地址空间地址信息被类型化为指针, 因此它们的大小因进程的“位数”而异. 我们将在本章后面的“32位 vs. 64位开发”部分更详细地讨论 32 位和 64 位开发.

   不用担心这个小应用程序呈现的信息的含义 (尽管其中一些是自解释的). 我们将在后面的章节中探讨这些术语.

   在上述代码中, 函数名前使用双冒号 `::GetNativeSystemInfo` 是为了强调该函数是 Windows API 的一部分, 而不是当前 C++ 类的某个成员函数. 在这个例子中, 这是显而易见的, 因为周围没有 C++ 类, 但这个约定将在全书中使用 (它还稍微加快了编译器的函数查找). 更多编码约定将在本章后面的“编码约定”部分描述.

1.2.4. 使用字符串

HANDLE CreateMutex(
    _In_opt_ LPSECURITY_ATTRIBUTES lpMutexAttributes,
    _In_     BOOL                  bInitialOwner,
    _In_opt_ LPCTSTR               lpName);

typedef LPCSTR LPCTSTR; // const char* (UNICODE not defined)
typedef LPCWSTR LPCTSTR; // const wchar_t* (UNICODE defined)

const char name1[] = "Hello";      // 6 bytes (including NULL terminator)
const wchar_t name2[] = L"Hello"; // 12 bytes (including UTF-16 NULL terminator)

HANDLE hMutex = ::CreateMutex(nullptr, FALSE, TEXT("MyMutex"));

1. C/C++ 运行时中的字符串
   

   C/C++ 运行时有两套用于操作字符串的函数. 经典的 (ASCII) 函数以“str”开头, 例如 `strlen`, `strcpy`, `strcat` 等, 但也有 Unicode 版本以“wcs”开头, 例如 `wcslen`, `wcscpy`, `wcscat` 等.

   与 Windows API 一样, 也有一套宏, 根据另一个编译常量 `<sub>UNICODE</sub>` (注意下划线) 扩展为 ASCII 或 Unicode 版本. 这些函数的前缀是“_tcs”. 所以我们有 `<sub>tcslen</sub>`, `<sub>tcscpy</sub>`, `<sub>tcscat</sub>` 等函数, 它们都使用 `TCHAR` 类型.

   Visual Studio 默认定义 `<sub>UNICODE</sub>` 常量, 所以如果我们使用“_tcs”函数, 我们会得到 Unicode 函数. 如果只定义了“UNICODE”常量中的一个, 那将非常奇怪, 所以要避免这种情况.

2. 字符串输出参数
   

   像 `CreateMutex` 那样将字符串作为输入传递给函数是非常常见的. 另一个常见的需求是以字符串的形式接收结果. Windows API 使用几种方式来传回字符串结果.

   第一种 (也是更常见的) 情况是客户端代码分配一个缓冲区来保存结果字符串, 并向 API 提供缓冲区的大小 (字符串可以容纳的最大大小), API 则将字符串写入到指定大小的缓冲区中. 一些 API 还会返回实际写入的字符数和/或如果缓冲区太小所需的字符数.

   考虑 `GetSystemDirectory` 函数, 定义如下:

   UINT GetSystemDirectory(
       _Out_ LPTSTR lpBuffer,
       _In_  UINT   uSize);
   

   该函数接受一个字符串缓冲区及其大小, 并返回写入的字符数. 请注意, 所有大小都是以*字符*为单位, 而不是字节, 这很方便. 函数在失败时返回零. 以下是一个示例用法 (暂时省略错误处理):

   WCHAR path[MAX_PATH];
   ::GetSystemDirectory(path, MAX_PATH);
   printf("System directory: %ws\n", path);
   

   不要被指针类型迷惑——`GetSystemDirectory` 的声明并不意味着你只提供一个指针. 相反, 你必须分配一个缓冲区并传递指向此缓冲区的指针.

   `MAX<sub>PATH</sub>` 在 Windows 头文件中定义为 260, 这是 Windows 中标准的最大路径长度 (从 Windows 10 开始, 这个限制可以扩展, 我们将在第 11 章中看到). 注意 `printf` 使用 `%ws` 作为字符串格式来指示它是一个 Unicode 字符串, 因为 `UNICODE` 默认是定义的, 所以所有字符串都是 Unicode.

   第二种常见情况是客户端代码只提供一个字符串指针 (通过其地址), API 本身分配内存并将结果指针放入提供的变量中. 这意味着客户端代码有责任在不再需要结果字符串时释放内存. 关键在于使用正确的函数来释放内存. API 的文档会指明使用哪个函数. 以下是使用 `FormatMessage` 函数的一个例子, 其 Unicode 变体定义如下:

   DWORD FormatMessageW(
       _In_     DWORD   dwFlags,
       _In_opt_ LPCVOID lpSource,
       _In_     DWORD   dwMessageId,
       _In_     DWORD   dwLanguageId,
       _When_((dwFlags & FORMAT_MESSAGE_ALLOCATE_BUFFER) != 0, _At_((LPWSTR*)lpBuffer, _Outptr_result_z_))
       _When_((dwFlags & FORMAT_MESSAGE_ALLOCATE_BUFFER) == 0, _Out_writes_z_(nSize))
                LPWSTR  lpBuffer,
       _In_     DWORD   nSize,
       _In_opt_ va_list *Arguments);
   

   看起来很吓人, 对吧? 我特意包含了这个函数的完整 SAL 注解, 因为 `lpBuffer` 参数很棘手. `FormatMessage` 返回一个错误号的字符串表示 (我们将在本章后面的“API 错误”部分更详细地讨论错误). 该函数很灵活, 因为它可以自己分配字符串, 或者让客户端提供一个缓冲区来保存结果字符串. 实际行为取决于第一个 `dwFlags` 参数: 如果它包含 `FORMAT<sub>MESSAGEALLOCATEBUFFER</sub>` 标志, 函数将分配正确大小的缓冲区. 如果没有该标志, 则由调用者提供存储返回字符串的空间.

   所有这些使得函数有点棘手, 至少因为如果选择了前一个选项, 指针类型应该是 `LPWSTR*`——也就是说, 一个指向指针的指针, 由函数填充. 这需要一个难看的转换来让编译器满意.

   以下是一个简单的 `main` 函数, 它接受命令行参数中的错误号, 并显示其字符串表示 (如果有的话). 它使用了让函数自己分配的选项.

   int main(int argc, const char* argv[]) {
       if (argc < 2) {
           printf("Usage: ShowError <number>\n");
           return 0;
       }
   
       int message = atoi(argv);
   
       LPWSTR text;
       DWORD chars = ::FormatMessage(
           FORMAT_MESSAGE_ALLOCATE_BUFFER |    // function allocates
           FORMAT_MESSAGE_FROM_SYSTEM |
           FORMAT_MESSAGE_IGNORE_INSERTS,
           nullptr, message, 0,
           (LPWSTR)&text,                      // ugly cast
           0, nullptr);
   
       if (chars > 0) {
           printf("Message %d: %ws\n", message, text);
           ::LocalFree(text);
       }
       else {
           printf("No such error exists\n");
       }
       return 0;
   }
   

   完整的项目名为 `ShowError`, 位于本书的 Github 仓库中.

   请注意, 如果调用成功, 会调用 `LocalFree` 函数来释放字符串. `FormatMessage` 的文档说明这是释放缓冲区的函数.

   这是一个示例运行:

   C:\Dev\Win10SysProg\x64\Debug>ShowError.exe 2
   Message 2: The system cannot find the file specified.
   
   C:\Dev\Win10SysProg\x64\Debug>ShowError.exe 5
   Message 5: Access is denied.
   
   C:\Dev\Win10SysProg\x64\Debug>ShowError.exe 129
   Message 129: The %1 application cannot be run in Win32 mode.
   
   C:\Dev\Win10SysProg\x64\Debug>ShowError.exe 1999
   No such error exists
   

3. 安全字符串函数
   

   一些经典的 C/C++ 运行时字符串函数 (以及 Windows API 中的一些类似函数) 从安全性和可靠性的角度来看被认为不“安全”. 例如, `strcpy` 函数是有问题的, 因为它会复制源字符串到目标指针, 直到遇到 NULL 终止符. 这可能会溢出目标缓冲区, 在好的情况下导致崩溃 (例如, 缓冲区可能在栈上, 并破坏存储在那里的返回地址), 并被用作缓冲区溢出攻击, 其中一个备用返回地址被存储在栈上, 跳转到一个准备好的 shellcode.

   为了减轻这些潜在的漏洞, Microsoft 向 C/C++ 运行时库添加了一组“安全”的字符串函数, 其中使用一个额外的参数来指定目标缓冲区的最大大小, 因此它永远不会溢出. 这些函数有“_s”后缀, 例如 `strcpy<sub>s</sub>`, `wcscat<sub>s</sub>` 等.

   以下是使用这些函数的一些例子:

   void wmain(int argc, const wchar_t* argv[]) {
       // assume arc >= 2 for this demo
   
       WCHAR buffer;
       wcscpy_s(buffer, argv);    // C++ version aware of static buffers
   
       WCHAR* buffer2 = (WCHAR*)malloc(32 * sizeof(WCHAR));
       //wcscpy_s(buffer2, argv); // does not compile
       wcscpy_s(buffer2, 32, argv); // size in characters (not bytes)
   }
   

   最大大小总是以字符而不是字节指定. 另请注意, 如果目标缓冲区是静态分配的, 这些函数能够自动计算最大大小, 这很方便.

   另一组安全字符串函数也被添加到了 Windows API 中, 至少为了减少对 C/C++ 运行时的依赖. 这些函数在头文件 `<strsafe.h>` 中声明 (并实现). 它们是根据 Windows API 约定构建的, 其中函数实际上是扩展为带有“A”或“W”后缀的函数的宏. 以下是一些简单的用法示例 (使用与上面相同的声明):

   StringCchCopy(buffer, _countof(buffer), argv);
   StringCchCat(buffer, _countof(buffer), L"cat");
   
   StringCchCopy(buffer2, 32, argv);
   StringCchCat(buffer2, 32, L"cat");
   

   “Cch” 代表字符计数 (Count of Characters).

   注意这些函数没有能够处理静态分配缓冲区的 C++ 变体. 解决方案是使用 `<sub>countof</sub>` 宏, 该宏返回数组中的元素数量. 它的定义类似于 `sizeof(a)/sizeof(a[0])`, 给定一个数组 `a`.

   你应该使用哪一套函数? 这主要取决于个人喜好. 重要的是避免使用经典的, 不安全的函数. 如果你确实尝试使用它们, 你会得到一个类似这样的编译器错误:

   error C4996: 'wcscpy': This function or variable may be unsafe. Consider using wcscpy_s instead. To disable deprecation, use _CRT_SECURE_NO_WARNINGS. See online help for details.
   

   显然, 这个错误可以通过在包含 C/C++ 头文件之前定义 `<sub>CRTSECURENOWARNINGS</sub>` 来禁用, 但这是一个坏主意. 这个宏的存在是为了帮助维护与旧源代码的兼容性, 这些代码在用新编译器编译时不应被触动.

void* p = ...;
int value = (int)p;
// do something with value

void* p = ...;
INT_PTR value = (INT_PTR)p;
// do something with value

printf("Processor Mask: 0x%p\n", (PVOID)si.dwActiveProcessorMask);

#ifdef _WIN64
    printf("Processor Mask: 0x%016llX\n", si.dwActiveProcessorMask);
#else
    printf("Processor Mask: 0x%08X\n", si.dwActiveProcessorMask);
#endif

BOOL success = ::CallSomeAPIThatReturnsBOOL();
if(!success) {
    // error - handle it (just print it in this example)
    printf("Error: %d\n", ::GetLastError());
}

IGlobalInterfaceTable* pGit;
HRESULT hr = ::CoCreateInstance(CLSID_StdGlobalInterfaceTable, nullptr, CLSCTX_ALL,
    IID_IGlobalInterfaceTable, (void**)&pGit);
if(FAILED(hr)) {
    printf("Error: %08X\n", hr);
}
else {
    // do work
    pGit->Release(); // release interface pointer
}

typedef struct _OSVERSIONINFO {
    DWORD dwOSVersionInfoSize;
    DWORD dwMajorVersion;
    DWORD dwMinorVersion;
    DWORD dwBuildNumber;
    DWORD dwPlatformId;
    TCHAR szCSDVersion[ 128 ]; // Maintenance string for PSS usage
} OSVERSIONINFO, *POSVERSIONINFO, *LPOSVERSIONINFO;

BOOL GetVersionEx(
    _Inout_ POSVERSIONINFO pVersionInformation);

OSVERSIONINFO vi = { sizeof(vi) };
::GetVersionEx(&vi);

printf("Version: %d.%d.%d\n",
    vi.dwMajorVersion, vi.dwMinorVersion, vi.dwBuildNumber);

#define BUILD_WINDOWS
#include <Windows.h>

Version: 6.2.9200

OSVERSIONINFO vi = { sizeof(vi) };
::GetVersionEx(&vi);

if(vi.dwMajorVersion >= 5 && vi.dwMinorVersion >= 1) {
    // XP or later: good to go?
}

if(vi.dwMajorVersion > 5 || (vi.dwMajorVersion == 5 && vi.dwMinorVersion >= 1) {
    // XP or later: good to go!
}

<?xml version="1.0" encoding="utf-8"?>
<assembly manifestVersion="1.0" xmlns="urn:schemas-microsoft-com:asm.v1">
  <compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1">
    <application>
      <!-- Windows Vista -->
      <!--<supportedOS Id="{e2011457-1546-43c5-a5fe-008deee3d3f0}" />-->

      <!-- Windows 7 -->
      <!--<supportedOS Id="{35138b9a-5d96-4fbd-8e2d-a2440225f93a}" />-->

      <!-- Windows 8 -->
      <!--<supportedOS Id="{4a2f28e3-53b9-4441-ba9c-d69d4a4a6e38}" />-->

      <!-- Windows 8.1 -->
      <!--<supportedOS Id="{1f676c76-80e1-4239-95bb-83d0f6d0da78}" />-->

      <!-- Windows 10 -->
      <!--<supportedOS Id="{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a}" />-->
    </application>
  </compatibility>
</assembly>

Version: 6.3.9600

Version: 10.0.18362

1.3.1. 内核对象

1. 运行单个实例进程
   

   `ERROR<sub>ALREADYEXIST</sub>` 情况的一个相当众所周知的用法是限制一个可执行文件只有一个进程实例. 通常, 如果你在资源管理器中双击一个可执行文件, 就会基于该可执行文件生成一个新进程. 如果你重复此操作, 则会基于相同的可执行文件创建另一个进程. 如果你想阻止第二个进程启动, 或者至少让它在检测到同一可执行文件的另一个进程实例已在运行时关闭, 该怎么办.

   诀窍是使用一些命名的内核对象 (通常使用互斥体, 尽管任何命名的对象类型都可以代替使用), 其中创建了一个具有特定名称的对象. 如果该对象已存在, 则必须有另一个实例已在运行, 因此该进程可以关闭 (可能会通知其同胞这一事实).

   `SingleInstance` 演示应用程序演示了如何实现这一点. 这是一个基于 WTL 构建的对话框应用程序. 图 2-3 显示了此应用程序运行时的样子. 如果你尝试启动此应用程序的更多实例, 你会发现第一个窗口记录了来自新进程实例的消息, 然后该实例退出.

   在 `WinMain` 函数中, 我们首先创建互斥体. 如果失败, 那么说明出了很严重的问题, 我们就退出.

   HANDLE hMutex = ::CreateMutex(nullptr, FALSE, L"SingleInstanceMutex");
   if (!hMutex) {
       CString text;
       text.Format(L"Failed to create mutex (Error: %d)", ::GetLastError());
       ::MessageBox(nullptr, text, L"Single Instance", MB_OK);
       return 0;
   }
   

   创建互斥体失败应该极其罕见. 最可能的失败情况是另一个同名的内核对象 (不是互斥体) 已经存在.

   现在我们得到了一个正确的互斥体句柄, 唯一的问题是互斥体是实际创建的, 还是我们收到了一个到现有互斥体的另一个句柄 (大概是由这个可执行文件的先前实例创建的):

   if (::GetLastError() == ERROR_ALREADY_EXISTS) {
       NotifyOtherInstance();
       return 0;
   }
   

   如果在 `CreateMutex` 调用之前对象已存在, 那么我们调用一个辅助函数, 该函数向现有实例发送一些消息并退出. 这是 `NotifyOtherInstance`:

   #define WM_NOTIFY_INSTANCE (WM_USER + 100)
   
   void NotifyOtherInstance() {
       auto hWnd = ::FindWindow(nullptr, L"Single Instance");
       if (!hWnd) {
           ::MessageBox(nullptr, L"Failed to locate other instance window",
               L"Single Instance", MB_OK);
           return;
       }
   
       ::PostMessage(hWnd, WM_NOTIFY_INSTANCE, ::GetCurrentProcessId(), 0);
       ::ShowWindow(hWnd, SW_NORMAL);
       ::SetForegroundWindow(hWnd);
   }
   

   该函数使用 `FindWindow` 函数搜索现有窗口, 并使用窗口标题作为搜索条件. 这在一般情况下并不理想, 但对于此示例来说已经足够好.

   一旦找到窗口, 我们就向该窗口发送一个自定义消息, 并将当前进程 ID 作为参数. 这会显示在对话框的列表框中.

   谜题的最后一部分是由对话框处理 `WM<sub>NOTIFYINSTANCE</sub>` 消息. 在 WTL 中, 窗口消息使用宏映射到函数. `MainDlg.h` 中对话框类 (`CMainDlg`) 的消息映射重复如下:

   BEGIN_MSG_MAP(CMainDlg)
       MESSAGE_HANDLER(WM_NOTIFY_INSTANCE, OnNotifyInstance)
       MESSAGE_HANDLER(WM_INITDIALOG, OnInitDialog)
       COMMAND_ID_HANDLER(IDCANCEL, OnCancel)
   END_MSG_MAP()
   

   自定义消息映射到 `OnNotifyInstance` 成员函数, 实现如下:

   LRESULT CMainDlg::OnNotifyInstance(UINT, WPARAM wParam, LPARAM, BOOL &) {
       CString text;
       text.Format(L"Message from another instance (PID: %d)", wParam);
   
       AddText(text);
       return 0;
   }
   

   进程 ID 从 `wParam` 参数中提取出来, 并将一些文本添加到列表框中, 使用 `AddText` 辅助函数:

   void CMainDlg::AddText(PCWSTR text) {
       CTime dt = CTime::GetCurrentTime();
       m_List.AddString(dt.Format(L"%T") + L": " + text);
   }
   

   `m<sub>List</sub>` 是 `CListBox` 类型, 一个用于 Windows 列表框控件的 WTL 包装器.

2. 句柄
   

   如前一节所述, 句柄间接指向内核空间中的一个小数据结构, 该结构保存了该句柄的一些信息. 图 2-4 描绘了 32 位和 64 位系统上此数据结构的形态.

   

   Figure 11: 句柄条目

   在 32 位系统上, 此句柄条目大小为 8 字节, 在 64 位系统上为 16 字节 (技术上 12 字节就足够了, 但为了对齐目的扩展到 16 字节). 每个条目都包含以下成分:

   • 指向实际对象的指针. 由于低位用于标志和提高 CPU 访问时间的地址对齐, 对象的地址在 32 位系统上是 8 的倍数, 在 64 位系统上是 16 的倍数.
   • 访问掩码, 指示可以用此句柄做什么. 换句话说, 访问掩码是句柄的能力.
   • 三个标志: 继承 (Inheritance), 防止关闭 (Protect from close) 和关闭时审核 (Audit on close) (稍后讨论).

   访问掩码是一个位掩码, 其中每个“1”位指示可以使用该句柄执行的某个操作. 访问掩码在创建对象或打开现有对象时设置. 如果对象是创建的, 则调用者通常对对象拥有完全访问权限. 但如果对象是打开的, 调用者需要指定所需的访问掩码, 这可能会也可能不会得到.

   例如, 如果一个应用程序想要终止某个进程, 它必须首先调用 `OpenProcess` 函数, 以获取具有至少 `PROCESS<sub>TERMINATE</sub>` 访问掩码的所需进程的句柄, 否则无法用该句柄终止进程. 如果调用成功, 那么对 `TerminateProcess` 的调用就必定成功.

   以下是给定进程 ID 终止进程的示例:

   bool KillProcess(DWORD pid) {
       // open a powerful-enough handle to the process
       HANDLE hProcess = ::OpenProcess(PROCESS_TERMINATE, FALSE, pid);
       if (!hProcess)
           return false;
   
       // now kill it with some arbitrary exit code
       BOOL success = ::TerminateProcess(hProcess, 1);
   
       // close the handle
       ::CloseHandle(hProcess);
   
       return success != FALSE;
   }
   

   `OpenProcess` 函数具有以下原型:

   HANDLE OpenProcess(
       _In_ DWORD dwDesiredAccess,  // the access mask
       _In_ BOOL  bInheritHandle,   // inheritance flag
       _In_ DWORD dwProcessId);     // process ID
   

   由于这是一个 `Open` 操作, 所讨论的对象已经存在, 客户端需要指定它需要什么访问掩码来访问对象. 访问掩码有两种类型的访问位: 通用位和特定位. 我们将在第 16 章 (“安全性”) 中详细讨论这些细节. 进程的一个特定访问位是上面示例中使用的 `PROCESS<sub>TERMINATE</sub>`. 其他位包括 `PROCESS<sub>QUERYINFORMATION</sub>`, `PROCESS<sub>VMOPERATION</sub>` 等. 请参考 `OpenProcess` 的文档以找到完整的列表.

   客户端代码应该使用什么访问掩码? 通常, 它应该反映客户端代码打算对对象执行的操作. 请求超过需要的可能会失败, 而请求不足显然是不够的.

   与每个句柄关联的标志如下:

   • 继承 - 此标志用于句柄继承——一种允许在协作进程之间共享对象的机制. 我们将在第 3 章中讨论句柄继承.
   • 关闭时审核 - 此标志指示当该句柄关闭时, 是否应在安全日志中写入审计条目. 此标志很少使用, 默认是关闭的.
   • 防止关闭 - 设置此标志可防止句柄被关闭. 调用 `CloseHandle` 将返回 `FALSE`, `GetLastError` 返回 `ERROR<sub>INVALIDHANLDLE</sub>` (6). 如果进程在调试器下运行, 则会引发一个异常, 并显示以下消息: “0xC0000235: NtClose was called on a handle that was protected from close via NtSetInformationObject”. 此标志很少使用.

   可以使用 `SetHandleInformation` 函数更改继承和保护标志, 其定义如下:

   #define HANDLE_FLAG_INHERIT          0x00000001
   #define HANDLE_FLAG_PROTECT_FROM_CLOSE 0x00000002
   
   BOOL SetHandleInformation(
       _In_ HANDLE  hObject,
       _In_ DWORD   dwMask,
       _In_ DWORD   dwFlags);
   

   第一个参数是句柄本身. 第二个参数是一个位掩码, 指示要操作的标志. 最后一个参数是这些标志的实际值. 例如, 要在某个句柄上设置“防止关闭”位, 可以使用以下代码:

   ::SetHandleInformation(h, HANDLE_FLAG_PROTECT_FROM_CLOSE, HANDLE_FLAG_PROTECT_FROM_CLOSE);
   

   相反, 以下代码片段移除了这个位:

   ::SetHandleInformation(h, HANDLE_FLAG_PROTECT_FROM_CLOSE, 0);
   

   也存在一个用于读回这些标志的相反函数:

   BOOL GetHandleInformation(
       _In_  HANDLE  hObject,
       _Out_ LPDWORD lpdwFlags);
   

   可以使用 Sysinternals 的 Process Explorer 工具查看从特定进程打开的句柄. 导航到你感兴趣的进程, 并确保下方面板可见 (视图菜单, 显示下方面板). 下方面板显示两种视图之一——切换到句柄视图 (视图菜单, 下方面板视图, 句柄). 图 2-5 是该工具显示在 Explorer 进程中打开的句柄的屏幕截图. 默认显示的列只有类型和名称. 我通过右键单击标题区域并单击选择列添加了以下列: 句柄, 对象地址, 访问权限和解码的访问权限.

   

   Figure 12: Process Explorer 中的句柄视图

   以下是对这些列的简要描述:

   • 句柄 - 这是句柄值本身, 仅与此进程相关. 相同的句柄值在另一个进程中可能有不同的含义, 即——指向不同的对象, 或者可能是一个空索引.
   • 类型 - 对象类型名称. 这对应于图 2-1 中 WinObj 中显示的对象类型目录.
   • 对象地址 - 这是实际对象结构所在的内核地址. 请注意, 这些地址在 64 位系统上以零十六进制数字结尾 (在 32 位系统上, 地址以“8”或“0”结尾). 用户模式代码对此信息无能为力, 但它可以用于调试目的: 如果你有两个对象的句柄, 并且你想知道它们是否指向同一个对象, 你可以比较对象地址; 如果它们相同, 那么它们是同一个对象.
   • 访问权限 - 这是上面讨论的访问掩码. 要解释存储在此十六进制值中的位, 你需要在文档中找到访问掩码位. 为了减轻这种情况, 请使用*解码的访问权限*列.
   • 解码的访问权限 - 为常见的对象类型提供访问掩码位的字符串表示. 这使得在不深入文档的情况下更容易解释访问掩码位.

   我个人为 Process Explorer 实现了这一列.

   Process Explorer 的句柄视图默认只显示命名对象的句柄. 要查看所有句柄, 请从视图菜单中启用*显示未命名句柄和映射*选项. 图 2-6 显示了选中此选项时视图的变化情况.

   

   Figure 13: Process Explorer 中的句柄视图 (包括未命名对象)

   “名称”这个术语比看起来要棘手. Process Explorer 认为的命名对象不一定是实际名称, 在某些情况下是方便的代号. 例如, 进程和线程句柄如图 2-5 所示, 即使进程和线程不能有基于字符串的名称. 还有其他对象类型带有“名称”, 但那不是它们的名称; 最令人困惑的是*文件*和*键*. 我们将在本章后面的“对象名称”部分讨论这种“怪异”.

   进程句柄表中的句柄总数可作为 Process Explorer 和任务管理器中的一列. 图 2-7 显示了添加到任务管理器中的这一列.

   

   Figure 14: 任务管理器中的句柄计数列

   请注意, 显示的数字是句柄计数, 而不是对象计数. 这是因为可能存在多个引用同一对象的句柄.

   在 Process Explorer 中双击句柄条目会打开一个对话框, 显示该对象 (而不是句柄) 的一些属性. 图 2-8 是这样一个对话框的屏幕截图.

   

   Figure 15: Process Explorer 中的内核对象属性

   基本对象信息从句柄条目中重复 (名称, 类型和地址). 这个特定的对象 (一个互斥体) 有 3 个打开的句柄. 引用数是误导性的, 并不反映实际的对象引用计数. 对于某些类型的对象 (例如互斥体), 会显示额外的信息. 在这种特殊情况下, 是互斥体当前是否被持有以及是否被放弃. (我们将在第 8 章中详细讨论互斥体).

   要了解在给定时刻系统中对象和句柄的数量, 你可以运行我 Github 仓库中的 KernelObjectView 工具, 网址为 https://github.com/zodiacon/AllTools. 图 2-9 显示了该工具的屏幕截图. 显示了对象的总数 (按对象类型) 以及句柄的总数. 你可以按任何列排序; 哪个对象类型有最多的对象? 最多的句柄?

   

   Figure 16: 内核对象查看器

   1. 伪句柄
      

      一些句柄具有特殊值并且不可关闭. 这些被称为*伪句柄*, 尽管在需要时它们的使用方式与任何其他句柄一样. 在伪句柄上调用 `CloseHandle` 总是失败. 以下是返回伪句柄的函数:

      • `GetCurrentProcess` (-1) - 返回到调用进程的伪句柄
      • `GetCurrentThread` (-2) - 返回到调用线程的伪句柄
      • `GetCurrentProcessToken` (-4) - 返回到调用进程的令牌的伪句柄
      • `GetCurrentThreadToken` (-5) - 返回到调用线程的令牌的伪句柄
      • `GetCurrentThreadEffectiveToken` (-6) - 返回到调用线程的有效令牌的伪句柄 (如果线程有自己的令牌——则使用它, 否则——使用其进程令牌)

      最后三个伪句柄 (令牌句柄) 仅在 Windows 8 及更高版本上受支持, 其访问掩码仅为 `TOKEN<sub>QUERY</sub>` 和 `TOKEN<sub>QUERYSOURCE</sub>`.

      进程, 线程和令牌将在本书后面讨论.

   2. RAII for Handles
      

      一旦不再需要句柄, 关闭它很重要. 未能正确执行此操作的应用程序可能会出现“句柄泄漏”, 即句柄数量失控增长, 如果应用程序打开句柄但“忘记”关闭它们. 显然, 这是不好的.

      一种帮助代码管理句柄而不会忘记关闭它们的方法是使用 C++ 实现一个众所周知的习语, 称为*资源获取即初始化* (RAII). 这个名字不太好, 但这个习语很好. 其思想是为包装在类型中的句柄使用析构函数, 以确保在销毁包装器对象时关闭句柄.

      以下是一个句柄的简单 RAII 包装器 (为方便起见, 内联实现):

      struct Handle {
          explicit Handle(HANDLE h = nullptr) : _h(h) {}
          ~Handle() { Close(); }
      
          // delete copy-ctor and copy-assignment
          Handle(const Handle&) = delete;
          Handle& operator=(const Handle&) = delete;
      
          // allow move (transfer ownership)
          Handle(Handle&& other) : _h(other._h) {
              other._h = nullptr;
          }
          Handle& operator=(Handle&& other) {
              if (this != &other) {
                  Close();
                  _h = other._h;
                  other._h = nullptr;
              }
              return *this;
          }
      
          operator bool() const {
              return _h != nullptr && _h != INVALID_HANDLE_VALUE;
          }
      
          HANDLE Get() const {
              return _h;
          }
      
          void Close() {
              if (_h) {
                  ::CloseHandle(_h);
                  _h = nullptr;
              }
          }
      private:
          HANDLE _h;
      };
      

      `Handle` 类型提供了 RAII HANDLE 包装器所期望的基本操作. 复制构造函数和复制赋值运算符被移除, 因为复制可能拥有多个所有者的句柄没有意义 (导致 `CloseHandle` 对同一个句柄被调用两次). 可以通过复制句柄来实现这些复制操作 (参见本章后面的“共享内核对象”), 但这是一个不平凡的操作, 最好在隐式复制场景中避免. `bool` 运算符在当前持有的句柄有效时返回 true; 它将零和 `INVALID<sub>HANDLEVALUE</sub>` (-1) 视为无效句柄. `Close` 函数关闭句柄, 通常由析构函数调用. 最后, `Get` 函数返回底层的句柄.

      可以为 `HANDLE` 添加一个隐式转换运算符, 从而无需调用 `Get`.

      以下是使用上述包装器的一些示例代码:

      Handle hMyEvent(::CreateEvent(nullptr, TRUE, FALSE, nullptr));
      if (!hMyEvent) {
          // handle failure
          return;
      }
      
      ::SetEvent(hMyEvent.Get());
      
      // move ownership
      Handle hOtherEvent(std::move(hMyEvent));
      ::ResetEvent(hOtherEvent.Get());
      

      尽管编写这样一个 RAII 包装器是可能的, 但通常最好使用提供此 (及其他类似) 功能的现有库. 例如, 尽管 `CloseHandle` 是最常见的关闭句柄函数, 但还有其他类型的句柄需要不同的关闭函数. Microsoft 在 Windows 代码中使用的一个这样的库是 Windows Implementation Library (WIL). 这个库已在 Github 上发布, 并作为 Nuget 包提供.

   3. 使用 WIL
      

      将 WIL 添加到项目就像添加任何其他 Nuget 包一样. 右键单击 Visual Studio 项目中的*引用*节点, 然后选择*管理 Nuget 包…*. 在*浏览*选项卡的搜索文本框中, 键入“wil”以快速搜索 WIL. 包的全名是“Microsoft.Windows.ImplementationLibrary”, 如图 2-10 所示.

      

      Figure 17: 通过 Nuget 添加 WIL

      RAII 句柄包装器位于 `<wil\resource.h>` 头文件中. 以下是使用 WIL 的相同代码:

      #include <wil\resource.h>
      
      void DoWork() {
          wil::unique_handle hMyEvent(::CreateEvent(nullptr, TRUE, FALSE, nullptr));
          if (!hMyEvent) {
              // handle failure
              return;
          }
      
          ::SetEvent(hMyEvent.get());
      
          // move ownership
          auto hOtherEvent(std::move(hMyEvent));
          ::ResetEvent(hOtherEvent.get());
      }
      

      `wil::unique<sub>handle</sub>` 是一个 `HANDLE` 包装器, 在销毁时调用 `CloseHandle`. 它主要模仿 C++ `std::unique<sub>ptr</sub><>` 类型. 请注意, 获取内部 `HANDLE` 是通过调用 `get()` 完成的. 要替换 `unique<sub>handle</sub>` 内部的值 (并关闭旧值), 请使用 `reset` 函数; 不带参数调用 `reset` 只会关闭底层句柄, 使包装器对象成为一个空壳.

      通过添加 `using namespace wil;` 可以稍微简化代码, 这样就不需要在 WIL 中的每个类型前加上 `wil::`. 另外, 请注意可以使用 `auto` 来简化某些情况下的代码.

      本书中的代码示例在某些情况下使用 WIL, 但并非全部. 从学习的角度来看, 有时使用原始类型来使事情更简单易懂会更好.

3. 创建对象
   

   所有创建新对象的函数都有一些共同的参数. 以下是 `CreateMutex` 和 `CreateEvent` 函数以作演示:

   HANDLE CreateMutex(
       _In_opt_ LPSECURITY_ATTRIBUTES lpMutexAttributes,
       _In_     BOOL                  bInitialOwner,
       _In_opt_ LPCTSTR               lpName);
   
   HANDLE CreateEvent(
       _In_opt_ LPSECURITY_ATTRIBUTES lpEventAttributes,
       _In_     BOOL                  bManualReset,
       _In_     BOOL                  bInitialState,
       _In_opt_ LPCTSTR               lpName);
   

   请注意, 两个函数都接受一个类型为 `SECURITY<sub>ATTRIBUTES</sub>` 的参数. 这个结构在几乎所有的 `Create` 函数中都很常见, 定义如下:

   typedef struct _SECURITY_ATTRIBUTES {
       DWORD  nLength;
       LPVOID lpSecurityDescriptor;
       BOOL   bInheritHandle;
   } SECURITY_ATTRIBUTES, *PSECURITY_ATTRIBUTES;
   

   `nLength` 成员应设置为结构的大小. 这是 Windows 用于版本化结构的常用技术. 如果结构在未来的 Windows 版本中会有新成员, 旧代码仍然可以正常工作, 因为它会将长度设置为旧大小, 所以新的 Windows API 知道不要查看新成员, 因为旧代码不知道它们的存在. 也就是说, `SECURITY<sub>ATTRIBUTES</sub>` 结构自第一个 Windows NT 版本以来尚未更改.

   顾名思义, 该结构与新创建对象的安全设置有关. 主要与安全相关的成员是 `lpSecurityDescriptor`, 它可以指向一个安全描述符对象, 该对象基本上指定了谁可以对该对象做什么. 我们将在第 16 章中讨论安全描述符.

   最后一个成员, `bInheritHandle` 具有安全含义, 这就是为什么它也托管在此结构中的原因. 这是前面提到的继承位. 这意味着可以通过使用此结构来设置继承位, 而无需在创建新对象时调用 `SetHandleInformation`. 以下是创建一个事件对象并使其返回的句柄设置了继承位的示例:

   SECURITY_ATTRIBUTES sa = { sizeof(sa) }; // set nLength and zero the rest
   sa.bInheritHandle = TRUE;
   
   HANDLE hEvent = ::CreateEvent(&sa, TRUE, FALSE, nullptr);
   DWORD flags;
   ::GetHandleInformation(hEvent, &flags); // sets flags=1
   

   句柄继承在第 3 章中讨论.

   为 `SECURITY<sub>ATTRIBUTES</sub>` 传递 `NULL` 会使继承位保持清除状态. 在安全性方面, 这意味着“默认安全性”, 它基于存储在进程访问令牌中的安全描述符. 我们将在第 16 章中讨论细节. 在任何情况下, 在大多数情况下, 为安全描述符使用 `NULL` (无论是显式地还是通过为 `SECURITY<sub>ATTRIBUTES</sub>` 指针传递 `NULL`) 都是正确的做法.

4. 对象名称
   

   某些类型的对象可以有基于字符串的名称. 这些名称可以用于通过合适的 `Open` 函数按名称打开对象. 请注意, 并非所有对象都有名称; 例如, 进程和线程没有名称——它们有 ID. 这就是为什么 `OpenProcess` 和 `OpenThread` 函数需要一个进程/线程标识符 (一个数字) 而不是一个字符串基础名称的原因. 命名的对象可以用 Sysinternals 的 WinObj 工具查看.

   从用户模式代码, 调用带有名称的 `Create` 函数会在该名称的对象不存在时创建该对象, 但如果它存在, 则只会打开现有对象. 在后一种情况下, 调用 `GetLastError` 会返回 `ERROR<sub>ALREADYEXISTS</sub>`, 表明这不是一个新对象, 返回的句柄是现有对象的另一个句柄. 在这种情况下, 影响对象创建的参数 (如 `SECURITY<sub>ATTRIBUTES</sub>` 结构) 不会被使用, 因为创建者已经设置好了.

   提供给 `Create` 函数的名称不是对象的最终名称. 在经典 (桌面) 进程中, 它会前缀上 `\Sessions\x\BaseNamedObjects\`, 其中 `x` 是调用者的会话 ID. 如果会话为零, 名称仅前缀为 `\BaseNamedObjects\`. 如果调用者恰好在 AppContainer 中运行 (通常是通用 Windows 平台进程), 那么前缀字符串更复杂, 由唯一的 AppContainer SID 组成: `\Sessions\x\AppContainerNamedObjects\`.

   图 2-11 显示了在 WinObj 中会话 1 的命名对象.

   

   Figure 18: 会话 1 中的命名对象

   图 2-12 显示了会话 0 中的命名对象.

   

   Figure 19: 会话 0 中的命名对象

   以上所有内容意味着对象名称是会话相关的 (在 AppContainer 的情况下是包相关的). 如果一个对象必须跨会话共享, 它可以在会话 0 中创建, 通过在对象名称前加上 `Global\` 前缀; 例如, 使用 `CreateMutex` 函数创建一个名为 `Global\MyMutex` 的互斥体, 将在 `\BaseNamedObjects` 下创建它. 请注意, AppContainers 无权使用会话 0 对象命名空间.

   整个对象管理器命名空间层次结构可以用 WinObj 查看. 整个结构都保存在内存中, 并根据需要由对象管理器操作. 请注意, 未命名的对象不属于此结构的一部分, 这意味着在 WinObj 中看到的对象不包括所有现有对象, 而是所有用名称创建的对象.

   WinObj 中显示的“目录”实际上是目录对象, 它们只是一种作为逻辑容器的内核对象.

   回到 Process Explorer 的句柄视图——它默认显示“命名”对象. 这里的“命名”不仅意味着可以命名的对象, 还包括其他对象. 可以命名的对象是互斥体 (Mutants), 信号量, 事件, 节, ALPC 端口, 作业, 计时器以及其他一些不常用的对象类型. 还有一些显示带有名称的对象, 其含义与真正的命名对象不同:

   • 进程和线程对象 - 名称显示为其唯一的 ID.
   • 对于文件对象, 它显示文件对象指向的文件名 (或设备名). 这与对象的名称不同, 因为没有办法根据文件名获取文件对象的句柄——只能创建一个新的文件对象来访问相同的底层文件或设备 (假设原始文件对象的共享设置允许).
   • *(注册表) 键对象*名称显示为注册表项的路径. 这不是一个名称, 原因与文件对象相同.
   • *目录对象*显示其逻辑路径, 而不是真正的对象名称. 目录不是文件系统对象, 而是对象管理器目录.
   • *令牌对象*名称显示为存储在令牌中的用户名.

   要验证上述陈述, 请浏览 WinObj 并查找文件或键对象. 你不会找到任何, 这表明这些对象不能被命名.

5. 共享内核对象
   

   正如我们所见, 内核对象的句柄对进程是私有的. 在某些情况下, 一个进程可能希望与另一个进程共享一个内核对象. 这样的进程不能简单地以某种方式将句柄的值传递给另一个进程, 因为在另一个进程的句柄表中, 该句柄值可能指向一个不同的对象或者是空的.

   显然, 必须有一些机制来允许这种共享. 实际上, 有三种:

   • 按名称共享
   • 按句柄继承共享
   • 按句柄复制共享

   我们将在这里探讨第一种和第三种选项, 并在下一章讨论句柄继承.

   1. 按名称共享
      

      这是最简单的选项, 如果可用的话. “可用”意味着所讨论的对象可以有名称, 并且确实有名称. 典型的场景是协作进程 (2个或更多) 会用相同的对象名称调用适当的 `Create` 函数. 第一个进行调用的进程会创建对象, 而其他进程的后续调用会打开到同一对象的附加句柄.

      `BasicSharing` 示例展示了使用内存映射文件对象按名称共享的例子. 此对象可用于在进程之间共享内存 (通常, 每个进程只能看到自己的地址空间). 运行应用程序的两个 (或更多) 实例 (如图 2-13 所示) 允许在这些进程之间共享文本数据.

      内存映射文件的全部细节在第 14 章中讨论.

      

      Figure 20: Basic Sharing 应用程序

      要测试它, 请在编辑框中输入一些内容, 然后单击*写入*. 然后切换到另一个实例, 只需单击*读取*. 你输入的文本应该会出现在另一个应用程序的编辑框中. 当然, 你可以交换角色. 如果你启动另一个实例, 你可以单击*读取*并且最后输入的文本也会出现. 这是因为所有这些进程都在读写同一个 (共享) 内存.

      顺便说一句, 这些不必是基于同一可执行文件的进程——这里只是为了方便. 决定因素是对象的名称.

      在我们看代码之前, 让我们看看这在 Process Explorer 中是什么样子. 运行两个可执行文件的实例, 打开 Process Explorer 并找到这两个进程. 确保下方面板显示句柄 (而不是 DLL). 要查找的对象类型是*Section* (内存映射文件的内核名称). 找到一个名为“MySharedMemory”的节 (当然带有基于会话的前缀), 如图 2-14 所示.

      

      Figure 21: 共享的 section 对象

      如果你双击句柄, 你应该会看到如图 2-15 所示的节对象的属性.

      

      Figure 22: Section 对象属性

      请注意, 有两个打开的句柄指向该对象. 据推测, 它们来自持有该对象句柄的两个进程. 注意共享内存的大小: 4 KB——我们将在代码中看到这一点.

      如果你使用此对象找到第二个进程 (参见图 2-16), 你应该在双击句柄时发现呈现了相同的信息. 你怎么能确定这些是指向同一个对象呢? 查看*对象地址*列. 如果地址相同, 那么它们是同一个对象 (反之亦然). 还要注意句柄值不相同 (正常情况). 在图 2-14 中, 句柄值为 `0x14c` (PID 22384), 在图 2-16 中为 `0x16c` (PID 27864). 尽管如此, 它们引用的是完全相同的对象.

      

      Figure 23: 另一个进程中的共享节

      如果你关闭其中一个实例, 会发生什么? 一个句柄会关闭, 但对象仍然存在. 这意味着启动一个全新的实例并单击*读取*将显示最近的文本. 如果我们关闭所有协作应用程序然后启动一个实例会发生什么. 如果我们单击*读取*会看到什么? 试着自己解释一下为什么会这样.

      现在让我们把注意力转向代码. `BasicApplication` 是一个基于 WTL 的对话框项目. 对话框类 (`CMainDlg`) 包含一个我们感兴趣的成员, 即内存映射文件的句柄:

      private:
          HANDLE m_hSharedMem;
      

      当创建对话框时, 在 `WM<sub>INITDIALOG</sub>` 消息处理程序中, 我们创建文件映射对象并给它一个名称:

      m_hSharedMem = ::CreateFileMapping(INVALID_HANDLE_VALUE, nullptr, PAGE_READWRITE,
          0, 1 << 12, L"MySharedMemory");
      if (!m_hSharedMem) {
          AtlMessageBox(m_hWnd, L"Failed to create/open shared memory", IDR_MAINFRAME);
          EndDialog(IDCANCEL);
      }
      

      `CreateFileMapping` 用于创建 (或打开) 一个文件映射对象. 参数的详细信息在第 14 章 (第二部分) 中讨论. 这里我们关心一个特定的参数 (最后一个)——对象的名称. 这是我们在 Process Explorer 中看到过的名称 (带有标准的会话相关前缀). 如果这是第一个尝试创建该对象的进程——它就被创建了. 后续的调用会导致为同一个对象创建额外的句柄 (调用 `GetLastError` 会返回 `ERROR<sub>ALREADYEXISTS</sub>`). 在这种情况下, 我们不关心这个调用是第一次还是不是——我们只想得到同一个内核对象的句柄, 以便它的“功能”可以从多个进程中获得.

      倒数第二对参数 (`0` 和 `1 << 12`) 决定了共享内存的大小, 以 64 位值的形式. 在这种情况下, 它被设置为 4 KB (`1 << 12`). 如果调用因任何原因失败, 我们只打印一个简单的消息并关闭对话框, 导致进程本身退出.

      当对话框关闭时, 关闭句柄是个好主意. 严格来说, 在这个特定的情况下没有必要这样做, 因为一旦对话框关闭, 进程就会退出, 而内核确保从终止的进程中所有句柄都被正确关闭. 尽管如此, 养成这个好习惯是好的 (除非某个 RAII 包装器为你做这件事). 为完整起见, 以下是在处理 `WM<sub>DESTROY</sub>` 消息时关闭句柄的调用:

      if (m_hSharedMem)
          ::CloseHandle(m_hSharedMem);
      

      现在是写入和读取部分. 访问共享内存是通过调用 `MapViewOfFile` 完成的, 结果是一个指向共享内存的指针 (同样, 详细信息在第 12 章中). 然后就是将文本复制到该映射内存的问题:

      void* buffer = ::MapViewOfFile(m_hSharedMem, FILE_MAP_WRITE, 0, 0, 0);
      if (!buffer) {
          AtlMessageBox(m_hWnd, L"Failed to map memory", IDR_MAINFRAME);
          return 0;
      }
      CString text;
      GetDlgItemText(IDC_TEXT, text);
      ::wcscpy_s((PWSTR)buffer, text.GetLength() + 1, text);
      
      ::UnmapViewOfFile(buffer);
      

      复制是通过 `wcscpy<sub>s</sub>` 到映射内存完成的. 然后用 `UnmapViewOfFile` 取消内存映射. 读取数据非常相似. 访问掩码更改为 `FILE<sub>MAPREAD</sub>` 而不是 `FILE<sub>MAPWRITE</sub>`, 内存被复制到另一个方向, 直接到编辑框中:

      void* buffer = ::MapViewOfFile(m_hSharedMem, FILE_MAP_READ, 0, 0, 0);
      if (!buffer) {
          AtlMessageBox(m_hWnd, L"Failed to map memory", IDR_MAINFRAME);
          return 0;
      }
      
      SetDlgItemText(IDC_TEXT, (PCWSTR)buffer);
      ::UnmapViewOfFile(buffer);
      

   2. 按句柄复制共享
      

      按名称共享内核对象当然很简单. 那么那些没有 (或不能有) 名称的对象呢? 句柄复制可能是答案. 句柄复制没有固有的限制 (除了安全性)——它可以用于几乎任何内核对象, 无论命名与否, 并且它在任何时间点都有效 (在第 3 章中我们将看到句柄继承只在进程创建子进程时可用). 然而, 有一个问题; 这是实践中最困难的共享方式, 我们很快就会看到.

      复制的 I/O 完成端口句柄在目标进程中不起作用.

      复制句柄就像调用 `DuplicateHandle` 函数一样简单:

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

      复制句柄需要一个源进程, 源句柄和目标进程. 如果成功, 一个新的句柄条目会写入目标进程的句柄表中, 指向与源句柄相同的对象. 复制前后的情况分别如图 2-17 和 2-18 所示.

      

      Figure 24: 句柄复制前

      

      Figure 25: 句柄复制后

      技术上, `DuplicateHandle` 可以在任何可以获得正确句柄的两个进程上工作, 但典型的场景是将调用者的一个句柄复制到另一个进程的句柄表中. 另外, 源进程和目标进程可以是同一个. 让我们详细看一下 `DuplicateHandle` 的参数:

      • `hSourceProcessHandle` - 这是到源进程的句柄. 此句柄必须有 `PROCESS<sub>DUPHANDLE</sub>` 访问掩码. 如果源是调用者的进程, 那么传递 `GetCurrentProcess` 就可以了 (它总是有完全访问权限).
      • `hSourceHandle` - 要复制的源句柄. 此句柄在源进程的上下文中必须有效.
      • `hTargetProcessHandle` - 目标进程的句柄. 通常必须使用一些对 `OpenProcess` 的调用来获得这样的句柄. 与源进程一样, `PROCESS<sub>DUPHANDLE</sub>` 访问掩码是必需的.
      • `lpTargetHandle` - 这是结果句柄, 从目标进程的角度来看是有效的. 在图 2-18 中, 返回给调用者的句柄是 72. 这个值是相对于进程 B 的 (调用者假定为进程 A).
      • `dwDesiredAccess` - 复制句柄所需的访问掩码. 如果 `dwOptions` 参数有 `DUPLICATE<sub>SAMEACCESS</sub>` 标志, 则忽略此访问掩码. 否则, 这是为新句柄请求的访问掩码.
      • `bInheritHandle` - 指定新句柄是否可继承 (更多关于句柄继承的内容见第 3 章).
      • `dwOptions` - 一组标志. 一个是上面讨论的 `DUPLICATE<sub>SAMEACCESS</sub>`. 第二个支持的是 `DUPLICATE<sub>CLOSESOURCE</sub>`; 如果指定, 则在成功复制后关闭源句柄 (这意味着对象的句柄计数不会增加).

      以下是一个简单的例子, 创建一个作业对象并在同一进程中复制一个它的句柄, 同时减少访问掩码 (省略了错误处理):

      HANDLE hJob = ::CreateJobObject(nullptr, nullptr);
      HANDLE hJob2;
      ::DuplicateHandle(::GetCurrentProcess(), hJob, ::GetCurrentProcess(), &hJob2,
          JOB_OBJECT_ASSIGN_PROCESS | JOB_OBJECT_TERMINATE, FALSE, 0);
      

      源进程和目标进程是当前进程. 运行这段代码并在 Process Explorer 中查看句柄, 会显示出差异 (图 2-19).

      

      Figure 26: 简单的句柄复制

      一个句柄 (`0xac`) 对作业对象拥有完全访问权限, 而另一个 (复制的) 句柄 (`0xb0`) 只有指定的所需访问掩码.

      在更常见的情况下, 当前进程的句柄被复制到一个目标协作进程. 以下函数将从当前进程复制一个源句柄到目标进程:

      HANDLE DuplicateToProcess(HANDLE hSource, DWORD pid) {
          // open a strong-enough handle to the target process
          HANDLE hProcess = ::OpenProcess(PROCESS_DUP_HANDLE, FALSE, pid);
          if (!hProcess)
              return nullptr;
      
          HANDLE hTarget = nullptr;
          // duplicate
          ::DuplicateHandle(::GetCurrentProcess(), hSource, hProcess,
              &hTarget, 0, FALSE, DUPLICATE_SAME_ACCESS);
      
          // cleanup
          ::CloseHandle(hProcess);
      
          return hTarget;
      }
      

      这就是句柄复制变得不那么简单的情况. 问题不在于复制本身——那相当简单——一个函数调用. 问题在于如何将信息传达给目标进程. 必须向目标进程传达两部分信息:

      • 当句柄被复制时.
      • 复制的句柄值是多少?

      记住, 调用者知道创建的句柄值, 但目标进程不知道. 必须有某种其他形式的进程间通信, 允许调用者进程将所需信息传递给目标进程 (因为它们是同一系统的一部分, 需要通过共享内核对象进行协作).

      我们将在本书中探讨各种进程间通信机制.

6. 私有对象命名空间
   

   我们已经看到某些类型的内核对象可以有基于字符串的名称. 我们也看到这是在进程之间共享这些对象的一种 (方便的) 方法. 然而, 拥有命名对象有一些缺点:

   • 其他一些不相关的进程, 可能会创建一个同名的对象, 这在以后创建对象时可能导致失败 (如果对象类型不同), 或者更糟, 创建“成功”, 因为它是相同的对象类型, 代码得到了一个到现有对象的句柄. 结果是一团糟, 进程使用了它们不期望的同一个对象.
   • 这是上述要点的特例, 为了强调. 由于名称是可见的 (在工具中, 但也可以通过编程方式获得), 另一个进程可以“劫持”该对象或以其他方式干扰对象的使用. 从安全的角度来看

   , 所讨论的对象过于可见. 未命名对象则要隐蔽得多, 因为没有好方法可以猜测特定对象的用途.

   有没有一种方法可以让进程共享命名对象 (因为它很容易) 但又对其他进程不可见呢? 从 Windows Vista 开始, 有一种方法可以创建一个只有协作进程知道的私有对象命名空间. 使用工具或 API 不会揭示其全名.

   `PrivateSharing` 示例应用程序是 `BasicSharing` 的增强版本, 其中内存映射文件对象的名称现在位于私有对象命名空间下, 并且不是对所有人都可见. 使用 Process Explorer 查看此对象仅显示部分名称 (图 2-20).

   

   Figure 27: 带有私有命名空间的命名对象

   如果一些随机代码尝试定位一个名为“MySharedMem”的对象, 它会失败, 因为这不是该对象的真实名称.

   创建私有命名空间是一个两步过程. 首先, 必须创建一个名为*边界描述符* (Boundary Descriptor) 的辅助对象. 此描述符允许添加某些安全 ID (SID), 这些 SID 将能够使用基于该边界描述符创建的私有命名空间. 这有助于加强私有命名空间上的安全性. 要创建边界描述符, 请使用 `CreateBoundaryDescriptor`:

   HANDLE CreateBoundaryDescriptor(
       _In_ LPCTSTR Name,
       _In_ ULONG Flags); // currently unused
   

   一旦边界描述符存在, 可以使用两个函数来限制对通过该描述符创建的任何私有命名空间的访问: `AddSIDToBoundaryDescriptor` 和 `AddIntegrityLabelToBoundaryDescriptor` (后者从 Windows 7 开始可用):

   BOOL AddSIDToBoundaryDescriptor(
       _Inout_ HANDLE* BoundaryDescriptor,
       _In_    PSID    RequiredSid);
   
   BOOL AddIntegrityLabelToBoundaryDescriptor(
       _Inout_ HANDLE * BoundaryDescriptor,
       _In_    PSID   IntegrityLabel);
   

   两者都接受边界描述符句柄的地址和一个 SID. 使用 `AddSIDToBoundaryDescriptor`, SID 通常是一个组的 SID, 允许该组中的所有用户访问私有命名空间. `AddIntegrityLabelToBoundaryDescriptor` 允许为希望在此边界描述符管理的私有命名空间中打开对象的进程设置最低完整性级别.

   SIDs 和完整性级别将在第 16 章中讨论.

   一旦设置了边界描述符, 下一步就是用 `CreatePrivateNamespace` 创建实际的私有命名空间:

   HANDLE CreatePrivateNamespace(
       _In_opt_ LPSECURITY_ATTRIBUTES lpPrivateNamespaceAttributes,
       _In_     LPVOID                lpBoundaryDescriptor, // the boundary descriptor
       _In_     LPCWSTR               lpAliasPrefix);       // namespace name
   

   令人困惑的是, 边界描述符类型是 `void*` 而不是 `HANDLE`. 这是 API 中的一个疏忽, 但由于 `HANDLE` 被定义为 `void*`, 所以这可以正常工作. 这个失误也暗示了边界描述符不是一个内核对象, 即使它返回一个 `HANDLE`; 它有自己的关闭函数 - `DeleteBoundaryDescriptor`.

   对象命名空间也不是一个真正的内核对象. 如果命名空间已经存在, 该函数会失败, 必须改用 `OpenPrivateNamespace`. 它也有自己的关闭函数 (`ClosePrivateNamespace`):

   HANDLE OpenPrivateNamespaceW(
       _In_ LPVOID lpBoundaryDescriptor,
       _In_ LPCWSTR lpAliasPrefix); // namespace name
   
   BOOLEAN ClosePrivateNamespace(
       _In_ HANDLE Handle,
       _In_ ULONG Flags); // 0 or PRIVATE_NAMESPACE_FLAG_DESTROY
   

   另一个疏忽是函数 `ClosePrivateNamespace` 返回 `BOOLEAN` (typedef 为 `BYTE`) 而不是标准的 `BOOL`.

   一旦命名空间被创建或打开, 命名对象就可以正常创建, 名称格式为 `alias\name`, 其中“alias”是创建或打开命名空间时的 `lpAliasPrefix` 参数.

   让我们看看 `PrivateSharing` 应用程序中的具体代码. 对话框类现在有三个成员:

   private:
       wil::unique_handle m_hSharedMem;
       HANDLE m_hBD{ nullptr }, m_hNamespace{ nullptr };
   

   代码使用 WIL `unique<sub>handle</sub>` RAII 包装器来处理内存映射文件的句柄, 但边界描述符和命名空间作为原始句柄进行管理.

   当对话框创建时, 内存映射文件的创建方式与 `BasicSharing` 中相同, 但这次是在一个私有命名空间下 (为清晰起见, 省略了错误处理):

   // create the boundary descriptor
   m_hBD = ::CreateBoundaryDescriptor(L"MyDescriptor", 0);
   
   BYTE sid[SECURITY_MAX_SID_SIZE];
   auto psid = reinterpret_cast<PSID>(sid);
   DWORD sidLen;
   ::CreateWellKnownSid(WinBuiltinUsersSid, nullptr, psid, &sidLen);
   
   ::AddSIDToBoundaryDescriptor(&m_hBD, psid);
   
   // create the private namespace
   m_hNamespace = ::CreatePrivateNamespace(nullptr, m_hBD, L"MyNamespace");
   if (!m_hNamespace) { // maybe created already?
       m_hNamespace = ::OpenPrivateNamespace(m_hBD, L"MyNamespace");
   }
   
   m_hSharedMem.reset(::CreateFileMapping(INVALID_HANDLE_VALUE, nullptr,
       PAGE_READWRITE, 0, 1 << 12, L"MyNamespace\\MySharedMem"));
   

   在此示例中, 一个 SID 被添加到了边界描述符中. 这个 SID 是所有标准用户的. 也可以添加更严格的内容, 例如 Administrators 组, 这样在标准用户权限下运行的进程就无法访问此边界描述符. SID 是通过调用 `CreateWellKnownSid` 基于用户组的众所周知的 SID 创建的. 然后调用 `AddSIDToBoundaryDescriptor` 将 SID 附加到边界描述符.

   不用担心这些 SID 和其他安全术语. 它们在第 16 章中有详细描述.

   一旦边界描述符设置好, 就会调用 `CreatePrivateNamespace` 或 `OpenPrivateNamespace`, 别名为 “MyNamespace”. 这被用作使用 `CreateFileMapping` 创建的内存映射文件对象的前缀.

   最后, 对话框的 `WM<sub>DESTROY</sub>` 消息处理程序会删除命名空间和边界描述符:

   if (m_hNamespace)
       ::ClosePrivateNamespace(m_hNamespace, 0);
   if (m_hBD)
       ::DeleteBoundaryDescriptor(m_hBD);
   

   1. 附加内容: 用于私有命名空间的 WIL 包装器
      

      WIL 库有许多用于各种句柄和指针的包装器. 不幸的是, 它没有边界描述符和私有命名空间的包装器. 幸运的是, 创建它们并不太难. 以下是一种方法:

      namespace wil {
          static void close_private_ns(HANDLE h) {
              ::ClosePrivateNamespace(h, 0);
          };
      
          using unique_private_ns = unique_any_handle_null_only<decltype(
              &close_private_ns), close_private_ns>;
      
          using unique_bound_desc = unique_any_handle_null_only<decltype(
              &::DeleteBoundaryDescriptor), ::DeleteBoundaryDescriptor>;
      }
      

      我不会详细介绍上述声明的细节, 因为它们确实需要对 C++11 的 `decltype`, `using` 和模板有很好的了解.

      `PrivateSharing2` 项目与 `PrivateSharing` 相同, 但使用 WIL 包装器 (以及上述添加) 来管理所有句柄, 甚至是 `MapViewOfFile` 返回的指针. 例如, 以下是 `Read` 函数:

      wil::unique_mapview_ptr<void> buffer(::MapViewOfFile(
          m_hSharedMem.get(), FILE_MAP_READ, 0, 0, 0));
      if (!buffer) {
          AtlMessageBox(m_hWnd, L"Failed to map memory", IDR_MAINFRAME);
          return 0;
      }
      SetDlgItemText(IDC_TEXT, (PCWSTR)buffer.get());
      

7. 其他对象和句柄
   

   内核对象在系统编程的上下文中很有趣, 并且是本书的重点. Windows 中还使用了其他常见的对象, 即用户对象和 GDI 对象. 以下是对这些对象及其句柄的简要描述.

   任务管理器可以通过添加*用户对象*和 *GDI 对象*列来显示每个进程的此类对象的数量, 如图 2-21 所示.

   

   Figure 28: 用户和 GDI 对象计数

   1. 用户对象
      

      用户对象是窗口 (`HWND`), 菜单 (`HMENU`) 和钩子 (`HHOOK`). 这些对象的句柄具有以下属性:

      • 无引用计数. 第一个销毁用户对象的调用者——它就消失了.
      • 句柄值的作用域在一个窗口站下. 一个窗口站包含一个剪贴板, 桌面和原子表. 这意味着这些对象的句柄可以在共享桌面的所有应用程序之间自由传递, 例如.

      窗口站和桌面这两个术语将在本书后面讨论. 原子表则不会, 因为它们与 Windows 中的 UI 子系统相关, 这不是本书的重点.

   2. GDI 对象
      

      图形设备接口 (GDI) 是 Windows 中最初的图形 API, 至今仍在使用, 尽管有更丰富和更好的 API (例如 Direct2D). GDI 对象的示例: 设备上下文 (`HDC`), 画笔 (`HPEN`), 笔刷 (`HBRUSH`), 位图 (`HBITMAP`) 等. 以下是它们的属性:

      • 无引用计数.
      • 句柄仅在创建它们的进程中有效.
      • 不能在进程之间共享.
8. 总结
   

   在本章中, 我们探讨了内核对象以及如何通过使用句柄来访问和共享它们. 我们没有太深入地研究任何特定的对象类型, 因为这些将在其他章节中更详细地讨论. 在下一章中, 我们将深入探讨所有内核对象中最著名的——进程.

1.4.1. 进程基础

1. 名称
   

   这通常是进程所基于的可执行文件的名称. 请记住, 这个名称不是进程的唯一标识符. 有些进程似乎根本没有可执行文件名. 例子包括 `System`, `Secure System`, `Registry`, `Memory Compression`, `System Idle Process` 和 `System Interrupts`.

   • System Interrupts 实际上不是一个进程, 它只是用来衡量内核在服务硬件中断和延迟过程调用上花费的时间. 两者都超出了本书的范围. 你可以在 Windows Internals 和 Windows Kernel Programming 书籍中找到更多信息.
   • System Idle Process 也不是一个真正的进程. 它总是有进程 ID (PID) 为零. 它核算 Windows 的空闲时间. 这是当无事可做时 CPU 的去处.
   • System 进程是一个真正的进程, 技术上也是一个 minimal 进程. 它总是有 PID 为 4. 它代表了内核空间中发生的一切——内核和内核驱动程序使用的内存, 打开的句柄, 线程等等.
   • Secure System 进程仅在启用了基于虚拟化的安全的 Windows 10 和 Server 2016 (及更高版本) 系统上可用. 它代表了安全内核中发生的一切. 请参考 Windows Internals 书籍以获取更多信息.
   • Registry 进程是一个从 Windows 10 版本 1803 (RS4) 开始可用的 minimal 进程, 用作管理注册表的“工作区”, 而不是像以前版本那样使用分页池. 就本书而言, 这是一个不影响注册表以编程方式访问方式的实现细节.
   • Memory Compression 进程是一个从 Windows 10 版本 1607 (但不在服务器上) 开始可用的 minimal 进程, 并在其地址空间中保存压缩内存. 内存压缩是 Windows 10 中增加的一项功能, 用于节省物理内存 (RAM), 特别适用于资源有限的设备, 如手机和物联网 (Internet of Things) 设备. 令人困惑的是, 任务管理器不显示此进程, 但 Process Explorer 正确显示它.

   内存压缩 (Memory Compression) 不在任务管理器中显示的原因有些好笑. 在 Windows 10 版本 1607 之前支持内存压缩, 但压缩的内存存储在*System*进程的用户模式地址空间中, 这使得*System*进程看起来好像消耗了 (可能) 大量的内存. 那是压缩内存, 所以它实际上是*节省*内存, 但外观有时更重要, 所以压缩内存被移到了它自己的 (minimal) 进程中, 并且该进程被有意地从任务管理器的列表中隐藏了.

   本章的其余部分, 直到“Minimal 和 Pico 进程”部分, 都涉及基于可执行文件的“正常”进程. 无论如何, minimal 和 Pico 进程只能由内核创建.

2. PID
   

   进程的唯一 ID. PID 是 4 的倍数, 最低的有效 PID 值为 4 (属于*System*进程). 进程 ID 在进程终止后会重用, 因此可能会看到一个新进程的 PID 曾经被一个 (现在已消失的) 进程使用. 如果需要一个进程的唯一标识符, 那么 PID 和进程启动时间的组合在某个系统上是真正唯一的.

   你可能还记得第 2 章中, 句柄也是从 4 开始并且是 4 的倍数, 就像 PID 一样. 这不是巧合. 实际上, PID (和线程 ID) 是一个专门为此目的使用的特殊句柄表中的句柄值.

3. 状态
   

   状态*列是一个有趣的列. 它可以有三个值之一: *正在运行 (Running), 已挂起 (Suspended) 和*无响应 (Not Responding)*. 让我们逐一看看. 表 3-1 总结了这些状态基于进程类型的含义.

   进程类型	正在运行时…	已挂起时…	无响应时…
   GUI 进程 (非 UWP)	GUI 线程有响应	进程中的所有线程都已挂起	GUI 线程至少 5 秒内未检查消息队列
   CUI 进程 (非 UWP)	至少一个线程未被挂起	进程中的所有线程都已挂起	从不
   UWP 进程	在前台未被挂起	在后台	GUI 线程至少 5 秒内未检查消息队列

   带有 GUI 的进程必须有一个处理其用户界面的线程. 此线程有一个消息队列, 一旦它调用任何 UI 或 GDI 函数就会为它创建. 因此, 此线程必须泵送消息——也就是说, 监听其消息队列并处理到达的消息. 典型的监听函数是 `GetMessage` 或 `PeekMessage`. 如果至少 5 秒内没有调用任何一个, 任务管理器 会将状态更改为*无响应*, 该线程拥有的窗口会变暗, 并在窗口标题中添加“(无响应)”. 有问题的线程没有检查其消息队列, 原因有三:

   • 它因任何原因被挂起.
   • 它正在等待某个 I/O 操作完成, 并且耗时超过 5 秒.
   • 它正在做一些 CPU 密集型工作, 耗时超过 5 秒.

   我们将在第 5 章 (“线程基础”) 中探讨这些问题.

   UWP 进程是特殊的, 因为当它们移动到后台时, 例如当应用程序窗口最小化时, 它们会非自愿地被挂起. 一个简单的实验可以验证这种情况: 在 Windows 10 上打开现代计算器, 并在*任务管理器*中找到它. 你应该看到它的状态为*正在运行*, 这意味着它可以响应用户输入并通常地做它的事情. 现在最小化计算器, 你会看到几秒钟后状态变为*已挂起*. 这种行为只存在于 UWP 进程中.

   没有 GUI 的非 UWP 进程总是显示为*正在运行*状态, 因为 Windows 不知道这些进程实际上在做什么 (或不做什么). 唯一的例外是, 如果此类进程中的所有线程都被挂起, 那么其状态将变为*已挂起*.

   Windows API 没有挂起进程的函数, 只有挂起线程的函数. 技术上可以遍历某个进程中的所有线程并挂起每一个 (假设可以获得足够强大的句柄). native API (在 NtDll.Dll 中实现) 确实有一个用于此目的的函数, `NtSuspendProcess`. 这是 Process Explorer 如果你右键单击一个进程并选择*挂起*时调用的函数. 当然, 相反的函数也存在 - `NtResumeProcess`.

4. 用户名
   

   用户名指示进程在哪个用户下运行. 一个令牌对象附加到进程 (称为*主令牌*), 它基于用户持有进程的安全上下文. 该安全上下文包含诸如用户所属的组, 它拥有的特权等信息. 我们将在第 16 章中更深入地探讨令牌. 进程可以在特殊的内置用户下运行, 例如本地系统 (在任务管理器中显示为 `System`), 网络服务和本地服务. 这些用户帐户通常用于运行服务, 我们将在第 16 章中探讨.

5. 会话 ID
   

   进程执行的会话号. 会话 0 用于系统进程和服务, 会话 1 及更高版本用于交互式登录. 我们将在第 16 章中更详细地探讨会话.

6. CPU
   

   此列显示该进程的 CPU 百分比消耗. 请注意, 它只显示整数. 要获得更高的精度, 请使用 Process Explorer.

7. 内存
   

   与内存相关的列有些棘手. 任务管理器显示的默认列是*内存(活动私有工作集)* (Windows 10 版本 1903) 或*内存(私有工作集)* (早期版本). *工作集*这个术语指的是 RAM (物理内存). *私有工作集*是进程使用且不与其他进程共享的 RAM. 共享内存最常见的例子是 DLL 代码. *活动私有工作集*与*私有工作集*相同, 但对于当前挂起的 UWP 进程设置为零.

   上述两个计数器是否能很好地指示进程使用的内存量? 不幸的是, 不能. 这些指示了使用的私有 RAM, 但当前分页出去的内存呢? 还有另一个列可以解决这个问题——*提交大小 (Commit Size)*. 这是用于了解进程内存使用情况的最佳列. “不幸的”部分是任务管理器默认不显示此列.

   Process Explorer 有一个与 Commit Size 等效的列, 但它被称为 Private Bytes, 这与性能计数器的名称一致.

   这些内存术语将在第 12 章中进一步讨论.

8. 基本优先级
   

   基本优先级*列, 官方称为*优先级类, 显示六个值之一, 这些值为在该进程中执行的线程提供基本调度优先级. 可能的值及其关联的优先级级别如下:

   • 空闲 (在任务管理器中称为*低*) = 4
   • 低于正常 = 6
   • 正常 = 8
   • 高于正常 = 10
   • 高 = 13
   • 实时 = 24

   最常见 (也是默认) 的优先级类是*正常* (8). 我们将在第 6 章中讨论优先级和调度.

9. 句柄
   

   *句柄*列显示在特定进程中打开的内核对象句柄的数量. 这在第 2 章中已详细讨论.

10. 线程
    

    线程*列显示每个进程中的线程数. 通常, 这至少应该是一个, 因为没有线程的进程是无用的. 然而, 有些进程显示没有线程 (使用破折号). 具体来说, *Secure System 显示没有线程, 因为安全内核实际上使用普通内核进行调度. System Interrupts 伪进程根本不是一个进程, 所以不能有任何线程. 最后, System Idle Process 也不拥有线程. 为此进程显示的线程数是系统上的逻辑处理器数.

    任务管理器中还有其他感兴趣的列, 将在适当的时候进行检查.

1.4.2. Process Explorer 中的进程

1.4.3. 进程创建

c:\>dumpbin /imports c:\Windows\System32\notepad.exe

Dump of file c:\Windows\System32\notepad.exe

File Type: EXECUTABLE IMAGE

  Section contains the following imports:

    GDI32.dll
             140022788 Import Address Table
             1400289E8 Import Name Table
                     0 time date stamp
                     0 Index of first forwarder reference

                       35C SelectObject
                       2D0 GetTextFaceW
                       1C2 EnumFontsW
...
    USER32.dll
             140022840 Import Address Table
             140028AA0 Import Name Table
                     0 time date stamp
                     0 Index of first forwarder reference

                       364 SetThreadDpiAwarenessContext
                       2AD PostMessageW
                        BA DialogBoxParamW
...
    msvcrt.dll
             140022FD8 Import Address Table
             140029238 Import Name Table
                     0 time date stamp
                     0 Index of first forwarder reference

                        2F ?terminate@@YAXXZ
                       496 memset
...
    api-ms-win-core-libraryloader-l1-2-0.dll
             140022C60 Import Address Table
             140028EC0 Import Name Table
                     0 time date stamp
                     0 Index of first forwarder reference

                         F GetModuleFileNameA
                        18 LoadLibraryExW
                        13 GetModuleHandleExW
...
    urlmon.dll
                00000001 Characteristics
        000000014002C0D0 Address of HMODULE
        000000014002F0E0 Import Address Table
        0000000140028368 Import Name Table
        0000000140028638 Bound Import Name Table
        0000000000000000 Unload Import Name Table
                     0 time date stamp

        0000000140020F31      3B FindMimeFromData
...

C:\>APISetMap.exe
ApiSetMap - list API Set mappings - version 1.0
(c) Alex Ionescu, Pavel Yosifovich, and Contributors
http://www.alex-ionescu.com

api-ms-onecoreuap-print-render-l1-1-0.dll -> s{printrenderapihost.dll}
api-ms-win-appmodel-identity-l1-2-0.dll -> s{kernel.appcore.dll}
api-ms-win-appmodel-runtime-internal-l1-1-6.dll -> s{kernel.appcore.dll}
api-ms-win-appmodel-runtime-l1-1-3.dll -> s{kernel.appcore.dll}
api-ms-win-appmodel-state-l1-1-2.dll -> s{kernel.appcore.dll}
api-ms-win-appmodel-state-l1-2-0.dll -> s{kernel.appcore.dll}
api-ms-win-appmodel-unlock-l1-1-0.dll -> s{kernel.appcore.dll}
api-ms-win-base-bootconfig-l1-1-0.dll -> s{advapi32.dll}
api-ms-win-base-util-l1-1-0.dll -> s{advapi32.dll}
api-ms-win-composition-redirection-l1-1-0.dll -> s{dwmredir.dll}
api-ms-win-composition-windowmanager-l1-1-0.dll -> s{udwm.dll}
api-ms-win-containers-cmclient-l1-1-1.dll -> s{cmclient.dll}
api-ms-win-core-apiquery-l1-1-1.dll -> s{ntdll.dll}
api-ms-win-core-apiquery-l2-1-0.dll -> s{kernelbase.dll}

1. 主要函数
   

   开发人员实际上可以编写四种主要的函数, 每种都有一个对应的 C/C++ 运行时函数. 表 3-4 总结了这些名称以及它们的使用时机.

   开发人员的 main	C/C++ 运行时启动	场景
   main	mainCRTStartup	使用 ASCII 字符的控制台应用程序
   wmain	wmainCRTStartup	使用 Unicode 字符的控制台应用程序
   WinMain	WinMainCRTStartup	使用 ASCII 字符的 GUI 应用程序
   wWinMain	wWinMainCRTStartup	使用 Unicode 字符的 GUI 应用程序

   正确的函数由链接器的 `/SUBSYSTEM` 开关设置, 该开关也通过 Visual Studio 在项目属性对话框中暴露, 如图 3-9 所示.

   

   Figure 37: Visual Studio 中的系统链接器设置

   基于控制台的进程与基于 GUI 的进程有什么不同吗? 不完全是. 这两种类型都是 Windows 子系统的成员. 控制台应用程序可以显示 GUI, GUI 应用程序也可以使用控制台. 区别在于各种默认值, 例如主函数原型以及是否默认创建控制台窗口.

   GUI 应用程序可以使用 `AllocConsole` 创建一个控制台.

   基于表 3-4 中的行, 开发人员可以编写四种 `main` 函数的变体:

   int main(int argc, const char* argv[]);        // const is optional
   int wmain(int argc, const wchar_t* argv[]);    // const is optional
   int WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,
       LPSTR commandLine, int showCmd);
   int wWinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,
       LPWSTR commandLine, int showCmd);
   

   有时你会看到 `main` 函数写成 `<sub>tmain</sub>` 或 `<sub>tWinMain</sub>`. 正如你可能猜到的, 这允许根据编译常量 `<sub>UNICODE</sub>` 和 `UNICODE` 编译为 Unicode 或 ASCII.

   使用经典的 `main/wmain` 函数, 命令行参数在调用 `(w)main` 之前由 C/C++ 运行时分解. `argc` 表示命令行参数的数量, 并且至少为 1, 因为第一个“参数”是可执行文件的完整路径. `argv` 是一个指向解析的 (基于空格分割) 参数的指针数组. 这意味着 `argv[0]` 指向完整的可执行文件路径.

   使用 `w(WinMain)` 函数, 参数如下:

   • `hInstance` 代表进程地址空间内的可执行模块本身. 技术上, 这是可执行文件映射到的地址. 由链接器指定此值. 默认情况下, Visual Studio 使用链接器选项 `/DYNAMICBASE`, 该选项在每次项目构建时生成一个伪随机基地址. 在任何情况下, 数字本身并不重要, 但在各种函数中需要它, 例如用于加载资源 (`LoadIcon`, `LoadString` 等).

   `HINSTANCE` 类型只是一个 `void` 指针. 顺便说一句, `HMODULE` 类型有时与 `HINSTANCE` 互换使用, 实际上是同一回事. 存在两种类型而不是一种的原因与 16 位 Windows 有关, 当时它们的含义不同.

   • `hPrevInstance` 应该代表同一可执行文件的先前实例的 `HINSTANCE`. 然而, 这个值总是 `NULL`, 并且没有真正使用. 在 16 位 Windows 时代, 它是非 `NULL` 的. 这意味着没有直接的方法知道是否有另一个运行相同可执行文件的进程已经存在. 我们在第 2 章的 `Singleton` 演示应用程序中看到了如果需要如何处理这个问题. `WinMain` 签名是从 16 位 Windows 保留下来的, 以便更容易地移植到 32 位 Windows (当时). 最终结果是这个参数通常在没有变量名的情况下编写, 因为它完全没用.

   一种静默编译器警告 (尤其是在纯 C 中) 的替代技术是使用 `UNREFERENCED<sub>PARAMETER</sub>` 宏, 变量名如: `UNREFERENCED<sub>PARAMETER</sub>(hPrevInstance);`. 具有讽刺意味的是, 这个宏实际上通过简单地用分号结束来引用它的参数; 这足以让编译器满意.

   • `commandLine` 是不包括可执行文件路径的命令行字符串——它是命令行的其余部分 (如果有的话). 它没有被“解析”成单独的标记——它只是一个单一的字符串. 如果解析是有益的, 可以使用以下函数:

   #include <ShellApi.h>
   
   LPWSTR* CommandLineToArgvW(_In_ LPCWSTR lpCmdLine, _Out_ int* pNumArgs);
   

   该函数接受命令行并将其分割成标记, 返回一个指向字符串指针数组的指针. 字符串的数量通过 `*pNumArgs` 返回. 该函数分配一个内存块来保存解析的命令行参数, 并且必须最终通过调用 `LocalFree` 来释放它. 以下代码片段显示了如何在 `wWinMain` 函数中正确解析命令行:

   int wWinMain(HINSTANCE hInstance, HINSTANCE, LPWSTR lpCmdLine, int nCmdShow) {
       int count;
       PWSTR* args = CommandLineToArgvW(lpCmdLine, &count);
   
       WCHAR text = { 0 };
       for (int i = 0; i < count; i++) {
           ::wcscat_s(text, 1024, args[i]);
           ::wcscat_s(text, 1024, L"\n");
       }
       ::LocalFree(args);
   
       ::MessageBox(nullptr, text, L"Command Line Arguments", MB_OK);
   }
   

   如果传递给 `CommandLineToArgvW` 的字符串是空字符串, 那么它的返回值是一个包含完整可执行文件路径的单个字符串. 另一方面, 如果传入的字符串包含非空参数, 它会返回一个只包含解析的参数的字符串指针数组, 而不将完整可执行文件路径作为第一个解析的字符串.

   进程可以随时通过调用 `GetCommandLine` 获取其命令行, 并且它是 `CommandLineToArgvW` 的一个合适参数. 如果需要在 `wWinMain` 之外进行解析, 这可能很有用.

   • `showCmd` 是最后一个参数, 它建议如何显示应用程序的主窗口. 它由进程创建者确定, 默认值为 `SW<sub>SHOWDEFAULT</sub>` (10). 应用程序当然可以自由地忽略此值, 并以任何它认为合适的方式显示其主窗口.
2. 进程环境变量
   

   环境变量是一组名称/值对, 可以在系统或用户级别上使用图 3-10 中显示的对话框 (可从系统属性对话框或简单搜索访问) 设置. 名称和值存储在注册表中 (像 Windows 中的大多数系统数据一样).

   

   Figure 38: 环境变量编辑器

   用户环境变量存储在 `HKEY<sub>CURRENTUSER\Environment</sub>` 中. 系统环境变量 (适用于所有用户) 存储在 `HKEY<sub>LOCALMACHINE\System\Current</sub> Control Set\Control\Session Manager\Environment` 中.

   进程从其父进程接收环境变量, 这些变量是系统变量 (适用于所有用户) 和用户特定变量的组合. 在大多数情况下, 进程接收的环境变量是其父进程的副本 (见下一节).

   控制台应用程序可以使用 `main` 或 `wmain` 的第三个参数来获取进程环境变量:

   int main(int argc, char* argv[], const char* env[]); // const is optional
   int wmain(int argc, wchar_t* argv[], const wchar_t* env[]); // const is optional
   

   `env` 是一个字符串指针数组, 其中最后一个指针是 `NULL`, 表示数组的结束. 每个字符串都以下列格式构建:

   name=value
   

   等号字符分隔了名称和值. 以下示例 `main` 函数打印出每个环境变量的名称和值:

   int main(int argc, const char* argv[], char* env[]) {
       for (int i = 0; ; i++) {
           if (env[i] == nullptr)
               break;
   
           auto equals = strchr(env[i], '=');
           // change the equals to NULL
           *equals = '\0';
           printf("%s: %s\n", env[i], equals + 1);
   
           // for consistency, revert the equals sign
           *equals = '=';
       }
       return 0;
   }
   

   GUI 应用程序可以调用 `GetEnvironmentStrings` 来获取一个指向环境变量内存块的指针, 格式如下:

   name1=value1\0
   name2=value2\0
   ...
   \0
   

   以下代码片段使用 `GetEnvironmentStrings` 在一个巨大的消息框中显示所有环境变量:

   PWSTR env = ::GetEnvironmentStrings();
   WCHAR text = { 0 };
   
   auto p = env;
   while (*p) {
       auto equals = wcschr(p, L'=');
       if (equals != p) { // eliminate empty names/values
           wcsncat_s(text, p, equals - p);
           wcscat_s(text, L": ");
           wcscat_s(text, equals + 1);
           wcscat_s(text, L"\n");
       }
       p += wcslen(p) + 1;
   }
   
   ::FreeEnvironmentStrings(env);
   

   可以使用 `SetEnvironmentStrings` 一次性替换环境块, 使用与 `GetEnvironmentStrings` 返回的相同格式.

   环境块必须用 `FreeEnvironmentStrings` 释放. 通常, 应用程序不需要枚举环境变量, 而是更改或读取特定值. 以下函数用于此目的:

   BOOL SetEnvironmentVariable(
       _In_     LPCTSTR lpName,
       _In_opt_ LPCTSTR lpValue);
   
   DWORD GetEnvironmentVariable(
       _In_opt_ LPCTSTR lpName,
       _Out_    LPTSTR  lpBuffer,
       _In_     DWORD   nSize);
   

   `GetEnvironmentVariable` 如果缓冲区足够大, 则返回复制到缓冲区的字符数, 否则返回环境变量的长度. 如果失败 (如果指定的变量不存在), 则返回零. 通常的做法是调用该函数两次: 第一次不带缓冲区以获取长度, 然后在分配了适当大小的缓冲区后第二次调用以接收结果. 以下函数可用于通过返回 C++ `std::wstring` 来获取变量的值:

   std::wstring ReadEnvironmentVariable(PCWSTR name) {
       DWORD count = ::GetEnvironmentVariable(name, nullptr, 0);
       if (count > 0) {
           std::wstring value;
           value.resize(count);
           ::GetEnvironmentVariable(name, const_cast<PWSTR>(value.data()), count);
           return value;
       }
       return L"";
   }
   

   上面的 `const<sub>cast</sub>` 运算符移除了 `value.data()` 的“常量性”, 因为它返回 `const wchar<sub>t</sub>*`. 一个粗暴的 C 风格转换也可以同样工作: `(PWSTR)value.data()`.

   环境变量在许多情况下用于指定基于其当前值的信息. 例如, 文件路径可以指定为 “%windir%\\explorer.exe”. 百分号之间的名称是一个环境变量, 应扩展为其真实值. 普通的 API 函数对这些意图没有任何特殊的理解. 相反, 应用程序必须调用 `ExpandEnvironmentStrings` 将任何用百分号括起来的环境变量转换为其值:

   DWORD ExpandEnvironmentStrings(
       _In_     LPCTSTR lpSrc,
       _Out_opt_ LPTSTR  lpDst,
       _In_     DWORD   nSize);
   

   就像 `GetEnviromentVariable` 一样, `ExpandEnvironmentStrings` 返回复制到目标缓冲区的字符数, 或者如果缓冲区太小则返回所需的字符数 (加上 NULL 终止符). 以下是一个示例用法:

   WCHAR path[MAX_PATH];
   ::ExpandEnvironmentStrings(L"%windir%\\explorer.exe", path, MAX_PATH);
   printf("%ws\n", path); // c:\windows\explorer.exe
   

BOOL CreateProcess(
    _In_opt_    PCTSTR                pApplicationName,
    _Inout_opt_ PTSTR                 pCommandLine,
    _In_opt_    PSECURITY_ATTRIBUTES  pProcessAttributes,
    _In_opt_    PSECURITY_ATTRIBUTES  pThreadAttributes,
    _In_        BOOL                  bInheritHandles,
    _In_        DWORD                 dwCreationFlags,
    _In_opt_    PVOID                 pEnvironment,
    _In_opt_    PCTSTR                pCurrentDirectory,
    _In_        PSTARTUPINFO          pStartupInfo,
    _Out_       PPROCESS_INFORMATION  lpProcessInformation);

typedef struct _PROCESS_INFORMATION {
    HANDLE hProcess;
    HANDLE hThread;
    DWORD  dwProcessId;
    DWORD  dwThreadId;
} PROCESS_INFORMATION, *PPROCESS_INFORMATION;

void ExitProcess(_In_ UINT exitCode);

BOOL GetExitCodeProcess(
    _In_  HANDLE  hProcess,
    _Out_ LPDWORD lpExitCode);

BOOL TerminateProcess(
    _In_ HANDLE hProcess,
    _In_ UINT   uExitCode);

1.5.1. 作业简介

1.5.2. 创建作业

HANDLE CreateJobObject(
    _In_opt_ LPSECURITY_ATTRIBUTES pJobAttributes,
    _In_opt_ LPCTSTR               pName);

HANDLE OpenJobObject(
    _In_ DWORD   dwDesiredAccess,
    _In_ BOOL    bInheritHandle,
    _In_ PCTSTR  pName);

BOOL AssignProcessToJobObject(
    _In_ HANDLE hJob,
    _In_ HANDLE hProcess);

bool AddProcessToJob(HANDLE hJob, DWORD pid) {
    HANDLE hProcess = ::OpenProcess(PROCESS_SET_QUOTA | PROCESS_TERMINATE, FALSE, pid);
    if(!hProcess)
        return false;
    BOOL success = ::AssignProcessToJobObject(hJob, hProcess);
    ::CloseHandle(hProcess);
    return success ? true : false;
}

1.5.3. 嵌套作业

#include <windows.h>
#include <stdio.h>
#include <assert.h>
#include <string>

HANDLE CreateSimpleProcess(PCWSTR name) {
    std::wstring sname(name);
    PROCESS_INFORMATION pi;
    STARTUPINFO si = { sizeof(si) };
    if (!::CreateProcess(nullptr, const_cast<PWSTR>(sname.data()), nullptr, nullptr,
        FALSE, CREATE_BREAKAWAY_FROM_JOB | CREATE_NEW_CONSOLE,
        nullptr, nullptr, &si, &pi))
        return nullptr;
    ::CloseHandle(pi.hThread);
    return pi.hProcess;
}

HANDLE CreateJobHierarchy() {
    auto hJob1 = ::CreateJobObject(nullptr, L"Job1");
    assert(hJob1);
    auto hProcess1 = CreateSimpleProcess(L"mspaint");

    auto success = ::AssignProcessToJobObject(hJob1, hProcess1);
    assert(success);

    auto hJob2 = ::CreateJobObject(nullptr, L"Job2");
    assert(hJob2);
    success = ::AssignProcessToJobObject(hJob2, hProcess1);
    assert(success);

    auto hProcess2 = CreateSimpleProcess(L"mstsc");
    success = ::AssignProcessToJobObject(hJob2, hProcess2);
    assert(success);

    auto hProcess3 = CreateSimpleProcess(L"cmd");
    success = ::AssignProcessToJobObject(hJob1, hProcess3);
    assert(success);

    // not bothering to close process and job 2 handles
    return hJob1;
}

int main() {
    auto hJob = CreateJobHierarchy();
    printf("Press any key to terminate parent job...\n");
    ::getchar();
    ::TerminateJobObject(hJob, 0);
    return 0;
}

1.5.4. 查询作业信息

BOOL QueryInformationJobObject(
    _In_opt_    HANDLE              hJob,
    _In_        JOBOBJECTINFOCLASS  JobObjectInfoClass,
    _Out_       LPVOID              pJobObjectInfo,
    _In_        DWORD               cbJobObjectInfoLength,
    _Out_opt_   LPDWORD             pReturnLength);

1. 作业统计信息
   

   如前所述, 作业会跟踪一些信息, 无论是否对它施加了任何限制. 基本的统计信息可通过 `JobObjectBasicAccountingInformation` 枚举和 `JOBOBJECT<sub>BASICACCOUNTINGINFORMATION</sub>` 结构获得, 定义如下:

   typedef struct _JOBOBJECT_BASIC_ACCOUNTING_INFORMATION {
       LARGE_INTEGER TotalUserTime;          // total user mode CPU time
       LARGE_INTEGER TotalKernelTime;        // total kernel mode CPU time
       LARGE_INTEGER ThisPeriodTotalUserTime;  // same counters as above
       LARGE_INTEGER ThisPeriodTotalKernelTime;// for a "period"
       DWORD         TotalPageFaultCount;      // page fault count
       DWORD         TotalProcesses;           // total processes ever existed in the job
       DWORD         ActiveProcesses;          // live processes in the job
       DWORD         TotalTerminatedProcesses; // processes terminated because of limit violation
   } JOBOBJECT_BASIC_ACCOUNTING_INFORMATION, *PJOBOBJECT_BASIC_ACCOUNTING_INFORMATION;
   

   各种时间以 `LARGE<sub>INTEGER</sub>` 结构提供, 每个结构都持有一个 64 位的值, 以 100 纳秒为单位. “this period”前缀报告自最近设置的每作业用户/内核时间限制 (如果有的话) 以来的时间. 这些值在作业创建时以及设置新的每作业时间限制时归零.

   以下代码片段显示了如何对作业对象进行基本统计信息的查询调用:

   // assume hJob is a job handle
   JOBOBJECT_BASIC_ACCOUNTING_INFORMATION info;
   BOOL success = QueryInformationJobObject(hJob, JobObjectBasicAccountingInformation,
       &info, sizeof(info), nullptr);
   

   类似地, 使用 `JobObjectBasicAndIoAccountingInformation` 和 `JOBOBJECT<sub>BASICANDIOACCOUNTINGINFORMATION</sub>` 提供了作业的扩展统计信息, 包括 I/O 操作计数和大小. 这个扩展结构包括两个结构, 其中一个是 `JOBOBJECT<sub>BASICACCOUNTINGINFORMATION</sub>`:

   typedef struct _IO_COUNTERS {
       ULONGLONG ReadOperationCount;
       ULONGLONG WriteOperationCount;
       ULONGLONG OtherOperationCount;
       ULONGLONG ReadTransferCount;
       ULONGLONG WriteTransferCount;
       ULONGLONG OtherTransferCount;
   } IO_COUNTERS, *PIO_COUNTERS;
   
   typedef struct JOBOBJECT_BASIC_AND_IO_ACCOUNTING_INFORMATION {
       JOBOBJECT_BASIC_ACCOUNTING_INFORMATION BasicInfo;
       IO_COUNTERS                             IoInfo;
   } JOBOBJECT_BASIC_AND_IO_ACCOUNTING_INFORMATION, *PJOBOBJECT_BASIC_AND_IO_ACCOUNTING_INFORMATION;
   

   读写操作指的是 `ReadFile` 和 `WriteFile` (及类似) API, 我们将在本书后面看到. “其他”操作指的是 `DeviceIoControl` API 的使用, 它用于非读/写操作, 通常针对设备而不是文件系统文件.

   `JobMon` 项目是本章源代码的一部分, 包括了我们讨论的许多作业特性. 运行它会显示图 4-8 中的窗口.

   

   Figure 61: Job Monitor 初始窗口

   单击*创建作业*按钮创建一个空作业. 你可以在创建作业之前为其设置一个名称. 作业创建时没有进程, 并显示基本和 I/O 信息 (图 4-9).

   

   Figure 62: Job Monitor 和一个新创建的作业

   要看到作业统计的实际效果, 请从 https://github.com/zodiacon/AllTools 下载 `CPUStres.exe` 工具. 单击三个点按钮浏览 `CpuStres.exe`. 然后多次单击*创建并添加进程*按钮, 将 `CPUStres` 的实例添加到作业中 (图 4-10). 注意统计信息不再是零.

   

   Figure 63: Job Monitor 和几个 CPUStres 进程

   `CPUStres` 是一个耗费 CPU 的实用程序, 在下一章中会更多地使用. 显示大约每 1.5 秒更新一次. 你可以向作业添加更多进程 (无论是 `CPUStres` 还是其他映像), 并关闭进程. 图 4-11 显示了在添加更多 `CPUStres` 并关闭一些后, Job Monitor 的情况.

   

   Figure 64: Job Monitor 和更多进程

   你可以单击*终止作业*来一次性终止作业中的所有进程. 这是通过调用 `TerminateJobObject` 实现的:

   BOOL TerminateJobObject(
       _In_ HANDLE hJob,
       _In_ UINT   uExitCode);
   

   `TerminateJobObject` 的行为就像作业中每个活动进程都用 `TerminateProcess` 终止一样, 其中 `uExitCode` 是作业中所有进程的退出代码. 此时, 可以向作业添加新进程, 统计信息会正常更新.

2. 查询作业进程列表
   

   可以通过调用 `QueryInformationJobObject` 并使用 `JobObjectBasicProcessIdList` 信息类来检索作业中的活动 (实时) 进程列表, 在 `JOBOBJECT<sub>BASICPROCESSIDLIST</sub>` 结构中返回一个进程 ID 数组:

   typedef struct _JOBOBJECT_BASIC_PROCESS_ID_LIST {
       DWORD     NumberOfAssignedProcesses;
       DWORD     NumberOfProcessIdsInList;
       ULONG_PTR ProcessIdList;
   } JOBOBJECT_BASIC_PROCESS_ID_LIST, *PJOBOBJECT_BASIC_PROCESS_ID_LIST;
   

   该结构由于进程 ID 数组而具有可变大小. 这意味着一个固定大小的数组应该足够大以包含所有进程 ID, 并希望如此. 或者, 可以使用动态分配的缓冲区, 如果不够大, 则调整其大小. 以下示例显示了如何检索活动进程列表, 同时根据需要分配足够大的缓冲区.

   #include <vector>
   #include <memory>
   
   std::vector<DWORD> GetJobProcessList(HANDLE hJob) {
       auto size = 256;
       std::vector<DWORD> pids;
       while (true) {
           auto buffer = std::make_unique<BYTE[]>(size);
           auto ok = ::QueryInformationJobObject(hJob, JobObjectBasicProcessIdList,
               buffer.get(), size, nullptr);
           if (!ok && ::GetLastError() == ERROR_MORE_DATA) {
               // buffer too small - resize and try again
               size *= 2;
               continue;
           }
           if (!ok)
               break;
   
           auto info = reinterpret_cast<JOBOBJECT_BASIC_PROCESS_ID_LIST*>(buffer.get());
           pids.reserve(info->NumberOfAssignedProcesses);
           for (DWORD i = 0; i < info->NumberOfAssignedProcesses; i++)
               pids.push_back((DWORD)info->ProcessIdList[i]);
           break;
       }
       return pids;
   }
   

   代码使用了一些 C++ 构造来简化内存管理. 函数本身返回一个 `std::vector<DWORD>`, 其中包含作业中的进程 ID. 在最一般的情况下, 预先不知道进程的数量, 因此函数用 `std::make<sub>unique</sub><BYTE[]>` 分配一个缓冲区, 该缓冲区分配一个给定元素数量 (大小) 的字节数组. `unique<sub>ptr</sub>` 的析构函数在它超出作用域时释放缓冲区.

   接下来, 用分配的字节缓冲区调用 `QueryInformationJobObject`. 如果它返回 `FALSE` 并且 `GetLastError` 返回 `ERROR<sub>MOREDATA</sub>`, 这意味着分配的缓冲区太小, 所以函数将大小加倍并重试.

   一旦缓冲区足够大, 指针就被转换为 `JOBOBJECT<sub>BASICPROCESSIDLIST</sub>*`, 并且可以检索进程 ID 并将其放入 `std::vector` 中. 奇怪的是, 此结构中返回的进程 ID 类型为 `ULONG<sub>PTR</sub>`, 这意味着在 64 位进程中每个 ID 都是 64 位. 这是不寻常的, 因为进程 ID 通常是 32 位值 (`DWORD`). 这就是为什么我们不能简单地将整个数组一次性复制到向量中 (除非将向量更改为持有 `ULONG<sub>PTR</sub>`).

   你可能会好奇为什么进程 ID 的类型是 `ULONG<sub>PTR</sub>`. 这是 Windows API 中很少发生的情况之一. 在内核内部, 进程 (和线程) ID 是使用一个专门为此目的的私有句柄表生成的. 而且由于 64 位系统上的句柄是 64 位值, 所以按原样使用它们可能“自然地”容易. 尽管如此, 由于句柄表限制在大约 1600 万个句柄, 目前不需要 64 位值 (并且不在内核外部用于进程 ID).

1.5.5. 设置作业限制

BOOL SetInformationJobObject(
    _In_ HANDLE             hJob,
    _In_ JOBOBJECTINFOCLASS JobObjectInfoClass,
    _In_ PVOID              pJobObjectInfo,
    _In_ DWORD              cbJobObjectInfoLength);

typedef struct _JOBOBJECT_BASIC_LIMIT_INFORMATION {
    LARGE_INTEGER PerProcessUserTimeLimit;
    LARGE_INTEGER PerJobUserTimeLimit;
    DWORD         LimitFlags;
    SIZE_T        MinimumWorkingSetSize;
    SIZE_T        MaximumWorkingSetSize;
    DWORD         ActiveProcessLimit;
    ULONG_PTR     Affinity;
    DWORD         PriorityClass;
    DWORD         SchedulingClass;
} JOBOBJECT_BASIC_LIMIT_INFORMATION, *PJOBOBJECT_BASIC_LIMIT_INFORMATION;

typedef struct _JOBOBJECT_EXTENDED_LIMIT_INFORMATION {
    JOBOBJECT_BASIC_LIMIT_INFORMATION BasicLimitInformation;
    IO_COUNTERS                       IoInfo;
    SIZE_T                            ProcessMemoryLimit;
    SIZE_T                            JobMemoryLimit;
    SIZE_T                            PeakProcessMemoryUsed;
    SIZE_T                            PeakJobMemoryUsed;
} JOBOBJECT_EXTENDED_LIMIT_INFORMATION, *PJOBOBJECT_EXTENDED_LIMIT_INFORMATION;

bool SetJobPriorityClass(HANDLE hJob) {
    JOBOBJECT_BASIC_LIMIT_INFORMATION info;
    info.LimitFlags = JOB_OBJECT_LIMIT_PRIORITY_CLASS;
    info.PriorityClass = BELOW_NORMAL_PRIORITY_CLASS;
    return ::SetInformationJobObject(hJob, JobObjectBasicLimitInformation,
        &info, sizeof(info));
}

1. CPU 速率限制
   

   Windows 8 为可用的作业限制添加了 CPU 速率限制, 这不是由基本或扩展限制设置的, 而是使用其自己的作业限制枚举: `JobObjectCpuRateControlInformation`. 相关的结构是 `JOBOBJECT<sub>CPURATECONTROLINFORMATION</sub>`, 定义如下:

   typedef struct _JOBOBJECT_CPU_RATE_CONTROL_INFORMATION {
       DWORD ControlFlags;
       union {
           DWORD CpuRate;
           DWORD Weight;
           struct {
               WORD MinRate;
               WORD MaxRate;
           };
       };
   } JOBOBJECT_CPU_RATE_CONTROL_INFORMATION, *PJOBOBJECT_CPU_RATE_CONTROL_INFORMATION;
   

   有三种不同的方式来设置 CPU 速率限制, 由 `ControlFlags` 字段控制. 其可能的值在表 4-5 中总结.

   标志 (JOBOBJECTCPURATE*)	描述
   ENABLE (1)	启用 CPU 速率控制
   WEIGHTBASED (2)	CPU 速率基于相对权重 (`Weight` 成员)
   HARDCAP (4)	为 CPU 消耗设置硬上限
   NOTIFY (8)	通知与作业关联的 I/O 完成端口 (如果有的话) 速率违规
   MINMAXRATE (0x10)	在最小值和最大值之间设置 CPU 速率 (`MinRate` 和 `MaxRate` 成员)

   如果启用了 CPU 速率控制, 并且未指定 `JOB<sub>OBJECTCPURATECONTROLWEIGHTBASED</sub>` 或 `JOB<sub>OBJECTCPURATECONTROLMINMAXRATE</sub>`, 那么 `CpuRate` 成员指定相对于 10000 的 CPU 限制百分比. 例如, 如果需要 15% 的 CPU, 该值应设置为 1500. 这允许指定小数 CPU 速率.

   如果还指定了 `JOB<sub>OBJECTCPURATECONTROLHARDCAP</sub>` 标志, 则限制是硬性的——即使有可用的 CPU, 作业也不会获得更多的 CPU. 没有此标志, 如果有可用的处理器, 作业可能会获得更多的 CPU 时间.

   在幕后, 内核通过测量作业在 300 毫秒时间间隔内的 CPU 消耗来应用这些限制, 允许/阻止它在下一个间隔内执行.

   `CpuLimit` 项目演示了如何使用 `CpuRate` 成员和硬上限来控制 CPU 速率. `main` 函数接受一个要放入作业的进程 ID 数组, 以及一个用作硬 CPU 速率限制的百分比.

   以下是 `main` 的开头:

   int main(int argc, const char* argv[]) {
       if (!::IsWindows8OrGreater()) {
           printf("CPU Rate control is only available on Windows 8 and later\n");
           return 1;
       }
   
       if (argc < 3) {
           printf("Usage: CpuLimit <pid> [<pid> ...] <precentage>\n");
           return 0;
       }
   
       // create the job object
       HANDLE hJob = ::CreateJobObject(nullptr, L"CpuRateJob");
       if (!hJob)
           return Error("Failed to create object");
   
       for (int i = 1; i < argc - 1; i++) {
           int pid = atoi(argv[i]);
           HANDLE hProcess = ::OpenProcess(PROCESS_SET_QUOTA | PROCESS_TERMINATE,
               FALSE, pid);
           if (!hProcess) {
               printf("Failed to open handle to process %d (error=%d)\n", pid,
                   ::GetLastError());
               continue;
           }
           if (!::AssignProcessToJobObject(hJob, hProcess)) {
               printf("Failed to assign process %d to job (error=%d)\n", pid,
                   ::GetLastError());
           }
           else {
               printf("Added process %d to job\n", pid);
           }
           ::CloseHandle(hProcess);
       }
   }
   

   `main` 首先检查应用程序是否至少在 Windows 8 上执行, 因为 CPU 速率控制在早期版本中不可用. 然后, 程序通过检查至少 3 个参数 (程序本身, PID, 速率) 来验证至少有一个进程 ID 和一个 CPU 百分比.

   然后创建一个作业对象, 并带有名称, 以便更容易用工具识别. 每个进程都被打开并分配给作业, 如果可能的话.

   现在程序准备好应用 CPU 速率控制:

       JOBOBJECT_CPU_RATE_CONTROL_INFORMATION info;
       info.CpuRate = atoi(argv[argc - 1]) * 100;
       info.ControlFlags = JOB_OBJECT_CPU_RATE_CONTROL_ENABLE |
           JOB_OBJECT_CPU_RATE_CONTROL_HARD_CAP;
   
       if (!::SetInformationJobObject(hJob, JobObjectCpuRateControlInformation,
           &info, sizeof(info)))
           return Error("Failed to set job limits");
   
       printf("CPU limit set successfully.\n");
   
       printf("Press ENTER to quit.\n");
       char dummy[10];
       gets_s(dummy);
   
       ::CloseHandle(hJob);
       return 0;
   }
   

   CPU 速率限制是通过从命令行获取参数并乘以 100 来计算的. 最后, 调用 `SetInformationJobObject` 来设置限制.

   在程序退出之前, 它会等待用户按 ENTER. 这使得作业对象的句柄保持打开状态, 因此更容易用工具发现. 否则, 句柄将被关闭, 标记作业为删除. 然而, 只要有活动的进程, 限制仍然适用.

   让我们通过启动两个 `CpuStress` 应用程序的实例来测试这个 (图 4-16). 这里使用的系统有 16 个逻辑处理器, 所以我们将在它们两个中都激活 4 个具有最大活动的线程. 这应该消耗系统上所有 CPU 时间的大约 50% (图 4-17). 任务管理器显示情况确实如此 (图 4-18).

   

   Figure 69: 启动时的 2 个 CPU Stress 实例

   

   Figure 70: 2 个具有 4 个最大活动线程的 CPU Stress

   

   Figure 71: 任务管理器显示 50% 的 CPU 使用率

   现在我们用进程 ID 和所需的 CPU 速率限制 (本例中为 20%) 执行 `CpuLimit`:

   cpulimit 38984 28760 20
   

   你应该会看到一组成功消息, 像这样:

   CpuLimit.exe 20132 17480 20
   Added process 20132 to job
   Added process 17480 to job
   CPU limit set successfully.
   Press ENTER to quit.
   

   此时, 你应该能看到两个 `CPUStress` 实例的 CPU 消耗下降 (图 4-19). 两者消耗的总 CPU 应该在 20% 左右, 可以在任务管理器中看到.

   打开 Job Explorer 并查看 `CpuRateJob` 作业 (这是代码中为方便识别而给定的名称) 应该会显示 CPU 速率限制 (图 4-20).

   不幸的是, 在撰写本文时, Process Explorer 不显示作业的 CPU 速率控制信息.

   

   Figure 72: CPU Stress 实例受 CPU 速率控制影响

   

   Figure 73: Job Explorer 显示 CPU 速率控制

   如果 `CpuLimit` 添加进程时失败并出现错误 5 (访问被拒绝), 请从命令窗口运行 `CpuStress` 而不是通过资源管理器. 如果你好奇, 请调查为什么会这样.

2. 用户界面限制
   

   另一组作业限制可通过 `JobObjectBasicUIRestrictions` 信息类获得, 用于与用户界面相关的限制. 这些由一个简单的结构中存储的单个 32 位值表示:

   typedef struct _JOBOBJECT_BASIC_UI_RESTRICTIONS {
       DWORD UIRestrictionsClass;
   } JOBOBJECT_BASIC_UI_RESTRICTIONS, *PJOBOBJECT_BASIC_UI_RESTRICTIONS;
   

   可用的限制是表 4-6 中列出的位标志.

   使用 UI 限制的作业不能是作业层次结构的一部分.

   UI 标志 (JOBOBJECTUILIMIT*)	描述
   NONE (0)	无限制
   HANDLES (1)	作业中的进程不能访问不属于作业的进程拥有的 USER 句柄 (例如窗口)
   READCLIPBOARD (2)	作业中的进程不能从剪贴板读取数据
   WRITECLIPBOARD (4)	作业中的进程不能向剪贴板写入数据
   SYSTEMPARAMETERS (8)	作业中的进程不能通过调用 `SystemParametersInfo` 更改系统参数
   DISPLAYSETTINGS (0x10)	作业中的进程不能调用 `ChangeDisplaySettings`
   GLOBALATOMS (0x20)	作业中的进程不能访问全局原子. 作业有自己的原子表 (见下一个侧边栏)
   DESKTOP (0x40)	作业中的进程不能创建或切换桌面 (`CreateDesktop`, `SwitchDesktop`)
   EXITWINDOWS (0x80)	作业中的进程不能调用 `ExitWindows` 或 `ExitWindowsEx`

   原子表是一个系统管理的表, 它将字符串 (或某个范围内的整数) 映射到整数. 表中的每个条目都是一个原子. 这些原子与用户界面 API 一起使用, 例如在注册窗口类 (`RegisterClass` / `RegisterClassEx`) 时, 或通过手动操作原子表 (`AddAtom`, `FindAtom`, `GlobalAddAtom` 等). 全局原子表对所有应用程序都可用——这就是在作业中用 `JOB<sub>OBJECTUILIMITGLOBALATOMS</sub>` 限制的那个.

   这里有一个快速实验来展示 UI 限制的一个效果. 打开 Job Monitor, 创建一个新作业并在其中插入一个 Notepad 实例. 然后设置一个*写入剪贴板*的 UI 限制 (图 4-21).

   

   Figure 74: Job Monitor 和一个 Notepad 及 UI 限制

   现在在作业外部打开另一个 Notepad 实例 (或使用任何其他文本编辑应用程序). 从该应用程序复制一些文本, 然后尝试将其粘贴到作业中的 Notepad 实例中. 该操作应该会失败, 即使*编辑*菜单显示*粘贴*选项已启用.

   `JOB<sub>OBJECTUILIMITHANDLES</sub>` 标志阻止作业中的进程访问作业外部的其他用户界面对象 (例如窗口). 这意味着调用诸如 `PostMessage` 或 `SendMessage` 到作业外部的窗口会失败. 在某些情况下, 需要从作业内部与作业外部的特定窗口通信. 作业外部的进程可以通过调用 `UserHandleGrantAccess` 来授予 (或移除) 对窗口 (或其他 USER 对象, 如菜单或钩子) 的访问权限:

   BOOL UserHandleGrantAccess(
       _In_ HANDLE hUserHandle, // user object handle
       _In_ HANDLE hJob,        // job handle
       _In_ BOOL   bGrant);     // TRUE to grant access, FALSE to remove it
   

   上一段中提到的“钩子”是那些可以用 `SetWindowsHookEx` 安装的钩子之一 (在后面的章节中讨论). 在此限制下, 作业中的进程无法钩住作业外部进程中运行的线程.

wil::unique_handle hCompletionPort(::CreateIoCompletionPort(
    INVALID_HANDLE_VALUE, nullptr, 0, 0));

JOBOBJECT_ASSOCIATE_COMPLETION_PORT info;
info.CompletionKey = 0; // application defined
info.CompletionPort = hCompletionPort.get();
::SetInformationJobObject(m_hJob.get(), JobObjectAssociateCompletionPortInformation,
    &info, sizeof(info));

// transfer ownership and store in a member
m_hCompletionPort = std::move(hCompletionPort);

BOOL GetQueuedCompletionStatus(
    _In_      HANDLE       CompletionPort,
    _Out_     PDWORD       pNumberOfBytesTransferred,
    _Out_     PULONG_PTR   lpCompletionKey,
    _Out_     LPOVERLAPPED *pOverlapped,
    _In_      DWORD        dwMilliseconds);

// create a thread to monitor notifications
wil::unique_handle hThread(::CreateThread(nullptr, 0, [](auto p) {
    return static_cast<CMainDlg*>(p)->DoMonitorJob();
}, this, 0, nullptr));

DWORD CMainDlg::DoMonitorJob() {
    for (;;) {
        DWORD message;
        ULONG_PTR key;
        LPOVERLAPPED data;
        if (::GetQueuedCompletionStatus(m_hCompletionPort.get(),
            &message, &key, &data, INFINITE)) {
            // handle notification
        }
    }
}