fonction CM_Get_Device_ID_ListW (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_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 de instance (ID) de l’appareil 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 suivant 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 les 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 d’installation 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 d’installation 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 les ID d’appareil instance pour les relations d’éjection du instance d’appareil spécifié.

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>, tel que 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ées à 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 les ID d’appareil instance 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 d’appareil instance 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 les ID d’appareil instance 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 les ID d’appareil instance 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 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 instance d’appareil pour toutes les instances d’appareil.

Valeur retournée

Si l’opération réussit, la fonction retourne CR_SUCCESS. Sinon, il 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 devnodecomposite. Un devnode composite représente logiquement l’appareil composite pour l’utilisateur et les applications sous la forme d’un seul appareil, 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 publiques, 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 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.

Configuration requise

Voir aussi

CM_Get_Device_ID_List_Size