fonction CM_Query_And_Remove_SubTreeA (cfgmgr32.h)

Article
02/26/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_SubTreeA(
  [in]            DEVINST        dnAncestor,
  [out, optional] PPNP_VETO_TYPE pVetoType,
  [out, optional] LPSTR          pszVetoName,
  [in]            ULONG          ulNameLength,
  [in]            ULONG          ulFlags
);

Paramètres

[in] dnAncestor

L’appareil fourni par l’appelant instance gérer l’appareil à la racine de la sous-arborescence à supprimer. Ce handle d’appareil instance 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), lorsque vous retournez, cela pointe vers une valeur de type PNP_VETO_TYPE qui indique la raison du veto.

[out, optional] pszVetoName

(Facultatif) Si l’appelant ne transmet pas la valeur 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, il 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 d’indicateurs ulFlags avec l’un des deux indicateurs suivants : ces indicateurs s’appliquent uniquement si Windows ou un programme d’installation met 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 peut pas être redémarré tant qu’une fois que l’appareil status est réinitialisé.

L’appareil status est réinitialisé par l’un des éléments suivants :

Appelez CM_Setup_DevNode pour l’appareil et spécifiez CM_SETUP_DEVNODE_RESET. Une fois que l’appareil status est réinitialisé 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é le status de l’appareil, toute autre opération énumérant l’appareil redémarre également l’appareil, par exemple, si le Gestionnaire de périphériques est utilisé pour énumérer à nouveau les appareils.
L’appareil est détaché et attaché à nouveau, ou l’ordinateur est redémarré. Dans ce cas, l’appareil status sera réinitialisé et l’appareil sera redémarré.
Si cet indicateur n’est pas défini, le status de l’appareil n’a pas besoin d’ê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éinsère l’appareil redémarre également l’appareil. Un exemple d’opération qui réexécère 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 DIF_PROPERTYCHANGE pour désactiver un appareil au lieu d’utiliser CM_Query_And_Remove_SubTree pour supprimer un appareil. La requête 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

Voir aussi

CM_Get_Child
CM_Query_And_Remove_SubTree_Ex
CM_Reenumerate_DevNode
CM_Request_Device_Eject
CM_Setup_DevNode
DIF_PROPERTYCHANGE

Partager via