WdfIoTargetFormatRequestForInternalIoctl-Funktion (wdfiotarget.h)

[Gilt nur für KMDF]

Die WdfIoTargetFormatRequestForInternalIoctl-Methode erstellt eine interne Gerätesteuerungsanforderung für ein I/O-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 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] Request

Ein Handle zu einem Framework-Anforderungsobjekt. 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 Handle zu einem Framework-Speicherobjekt. 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 aufrufer-zugeordnete WDFMEMORY_OFFSET Struktur, die optionale Byte-Offset- 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 ist die Puffergröße.

[in, optional] OutputBuffer

Ein Handle zu einem Framework-Speicherobjekt. Dieses Objekt stellt einen Puffer dar, der Daten vom I/O-Ziel empfängt. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in, optional] OutputBufferOffset

Ein Zeiger auf eine aufrufer-zugeordnete WDFMEMORY_OFFSET Struktur, die optionale Byte-Offset- 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 ist die Puffergröße.

Rückgabewert

WdfIoTargetFormatRequestForInternalIoctl gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich verläuft. 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_INVALID_DEVICE_REQUEST
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.
STATUS_INSUFFICIENT_RESOURCES
Das Framework konnte keine Systemressourcen (in der Regel Arbeitsspeicher) zuordnen.
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 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 I/O-Steuerelementcodes.

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 WdfIoTargetFormatRequestForInternalIoctl-Methode an.
  2. Verwenden Sie den Eingabepuffer der empfangenen Anforderung für den InputBuffer-Parameter der WdfIoTargetFormatRequestForInternalIoctl-Methode.

    Der Treiber muss WdfRequestRetrieveInputMemory aufrufen, um einen Handle für den Eingabepuffer der Anforderung abzurufen, und er muss diesen Handle als Wert für InputBuffer verwenden.

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

    Der Treiber muss WdfRequestRetrieveOutputMemory aufrufen, um einen Handle für den Ausgabepuffer der Anforderung abzurufen, und er muss diesen Handle als Wert für OutputBuffer verwenden.

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. Erstellen Sie ein neues Anforderungsobjekt, und geben Sie dessen Handle für den Anforderungsparameter der WdfIoTargetFormatRequestForInternalIoctl-Methode an.

    Rufen Sie WdfRequestCreate auf, um mindestens ein Anforderungsobjekt vorzuallocatieren. Sie können diese Anforderungsobjekte wiederverwenden, indem Sie WdfRequestReuse aufrufen. Die Rückruffunktion Des Treibers EvtDriverDeviceAdd kann Anforderungsobjekte für ein Gerät vorschreiben.

  2. Stellen Sie Pufferraum bereit, und geben Sie den Handle des Puffers für die Parameter "WdfIoTargetFormatRequestForInternalIoctl " der InputBuffer - und OutputBuffer-Methode an.

    Ihr Treiber muss diesen Pufferspeicher angeben, da WDFMEMORY den vom Framework verwalteten Arbeitsspeicher verarbeitet. Ihr Treiber kann eine der folgenden Aktionen ausführen:

    Wenn Ihr Treiber WdfRequestRetrieveInputMemory oder WdfRequestRetrieveOutputMemory aufruft und den Speicherhandpunkt an WdfIoTargetFormatRequestForInternalIoctl übergibt, muss der Treiber die empfangene I/O-Anforderung erst abschließen, nachdem der Treiber das neue, vom Treiber erstellte Anforderungsobjekt gelöscht, wiederverwendet oder reformiert hat. (WdfIoTargetFormatRequestForInternalIoctl erhöht die Referenzanzahl des Speicherobjekts. Das Löschen, Erneute Verwenden oder Neuattieren eines Anforderungsobjekts erhöht die Referenzanzahl des Speicherobjekts.)
Nachdem ein Treiber WdfIoTargetFormatRequestForInternalIoctl aufgerufen hat, um eine Gerätesteuerungsanforderung zu formatieren, muss der Treiber WdfRequestSend aufrufen, um die Anforderung (synchron oder asynchron) an ein I/O-Ziel zu senden.

Mehrere Aufrufe an WdfIoTargetFormatRequestForInternalIoctl , die dieselbe Anforderung verwenden, verursachen keine zusätzlichen Ressourcenzuweisungen. Um die Chance zu verringern, dass WdfRequestCreate STATUS_INSUFFICIENT_RESOURCES zurückgibt, kann die Rückruffunktion Des Treibers EvtDriverDeviceAddWdfRequestCreate aufrufen, um ein oder mehrere Anforderungsobjekte für ein Gerät vorzuladen. Der Treiber kann anschließend wiederverwendet werden ( WdfRequestReuse aufrufen), umformatieren ( WdfIoTargetFormatRequestForInternalIoctl) und erneut senden ( Aufrufen von WdfRequestSend) jedes Anforderungsobjekt ohne Risiko eines STATUS_INSUFFICIENT_RESOURCES Rückgabewerts von einem späteren Aufruf von WdfRequestCreate. Alle nachfolgenden Aufrufe von WdfIoTargetFormatRequestForInternalIoctl für das wiederverwendete Anforderungsobjekt geben STATUS_SUCCESS zurück, wenn Parameterwerte nicht geändert werden. (Wenn der Treiber jedoch die gleiche Anforderungsformatierungsmethode nicht jedes Mal aufruft, werden möglicherweise zusätzliche Ressourcen zugewiesen. Wenn der I/O-Steuerelementcode einen Übertragungstyp von METHOD_BUFFERED angibt, muss das Framework einen Systempuffer für jede Anforderung zuweisen, und diese Zuordnung kann aufgrund unzureichender Speicherressourcen fehlschlagen.)

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

Weitere Informationen zu WdfIoTargetFormatRequestForInternalIoctl 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 Framework-Speicherobjekt 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 I/O-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

   
Zielplattform Universell
KMDF-Mindestversion 1.0
Header wdfiotarget.h (include Wdf.h)
Bibliothek Wdf01000.sys (siehe Framework-Bibliotheksversioning.)
IRQL <=DISPATCH_LEVEL
DDI-Complianceregeln DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf)

Weitere Informationen

EvtDriverDeviceAdd

WDFMEMORY_OFFSET

WdfDeviceGetIoTarget

WdfIoTargetCreate

WdfIoTargetFormatRequestForIoctl

WdfIoTargetSendInternalIoctlSynchronously

WdfIoTargetSendIoctlSynchronly

WdfMemoryCreate

WdfMemoryCreatePreallocated

WdfRequestCreate

WdfRequestRetrieveInputMemory

WdfRequestRetrieveOutputMemory

WdfRequestReuse

WdfRequestSend