DevGetObjectPropertiesEx-Funktion (devquery.h)

Synchrones Abrufen einer Gruppe von Eigenschaften für ein angegebenes Objekt optional basierend auf den angegebenen erweiterten Parametern.

Syntax

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
);

Parameter

[in] ObjectType

Ein Wert aus dem DEV_OBJECT_TYPE, der den Objekttyp bestimmt, für den Eigenschaften abgerufen werden sollen.

[in] pszObjectId

Die Identität des Objekts, für das Eigenschaften abgerufen werden sollen.

[in] QueryFlags

Eine Kombination aus DEV_QUERY_FLAGS Werten, die mithilfe eines bitweisen OR-Vorgangs kombiniert werden. Es ist ungültig, entweder DevQueryFlagUpdateResults oder DevQueryFlagAsyncClose- an diese Funktion zu übergeben.

[in] cRequestedProperties

Die Anzahl der DEVPROPCOMPKEY- Strukturen, die in pRequestedPropertiesbereitgestellt werden. Wenn DevQueryFlagAllProperties- angegeben ist, muss dies auf 0 festgelegt werden.

[in] pRequestedProperties

Stellt ein Array von DEVPROPCOMPKEY Strukturen bereit, die die Eigenschaften angeben, die für das angegebene Objekt abgerufen werden sollen.

Das LocaleName- Feld der DEVPROPCOMPKEY- Struktur wird ignoriert und muss auf NULL festgelegt werden.

Wenn cRequestedProperties 0 ist, muss dies NULL sein.

[in] cExtendedParameterCount

Reserviert für die Systemverwendung. Muss auf 0 festgelegt sein.

[in] pExtendedParameters

Reserviert für die Systemverwendung. Muss auf NULL festgelegt werden.

[out] pcPropertyCount

Die Anzahl der DEVPROPERTY- Strukturen, die in ppProperties-zurückgegeben werden.

[out] ppProperties

Zeiger, der das neu zugeordnete Array von DEVPROPERTY- Ergebnissen empfängt. Aufrufer müssen den Zeiger mit DevFreeObjectPropertiesfreigeben.

Rückgabewert

S_OK wird zurückgegeben, wenn die Funktion die Suchkriterien erfolgreich ausgewertet und übereinstimmende Objekte zurückgegeben hat; andernfalls ein entsprechender Fehlerwert.

Bemerkungen

Diese Funktion ist eine effiziente Möglichkeit, einen Satz von Eigenschaften aus einem Objekt anhand seines Typs und seiner Identität synchron abzurufen. Das Array der zurückgegebenen Eigenschaften muss mit DevFreeObjectPropertiesfreigegeben werden. Wenn keine angeforderte Eigenschaft vorhanden ist, enthält ppProperties- weiterhin einen Eintrag für diese Eigenschaft, aber der Eintrag hat einen Typ von DEVPROP_TYPE_EMPTY.

Beispiel

Im folgenden Beispiel wird veranschaulicht, DevGetObjectPropertiesEx- aufgerufen wird, um eine Reihe angeforderter Eigenschaften abzurufen und dann DevFindProperty- aufzurufen, um eine bestimmte Eigenschaft innerhalb eines Arrays von DEVPROPERTY- Strukturen zu finden.

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;
}

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows 10, Version 1809
mindestens unterstützte Server-	Windows Server 2019
Header-	devquery.h
Library	Onecore.lib
DLL-	Cfgmgr32.dll