WdfIoTargetSendInternalIoctlSynchronously-Funktion (wdfiotarget.h)

[Gilt nur für KMDF]

Die WdfIoTargetSendInternalIoctlSynchronously-Methode erstellt eine interne Gerätesteuerungsanforderung und sendet sie synchron an ein I/O-Ziel.

Syntax

NTSTATUS WdfIoTargetSendInternalIoctlSynchronously(
  [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 zu einem lokalen oder Remote-I/O-Zielobjekt, das von einem vorherigen Aufruf von WdfDeviceGetIoTarget oder WdfIoTargetCreate oder von einer Methode abgerufen wurde, die ein spezielles I/O-Ziel bereitstellt.

[in, optional] Request

Ein Handle zu einem Framework-Anforderungsobjekt. Dieser Parameter ist optional und kann NULL sein. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in] IoctlCode

Ein I/O-Steuerelementcode (IOCTL), den das I/O-Ziel unterstützt.

[in, optional] InputBuffer

Ein Zeiger auf eine aufgerufene WDF_MEMORY_DESCRIPTOR Struktur, die einen Puffer beschreibt, der in das I/O-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 aufgerufene WDF_MEMORY_DESCRIPTOR Struktur, die einen Puffer beschreibt, der Daten vom I/O-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 WDF_REQUEST_SEND_OPTIONS Struktur zugeordnete Aufrufer, 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 Bytes, die übertragen wurden), die ein anderer Treiber liefert, wenn er die Anforderung durch Aufrufen von WdfRequestCompleteWithInformation abschließt. Dieser Zeiger ist optional und kann NULL sein.

Rückgabewert

Wenn der Vorgang erfolgreich verläuft, gibt WdfIoTargetSendInternalIoctlSynchronously zurück, nachdem die interne Gerätesteuerungsanforderung abgeschlossen ist, und der Rückgabewert ist der Abschlussstatuswert der Anforderung. Andernfalls gibt diese Methode möglicherweise einen der folgenden Werte zurück:

Rückgabecode Beschreibung
STATUS_INVALID_PARAMETER
Ein ungültiger Parameter wurde erkannt.
STATUS_INFO_LENGTH_MISMATCH
Die Größe der WDF_REQUEST_SEND_OPTIONS Struktur, auf die der RequestOptions-Parameter verweist, war falsch.
STATUS_INVALID_DEVICE_REQUEST
Die Anforderung wurde bereits an ein E/A-Ziel in die Warteschlange gestellt.
STATUS_INSUFFICIENT_RESOURCES
Das Framework konnte keine Systemressourcen (in der Regel Arbeitsspeicher) zuordnen.
STATUS_IO_TIMEOUT
Der Treiber hat einen Timeoutwert angegeben, und die Anforderung wurde innerhalb der zugewiesenen Zeit nicht abgeschlossen.
STATUS_REQUEST_NOT_ACCEPTED
Das I/O-Anforderungspaket (IRP), das der Anforderungsparameter darstellt, stellt nicht genügend IO_STACK_LOCATION Strukturen bereit, 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.

Bemerkungen

Verwenden Sie die WdfIoTargetSendInternalIoctlSynchronously-Methode , um interne Gerätesteuerungsanforderungen synchron zu senden. Um interne Gerätesteuerungsanforderungen asynchron zu senden, verwenden Sie die WdfIoTargetFormatRequestForInternalIoctl-Methode , gefolgt von der WdfRequestSend-Methode .

Weitere Informationen zu internen Gerätesteuerungsanforderungen finden Sie unter Verwenden von I/O-Steuerelementcodes.

Die WdfIoTargetSendInternalIoctlSynchronously-Methode gibt erst zurück, wenn die Anforderung abgeschlossen wurde, es sei denn, der Treiber liefert einen Timeoutwert in der WDF_REQUEST_SEND_OPTIONS Struktur des RequestOptions-Parameters oder es sei denn, ein Fehler wird erkannt.

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 einen Pufferspeicher.

So leiten Sie eine interne Gerätesteuerungsanforderung weiter, die Ihr Treiber in einer E/A-Warteschlange empfangen hat:

  1. Geben Sie den Handle der empfangenen Anforderung für den Anforderungsparameter der WdfIoTargetSendInternalIoctlSynchronously-Methode an.
  2. Verwenden Sie den Eingabepuffer der empfangenen Anforderung für den InputBuffer-Parameter der WdfIoTargetSendInternalIoctlSynchronously-Methode.

    Der Treiber muss WdfRequestRetrieveInputMemory aufrufen, um einen Handle für den Eingabepuffer der Anforderung abzurufen. Der Treiber muss dann den Handle in der WDF_MEMORY_DESCRIPTOR Struktur platzieren, die der Treiber für den InputBuffer-Parameter bereitstellt.

  3. Verwenden Sie den Ausgabepuffer der empfangenen Anforderung für den OutputBuffer-Parameter der WdfIoTargetSendInternalIoctlSynchronously-Methode.

    Der Treiber muss WdfRequestRetrieveOutputMemory aufrufen, um einen Handle für den Ausgabepuffer der Anforderung abzurufen, und er muss dann den Handle in der WDF_MEMORY_DESCRIPTOR Struktur platzieren, die der Treiber für den OutputBuffer-Parameter bereitstellt.

Weitere Informationen zum Weiterleiten einer E/A-Anforderung finden Sie unter Weiterleitung von E/A-Anforderungen.

Treiber teilen häufig empfangene E/A-Anforderungen 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:

  1. Geben Sie einen NULL-Anforderungshandpunkt für den Anforderungsparameter der WdfIoTargetSendInternalIoctlSynchronously-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 können Sie die EvtDriverDeviceAdd-Rückruffunktion Ihres Treibers zum Vorallokaten von Anforderungsobjekten für ein Gerät verwenden. Darüber hinaus kann ein anderer Treiberthread WdfRequestCancelSentRequest aufrufen, um die Anforderung bei Bedarf abzubrechen.

    Ihr Treiber kann einen Parameter ohneNULL-Anforderungsoptions angeben, unabhängig davon, ob der Treiber einen Nicht-NULL- oder einen NULL-Anforderungsparameter bereitstellt. Sie können z. B. den Parameter RequestOptions verwenden, um einen Timeoutwert anzugeben.

  2. Stellen Sie Pufferspeicher für die Parameter "InputBuffer" und "OutputBuffer" für die WdfIoTargetSendInternalIoctlSynchronously-Methode bereit, wenn die Anforderung sie erfordert.

    Ihr Treiber kann diesen Pufferraum als lokal zugewiesene Puffer angeben, da WDFMEMORY-Handle oder Speicherdeskriptorlisten (MDLs) verwendet werden. Sie können verwenden, welche Methode am bequemsten ist.

    Bei Bedarf konvertiert das Framework die Pufferbeschreibungen so, dass sie für den Übertragungstyp des IOCTL korrekt sind. Weitere Informationen zu IOCTL-Übertragungstypen finden Sie unter Definieren von I/O-Steuerelementcodes.

    Die folgenden Techniken zum Angeben des Pufferraums sind verfügbar:

    • Geben Sie lokale Puffer an.

      Da WdfIoTargetSendInternalIoctlSynchronously I/O-Anforderungen synchron verarbeitet, kann der Treiber Anforderungspuffer erstellen, die lokal für die Aufrufroutine sind, wie das folgende Codebeispiel zeigt.

      WDF_MEMORY_DESCRIPTOR  MemoryDescriptor;
      MY_BUFFER_TYPE  MyBuffer;
      WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&MemoryDescriptor,
                                        (PVOID) &MyBuffer,
                                        sizeof(MyBuffer));
      
    • Geben Sie WDFMEMORY-Ziehpunkte an.

      Rufen Sie WdfMemoryCreate oder WdfMemoryCreatePreallocated auf, um ein Handle für den vom Framework verwalteten Arbeitsspeicher abzurufen, wie das folgende Codebeispiel veranschaulicht.

      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 Framework-Speicherobjekt abzurufen, das den Puffer einer empfangenen E/A-Anforderung darstellt, wenn der Treiber den Inhalt dieses Puffers an das I/O-Ziel übergeben soll. Der Treiber darf die empfangene E/A-Anforderung erst abschließen, wenn die neue Anforderung , die WdfIoTargetSendInternalIoctlSynchronously sendet, an das I/O-Ziel gelöscht, wiederverwendet oder neu formatiert wurde. (WdfIoTargetSendInternalIoctlSynchronously erhöht die Referenzanzahl des Speicherobjekts. Das Löschen, Erneute Verwenden oder Neuattieren eines Anforderungsobjekts erhöht die Referenzanzahl des Speicherobjekts.)

    • Geben Sie MDLs an.

      Treiber können MDLs abrufen, die einer empfangenen E/A-Anforderung zugeordnet sind, indem WdfRequestRetrieveInputWdmMdl und WdfRequestRetrieveOutputWdmMdl aufgerufen werden.

Informationen zum Abrufen von Statusinformationen nach Abschluss einer E/A-Anforderung finden Sie unter Abrufen von Abschlussinformationen.

Weitere Informationen zu WdfIoTargetSendInternalIoctlSynchronously finden Sie unter Senden von I/O-Anforderungen an allgemeine I/O-Ziele.

Weitere Informationen zu I/O-Zielen finden Sie unter Verwenden von I/O-Zielen.

Beispiele

Im folgenden Codebeispiel wird ein lokaler Puffer definiert, eine WDF_MEMORY_DESCRIPTOR Struktur initialisiert und WdfIoTargetSendInternalIoctlSynchronously aufgerufen. In diesem Beispiel wird NULL für das Anforderungsobjekthandling angegeben, sodass das Framework ein neues Anforderungsobjekt für das I/O-Ziel erstellt.

WDF_MEMORY_DESCRIPTOR  outputDescriptor;
NTSTATUS  status;
MY_DRIVER_INFORMATION  driverInformation;

WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
                                  &outputDescriptor,
                                  (PVOID) &driverInformation,
                                  sizeof(MY_DRIVER_INFORMATION)
                                  );

status = WdfIoTargetSendInternalIoctlSynchronously(
                                                   hidTarget,
                                                   NULL,
                                                   IOCTL_INTERNAL_GET_MY_DRIVER_INFORMATION,
                                                   NULL,
                                                   &outputDescriptor,
                                                   NULL,
                                                   NULL
                                                   );

Anforderungen

   
Zielplattform Universell
KMDF-Mindestversion 1.0
Header wdfiotarget.h (include Wdf.h)
Bibliothek Wdf01000.sys (siehe Framework-Bibliotheksversioning.)
IRQL PASSIVE_LEVEL
DDI-Complianceregeln DeferredRequestCompleted(kmdf), DriverCreate(kmdf), IoctlReqs(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit( kmdf), ReadReqs(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf), WriteReqs(kmdf)

Weitere Informationen

EvtDriverDeviceAdd

WDF_MEMORY_DESCRIPTOR

WDF_REQUEST_SEND_OPTIONS

WdfDeviceGetIoTarget

WdfIoTargetCreate

WdfIoTargetFormatRequestForInternalIoctl

WdfIoTargetSendIoctlSynchronly

WdfMemoryCreate

WdfMemoryCreatePreallocated

WdfRequestCancelSentRequest

WdfRequestCompleteWithInformation

WdfRequestCreate

WdfRequestRetrieveInputMemory

WdfRequestRetrieveInputWdmMdl

WdfRequestRetrieveOutputMemory

WdfRequestRetrieveOutputWdmMdl

WdfRequestReuse

WdfRequestSend