SetupDiRegisterDeviceInfo 함수(setupapi.h)
SetupDiRegisterDeviceInfo 함수는 DIF_REGISTERDEVICE 요청에 대한 기본 처리기입니다.
구문
WINSETUPAPI BOOL SetupDiRegisterDeviceInfo(
[in] HDEVINFO DeviceInfoSet,
[in, out] PSP_DEVINFO_DATA DeviceInfoData,
[in] DWORD Flags,
[in, optional] PSP_DETSIG_CMPPROC CompareProc,
[in, optional] PVOID CompareContext,
[out, optional] PSP_DEVINFO_DATA DupDeviceInfoData
);
매개 변수
[in] DeviceInfoSet
등록할 디바이스를 나타내는 디바이스 정보 요소가 포함된 디바이스 정보 집합에 대한 핸들입니다. 디바이스 정보 집합에는 원격 요소가 포함되어서는 안됩니다.
[in, out] DeviceInfoData
DeviceInfoSet에서 디바이스 정보 요소를 지정하는 SP_DEVINFO_DATA 구조체에 대한 포인터입니다. DeviceInfoData이기 때문에 IN-OUT 매개 변수입니다.DevInst는 반환 시 새 핸들 값으로 업데이트될 수 있습니다.
[in] Flags
디바이스가 등록되는 방식을 제어하는 플래그 값으로, 0 또는 다음 값일 수 있습니다.
SPRDI_FIND_DUPS
DeviceInfoData로 표시되는 디바이스에 해당하는 기존 디바이스 instance 검색합니다. 이 플래그를 지정하지 않으면 디바이스 instance 이미 있는지 여부에 관계없이 디바이스 instance 등록됩니다.
호출자가 CompareProc을 제공하는 경우 호출자도 이 플래그를 설정해야 합니다.
[in, optional] CompareProc
중복 검색에 사용할 비교 콜백 함수에 대한 포인터입니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다. 이 매개 변수를 지정하면 등록 중인 디바이스 instance 동일한 클래스인 각 디바이스 instance 대해 콜백 함수가 호출됩니다. 콜백 함수의 프로토타입은 다음과 같습니다.
typedef DWORD (CALLBACK* PSP_DETSIG_CMPPROC) (
IN HDEVINFO DeviceInfoSet,
IN PSP_DEVINFO_DATA NewDeviceData,
IN PSP_DEVINFO_DATA ExistingDeviceData,
IN PVOID CompareContextOPTIONAL
);
compare 함수는 두 디바이스가 중복되는 경우 ERROR_DUPLICATE_FOUND 반환해야 합니다. 그렇지 않으면 NO_ERROR 반환해야 합니다. 다른 오류가 발생하는 경우 콜백 함수는 오류를 나타내는 적절한 ERROR_* 코드를 반환해야 합니다.
CompareProc을 지정하지 않고 중복 검색을 요청하는 경우 기본 비교 동작이 사용됩니다. 기본값은 새 디바이스의 검색 서명을 클래스의 다른 모든 디바이스의 검색 서명과 비교하는 것입니다. 검색 서명은 디바이스 부팅 로그 구성의 클래스별 리소스 설명자에 포함되어 있습니다.
[in, optional] CompareContext
콜백 함수에 전달되는 호출자 제공 컨텍스트 버퍼에 대한 포인터입니다. CompareProc을 지정하지 않으면 이 매개 변수는 무시됩니다.
[out, optional] DupDeviceInfoData
이 디바이스를 등록하려고 시도한 결과로 검색된 중복된 디바이스 instance 대한 정보를 수신하는 SP_DEVINFO_DATA 구조체에 대한 포인터입니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다. 이 매개 변수를 지정하면 호출자는 DupDeviceInfoData를 설정해야 합니다.cbSize to sizeof(SP_DEVINFO_DATA). 함수가 FALSE를 반환하고 GetLastError 가 ERROR_DUPLICATE_FOUND 반환하는 경우 이 값이 채워집니다. 이 디바이스 정보 요소는 지정된 DeviceInfoSet의 멤버로 추가됩니다(아직 멤버가 아닌 경우). DupDeviceInfoData를 지정하지 않으면 중복 항목이 디바이스 정보 집합에 추가되지 않습니다.
DIF_REGISTERDEVICE 요청을 처리할 때 이 함수를 호출하는 경우 DupDeviceInfoData 매개 변수는 NULL이어야 합니다.
반환 값
함수가 성공하면 TRUE 를 반환합니다. 그렇지 않으면 FALSE 를 반환하고 GetLastError를 호출하여 기록된 오류를 검색할 수 있습니다.
설명
SetupDiRegisterDeviceInfo는 주로 PnP가 아닌 디바이스를 로컬 컴퓨터의 플러그 앤 플레이(PnP) 관리자에 등록하도록 설계되었습니다. 디바이스 정보 집합이 원격 컴퓨터에 대해 설정된 경우 SetupDiRegisterDeviceInfo 가 실패하지 않지만, 이후 디바이스 정보 집합을 원격 컴퓨터에서 작업을 지원하지 않는 DIF_Xxx 설치 요청 또는 SetupDiXxx 함수와 함께 사용할 수 없으므로 그 결과는 제한적입니다. 예를 들어 SetupDiCreateDevRegKey 를 호출하여 원격 컴퓨터에서 새로 등록된 디바이스에 대한 INF 섹션을 실행하지 못합니다.
PnP 디바이스 인스턴스에 대해 이 함수를 직접 호출하지 마세요. PnP 디바이스 인스턴스는 운영 체제에 의해 자동으로 등록됩니다. 그러나 다음 방법 중 하나로 비 PnP 디바이스 인스턴스를 등록해야 합니다.
- 설치 애플리케이션이 DIF_DETECT 요청을 사용하여 디바이스를 성공적으로 검색하는 경우 DIF_REGISTERDEVICE 요청을 사용하여 디바이스 instance 등록해야 합니다. 요청은 기본 방식으로 처리되어야 합니다. (기본적으로 SetupDiCallClassInstaller는 먼저 클래스 설치 관리자 및 클래스 공동 설치 관리자를 호출하여 중복 검색을 수행하고 디바이스 instance 등록합니다. 이러한 설치 관리자가 디바이스 instance 등록하지 않으면 SetupDiCallClassInstaller는 SetupDiRegisterDeviceInfo를 호출하여 중복 검색을 수행하고 디바이스 instance 등록합니다.)
- 설치 애플리케이션이 디바이스 instance 만들지만(예: SetupDiCreateDeviceInfo 호출) 중복 검색을 수행하지 않는 경우 설치 애플리케이션은 DIF_REGISTERDEVICE 요청을 사용하여 디바이스 instance 등록해야 합니다. 요청은 앞에서 설명한 대로 기본 방식으로 처리되어야 합니다.
-
설치 애플리케이션이 새 디바이스를 만들고 중복 검색을 수행하는 경우 설치 애플리케이션은 DIF_REGISTERDEVICE 요청을 사용해야 하지만 SetupDiCallClassInstaller 가 SetupDiRegisterDeviceInfo를 호출하지 못하도록 해야 합니다. SetupDiCallClassInstaller가 SetupDiRegisterDeviceInfo를 호출하지 않도록 하려면 디바이스 instance 대한 SP_DEVINSTALL_PARAMS 구조의 Flags 멤버에 DI_NODI_DEFAULTACTION 플래그를 설정합니다.
SetupDiCallClassInstaller가 DIF_REGISTERDEVICE 요청에 대해 TRUE를 반환하는 경우 클래스 설치 관리자 또는 클래스 공동 설치 관리자가 디바이스 instance 등록했습니다. 이 경우 설치 애플리케이션은 디바이스를 계속 설치할 수 있습니다.
SetupDiCallClassInstaller가 DIF_REGISTERDEVICE 요청에 대해 FALSE를 반환하는 경우 클래스 설치 관리자 또는 클래스 공동 설치 관리자가 디바이스 instance 등록하지 않았습니다. 이 경우 설치 애플리케이션은 GetLastError 가 요청에 대해 반환하는 마지막 오류에 따라 다음 중 하나를 수행해야 합니다.
- 마지막 오류가 ERROR_DI_DO_DEFAULT 설치 애플리케이션은 SetupDiRegisterDeviceInfo 를 직접 호출하고 CompareProc 을 제공하여 중복 검색을 수행할 수 있습니다. 이 호출이 성공하고 중복을 찾을 수 없는 경우 디바이스 설치를 계속할 수 있습니다. 중복된 항목이 발견되면 SetupDiRegisterDeviceInfo 는 FALSE를 반환하고 설치 애플리케이션은 디바이스 설치를 종료해야 합니다.
- 마지막 오류가 ERROR_DI_DO_DEFAULT 않으면 설치 애플리케이션이 디바이스 설치를 종료해야 합니다.
요구 사항
요구 사항 | 값 |
---|---|
지원되는 최소 클라이언트 | Microsoft Windows 2000 이상 버전의 Windows에서 사용할 수 있습니다. |
대상 플랫폼 | 데스크톱 |
머리글 | setupapi.h(Setupapi.h 포함) |
라이브러리 | Setupapi.lib |
DLL | Setupapi.dll |