Metode IWDFUnifiedPropertyStore::GetPropertyData (wudfddi.h)

Artikel
03/01/2024

[Peringatan: UMDF 2 adalah versi terbaru UMDF dan pengganti UMDF 1. Semua driver UMDF baru harus ditulis menggunakan UMDF 2. Tidak ada fitur baru yang ditambahkan ke UMDF 1 dan ada dukungan terbatas untuk UMDF 1 pada versi Windows 10 yang lebih baru. Driver Universal Windows harus menggunakan UMDF 2. Untuk informasi selengkapnya, lihat Mulai menggunakan UMDF.]

Metode GetPropertyData mengambil pengaturan saat ini untuk properti perangkat.

Sintaks

HRESULT GetPropertyData(
  [in]            const DEVPROPKEY *PropertyKey,
  [in]            LCID             Lcid,
  [in]            ULONG            Flags,
  [in]            ULONG            PropertyDataSize,
  [out, optional] PVOID            PropertyData,
  [out]           ULONG            *PropertyDataRequiredSize,
  [out]           DEVPROPTYPE      *PropertyType
);

Parameter

[in] PropertyKey

Penunjuk ke struktur DEVPROPKEY yang menentukan kunci properti perangkat.

[in] Lcid

Menentukan pengidentifikasi lokal. Atur parameter ini ke nilai LCID khusus bahasa atau ke LOCALE_NEUTRAL. LOCALE_NEUTRAL LCID menentukan bahwa properti netral bahasa (yaitu, tidak khusus untuk bahasa apa pun). Jangan atur parameter ini ke LOCALE_SYSTEM_DEFAULT atau LOCALE_USER_DEFAULT. Untuk informasi selengkapnya tentang nilai LCID khusus bahasa, lihat Struktur LCID.

[in] Flags

Dicadangkan untuk penggunaan sistem. Driver harus mengatur nilai ini ke 0.

[in] PropertyDataSize

Ukuran, dalam byte, dari buffer yang dituju propertyData .

[out, optional] PropertyData

Penunjuk ke data properti perangkat.

[out] PropertyDataRequiredSize

Penunjuk ke ULONG untuk menerima ukuran informasi properti yang dikembalikan di PropertyData.

[out] PropertyType

Penunjuk ke nilai DEVPROPTYPE . Jika GetPropertyData berhasil diselesaikan, metode menggunakan PropertyType untuk menyediakan jenis data yang dikembalikan dalam buffer PropertyData .

Mengembalikan nilai

GetPropertyData mengembalikan S_OK jika operasi berhasil. Jika tidak, metode mungkin mengembalikan nilai berikut.

Menampilkan kode	Deskripsi
E_OUTOFMEMORY	Upaya kerangka kerja untuk mengalokasikan memori gagal.
HRESULT_FROM_NT(STATUS_BUFFER_TOO_SMALL)	Parameter PropertyDataRequiredSize berisi ukuran buffer yang diperlukan.
HRESULT_FROM_WIN32 (ERROR_INVALID_PARAMETER)	Jika driver menentukan WdfPropertyStoreRootClassDeviceInterfaceKey, antarmuka yang diminta harus merupakan salah satu driver UMDF yang sebelumnya terdaftar.
HRESULT_FROM_WIN32 (STATUS_NOT_SUPPORTED)	Driver dapat meminta data properti antarmuka perangkat hanya dimulai dengan Windows 8.

Metode ini mungkin mengembalikan salah satu nilai lain yang dikandung Winerror.h .

Keterangan

Driver berbasis kerangka kerja menggunakan metode GetPropertyData untuk mengambil properti perangkat yang didefinisikan sebagai bagian dari model properti perangkat terpadu.

Secara khusus, Anda dapat menggunakan metode ini untuk mengambil kunci perangkat keras perangkat atau instans kelas antarmuka perangkat. Saat Anda memanggil IWDFUnifiedPropertyStoreFactory::RetrieveUnifiedDevicePropertyStore, atur anggota RootClass parameter RootSpecifier ke WdfPropertyStoreRootClassHardwareKey atau WdfPropertyStoreRootClassDeviceInterfaceKey.

Jika Anda menentukan WdfPropertyStoreRootClassHardwareKey, maka ketika Anda memanggil GetPropertyData, Anda harus memberikan nilai DEVPROPKEY kustom dalam parameter PropertyKey , dan bukan kunci yang ditentukan PnP. Nilai harus telah ditetapkan sebelumnya dengan memanggil SetPropertyData, fungsi properti perangkat SetupDI, atau dengan menggunakan arahan INF AddProperty.

Untuk informasi selengkapnya tentang properti perangkat, lihat Properti Perangkat.

Untuk informasi selengkapnya tentang mengakses registri, lihat Menggunakan Registri di Driver berbasis UMDF.

Contoh

Untuk properti ukuran variabel, driver harus membuat dua pass untuk mengambil data properti. Pertama, driver harus melewati buffer NULL di parameter PropertyData , dan mengatur PropertyDataSize ke 0. Kemudian, driver kemudian harus mengalokasikan buffer berdasarkan PropertyDataRequiredSize yang dikembalikan dan memanggil GetPropertyData lagi, melewati buffer yang dialokasikan.

Contoh berikut menunjukkan pola ini.

HRESULT
GetFriendlyName(
    _In_ IWDFUnifiedPropertyStore * pUnifiedPropertyStore
    )
{
    HRESULT hr = S_OK;
    DEVPROPTYPE type;
    ULONG requiredSize;
    BYTE * friendlyNameBuffer = NULL;
    ULONG friendlyNameBufferSize;

    hr = pUnifiedPropertyStore->GetPropertyData(
            &DEVPKEY_Device_FriendlyName,
            0, //Lcid
            0, //Flags
            0, //BufferSize
            NULL, //Buffer
            &requiredSize,
            &type
            );

    if (HRESULT_CODE(hr) != ERROR_INSUFFICIENT_BUFFER)
    {
        TraceEvents(
            TRACE_LEVEL_ERROR, 
            TEST_TRACE_DEVICE, 
            "GetPropertyData failed: hr = %!HRESULT!",
            hr
            );
        goto exit;
    }

    friendlyNameBufferSize = requiredSize;
    friendlyNameBuffer = new BYTE[requiredSize];
    if (NULL == friendlyNameBuffer)
    {
        hr = E_OUTOFMEMORY;
        TraceEvents(
            TRACE_LEVEL_ERROR, 
            TEST_TRACE_DEVICE, 
            "Out of memory while allocating property data buffer returning:”
            “ %!HRESULT!",
            hr
            );
        goto exit;
    }
    
    hr = pUnifiedPropertyStore->GetPropertyData(
            &DEVPKEY_Device_FriendlyName,
            0, //Lcid
            0, //Flags
            friendlyNameBufferSize,
            friendlyNameBuffer,
            &requiredSize,
            &type
            );

    if (FAILED(hr))
    {
        TraceEvents(
            TRACE_LEVEL_ERROR, 
            TEST_TRACE_DEVICE, 
            "GetPropertyData failed: hr = %!HRESULT!",
            hr
            );
        goto exit;
    }
    
    if (type != DEVPROP_TYPE_STRING)
    {
        TraceEvents(
            TRACE_LEVEL_ERROR, 
            TEST_TRACE_DEVICE, 
            "Expected type %d, actual type: %d",
            DEVPROP_TYPE_STRING,
            type
            );
        hr = E_UNEXPECTED;
        goto exit;
    }

exit:
    delete [] friendlyNameBuffer;
    friendlyNameBuffer = NULL;

    return hr;
}

Persyaratan

Persyaratan	Nilai
Akhir dukungan	Tidak tersedia di UMDF 2.0 dan yang lebih baru.
Target Platform	Desktop
Versi UMDF minimum	1.11
Header	wudfddi.h
DLL	WUDFx.dll