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

Статья
02/07/2025

[Применимо к 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	Буфер, на который указывает параметр значение, слишком мал, и в буфер записываются только частичные данные.
STATUS_BUFFER_OVERFLOW	Буфер, на который указывает параметр , слишком мал, и данные не записываются в буфер.
STATUS_OBJECT_NAME_NOT_FOUND	Значение реестра недоступно.

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

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

Замечания

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

Примеры

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