CM_Query_And_Remove_SubTreeW, fonction (cfgmgr32.h)

Article
02/23/2024

La fonction CM_Query_And_Remove_SubTree vérifie si un appareil instance et ses enfants peuvent être supprimés et, si c’est le cas, elle les supprime.

Syntaxe

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

Paramètres

[in] dnAncestor

L’appareil fourni par l’appelant instance handle à l’appareil à la racine de la sous-arborescence à supprimer. Ce handle de instance d’appareil est lié à l’ordinateur local.

[out, optional] pVetoType

(Facultatif) Si l’appelant ne passe pas null et que la demande de suppression est bloquée (c’est-à-dire que la fonction retourne CR_REMOVE_VETOED), cette valeur pointe vers une valeur de type PNP_VETO_TYPE qui indique la raison du veto.

[out, optional] pszVetoName

(Facultatif) Si l’appelant ne passe pas null et que la demande de suppression est bloquée (autrement dit, la fonction retourne CR_REMOVE_VETOED), cette opération pointe vers une chaîne de texte associée au type de veto. Le type d’informations fournies par cette chaîne dépend de la valeur reçue par pVetoType. Pour plus d’informations sur ces chaînes, consultez PNP_VETO_TYPE.

[in] ulNameLength

Valeur fournie par l’appelant représentant la longueur (nombre de caractères) de la mémoire tampon de chaîne fournie par pszVetoName. Cette valeur doit être définie sur MAX_PATH.

[in] ulFlags

Or au niveau du bit des constantes d’indicateur fournies par l’appelant qui sont décrites dans la section Remarques .

Valeur retournée

Si l’opération réussit, la fonction retourne CR_SUCCESS. Sinon, elle retourne l’un des autres codes d’erreur préfixés CR_ définis dans Cfgmgr32.h.

Remarques

L’objectif de la fonction CM_Query_And_Remove_SubTree est de permettre à une application de préparer un appareil pour une suppression sécurisée de l’ordinateur local. Utilisez cette fonction pour supprimer des appareils uniquement si un pilote n’a pas défini le membre SurpriseRemovalOK de DEVICE_CAPABILITIES. Si un pilote a défini SurpriseRemovalOK, l’application doit appeler CM_Request_Device_Eject au lieu de CM_Query_And_Remove_SubTree.

CM_Query_And_Remove_SubTree prend en charge la définition du paramètre flags ulFlags avec l’un des deux indicateurs suivants : ces indicateurs s’appliquent uniquement si Windows ou un programme d’installation oppose son veto à la suppression d’un appareil :

Indicateur	Description
CM_REMOVE_UI_OK	La fonction permet d’afficher une boîte de dialogue utilisateur pour indiquer la raison du veto. Il s’agit du paramètre d’indicateur par défaut.
CM_REMOVE_UI_NOT_OK	La fonction supprime l’affichage d’une boîte de dialogue utilisateur qui indique la raison du veto.

À compter de Windows XP, CM_Query_And_Remove_SubTree prend également en charge la définition de l’indicateur supplémentaire suivant : cet indicateur s’applique uniquement si la fonction supprime correctement l’appareil instance :

Indicateur	Description
CM_REMOVE_NO_RESTART	Si cet indicateur est défini, la fonction configure l’appareil status de sorte que l’appareil ne puisse pas être redémarré tant que l’appareil status n’a pas été réinitialisé.

L’appareil status est réinitialisé par l’une des opérations suivantes :

Appel de CM_Setup_DevNode pour l’appareil et spécification de CM_SETUP_DEVNODE_RESET. Une fois la status de l’appareil réinitialisée de cette manière, vous pouvez redémarrer l’appareil en appelant CM_Reenumerate_DevNode pour le instance de l’appareil. Après avoir réinitialisé l’appareil status, toute autre opération qui énumère l’appareil redémarre également l’appareil, par exemple, si le Gestionnaire de périphériques est utilisé pour énumérer les appareils.
L’appareil est détaché et attaché à nouveau, ou l’ordinateur est redémarré. Dans ce cas, l’appareil status est réinitialisé et l’appareil est redémarré.
Si cet indicateur n’est pas défini, l’appareil status ne doit pas être réinitialisé. Vous pouvez redémarrer l’appareil supprimé en appelant un CM_Setup_DevNode pour l’appareil et en spécifiant CM_SETUP_DEVNODE_READY. Toute autre opération qui réinume l’appareil redémarre également l’appareil. Un exemple d’opération qui réinitule un appareil est l’appel de CM_Reenumerate_DevNode pour l’appareil, le détachement et le rattachement de l’appareil ou le redémarrage de l’ordinateur. |

Les applications Windows qui ne nécessitent pas l’opération de bas niveau CM_Query_And_Remove_SubTree doivent utiliser la demande de DIF_PROPERTYCHANGE pour désactiver un appareil au lieu d’utiliser CM_Query_And_Remove_SubTree pour supprimer un appareil. La demande DIF_PROPERTYCHANGE peut être utilisée pour activer, désactiver, redémarrer, arrêter ou modifier les propriétés d’un appareil.

Les appelants de cette fonction doivent avoir SeLoadDriverPrivilege. (Les privilèges sont décrits dans la documentation Microsoft Windows SDK.)

Pour plus d’informations sur l’utilisation de handles de instance d’appareil liés à l’ordinateur local, consultez CM_Get_Child.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible dans Microsoft Windows 2000 et versions ultérieures de Windows.
Plateforme cible	Universal
En-tête	cfgmgr32.h (inclure Cfgmgr32.h)
Bibliothèque	Cfgmgr32.lib