Функция WdfRegistryQueryMultiString (wdfregistry.h)

Статья
08/08/2023

[Применимо к 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 драйвер может вызвать WdfCollectionGetCount , чтобы получить количество полученных строк, и WdfCollectionGetItem для получения строковых объектов из коллекции.

Если коллекция содержит объекты до вызова драйвера метода WdfRegistryQueryMultiString , метод не удаляет эти объекты и не изменяет их значения индекса. Новые объекты добавляются в конец коллекции.

Чтобы получить строку из строкового объекта, драйвер может вызвать WdfStringGetUnicodeString.

Дополнительные сведения об объектах раздела реестра см. в разделе Использование реестра в Framework-Based Drivers.

Примеры

В следующем примере кода создается объект коллекции, инициализируется структура 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)