WdfIoTargetSendInternalIoctlOthersSynchronously-Funktion (wdfiotarget.h)

Artikel
07/16/2024

[Gilt nur für KMDF]

Die WdfIoTargetSendInternalIoctlOthersSynchronously Methode erstellt eine nicht standardmäßige interne Gerätesteuerungsanforderung und sendet sie synchron an ein E/A-Ziel.

Syntax

NTSTATUS WdfIoTargetSendInternalIoctlOthersSynchronously(
  [in]            WDFIOTARGET               IoTarget,
  [in, optional]  WDFREQUEST                Request,
  [in]            ULONG                     IoctlCode,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    OtherArg1,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    OtherArg2,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    OtherArg4,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [out, optional] PULONG_PTR                BytesReturned
);

Parameter

[in] IoTarget

Ein Handle für ein lokales oder Remote-E/A-Zielobjekt, das von einem vorherigen Aufruf an WdfDeviceGetIoTarget oder WdfIoTargetCreateabgerufen wurde, oder von einer Methode, die ein spezialisiertes E/A-Ziel bereitstellt.

[in, optional] Request

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

[in] IoctlCode

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

[in, optional] OtherArg1

Ein Zeiger auf eine WDF_MEMORY_DESCRIPTOR-Struktur, die einen Speicherpuffer beschreibt, der Kontextinformationen enthält. Dieser Parameter ist optional und kann NULL-werden.

[in, optional] OtherArg2

Ein Zeiger auf eine WDF_MEMORY_DESCRIPTOR Struktur, die einen Speicherpuffer beschreibt, der Kontextinformationen enthält. Dieser Parameter ist optional und kann NULL-werden.

[in, optional] OtherArg4

Ein Zeiger auf eine WDF_MEMORY_DESCRIPTOR Struktur, die einen Speicherpuffer beschreibt, der Kontextinformationen enthält. Dieser Parameter ist optional und kann NULL-werden.

[in, optional] RequestOptions

Ein Zeiger auf eine vom Aufrufer zugewiesene WDF_REQUEST_SEND_OPTIONS Struktur, 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 bereitstellt, wenn er die Anforderung durch Aufrufen von WdfRequestCompleteWithInformation. Dieser Zeiger ist optional und kann NULL-sein.

Rückgabewert

Wenn der Vorgang erfolgreich ist, WdfIoTargetSendInternalIoctlOthersSynchronously zurückgegeben, nachdem die interne Gerätesteuerungsanforderung abgeschlossen ist, und der Rückgabewert ist der Fertigstellungsstatuswert 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 nicht innerhalb der zugewiesenen Zeit abgeschlossen.
STATUS_REQUEST_NOT_ACCEPTED	Das E/A-Anforderungspaket (IRP-), das der parameter Request darstellt, stellt nicht genügend IO_STACK_LOCATION Strukturen bereit, damit der Treiber die Anforderung weiterleiten kann.

Diese Methode kann auch andere NTSTATUS-Wertezurückgeben.

Wenn der Treiber ein ungültiges Objekthandle bereitstellt, tritt eine Fehlerüberprüfung auf.

Bemerkungen

Eine nicht standardmäßige interne Gerätesteuerungsanforderung verwendet einen IOCTL-Code, um den auszuführenden Vorgang zu identifizieren, die Anforderung verwendet jedoch nicht die Standardeingabe- und Ausgabepuffer, die andere interne Gerätesteuerungsanforderungen verwenden. Wenn Sie eine Reihe von interagierenden Treibern erstellen, können Sie definieren, wie diese Gruppe von Treibern die Argumente der Anforderung verwendet: OtherArg1, OtherArg2und OtherArg4.

Es gibt keinen Parameter namens OtherArg3, da das Framework diese Parameter dem Argument1, Argument2und Argument4 Member der Other.Parameters Union in der IO_STACK_LOCATION Struktur des Treibers zuordnet. Das Argument3 Mitglied in dieser Union empfängt den Wert aus dem IoctlCode- Parameter, sodass er für andere vom Treiber bereitgestellte Werte nicht verfügbar ist.

Verwenden Sie die WdfIoTargetSendInternalIoctlOthersSynchronously Methode, um nicht standardmäßige interne Gerätesteuerungsanforderungen synchron zu senden. Um interne Gerätesteuerungsanforderungen asynchron zu senden, verwenden Sie WdfIoTargetFormatRequestForInternalIoctlOthers, gefolgt von WdfRequestSend.

Weitere Informationen zu internen Gerätesteuerungsanforderungen finden Sie unter Using I/O Control Codes.

Die WdfIoTargetSendInternalIoctlOthersSynchronously Methode wird erst zurückgegeben, wenn die Anforderung abgeschlossen wurde, es sei denn, der Treiber stellt einen Timeoutwert in der RequestOptionsWDF_REQUEST_SEND_OPTIONS-Struktur des Parameters oder es sei denn, ein Fehler wird erkannt.

Sie können eine nicht standardmäßige interne Gerätesteuerungsanforderung weiterleiten, die Ihr Treiber in einer E/A-Warteschlange erhalten hat, oder Sie können eine neue Anforderung erstellen und senden. In beiden Fällen erfordert das Framework ein Anforderungsobjekt und möglicherweise einen Kontextbereich.

So leiten Sie eine nicht standardmäßige interne Gerätesteuerungsanforderung weiter, die Ihr Treiber in einer E/A-Warteschlange erhalten hat:

Geben Sie das Handle der empfangenen Anforderung für den WdfIoTargetSendInternalIoctlOthersSynchronously Method's Request Parameter an.
Verwenden Sie die Kontextinformationen der empfangenen Anforderung für die WdfIoTargetSendInternalIoctlOthersSynchronersSynchronouslyOtherArg1,OtherArg2undOtherArg4 Parameter.
Um diese Parameterwerte abzurufen, muss der Treiber WdfRequestGetParameters aufrufen und das DeviceIoControl Member der zurückgegebenen WDF_REQUEST_PARAMETERS Struktur verwenden.

Weitere Informationen zum Weiterleiten einer E/A-Anforderung finden Sie unter Weiterleitung 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:

Geben Sie einen NULL- Anforderungshandle für den WdfIoTargetSendInternalIoctlOthersSynchronouslyRequest-Parameter der 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 WdfRequestReuseaufrufen. Mit dieser Technik können Sie die EvtDriverDeviceAdd Rückruffunktion Ihres Treibers vorschreiben, um Anforderungsobjekte für ein Gerät vorab zu verwenden. Darüber hinaus kann ein anderer Treiberthread WdfRequestCancelSentRequest- aufrufen, um die Anforderung bei Bedarf abzubrechen.
Der Treiber kann einen Parameter ohneNULL-RequestOptions- angeben, unabhängig davon, ob der Treiber ein nicht-NULL- oder ein NULL-Request Parameter bereitstellt. Sie können z. B. den parameter RequestOptions verwenden, um einen Timeoutwert anzugeben.
Stellen Sie Kontextbereich für die WdfIoTargetSendInternalIoctlOthersSynchronously Methoden OtherArg1,OtherArg2und OtherArg4 Parameter bereit, wenn die Anforderung sie benötigt.
Der Treiber kann diesen Kontextbereich als lokal zugeordnete Puffer angeben, als WDFMEMORY-Handles oder als Speicherdeskriptorlisten (MDLs). Sie können verwenden, welche Methode am bequemsten ist.

Die folgenden Techniken zum Angeben des Pufferraums stehen zur Verfügung:
- Geben Sie lokale Puffer an.
  Da WdfIoTargetSendInternalIoctlOthersSynchronously E/A-Anforderungen synchron behandelt, kann der Treiber Anforderungspuffer erstellen, die lokal für die aufrufende Routine sind, wie im folgenden Codebeispiel gezeigt.
```
WDF_MEMORY_DESCRIPTOR  MemoryDescriptor;
MY_BUFFER_TYPE  MyBuffer;
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&MemoryDescriptor,
                                  (PVOID) &MyBuffer,
                                  sizeof(MyBuffer));
```
- Stellen Sie WDFMEMORY-Handles zur Verfügung.
  Rufen Sie WdfMemoryCreate oder WdfMemoryCreatePreallocated auf, um ein Handle für vom Framework verwalteten Speicher abzurufen, wie im folgenden Codebeispiel gezeigt.
```
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);
```
- Geben Sie MDLs an.
  Treiber können MDLs abrufen, die einer empfangenen E/A-Anforderung zugeordnet sind, indem sie WdfRequestRetrieveInputWdmMdl und WdfRequestRetrieveOutputWdmMdlaufrufen.

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

Weitere Informationen zu WdfIoTargetSendInternalIoctlOthersSynchronouslyfinden Sie unter Senden von E/A-Anforderungen an allgemeine E/A-Ziele.

Weitere Informationen zu E/A-Zielen finden Sie unter Using I/O Targets.

Beispiele

Im folgenden Codebeispiel wird eine IEEE 1394 IRB-Struktur initialisiert, die Adresse der Struktur verwendet, um eine WDF_MEMORY_DESCRIPTOR Struktur zu initialisieren, und ruft dann WdfIoTargetSendInternalIoctlOthersSynchronouslyauf.

WDF_MEMORY_DESCRIPTOR descriptor;
IRB Irb;

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

WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
                                  &descriptor,
                                  &Irb,
                                  sizeof (IRB)
                                  );

ntStatus = WdfIoTargetSendInternalIoctlOthersSynchronously(
                                                           IoTarget, 
                                                           NULL,
                                                           IOCTL_1394_CLASS,
                                                           &descriptor,
                                                           NULL,
                                                           NULL,
                                                           NULL,
                                                           NULL
                                                           );

Anforderungen

Anforderung	Wert
Zielplattform-	Universal
Minimale KMDF-Version	1.0
Header-	wdfiotarget.h (include Wdf.h)
Library	Wdf01000.sys (siehe Framework-Bibliotheksversionsverwaltung.)
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)