Acessando propriedades da instância do dispositivo

No Windows Vista e versões posteriores do Windows, aplicativos e instaladores podem acessar propriedades de instância de dispositivo que fazem parte do modelo de propriedade unificado chamando as funções a seguir.

Observação

Não há suporte para SetupApi em todas as edições do Windows. Quando possível, você deve usar APIs de camada inferior, como aquelas disponíveis por meio deCfgMgr32.dll. Confira Portabilidade de SetupApi para CfgMgr32 para obter dicas.

Para obter informações sobre como acessar as propriedades do dispositivo no Windows Server 2003, Windows XP e Windows 2000, consulte Using SetupAPI and Configuration Manager to Access Device Properties.

Recuperando propriedades

APIs de propriedade como CM_Get_DevNode_Property ou SetupDiGetDeviceProperty podem ser usadas para recuperar uma propriedade de dispositivo definida para uma instância de dispositivo. Por exemplo, aqui está um exemplo que está recuperando uma propriedade que deve ser do tipo 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);
}

Definir propriedades

APIs de propriedade como CM_Set_DevNode_Property ou SetupDiSetDeviceProperty podem ser usadas para definir uma propriedade de dispositivo para uma instância de dispositivo. Por exemplo, aqui está um exemplo que está definindo uma propriedade do tipo 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);
}

Obter uma lista de propriedades disponíveis

APIs de propriedade, como CM_Get_DevNode_Property_Keys ou SetupDiGetDevicePropertyKeys , podem ser usadas para recuperar uma matriz das chaves de propriedade do dispositivo que identificam as propriedades do dispositivo definidas atualmente para uma instância de dispositivo. Isso pode ser usado para determinar o conjunto completo de propriedades definidas em um dispositivo. No entanto, o uso dessas funções, especialmente para recuperar posteriormente o valor de todas as propriedades que essas funções indicam que estão definidas na instância do dispositivo, deve ser usado com moderação, pois a recuperação da lista de todas as propriedades e seus valores pode ser uma operação cara.