Fungsi DevGetObjectProperties (devquery.h)

Mengambil sekumpulan properti secara sinkron untuk objek tertentu

Sintaksis

HRESULT DevGetObjectProperties(
  [in]  DEV_OBJECT_TYPE      ObjectType,
  [in]  PCWSTR               pszObjectId,
  [in]  ULONG                QueryFlags,
  [in]  ULONG                cRequestedProperties,
  [in]  const DEVPROPCOMPKEY *pRequestedProperties,
  [out] PULONG               pcPropertyCount,
  [out] const DEVPROPERTY    **ppProperties
);

Parameter

[in] ObjectType

Nilai dari DEV_OBJECT_TYPE yang menentukan jenis objek yang propertinya akan diambil.

[in] pszObjectId

Identitas objek tempat properti akan diambil.

[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] pRequestedProperties

Menyediakan array struktur DEVPROPCOMPKEY yang menentukan properti yang harus diambil untuk objek yang ditentukan.

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

Jika cRequestedProperties adalah 0, ini harus NULL.

[out] pcPropertyCount

Jumlah struktur DEVPROPERTY yang dikembalikan dalamppProperties .

[out] ppProperties

Pointer yang menerima array DEVPROPERTY yang baru dialokasikan hasil. Penelepon harus membebaskan pointer menggunakan DevFreeObjectProperties.

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 mengambil sekumpulan properti secara sinkron dari objek yang diberikan jenis dan identitasnya. Array properti yang dikembalikan harus dibebaskan menggunakan DevFreeObjectProperties. Jika properti yang diminta tidak ada, ppProperties masih akan berisi entri untuk properti tersebut tetapi entri akan memiliki jenis DEVPROP_TYPE_EMPTY.

Contoh

Contoh berikut menunjukkan panggilan DevGetObjectProperties untuk mengambil sekumpulan properti yang diminta lalu memanggil DevFindProperty untuk menemukan properti tertentu dalam array struktur DEVPROPERTY.

void
Example1(PCWSTR DeviceInstancePath)
{
    HRESULT hr = S_OK;
    const DEVPROPERTY* TempProperty = NULL;
    ULONG PropertyCount = 0;
    const DEVPROPERTY* PropertyList = NULL;
    DEVPROPCOMPKEY RequestedProperties[] =
    {
        { DEVPKEY_Device_HardwareIds, DEVPROP_STORE_SYSTEM, NULL },
        { DEVPKEY_Device_CompatibleIds, DEVPROP_STORE_SYSTEM, NULL }
    };

    hr = DevGetObjectProperties(DevObjectTypeDevice,
                                DeviceInstancePath,
                                DevQueryFlagNone,
                                RTL_NUMBER_OF(RequestedProperties),
                                RequestedProperties,
                                &PropertyCount,
                                &PropertyList);

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

    wprintf(L"Hardware IDs:\n");
    TempProperty = DevFindProperty(&DEVPKEY_Device_HardwareIds,
                                   DEVPROP_STORE_SYSTEM,
                                   NULL,
                                   PropertyCount,
                                   PropertyList);

    if ((TempProperty == NULL) ||
        (TempProperty->Type == DEVPROP_TYPE_EMPTY) ||
        (TempProperty->Buffer == NULL))
    {
        wprintf(L"<none>\n");
    }
    else if ((TempProperty->Type != DEVPROP_TYPE_STRING_LIST) ||
             (TempProperty->BufferSize < sizeof(WCHAR)))
    {
        wprintf(L"Device '%ws' has a corrupted Hardware IDs property.\n",
                DeviceInstancePath);
    }
    else
    {
        for (PCWSTR CurrentId = (PCWSTR)TempProperty->Buffer;
             *CurrentId != L'\0';
             CurrentId += wcslen(CurrentId) + 1)
        {
            wprintf(L"%ws\n", CurrentId);
        }
    }

    wprintf(L"\nCompatible IDs:\n");
    TempProperty = DevFindProperty(&DEVPKEY_Device_CompatibleIds,
                                   DEVPROP_STORE_SYSTEM,
                                   NULL,
                                   PropertyCount,
                                   PropertyList);

    if ((TempProperty == NULL) ||
        (TempProperty->Type == DEVPROP_TYPE_EMPTY) ||
        (TempProperty->Buffer == NULL))
    {
        wprintf(L"<none>\n");
    }
    else if ((TempProperty->Type != DEVPROP_TYPE_STRING_LIST) ||
             (TempProperty->BufferSize < sizeof(WCHAR)))
    {
        wprintf(L"Device '%ws' has a corrupted Compatible IDs property.\n",
                DeviceInstancePath);
    }
    else
    {
        for (PCWSTR CurrentId = (PCWSTR)TempProperty->Buffer;
             *CurrentId != L'\0';
             CurrentId += wcslen(CurrentId) + 1)
        {
            wprintf(L"%ws\n", CurrentId);
        }
    }

  exit:

    if (PropertyList != NULL)
    {
        DevFreeObjectProperties(PropertyCount, PropertyList);
    }

    return;
}

Persyaratan