Metodo IWDFUnifiedPropertyStore::SetPropertyData (wudfddi.h)

Articolo
02/07/2025

[Avviso: UMDF 2 è la versione più recente di UMDF e sostituisce UMDF 1. Tutti i nuovi driver UMDF devono essere scritti usando UMDF 2. Non vengono aggiunte nuove funzionalità a UMDF 1 ed è disponibile un supporto limitato per UMDF 1 nelle versioni più recenti di Windows 10. I driver di Windows universali devono usare UMDF 2. Per altre informazioni, vedi Introduzione a UMDF.]

Il metodo SetPropertyData modifica l'impostazione corrente di una proprietà del dispositivo.

Sintassi

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

Parametri

[in] PropertyKey

Puntatore a una struttura DEVPROPKEY che specifica la chiave della proprietà del dispositivo.

[in] Lcid

Specifica un identificatore delle impostazioni locali. Impostare questo parametro su un valore LCID specifico della lingua o su LOCALE_NEUTRAL. L'LOCALE_NEUTRAL LCID specifica che la proprietà è indipendente dalla lingua, ovvero non specifica di alcuna lingua. Non impostare questo parametro su LOCALE_SYSTEM_DEFAULT o LOCALE_USER_DEFAULT. Per altre informazioni sui valori LCID specifici del linguaggio, vedere Struttura LCID.

[in] Flags

Riservato. I driver devono impostare questo valore su 0.

[in] PropertyType

Puntatore a un valore DEVPROPTYPE che specifica il tipo di dati forniti nel buffer PropertyData.

[in] PropertyDataSize

Dimensioni, in byte, del buffer a cui PropertyData punta.

[in, optional] PropertyData

Puntatore ai dati della proprietà del dispositivo. Impostare questo parametro su NULL per eliminare la proprietà specificata.

Valore restituito

SetPropertyData restituisce S_OK se l'operazione ha esito positivo. In caso contrario, il metodo potrebbe restituire i valori seguenti.

Codice restituito	Descrizione
E_OUTOFMEMORY	Il tentativo del framework di allocare memoria non è riuscito.
HRESULT_FROM_WIN32 (ERROR_INVALID_PARAMETER)	Se il driver specifica WdfPropertyStoreRootClassDeviceInterfaceKey, l'interfaccia richiesta deve essere quella registrata in precedenza dal driver UMDF.
HRESULT_FROM_WIN32 (STATUS_NOT_SUPPORTED)	Il driver può modificare i dati delle proprietà dell'interfaccia dispositivo solo a partire da Windows 8.

Questo metodo potrebbe restituire un valore tipizzato HRESULT corrispondente a uno degli altri valori contenuti winerror.h.

Osservazioni

I driver basati su framework usano il metodo SetPropertyData per modificare le proprietà del dispositivo definite come parte del modello di proprietà unificata del dispositivo.

In particolare, è possibile usare questo metodo per modificare la chiave hardware di un dispositivo o un'istanza di una classe di interfaccia dispositivo. Quando chiami IWDFUnifiedPropertyStoreFactory::RetrieveUnifiedDevicePropertyStore, imposta il RootSpecifier parametro membro RootClass su WdfPropertyStoreRootClassHardwareKey o WdfPropertyStoreRootClassDeviceInterfaceKey.

Se si specifica WdfPropertyStoreRootClassHardwareKey, quando si chiama SetPropertyData, è necessario fornire un valore DEVPROPKEY personalizzato nel parametro PropertyKey e non una chiave definita da PnP. Il valore deve essere stato impostato in precedenza chiamando SetPropertyData, una funzione della proprietà del dispositivo setupDI oppure usando la direttiva INF AddProperty.

Se il driver specifica WdfPropertyStoreRootClassDeviceInterfaceKey, l'interfaccia richiesta deve essere quella registrata in precedenza dal driver UMDF in fase di esecuzione.

Se il driver registra un'interfaccia nel file INF, deve anche impostare le proprietà associate in INF.

Per altre informazioni sull'accesso al Registro di sistema, vedere Uso del Registro di sistema nei driver basati su UMDF.

Esempi

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

Fabbisogno

Requisito	Valore
Fine del supporto	Non disponibile in UMDF 2.0 e versioni successive.
piattaforma di destinazione	Desktop
versione minima di UMDF	1.11
intestazione	wudfddi.h
dll	WUDFx.dll