função CM_Query_And_Remove_SubTreeW (cfgmgr32.h)

Artigo
08/22/2023

A função CM_Query_And_Remove_SubTree 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_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 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 computador local.

[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

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.

Retornar valor

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

Comentários

A finalidade da função CM_Query_And_Remove_SubTree é permitir que um aplicativo prepare um dispositivo para remoção segura do computador local. 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 em vez de CM_Query_And_Remove_SubTree.

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

Sinalizador	Descrição
CM_REMOVE_UI_OK	A função permite que uma caixa de diálogo do usuário seja exibida para indicar o motivo do veto. Essa é a configuração de sinalizador padrão.
CM_REMOVE_UI_NOT_OK	A função suprime a exibição de uma caixa de diálogo do usuário que indica o motivo do veto.

A partir do Windows XP, CM_Query_And_Remove_SubTree 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:

Sinalizador	Descrição
CM_REMOVE_NO_RESTART	Se esse sinalizador estiver definido, a função configurará o dispositivo status de modo que o dispositivo não possa ser reiniciado até que o dispositivo status seja redefinido.

O dispositivo status é redefinido pelo seguinte:

Chamando CM_Setup_DevNode para o dispositivo e especificando CM_SETUP_DEVNODE_RESET. Depois que o dispositivo status for redefinido dessa maneira, o dispositivo poderá ser reiniciado chamando CM_Reenumerate_DevNode para a instância do dispositivo. Depois de redefinir o dispositivo status, qualquer outra operação que enumerar o dispositivo também reiniciará o dispositivo, por exemplo, se o Gerenciador de Dispositivos for usado para reenumerar dispositivos.
O dispositivo é desanexado e reanexado ou o computador é reiniciado. Nesse caso, o dispositivo status será redefinido e o dispositivo será reiniciado.
Se esse sinalizador não estiver definido, o dispositivo status não precisará ser redefinido. Você pode reiniciar o dispositivo removido chamando CM_Setup_DevNode para o dispositivo e especificando CM_SETUP_DEVNODE_READY. Qualquer outra operação que reenumere o dispositivo também reiniciará o dispositivo. Um exemplo de uma operação que reenumeriza um dispositivo é chamar CM_Reenumerate_DevNode para o dispositivo, desanexar e reanexar o dispositivo ou reiniciar o computador. |

Aplicativos do Windows que não exigem a operação de baixo nível CM_Query_And_Remove_SubTree devem usar a solicitação DIF_PROPERTYCHANGE para desabilitar um dispositivo em vez de usar CM_Query_And_Remove_SubTree 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 ao computador local, consulte CM_Get_Child.

Requisitos

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