WdfIoTargetFormatRequestForInternalIoctlOthers-Funktion (wdfiotarget.h)

Artikel
08/08/2023

[Gilt nur für KMDF]

Die WdfIoTargetFormatRequestForInternalIoctlOthers-Methode erstellt eine nicht standardmäßige interne Gerätesteuerungsanforderung für ein E/A-Ziel, sendet die Anforderung jedoch nicht.

Syntax

NTSTATUS WdfIoTargetFormatRequestForInternalIoctlOthers(
  [in]           WDFIOTARGET       IoTarget,
  [in]           WDFREQUEST        Request,
  [in]           ULONG             IoctlCode,
  [in, optional] WDFMEMORY         OtherArg1,
  [in, optional] PWDFMEMORY_OFFSET OtherArg1Offset,
  [in, optional] WDFMEMORY         OtherArg2,
  [in, optional] PWDFMEMORY_OFFSET OtherArg2Offset,
  [in, optional] WDFMEMORY         OtherArg4,
  [in, optional] PWDFMEMORY_OFFSET OtherArg4Offset
);

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] OtherArg1

Ein Handle für ein Frameworkspeicherobjekt. Dieses Objekt stellt einen Puffer dar, den der Treiber für anforderungsspezifische, treiberdefinierte Kontextinformationen verwendet. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise". Dieser Parameter ist optional und kann NULL sein.

[in, optional] OtherArg1Offset

Ein Zeiger auf eine vom Aufrufer zugewiesene WDFMEMORY_OFFSET Struktur, die optionale Byteoffset- und Längenwerte bereitstellt. Treiber können diese Werte verwenden, um die Anfangsadresse und Länge eines Segments des Kontextbereichs anzugeben, der von OtherArg1 angegeben wird. Dieser Parameter ist optional und kann NULL sein.

[in, optional] OtherArg2

[in, optional] OtherArg2Offset

Ein Zeiger auf eine vom Aufrufer zugewiesene WDFMEMORY_OFFSET Struktur, die optionale Byteoffset- und Längenwerte bereitstellt. Treiber können diese Werte verwenden, um die Anfangsadresse und länge eines Segments des Kontextbereichs anzugeben, der von OtherArg2 angegeben wird. Dieser Parameter ist optional und kann NULL sein.

[in, optional] OtherArg4

[in, optional] OtherArg4Offset

Ein Zeiger auf eine vom Aufrufer zugewiesene WDFMEMORY_OFFSET Struktur, die optionale Byteoffset- und Längenwerte bereitstellt. Treiber können diese Werte verwenden, um die Anfangsadresse und länge eines Segments des Kontextbereichs anzugeben, der von OtherArg4 angegeben wird. Dieser Parameter ist optional und kann NULL sein.

Rückgabewert

WdfIoTargetFormatRequestForInternalIoctlOthers 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 WdfIoTargetFormatRequestForInternalIoctlOthers-Methode gefolgt von der WdfRequestSend-Methode , um nicht standardmäßige interne Gerätesteuerungsanforderungen synchron oder asynchron zu senden. Alternativ können Sie die WdfIoTargetSendInternalIoctlOthersSynchronously-Methode verwenden, um nicht standardmäßige interne Gerätesteuerungsanforderungen synchron zu senden.

Sie können eine nicht standardmäßige 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 etwas Pufferspeicher.

So leiten Sie eine nicht standardmäßige interne 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 WdfIoTargetFormatRequestForInternalIoctlOthers-Methode an.
Verwenden Sie die Kontextinformationen der empfangenen Anforderung für die OtherArg1-, OtherArg2- und OtherArg4-Parameter der WdfIoTargetFormatRequestForInternalIoctlOthers-Methode.
Um diese Parameterwerte abzurufen, muss der Treiber WdfRequestGetParameters aufrufen und das DeviceIoControl-Element der zurückgegebenen WDF_REQUEST_PARAMETERS Struktur 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 WdfIoTargetFormatRequestForInternalIoctlOthers-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.
Stellen Sie Kontextpuffer bereit, wenn die Anforderung diese erfordert, und geben Sie Pufferhandles für die Parameter OtherArg1, OtherArg2 und OtherArg4 der WdfIoTargetFormatRequestForInternalIoctlOthers-Methode an.
Ihr Treiber muss diesen Pufferspeicher angeben, der von WDFMEMORY in den vom Framework verwalteten Arbeitsspeicher verarbeitet wird. Um WDFMEMORY-Handles abzurufen, ruft der Treiber WdfMemoryCreate oder WdfMemoryCreatePreallocated auf.

Nachdem ein Treiber WdfIoTargetFormatRequestForInternalIoctlOthers 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 WdfIoTargetFormatRequestForInternalIoctlOthers , 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 WdfIoTargetFormatRequestForInternalIoctlOthers) und erneut senden (aufrufen WdfRequestSend), ohne einen STATUS_INSUFFICIENT_RESOURCES Rückgabewert aus einem späteren Aufruf von WdfRequestCreate zu riskieren. (Wenn der Treiber nicht jedes Mal dieselbe Methode zur Anforderungsformatierung aufruft, werden möglicherweise zusätzliche Ressourcen zugewiesen.) Alle nachfolgenden Aufrufe von WdfIoTargetFormatRequestForInternalIoctlOthers für das wiederverwendete Anforderungsobjekt geben STATUS_SUCCESS zurück, wenn sich die Parameterwerte nicht ändern.

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

Weitere Informationen zu WdfIoTargetFormatRequestForInternalIoctlOthers 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 Frameworkspeicherobjekt erstellt, der Puffer abgerufen, den das Speicherobjekt enthält, und den Puffer initialisiert. Anschließend formatiert das Beispiel die Anforderung, legt eine CompletionRoutine-Rückruffunktion fest und sendet die Anforderung an ein E/A-Ziel.

PIRB pIrb;
WDFMEMORY memory;
NTSTATUS status;

status = WdfMemoryCreate(
                         WDF_NO_OBJECT_ATTRIBUTES,
                         NonPagedPool,
                         0,
                         sizeof(IRB),
                         &memory,
                         NULL
                         );
if (!NT_SUCCESS(status)) {
    goto Done;
}
pIrb = WdfMemoryGetBuffer(
                          memory,
                          NULL
                          );

pIrb->FunctionNumber = REQUEST_ALLOCATE_ADDRESS_RANGE;
pIrb->Flags = 0;
pIrb->u.AllocateAddressRange.Mdl = pAsyncAddressData->pMdl;
pIrb->u.AllocateAddressRange.fulFlags = fulFlags;
pIrb->u.AllocateAddressRange.nLength = nLength;
pIrb->u.AllocateAddressRange.MaxSegmentSize = MaxSegmentSize;
pIrb->u.AllocateAddressRange.fulAccessType = fulAccessType;
pIrb->u.AllocateAddressRange.fulNotificationOptions = fulNotificationOptions;
pIrb->u.AllocateAddressRange.Callback = NULL;
pIrb->u.AllocateAddressRange.Context = NULL;
pIrb->u.AllocateAddressRange.Required1394Offset = *Required1394Offset;
pIrb->u.AllocateAddressRange.FifoSListHead = NULL;
pIrb->u.AllocateAddressRange.FifoSpinLock = NULL;
pIrb->u.AllocateAddressRange.AddressesReturned = 0;
pIrb->u.AllocateAddressRange.p1394AddressRange = pAsyncAddressData->AddressRange;
pIrb->u.AllocateAddressRange.DeviceExtension = deviceExtension;

status = WdfIoTargetFormatRequestForInternalIoctlOthers(
                                                        IoTarget,
                                                        Request,
                                                        IOCTL_1394_CLASS,
                                                        memory,
                                                        NULL,
                                                        NULL,
                                                        NULL,
                                                        NULL,
                                                        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

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