WdfRegistryQueryMultiString 函数（wdfregistry.h）

项目
02/07/2025

[适用于 KMDF 和 UMDF]

WdfRegistryQueryMultiString 方法检索当前分配给指定多字符串注册表值的字符串，为每个字符串创建框架字符串对象，并将每个字符串对象添加到指定的对象集合。

语法

NTSTATUS WdfRegistryQueryMultiString(
  [in]           WDFKEY                 Key,
  [in]           PCUNICODE_STRING       ValueName,
  [in, optional] PWDF_OBJECT_ATTRIBUTES StringsAttributes,
  [in]           WDFCOLLECTION          Collection
);

参数

[in] Key

表示已打开的注册表项的注册表项对象的句柄。

[in] ValueName

指向包含值名称的 UNICODE_STRING 结构的指针。

[in, optional] StringsAttributes

指向 WDF_OBJECT_ATTRIBUTES 结构的指针，该结构包含每个新字符串对象的对象属性。此参数是可选的，可以WDF_NO_OBJECT_ATTRIBUTES。

[in] Collection

驱动程序提供的框架集合对象的句柄。

返回值

如果作成功，WdfRegistryQueryMultiString 返回STATUS_SUCCESS。否则，该方法可能会返回以下值之一：

返回代码	描述
STATUS_INVALID_DEVICE_REQUEST	在 IRQL = PASSIVE_LEVEL 中未调用 WdfRegistryQueryMultiString。
STATUS_INVALID_PARAMETER	指定了无效参数。
STATUS_INSUFFICIENT_RESOURCES	无法分配字符串对象。
STATUS_ACCESS_DENIED	驱动程序未使用KEY_QUERY_VALUE、KEY_READ或KEY_ALL_ACCESS访问打开注册表项。
STATUS_OBJECT_TYPE_MISMATCH	指定的 ValueName 参数未REG_MULTI_SZ注册表值的数据类型。
STATUS_OBJECT_NAME_NOT_FOUND	注册表值不可用。
STATUS_RESOURCE_DATA_NOT_FOUND	注册表值存在于指定的键下，但为空。

有关 WdfRegistryQueryMultiString 方法可能返回的其他返回值的列表，请参阅 Framework 对象创建错误。

此方法还可以返回其他NTSTATUS 值。

如果驱动程序提供无效的对象句柄，则会发生 bug 检查。

言论

在驱动程序调用 WdfRegistryQueryMultiString之前，它必须调用 WdfCollectionCreate 来创建集合对象。

如果调用方未提供 StringsAttributes 参数，则框架创建的任何 WDFSTRING 对象默认为 WDFDRIVER 父级。

WdfRegistryQueryMultiString 返回后，驱动程序可以调用 WdfCollectionGetCount 以获取检索到的字符串数，WdfCollectionGetItem 以获取集合中的字符串对象。

如果集合包含驱动程序调用 WdfRegistryQueryMultiString 方法之前的对象，该方法不会删除这些对象或更改其索引值。新对象将追加到集合的末尾。

若要从字符串对象获取字符串，驱动程序可以调用 WdfStringGetUnicodeString。

有关注册表项对象的详细信息，请参阅使用 Framework-Based 驱动程序中的注册表。

例子

下面的代码示例创建一个集合对象，初始化 WDF_OBJECT_ATTRIBUTES 结构，以便集合对象将是框架为集合创建的所有字符串对象的父对象，并从多字符串注册表值检索字符串。最后，该示例获取框架添加到集合中的字符串对象数。

WDF_OBJECT_ATTRIBUTES stringAttributes;
WDFCOLLECTION col;
NTSTATUS status;
ULONG count;
DECLARE_CONST_UNICODE_STRING(valueMultiSz, VALUE_MULTI_SZ);

status = WdfCollectionCreate(
                             NULL,
                             &col
                             );
ASSERT(NT_SUCCESS(status));

WDF_OBJECT_ATTRIBUTES_INIT(&stringAttributes);
stringAttributes.ParentObject = col;

status = WdfRegistryQueryMultiString(
                                     Key,
                                     &valueMultiSzEmpty,
                                     &stringAttributes,
                                     col
                                     );

count = WdfCollectionGetCount(col);

要求

要求	价值
目标平台	普遍
最低 KMDF 版本	1.0
最低 UMDF 版本	2.0
标头	wdfregistry.h （包括 Wdf.h）
库	Wdf01000.sys（KMDF）：WUDFx02000.dll （UMDF）
IRQL	PASSIVE_LEVEL
DDI 符合性规则	DriverCreate（kmdf），KmdfIrql（kmdf），KmdfIrql2（kmdf），KmdfIrqlExplicit（kmdf）