DevGetObjects-Funktion (devquery.h)

Ruft synchron eine Reihe von DEV_OBJECT Strukturen basierend auf den bereitgestellten angeforderten Eigenschaften und Filterkriterien ab.

Syntax

HRESULT DevGetObjects(
  [in]           DEV_OBJECT_TYPE                 ObjectType,
  [in]           ULONG                           QueryFlags,
  [in]           ULONG                           cRequestedProperties,
  [in, optional] const DEVPROPCOMPKEY            *pRequestedProperties,
  [in]           ULONG                           cFilterExpressionCount,
  [in, optional] const DEVPROP_FILTER_EXPRESSION *pFilter,
  [out]          PULONG                          pcObjectCount,
  [out]          const DEV_OBJECT                **ppObjects
);

Parameter

[in] ObjectType

Ein Wert aus der DEV_OBJECT_TYPE-Aufzählung, der den Objekttyp bestimmt, für den diese Abfrage ausgeführt werden soll.

[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, optional] pRequestedProperties

Stellt optional ein Array von DEVPROPCOMPKEY- Strukturen bereit, die die Eigenschaften angeben, die für Objekte im Resultset der Abfrage abgerufen werden sollen, wenn pCallback- aufgerufen wird, um die Abfrage über das Hinzufügen eines Objekts zu seinem Resultset zu benachrichtigen.
Wenn DevQueryFlagUpdateResults- in QueryFlags-angegeben wurde, wird die Abfrage benachrichtigt, wenn sich der Wert dieser Eigenschaften für ein Objekt im Resultset der Abfrage ändert.

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

Wenn cRequestedProperties 0 ist, muss dies NULL sein.

[in] cFilterExpressionCount

Die Anzahl der in pFilterbereitgestellten DEVPROP_FILTER_EXPRESSION Strukturen.

[in, optional] pFilter

Stellt optional ein Array von DEVPROP_FILTER_EXPRESSION Strukturen bereit, die Filterkriterien für die Objekte angeben, die Teil des Resultsets der Abfrage sein sollen. Wenn cFilterExpressionCount 0 ist, muss dies NULL sein.

[out] pcObjectCount

Die Anzahl der in ppObjects zurückgegebenen DEV_OBJECT Strukturen.

[out] ppObjects

Zeiger, der das neu zugeordnete Array von DEV_OBJECT Ergebnissen empfängt. Aufrufer müssen den Zeiger mit DevFreeObjectsfreigeben. Wenn keine Objekte aufgezählt werden, wird NULL zurückgegeben.

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 zum synchronen Aufzählen von Objekten beim Abrufen ihrer Eigenschaften. Das Array der zurückgegebenen Objekte muss mit DevFreeObjectsfreigegeben werden. Wenn für ein Objekt, das den Filterkriterien entspricht, keine angeforderte Eigenschaft vorhanden ist, weist der DEVPROPERTY Eintrag in der DEV_OBJECT für diese Eigenschaft einen Typ von DEVPROP_TYPE_EMPTYauf.

Bevor Sie diese Funktion verwenden, überlegen Sie, wie viele Daten im Array zurückgegeben werden können und wie lange der Aufruf blockiert werden kann. Es kann besser sein, die DevCreateObjectQuery-Funktion zu verwenden, wodurch die Daten asynchron genutzt werden können.

Beispiel

Im folgenden Beispiel wird die Verwendung von DevGetObjects- veranschaulicht, um den Satz von DEV_OBJECT abzurufen, der einem Satz von DEVPROP_FILTER_EXPRESSION Strukturen entspricht.

void
Example1()
{
    HRESULT hr = S_OK;
    ULONG ObjectCount = 0;
    const DEV_OBJECT* ObjectList = NULL;
    DEVPROP_BOOLEAN DevPropTrue = DEVPROP_TRUE;
    DEVPROPCOMPKEY RequestedProperties[] =
    {
        { DEVPKEY_Device_InstanceId, DEVPROP_STORE_SYSTEM, NULL }
    };
    DEVPROP_FILTER_EXPRESSION ObjectFilter[] =
    {
        {
            DEVPROP_OPERATOR_AND_OPEN, {0}
        },
        {
            DEVPROP_OPERATOR_EQUALS,
            {
                { DEVPKEY_DeviceInterface_Enabled, DEVPROP_STORE_SYSTEM, NULL },
                DEVPROP_TYPE_BOOLEAN,
                sizeof(DevPropTrue),
                (void*)&DevPropTrue
            }
        },
        {
            DEVPROP_OPERATOR_OR_OPEN, {0}
        },
        {
            DEVPROP_OPERATOR_EQUALS,
            {
                { DEVPKEY_DeviceInterface_ClassGuid, DEVPROP_STORE_SYSTEM, NULL },
                DEVPROP_TYPE_GUID,
                sizeof(GUID),
                (void*)&GUID_DEVINTERFACE_MOUSE
            }
        },
        {
            DEVPROP_OPERATOR_EQUALS,
            {
                { DEVPKEY_DeviceInterface_ClassGuid, DEVPROP_STORE_SYSTEM, NULL },
                DEVPROP_TYPE_GUID,
                sizeof(GUID),
                (void*)&GUID_DEVINTERFACE_KEYBOARD
            }
        },
        {
            DEVPROP_OPERATOR_OR_CLOSE, {0}
        },
        {
            DEVPROP_OPERATOR_AND_CLOSE, {0}
        }
    };

    hr = DevGetObjects(DevObjectTypeDeviceInterface,
                       DevQueryFlagNone,
                       RTL_NUMBER_OF(RequestedProperties),
                       RequestedProperties,
                       RTL_NUMBER_OF(ObjectFilter),
                       ObjectFilter,
                       &ObjectCount,
                       &ObjectList);

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

    for (ULONG i = 0; i < ObjectCount; i++)
    {
        wprintf(L"Retrieved object '%ws'\n",
                ObjectList[i].pszObjectId);
    }

  exit:

    if (ObjectList != NULL)
    {
        DevFreeObjects(ObjectCount, ObjectList);
    }

    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

Siehe auch

DevCreateObjectQuery-