Функция 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	WdfRegistryQueryMultiString не был вызван в IRQL = PASSIVE_LEVEL.
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, см. в ошибках создания объектов Платформы.

Этот метод также может возвращать другие значения NTSTATUS.

Ошибка возникает, если драйвер предоставляет недопустимый дескриптор объекта.

Замечания

Прежде чем драйвер вызывает 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 (include Wdf.h)
библиотеки	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
правил соответствия DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)