Funzione WdfFdoInitQueryProperty (wdffdo.h)

[Si applica a KMDF e UMDF]

Il metodo WdfFdoInitQueryProperty recupera una proprietà del dispositivo specificata.

Sintassi

NTSTATUS WdfFdoInitQueryProperty(
  [in]  PWDFDEVICE_INIT          DeviceInit,
  [in]  DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]  ULONG                    BufferLength,
  [out] PVOID                    PropertyBuffer,
  [out] PULONG                   ResultLength
);

Parametri

[in] DeviceInit

Puntatore a una struttura WDFDEVICE_INIT ottenuta dal driver dalla funzione EvtDriverDeviceAdd callback.

[in] DeviceProperty

Valore 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 la proprietà del dispositivo richiesto. Questo 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 da WdfFdoInitQueryProperty in PropertyBuffer. Se il valore restituito di questo metodo è STATUS_BUFFER_TOO_SMALL, ResultLength riceve le dimensioni del buffer necessarie.

Valore restituito

Se l'operazione ha esito positivo, il metodo 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	La struttura WDFDEVICE_INIT non è stata ottenuta dalla funzione EvtDriverDevice del driverAggiungi il callback.

 

Il metodo potrebbe restituire anche altri valori NTSTATUS.

Commenti

Prima di ricevere i dati delle proprietà del dispositivo, i driver in genere devono effettuare una chiamata iniziale a WdfFdoInitQueryProperty per ottenere le dimensioni del buffer necessarie. Per alcune proprietà, le dimensioni dei dati possono cambiare tra il momento in cui vengono restituite le dimensioni necessarie e il tempo in cui il driver chiama nuovamente questa routine. Pertanto, i driver devono chiamare WdfFdoInitQueryProperty all'interno di un ciclo che viene eseguito fino a quando lo stato restituito non è STATUS_BUFFER_TOO_SMALL.

È consigliabile usare WdfFdoInitQueryProperty solo se la dimensione del buffer necessaria è nota e non modificabile, perché in questo caso il driver deve chiamare WdfFdoInitQueryProperty una sola volta. Se le dimensioni del buffer necessarie sono sconosciute o variano, il driver deve chiamare WdfFdoInitAllocAndQueryProperty.

Il driver può chiamare WdfFdoInitQueryProperty solo prima di chiamare WdfDeviceCreate. Per altre informazioni sulla chiamata a WdfDeviceCreate, vedere Creazione di un oggetto dispositivo Framework.

Dopo aver chiamato WdfDeviceCreate, un driver può ottenere informazioni sulla proprietà del dispositivo chiamando WdfDeviceQueryProperty.

Per altre informazioni sul metodo WdfFdoInitQueryProperty , vedere Creazione di oggetti dispositivo in un driver di funzione.

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

Esempio

Nell'esempio di codice seguente viene ottenuta una stringa Unicode che rappresenta il nome dell'enumeratore di un dispositivo e restituisce TRUE se la stringa è "PCI".

NTSTATUS  status = STATUS_SUCCESS;
WCHAR  enumeratorName[64] = {0};
ULONG  returnSize;
UNICODE_STRING  unicodeEnumName, temp;

status = WdfFdoInitQueryProperty(
                                 DeviceInit,
                                 DevicePropertyEnumeratorName,
                                 sizeof(enumeratorName),
                                 enumeratorName,
                                 &returnSize
                                 );
if(!NT_SUCCESS(status)){
    return status;
}

RtlInitUnicodeString(
                     &unicodeEnumName,
                     enumeratorName
                     );
RtlInitUnicodeString(
                     &temp,
                     L"PCI"
                     );
if(RtlCompareUnicodeString(
                           &unicodeEnumName,
                           &temp,
                           TRUE
                           ) == 0) {
    //
    // This device is a PCI device.
    //
    return TRUE;
}

Requisiti

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

Vedi anche

WdfDeviceQueryProperty

WdfFdoInitAllocAndQueryProperty