Funzione WdfIoTargetFormatRequestForWrite (wdfiotarget.h)
[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 |
|---|---|
|
È stato rilevato un parametro non valido. |
|
La lunghezza del trasferimento è maggiore della lunghezza del buffer oppure la richiesta di I/O è già stata accodata a una destinazione di I/O. |
|
Il framework non è riuscito ad allocare le risorse di sistema (in genere memoria). |
|
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.
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.
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) |