Поделиться через

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

  • Статья

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

Синтаксис

CMAPI CONFIGRET CM_Query_And_Remove_SubTreeA(
  [in]            DEVINST        dnAncestor,
  [out, optional] PPNP_VETO_TYPE pVetoType,
  [out, optional] LPSTR          pszVetoName,
  [in]            ULONG          ulNameLength,
  [in]            ULONG          ulFlags
);

Параметры

[in] dnAncestor

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

[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

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

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

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

Комментарии

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

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

Flag Описание
CM_REMOVE_UI_OK Функция позволяет отобразить диалоговое окно пользователя, указывающее причину вето. Это параметр флага по умолчанию.
CM_REMOVE_UI_NOT_OK Функция подавляет отображение диалогового окна пользователя, указывающего причину вето.

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

Flag Описание
CM_REMOVE_NO_RESTART Если этот флаг установлен, функция настраивает состояние устройства таким образом, что устройство не может быть перезапущено до тех пор, пока состояние устройства не будет сброшено.

Состояние устройства сбрасывается одним из следующих элементов:

  • Вызов CM_Setup_DevNode для устройства и указание CM_SETUP_DEVNODE_RESET. После сброса состояния устройства таким образом можно перезапустить устройство, вызвав CM_Reenumerate_DevNode для экземпляра устройства. После сброса состояния устройства любая другая операция, которая перечисляет устройство, также перезапустит устройство, например, если для повторной регистрации устройств используется диспетчер устройств.
  • Устройство отсоединяется и повторно подключено либо компьютер перезагружается. В этом случае состояние устройства будет сброшено, а устройство будет перезапущено.
  • Если этот флаг не установлен, состояние устройства не нужно сбрасывать. Вы можете перезапустить удаленное устройство, вызвав CM_Setup_DevNode для устройства и указав CM_SETUP_DEVNODE_READY. Любая другая операция, которая повторно использует устройство, также перезапустит устройство. Примером операции повторной регистрации устройства является вызов CM_Reenumerate_DevNode для устройства, отсоединение и повторное подключение устройства или перезагрузка компьютера. |

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

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

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

Требования

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

См. также раздел

CM_Get_Child
CM_Query_And_Remove_SubTree_Ex
CM_Reenumerate_DevNode
CM_Request_Device_Eject
CM_Setup_DevNode
DIF_PROPERTYCHANGE