Accès aux propriétés de l’instance d’appareil

Dans Windows Vista et les versions ultérieures de Windows, les applications et les programmes d’installation peuvent accéder aux propriétés de instance d’appareil qui font partie du modèle de propriété unifié en appelant les fonctions suivantes.

Notes

SetupApi n’est pas pris en charge sur toutes les éditions de Windows. Dans la mesure du possible, vous devez utiliser des API de couche inférieure telles que celles disponibles via CfgMgr32.dll. Pour obtenir des conseils, consultez Portage de SetupApi vers CfgMgr32 .

Pour plus d’informations sur l’accès aux propriétés de l’appareil sur Windows Server 2003, Windows XP et Windows 2000, voir Using SetupAPI and Configuration Manager to Access Device Properties.

Récupération des propriétés

Les API de propriété telles que CM_Get_DevNode_Property ou SetupDiGetDeviceProperty peuvent être utilisées pour récupérer une propriété d’appareil définie pour un appareil instance. Par exemple, voici un exemple qui récupère une propriété qui est censée être de type DEVPROP_TYPE_UINT32 :

DEVPROPTYPE PropertyType = DEVPROP_TYPE_EMPTY;
ULONG PropertySize = 0;
ULONG SomeValue = 0;

PropertySize = sizeof(SomeValue);
cr = CM_Get_DevNode_Property(DevInst,
                             &DEVPKEY_CustomProperty,
                             &PropertyType,
                             (PBYTE)&SomeValue,
                             &PropertySize,
                             0);

if (cr == CR_NO_SUCH_VALUE) {
    printf("Property was not found\n");
} else if (cr != CR_SUCCESS) {
    printf("Error 0x%08x retrieving property.\n", cr);
} else if ((PropertyType != DEVPROP_TYPE_UINT32) || (PropertySize != sizeof(SomeValue))) {
    printf("Property data was not of the expected type or size\n");
} else {
    printf("Property value: 0x%08x\n", SomeValue);
}

Définition de propriétés

Les API de propriété telles que CM_Set_DevNode_Property ou SetupDiSetDeviceProperty peuvent être utilisées pour définir une propriété d’appareil pour un appareil instance. Par exemple, voici un exemple qui définit une propriété de type DEVPROP_TYPE_UINT32 :

ULONG SomeValue = 5;
cr = CM_Set_DevNode_Property(DevInst,
                             &DEVPKEY_CustomProperty,
                             DEVPROP_TYPE_UINT32,
                             (PBYTE)&SomeValue,
                             sizeof(SomeValue),
                             0);

if (cr != CR_SUCCESS) {
    printf("Error 0x%08x setting property.\n", cr);
}

Obtention d’une liste des propriétés disponibles

Les API de propriété telles que CM_Get_DevNode_Property_Keys ou SetupDiGetDevicePropertyKeys peuvent être utilisées pour récupérer un tableau des clés de propriété d’appareil qui identifient les propriétés d’appareil actuellement définies pour un appareil instance. Cela peut être utilisé pour déterminer l’ensemble complet des propriétés définies sur un appareil. Toutefois, l’utilisation de ces fonctions, en particulier pour récupérer ensuite la valeur de toutes les propriétés que ces fonctions indiquent sont définies sur l’appareil instance, doit être utilisée avec parcimonie, car la récupération de la liste de toutes les propriétés et de leurs valeurs peut être une opération coûteuse.