Windows内核函数 - 枚举子项

        在注册表的操作中，还经常有另外两种操作，分别是枚举子项和枚举子键。枚举子项就是事先不知道该项中有多少个子项目，用某个函数将子项一一列举出来。而枚举子键是事先不知道该项中有多少个子键，用某个函数一一将子键列举出来。

        DDK提供了列举子项的函数，它是 ZwQueryKey 函数（注意不是ZwQueryValueKey函数）和ZwEnumerateKey。西安看一下这两个函数的声明。

NTSTATUS ZwQueryKey(
    IN HANDLE KeyHandle,
    IN KEY_INFORMATION_CLASS KeyInformationClass,
    OUT PVOID KeyInformation,
    IN ULONG Length,
    OUT PULONG ResultLength
    );
// KeyHandle: 注册表项的句柄
// KeyInformationClass: 查询的类别，一般选择 KeyFullInformation.
// KeyInformation: 查询的数据指针。如果 KeyInformationClass 是KeyFullInformation, 则该指针指向一个 KEY_FULL_INFORMATION 的数据结构。
// Length: 数据长度
// ResultLength: 返回的数据长度。
// 返回值：只是查询是否成功。

NTSTATUS ZwEnumerateKey(
    IN HANDLE KeyHandle,
    IN ULONG Index,
    IN KEY_INFORMATION_CLASS KeyInformationClass,
    out PVOID KeyInformation,
    IN ULONG Length,
    out PULONG ResultLength
    );
    
// KeyHandle: 注册表项的句柄
// Index: 很少用到，一般为0
// KeyInformationClass: 该子项的信息
// Length: 子项信息的长度
// ResultLength: 返回子键信息的长度。
// 返回值：指明枚举是否成功。

        ZwQueryKey 的作用主要是获得某注册表项究竟有多少个子项，而 ZwEnumerateKey 的作用主要是针对第几个子项获取该子项的基本信息。

        在使用 ZwQueryKey 时，可以将参数 KeyInformationClass 指定为 KeyFullInformation。 这样参数 KeyInformation 就对应一个 KEY_FULL_INFORMATION 的数据结构，该数据结构中的 SubKeys指明了项中有多少个子项。

        KEY_FULL_INFORMATION 数据结构的大小是边长的，所以要调用两次 ZwQueryKey。 第一次获取 KEY_FULL_INFORMATION 数据的长度，第二次真正获取 KEY_FULL_INFORMATION 数据。

        在使用 ZwEnumerateKey 时，需要将参数 KeyInformationClass 设置为 KeyBasicInformation, 这样其参数 KeyInformation 就能对应 KEY_BASIC_INFORMATION 的数据结构。

        同理， KEY_BASIC_INFORMATION 也是变长的数据结构，需要两次调用 ZwEnumerateKey ，第一次获取 KEY_BASIC_INFORMATION 的长度， 第二次获取 KEY_BASIC_INFORMATION 数据。

下面的例子演示了如何枚举子键。

UNICODE_STRING RegUnicodeStr;
	HANDLE hRegister;

	// 初始化 UNICODE_STRING 字符串
	RtlInitUnicodeString(&RegUnicodeStr,
		MY_REG_SOFTWARE_KEY_NAME);

	OBJECT_ATTRIBUTES objectAttributes;

	// 初始化objectAttributes
	InitializeObjectAttributes(&objectAttributes,
		&RegUnicodeStr,
		OBJ_CASE_INSENSITIVE, // 对大小写敏感
		NULL,
		NULL
		);

	// 打开注册表项
	NTSTATUS ntStatus = ZwOpenKey(&hRegister,
		KEY_ALL_ACCESS,
		&objectAttributes);

	// 判断操作是否成功
	if (NT_SUCCESS(ntStatus))
	{
		KdPrint(("Open register successfully. \n"));
	}


	// 第一次调用ZwQueryKey，为了获取PKEY_FULL_INFORMATION 数据的长度
	ULONG ulSize;
	ZwQueryKey(hRegister,		
		KeyFullInformation,
		NULL,
		0,
		&ulSize);


	PKEY_FULL_INFORMATION pfi =
		(PKEY_FULL_INFORMATION)ExAllocatePool(PagedPool, ulSize);

	// 第二次调用ZwQueryKey，为了获取 KEY_FULL_INFORMATION 数据
	ZwQueryKey(hRegister,
		KeyFullInformation,
		pfi,
		ulSize,
		&ulSize);


	for (ULONG i = 0; i < pfi->SubKeys; i++)
	{
		// 第一次调用 ZwEnumerateKey, 为了获取 KEY_BASIC_INFORMATION 数据的长度
		ZwEnumerateKey(hRegister,
			i,
			KeyBasicInformation,
			NULL,
			0,
			&ulSize);

		PKEY_BASIC_INFORMATION pbi =
			(PKEY_BASIC_INFORMATION)ExAllocatePool(PagedPool, ulSize);


		// 第二次调用 ZwEnumerateKey, 为了获取 KEY_BASIC_INFORMATION 数据
		ZwEnumerateKey(hRegister,
			i,
			KeyBasicInformation,
			pbi,
			ulSize,
			&ulSize);

		UNICODE_STRING uniKeyName;
		uniKeyName.Length = pbi->NameLength;
		uniKeyName.MaximumLength = pbi->NameLength;
		uniKeyName.Buffer = pbi->Name;
		KdPrint(("The %d sub item name: %wZ\n", i, &uniKeyName));

		// 回收内存
		ExFreePool(pbi);
	}

	// 回收内存
	ExFreePool(pfi);
	
	// 关闭句柄
	ZwClose(hRegister);