CM_Get_Device_ID_ListA, fonction (cfgmgr32.h)

La fonction CM_Get_Device_ID_List récupère une liste d’ID de instance d’appareil pour lesinstances d’appareil de l’ordinateur local.

Syntaxe

CMAPI CONFIGRET CM_Get_Device_ID_ListA(
  [in, optional] PCSTR  pszFilter,
  [out]          PZZSTR Buffer,
  [in]           ULONG  BufferLen,
  [in]           ULONG  ulFlags
);

Paramètres

[in, optional] pszFilter

Pointeur fourni par l’appelant vers une chaîne de caractères définie sur un sous-ensemble des identificateurs de instance d’appareil (ID) de l’ordinateur, ou sur NULL. Consultez la description suivante de ulFlags.

[out] Buffer

Adresse d’une mémoire tampon pour recevoir un ensemble de chaînes d’identificateur d’appareil terminées par NULL instance. La fin du jeu est terminée par une valeur NULL supplémentaire. La taille de mémoire tampon requise doit être obtenue en appelant CM_Get_Device_ID_List_Size.

[in] BufferLen

Longueur fournie par l’appelant, en caractères, de la mémoire tampon spécifiée par Buffer.

[in] ulFlags

L’un des indicateurs de bits fournis par l’appelant qui spécifie les filtres de recherche :

CM_GETIDLIST_FILTER_BUSRELATIONS

Si cet indicateur est défini, pszFilter doit spécifier un identificateur de instance d’appareil. La fonction retourne des ID de instance d’appareil pour les relations de bus du instance d’appareil spécifié.

CM_GETIDLIST_FILTER_CLASS (Windows 7 et versions ultérieures de Windows)

Si cet indicateur est défini, pszFilter contient une chaîne qui spécifie un GUID de classe de configuration d’appareil . La liste retournée contient des instances d’appareil pour lesquelles la propriété (référencée par la constante CM_DRP_CLASSGUID) correspond au GUID de la classe de configuration d’appareil spécifiée.

La constante CM_DRP_CLASSGUID est définie dans Cfgmgr32.h.

CM_GETIDLIST_FILTER_PRESENT (Windows 7 et versions ultérieures de Windows)

Si cet indicateur est défini, la liste retournée contient uniquement les instances d’appareil actuellement présentes sur le système. Cette valeur peut être combinée avec d’autres valeurs ulFlags , telles que CM_GETIDLIST_FILTER_CLASS.

CM_GETIDLIST_FILTER_TRANSPORTRELATIONS (Windows 7 et versions ultérieures de Windows)

Si cet indicateur est défini, pszFilter doit spécifier l’identificateur de instance d’appareil d’un nœud d’appareil composite (devnode).

La fonction retourne l’appareil instance identificateurs des devnodes qui représentent les relations de transport du devnode composite spécifié.

Pour plus d’informations sur les devnodes composites et les relations de transport, consultez la section Remarques suivante.

CM_GETIDLIST_DONOTGENERATE

Utilisé uniquement avec CM_GETIDLIST_FILTER_SERVICE. S’il est défini et si l’arborescence d’appareils ne contient pas de devnode pour le service spécifié, cet indicateur empêche la fonction de créer un devnode pour le service.

CM_GETIDLIST_FILTER_EJECTRELATIONS

Si cet indicateur est défini, pszFilter doit spécifier un identificateur de instance d’appareil. La fonction retourne des ID de instance d’appareil pour les relations d’éjection de la instance d’appareil spécifiée.

CM_GETIDLIST_FILTER_ENUMERATOR

Si cet indicateur est défini, pszFilter doit spécifier le nom d’un énumérateur d’appareil, éventuellement suivi d’un ID d’appareil. Le format de chaîne est EnumeratorName\<DeviceID>, par exemple ROOT ou ROOT\*PNP0500.

Si pszFilter fournit uniquement un nom d’énumérateur, la fonction retourne les ID de instance d’appareil pour les instances de chaque appareil associé à l’énumérateur. Les noms d’énumérateurs peuvent être obtenus en appelant CM_Enumerate_Enumerators.

Si pszFilter fournit à la fois un énumérateur et un ID d’appareil, la fonction retourne instance ID d’appareil uniquement pour les instances de l’appareil spécifié associé à l’énumérateur.

CM_GETIDLIST_FILTER_NONE

Si cet indicateur est défini, pszFilter est ignoré et une liste de tous les appareils sur le système est retournée.

CM_GETIDLIST_FILTER_POWERRELATIONS

Si cet indicateur est défini, pszFilter doit spécifier un identificateur de instance d’appareil. La fonction retourne les ID de instance d’appareil pour les relations d’alimentation du instance d’appareil spécifié.

CM_GETIDLIST_FILTER_REMOVALRELATIONS

Si cet indicateur est défini, pszFilter doit spécifier un identificateur de instance d’appareil. La fonction retourne des ID de instance d’appareil pour les relations de suppression du instance d’appareil spécifié.

CM_GETIDLIST_FILTER_SERVICE

Si cet indicateur est défini, pszFilter doit spécifier le nom d’un service Microsoft Windows (généralement un pilote). La fonction retourne des ID de instance d’appareil pour les instances d’appareil contrôlées par le service spécifié.

Notez que si l’arborescence d’appareils ne contient pas de devnode pour le service spécifié, cette fonction en crée un par défaut. Pour empêcher ce comportement, définissez également CM_GETIDLIST_DONOTGENERATE.

Si aucun indicateur de filtre de recherche n’est spécifié, la fonction retourne tous les ID de instance d’appareil pour toutes les instances d’appareil.

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

À compter de Windows 7, un appareil qui prend en charge plusieurs chemins de transport pour les données basées sur des paquets est appelé appareil composite et est représenté par un devnodecomposite. Un devnode composite représente logiquement l’appareil composite pour l’utilisateur et les applications en tant qu’appareil unique, même si le devnode composite peut avoir plusieurs chemins d’accès à l’appareil physique.

Chaque chemin de transport actif vers l’appareil physique est représenté par un devnode de transport et est appelé relation de transport pour l’appareil composite.

Le devnode composite (mais pas les devnodes de transport associés) expose les interfaces d’appareil aux applications et au système. Lorsqu’une application utilise ces interfaces d’appareil public, l’appareil composite achemine les données basées sur les paquets vers un ou plusieurs de ces devnodes de transport, qui transportent ensuite les données vers l’appareil physique.

Par exemple, si un téléphone cellulaire physique est connecté simultanément à l’ordinateur sur les bus USB et Bluetooth, chaque bus énumère un devnode de transport enfant sur ce bus pour représenter la connexion physique de l’appareil.

Dans ce cas, si vous définissez les indicateurs de CM_GETIDLIST_FILTER_TRANSPORTRELATIONS dans ulFlags et que vous spécifiez l’ID de instance de l’appareil du devnode composite du téléphone portable dans pszFilter, la fonction retourne l’appareil instance ID pour les deux devnodes de transport dans le paramètre Buffer.

Pour plus d’informations sur les ID de instance d’appareil, consultez Chaînes d’identification d’appareil.

Notes

L’en-tête cfgmgr32.h définit CM_Get_Device_ID_List en tant qu’alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. La combinaison de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

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
DLL	CfgMgr32.dll

Voir aussi

CM_Get_Device_ID_List_Size