Fungsi DevCreateObjectQueryFromId (devquery.h)

Membuat kueri perangkat untuk mengambil properti berdasarkan parameter kueri dan ID objek yang ditentukan.

Sintaksis

HRESULT DevCreateObjectQueryFromId(
  [in]           DEV_OBJECT_TYPE                 ObjectType,
  [in]           PCWSTR                          pszObjectId,
  [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

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

[in] pszObjectId

Pengidentifikasi string untuk objek yang harus dioperasikan kueri.

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

Ketika klien ingin mengambil data tentang objek tertentu yang diberikan identitasnya, gunakan fungsi ini daripada DevCreateObjectQuery dengan filter. Fungsi ini lebih efisien.

Untuk informasi selengkapnya, lihat bagian keterangan DevCreateObjectQuery, yang juga berlaku untuk fungsi 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 DevCreateObjectQueryFromId dipanggil dengan ID objek yang ditentukan oleh variabel InterfacePath.

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(PCWSTR InterfacePath)
{
    DEVPROPCOMPKEY RequestedProperties[] =
    {
        { DEVPKEY_DeviceInterface_Enabled, DEVPROP_STORE_SYSTEM, NULL },
        { DEVPKEY_DeviceInterface_FriendlyName, DEVPROP_STORE_SYSTEM, NULL }
    };

    HDEVQUERY hDevQuery = NULL;
    HRESULT hr = DevCreateObjectQueryFromId(DevObjectTypeDeviceInterface,
                                            InterfacePath,
                                            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;
}

Persyaratan

Syarat	Nilai
klien minimum yang didukung	Windows 10 versi 1809
Header	devquery.h
Pustaka	Onecore.lib
DLL	Cfgmgr32.dll

Lihat juga

DevCreateObjectQuery