Fungsi DevCreateObjectQueryFromIds (devquery.h)

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

Sintaksis

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

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

[in] pszzObjectIds

Daftar multi-sz pengidentifikasi objek untuk objek yang harus dioperasikan kueri. Untuk informasi tentang string multi-sz, lihat REG_MULTI_SZ.

[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

Saat klien ingin mengambil data tentang sekumpulan 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 diimplementasikan di mana DevCreateObjectQueryFromIds dipanggil dengan daftar MULTI-sz ID objek yang diteruskan ke fungsi dalam argumen InterfacePaths.

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

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

DevCreateObjectQuery