DevGetObjectProperties-Funktion (devquery.h)

Artikel
11/15/2024

Synchrones Abrufen einer Reihe von Eigenschaften für ein angegebenes Objekt

Syntax

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

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.

[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 das Aufrufen DevGetObjectProperties zum Abrufen einer Reihe angeforderter Eigenschaften veranschaulicht und anschließend DevFindProperty- aufgerufen, um eine bestimmte Eigenschaft innerhalb eines Arrays 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 = 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;
}

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

Freigeben über