Metodo IWDFUnifiedPropertyStore::GetPropertyData (wudfddi.h)
[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 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 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 per l'uso del sistema. I driver devono impostare questo valore su 0.
[in] PropertyDataSize
Dimensioni, in byte, del buffer a cui PropertyData punta.
[out, optional] PropertyData
Puntatore ai dati della proprietà del dispositivo.
[out] PropertyDataRequiredSize
Puntatore a ULONG per ricevere le dimensioni delle informazioni sulla proprietà restituite in PropertyData.
[out] PropertyType
Puntatore a un valore DEVPROPTYPE. Se GetPropertyData viene completato correttamente, il metodo utilizza PropertyType per specificare il tipo di dati restituiti 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 |
|---|---|
|
Il tentativo del framework di allocare memoria non è riuscito. |
|
Il parametro PropertyDataRequiredSize contiene le dimensioni del buffer richiesto. |
|
Se il driver specifica WdfPropertyStoreRootClassDeviceInterfaceKey, l'interfaccia richiesta deve essere quella registrata in precedenza dal driver UMDF. |
|
Il driver può richiedere i dati delle proprietà dell'interfaccia dispositivo solo a partire da Windows 8. |
Questo metodo potrebbe restituire uno degli altri valori contenuti Winerror.h.
Osservazioni
I driver basati su framework usano il metodo GetPropertyData per recuperare le proprietà del dispositivo definite come parte del modello di proprietà unificata del dispositivo.
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 chiami IWDFUnifiedPropertyStoreFactory::RetrieveUnifiedDevicePropertyStore, imposta il RootSpecifier parametro membro RootClass su WdfPropertyStoreRootClassHardwareKey o WdfPropertyStoreRootClassDeviceInterfaceKey.
Se si specifica WdfPropertyStoreRootClassHardwareKey, quando si chiama GetPropertyData, è necessario fornire un valore personalizzato DEVPROPKEY 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.
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.
Esempi
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 al PropertyDataRequired Size restituito e chiamare nuovamente 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;
}
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 |
Vedere anche
IWDFUnifiedPropertyStoreFactory