SetupDiGetCustomDevicePropertyA 함수(setupapi.h)

아티클
03/05/2024

SetupDiGetCustomDeviceProperty 함수는 레지스트리에서 지정된 사용자 지정 디바이스 속성을 검색합니다.

구문

WINSETUPAPI BOOL SetupDiGetCustomDevicePropertyA(
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA DeviceInfoData,
  [in]            PCSTR            CustomPropertyName,
  [in]            DWORD            Flags,
  [out, optional] PDWORD           PropertyRegDataType,
  [out]           PBYTE            PropertyBuffer,
  [in]            DWORD            PropertyBufferSize,
  [out, optional] PDWORD           RequiredSize
);

매개 변수

[in] DeviceInfoSet

사용자 지정 디바이스 속성을 검색할 디바이스를 나타내는 디바이스 정보 요소가 포함된 디바이스 정보 집합 에 대한 핸들입니다.

[in] DeviceInfoData

DeviceInfoSet에서 디바이스 정보 요소를 지정하는 SP_DEVINFO_DATA 구조체에 대한 포인터입니다.

[in] CustomPropertyName

사용자 지정 속성을 나타내는 레지스트리 값 이름입니다.

[in] Flags

요청된 정보를 반환하는 방법을 나타내는 플래그 값입니다. 플래그는 0이거나 다음 중 하나일 수 있습니다.

DICUSTOMDEVPROP_MERGE_MULTISZ

설정되면 함수는 REG_MULTI_SZ 형식의 문자열로 연결된 디바이스 instance 특정 속성 값과 하드웨어 ID별 속성 값을 모두 검색합니다. (자세한 내용은 이 참조 페이지의 설명 섹션을 참조하세요.)

[out, optional] PropertyRegDataType

검색된 속성의 데이터 형식을 수신하는 DWORD 형식의 변수에 대한 포인터입니다. 데이터 형식은 레지스트리 데이터 형식을 나타내는 REG_ 접두사 상수 중 하나로 지정됩니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다.

[out] PropertyBuffer

요청된 속성 정보를 수신하는 버퍼에 대한 포인터입니다.

[in] PropertyBufferSize

PropertyBuffer 버퍼의 크기(바이트)입니다.

[out, optional] RequiredSize

요청된 정보를 받는 데 필요한 버퍼 크기(바이트)를 수신하는 DWORD 형식의 변수에 대한 포인터입니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다. 이 매개 변수를 지정하면 PropertyBuffer 버퍼가 요청된 정보를 받을 수 있을 만큼 큰지 여부에 관계없이 SetupDiGetCustomDeviceProperty는 필요한 크기를 반환합니다.

반환 값

작업이 성공하면 SetupDiGetCustomDeviceProperty 는 TRUE를 반환합니다. 그렇지 않으면 함수는 FALSE 를 반환하고 GetLastError를 호출하여 기록된 오류를 검색할 수 있습니다. PropertyBuffer 버퍼가 요청된 정보를 받을 만큼 크지 않으면 SetupDiGetCustomDeviceProperty는 FALSE를 반환하고 GetLastError에 대한 후속 호출은 ERROR_INSUFFICIENT_BUFFER 반환합니다.

설명

SetupDiGetCustomDeviceProperty는 단일 디바이스 instance 또는 특정 하드웨어 ID와 일치하는 모든 디바이스와 연결된 디바이스 속성을 검색합니다. (하드웨어 ID에 대한 자세한 내용은 디바이스 식별 문자열을 참조하세요.)

공급업체는 INF DDInstall.HW 섹션에서 INF AddReg 지시문을 사용하고 HKR 레지스트리 루트를 지정하여 디바이스 instance 속성을 설정할 수 있습니다.

시스템에서만 하드웨어 ID에 대한 속성을 설정할 수 있습니다. 시스템은 일부 하드웨어 ID에 대해 "아이콘" 속성을 제공합니다.

함수는 먼저 지정된 디바이스 instance 대해 지정된 속성이 있는지 확인합니다. 이 경우 속성의 값이 반환됩니다. 그렇지 않은 경우 함수는 지정된 디바이스 instance 하드웨어 ID와 일치하는 모든 디바이스에 대한 속성이 있는지 확인합니다. 이 경우 속성의 값이 반환됩니다. DICUSTOMDEVPROP_MERGE_MULTISZ Flags에 설정된 경우 함수는 디바이스 instance 및 하드웨어 ID와 연결된 속성 값(둘 다 있는 경우)을 반환합니다.

참고

setupapi.h 헤더는 SETUPDiGetCustomDeviceProperty를 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.

요구 사항

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