CM_Query_And_Remove_SubTree_ExW 함수(cfgmgr32.h)

아티클
08/22/2023

[Windows 8 및 Windows Server 2012 이 함수는 더 이상 사용되지 않습니다. 대신 CM_Query_And_Remove_SubTree 사용하세요.]

CM_Query_And_Remove_SubTree_Ex 함수는 디바이스 instance 및 해당 자식을 제거할 수 있는지 여부를 확인하고 제거합니다.

구문

CMAPI CONFIGRET CM_Query_And_Remove_SubTree_ExW(
  [in]            DEVINST        dnAncestor,
  [out, optional] PPNP_VETO_TYPE pVetoType,
  [out, optional] LPWSTR         pszVetoName,
  [in]            ULONG          ulNameLength,
  [in]            ULONG          ulFlags,
  [in, optional]  HMACHINE       hMachine
);

매개 변수

[in] dnAncestor

호출자가 제공한 디바이스는 제거할 하위 트리의 루트에 있는 디바이스에 대한 핸들을 instance. 이 디바이스 instance 핸들은 hMachine에서 제공하는 컴퓨터 핸들에 바인딩됩니다.

[out, optional] pVetoType

(선택 사항) 호출자가 NULL 을 통과하지 못하고 제거 요청이 거부되면(즉, 함수가 CR_REMOVE_VETOED 반환) 이 값을 반환하면 이 값은 거부권의 이유를 나타내는 PNP_VETO_TYPE 형식의 값을 가리킵니다.

[out, optional] pszVetoName

(선택 사항) 호출자가 NULL 을 전달하지 않고 제거 요청이 거부되면(즉, 함수가 CR_REMOVE_VETOED 반환함) 이 반환은 거부 유형과 연결된 텍스트 문자열을 가리킵니다. 이 문자열에서 제공하는 정보의 형식은 pVetoType에서 받은 값에 따라 달라집니다. 이러한 문자열에 대한 자세한 내용은 PNP_VETO_TYPE.

[in] ulNameLength

(선택 사항) pszVetoName에서 제공하는 문자열 버퍼의 길이(문자 수)를 나타내는 호출자 제공 값입니다. MAX_PATH 설정해야 합니다.

[in] ulFlags

설명 섹션에 설명된 호출자 제공 플래그 상수의 비트 OR 입니다 .

[in, optional] hMachine

호출자가 제공한 디바이스 instance 핸들이 바인딩된 호출자 제공 컴퓨터 핸들입니다.

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

반환 값

작업이 성공하면 함수는 CR_SUCCESS 반환합니다. 그렇지 않으면 Cfgmgr32.h에 정의된 CR_ 접두사 오류 코드 중 하나를 반환합니다.

설명

CM_Query_And_Remove_SubTree_Ex 함수의 목적은 애플리케이션이 원격 컴퓨터에서 안전하게 제거할 수 있도록 디바이스를 준비할 수 있도록 하는 것입니다. 드라이버가 DEVICE_CAPABILITIESSurpriseRemovalOK 멤버를 설정하지 않은 경우에만 이 함수를 사용하여 디바이스를 제거합니다. 드라이버가 SurpriseRemovalOK를 설정한 경우 애플리케이션은 CM_Query_And_Remove_SubTree_Ex 대신 CM_Request_Device_Eject_Ex 호출해야 합니다.

CM_Query_And_Remove_SubTree_Ex 다음 두 플래그 중 하나를 사용하여 flags 매개 변수 ulFlags 설정을 지원합니다. 이러한 플래그는 Windows 또는 설치 관리자가 디바이스 제거를 거부하는 경우에만 적용됩니다.

Windows XP부터 CM_Query_And_Remove_SubTree_Ex 다음과 같은 추가 플래그 설정도 지원합니다. 이 플래그는 함수가 디바이스 instance 성공적으로 제거한 경우에만 적용됩니다.

CM_Query_And_Remove_SubTree_Ex 하위 수준 작업이 필요하지 않은 디바이스 설치 애플리케이션은 CM_Query_And_Remove_SubTree_Ex사용하여 디바이스를 제거하는 대신 DIF_PROPERTYCHANGE 요청을 사용하여 디바이스를 사용하지 않도록 설정해야 합니다. DIF_PROPERTYCHANGE 요청을 사용하여 디바이스의 속성을 활성화, 비활성화, 다시 시작, 중지 또는 변경할 수 있습니다.

이 함수의 호출자에게 는 SeLoadDriverPrivilege가 있어야 합니다. 권한은 Microsoft Windows SDK 설명서에 설명되어 있습니다.

로컬 또는 원격 머신에 바인딩된 디바이스 instance 핸들을 사용하는 방법에 대한 자세한 내용은 CM_Get_Child_Ex 참조하세요.

원격 머신에 액세스하는 기능은 Windows 8 및 Windows Server 2012 이상 운영 체제에서 제거되었으므로 이러한 버전의 Windows에서 실행할 때 원격 컴퓨터에 액세스할 수 없습니다.

요구 사항

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