Bagikan melalui

Fungsi DevCreateObjectQuery (devquery.h)

Membuat kueri perangkat untuk mengambil properti berdasarkan parameter kueri yang ditentukan.

Sintaksis

HRESULT DevCreateObjectQuery(
  [in]           DEV_OBJECT_TYPE                 ObjectType,
  [in]           ULONG                           QueryFlags,
  [in]           ULONG                           cRequestedProperties,
  [in]           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

Nilai dari enumerasi DEV_OBJECT_TYPE yang menentukan tipe objek yang harus dioperasikan kueri ini.

[in] QueryFlags

Kombinasi nilai DEV_QUERY_FLAGS yang digabungkan dengan menggunakan operasi OR bitwise.

[in] cRequestedProperties

Jumlah struktur DEVPROPCOMPKEY yang disediakan dalam pRequestedProperties. Jika DevQueryFlagAllProperties ditentukan, ini harus diatur ke 0.

[in] pRequestedProperties

Secara opsional menyediakan array struktur DEVPROPCOMPKEY yang menentukan properti yang harus diambil untuk objek dalam hasil kueri yang ditetapkan ketika pCallback dipanggil untuk memberi tahu kueri penambahan objek ke tataan hasilnya.
Jika DevQueryFlagUpdateResults ditentukan dalam QueryFlags, kueri akan diberi tahu jika nilai salah satu properti ini berubah untuk objek apa pun dalam kumpulan hasil kueri.

Bidang LocaleName dari struktur DEVPROPCOMPKEY diabaikan dan harus diatur ke NULL.

Jika cRequestedProperties adalah 0, ini harus NULL.

[in] cFilterExpressionCount

Jumlah struktur DEVPROP_FILTER_EXPRESSION yang disediakan dalam pFilter.

[in, optional] pFilter

Secara opsional menyediakan array struktur DEVPROP_FILTER_EXPRESSION yang menentukan kriteria filter untuk objek apa yang harus menjadi bagian dari tataan hasil kueri. Jika cFilterExpressionCount adalah 0, ini harus NULL.

[in] pCallback

Fungsi panggilan balik PDEV_QUERY_RESULT_CALLBACK yang menghasilkan kueri ini harus dikirim.

[in, optional] pContext

Konteks yang disediakan pemanggil. Nilai ini diteruskan ke fungsi panggilan balik yang tidak dimodifikasi.

[out] phDevQuery

Penunjuk yang menerima handel yang mewakili kueri. Jika DevQueryFlagsUpdateResults ditentukan, maka kueri akan menerima pembaruan hingga handel ditutup. Panggil DevCloseObjectQuery untuk menutup handel ini untuk menghentikan kueri.

Mengembalikan nilai

S_OK dikembalikan jika kueri berhasil dibuat; jika tidak, nilai kesalahan yang sesuai.

Komentar

Gunakan DevCreateObjectQuery untuk mengkueri data tentang DEV_OBJECT_TYPEyang ditentukan. Objek diwakili oleh jenis objek, identitas string, dan penyimpanan properti pasangan kunci/nilai. Setiap kueri memiliki tataan hasil yang terkait dengannya. Objek ditambahkan, diperbarui, atau dihapus dari tataan hasil berdasarkan status sistem dan perubahan dan fungsi panggilan balik terkait akan diberi tahu. Setiap panggilan ke fungsi panggilan balik mewakili rekam jepret nilai properti pada saat panggilan balik dipanggil. Hanya objek yang cocok dengan kriteria yang dinyatakan dalam ekspresi pFilter yang dikembalikan ke pemanggil. Selain pemanggilan panggilan balik yang memperbarui tataan hasil, ada juga panggilan balik perubahan status yang memberi tahu klien tentang perubahan pada status kueri.

Secara default, kueri tidak menerima pembaruan setelah status sistem saat ini telah diproses. Setelah semua objek yang cocok ditambahkan ke tataan hasil, kueri memasuki status DevQueryStateEnumCompleted dan tidak ada panggilan balik lebih lanjut yang akan dilakukan. Saat kueri mendaftar untuk pembaruan dengan menentukan bendera DevQueryFlagUpdateResults, tataan hasilnya akan terus diperbarui, dan panggilan balik terkait diberi tahu, setelah kueri memasuki status DevQueryStateEnumCompleted saat perubahan dalam sistem terjadi yang menambahkan atau menghapus objek berdasarkan ekspresi filter yang cocok.

Kueri mungkin dibatalkan. Ini terjadi ketika kesalahan internal terjadi yang membuatnya tidak mungkin untuk mengomunikasikan pemberitahuan kepada klien. Misalnya, ini dapat terjadi ketika sistem berada dalam kondisi di luar memori. Ketika ini terjadi, tataan hasil penelepon tidak lagi mencerminkan representasi benar dari status kueri. Pemanggil akan menerima panggilan balik DevQueryStateAborted. Tidak ada panggilan balik lebih lanjut yang akan diterima. Pemanggil harus menutup kueri dan membuat kueri baru untuk memulihkan dari kondisi ini.

Contoh

Dalam contoh berikut, metode PDEV_QUERY_RESULT_CALLBACK diimplementasikan untuk mencetak pesan status saat status kueri berubah, ketika item telah ditambahkan ke, diperbarui, atau dihapus dari hasil kueri. Selanjutnya, skenario kueri sederhana diterapkan di mana DevCreateObjectQuery dipanggil dengan array DEVPROPCOMPKEY dan DEVPROP_FILTER_EXPRESSION untuk mengkueri objek DevObjectTypeDevice dengan properti DEVPKEY_Device_ClassGuid dengan nilai GUID_DEVCLASS_NET.

void WINAPI
Example1Callback(
    HDEVQUERY hDevQuery,
    PVOID pContext,
    const DEV_QUERY_RESULT_ACTION_DATA *pActionData
    )
{
    const DEVPROPERTY* NameProperty = NULL;

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

        NameProperty = DevFindProperty(&DEVPKEY_NAME,
                                       DEVPROP_STORE_SYSTEM,
                                       NULL,
                                       pActionData->Data.DeviceObject.cPropertyCount,
                                       pActionData->Data.DeviceObject.pProperties);

        if ((NameProperty == NULL) ||
            (NameProperty->Type == DEVPROP_TYPE_EMPTY) ||
            (NameProperty->Buffer == NULL))
        {
            wprintf(L"Object '%ws' had no name property.\n",
                    pActionData->Data.DeviceObject.pszObjectId);
        }
        else if ((NameProperty->Type != DEVPROP_TYPE_STRING) ||
                 (NameProperty->BufferSize < sizeof(WCHAR)))
        {
            wprintf(L"Object '%ws' had a corrupted name property.\n",
                    pActionData->Data.DeviceObject.pszObjectId);
        }
        else
        {
            wprintf(L"Object '%ws' has name '%ws'.\n",
                    pActionData->Data.DeviceObject.pszObjectId,
                    (PWSTR)NameProperty->Buffer);
        }

        break;

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

        NameProperty = DevFindProperty(&DEVPKEY_NAME,
                                       DEVPROP_STORE_SYSTEM,
                                       NULL,
                                       pActionData->Data.DeviceObject.cPropertyCount,
                                       pActionData->Data.DeviceObject.pProperties);

        if ((NameProperty == NULL) ||
            (NameProperty->Type == DEVPROP_TYPE_EMPTY) ||
            (NameProperty->Buffer == NULL))
        {
            wprintf(L"Object '%ws' had no name property.\n",
                    pActionData->Data.DeviceObject.pszObjectId);
        }
        else if ((NameProperty->Type != DEVPROP_TYPE_STRING) ||
                 (NameProperty->BufferSize < sizeof(WCHAR)))
        {
            wprintf(L"Object '%ws' had a corrupted name property.\n",
                    pActionData->Data.DeviceObject.pszObjectId);
        }
        else
        {
            wprintf(L"Object '%ws' has name '%ws'.\n",
                    pActionData->Data.DeviceObject.pszObjectId,
                    (PWSTR)NameProperty->Buffer);
        }

        break;

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

void
Example1()
{
    DEVPROPCOMPKEY RequestedProperties[] =
    {
        { DEVPKEY_NAME, DEVPROP_STORE_SYSTEM, NULL }
    };
    DEVPROP_FILTER_EXPRESSION ObjectFilter[] =
    {
        {
            DEVPROP_OPERATOR_EQUALS,
            {
                { DEVPKEY_Device_ClassGuid, DEVPROP_STORE_SYSTEM, NULL },
                DEVPROP_TYPE_GUID,
                sizeof(GUID),
                (void*)&GUID_DEVCLASS_NET
            }
        }
    };

    HDEVQUERY hDevQuery = NULL;
    HRESULT hr = DevCreateObjectQuery(DevObjectTypeDevice,
                                      DevQueryFlagUpdateResults,
                                      RTL_NUMBER_OF(RequestedProperties),
                                      RequestedProperties,
                                      RTL_NUMBER_OF(ObjectFilter),
                                      ObjectFilter,
                                      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;
}

Dalam contoh berikut, parameter pContext yang ditentukan pemanggil opsional digunakan untuk meneruskan handel peristiwa ke metode PDEV_QUERY_RESULT_CALLBACK. Ketika panggilan balik mendeteksi bahwa status kueri DevQueryStateAborted, peristiwa tersebut disinyalir untuk memberi tahu pemanggil bahwa ia harus membuang kueri yang ada dan membuat ulang kueri baru.

typedef struct _MY_QUERY_CONTEXT {
    HANDLE CompletionEvent;
    HRESULT hr;
} MY_QUERY_CONTEXT, *PMY_QUERY_CONTEXT;

void WINAPI
Example2Callback(
    HDEVQUERY hDevQuery,
    PVOID pContext,
    const DEV_QUERY_RESULT_ACTION_DATA *pActionData
    )
{
    PMY_QUERY_CONTEXT QueryContext = (PMY_QUERY_CONTEXT)pContext;
    const DEVPROPERTY* DevProperty = NULL;

    UNREFERENCED_PARAMETER(hDevQuery);

    switch (pActionData->Action)
    {
    case DevQueryResultStateChange:
        if (pActionData->Data.State == DevQueryStateEnumCompleted)
        {
            wprintf(L"Enumeration of current system state complete.\n");
            // The query did not use DevQueryFlagUpdateResults so the result set
            // is now complete. Signal the caller to stop waiting.
            if (!SetEvent(QueryContext->CompletionEvent))
            {
                wprintf(L"Failed to signal completion event. Err = 0x%08x\n",
                        GetLastError());
            }
        }
        else if (pActionData->Data.State == DevQueryStateAborted)
        {
            wprintf(L"Query has aborted. No further results will be received.\n");
            QueryContext->hr = E_FAIL;
            // Communicate back to the creator of the query that it has aborted
            // so it can handle that appropriately, such as by recreating the
            // query.
            if (!SetEvent(QueryContext->CompletionEvent))
            {
                wprintf(L"Failed to signal completion event. Err = 0x%08x\n",
                        GetLastError());
            }
        }
        break;

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

        DevProperty = DevFindProperty(&DEVPKEY_Device_InstanceId,
                                      DEVPROP_STORE_SYSTEM,
                                      NULL,
                                      pActionData->Data.DeviceObject.cPropertyCount,
                                      pActionData->Data.DeviceObject.pProperties);

        if ((DevProperty == NULL) ||
            (DevProperty->Type == DEVPROP_TYPE_EMPTY) ||
            (DevProperty->Buffer == NULL))
        {
            wprintf(L"Object '%ws' had no instance ID property.\n",
                    pActionData->Data.DeviceObject.pszObjectId);
        }
        else if ((DevProperty->Type != DEVPROP_TYPE_STRING) ||
                 (DevProperty->BufferSize < sizeof(WCHAR)))
        {
            wprintf(L"Object '%ws' had a corrupted instance ID property.\n",
                    pActionData->Data.DeviceObject.pszObjectId);
        }
        else
        {
            wprintf(L"Object '%ws' was exposed by instance ID '%ws'.\n",
                    pActionData->Data.DeviceObject.pszObjectId,
                    (PWSTR)DevProperty->Buffer);
        }

        break;

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

        DevProperty = DevFindProperty(&DEVPKEY_Device_InstanceId,
                                      DEVPROP_STORE_SYSTEM,
                                      NULL,
                                      pActionData->Data.DeviceObject.cPropertyCount,
                                      pActionData->Data.DeviceObject.pProperties);

        if ((DevProperty == NULL) ||
            (DevProperty->Type == DEVPROP_TYPE_EMPTY) ||
            (DevProperty->Buffer == NULL))
        {
            wprintf(L"Object '%ws' had no instance ID property.\n",
                    pActionData->Data.DeviceObject.pszObjectId);
        }
        else if ((DevProperty->Type != DEVPROP_TYPE_STRING) ||
                 (DevProperty->BufferSize < sizeof(WCHAR)))
        {
            wprintf(L"Object '%ws' had a corrupted instance ID property.\n",
                    pActionData->Data.DeviceObject.pszObjectId);
        }
        else
        {
            wprintf(L"Object '%ws' was exposed by instance ID '%ws'.\n",
                    pActionData->Data.DeviceObject.pszObjectId,
                    (PWSTR)DevProperty->Buffer);
        }

        break;

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

void
Example2()
{
    HRESULT hr = S_OK;
    MY_QUERY_CONTEXT QueryContext = {0};
    HDEVQUERY hDevQuery = 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}
        }
    };

    QueryContext.CompletionEvent = CreateEvent(NULL, FALSE, FALSE, NULL);

    if (!QueryContext.CompletionEvent)
    {
        wprintf(L"Failed to create event. Error = 0x%08x\n",
                GetLastError());
        goto exit;
    }

    hr = DevCreateObjectQuery(DevObjectTypeDeviceInterface,
                              DevQueryFlagNone,
                              RTL_NUMBER_OF(RequestedProperties),
                              RequestedProperties,
                              RTL_NUMBER_OF(ObjectFilter),
                              ObjectFilter,
                              Example2Callback,
                              &QueryContext,
                              &hDevQuery);

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

    switch (WaitForSingleObject(QueryContext.CompletionEvent, INFINITE))
    {
    case WAIT_OBJECT_0:
        if (SUCCEEDED(QueryContext.hr))
        {
            wprintf(L"Successfully enumerated results.\n");
        }
        else
        {
            wprintf(L"Failed to Successfully enumerate results. hr = 0x%08x\n",
                    QueryContext.hr);
        }
        break;

    default:
        wprintf(L"An error waiting occurred.\n");
        break;
    }

  exit:

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

    if (QueryContext.CompletionEvent != NULL)
    {
        CloseHandle(QueryContext.CompletionEvent);
    }

    return;
}

Persyaratan

Syarat Nilai
klien minimum yang didukung Windows 10 versi 1809
server minimum yang didukung Windows Server 2019
Header devquery.h
Pustaka onecore.lib
DLL Cfgmgr32.dll

Lihat juga

DevCreateObjectQueryEx

  • Last updated on