Fungsi DevGetObjects (devquery.h)

Secara sinkron mengambil sekumpulan struktur DEV_OBJECT berdasarkan properti dan kriteria filter yang diminta yang disediakan.

Sintaksis

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

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. Tidak valid untuk meneruskan DevQueryFlagUpdateResults atau DevQueryFlagAsyncClose ke fungsi ini.

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

[out] pcObjectCount

Jumlah struktur DEV_OBJECT yang dikembalikan dalam ppObjects.

[out] ppObjects

Pointer yang menerima array hasil DEV_OBJECT yang baru dialokasikan. Penelepon harus membebaskan pointer menggunakan DevFreeObjects. Jika tidak ada objek yang dijumlahkan, NULL akan dikembalikan.

Mengembalikan nilai

S_OK dikembalikan jika fungsi berhasil mengevaluasi kriteria pencarian dan mengembalikan objek yang cocok; jika tidak, nilai kesalahan yang sesuai.

Komentar

Fungsi ini adalah cara yang efisien untuk menghitung objek secara sinkron sambil mengambil propertinya. Array objek yang dikembalikan harus dibebaskan menggunakan DevFreeObjects. Jika properti yang diminta tidak ada untuk objek yang memenuhi kriteria filter, maka entri DEVPROPERTY di DEV_OBJECT untuk properti tersebut akan memiliki jenis DEVPROP_TYPE_EMPTY.

Sebelum menggunakan fungsi ini, pertimbangkan berapa banyak data yang dapat dikembalikan dalam array dan berapa lama panggilan dapat diblokir. Mungkin lebih baik menggunakan fungsi DevCreateObjectQuery, yang memungkinkan data dikonsumsi secara sepotong dan asinkron.

Contoh

Contoh berikut menunjukkan penggunaan DevGetObjects untuk mengambil kumpulan DEV_OBJECT yang cocok dengan sekumpulan struktur DEVPROP_FILTER_EXPRESSION.

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

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