Metodo IWDFUnifiedPropertyStore::SetPropertyData (wudfddi.h)

Articolo
08/08/2023

[Avviso: UMDF 2 è la versione più recente di UMDF e sostituisce UMDF 1. Tutti i nuovi driver UMDF devono essere scritti usando UMDF 2. Nessuna nuova funzionalità viene aggiunta 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, vedere Introduzione con 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 del linguaggio o su LOCALE_NEUTRAL. L'LOCALE_NEUTRAL LCID specifica che la proprietà è indipendente dal linguaggio , ovvero non specifica per nessun linguaggio. 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 punta PropertyData .

[in, optional] PropertyData

Puntatore ai dati delle 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 del dispositivo solo a partire da Windows 8.

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

Commenti

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

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

Se si specifica WdfPropertyStoreRootClassHardwareKey, quando si chiama SetPropertyData, è necessario specificare 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 di proprietà del dispositivo SetupDI o usando la direttiva INF AddProperty.

Se il driver specifica WdfPropertyStoreRootClassDeviceInterfaceKey, l'interfaccia richiesta deve essere una che il driver UMDF registrato in precedenza in fase di esecuzione.

Se il driver registra un'interfaccia nel file INF, deve impostare anche 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.

Esempio

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

Requisiti

Requisito	Valore
Fine del supporto	Non disponibile in UMDF 2.0 e versioni successive.
Piattaforma di destinazione	Desktop
Versione UMDF minima	1.11
Intestazione	wudfddi.h
DLL	WUDFx.dll