función CM_Query_And_Remove_SubTree_ExW (cfgmgr32.h)

Artículo
03/08/2023

[A partir de Windows 8 y Windows Server 2012, esta función ha quedado en desuso. Use CM_Query_And_Remove_SubTree en su lugar.

La función CM_Query_And_Remove_SubTree_Ex 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_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
);

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 identificador de equipo proporcionado por hMachine.

[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

(Opcional). 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 .

[in, optional] hMachine

Identificador de equipo proporcionado por el autor de la llamada al que está enlazado el identificador de instancia del dispositivo proporcionado por el autor de la llamada.

Nota No se admite el uso de esta función para acceder a máquinas remotas a partir de Windows 8 y Windows Server 2012, ya que esta funcionalidad se ha quitado.

Valor devuelto

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

Comentarios

El propósito de la función CM_Query_And_Remove_SubTree_Ex es permitir que una aplicación prepare un dispositivo para la eliminación segura de una máquina remota. 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_Ex en lugar de CM_Query_And_Remove_SubTree_Ex.

CM_Query_And_Remove_SubTree_Ex 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:

A partir de Windows XP, CM_Query_And_Remove_SubTree_Ex 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:

Las aplicaciones de instalación de dispositivos que no requieren la operación de bajo nivel de CM_Query_And_Remove_SubTree_Ex deben usar la solicitud de DIF_PROPERTYCHANGE para deshabilitar un dispositivo en lugar de usar CM_Query_And_Remove_SubTree_Ex 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 un equipo local o remoto, consulte CM_Get_Child_Ex.

La funcionalidad para acceder a las máquinas remotas se ha quitado en Windows 8 y Windows Server 2012 y sistemas operativos posteriores, por lo que no se puede acceder a las máquinas remotas cuando se ejecutan en estas versiones de Windows.

Requisitos

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