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

아티클
08/08/2023

[경고: UMDF 2는 UMDF의 최신 버전이며 UMDF 1을 대체합니다. 모든 새 UMDF 드라이버는 UMDF 2를 사용하여 작성해야 합니다. UMDF 1에 새 기능이 추가되지 않으며 최신 버전의 Windows 10 UMDF 1에 대한 지원이 제한되어 있습니다. 유니버설 Windows 드라이버는 UMDF 2를 사용해야 합니다. 자세한 내용은 UMDF를 사용하여 시작 참조하세요.]

SetPropertyData 메서드는 디바이스 속성의 현재 설정을 수정합니다.

구문

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

매개 변수

[in] PropertyKey

디바이스 속성 키를 지정하는 DEVPROPKEY 구조체에 대한 포인터입니다.

[in] Lcid

로캘 식별자를 지정합니다. 이 매개 변수를 언어별 LCID 값으로 설정하거나 LOCALE_NEUTRAL. LOCALE_NEUTRAL LCID는 속성이 언어 중립적임을 지정합니다(즉, 언어와 관련이 없음). 이 매개 변수를 LOCALE_SYSTEM_DEFAULT 또는 LOCALE_USER_DEFAULT 설정하지 마세요. 언어별 LCID 값에 대한 자세한 내용은 LCID 구조를 참조하세요.

[in] Flags

예약되어 있습니다. 드라이버는 이 값을 0으로 설정해야 합니다.

[in] PropertyType

PropertyData 버퍼에 제공되는 데이터의 형식을 지정하는 DEVPROPTYPE 값에 대한 포인터입니다.

[in] PropertyDataSize

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

[in, optional] PropertyData

디바이스 속성 데이터에 대한 포인터입니다. 지정된 속성을 삭제하려면 이 매개 변수를 NULL 로 설정합니다.

반환 값

SetPropertyData 는 작업이 성공하면 S_OK 반환합니다. 그렇지 않으면 메서드가 다음 값을 반환할 수 있습니다.

반환 코드	설명
E_OUTOFMEMORY	프레임워크의 메모리 할당 시도가 실패했습니다.
HRESULT_FROM_WIN32(ERROR_INVALID_PARAMETER)	드라이버가 WdfPropertyStoreRootClassDeviceInterfaceKey를 지정하는 경우 요청된 인터페이스는 UMDF 드라이버가 이전에 등록한 인터페이스여야 합니다.
HRESULT_FROM_WIN32(STATUS_NOT_SUPPORTED)	드라이버는 Windows 8 시작하는 디바이스 인터페이스 속성 데이터를 수정할 수 있습니다.

이 메서드는 Winerror.h 에 포함된 다른 값 중 하나에 해당하는 HRESULT 형식 값을 반환할 수 있습니다.

설명

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

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

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

드라이버가 WdfPropertyStoreRootClassDeviceInterfaceKey를 지정하는 경우 요청된 인터페이스는 런타임에 UMDF 드라이버가 이전에 등록한 인터페이스여야 합니다.

드라이버가 INF 파일에 인터페이스를 등록하는 경우 INF에서도 연결된 속성을 설정해야 합니다.

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

예제

HRESULT
SetFriendlyName(
    _In_ IWDFUnifiedPropertyStore * pUnifiedPropertyStore
    )
{
    HRESULT hr = S_OK;
    WCHAR friendlyName[] = L"UMDF OSR USB Fx2 Test Device";

    hr = pUnifiedPropertyStore->SetPropertyData(
            &DEVPKEY_Device_FriendlyName,
            0, //Lcid
            0, //Flags
            DEVPROP_TYPE_STRING, //Type
            sizeof(friendlyName),
            friendlyName
            );

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

exit:
    return hr;
}

요구 사항

요구 사항	값
지원 종료	UMDF 2.0 이상에서는 사용할 수 없습니다.
대상 플랫폼	데스크톱
최소 UMDF 버전	1.11
머리글	wudfddi.h
DLL	WUDFx.dll