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

Статья
08/08/2023

[Относится к KMDF и UMDF]

Метод WdfRegistryQueryUnicodeString извлекает строковые данные, назначенные указанному значению строки реестра, и копирует строку в указанную структуру UNICODE_STRING .

Синтаксис

NTSTATUS WdfRegistryQueryUnicodeString(
  [in]            WDFKEY           Key,
  [in]            PCUNICODE_STRING ValueName,
  [out, optional] PUSHORT          ValueByteLength,
  [in, out]       PUNICODE_STRING  Value
);

Параметры

[in] Key

Дескриптор для объекта раздела реестра, представляющего открытый раздел реестра.

[in] ValueName

Указатель на структуру UNICODE_STRING , содержащую имя для значения реестра.

[out, optional] ValueByteLength

Указатель на расположение, которое получает количество байтов, содержащихся в строке Юникода, на которую указывает Значение , включая конечный байт NULL . Этот указатель является необязательным и может иметь значение NULL.

[in, out] Value

Указатель на структуру UNICODE_STRING, которая получает строку данных для ключа, указанного ключом . Если этот параметр имеет значение NULL , а ValueByteLength не равен NULL, WdfRegistryQueryUnicodeString возвращает только размер строки.

Возвращаемое значение

WdfRegistryQueryUnicodeString возвращает STATUS_SUCCESS, если операция выполнена успешно. В противном случае метод может вернуть одно из следующих значений:

Код возврата	Описание
STATUS_INVALID_DEVICE_REQUEST	WdfRegistryQueryUnicodeString не был вызван в 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_SZ.
STATUS_BUFFER_OVERFLOW	Буфер, на который указывает параметр Value , был слишком мал, и в буфер были записаны только частичные данные.
STATUS_BUFFER_OVERFLOW	Буфер, на который указывает параметр Value , был слишком мал, и данные не были записаны в буфер.
STATUS_OBJECT_NAME_NOT_FOUND	Значение реестра недоступно.

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

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

В следующем примере кода, который является примером драйвера Serial , извлекается строка Юникода, представляющая строковые данные, назначенные значению PortName в аппаратном ключе устройства.

NTSTATUS
SerialReadSymName(
    IN WDFDEVICE Device,
    __out PWCHAR RegName,
    IN OUT PUSHORT LengthOfRegName // In characters
    )
{
    NTSTATUS status;
    WDFKEY hKey;
    UNICODE_STRING value;
    UNICODE_STRING valueName;
    USHORT requiredLength;

    value.Buffer = RegName;
    value.MaximumLength = *LengthOfRegName;
    value.Length = 0;

    status = WdfDeviceOpenRegistryKey(
                                      Device,
                                      PLUGPLAY_REGKEY_DEVICE,
                                      STANDARD_RIGHTS_ALL,
                                      WDF_NO_OBJECT_ATTRIBUTES,
                                      &hKey
                                      );

    if (NT_SUCCESS (status)) {
        RtlInitUnicodeString(
                             &valueName,
                             L"PortName"
                             );
        status = WdfRegistryQueryUnicodeString (
                                      hKey,
                                      &valueName,
                                      &requiredLength,
                                      &value
                                      );
        WdfRegistryClose(hKey);
    }
    return status;
}

Требования

Требование	Значение
Целевая платформа	Универсальное
Минимальная версия 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)