DiUninstallDevice 함수(newdev.h)

아티클
03/08/2023

DiUninstallDevice 함수는 디바이스를 제거하고 시스템에서 디바이스 노드(devnode)를 제거합니다. 이는 호출 시 존재하는 자식 devnode 외에 디바이스 노드를 제거하려고 하기 때문에 DIF_REMOVE 코드와 함께 SetupDiCallClassInstaller를 사용하는 것과 다릅니다.

Windows 8 전에 호출 시 존재하지 않는 자식 디바이스는 제거되지 않습니다. 그러나 Windows 8 호출 시 존재하지 않는 모든 자식 디바이스는 제거됩니다.

구문

BOOL DiUninstallDevice(
  [in]            HWND             hwndParent,
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA DeviceInfoData,
  [in]            DWORD            Flags,
  [out, optional] PBOOL            NeedReboot
);

매개 변수

[in] hwndParent

디바이스에 대한 제거 요청과 연결된 사용자 인터페이스 구성 요소를 표시하는 데 사용되는 최상위 창에 대한 핸들입니다. 이 매개 변수는 선택 사항이며 NULL로 설정할 수 있습니다.

[in] DeviceInfoSet

디바이스 정보 요소가 포함된 디바이스 정보 집합 에 대한 핸들입니다. 이 요소는 이 호출을 통해 제거할 디바이스를 나타냅니다.

[in] DeviceInfoData

제거 요청이 수행되는 지정된 디바이스 정보 집합에서 지정된 디바이스를 나타내는 SP_DEVINFO_DATA 구조체에 대한 포인터입니다.

[in] Flags

디바이스 제거 플래그를 지정하는 DWORD 형식의 값입니다. Windows 7부터 이 매개 변수는 0으로 설정해야 합니다.

[out, optional] NeedReboot

디바이스 제거 요청을 완료하기 위해 시스템 다시 시작이 필요한지 여부를 나타내기 위해 DiUninstallDevice 가 설정하는 BOOL 형식의 값에 대한 포인터입니다. 이 매개 변수는 선택 사항이며 NULL로 설정할 수 있습니다.

매개 변수가 지정되고 시스템 다시 시작이 필요한 경우 DiUninstallDevice 는 값을 TRUE로 설정합니다. 이 경우 애플리케이션은 사용자에게 시스템을 다시 시작하라는 메시지를 표시해야 합니다. 이 매개 변수가 제공되고 시스템 다시 시작이 필요하지 않은 경우 DiUninstallDevice 는 값을 FALSE로 설정합니다.

이 매개 변수가 NULL 이고 디바이스 제거를 완료하기 위해 시스템 다시 시작이 필요한 경우 DiUninstallDevice 는 시스템 다시 시작 대화 상자를 표시합니다.

이 매개 변수에 대한 자세한 내용은 설명 섹션 을 참조하세요 .

반환 값

DiUninstallDevice는 함수가 디바이스를 나타내는 최상위 디바이스 노드를 성공적으로 제거한 경우 TRUE 를 반환합니다. 그렇지 않으면 DiUninstallDevice 가 FALSE를 반환하고 GetLastError를 호출하여 기록된 오류를 검색할 수 있습니다. 다음 목록에서는 GetLastError 가 이 API에 대해 반환할 수 있는 몇 가지 일반적인 오류 값을 보여 드립니다.

반환 코드	설명
ERROR_ACCESS_DENIED	호출자에게 관리자 권한이 없습니다. 기본적으로 Windows에서는 호출자에게 디바이스를 제거하는 관리자 권한이 있어야 합니다.
ERROR_INVALID_FLAGS	Flags 매개 변수에 대해 지정된 값이 0과 같지 않습니다.

참고 반환 값은 모든 자식 devnode의 제거가 성공했거나 실패했음을 나타내지 않습니다. Windows Vista부터 자식 devnodes 제거의 상태 대한 정보는 Setupapi.dev.log 파일에서 확인할 수 있습니다. 이 파일에 대한 자세한 내용은 SetupAPI 텍스트 로그를 참조하세요.

설명

DiUninstallDevice는DIF_REMOVE 코드와 함께 사용할 때 SetupDiCallClassInstaller와 동일한 함수를 수행합니다. 주요 차이점은 최상위 디바이스에 대한 자식 devnode도 삭제된다는 것입니다. DiUninstallDevice는 최상위 디바이스 노드를 제거하지 못한 경우에만 실패를 반환하며, 이는 DIF_REMOVE 코드와 함께 사용할 때 SetupDiCallClassInstaller의 동작과 일치합니다. 자식 devnode 제거가 성공했는지 여부에 대한 자세한 내용은 Setupapi.dev.log 파일에서 확인할 수 있습니다.

제거할 디바이스는 참조된 디바이스를 포함하는 디바이스 정보 집합 과 특정 디바이스에 대한 SP_DEVINFO_DATA 구조를 제공하여 지정됩니다. 이러한 매개 변수는 DeviceInfoSet 및 DeviceInfoData 매개 변수에 제공됩니다.

지정된 디바이스를 포함하는 디바이스 정보 집합을 만들고 디바이스에 대한 SP_DEVINFO_DATA 구조를 가져오려면 다음 작업 중 하나를 완료합니다.

SetupDiGetClassDevs를 호출하여 디바이스가 포함된 디바이스 정보 집합을 검색한 다음 SetupDiEnumDeviceInfo를 호출하여 디바이스 정보 집합의 디바이스를 열거합니다. 각 호출에서 SetupDiEnumDeviceInfo 는 디바이스 정보 집합의 열거형 디바이스를 나타내는 SP_DEVINFO_DATA 구조를 반환합니다.
열거된 디바이스에 대한 특정 정보를 가져오려면 SetupDiGetDeviceProperty를 호출하고 SetupDiEnumDeviceInfo에서 반환되는 SP_DEVINFO_DATA 구조를 제공하세요.
SetupDiEnumDeviceInfo를 호출하여 알려진 디바이스 instance ID가 있는 디바이스를 디바이스 정보 집합에 추가합니다. SetupDiOpenDeviceInfo 는 디바이스 정보 집합의 디바이스를 나타내는 SP_DEVINFO_DATA 구조를 반환합니다.

디바이스 제거 요청에 컴퓨터를 다시 시작해야 하는 경우, NeedReboot 매개 변수가 NULL로 설정된 경우 DiUninstallDevice는 사용자에게 시스템을 다시 시작하라는 메시지를 표시합니다. 애플리케이션에서 사용하는 사용자 인터페이스 창이 있는 경우 hwndParent 매개 변수를 해당 창 핸들의 값으로 설정해야 합니다.

그러나 애플리케이션이 필요한 시스템 다시 시작 알림을 관리하는 경우 NeedReboot 매개 변수를 NULL 이 아닌 값으로 설정해야 합니다. DiUninstallDevice는 시스템 다시 시작이 필요한지에 따라 NeedReboot 매개 변수를 TRUE 또는 FALSE로 설정합니다.

다음 목록에서는 애플리케이션이 시스템 다시 시작을 관리할 수 있는 이유의 예를 보여 줍니다.

애플리케이션은 여러 디바이스를 제거해야 합니다. 모든 디바이스를 제거한 후에는 DiUninstallDevice에 대한 호출이 NeedReboot 매개 변수에서 TRUE를 반환한 경우 애플리케이션에서 사용자에게 시스템을 다시 시작하라는 메시지를 표시해야 합니다.
애플리케이션은 시스템을 다시 시작하기 전에 몇 가지 다른 작업이 발생해야 합니다. 시스템 다시 시작이 필요한 경우 애플리케이션은 필요한 작업을 완료한 다음 사용자에게 시스템을 다시 시작하라는 메시지를 표시해야 합니다.
애플리케이션은 클래스 설치 관리자입니다. 이 경우 클래스 설치 관리자는 디바이스에 대한 SP_DEVINSTALL_PARAMS 구조의 Flags 멤버에서 DI_NEEDREBOOT 플래그를 설정해야 합니다.

요구 사항

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