fonction CM_Get_Device_ID_ListW (cfgmgr32.h)
La fonction CM_Get_Device_ID_List récupère une liste d’ID d’instance d’appareil pour les instances d’appareil de l’ordinateur local.
Syntaxe
CMAPI CONFIGRET CM_Get_Device_ID_ListW(
[in, optional] PCWSTR pszFilter,
[out] PZZWSTR 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 d’instance d’appareil de l’ordinateur ou vers 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’instance d’appareil terminées par NULL. La fin du jeu est arrêtée par une 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 tampon .
[in] ulFlags
L’un des indicateurs de bits fournis par l’appelant suivant qui spécifie les filtres de recherche :
CM_GETIDLIST_FILTER_BUSRELATIONS
Si cet indicateur est défini, pszFilter doit spécifier un identificateur d’instance d’appareil. La fonction retourne les ID d’instance d’appareil pour les relations de bus de l’instance d’appareil spécifiée.
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 une classe de configuration d’appareil GUID. 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 classe de configuration d’appareil spécifié.
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 d’instance d’appareil d’un nœud d’appareil composite (devnode).
La fonction retourne les identificateurs d’instance d’appareil 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 suivante Remarques.
CM_GETIDLIST_DONOTGENERATE
Utilisé uniquement avec CM_GETIDLIST_FILTER_SERVICE. Si elle est définie et si l’arborescence de l’appareil 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 d’instance d’appareil. La fonction retourne les ID d’instance d’appareil pour les relations d’éjection de l’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 ID d’instance d’appareil pour les instances de chaque appareil associé à l’énumérateur. Vous pouvez obtenir des noms d’énumérateurs en appelant CM_Enumerate_Enumerators.
Si pszFilter fournit à la fois un énumérateur et un ID d’appareil , la fonction retourne ID d’instance 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 d’instance d’appareil. La fonction retourne les ID d’instance d’appareil pour les relations de puissance de l’instance d’appareil spécifiée.
CM_GETIDLIST_FILTER_REMOVALRELATIONS
Si cet indicateur est défini, pszFilter doit spécifier un identificateur d’instance d’appareil. La fonction retourne les ID d’instance d’appareil pour les relations de suppression de l’instance d’appareil spécifiée.
CM_GETIDLIST_FILTER_SERVICE
Si cet indicateur est défini, pszFilter devez spécifier le nom d’un service Microsoft Windows (généralement un pilote). La fonction retourne les ID d’instance d’appareil pour les instances d’appareil contrôlées par le service spécifié.
Notez que si l’arborescence de l’appareil ne contient pas de devnode pour le service spécifié, cette fonction en crée une 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 d’instance d’appareil pour toutes les instances d’appareil.
Valeur de retour
Si l’opération réussit, la fonction retourne CR_SUCCESS. Sinon, elle retourne l’un des codes d’erreur CR_ préfixés 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 composite devnode. 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 des 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 l’usb et les bus 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 spécifiez l’ID d’instance de l’appareil du devnode composite du téléphone cellulaire dans pszFilter, la fonction retourne les ID d’instance d’appareil pour les deux devnodes de transport dans le paramètre Buffer.
Pour plus d’informations sur les ID d’instance d’appareil, consultez chaînes d’identification d’appareil.
Note
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. Le mélange 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.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Disponible dans Microsoft Windows 2000 et versions ultérieures de Windows. |
| plateforme cible | Universel |
| d’en-tête | cfgmgr32.h (include Cfgmgr32.h) |
| bibliothèque | Cfgmgr32.lib |
| DLL | CfgMgr32.dll |