Metodo IWDFUnifiedPropertyStore::GetPropertyData (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 GetPropertyData recupera l'impostazione corrente per una proprietà del dispositivo.

Sintassi

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

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 per l'utilizzo nel sistema. I driver devono impostare questo valore su 0.

[in] PropertyDataSize

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

[out, optional] PropertyData

Puntatore ai dati delle proprietà del dispositivo.

[out] PropertyDataRequiredSize

Puntatore a un ULONG per ricevere le dimensioni delle informazioni sulle proprietà restituite in PropertyData.

[out] PropertyType

Puntatore a un valore DEVPROPTYPE . Se GetPropertyData viene completato correttamente, il metodo usa PropertyType per specificare il tipo di dati restituito nel buffer PropertyData .

Valore restituito

GetPropertyData 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_NT(STATUS_BUFFER_TOO_SMALL)	Il parametro PropertyDataRequiredSize contiene le dimensioni del buffer richiesto.
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ò richiedere i dati delle proprietà dell'interfaccia del dispositivo solo a partire da Windows 8.

Questo metodo potrebbe restituire uno degli altri valori che Winerror.h contiene.

Commenti

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

In particolare, è possibile usare questo metodo per recuperare 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 GetPropertyData, è 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.

Per altre informazioni sulle proprietà del dispositivo, vedere Proprietà dispositivo.

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

Esempio

Per le proprietà delle dimensioni delle variabili, il driver deve eseguire due passaggi per recuperare i dati della proprietà. Prima di tutto, il driver deve passare un buffer NULL nel parametro PropertyData e impostare PropertyDataSize su 0. Il driver deve quindi allocare un buffer in base alla proprietà PropertyDataRequiredSize restituito e chiamare di nuovo GetPropertyData , passando il buffer allocato.

Nell'esempio seguente viene illustrato questo modello.

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

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