Funzione WdfIoTargetFormatRequestForRead (wdfiotarget.h)

Articolo
08/08/2023

[Si applica a KMDF e UMDF]

Il metodo WdfIoTargetFormatRequestForRead compila una richiesta di lettura per una destinazione di I/O, ma non invia la richiesta.

Sintassi

NTSTATUS WdfIoTargetFormatRequestForRead(
  [in]           WDFIOTARGET       IoTarget,
  [in]           WDFREQUEST        Request,
  [in, optional] WDFMEMORY         OutputBuffer,
  [in, optional] PWDFMEMORY_OFFSET OutputBufferOffset,
  [in, optional] PLONGLONG         DeviceOffset
);

Parametri

[in] IoTarget

Handle per un oggetto di destinazione I/O locale o remoto ottenuto da una chiamata precedente a WdfDeviceGetIoTarget o WdfIoTargetCreate o da un metodo fornito da una destinazione di I/O specializzata.

[in] Request

Handle per un oggetto richiesta del framework. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

[in, optional] OutputBuffer

Handle per un oggetto memoria del framework. Questo oggetto rappresenta un buffer che riceverà i dati dalla destinazione di I/O. Questo parametro è facoltativo e può essere NULL. Per altre informazioni su questo parametro, vedere la sezione Osservazioni seguente.

[in, optional] OutputBufferOffset

Puntatore a una struttura WDFMEMORY_OFFSET allocata dal chiamante che fornisce valori facoltativi di offset di byte e lunghezza. Il framework usa questi valori per determinare l'indirizzo iniziale e la lunghezza, all'interno del buffer di output, per il trasferimento dei dati. Se questo puntatore è NULL, il trasferimento dei dati inizia all'inizio del buffer di output e le dimensioni del trasferimento sono le dimensioni del buffer.

[in, optional] DeviceOffset

Puntatore a una variabile che specifica un offset iniziale per il trasferimento. La destinazione di I/O, ovvero il driver inferiore successivo, definisce come usare questo valore. Ad esempio, i driver nello stack di driver di un disco possono specificare un offset dall'inizio del disco. La destinazione di I/O ottiene queste informazioni nel membro Parameters.Read.DeviceOffset della struttura WDF_REQUEST_PARAMETERS della richiesta. Questo puntatore è facoltativo. La maggior parte dei driver imposta questo puntatore su NULL.

Valore restituito

WdfIoTargetFormatRequestForRead restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, questo metodo potrebbe restituire uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_INVALID_PARAMETER	È stato rilevato un parametro non valido.
STATUS_INVALID_DEVICE_REQUEST	La lunghezza del trasferimento è maggiore della lunghezza del buffer oppure la richiesta di I/O è già stata accodata a una destinazione di I/O.
STATUS_INSUFFICIENT_RESOURCES	Il framework non è riuscito ad allocare risorse di sistema (in genere memoria).
STATUS_REQUEST_NOT_ACCEPTED	Il pacchetto di richiesta di I/O rappresentato dal parametro Request non fornisce strutture IO_STACK_LOCATION sufficienti per consentire al driver di inoltrare la richiesta.

Questo metodo potrebbe anche restituire altri valori NTSTATUS.

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

Commenti

Utilizzare il metodo WdfIoTargetFormatRequestForRead , seguito dal metodo WdfRequestSend , per inviare richieste di lettura in modo sincrono o asincrono. In alternativa, usare il metodo WdfIoTargetSendReadSynchronously per inviare le richieste di lettura in modo sincrono.

È possibile inoltrare una richiesta di I/O ricevuta dal driver in una coda di I/O oppure creare e inviare una nuova richiesta. In entrambi i casi, il framework richiede un oggetto richiesta e uno spazio buffer.

Per inoltrare una richiesta di I/O ricevuta dal driver in una coda di I/O:

Specificare l'handle della richiesta ricevuta per il parametro Request del metodo WdfIoTargetFormatRequestForRead.
Usare il buffer di output della richiesta ricevuta per il parametro OutputBuffer del metodo WdfIoTargetFormatRequestForRead.
Il driver deve chiamare WdfRequestRetrieveOutputMemory per ottenere un handle a un oggetto memoria framework che rappresenta il buffer di output della richiesta e deve usare tale handle come valore per OutputBuffer.

Per altre informazioni sull'inoltro di una richiesta di I/O, vedere Inoltro di richieste di I/O.

I driver spesso dividono le richieste di I/O ricevute in richieste più piccole inviate a una destinazione di I/O, in modo che il driver possa creare nuove richieste.

Per creare una nuova richiesta di I/O:

Creare un nuovo oggetto richiesta e specificare il relativo handle per il parametro Request del metodo WdfIoTargetFormatRequestForRead.
Chiamare WdfRequestCreate per preallocare uno o più oggetti richiesta. È possibile riutilizzare questi oggetti richiesta chiamando WdfRequestReuse. La funzione di callback EvtDriverDeviceAdd del driver può preallocare oggetti richiesta per un dispositivo.
Specificare lo spazio del buffer e specificare l'handle del buffer per il parametro OutputBuffer del metodo WdfIoTargetFormatRequestForRead.
Il driver deve specificare questo spazio buffer come handle WDFMEMORY per la memoria gestita dal framework. Il driver può eseguire una delle operazioni seguenti:
- Chiamare WdfMemoryCreate o WdfMemoryCreatePreallocated per creare un nuovo buffer di memoria, se si vuole che il driver passi un nuovo buffer alla destinazione di I/O.
- Chiamare WdfRequestRetrieveOutputMemory per ottenere un handle per l'oggetto memoria che rappresenta il buffer della richiesta di I/O ricevuta, se si desidera che il driver passi il contenuto del buffer alla destinazione di I/O.
Si noti che se il driver chiama WdfRequestRetrieveOutputMemory e passa l'handle di memoria a WdfIoTargetFormatRequestForRead, il driver non deve completare la richiesta di I/O ricevuta fino a quando il driver elimina, riutilizza o riformatta il nuovo oggetto richiesta creato dal driver. WdfIoTargetFormatRequestForRead incrementa il conteggio dei riferimenti dell'oggetto memoria. L'eliminazione, il riutilizzo o la riformattazione di un oggetto richiesta decrementa il conteggio dei riferimenti dell'oggetto memoria.

Alcune destinazioni di I/O accettano richieste di lettura con un buffer di lunghezza zero. Per tali destinazioni di I/O, il driver può specificare NULL per il parametro OutputBuffer .

Dopo che un driver chiama WdfIoTargetFormatRequestForRead per formattare una richiesta di I/O, deve chiamare WdfRequestSend per inviare la richiesta (in modo sincrono o asincrono) a una destinazione di I/O.

Più chiamate a WdfIoTargetFormatRequestForRead che usano la stessa richiesta non causano allocazioni di risorse aggiuntive. Pertanto, per ridurre la probabilità che WdfRequestCreate restituisca STATUS_INSUFFICIENT_RESOURCES, la funzione di callback EvtDriverDeviceAdd del driver può chiamare WdfRequestCreate per preallocare uno o più oggetti richiesta per un dispositivo. Il driver può successivamente riutilizzare (chiamare WdfRequestReuse), riformattare (chiamare WdfIoTargetFormatRequestForRead) e inviare di nuovo (chiamare WdfRequestSend) ogni oggetto richiesta senza rischiare un valore restituito STATUS_INSUFFICIENT_RESOURCES da una chiamata successiva a WdfRequestCreate. Tutte le chiamate successive a WdfIoTargetFormatRequestForRead per l'oggetto richiesta riutilizzato restituiranno STATUS_SUCCESS, se i valori dei parametri non cambiano. Se il driver non chiama lo stesso metodo di formattazione delle richieste ogni volta, è possibile allocare risorse aggiuntive.

Per informazioni su come ottenere informazioni sullo stato dopo il completamento di una richiesta di I/O, vedere Ottenere informazioni di completamento.

Per altre informazioni su WdfIoTargetFormatRequestForRead, vedere Invio di richieste di I/O a destinazioni di I/O generali.

Per altre informazioni sulle destinazioni di I/O, vedere Uso delle destinazioni di I/O.

Esempio

L'esempio di codice seguente crea un oggetto memoria framework per il buffer di output di una richiesta di lettura, formatta la richiesta di lettura, registra una funzione di callback CompletionRoutine e invia la richiesta di lettura a una destinazione di I/O.

WDFREQUEST  request;
NTSTATUS  status;
WDFMEMORY  memory;
WDF_OBJECT_ATTRIBUTES  attributes;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
status = WdfMemoryCreate(
                         &attributes,
                         NonPagedPool,
                         DRIVER_TAG,
                         READ_BUF_SIZE,
                         &memory,
                         NULL
                         );

if (!NT_SUCCESS(status)) {
    return status;
}

status = WdfIoTargetFormatRequestForRead(
                                         IoTarget,
                                         request,
                                         memory,
                                         NULL,
                                         NULL
                                         );
if (!NT_SUCCESS(status)) {
        return status;
}
WdfRequestSetCompletionRoutine(
                               request,
                               MyReadRequestCompletionRoutine,
                               targetInfo
                               );
if (WdfRequestSend(
                   request,
                   IoTarget,
                   WDF_NO_SEND_OPTIONS
                   ) == FALSE) {
        status = WdfRequestGetStatus(request);
}

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1.0
Versione UMDF minima	2,0
Intestazione	wdfiotarget.h (include Wdf.h)
Libreria	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Regole di conformità DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf)