WdfIoTargetSendIoctlSynchronously-Funktion (wdfiotarget.h)
[Gilt für KMDF und UMDF]
Die WdfIoTargetSendIoctlSynchronously-Methode erstellt eine Gerätesteuerungsanforderung und sendet sie synchron an ein E/A-Ziel.
Syntax
NTSTATUS WdfIoTargetSendIoctlSynchronously(
[in] WDFIOTARGET IoTarget,
[in, optional] WDFREQUEST Request,
[in] ULONG IoctlCode,
[in, optional] PWDF_MEMORY_DESCRIPTOR InputBuffer,
[in, optional] PWDF_MEMORY_DESCRIPTOR OutputBuffer,
[in, optional] PWDF_REQUEST_SEND_OPTIONS RequestOptions,
[out, optional] PULONG_PTR BytesReturned
);
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, optional] Request
Ein Handle für ein Frameworkanforderungsobjekt. Dieser Parameter ist optional und kann NULL sein. 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 Zeiger auf eine vom Aufrufer zugewiesene WDF_MEMORY_DESCRIPTOR Struktur, die einen Puffer beschreibt, der in das E/A-Ziel geschrieben wird. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise". Dieser Parameter ist optional und kann NULL sein, wenn die Anforderung keine Daten sendet.
[in, optional] OutputBuffer
Ein Zeiger auf eine vom Aufrufer zugewiesene WDF_MEMORY_DESCRIPTOR Struktur, die einen Puffer beschreibt, der Daten vom E/A-Ziel empfängt. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise". Dieser Parameter ist optional und kann NULL sein, wenn die Anforderung keine Daten empfängt.
[in, optional] RequestOptions
Ein Zeiger auf eine vom Aufrufer zugeordnete WDF_REQUEST_SEND_OPTIONS Struktur, die Optionen für die Anforderung angibt. Dieser Zeiger ist optional und kann NULL sein. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".
[out, optional] BytesReturned
Ein Zeiger auf einen Speicherort, der Informationen empfängt (z. B. die Anzahl der übertragenen Bytes), die ein anderer Treiber bereitstellt, wenn er die Anforderung durch Aufrufen von WdfRequestCompleteWithInformation abschließt. Dieser Zeiger ist optional und kann NULL sein.
Rückgabewert
Wenn der Vorgang erfolgreich ist, gibt WdfIoTargetSendIoctlSynchronously zurück, nachdem die Gerätesteuerungsanforderung abgeschlossen wurde, und der Rückgabewert ist der Wert für den Abschluss status der Anforderung. Andernfalls gibt diese Methode möglicherweise einen der folgenden Werte zurück:
Rückgabecode | Beschreibung |
---|---|
|
Ein ungültiger Parameter wurde erkannt. |
|
Die Größe der WDF_REQUEST_SEND_OPTIONS Struktur, auf die der RequestOptions-Parameter verweist, war falsch. |
|
Die Anforderung wurde bereits an einem E/A-Ziel in die Warteschlange gestellt. |
|
Das Framework kann 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 WdfIoTargetSendIoctlSynchronously-Methode , um Gerätesteuerungsanforderungen synchron zu senden. Verwenden Sie zum asynchronen Senden von Gerätesteuerungsanforderungen die WdfIoTargetFormatRequestForctl-Methode , gefolgt von der WdfRequestSend-Methode .
Weitere Informationen zu Gerätesteuerungsanforderungen finden Sie unter Verwenden von E/A-Steuerungscodes.
Die WdfIoTargetSendIoctlSynchronously-Methode gibt erst zurück, wenn die Anforderung abgeschlossen ist, es sei denn, der Treiber liefert einen Timeoutwert in der WDF_REQUEST_SEND_OPTIONS-Struktur des RequestOptions-Parameters oder es wird kein Fehler erkannt.
Sie können eine 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 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 WdfIoTargetSendIoctlSynchronously-Methode an.
-
Verwenden Sie den Eingabepuffer der empfangenen Anforderung für den InputBuffer-Parameter der WdfIoTargetSendIoctlSynchronously-Methode.
Der Treiber muss WdfRequestRetrieveInputMemory aufrufen, um ein Handle für ein Frameworkspeicherobjekt abzurufen, das den Eingabepuffer der Anforderung darstellt. Anschließend muss der Treiber dieses Handle in der WDF_MEMORY_DESCRIPTOR Struktur platzieren, die der Treiber für den InputBuffer-Parameter von WdfIoTargetSendIoctlSynchronously bereitstellt.
-
Verwenden Sie den Ausgabepuffer der empfangenen Anforderung für den OutputBuffer-Parameter der WdfIoTargetSendIoctlSynchronously-Methode.
Der Treiber muss WdfRequestRetrieveOutputMemory aufrufen, um ein Handle für ein Frameworkspeicherobjekt abzurufen, das den Ausgabepuffer der Anforderung darstellt. Anschließend muss der Treiber dieses Handle in der WDF_MEMORY_DESCRIPTOR Struktur platzieren, die der Treiber für den OutputBuffer-Parameter von WdfIoTargetSendIoctlSynchronously bereitstellt.
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:
-
Geben Sie ein NULL-Anforderungshandle für den Request-Parameter der WdfIoTargetSendIoctlSynchronously-Methode an, oder erstellen Sie ein neues Anforderungsobjekt, und geben Sie dessen Handle an:
- Wenn Sie ein NULL-Anforderungshandle bereitstellen, verwendet das Framework ein internes Anforderungsobjekt. Diese Technik ist einfach zu verwenden, aber der Treiber kann die Anforderung nicht abbrechen.
- Wenn Sie WdfRequestCreate aufrufen, um ein oder mehrere Anforderungsobjekte zu erstellen, können Sie diese Anforderungsobjekte wiederverwenden, indem Sie WdfRequestReuse aufrufen. Mit dieser Technik kann die EvtDriverDeviceAdd-Rückruffunktion Ihres Treibers Anforderungsobjekte für ein Gerät vorab zugeordnet werden. Darüber hinaus kann ein anderer Treiberthread WdfRequestCancelSentRequest aufrufen, um die Anforderung bei Bedarf abzubrechen.
Ihr Treiber kann einen RequestOptions-Parameter ungleich NULL angeben, unabhängig davon, ob der Treiber einen Nicht-NULL- oder null-Anforderungsparameter bereitstellt. Sie können beispielsweise den Parameter RequestOptions verwenden, um einen Timeoutwert anzugeben.
-
Stellen Sie Pufferspeicher für die InputBuffer- und OutputBuffer-Parameter der WdfIoTargetSendIoctlSynchronously-Methode bereit, wenn dies für die Anforderung erforderlich ist.
Ihr Treiber kann diesen Pufferspeicher als lokal zugeordnete Puffer, wie WDFMEMORY behandelt, oder als Speicherdeskriptorlisten (Memory Descriptor Lists, MDLs) angeben. Sie können die methode verwenden, die am bequemsten ist.
Bei Bedarf konvertiert das Framework die Pufferbeschreibungen so, dass sie für den Übertragungstyp der IOCTL korrekt sind. Weitere Informationen zu IOCTL-Übertragungstypen finden Sie unter Definieren von E/A-Kontrollcodes.
Die folgenden Techniken zum Angeben des Pufferspeichers sind verfügbar:
-
Geben Sie lokale Puffer an.
Da WdfIoTargetSendIoctlSynchronously E/A-Anforderungen synchron verarbeitet, kann der Treiber Anforderungspuffer erstellen, die für die aufrufende Routine lokal sind, wie im folgenden Codebeispiel gezeigt.
WDF_MEMORY_DESCRIPTOR MemoryDescriptor; MY_BUFFER_TYPE MyBuffer; WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&MemoryDescriptor, (PVOID) &MyBuffer, sizeof(MyBuffer));
-
Geben Sie WDFMEMORY-Handles an.
Rufen Sie WdfMemoryCreate oder WdfMemoryCreatePreallocated auf, um ein Handle für den vom Framework verwalteten Speicher zu erhalten, wie im folgenden Codebeispiel gezeigt.
WDF_MEMORY_DESCRIPTOR MemoryDescriptor; WDFMEMORY MemoryHandle = NULL; status = WdfMemoryCreate(NULL, NonPagedPool, POOL_TAG, MY_BUFFER_SIZE, &MemoryHandle, NULL); WDF_MEMORY_DESCRIPTOR_INIT_HANDLE(&MemoryDescriptor, MemoryHandle, NULL);
Alternativ kann der Treiber WdfRequestRetrieveInputMemory oder WdfRequestRetrieveOutputMemory aufrufen, um ein Handle für ein Frameworkspeicherobjekt zu erhalten, das den Puffer einer empfangenen E/A-Anforderung darstellt, wenn der Treiber den Inhalt dieses Puffers an das E/A-Ziel übergibt. Der Treiber darf die empfangene E/A-Anforderung erst abschließen, wenn die neue Anforderung, die WdfIoTargetSendIoctlSynchronously an das E/A-Ziel sendet, gelöscht, wiederverwendet oder neu formatiert wurde. (WdfIoTargetSendIoctlSynchronously erhöht die Referenzanzahl des Speicherobjekts. Durch das Löschen, Wiederverwenden oder Neuformatieren eines Anforderungsobjekts wird die Referenzanzahl des Speicherobjekts verringert.)
-
Geben Sie MDLs an.
Treiber können MDLs abrufen, die einer empfangenen E/A-Anforderung zugeordnet sind, indem sie WdfRequestRetrieveInputWdmMdl und WdfRequestRetrieveOutputWdmMdl aufrufen.
-
Geben Sie lokale Puffer an.
Weitere Informationen zu WdfIoTargetSendIoctlSynchronously 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 lokaler Puffer definiert, eine WDF_MEMORY_DESCRIPTOR-Struktur initialisiert und WdfIoTargetSendIoctlSynchronously aufgerufen. In diesem Beispiel wird NULL für das Anforderungsobjekthandle angegeben, sodass das Framework ein neues Anforderungsobjekt für das E/A-Ziel erstellt.
WDF_MEMORY_DESCRIPTOR outputDescriptor;
NTSTATUS status;
HID_COLLECTION_INFORMATION collectionInformation;
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
&outputDescriptor,
(PVOID) &collectionInformation,
sizeof(HID_COLLECTION_INFORMATION)
);
status = WdfIoTargetSendIoctlSynchronously(
hidTarget,
NULL,
IOCTL_HID_GET_COLLECTION_INFORMATION,
NULL,
&outputDescriptor,
NULL,
NULL
);
Anforderungen
Anforderung | Wert |
---|---|
Zielplattform | Universell |
KMDF-Mindestversion | 1.0 |
UMDF-Mindestversion | 2.0 |
Kopfzeile | wdfiotarget.h (include Wdf.h) |
Bibliothek | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
IRQL | PASSIVE_LEVEL |
DDI-Complianceregeln | DeferredRequestCompleted(kmdf), DriverCreate(kmdf), InternalIoctlReqs(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), ReadReqs(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf), SyncReqSend(kmdf), WriteReqs(kmdf) |
Weitere Informationen
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER
WdfIoTargetFormatRequestForIoctl
WdfIoTargetSendInternalIoctlSynchronously
WdfRequestCompleteWithInformation
WdfRequestRetrieveOutputMemory
Feedback
https://aka.ms/ContentUserFeedback.
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unterFeedback senden und anzeigen für