функция CM_Query_And_Remove_SubTreeW (cfgmgr32.h)
Функция CM_Query_And_Remove_SubTree проверяет, можно ли удалить экземпляр устройства и его дочерние элементы, и, если да, она удаляет их.
Синтаксис
CMAPI CONFIGRET CM_Query_And_Remove_SubTreeW(
[in] DEVINST dnAncestor,
[out, optional] PPNP_VETO_TYPE pVetoType,
[out, optional] LPWSTR 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 поддерживает установку параметра flags 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 |