WdfIoTargetFormatRequestForInternalIoctl-Funktion (wdfiotarget.h)
[Gilt nur für KMDF]
Die WdfIoTargetFormatRequestForInternalIoctl-Methode erstellt eine interne Gerätesteuerungsanforderung für ein E/A-Ziel, sendet die Anforderung jedoch nicht.
Syntax
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
);
Parameter
[in] IoTarget
Ein Handle für ein lokales oder Remote-E/A-Zielobjekt, das aus einem vorherigen Aufruf von WdfDeviceGetIoTarget oder WdfIoTargetCreate oder von einer Methode abgerufen wurde, die ein spezialisiertes E/A-Ziel bereitstellt.
[in] Request
Ein Handle für ein Frameworkanforderungsobjekt. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".
[in] IoctlCode
Ein E/A-Kontrollcode (IOCTL), den das E/A-Ziel unterstützt.
[in, optional] InputBuffer
Ein Handle für ein Frameworkspeicherobjekt. Dieses Objekt stellt einen Puffer dar, der Daten enthält, die an das E/A-Ziel gesendet werden. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".
[in, optional] InputBufferOffset
Ein Zeiger auf eine aufruferseitig zugeordnete WDFMEMORY_OFFSET-Struktur , die optionale Byteoffset- und Längenwerte bereitstellt. Das Framework verwendet diese Werte, um die Anfangsadresse und die Länge innerhalb des Eingabepuffers für die Datenübertragung zu bestimmen. Wenn dieser Zeiger NULL ist, beginnt die Datenübertragung am Anfang des Eingabepuffers, und die Übertragungsgröße entspricht der Puffergröße.
[in, optional] OutputBuffer
Ein Handle für ein Frameworkspeicherobjekt. Dieses Objekt stellt einen Puffer dar, der Daten vom E/A-Ziel empfängt. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".
[in, optional] OutputBufferOffset
Ein Zeiger auf eine aufruferseitig zugeordnete WDFMEMORY_OFFSET-Struktur , die optionale Byteoffset- und Längenwerte bereitstellt. Das Framework verwendet diese Werte, um die Anfangsadresse und die Länge innerhalb des Ausgabepuffers für die Datenübertragung zu bestimmen. Wenn dieser Zeiger NULL ist, beginnt die Datenübertragung am Anfang des Ausgabepuffers, und die Übertragungsgröße entspricht der Puffergröße.
Rückgabewert
WdfIoTargetFormatRequestForInternalIoctl gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt diese Methode möglicherweise einen der folgenden Werte zurück:
| Rückgabecode | Beschreibung |
|---|---|
|
Ein ungültiger Parameter wurde erkannt. |
|
Die Übertragungslänge war größer als die Pufferlänge, oder die E/A-Anforderung wurde bereits an ein E/A-Ziel in die Warteschlange gestellt. |
|
Das Framework konnte keine Systemressourcen (in der Regel Arbeitsspeicher) zuordnen. |
|
Das vom Request-Parameter dargestellte E/A-Anforderungspaket (IRP) bietet nicht genügend IO_STACK_LOCATION Strukturen, damit der Treiber die Anforderung weiterleiten kann. |
Diese Methode kann auch andere NTSTATUS-Werte zurückgeben.
Eine Fehlerüberprüfung tritt auf, wenn der Treiber ein ungültiges Objekthandle bereitstellt.
Hinweise
Verwenden Sie die WdfIoTargetFormatRequestForInternalIoctl-Methode gefolgt von der WdfRequestSend-Methode , um interne Gerätesteuerungsanforderungen entweder synchron oder asynchron zu senden. Alternativ können Sie die WdfIoTargetSendInternalIoctlSynchronously-Methode verwenden, um interne Gerätesteuerungsanforderungen synchron zu senden.
Weitere Informationen zu internen Gerätesteuerungsanforderungen finden Sie unter Verwenden von E/A-Steuerungscodes.
Sie können eine interne Gerätesteuerungsanforderung weiterleiten, die Ihr Treiber in einer E/A-Warteschlange empfangen hat, oder Sie können eine neue Anforderung erstellen und senden. In beiden Fällen erfordert das Framework ein Anforderungsobjekt und etwas Pufferspeicherplatz.
So leiten Sie eine interne Gerätesteuerungsanforderung weiter, die Ihr Treiber in einer E/A-Warteschlange empfangen hat:
- Geben Sie das Handle der empfangenen Anforderung für den Request-Parameter der WdfIoTargetFormatRequestForInternalIoctl-Methode an.
-
Verwenden Sie den Eingabepuffer der empfangenen Anforderung für den InputBuffer-Parameter der WdfIoTargetFormatRequestForInternalIoctl-Methode.
Der Treiber muss WdfRequestRetrieveInputMemory aufrufen, um ein Handle für den Eingabepuffer der Anforderung abzurufen, und er muss dieses Handle als Wert für InputBuffer verwenden.
-
Verwenden Sie den Ausgabepuffer der empfangenen Anforderung für den OutputBuffer-Parameter der WdfIoTargetFormatRequestForInternalIoctl-Methode.
Der Treiber muss WdfRequestRetrieveOutputMemory aufrufen, um ein Handle für den Ausgabepuffer der Anforderung abzurufen, und er muss dieses Handle als Wert für OutputBuffer verwenden.
Treiber teilen empfangene E/A-Anforderungen häufig in kleinere Anforderungen auf, die sie an ein E/A-Ziel senden, sodass Ihr Treiber möglicherweise neue Anforderungen erstellt.
So erstellen Sie eine neue E/A-Anforderung:
-
Erstellen Sie ein neues Anforderungsobjekt, und geben Sie dessen Handle für den Request-Parameter der WdfIoTargetFormatRequestForInternalIoctl-Methode an.
Rufen Sie WdfRequestCreate auf , um mindestens ein Anforderungsobjekt vorab zu verwenden. Sie können diese Anforderungsobjekte wiederverwenden, indem Sie WdfRequestReuse aufrufen. Die Rückruffunktion EvtDriverDeviceAdd Ihres Treibers kann Anforderungsobjekte für ein Gerät vorab zuweisungen.
-
Geben Sie Pufferspeicher an, und geben Sie das Handle des Puffers für die InputBuffer- und OutputBuffer-Parameter der WdfIoTargetFormatRequestForInternalIoctl-Methode an.
Ihr Treiber muss diesen Pufferspeicher angeben, wie WDFMEMORY in den vom Framework verwalteten Speicher verarbeitet. Ihr Treiber kann eine der folgenden Aktionen ausführen:
- Rufen Sie WdfMemoryCreate oder WdfMemoryCreatePreallocated auf, um einen neuen Speicherpuffer zu erstellen, wenn der Treiber einen neuen Puffer an das E/A-Ziel übergeben soll.
- Rufen Sie WdfRequestRetrieveInputMemory oder WdfRequestRetrieveOutputMemory auf, um ein Handle für das Speicherobjekt abzurufen, das den Puffer einer empfangenen E/A-Anforderung darstellt, wenn der Treiber den Inhalt dieses Puffers an das E/A-Ziel übergibt.
Mehrere Aufrufe von WdfIoTargetFormatRequestForInternalIoctl , die dieselbe Anforderung verwenden, verursachen keine zusätzlichen Ressourcenzuordnungen. Aus diesem Grund kann die EvtDriverDeviceAdd-Rückruffunktion Ihres Treibers WdfRequestCreate aufrufen, um die Chance zu verringern, dass WdfRequestCreate zurückgegeben STATUS_INSUFFICIENT_RESOURCES wird, um ein oder mehrere Anforderungsobjekte für ein Gerät vorab zu verwenden. Der Treiber kann jedes Anforderungsobjekt anschließend wiederverwenden ( WdfRequestReuse aufrufen), neu formatieren ( WdfIoTargetFormatRequestForInternalIoctl aufrufen) und jedes Anforderungsobjekt erneut senden (WdfRequestSend aufrufen), ohne einen STATUS_INSUFFICIENT_RESOURCES Rückgabewert aus einem späteren Aufruf von WdfRequestCreate zu riskieren. Alle nachfolgenden Aufrufe von WdfIoTargetFormatRequestForInternalIoctl für das wiederverwendete Anforderungsobjekt geben STATUS_SUCCESS zurück, wenn sich die Parameterwerte nicht ändern. (Wenn der Treiber jedoch nicht jedes Mal dieselbe Anforderungsformatierungsmethode aufruft, werden möglicherweise zusätzliche Ressourcen zugeordnet. Wenn der E/A-Steuerungscode einen Übertragungstyp von METHOD_BUFFERED angibt, muss das Framework für jede Anforderung einen Systempuffer zuweisen, und diese Zuordnung kann aufgrund unzureichender Speicherressourcen fehlschlagen.)
Informationen zum Abrufen status Informationen nach Abschluss einer E/A-Anforderung finden Sie unter Abrufen von Abschlussinformationen.
Weitere Informationen zu WdfIoTargetFormatRequestForInternalIoctl finden Sie unter Senden von E/A-Anforderungen an allgemeine E/A-Ziele.
Weitere Informationen zu E/A-Zielen finden Sie unter Verwenden von E/A-Zielen.
Beispiele
Im folgenden Codebeispiel wird ein Frameworkspeicherobjekt erstellt, das ein untergeordnetes Element eines Anforderungsobjekts ist. Als Nächstes ruft das Beispiel den Puffer ab, den das Speicherobjekt enthält, und initialisiert den Puffer. Anschließend formatiert das Beispiel die Anforderung, legt eine CompletionRoutine-Rückruffunktion fest und sendet die Anforderung an ein E/A-Ziel.
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;
}
Anforderungen
| Anforderung | Wert |
|---|---|
| Zielplattform | Universell |
| KMDF-Mindestversion | 1.0 |
| Kopfzeile | wdfiotarget.h (include Wdf.h) |
| Bibliothek | Wdf01000.sys (siehe Versionsverwaltung der Frameworkbibliothek).) |
| IRQL | <=DISPATCH_LEVEL |
| DDI-Complianceregeln | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf) |
Weitere Informationen
WdfIoTargetFormatRequestForIoctl
WdfIoTargetSendInternalIoctlSynchronously
WdfIoTargetSendIoctlSynchronously