DevGetObjectPropertiesEx, fonction (devquery.h)

Récupérez de façon synchrone un ensemble de propriétés pour un objet spécifié éventuellement en fonction des paramètres étendus spécifiés.

Syntaxe

HRESULT DevGetObjectPropertiesEx(
  [in]  DEV_OBJECT_TYPE           ObjectType,
  [in]  PCWSTR                    pszObjectId,
  [in]  ULONG                     QueryFlags,
  [in]  ULONG                     cRequestedProperties,
  [in]  const DEVPROPCOMPKEY      *pRequestedProperties,
  [in]  ULONG                     cExtendedParameterCount,
  [in]  const DEV_QUERY_PARAMETER *pExtendedParameters,
  [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.

[in] cExtendedParameterCount

Réservé à l’utilisation du système. Doit être défini sur 0.

[in] pExtendedParameters

Réservé à l’utilisation du système. Doit être défini sur 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 DevGetObjectPropertiesEx 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 = DevGetObjectPropertiesEx(DevObjectTypeDevice,
                                  DeviceInstancePath,
                                  DevQueryFlagNone,
                                  RTL_NUMBER_OF(RequestedProperties),
                                  RequestedProperties,
                                  0,
                                  NULL,
                                  &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