SetupDiSetClassPropertyExW 함수(setupapi.h)

아티클
03/15/2023

SetupDiSetClassPropertyEx 함수는 로컬 또는 원격 컴퓨터의 디바이스 설정 클래스 또는 디바이스 인터페이스 클래스에 대한 디바이스 속성을 설정합니다.

구문

WINSETUPAPI BOOL SetupDiSetClassPropertyExW(
  [in]           const GUID       *ClassGuid,
  [in]           const DEVPROPKEY *PropertyKey,
  [in]           DEVPROPTYPE      PropertyType,
  [in, optional] const PBYTE      PropertyBuffer,
  [in]           DWORD            PropertyBufferSize,
  [in]           DWORD            Flags,
  [in, optional] PCWSTR           MachineName,
                 PVOID            Reserved
);

매개 변수

[in] ClassGuid

디바이스 속성을 설정할 디바이스 설정 클래스 또는 디바이스 인터페이스 클래스를 식별하는 GUID에 대한 포인터입니다. 클래스 형식을 지정하는 방법에 대한 자세한 내용은 Flags 매개 변수를 참조하세요.

[in] PropertyKey

설정할 디바이스 클래스 속성의 디바이스 속성 키를 나타내는 DEVPROPKEY 구조체에 대한 포인터입니다.

[in] PropertyType

클래스 속성의 property-data-type 식별자를 나타내는 DEVPROPTYPE 형식 값입니다. 속성 데이터 형식 식별자에 대한 자세한 내용은 이 항목의 뒷부분에 있는 설명 섹션을 참조하세요.

[in, optional] PropertyBuffer

클래스 속성 값이 포함된 버퍼에 대한 포인터입니다. 속성 또는 속성 값이 삭제되는 경우 이 포인터를 NULL로 설정하고 PropertyBufferSize 를 0으로 설정해야 합니다. 속성 값 요구 사항에 대한 자세한 내용은 이 항목의 뒷부 분에 있는 설명 섹션을 참조하세요.

[in] PropertyBufferSize

PropertyBuffer 버퍼의 크기(바이트)입니다. 속성 버퍼 크기는 PropertyType에서 제공하는 속성 데이터 형식 식별자와 일치해야 합니다. PropertyBuffer 가 NULL로 설정된 경우 PropertyBufferSize를 0으로 설정해야 합니다.

[in] Flags

클래스가 디바이스 설정 클래스인지 디바이스 인터페이스 클래스인지 여부를 지정하는 다음 값 중 하나입니다.

DICLASSPROP_INSTALLER

ClassGuid 는 디바이스 설정 클래스를 지정합니다. 이 플래그는 DICLASSPROP_INTERFACE 사용할 수 없습니다.

DICLASSPROP_INTERFACE

ClassGuid 는 디바이스 인터페이스 클래스를 지정합니다. 이 플래그는 DICLASSPROP_INSTALLER 사용할 수 없습니다.

[in, optional] MachineName

컴퓨터의 "\" 접두사를 포함하여 UNC 이름을 포함하는 NULL로 끝나는 유니코드 문자열에 대한 포인터입니다. 이 포인터는 NULL로 설정할 수 있습니다. 포인터가 NULL이면 SetupDiSetClassPropertyEx 는 로컬 컴퓨터에 설치된 클래스의 클래스 속성을 설정합니다.

주의

이 기능이 제거되었으므로 이 함수를 사용하여 원격 머신에 액세스하는 것은 Windows 8 및 Windows Server 2012 시작해도 지원되지 않습니다.

Reserved

이 매개 변수는 NULL로 설정해야 합니다.

반환 값

SetupDiSetClassPropertyEx 가 성공하면 TRUE 를 반환합니다. 그렇지 않으면 FALSE를 반환하고 GetLastError를 호출하여 기록된 오류를 검색할 수 있습니다.

다음 표에는 이 함수가 기록할 수 있는 몇 가지 일반적인 오류 코드가 포함되어 있습니다.

반환 코드	설명
ERROR_INVALID_FLAGS	Flags 값이 잘못되었습니다.
ERROR_INVALID_CLASS	ClassGuid로 지정된 디바이스 설정 클래스가 잘못되었습니다. 이 오류는 DICLASSPROP_INSTALLER 플래그가 지정된 경우에만 발생할 수 있습니다.
ERROR_INVALID_REFERENCE_STRING	디바이스 인터페이스 참조 문자열이 잘못되었습니다. 이 오류는 DICLASSPROP_INTERFACE 플래그가 지정된 경우에만 발생할 수 있습니다.
ERROR_INVALID_REG_PROPERTY	PropertyKey에서 제공하는 속성 키가 잘못되었습니다.
ERROR_INVALID_DATA	지정되지 않은 내부 데이터 값이 잘못되었습니다. ClassGuid 값이 유효한 GUID가 아니거나 속성 값이 PropertyType에 지정된 속성 형식과 일치하지 않는 경우 이 오류가 기록될 수 있습니다.
ERROR_INVALID_USER_BUFFER	사용자 버퍼가 잘못되었습니다. 한 가지 가능성은 PropertyBuffer 가 NULL이고 PropertyBufferSize 가 0이 아니라는 것입니다.
ERROR_INVALID_MACHINENAME	MachineName으로 지정된 컴퓨터 이름이 잘못되었습니다.
ERROR_NO_SUCH_INTERFACE_CLASS	ClassGuid에 지정된 디바이스 인터페이스 클래스가 없습니다. 이 오류는 DICLASSPROP_INTERFACE 플래그가 지정된 경우에만 발생할 수 있습니다.
ERROR_INSUFFICIENT_BUFFER	시스템 호출에 전달된 내부 데이터 버퍼가 너무 작습니다.
ERROR_NOT_ENOUGH_MEMORY	작업을 완료하는 데 사용할 수 있는 시스템 메모리가 부족했습니다.
ERROR_NOT_FOUND	지정되지 않은 항목을 찾을 수 없습니다. 한 가지 가능성은 삭제할 속성이 존재하지 않는다는 것입니다.
ERROR_ACCESS_DENIED	호출자에게 관리자 권한이 없습니다.

설명

SetupDiSetClassPropertyEx 는 통합 디바이스 속성 모델의 일부입니다.

SetupAPI는 SetupDiSetClassPropertyEx의 유니코드 버전만 지원합니다.

SetupDiSetClassPropertyEx의 호출자는 디바이스 인터페이스 속성을 설정하려면 Administrators 그룹의 구성원이어야 합니다.

SetupDiSetClassPropertyEx 는 property-data-type 식별자 및 속성 값에 대한 요구 사항을 적용합니다.

원격 컴퓨터에서 디바이스 클래스에 대해 설정된 디바이스 속성을 나타내는 디바이스 속성 키를 가져오려면 SetupDiGetClassPropertyKeysEx를 호출합니다.

로컬 컴퓨터에서 디바이스 클래스 속성을 검색하려면 SetupDiGetClassProperty를 호출하고 원격 컴퓨터에서 디바이스 클래스 속성을 검색하려면 SetupDiGetClassPropertyEx를 호출합니다.

로컬 컴퓨터에서 디바이스 클래스 속성을 설정하려면 SetupDiSetClassProperty를 호출합니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows Vista 및 이후 버전의 Windows에서 사용할 수 있습니다.
대상 플랫폼	데스크톱
머리글	setupapi.h(Setupapi.h 포함)
라이브러리	Setupapi.lib