WdfIoTargetFormatRequestForIoctl-Funktion (wdfiotarget.h)

Artikel
02/27/2024

[Gilt für KMDF und UMDF]

Die WdfIoTargetFormatRequestForIoctl-Methode erstellt eine Gerätesteuerungsanforderung für ein E/A-Ziel, sendet die Anforderung jedoch nicht.

Syntax

NTSTATUS WdfIoTargetFormatRequestForIoctl(
  [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 von einem spezialisierten E/A-Ziel bereitgestellt wird.

[in] Request

Ein Handle für ein Frameworkanforderungsobjekt. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in] IoctlCode

Ein E/A-Steuerungscode (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 vom Aufrufer zugewiesene WDFMEMORY_OFFSET Struktur, die optionale Byteoffset- und Längenwerte bereitstellt. Das Framework verwendet diese Werte, um die Anfangsadresse und 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 vom Aufrufer zugewiesene WDFMEMORY_OFFSET Struktur, die optionale Byteoffset- und Längenwerte bereitstellt. Das Framework verwendet diese Werte, um die Anfangsadresse und 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

WdfIoTargetFormatRequestForIoctl 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
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 vom Request-Parameter dargestellte E/A-Anforderungspaket (IRP) 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.

Hinweise

Verwenden Sie die WdfIoTargetFormatRequestForIoctl-Methode , gefolgt von der WdfRequestSend-Methode, um Gerätesteuerungsanforderungen synchron oder asynchron zu senden. Alternativ können Sie die WdfIoTargetSendIoctlSynchronously-Methode verwenden, um Gerätesteuerungsanforderungen synchron zu senden.

Weitere Informationen zu Gerätesteuerungsanforderungen finden Sie unter Verwenden von E/A-Steuerungscodes.

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

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 WdfIoTargetFormatRequestForIoctl-Methode an.
Verwenden Sie den Eingabepuffer der empfangenen Anforderung für den InputBuffer-Parameter der WdfIoTargetFormatRequestForIoctl-Methode.
Der Treiber muss WdfRequestRetrieveInputMemory aufrufen, um ein Handle für ein Framework-Speicherobjekt abzurufen, das den Eingabepuffer der Anforderung darstellt, und er muss dieses Handle als Wert für InputBuffer verwenden.
Verwenden Sie den Ausgabepuffer der empfangenen Anforderung für den OutputBuffer-Parameter der WdfIoTargetFormatRequestForIoctl-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.

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

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 WdfIoTargetFormatRequestForIoctl-Methode an.
Rufen Sie WdfRequestCreate auf , um ein oder mehrere Anforderungsobjekte vorab zuzulisten. 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 stellen Sie das Handle des Puffers für die InputBuffer- und OutputBuffer-Parameter der WdfIoTargetFormatRequestForIoctl-Methode bereit.
Ihr Treiber muss diesen Pufferspeicher angeben, der von WDFMEMORY in den vom Framework verwalteten Arbeitsspeicher verarbeitet wird. 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.
Wenn Ihr Treiber WdfRequestRetrieveInputMemory oder WdfRequestRetrieveOutputMemory aufruft und das Speicherhandle an WdfIoTargetFormatRequestForIoctl übergibt, darf der Treiber die empfangene E/A-Anforderung erst abschließen, nachdem der Treiber das neue, vom Treiber erstellte Anforderungsobjekt gelöscht, wiederverwendet oder neu formatiert hat. (WdfIoTargetFormatRequestForIoctl erhöht die Verweisanzahl des Speicherobjekts. Durch das Löschen, Erneutes Verwenden oder Neuformatieren eines Anforderungsobjekts wird die Verweisanzahl des Speicherobjekts verringert.)

Nachdem ein Treiber WdfIoTargetFormatRequestForIoctl zum Formatieren einer Gerätesteuerungsanforderung aufgerufen hat, muss der Treiber WdfRequestSend aufrufen, um die Anforderung (synchron oder asynchron) an ein E/A-Ziel zu senden.

Mehrere Aufrufe von WdfIoTargetFormatRequestForIoctl , die dieselbe Anforderung verwenden, verursachen keine zusätzlichen Ressourcenzuordnungen. Daher kann die EvtDriverDeviceAdd-Rückruffunktion Ihres Treibers WdfRequestCreate aufrufen, um die Möglichkeit zu verringern, dass WdfRequestCreate zurückgegeben STATUS_INSUFFICIENT_RESOURCES wird, um ein oder mehrere Anforderungsobjekte für ein Gerät vorab zuordnen. Der Treiber kann jedes Anforderungsobjekt anschließend wiederverwenden ( aufrufen WdfRequestReuse), neu formatieren (aufrufen von WdfIoTargetFormatRequestForIoctl) und erneut senden (aufrufen WdfRequestSend), ohne einen STATUS_INSUFFICIENT_RESOURCES Rückgabewert aus einem späteren Aufruf von WdfRequestCreate zu riskieren. Alle nachfolgenden Aufrufe von WdfIoTargetFormatRequestForIoctl für das wiederverwendete Anforderungsobjekt geben STATUS_SUCCESS zurück, wenn sich die Parameterwerte nicht ändern. (Wenn der Treiber nicht jedes Mal dieselbe Anforderungsformatierungsmethode aufruft, werden möglicherweise zusätzliche Ressourcen zugewiesen. Wenn der E/A-Steuerungscode einen Übertragungstyp von METHOD_BUFFERED angibt, muss das Framework für jede Anforderung einen Systempuffer zuweisen, und die 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 WdfIoTargetFormatRequestForIoctl 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

Der folgende Code verwendet ein vorab zugewiesenes Anforderungsobjekt und vorab zugeordnete Speicherobjekte wieder. Das Beispiel weist den Speicherobjekten Eingabe- und Ausgabepuffer zu, formatiert das Anforderungsobjekt, registriert eine CompletionRoutine-Rückruffunktion und sendet die Anforderung an ein E/A-Ziel.

NTSTATUS
NICSendOidRequestToTargetAsync(
    IN WDFIOTARGET  IoTarget,
    IN WDFREQUEST  Request,
    IN PFILE_OBJECT  FileObject,
    IN ULONG  IoctlControlCode,
    IN OUT PVOID  InputBuffer,
    IN ULONG  InputBufferLength,
    IN OUT PVOID  OutputBuffer,
    IN ULONG  OutputBufferLength,
    OUT PULONG  BytesReadOrWritten
    )
{
    NTSTATUS  status;
    PREQUEST_CONTEXT  reqContext;
    WDF_REQUEST_REUSE_PARAMS  params;
    WDFMEMORY  inputMem, outputMem;
 
    WDF_REQUEST_REUSE_PARAMS_INIT(
                                  &params, 
                                  WDF_REQUEST_REUSE_NO_FLAGS, 
                                  STATUS_SUCCESS
                                  );
    status = WdfRequestReuse(Request, &params);
    if (!NT_SUCCESS(status)){
        return status;
    }

    reqContext = GetRequestContext(Request);

    inputMem = outputMem = NULL;
 
    if (InputBuffer != NULL) {
        status = WdfMemoryAssignBuffer(
                                       reqContext->InputMemory,
                                       InputBuffer, 
                                       InputBufferLength
                                       );
        if (!NT_SUCCESS(status)) {
             return status;
        }
        inputMem = reqContext->InputMemory;
    }

    if (OutputBuffer != NULL) {
        status = WdfMemoryAssignBuffer(
                                       reqContext->OutputMemory,
                                       OutputBuffer, 
                                       OutputBufferLength
                                       );
        if (!NT_SUCCESS(status)) {
            return status;
        }
        outputMem = reqContext->OutputMemory;
    }

    status = WdfIoTargetFormatRequestForIoctl(
                                              IoTarget,
                                              Request,
                                              IoctlControlCode,
                                              inputMem,
                                              NULL,
                                              outputMem,
                                              NULL
                                              );
    if (!NT_SUCCESS(status)) {
        return status;
    }

    WdfRequestSetCompletionRoutine(
                                   Request,
                                   NICSendOidRequestToTargetAsyncCompletionRoutine,
                                   BytesReadOrWritten
                                   );

    if (WdfRequestSend(
                       Request,
                       IoTarget,
                       WDF_NO_SEND_OPTIONS
                       ) == FALSE) {
        status = WdfRequestGetStatus(Request);
    }
    return status;
}

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.0
UMDF-Mindestversion	2.0
Kopfzeile	wdfiotarget.h (einschließen von Wdf.h)
Bibliothek	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf)