função CM_Query_And_Remove_SubTree_ExW (cfgmgr32.h)

Artigo
02/23/2024

[Começando com Windows 8 e Windows Server 2012, essa função foi preterida. Em vez disso, use CM_Query_And_Remove_SubTree .]

A função CM_Query_And_Remove_SubTree_Ex verifica se uma instância de dispositivo e seus filhos podem ser removidos e, nesse caso, remove-os.

Sintaxe

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 instância de dispositivo fornecido pelo chamador para o dispositivo na raiz da subárvore a ser removida. Esse identificador de instância do dispositivo está associado ao identificador do computador fornecido pelo hMachine.

[out, optional] pVetoType

(Opcional) Se o chamador não passar NULL e a solicitação de remoção for vetada (ou seja, a função retornará CR_REMOVE_VETOED), ao retornar esse ponto para um valor tipado em PNP_VETO_TYPE que indica o motivo do veto.

[out, optional] pszVetoName

(Opcional) Se o chamador não passar NULL e a solicitação de remoção for vetada (ou seja, a função retornará CR_REMOVE_VETOED), ao retornar esse ponto para uma cadeia de caracteres de texto associada ao tipo de veto. O tipo de informação que essa cadeia de caracteres fornece depende do valor recebido por pVetoType. Para obter informações sobre essas cadeias de caracteres, consulte PNP_VETO_TYPE.

[in] ulNameLength

(Opcional.) Valor fornecido pelo chamador que representa o comprimento (número de caracteres) do buffer de cadeia de caracteres fornecido por pszVetoName. Isso deve ser definido como MAX_PATH.

[in] ulFlags

Um OR bit a bit das constantes de sinalizador fornecidas pelo chamador descritas na seção Comentários.

[in, optional] hMachine

Identificador de computador fornecido pelo chamador ao qual o identificador de instância do dispositivo fornecido pelo chamador está associado.

Nota Não há suporte para o uso dessa função para acessar computadores remotos, começando com Windows 8 e Windows Server 2012, pois essa funcionalidade foi removida.

Retornar valor

Se a operação for bem-sucedida, a função retornará CR_SUCCESS. Caso contrário, ele retornará um dos códigos de erro prefixados por CR_ definidos em Cfgmgr32.h.

Comentários

A finalidade da função CM_Query_And_Remove_SubTree_Ex é permitir que um aplicativo prepare um dispositivo para remoção segura de um computador remoto. Use essa função para remover dispositivos somente se um driver não tiver definido o membro SurpriseRemovalOK de DEVICE_CAPABILITIES. Se um driver tiver definido SurpriseRemovalOK, o aplicativo deverá chamar CM_Request_Device_Eject_Ex em vez de CM_Query_And_Remove_SubTree_Ex.

CM_Query_And_Remove_SubTree_Ex dá suporte à definição do parâmetro flags ulFlags com um dos dois sinalizadores a seguir; esses sinalizadores se aplicam somente se o Windows ou um instalador veta a remoção de um dispositivo:

A partir do Windows XP, CM_Query_And_Remove_SubTree_Ex também dá suporte à configuração do sinalizador adicional a seguir; esse sinalizador só se aplicará se a função remover com êxito a instância do dispositivo:

Aplicativos de instalação de dispositivo que não exigem a operação de baixo nível de CM_Query_And_Remove_SubTree_Ex devem usar a solicitação DIF_PROPERTYCHANGE para desabilitar um dispositivo em vez de usar CM_Query_And_Remove_SubTree_Ex para remover um dispositivo. A solicitação DIF_PROPERTYCHANGE pode ser usada para habilitar, desabilitar, reiniciar, parar ou alterar as propriedades de um dispositivo.

Os chamadores dessa função devem ter SeLoadDriverPrivilege. (Os privilégios são descritos na documentação do SDK do Microsoft Windows.)

Para obter informações sobre como usar identificadores de instância de dispositivo associados a um computador local ou remoto, consulte CM_Get_Child_Ex.

A funcionalidade para acessar computadores remotos foi removida em sistemas operacionais Windows 8 e Windows Server 2012 e posteriores, portanto, você não pode acessar computadores remotos durante a execução nessas versões do Windows.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível no Microsoft Windows 2000 e versões posteriores do Windows.
Plataforma de Destino	Área de Trabalho
Cabeçalho	cfgmgr32.h (inclua Cfgmgr32.h)
Biblioteca	Cfgmgr32.lib