WdfUsbTargetPipeWriteSynchronously-Funktion (wdfusb.h)
[Gilt für KMDF und UMDF]
Die WdfUsbTargetPipeWriteSynchronously-Methode erstellt eine Schreibanforderung und sendet sie synchron an eine angegebene USB-Ausgabepipe.
Syntax
NTSTATUS WdfUsbTargetPipeWriteSynchronously(
[in] WDFUSBPIPE Pipe,
[in, optional] WDFREQUEST Request,
[in, optional] PWDF_REQUEST_SEND_OPTIONS RequestOptions,
[in, optional] PWDF_MEMORY_DESCRIPTOR MemoryDescriptor,
[out, optional] PULONG BytesWritten
);
Parameter
[in] Pipe
Ein Handle für ein Framework-Pipeobjekt, das durch aufrufen von WdfUsbInterfaceGetConfiguredPipe abgerufen wurde.
[in, optional] Request
Ein Handle für ein Frameworkanforderungsobjekt. Dieser Parameter ist optional und kann NULL sein. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".
[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".
[in, optional] MemoryDescriptor
Ein Zeiger auf eine vom Aufrufer zugewiesene WDF_MEMORY_DESCRIPTOR Struktur, die den Puffer beschreibt, der Daten enthält, die auf das Gerät geschrieben werden. Weitere Informationen zu diesem Puffer finden Sie im abschnitt Hinweise.
[out, optional] BytesWritten
Ein Zeiger auf einen Speicherort, der die Anzahl der geschriebenen Bytes empfängt, wenn der Vorgang erfolgreich ist. Dieser Parameter ist optional und kann NULL sein.
Rückgabewert
WdfUsbTargetPipeWriteSynchronously gibt die Vervollständigung des E/A-Ziels status Wert zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt diese Methode möglicherweise einen der folgenden Werte zurück:
Rückgabecode | Beschreibung |
---|---|
|
Die Größe der WDF_REQUEST_SEND_OPTIONS Struktur, auf die der RequestOptions-Parameter verweist, war falsch. |
|
Ein ungültiger Parameter wurde erkannt. |
|
Nicht genügend Arbeitsspeicher war verfügbar. |
|
Die IRQL des Aufrufers wurde nicht PASSIVE_LEVEL, ein ungültiger Speicherdeskriptor wurde angegeben, der Typ der Pipe war ungültig, die Übertragungsrichtung war ungültig oder die angegebene E/A-Anforderung wurde bereits an ein E/A-Ziel in die Warteschlange gestellt. |
|
Der Treiber hat einen Timeoutwert angegeben, und die Anforderung wurde nicht innerhalb der zugewiesenen Zeit abgeschlossen. |
|
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 WdfUsbTargetPipeWriteSynchronously-Methode , um Schreibanforderungen synchron zu senden. Verwenden Sie zum asynchronen Senden von Schreibanforderungen WdfUsbTargetPipeFormatRequestForWrite, gefolgt von WdfRequestSend.
Die angegebene Pipe muss eine Ausgabepipe sein, und der Typ der Pipe muss WdfUsbPipeTypeBulk oder WdfUsbPipeTypeInterrupt sein.
Die WdfUsbTargetPipeWriteSynchronously-Methode wird erst zurückgegeben, wenn die Anforderung abgeschlossen ist, es sei denn, der Treiber gibt einen Timeoutwert in der WDF_REQUEST_SEND_OPTIONS Struktur des RequestOptions-Parameters an, oder es wird kein Fehler erkannt.
Sie können eine E/A-Anforderung 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 etwas Pufferspeicher.
So leiten Sie eine E/A-Anforderung weiter, die Ihr Treiber in einer E/A-Warteschlange empfangen hat:
- Geben Sie das Handle der empfangenen Anforderung für den Request-Parameter an .
-
Verwenden Sie den Eingabepuffer der empfangenen Anforderung für den Parameter MemoryDescriptor .
Der Treiber muss WdfRequestRetrieveInputMemory aufrufen, um ein Handle für ein Framework-Speicherobjekt abzurufen, das den Eingabepuffer der Anforderung darstellt, und dann dieses Handle in der WDF_MEMORY_DESCRIPTOR Struktur platzieren, auf die MemoryDescriptor verweist.
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 ein NULL-Anforderungshandle für den Request-Parameter der WdfUsbTargetPipeWriteSynchronously-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 WdfRequestReuse aufrufen. Mit dieser Technik kann die EvtDriverDeviceAdd-Rückruffunktion Ihres Treibers Anforderungsobjekte für ein Gerät vorab zugeordnet werden. Darüber hinaus kann ein anderer Treiberthread WdfRequestCancelSentRequest aufrufen, um die Anforderung bei Bedarf abzubrechen.
Ihr Treiber kann einen RequestOptions-Parameter ohne NULL angeben, unabhängig davon, ob der Treiber einen Nicht-NULL- oder null-Anforderungsparameter bereitstellt. Sie können beispielsweise den Parameter RequestOptions verwenden, um einen Timeoutwert anzugeben.
-
Stellen Sie Pufferspeicher für den MemoryDescriptor-Parameter der WdfUsbTargetPipeWriteSynchronously-Methode bereit.
Ihr Treiber kann diesen Pufferspeicher als lokal zugeordneten Puffer, als WDFMEMORY-Handle oder als MDL angeben. Sie können die methode verwenden, die am bequemsten ist.
Bei Bedarf konvertiert das Framework die Pufferbeschreibung in eine Pufferbeschreibung, die für die E/A-Zielmethode für den Zugriff auf Datenpuffer richtig ist.
Die folgenden Techniken sind verfügbar:
-
Bereitstellen eines lokalen Puffers
Da WdfUsbTargetPipeWriteSynchronously E/A-Anforderungen synchron verarbeitet, kann der Treiber Anforderungspuffer erstellen, die für die aufrufende Routine lokal sind, wie das folgende Codebeispiel zeigt.
WDF_MEMORY_DESCRIPTOR memoryDescriptor; MY_BUFFER_TYPE myBuffer; WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&memoryDescriptor, (PVOID) &myBuffer, sizeof(myBuffer));
-
Bereitstellen eines WDFMEMORY-Handles
Rufen Sie WdfMemoryCreate oder WdfMemoryCreatePreallocated auf, um ein Handle für den vom Framework verwalteten Arbeitsspeicher abzurufen, wie das folgende Codebeispiel zeigt.
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);
Alternativ kann der Treiber WdfRequestRetrieveInputMemory aufrufen, um ein Handle für ein Framework-Speicherobjekt abzurufen, das den Eingabepuffer einer empfangenen E/A-Anforderung darstellt, wenn der Treiber den Inhalt dieses Puffers an das E/A-Ziel übergeben soll. Der Treiber darf die empfangene E/A-Anforderung erst abschließen, wenn die neue Anforderung, die WdfUsbTargetPipeWriteSynchronously an das E/A-Ziel sendet, gelöscht, wiederverwendet oder neu formatiert wurde. (WdfUsbTargetPipeWriteSynchronously erhöht die Referenzanzahl des Speicherobjekts. Durch das Löschen, Erneutes Verwenden oder Neuformatieren eines Anforderungsobjekts wird die Verweisanzahl des Speicherobjekts verringert.)
-
Bereitstellen einer MDL
Treiber können die MDL abrufen, die einer empfangenen E/A-Anforderung zugeordnet ist, indem sie WdfRequestRetrieveInputWdmMdl aufrufen.
-
Bereitstellen eines lokalen Puffers
Weitere Informationen zur WdfUsbTargetPipeWriteSynchronously-Methode und USB-E/A-Zielen finden Sie unter USB-E/A-Ziele.
Beispiele
Das folgende Codebeispiel erstellt ein Speicherobjekt, ruft einen Zeiger auf den Puffer des Objekts ab, füllt den Puffer aus und verwendet den Puffer als Eingabe für WdfUsbTargetPipeWriteSynchronously.
WDF_MEMORY_DESCRIPTOR writeBufDesc;
WDFMEMORY wdfMemory;
ULONG writeSize, bytesWritten;
size_t bufferSize;
NTSTATUS status;
writeSize = SMALL_BUF_LEN;
status = WdfMemoryCreate(
WDF_NO_OBJECT_ATTRIBUTES,
NonPagedPool,
0,
writeSize,
&wdfMemory,
NULL
);
if (!NT_SUCCESS(status)){
return status;
}
writeBuffer = WdfMemoryGetBuffer(
wdfMemory,
&bufferSize
);
FillMyBuffer(
writeBuffer,
writeSize
);
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
&writeBufDesc,
writeBuffer,
writeSize
);
status = WdfUsbTargetPipeWriteSynchronously(
pipeHandle,
NULL,
NULL,
&writeBufDesc,
&bytesWritten
);
Anforderungen
Anforderung | Wert |
---|---|
Zielplattform | Universell |
KMDF-Mindestversion | 1.0 |
UMDF-Mindestversion | 2.0 |
Kopfzeile | wdfusb.h (einschließlich Wdfusb.h) |
Bibliothek | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
IRQL | PASSIVE_LEVEL |
DDI-Complianceregeln | DriverCreate(kmdf), InternalIoctlReqs(kmdf), IoctlReqs(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), ReadReqs(kmdf), SyncReqSend(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf) |
Weitere Informationen
Feedback
https://aka.ms/ContentUserFeedback.
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unterFeedback senden und anzeigen für