CM_Query_And_Remove_SubTree_ExW, fonction (cfgmgr32.h)

Article
08/22/2023

[À compter de Windows 8 et Windows Server 2012, cette fonction a été déconseillée. Utilisez CM_Query_And_Remove_SubTree à la place.]

La fonction CM_Query_And_Remove_SubTree_Ex 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_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
);

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é au handle de machine fourni par hMachine.

[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

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

[in, optional] hMachine

Handle de machine fourni par l’appelant auquel le handle de instance d’appareil fourni par l’appelant est lié.

Note L’utilisation de cette fonction pour accéder aux machines distantes n’est pas prise en charge à partir de Windows 8 et Windows Server 2012, car cette fonctionnalité a été supprimée.

Valeur retournée

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

Remarques

L’objectif de la fonction CM_Query_And_Remove_SubTree_Ex est de permettre à une application de préparer un appareil pour une suppression sécurisée d’un ordinateur distant. 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_Ex au lieu de CM_Query_And_Remove_SubTree_Ex.

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

À compter de Windows XP, CM_Query_And_Remove_SubTree_Ex 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 :

Les applications d’installation d’appareil qui ne nécessitent pas l’opération de bas niveau de CM_Query_And_Remove_SubTree_Ex doivent utiliser la demande DIF_PROPERTYCHANGE pour désactiver un appareil au lieu d’utiliser CM_Query_And_Remove_SubTree_Ex 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 à un ordinateur local ou distant, consultez CM_Get_Child_Ex.

La fonctionnalité permettant d’accéder aux ordinateurs distants a été supprimée dans Windows 8 et Windows Server 2012 systèmes d’exploitation et versions ultérieures. Vous ne pouvez donc pas accéder aux ordinateurs distants lors de l’exécution sur ces versions de Windows.

Configuration requise

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