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 섹션을 실행하지 못합니다.

참고 클래스 설치 관리자만 SetupDiRegisterDeviceInfo 를 호출해야 하며, SetupDiRegisterDeviceInfo 가 기본 디바이스 등록 작업을 완료한 후에는 클래스 설치 관리자가 디바이스 등록 작업을 수행해야 하는 경우에만 호출해야 합니다. 이러한 상황에서 클래스 설치 관리자는 설치 관리자가 DIF_REGISTERDEVICE 요청을 처리할 때 SetupDiRegisterDeviceInfo 를 직접 호출해야 합니다. 기본 처리기를 호출하는 방법에 대한 자세한 내용은 기본 DIF 코드 처리기 호출을 참조하세요.
 
디바이스 정보 요소를 등록한 후 호출자는 이 디바이스와 연결된 DevInst 핸들의 저장된 복사본을 업데이트해야 합니다. 등록하는 동안 핸들 값이 변경되었을 수 있으므로 이 작업이 필요합니다. 구조체의 DevInst 필드가 핸들의 현재 값을 반영하도록 업데이트되므로 호출자가 SP_DEVINFO_DATA 구조를 다시 검색할 필요가 없습니다.

PnP 디바이스 인스턴스에 대해 이 함수를 직접 호출하지 마세요. PnP 디바이스 인스턴스는 운영 체제에 의해 자동으로 등록됩니다. 그러나 다음 방법 중 하나로 비 PnP 디바이스 인스턴스를 등록해야 합니다.

  1. 설치 애플리케이션이 DIF_DETECT 요청을 사용하여 디바이스를 성공적으로 검색하는 경우 DIF_REGISTERDEVICE 요청을 사용하여 디바이스 instance 등록해야 합니다. 요청은 기본 방식으로 처리되어야 합니다. (기본적으로 SetupDiCallClassInstaller는 먼저 클래스 설치 관리자 및 클래스 공동 설치 관리자를 호출하여 중복 검색을 수행하고 디바이스 instance 등록합니다. 이러한 설치 관리자가 디바이스 instance 등록하지 않으면 SetupDiCallClassInstaller는 SetupDiRegisterDeviceInfo를 호출하여 중복 검색을 수행하고 디바이스 instance 등록합니다.)
  2. 설치 애플리케이션이 디바이스 instance 만들지만(예: SetupDiCreateDeviceInfo 호출) 중복 검색을 수행하지 않는 경우 설치 애플리케이션은 DIF_REGISTERDEVICE 요청을 사용하여 디바이스 instance 등록해야 합니다. 요청은 앞에서 설명한 대로 기본 방식으로 처리되어야 합니다.
  3. 설치 애플리케이션이 새 디바이스를 만들고 중복 검색을 수행하는 경우 설치 애플리케이션은 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 않으면 설치 애플리케이션이 디바이스 설치를 종료해야 합니다.
    SetupDiRegisterDeviceInfo의 호출자는 Administrators 그룹의 구성원이어야 합니다.

요구 사항

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

추가 정보

DIF_REGISTERDEVICE

SP_DEVINFO_DATA

SP_DEVINSTALL_PARAMS