Funzione WdfDeviceQueryProperty (wdfdevice.h)

Articolo
02/27/2024

[Si applica a KMDF e UMDF]

Il metodo WdfDeviceQueryProperty recupera una proprietà del dispositivo specificata.

Sintassi

NTSTATUS WdfDeviceQueryProperty(
  [in]  WDFDEVICE                Device,
  [in]  DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]  ULONG                    BufferLength,
  [out] PVOID                    PropertyBuffer,
  [out] PULONG                   ResultLength
);

Parametri

[in] Device

Handle per un oggetto dispositivo framework.

[in] DeviceProperty

Enumeratore DEVICE_REGISTRY_PROPERTY tipizzato che identifica la proprietà del dispositivo da recuperare.

[in] BufferLength

Dimensioni, in byte, del buffer a cui fa riferimento PropertyBuffer.

[out] PropertyBuffer

Puntatore fornito dal chiamante a un buffer allocato dal chiamante che riceve le informazioni richieste. Il puntatore può essere NULL se il parametro BufferLength è zero.

[out] ResultLength

Percorso fornito dal chiamante che, in caso di restituzione, contiene le dimensioni, in byte, delle informazioni archiviate nel metodo in PropertyBuffer. Se il valore restituito della funzione è STATUS_BUFFER_TOO_SMALL, questa posizione riceve le dimensioni del buffer necessarie.

Valore restituito

Se l'operazione ha esito positivo, WdfDeviceQueryProperty restituisce STATUS_SUCCESS. I valori restituiti aggiuntivi includono:

Codice restituito	Descrizione
STATUS_BUFFER_TOO_SMALL	Il buffer fornito è troppo piccolo per ricevere le informazioni.
STATUS_INVALID_PARAMETER_2	Il valore DeviceProperty specificato non è valido
STATUS_INVALID_DEVICE_REQUEST	I driver del dispositivo non hanno ancora segnalato le proprietà del dispositivo.

Il metodo potrebbe restituire altri valori NTSTATUS.

Un controllo di bug si verifica se il driver fornisce un handle di oggetti non valido.

Commenti

Prima di ricevere i dati delle proprietà del dispositivo, i driver chiamano in genere il metodo WdfDeviceQueryProperty solo per ottenere le dimensioni del buffer necessarie. Per alcune proprietà, le dimensioni dei dati possono cambiare tra quando vengono restituite le dimensioni necessarie e quando il driver chiama di nuovo WdfDeviceQueryProperty . Pertanto, i driver devono chiamare WdfDeviceQueryProperty all'interno di un ciclo che viene eseguito fino a quando lo stato restituito non è STATUS_BUFFER_TOO_SMALL.

È consigliabile usare WdfDeviceQueryProperty solo se le dimensioni del buffer necessarie sono note e non modificabili, perché in questo caso il driver deve chiamare WdfDeviceQueryProperty una sola volta. Se le dimensioni del buffer necessarie sono sconosciute o variano, il driver deve chiamare WdfDeviceAllocAndQueryProperty.

In alternativa, è possibile usare WdfDeviceQueryPropertyEx per accedere alle proprietà del dispositivo esposte tramite il modello di proprietà Unified.

Esempio

Nell'esempio di codice seguente viene ottenuta la proprietà DevicePropertyBusTypeGuid di un dispositivo. L'esempio chiama WdfDeviceQueryProperty anziché WdfDeviceAllocAndQueryProperty perché la lunghezza di un GUID è nota.

GUID  busTypeGuid;
ULONG  resultLength = 0;
NTSTATUS  status;

status = WdfDeviceQueryProperty( 
                                device,
                                DevicePropertyBusTypeGuid,
                                sizeof(GUID),
                                (PVOID)&busTypeGuid,
                                &resultLength
                                );

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1,0
Versione UMDF minima	2,0
Intestazione	wdfdevice.h (includere Wdf.h)
Libreria	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Regole di conformità DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Vedi anche

WdfDeviceAllocAndQueryProperty

WdfFdoInitQueryProperty

Condividi tramite