функция CM_Query_And_Remove_SubTree_ExW (cfgmgr32.h)

Статья
02/23/2024

[Начиная с Windows 8 и Windows Server 2012 эта функция устарела. Вместо этого используйте CM_Query_And_Remove_SubTree .]

Функция CM_Query_And_Remove_SubTree_Ex проверяет, можно ли удалить экземпляр устройства и его дочерние элементы, и, если да, она удаляет их.

Синтаксис

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

Дескриптор экземпляра устройства, предоставленный вызывающим абонентом, для устройства в корне удаляемого поддеревого. Этот дескриптор экземпляра устройства привязан к дескрипторе компьютера, предоставленному hMachine.

[out, optional] pVetoType

[out, optional] pszVetoName

(Необязательно) Если вызывающий объект не передает значение NULL и запрос на удаление наложен вето (то есть функция возвращает CR_REMOVE_VETOED), то при возврате это указывает на текстовую строку, связанную с типом вето. Тип сведений, предоставляемых этой строкой, зависит от значения, полученного pVetoType. Сведения об этих строках см. в разделе PNP_VETO_TYPE.

[in] ulNameLength

(Необязательно.) Предоставленное вызывающим объектом значение, представляющее длину (количество символов) строкового буфера, предоставленного pszVetoName. Для этого параметра должно быть задано значение MAX_PATH.

[in] ulFlags

Побитовое ИЛИ констант флага, предоставленных вызывающим абонентом, которые описаны в разделе Примечания .

[in, optional] hMachine

Дескриптор компьютера, предоставленный вызывающим абонентом, к которому привязан дескриптор экземпляра устройства, предоставленный вызывающим абонентом.

Примечание Использование этой функции для доступа к удаленным компьютерам не поддерживается, начиная с Windows 8 и Windows Server 2012, так как эта функция была удалена.

Возвращаемое значение

Если операция выполнена успешно, функция возвращает CR_SUCCESS. В противном случае возвращается один из кодов ошибок с префиксом CR_, определенных в Cfgmgr32.h.

Функция CM_Query_And_Remove_SubTree_Ex позволяет приложению подготовить устройство к безопасному удалению с удаленного компьютера. Используйте эту функцию для удаления устройств только в том случае, если драйвер не настроил элемент SurpriseRemovalOKDEVICE_CAPABILITIES. Если драйвер задал SurpriseRemovalOK, приложение должно вызывать CM_Request_Device_Eject_Ex , а не CM_Query_And_Remove_SubTree_Ex.

CM_Query_And_Remove_SubTree_Ex поддерживает установку параметра flags ulFlags с одним из следующих двух флагов; Эти флаги применяются только в том случае, если Windows или установщик накладывает вето на удаление устройства:

Начиная с Windows XP , CM_Query_And_Remove_SubTree_Ex также поддерживает установку следующего дополнительного флага: Этот флаг применяется только в том случае, если функция успешно удаляет экземпляр устройства:

Приложения установки устройств , которые не требуют низкоуровневой работы CM_Query_And_Remove_SubTree_Ex , должны использовать запрос DIF_PROPERTYCHANGE для отключения устройства, а не использовать CM_Query_And_Remove_SubTree_Ex для удаления устройства. Запрос DIF_PROPERTYCHANGE можно использовать для включения, отключения, перезапуска, остановки или изменения свойств устройства.

У вызывающих объектов этой функции должен быть SeLoadDriverPrivilege. (Привилегии описаны в документации по Microsoft Windows SDK.)

Сведения об использовании дескрипторов экземпляров устройства, привязанных к локальному или удаленному компьютеру, см. в разделе CM_Get_Child_Ex.

Функциональные возможности доступа к удаленным компьютерам были удалены в Windows 8 и Windows Server 2012 и более поздних версиях операционных систем, поэтому вы не сможете получить доступ к удаленным компьютерам при работе в этих версиях Windows.

Требования

Требование	Значение
Минимальная версия клиента	Доступно в Microsoft Windows 2000 и более поздних версиях Windows.
Целевая платформа	Персональный компьютер
Верхняя часть	cfgmgr32.h (включая Cfgmgr32.h)
Библиотека	Cfgmgr32.lib