DevCreateObjectQueryFromIds-Funktion (devquery.h)

Erstellt eine Geräteabfrage zum Abrufen von Eigenschaften basierend auf den angegebenen Abfrageparametern und einer Liste von Objekt-IDs.

Syntax

HRESULT DevCreateObjectQueryFromIds(
  [in]           DEV_OBJECT_TYPE                 ObjectType,
  [in]           PCZZWSTR                        pszzObjectIds,
  [in]           ULONG                           QueryFlags,
  [in]           ULONG                           cRequestedProperties,
  [in, optional] const DEVPROPCOMPKEY            *pRequestedProperties,
  [in]           ULONG                           cFilterExpressionCount,
  [in, optional] const DEVPROP_FILTER_EXPRESSION *pFilter,
  [in]           PDEV_QUERY_RESULT_CALLBACK      pCallback,
  [in, optional] PVOID                           pContext,
  [out]          PHDEVQUERY                      phDevQuery
);

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] pszzObjectIds

Eine Multi-sz-Liste mit Objektbezeichnern für Objekte, auf denen die Abfrage ausgeführt werden soll. Informationen zu Multi-sz-Zeichenfolgen finden Sie unter REG_MULTI_SZ.

[in] QueryFlags

Eine Kombination aus DEV_QUERY_FLAGS Werten, die mithilfe eines bitweisen OR-Vorgangs kombiniert werden.

[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.

[in] pCallback

Eine PDEV_QUERY_RESULT_CALLBACK Rückruffunktion, an die Ergebnisse für diese Abfrage gesendet werden sollen.

[in, optional] pContext

Vom Aufrufer bereitgestellter Kontext. Dieser Wert wird an die Rückruffunktion übergeben, die nicht geändert wurde.

[out] phDevQuery

Zeiger, der das Handle empfängt, das die Abfrage darstellt. Wenn DevQueryFlagsUpdateResults- angegeben ist, empfängt die Abfrage Updates, bis das Handle geschlossen ist. Rufen Sie DevCloseObjectQuery auf, um dieses Handle zu schließen, um die Abfrage zu beenden.

Rückgabewert

S_OK wird zurückgegeben, wenn eine Abfrage erfolgreich erstellt wurde; andernfalls ein entsprechender Fehlerwert.

Bemerkungen

Wenn ein Client Daten zu einer bestimmten Gruppe von Objekten abrufen möchte, die ihrer Identität zugeordnet sind, verwenden Sie diese Funktion anstelle DevCreateObjectQuery- mit einem Filter. Diese Funktion ist effizienter.

Weitere Informationen finden Sie im Abschnitt "Hinweise" DevCreateObjectQuery, der auch für diese Funktion gilt.

Beispiel

Im folgenden Beispiel wird die PDEV_QUERY_RESULT_CALLBACK-Methode implementiert, um Statusmeldungen auszudrucken, wenn sich der Abfragestatus ändert, wenn Elemente dem Abfrageergebnis hinzugefügt, aktualisiert oder daraus entfernt wurden. Als Nächstes wird ein einfaches Abfrageszenario implementiert, in dem DevCreateObjectQueryFromIds- mit einer Multi-sz-Liste von Objekt-IDs aufgerufen wird, die an die Funktion im InterfacePaths--Argument übergeben werden.

void WINAPI
Example1Callback(
    HDEVQUERY hDevQuery,
    PVOID pContext,
    const DEV_QUERY_RESULT_ACTION_DATA *pActionData
    )
{
    UNREFERENCED_PARAMETER(hDevQuery);
    UNREFERENCED_PARAMETER(pContext);

    switch (pActionData->Action)
    {
    case DevQueryResultStateChange:
        if (pActionData->Data.State == DevQueryStateEnumCompleted)
        {
            wprintf(L"Enumeration of current system state complete.\n");
        }
        else if (pActionData->Data.State == DevQueryStateAborted)
        {
            wprintf(L"Query has aborted. No further results will be received.\n");
            // Communicate back to the creator of the query that it has aborted
            // so it can handle that appropriately, such as by recreating the
            // query
        }
        break;

    case DevQueryResultAdd:
        wprintf(L"Object '%ws' has been added to the result set.\n",
                pActionData->Data.DeviceObject.pszObjectId);
        break;

    case DevQueryResultUpdate:
        wprintf(L"Object '%ws' was updated.\n",
                pActionData->Data.DeviceObject.pszObjectId);
        break;

    case DevQueryResultRemove:
        wprintf(L"Object '%ws' has been removed from the result set.\n",
                pActionData->Data.DeviceObject.pszObjectId);
        break;
    }
}

void
Example1(PCZZWSTR InterfacePaths)
{
    DEVPROPCOMPKEY RequestedProperties[] =
    {
        { DEVPKEY_DeviceInterface_Enabled, DEVPROP_STORE_SYSTEM, NULL },
        { DEVPKEY_DeviceInterface_FriendlyName, DEVPROP_STORE_SYSTEM, NULL }
    };

    HDEVQUERY hDevQuery = NULL;
    HRESULT hr = DevCreateObjectQueryFromIds(DevObjectTypeDeviceInterface,
                                             InterfacePaths,
                                             DevQueryFlagUpdateResults,
                                             RTL_NUMBER_OF(RequestedProperties),
                                             RequestedProperties,
                                             0,
                                             NULL,
                                             Example1Callback,
                                             NULL,
                                             &hDevQuery);

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

    // do other work while the query monitors system state in the background

  exit:

    if (hDevQuery != NULL)
    {
        DevCloseObjectQuery(hDevQuery);
    }

    return;
}

Anforderungen

Siehe auch

DevCreateObjectQuery-