WdfRequestSend-Funktion (wdfrequest.h)

[Gilt für KMDF und UMDF]

Die WdfRequestSend-Methode sendet eine angegebene I/O-Anforderung an ein angegebenes I/O-Ziel.

Syntax

BOOLEAN WdfRequestSend(
  [in] WDFREQUEST                Request,
  [in] WDFIOTARGET               Target,
       PWDF_REQUEST_SEND_OPTIONS Options
);

Parameter

[in] Request

Ein Handle zu einem Framework-Anforderungsobjekt.

[in] Target

Ein Handle zu einem Framework-I/O-Zielobjekt. Weitere Informationen zum Abrufen dieses Handle finden Sie im folgenden Abschnitt "Hinweise".

Options

Ein Zeiger auf eine WDF_REQUEST_SEND_OPTIONS Struktur, die Anrufer-bereitgestellte Anforderungsoptionen enthält. Dieser Parameter ist optional und kann NULL sein, wenn Sie keine Anforderungsoptionen aktivieren möchten.

Rückgabewert

WdfRequestSend gibt TRUE zurück, wenn die Anforderung an das Ziel gesendet wurde. Andernfalls gibt diese Methode FALSE zurück.

Eine Fehlerprüfung tritt auf, wenn der Treiber einen ungültigen Objekthandpunkt bereitstellt.

Bemerkungen

Das Anforderungsobjekt, das der Treiber für den Anforderungsparameter angibt, kann eine sein, die sie empfangen hat oder eine, die sie erstellt hat, indem sie die WdfRequestCreate-Methode aufruft .

Zum Abrufen eines Handles für ein I/O-Zielobjekt kann der Treiber eine der folgenden Aktionen ausführen:

Standardmäßig liefert WdfRequestSend die Anforderung asynchron an das Ziel, was bedeutet, dass er sofort zurückgibt, ohne darauf zu warten, dass die Anforderung abgeschlossen werden soll. Optional kann die Anforderung synchron übermittelt werden, was bedeutet, dass WdfRequestSend erst zurückgegeben wird, wenn ein Treiber die Anforderung abgeschlossen hat. Um die Anforderung synchron zu senden, muss der Treiber das WDF_REQUEST_SEND_OPTION_SYNCHRONOUS Flag in der WDF_REQUEST_SEND_OPTIONS-Struktur festlegen.

Wenn WdfRequestSend fehlschlägt oder wenn Der Treiber das WDF_REQUEST_SEND_OPTION_SYNCHRONOUS-Flag festlegt, kann der Treiber WdfRequestGetStatus unmittelbar nach dem Aufrufen von WdfRequestSend aufrufen.

Wenn WdfRequestSend erfolgreich ist und der Treiber das WDF_REQUEST_SEND_OPTION_SYNCHRONOUS-Flag nicht festgelegt hat, ruft der Treiber in der Regel WdfRequestGetStatus innerhalb einer CompletionRoutine-Rückruffunktion auf.

Wenn der Treiber die Anforderung synchron sendet, empfehlen wir, dass der Treiber einen Timeoutwert in der WDF_REQUEST_SEND_OPTIONS-Struktur und das Timeout-Flag im Flags-Element dieser Struktur festlegen.

Wenn der Treiber einen Timeoutwert bereitstellt, sollte WdfRequestAllocateTimer vor dem Aufrufen von WdfRequestSend aufgerufen werden. Dadurch wird sichergestellt, dass WdfRequestSend nicht fehlschlägt, wenn nicht genügend Systemressourcen vorhanden sind, um einen Zeitgeber zuzuweisen.

Wenn der Treiber das WDF_REQUEST_SEND_OPTION_SYNCHRONOUS-Flag festlegt, muss er WdfRequestSend bei IRQL = PASSIVE_LEVEL aufrufen. Wenn dieses Flag nicht festgelegt ist, muss der Treiber diese Methode bei IRQL <= DISPATCH_LEVEL aufrufen. WdfRequestSend sendet die Anforderung an die IRQL des Anrufers.

Ein Treiber kann WdfRequestSend nicht aufrufen, um eine I/O-Anforderung an ein USB-Rohr zu senden, wenn der Treiber eine fortlaufende Leseausgabe für das Rohr konfiguriert hat.

Beim Senden einer Anforderung an einen UMDF-Treiber muss ein Kernelmodustreiber die IRQL-Einschränkungen befolgen, die in der Unterstützung von Kernel-Mode Clients in UMDF-Treibern beschrieben sind.

Weitere Informationen zu WdfRequestSend finden Sie unter Weiterleitung von I/O-Anforderungen.

Beispiele

Im folgenden Codebeispiel handelt es sich um eine gekürzte Version einer EvtIoWrite-Rückruffunktion aus dem kmdf_fx2 Beispieltreiber. Die Funktion überprüft die Pufferlänge der Anforderung, ruft einen Handle zum Puffer ab, formatiert die Anforderung für ein USB-Ziel und sendet die Anforderung.

VOID 
OsrFxEvtIoWrite(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN size_t  Length
    )
{
    WDFUSBPIPE  pipe;
    NTSTATUS  status;
    WDFMEMORY  reqMemory;
    PDEVICE_CONTEXT  pDeviceContext;

    UNREFERENCED_PARAMETER(Queue);
    //
    // Check if the transfer size is valid.
    //
    if (Length > MAX_TRANSFER_BUFFER_SIZE) {
        status = STATUS_INVALID_PARAMETER;
        goto Exit;
    }
    //
    // Get driver-defined context space from
    // the device object. The driver stored the
    // pipe handle there.
    //
    pDeviceContext = GetDeviceContext(WdfIoQueueGetDevice(Queue));
    pipe = pDeviceContext->BulkWritePipe;
 
    //
    // Get a handle to a memory object that represents
    // the input buffer.
    //
    status = WdfRequestRetrieveInputMemory(Request, &reqMemory);
    if (!NT_SUCCESS(status)){
        goto Exit;
    }
    //
    // Format the request so it can be sent to a USB target.
    //
    status = WdfUsbTargetPipeFormatRequestForWrite(
                            pipe,
                            Request,
                            reqMemory,
                            NULL // Offsets
                            ); 
    if (!NT_SUCCESS(status)) {
        goto Exit;
    }
    //
    // Set a CompletionRoutine callback function.
    //
    WdfRequestSetCompletionRoutine(
                            Request,
                            EvtRequestReadCompletionRoutine,
                            pipe
                            );
    //
    // Send the request. If an error occurs, complete the request.
    //
    if (WdfRequestSend(
                       Request,
                       WdfUsbTargetPipeGetIoTarget(pipe),
                       WDF_NO_SEND_OPTIONS
                       ) == FALSE) {
        status = WdfRequestGetStatus(Request);
        goto Exit;
    }
Exit:
    if (!NT_SUCCESS(status)) {
        WdfRequestCompleteWithInformation(
                                          Request,
                                          status,
                                          0
                                          );
    }
    return;
}

Anforderungen

   
Zielplattform Universell
KMDF-Mindestversion 1.0
UMDF-Mindestversion 2.0
Header wdfrequest.h (enthalten Wdf.h)
Bibliothek Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL Siehe Abschnitt "Hinweise".
DDI-Complianceregeln DeferredRequestCompleted(kmdf), DriverCreate(kmdf), InvalidReqAccess(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), ReqCompletionRoutine(kmdf), ReqMarkCancelableSend(kmdf), ReqSendFail(kmdf), ReqSendWhileSpinlock(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf), RequestFormattedValid(kmdf), RequestGetStatusValid(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), SyncReqSend2(kmdf), WdfRequestSendSyncAtDispatch(kmdf), WdfRequestSendSyncAtDispatch2(kmdf)

Weitere Informationen

CompletionRoutine

WDF_REQUEST_SEND_OPTIONS

WdfDeviceGetIoTarget

WdfRequestAllocateTimer

WdfRequestCreate

WdfRequestGetStatus