función CM_Query_And_Remove_SubTreeW (cfgmgr32.h)

Artículo
02/26/2024

La función CM_Query_And_Remove_SubTree comprueba si se puede quitar una instancia de dispositivo y sus elementos secundarios y, si es así, las quita.

Sintaxis

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
);

Parámetros

[in] dnAncestor

Identificador de instancia de dispositivo proporcionado por el autor de la llamada al dispositivo en la raíz del subárbol que se va a quitar. Este identificador de instancia de dispositivo está enlazado al equipo local.

[out, optional] pVetoType

(Opcional) Si el autor de la llamada no pasa NULL y la solicitud de eliminación se veta (es decir, la función devuelve CR_REMOVE_VETOED), al devolver esto apunta a un valor de tipo PNP_VETO_TYPE que indica el motivo del vetar.

[out, optional] pszVetoName

(Opcional) Si el autor de la llamada no pasa NULL y la solicitud de eliminación se veta (es decir, la función devuelve CR_REMOVE_VETOED), al devolver esto apunta a una cadena de texto asociada al tipo de vetaje. El tipo de información que proporciona esta cadena depende del valor recibido por pVetoType. Para obtener información sobre estas cadenas, vea PNP_VETO_TYPE.

[in] ulNameLength

Valor proporcionado por el autor de la llamada que representa la longitud (número de caracteres) del búfer de cadena proporcionado por pszVetoName. Debe establecerse en MAX_PATH.

[in] ulFlags

Or bit a bit de las constantes de marca proporcionadas por el autor de la llamada que se describen en la sección Comentarios .

Valor devuelto

Si la operación se realiza correctamente, la función devuelve CR_SUCCESS. De lo contrario, devuelve uno de los otros códigos de error con prefijo CR_ definidos en Cfgmgr32.h.

Comentarios

El propósito de la función CM_Query_And_Remove_SubTree es permitir que una aplicación prepare un dispositivo para la eliminación segura de la máquina local. Use esta función para quitar dispositivos solo si un controlador no ha establecido el miembro SurpriseRemovalOK de DEVICE_CAPABILITIES. Si un controlador ha establecido SurpriseRemovalOK, la aplicación debe llamar a CM_Request_Device_Eject en lugar de CM_Query_And_Remove_SubTree.

CM_Query_And_Remove_SubTree admite la configuración del parámetro flags ulFlags con una de las dos marcas siguientes; estas marcas solo se aplican si Windows o un instalador bloquean la eliminación de un dispositivo:

Marca	Descripción
CM_REMOVE_UI_OK	La función permite que se muestre un cuadro de diálogo de usuario para indicar el motivo del vetar. Esta es la configuración de marca predeterminada.
CM_REMOVE_UI_NOT_OK	La función suprime la presentación de un cuadro de diálogo de usuario que indica el motivo del veteo.

A partir de Windows XP, CM_Query_And_Remove_SubTree también admite la configuración de la siguiente marca adicional; esta marca solo se aplica si la función quita correctamente la instancia del dispositivo:

Marca	Descripción
CM_REMOVE_NO_RESTART	Si se establece esta marca, la función configura el estado del dispositivo de modo que el dispositivo no se pueda reiniciar hasta que se restablezca el estado del dispositivo.

El estado del dispositivo se restablece por uno de los siguientes elementos:

Llamar a CM_Setup_DevNode para el dispositivo y especificar CM_SETUP_DEVNODE_RESET. Una vez restablecido el estado del dispositivo de esta manera, el dispositivo se puede reiniciar llamando a CM_Reenumerate_DevNode para la instancia del dispositivo. Después de restablecer el estado del dispositivo, cualquier otra operación que enumere el dispositivo también reiniciará el dispositivo, por ejemplo, si el Administrador de dispositivos se usa para volver a enumerar los dispositivos.
El dispositivo se desasocia y se vuelve a adjuntar o se reinicia el equipo. En este caso, se restablecerá el estado del dispositivo y se reiniciará el dispositivo.
Si no se establece esta marca, no es necesario restablecer el estado del dispositivo. Puede reiniciar el dispositivo quitado mediante una llamada CM_Setup_DevNode para el dispositivo y especificando CM_SETUP_DEVNODE_READY. Cualquier otra operación que vuelva a enumerar el dispositivo también reiniciará el dispositivo. Un ejemplo de una operación que vuelve a enumerar un dispositivo llama a CM_Reenumerate_DevNode para el dispositivo, desasociar y volver a asociar el dispositivo o reiniciar el equipo. |

Las aplicaciones de Windows que no requieren la operación de bajo nivel CM_Query_And_Remove_SubTree deben usar la solicitud de DIF_PROPERTYCHANGE para deshabilitar un dispositivo en lugar de usar CM_Query_And_Remove_SubTree para quitar un dispositivo. La solicitud DIF_PROPERTYCHANGE se puede usar para habilitar, deshabilitar, reiniciar, detener o cambiar las propiedades de un dispositivo.

Los autores de llamadas de esta función deben tener SeLoadDriverPrivilege. (Los privilegios se describen en la documentación de Microsoft Windows SDK).

Para obtener información sobre el uso de identificadores de instancia de dispositivo enlazados a la máquina local, consulte CM_Get_Child.

Requisitos

Requisito	Value
Cliente mínimo compatible	Disponible en Microsoft Windows 2000 y versiones posteriores de Windows.
Plataforma de destino	Universal
Encabezado	cfgmgr32.h (incluya Cfgmgr32.h)
Library	Cfgmgr32.lib