DevGetObjectProperties, fonction (devquery.h)

Récupérer de façon synchrone un ensemble de propriétés pour un objet spécifié

Syntaxe

HRESULT DevGetObjectProperties(
  [in]  DEV_OBJECT_TYPE      ObjectType,
  [in]  PCWSTR               pszObjectId,
  [in]  ULONG                QueryFlags,
  [in]  ULONG                cRequestedProperties,
  [in]  const DEVPROPCOMPKEY *pRequestedProperties,
  [out] PULONG               pcPropertyCount,
  [out] const DEVPROPERTY    **ppProperties
);

Paramètres

[in] ObjectType

Valeur de l'DEV_OBJECT_TYPE qui détermine le type d’objet pour lequel les propriétés doivent être récupérées.

[in] pszObjectId

Identité de l’objet pour lequel les propriétés doivent être récupérées.

[in] QueryFlags

Combinaison de valeurs DEV_QUERY_FLAGS combinées à l’aide d’une opération OR au niveau du bit. Il n’est pas valide de passer DevQueryFlagUpdateResults ou DevQueryFlagAsyncClose à cette fonction.

[in] cRequestedProperties

Nombre de structures DEVPROPCOMPKEY fournies dans pRequestedProperties. Si DevQueryFlagAllProperties est spécifié, cette valeur doit être définie sur 0.

[in] pRequestedProperties

Fournit un tableau de structures DEVPROPCOMPKEY qui spécifient les propriétés qui doivent être récupérées pour l’objet spécifié.

Le champ LocaleName de la structure DEVPROPCOMPKEY est ignoré et doit être défini sur NULL.

Si cRequestedProperties est 0, cette valeur doit être NULL.

[out] pcPropertyCount

Nombre de structures DEVPROPERTY retournées dans ppProperties.

[out] ppProperties

Pointeur qui reçoit le tableau nouvellement alloué de résultats DEVPROPERTY. Les appelants doivent libérer le pointeur à l’aide de DevFreeObjectProperties.

Valeur de retour

S_OK est retourné si la fonction a correctement évalué les critères de recherche et retourné des objets correspondants ; sinon, valeur d’erreur appropriée.

Remarques

Cette fonction est un moyen efficace de récupérer de manière synchrone un ensemble de propriétés à partir d’un objet en fonction de son type et de son identité. Le tableau des propriétés retournées doit être libéré à l’aide de DevFreeObjectProperties. Si une propriété demandée n’existe pas, ppProperties contiendra toujours une entrée pour cette propriété, mais l’entrée aura un type de DEVPROP_TYPE_EMPTY.

Exemple

L’exemple suivant montre comment appeler DevGetObjectProperties pour récupérer un ensemble de propriétés demandées, puis appeler DevFindProperty pour rechercher une propriété particulière dans un tableau de structures DEVPROPERTY.

void
Example1(PCWSTR DeviceInstancePath)
{
    HRESULT hr = S_OK;
    const DEVPROPERTY* TempProperty = NULL;
    ULONG PropertyCount = 0;
    const DEVPROPERTY* PropertyList = NULL;
    DEVPROPCOMPKEY RequestedProperties[] =
    {
        { DEVPKEY_Device_HardwareIds, DEVPROP_STORE_SYSTEM, NULL },
        { DEVPKEY_Device_CompatibleIds, DEVPROP_STORE_SYSTEM, NULL }
    };

    hr = DevGetObjectProperties(DevObjectTypeDevice,
                                DeviceInstancePath,
                                DevQueryFlagNone,
                                RTL_NUMBER_OF(RequestedProperties),
                                RequestedProperties,
                                &PropertyCount,
                                &PropertyList);

    if (FAILED(hr))
    {
        wprintf(L"Failed to retrieve properties. hr = 0x%08x\n", hr);
        goto exit;
    }

    wprintf(L"Hardware IDs:\n");
    TempProperty = DevFindProperty(&DEVPKEY_Device_HardwareIds,
                                   DEVPROP_STORE_SYSTEM,
                                   NULL,
                                   PropertyCount,
                                   PropertyList);

    if ((TempProperty == NULL) ||
        (TempProperty->Type == DEVPROP_TYPE_EMPTY) ||
        (TempProperty->Buffer == NULL))
    {
        wprintf(L"<none>\n");
    }
    else if ((TempProperty->Type != DEVPROP_TYPE_STRING_LIST) ||
             (TempProperty->BufferSize < sizeof(WCHAR)))
    {
        wprintf(L"Device '%ws' has a corrupted Hardware IDs property.\n",
                DeviceInstancePath);
    }
    else
    {
        for (PCWSTR CurrentId = (PCWSTR)TempProperty->Buffer;
             *CurrentId != L'\0';
             CurrentId += wcslen(CurrentId) + 1)
        {
            wprintf(L"%ws\n", CurrentId);
        }
    }

    wprintf(L"\nCompatible IDs:\n");
    TempProperty = DevFindProperty(&DEVPKEY_Device_CompatibleIds,
                                   DEVPROP_STORE_SYSTEM,
                                   NULL,
                                   PropertyCount,
                                   PropertyList);

    if ((TempProperty == NULL) ||
        (TempProperty->Type == DEVPROP_TYPE_EMPTY) ||
        (TempProperty->Buffer == NULL))
    {
        wprintf(L"<none>\n");
    }
    else if ((TempProperty->Type != DEVPROP_TYPE_STRING_LIST) ||
             (TempProperty->BufferSize < sizeof(WCHAR)))
    {
        wprintf(L"Device '%ws' has a corrupted Compatible IDs property.\n",
                DeviceInstancePath);
    }
    else
    {
        for (PCWSTR CurrentId = (PCWSTR)TempProperty->Buffer;
             *CurrentId != L'\0';
             CurrentId += wcslen(CurrentId) + 1)
        {
            wprintf(L"%ws\n", CurrentId);
        }
    }

  exit:

    if (PropertyList != NULL)
    {
        DevFreeObjectProperties(PropertyCount, PropertyList);
    }

    return;
}

Exigences

Exigence	Valeur
client minimum pris en charge	Windows 10 version 1809
serveur minimum pris en charge	Windows Server 2019
d’en-tête	devquery.h
bibliothèque	Onecore.lib
DLL	Cfgmgr32.dll