Metode IWDFUnifiedPropertyStore::SetPropertyData (wudfddi.h)

Artikel
08/08/2023

[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 SetPropertyData memodifikasi pengaturan properti perangkat saat ini.

Sintaks

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

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. Driver harus mengatur nilai ini ke 0.

[in] PropertyType

Penunjuk ke nilai DEVPROPTYPE yang menentukan jenis data yang disediakan dalam buffer PropertyData .

[in] PropertyDataSize

Ukuran, dalam byte, dari buffer yang dituju propertyData .

[in, optional] PropertyData

Penunjuk ke data properti perangkat. Atur parameter ini ke NULL untuk menghapus properti yang ditentukan.

Nilai kembali

SetPropertyData 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_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 mengubah data properti antarmuka perangkat hanya dimulai dengan Windows 8.

Metode ini mungkin mengembalikan nilai yang diketik HRESULT yang sesuai dengan salah satu nilai lain yang dikandung Winerror.h .

Keterangan

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

Secara khusus, Anda dapat menggunakan metode ini untuk memodifikasi 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 SetPropertyData, 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.

Jika driver menentukan WdfPropertyStoreRootClassDeviceInterfaceKey, antarmuka yang diminta harus merupakan salah satu driver UMDF yang sebelumnya terdaftar pada runtime.

Jika driver mendaftarkan antarmuka dalam file INF-nya, driver juga harus mengatur properti terkait di INF.

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

Contoh

HRESULT
SetFriendlyName(
    _In_ IWDFUnifiedPropertyStore * pUnifiedPropertyStore
    )
{
    HRESULT hr = S_OK;
    WCHAR friendlyName[] = L"UMDF OSR USB Fx2 Test Device";

    hr = pUnifiedPropertyStore->SetPropertyData(
            &DEVPKEY_Device_FriendlyName,
            0, //Lcid
            0, //Flags
            DEVPROP_TYPE_STRING, //Type
            sizeof(friendlyName),
            friendlyName
            );

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

exit:
    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