IWDFUnifiedPropertyStore::GetPropertyData 메서드(wudfddi.h)

아티클
08/08/2023

[경고: UMDF 2는 UMDF의 최신 버전이며 UMDF 1을 대체합니다. 모든 새 UMDF 드라이버는 UMDF 2를 사용하여 작성해야 합니다. UMDF 1에 새 기능이 추가되지 않으며 최신 버전의 Windows 10 UMDF 1에 대한 지원이 제한되어 있습니다. 유니버설 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 LCID는 속성이 언어 중립적임을 지정합니다(즉, 언어와 관련이 없음). 이 매개 변수를 LOCALE_SYSTEM_DEFAULT 또는 LOCALE_USER_DEFAULT 설정하지 마세요. 언어별 LCID 값에 대한 자세한 내용은 LCID 구조를 참조하세요.

[in] Flags

시스템에서 사용하도록 예약되었습니다. 드라이버는 이 값을 0으로 설정해야 합니다.

[in] PropertyDataSize

PropertyData가 가리키는 버퍼의 크기(바이트)입니다.

[out, optional] PropertyData

디바이스 속성 데이터에 대한 포인터입니다.

[out] PropertyDataRequiredSize

PropertyData에서 반환되는 속성 정보의 크기를 수신하는 ULONG에 대한 포인터입니다.

[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 에 포함된 다른 값 중 하나를 반환할 수 있습니다.

설명

프레임워크 기반 드라이버는 GetPropertyData 메서드를 사용하여 통합 디바이스 속성 모델의 일부로 정의된 디바이스 속성을 검색합니다.

특히 이 메서드를 사용하여 디바이스의 하드웨어 키 또는 디바이스 인터페이스 클래스의 instance 검색할 수 있습니다. IWDFUnifiedPropertyStoreFactory::RetrieveUnifiedDevicePropertyStore를 호출할 때 RootSpecifier 매개 변수의 RootClass 멤버를 WdfPropertyStoreRootClassHardwareKey 또는 WdfPropertyStoreRootClassDeviceInterfaceKey로 설정합니다.

WdfPropertyStoreRootClassHardwareKey를 지정하는 경우 GetPropertyData를 호출할 때 PnP 정의 키가 아닌 PropertyKey 매개 변수에 사용자 지정 DEVPROPKEY 값을 제공해야 합니다. 값은 이전에 SetupDI 디바이스 속성 함수인 SetPropertyData를 호출하거나 INF AddProperty 지시문을 사용하여 설정되었어야 합니다.

디바이스 속성에 대한 자세한 내용은 디바이스 속성을 참조하세요.

레지스트리에 액세스하는 방법에 대한 자세한 내용은 UMDF 기반 드라이버에서 레지스트리 사용을 참조하세요.

예제

변수 크기 속성의 경우 드라이버는 속성 데이터를 검색하기 위해 두 번의 패스를 수행해야 합니다. 먼저 드라이버는 PropertyData 매개 변수에서 NULL 버퍼를 전달하고 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