Funzione WdfIoTargetFormatRequestForInternalIoctl (wdfiotarget.h)
[Si applica solo a KMDF]
Il metodo WdfIoTargetFormatRequestForInternalIoctl compila una richiesta di controllo del dispositivo interno per una destinazione I/O, ma non invia la richiesta.
Sintassi
NTSTATUS WdfIoTargetFormatRequestForInternalIoctl(
[in] WDFIOTARGET IoTarget,
[in] WDFREQUEST Request,
[in] ULONG IoctlCode,
[in, optional] WDFMEMORY InputBuffer,
[in, optional] PWDFMEMORY_OFFSET InputBufferOffset,
[in, optional] WDFMEMORY OutputBuffer,
[in, optional] PWDFMEMORY_OFFSET OutputBufferOffset
);
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] IoctlCode
Codice di controllo I/O (IOCTL) supportato dalla destinazione I/O.
[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. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.
[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] OutputBuffer
Handle per un oggetto memoria framework. Questo oggetto rappresenta un buffer che riceverà i dati dalla destinazione di I/O. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.
[in, optional] OutputBufferOffset
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 output, per il trasferimento dei dati. Se questo puntatore è NULL, il trasferimento dei dati inizia all'inizio del buffer di output e la dimensione del trasferimento è la dimensione del buffer.
Valore restituito
WdfIoTargetFormatRequestForInternalIoctl 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 WdfIoTargetFormatRequestForInternalIoctl , seguito dal metodo WdfRequestSend , per inviare richieste di controllo del dispositivo interno in modo sincrono o asincrono. In alternativa, usare il metodo WdfIoTargetSendInternalIoctlSynchronously per inviare richieste di controllo del dispositivo interno in modo sincrono.
Per altre informazioni sulle richieste di controllo dei dispositivi interni, vedere Uso dei codici di controllo I/O.
È possibile inoltrare una richiesta di controllo del dispositivo interna 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 request e uno spazio buffer.
Per inoltrare una richiesta di controllo del dispositivo interna ricevuta dal driver in una coda di I/O:
- Specificare l'handle della richiesta ricevuta per il parametro Request del metodo WdfIoTargetFormatRequestForInternalIoctl.
-
Usare il buffer di input della richiesta ricevuta per il parametro InputBuffer del metodo WdfIoTargetFormatRequestForInternalIoctl.
Il driver deve chiamare WdfRequestRetrieveInputMemory per ottenere un handle nel buffer di input della richiesta e deve usare tale handle come valore per InputBuffer.
-
Usare il buffer di output della richiesta ricevuta per il parametro OutputBuffer del metodo WdfIoTargetFormatRequestForInternalIoctl.
Il driver deve chiamare WdfRequestRetrieveOutputMemory per ottenere un handle nel buffer di output della richiesta e deve usare tale handle come valore per OutputBuffer.
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 WdfIoTargetFormatRequestForInternalIoctl.
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 i parametri InputBuffer e OutputBuffer del metodo WdfIoTargetFormatRequestForInternalIoctl.
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 o WdfRequestRetrieveOutputMemory per ottenere un handle all'oggetto memoria che rappresenta il buffer della richiesta di I/O ricevuta, se si vuole che il driver passi il contenuto del buffer alla destinazione I/O.
Più chiamate a WdfIoTargetFormatRequestForInternalIoctl 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 WdfIoTargetFormatRequestForInternalIoctl) 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 WdfIoTargetFormatRequestForInternalIoctl per l'oggetto richiesta riutilizzato restituiranno STATUS_SUCCESS, se i valori dei parametri non cambiano. Tuttavia, se il driver non chiama lo stesso metodo di formattazione delle richieste ogni volta, è possibile allocare risorse aggiuntive. Inoltre, se il codice di controllo I/O specifica un tipo di trasferimento di METHOD_BUFFERED, il framework deve allocare un buffer di sistema per ogni richiesta e tale allocazione potrebbe non riuscire a causa di risorse di memoria insufficienti.
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 WdfIoTargetFormatRequestForInternalIoctl, 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 figlio di un oggetto request. L'esempio ottiene quindi il buffer che l'oggetto memoria contiene e inizializza il buffer. L'esempio formatta quindi la richiesta, imposta una funzione di callback Di completamentoRoutine e invia la richiesta a una destinazione di I/O.
WDF_OBJECT_ATTRIBUTES memoryObjAttr;
WDFMEMORY memory;
NTSTATUS status;
IOCTL_DATA *pIoctlData;
WDF_OBJECT_ATTRIBUTES_INIT(&memoryObjAttr);
memoryObjAttr.ParentObject = Request;
status = WdfMemoryCreate(
&memoryObjAttr,
NonPagedPool,
0,
sizeof(IOCTL_DATA),
&memory,
NULL
);
if (!NT_SUCCESS(status)) {
goto Done;
}
pIoctlData = WdfMemoryGetBuffer(
memory,
NULL
);
RtlZeroMemory(
pIoctlData,
sizeof(IOCTL_DATA)
);
pIoctlData->Member1 = MY_DATA;
status = WdfIoTargetFormatRequestForInternalIoctl(
IoTarget,
Request,
IOCTL_INTERNAL_GET_MY_DATA,
memory,
NULL,
WDF_NO_HANDLE,
NULL
);
if (!NT_SUCCESS(status)) {
goto Done;
}
WdfRequestSetCompletionRoutine(
Request,
MyRequestCompletion,
NULL
);
if (WdfRequestSend(
Request,
IoTarget,
NULL
) == FALSE) {
status = WdfRequestGetStatus(Request);
}
else {
status = STATUS_SUCCESS;
}
Requisiti
| Requisito | Valore |
|---|---|
| Piattaforma di destinazione | Universale |
| Versione KMDF minima | 1,0 |
| Intestazione | wdfiotarget.h (include Wdf.h) |
| Libreria | Wdf01000.sys (vedere Framework Library Versioning). |
| IRQL | <=DISPATCH_LEVEL |
| Regole di conformità DDI | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf) |
Vedi anche
WdfIoTargetFormatRequestForIoctl
WdfIoTargetSendInternalIoctlSynchronously
WdfIoTargetSendIoctlSynchronously