Funzione WdfDeviceQueryProperty (wdfdevice.h)

Articolo
02/07/2025

[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_PROPERTYtipizzato che identifica la proprietà del dispositivo da recuperare.

[in] BufferLength

Dimensione, in byte, del buffer a cui punta 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

Posizione fornita dal chiamante che, in caso di restituzione, contiene le dimensioni, in byte, delle informazioni archiviate nel metodo 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 .

Se il driver fornisce un handle di oggetto non valido, si verifica un controllo di bug.

Osservazioni

Prima di ricevere i dati delle proprietà del dispositivo, i driver in genere chiamano il metodo WdfDeviceQueryProperty solo per ottenere le dimensioni del buffer necessarie. Per alcune proprietà, le dimensioni dei dati possono variare tra quando vengono restituite le dimensioni necessarie e quando il driver chiama WdfDeviceQueryProperty di nuovo. 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 la dimensione del buffer richiesta è nota e non modificabile, 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à unificata.

Esempi

L'esempio di codice seguente ottiene 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
                                );

Fabbisogno

Requisito	Valore
piattaforma di destinazione	Universale
versione minima di KMDF	1.0
versione minima di UMDF	2.0
intestazione	wdfdevice.h (include Wdf.h)
libreria	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
regole di conformità DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Vedere anche

WdfDeviceAllocAndQueryProperty

WdfFdoInitQueryProperty

Condividi tramite