Funzione WdfIoTargetFormatRequestForWrite (wdfiotarget.h)

Articolo
08/08/2023

[Si applica a KMDF e UMDF]

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

Sintassi

NTSTATUS WdfIoTargetFormatRequestForWrite(
  [in]           WDFIOTARGET       IoTarget,
  [in]           WDFREQUEST        Request,
  [in, optional] WDFMEMORY         InputBuffer,
  [in, optional] PWDFMEMORY_OFFSET InputBufferOffset,
  [in, optional] PLONGLONG         DeviceOffset
);

Parametri

[in] IoTarget

Handle a 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 I/O specializzata.

[in] Request

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

[in, optional] InputBuffer

Handle per un oggetto memoria framework. Questo oggetto rappresenta un buffer che contiene dati che verranno inviati alla destinazione di I/O. Questo parametro è facoltativo e può essere NULL. Per altre informazioni su questo parametro, vedere la sezione Osservazioni seguenti.

[in, optional] InputBufferOffset

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

[in, optional] DeviceOffset

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

Valore restituito

WdfIoTargetFormatRequestForWrite 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 le risorse di sistema (in genere memoria).
STATUS_REQUEST_NOT_ACCEPTED	Il pacchetto di richiesta I/O (IRP) che il parametro Request rappresenta non fornisce strutture IO_STACK_LOCATION sufficienti per consentire al driver di inoltrare la richiesta.

Questo metodo potrebbe restituire anche altri valori NTSTATUS.

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

Commenti

Utilizzare il metodo WdfIoTargetFormatRequestForWrite , seguito dal metodo WdfRequestSend , per inviare richieste di scrittura in modo sincrono o asincrono. In alternativa, usare il metodo WdfIoTargetSendWriteSynchronously per inviare richieste di scrittura in modo sincrono.

È possibile inoltrare una richiesta di I/O ricevuta dal driver in una coda di I/O oppure è possibile creare e inviare una nuova richiesta. In entrambi i casi, il framework richiede un oggetto request 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 WdfIoTargetFormatRequestForWrite.
Usare il buffer di input della richiesta ricevuta per il parametro InputBuffer del metodo WdfIoTargetFormatRequestForWrite.
Il driver deve chiamare WdfRequestRetrieveInputMemory per ottenere un handle a un oggetto di memoria del framework che rappresenta il buffer di input della richiesta e deve usare tale handle come valore per InputBuffer.

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 request e specificare il relativo handle per il parametro Request del metodo WdfIoTargetFormatRequestForWrite.
Chiamare WdfRequestCrea per preallocare uno o più oggetti richiesta. È possibile riutilizzare questi oggetti richiesta chiamando WdfRequestReuse. La funzione di callback EvtDriverDevice del driver può preallocare gli oggetti di richiesta per un dispositivo.
Fornire spazio del buffer e fornire l'handle del buffer per il parametro InputBuffer del metodo WdfIoTargetFormatRequestForWrite.
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 WdfRequestRetrieveInputMemory per ottenere un handle per l'oggetto memoria che rappresenta il buffer della richiesta di I/O ricevuto, se si vuole che il driver passi il contenuto del buffer alla destinazione I/O.
Si noti che se il driver chiama WdfRequestRetrieveInputMemory e passa l'handle di memoria a WdfIoTargetFormatRequestForWrite, 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. (WdfIoTargetFormatRequestForWrite incrementa il conteggio dei riferimenti dell'oggetto memoria. Eliminazione, riutilizzo o riformattamento di un oggetto request decrementa il numero di riferimenti dell'oggetto memoria.

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

Dopo che un driver chiama WdfIoTargetFormatRequestForWrite 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 WdfIoTargetFormatRequestForWrite che usano la stessa richiesta non causano allocazioni di risorse aggiuntive. Pertanto, per ridurre la possibilità che WdfRequestCreate restituirà STATUS_INSUFFICIENT_RESOURCES, la funzione evtDriverDeviceAdd callback del driver può chiamare WdfRequestCreate per preallocare uno o più oggetti richiesta per un dispositivo. Il driver può successivamente riutilizzare (chiamare WdfRequestReuse), riformatare (chiamare WdfIoTargetFormatRequestForWrite) e inviare nuovamente (chiamare WdfRequestSend) ogni oggetto richiesta senza rischiare un valore restituito STATUS_INSUFFICIENT_RESOURCES da una chiamata successiva a WdfRequestCreate. Tutte le chiamate successive a WdfIoTargetFormatRequestForWrite 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 sull'acquisizione di informazioni sullo stato dopo il completamento di una richiesta di I/O, vedere Recupero delle informazioni di completamento.

Per altre informazioni su WdfIoTargetFormatRequestForWrite, 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

Nell'esempio di codice seguente viene creato un oggetto memoria framework per il buffer di input di una richiesta di scrittura, viene formattata la richiesta di scrittura, viene registrata una funzione di callback di CompletamentoRoutine e viene inviata la richiesta di scrittura 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,
                         WRITE_BUF_SIZE,
                         &memory,
                         NULL
                         );

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

status = WdfIoTargetFormatRequestForWrite(
                                          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)