Метод IWDFUnifiedPropertyStore::GetPropertyData (wudfddi.h)

Статья
08/08/2023

[Предупреждение: UMDF 2 является последней версией UMDF и заменяет UMDF 1. Все новые драйверы UMDF должны быть написаны с помощью UMDF 2. Новые функции не добавляются в UMDF 1, а поддержка UMDF 1 в более новых версиях Windows 10 ограничена. Универсальные драйверы Windows должны использовать UMDF 2. Дополнительные сведения см. в разделе начало работы с помощью UMDF.]

Метод GetPropertyData извлекает текущее значение для свойства устройства.

Синтаксис

HRESULT GetPropertyData(
  [in]            const DEVPROPKEY *PropertyKey,
  [in]            LCID             Lcid,
  [in]            ULONG            Flags,
  [in]            ULONG            PropertyDataSize,
  [out, optional] PVOID            PropertyData,
  [out]           ULONG            *PropertyDataRequiredSize,
  [out]           DEVPROPTYPE      *PropertyType
);

Параметры

[in] PropertyKey

Указатель на структуру DEVPROPKEY , задающую ключ свойства устройства.

[in] Lcid

Указывает идентификатор языкового стандарта. Задайте для этого параметра значение LCID для конкретного языка или LOCALE_NEUTRAL. Код LOCALE_NEUTRAL указывает, что свойство не зависит от языка (т. е. не относится к какому-либо языку). Не устанавливайте для этого параметра значение LOCALE_SYSTEM_DEFAULT или LOCALE_USER_DEFAULT. Дополнительные сведения о значениях LCID для конкретного языка см. в разделе Структура LCID.

[in] Flags

Зарезервировано для системного использования. Драйверы должны задать для этого значения значение 0.

[in] PropertyDataSize

Размер (в байтах) буфера, на который указывает PropertyData .

[out, optional] PropertyData

Указатель на данные свойства устройства.

[out] PropertyDataRequiredSize

Указатель на ULONG для получения размера сведений о свойстве, возвращаемых в PropertyData.

[out] PropertyType

Указатель на значение DEVPROPTYPE . Если getPropertyData завершается успешно, метод использует PropertyType для указания типа данных, возвращаемых в буфер PropertyData .

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

GetPropertyData возвращает S_OK, если операция выполнена успешно. В противном случае метод может вернуть следующие значения.

Код возврата	Описание
E_OUTOFMEMORY	Попытка платформы выделить память завершилась сбоем.
HRESULT_FROM_NT(STATUS_BUFFER_TOO_SMALL)	Параметр PropertyDataRequiredSize содержит размер требуемого буфера.
HRESULT_FROM_WIN32 (ERROR_INVALID_PARAMETER)	Если драйвер указывает WdfPropertyStoreRootClassDeviceInterfaceKey, запрошенным интерфейсом должен быть ранее зарегистрированный драйвером UMDF.
HRESULT_FROM_WIN32 (STATUS_NOT_SUPPORTED)	Драйвер может запрашивать данные свойств интерфейса устройства только начиная с Windows 8.

Этот метод может возвращать одно из других значений, содержащихся в Winerror.h .

В частности, этот метод можно использовать для получения аппаратного ключа устройства или экземпляра класса интерфейса устройства. При вызове IWDFUnifiedPropertyStoreFactory::RetrieveUnifiedDevicePropertyStore задайте для элемента RootClass параметра RootSpecifier значение WdfPropertyStoreRootClassHardwareKey или WdfPropertyStoreRootClassDeviceInterfaceKey.

Если указать WdfPropertyStoreRootClassHardwareKey, то при вызове GetPropertyData необходимо указать пользовательское значение DEVPROPKEY в параметре PropertyKey , а не ключ, определяемый PnP. Значение должно быть задано ранее путем вызова SetPropertyData, функции свойства устройства SetupDI или с помощью директивы INF AddProperty.

Дополнительные сведения о свойствах устройства см. в разделе Свойства устройства.

Дополнительные сведения о доступе к реестру см. в разделе Использование реестра в драйверах на основе UMDF.

Примеры

Для свойств переменной размера драйвер должен выполнить два прохода для получения данных свойства. Сначала драйвер должен передать буфер NULL в параметре PropertyData и присвоить свойству PropertyDataSize значение 0. Затем драйвер должен выделить буфер на основе возвращаемого значения PropertyDataRequiredSize и снова вызвать Метод GetPropertyData , передав выделенный буфер.

Следующий пример демонстрирует этот подход.

HRESULT
GetFriendlyName(
    _In_ IWDFUnifiedPropertyStore * pUnifiedPropertyStore
    )
{
    HRESULT hr = S_OK;
    DEVPROPTYPE type;
    ULONG requiredSize;
    BYTE * friendlyNameBuffer = NULL;
    ULONG friendlyNameBufferSize;

    hr = pUnifiedPropertyStore->GetPropertyData(
            &DEVPKEY_Device_FriendlyName,
            0, //Lcid
            0, //Flags
            0, //BufferSize
            NULL, //Buffer
            &requiredSize,
            &type
            );

    if (HRESULT_CODE(hr) != ERROR_INSUFFICIENT_BUFFER)
    {
        TraceEvents(
            TRACE_LEVEL_ERROR, 
            TEST_TRACE_DEVICE, 
            "GetPropertyData failed: hr = %!HRESULT!",
            hr
            );
        goto exit;
    }

    friendlyNameBufferSize = requiredSize;
    friendlyNameBuffer = new BYTE[requiredSize];
    if (NULL == friendlyNameBuffer)
    {
        hr = E_OUTOFMEMORY;
        TraceEvents(
            TRACE_LEVEL_ERROR, 
            TEST_TRACE_DEVICE, 
            "Out of memory while allocating property data buffer returning:”
            “ %!HRESULT!",
            hr
            );
        goto exit;
    }
    
    hr = pUnifiedPropertyStore->GetPropertyData(
            &DEVPKEY_Device_FriendlyName,
            0, //Lcid
            0, //Flags
            friendlyNameBufferSize,
            friendlyNameBuffer,
            &requiredSize,
            &type
            );

    if (FAILED(hr))
    {
        TraceEvents(
            TRACE_LEVEL_ERROR, 
            TEST_TRACE_DEVICE, 
            "GetPropertyData failed: hr = %!HRESULT!",
            hr
            );
        goto exit;
    }
    
    if (type != DEVPROP_TYPE_STRING)
    {
        TraceEvents(
            TRACE_LEVEL_ERROR, 
            TEST_TRACE_DEVICE, 
            "Expected type %d, actual type: %d",
            DEVPROP_TYPE_STRING,
            type
            );
        hr = E_UNEXPECTED;
        goto exit;
    }

exit:
    delete [] friendlyNameBuffer;
    friendlyNameBuffer = NULL;

    return hr;
}

Требования

Требование	Значение
Дата окончания поддержки	Недоступно в UMDF 2.0 и более поздних версиях.
Целевая платформа	Персональный компьютер
Минимальная версия UMDF	1.11
Верхняя часть	wudfddi.h
DLL	WUDFx.dll