Funzione WdfUsbTargetPipeWriteSynchronously (wdfusb.h)

Articolo
07/16/2024

[Si applica a KMDF e UMDF]

Il metodo WdfUsbTargetPipeWriteSynchronously compila una richiesta di scrittura e lo invia in modo sincrono a una pipe di output USB specificata.

Sintassi

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
);

Parametri

[in] Pipe

Handle per un oggetto pipe del framework ottenuto chiamando WdfUsbInterfaceGetConfiguredPipe.

[in, optional] Request

Handle per un oggetto richiesta framework. Questo parametro è facoltativo e può essere NULL. Per altre informazioni, vedere la sezione Osservazioni seguente.

[in, optional] RequestOptions

Puntatore a una struttura WDF_REQUEST_SEND_OPTIONS allocata dal chiamante che specifica le opzioni per la richiesta. Questo puntatore è facoltativo e può essere NULL. Per altre informazioni, vedere la sezione Osservazioni seguente.

[in, optional] MemoryDescriptor

Puntatore a una struttura di WDF_MEMORY_DESCRIPTOR allocata dal chiamante che descrive il buffer che contiene dati che verranno scritti nel dispositivo. Per altre informazioni su questo buffer, vedere la sezione Osservazioni seguente.

[out, optional] BytesWritten

Puntatore a una posizione che riceve il numero di byte scritti, se l'operazione ha esito positivo. Questo parametro è facoltativo e può essere NULL.

Valore restituito

WdfUsbTargetPipeWriteSynchronously restituisce il valore di stato di completamento della destinazione I/O se l'operazione ha esito positivo. In caso contrario, questo metodo potrebbe restituire uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_INFO_LENGTH_MISMATCH	Dimensioni della struttura di WDF_REQUEST_SEND_OPTIONS a cui punta il parametro RequestOptions non è corretto.
STATUS_INVALID_PARAMETER	È stato rilevato un parametro non valido.
STATUS_INSUFFICIENT_RESOURCES	Memoria insufficiente disponibile.
STATUS_INVALID_DEVICE_REQUEST	IrQL del chiamante non è stato PASSIVE_LEVEL, è stato specificato un descrittore di memoria non valido, il tipo della pipe non è valido, la direzione di trasferimento non è valida o la richiesta di I/O specificata è già stata accodata a una destinazione di I/O.
STATUS_IO_TIMEOUT	Il driver ha fornito un valore di timeout e la richiesta non è stata completata entro il tempo assegnato.
STATUS_REQUEST_NOT_ACCEPTED	Il pacchetto di richiesta di I/O (IRP) rappresentato dal parametro richiesta non fornisce strutture IO_STACK_LOCATION sufficienti per consentire al driver di inoltrare la richiesta.

Questo metodo potrebbe anche restituire altri valori NTSTATUS .

Se il driver fornisce un handle di oggetto non valido, si verifica un controllo di bug.

Osservazioni

Usare il metodo WdfUsbTargetPipeWriteSynchronously per inviare richieste di scrittura in modo sincrono. Per inviare richieste di scrittura in modo asincrono, usare WdfUsbTargetPipeFormatRequestForWrite, seguito da WdfRequestSend.

La pipe specificata deve essere una pipe di output e il tipo di della pipe deve essere WdfUsbPipeTypeBulk o WdfUsbPipeTypeInterrupt.

Il metodo WdfUsbTargetPipeWriteSynchronously non restituisce fino al completamento della richiesta, a meno che il driver non fornisca un valore di timeout nella struttura RequestOptions parametro WDF_REQUEST_SEND_OPTIONS o a meno che non venga rilevato un errore.

È possibile inoltrare una richiesta di I/O ricevuta dal driver in una coda di I/O oppure creare e inviare una nuova richiesta. In entrambi i casi, il framework richiede un oggetto richiesta e uno spazio buffer.

Per inoltrare una richiesta di I/O ricevuta dal driver in una coda di I/O:

Specificare l'handle della richiesta ricevuta per il parametro request .
Usare il buffer di input della richiesta ricevuta per il parametro MemoryDescriptor.
Il driver deve chiamare WdfRequestRetrieveInputMemory per ottenere un handle a un oggetto memoria framework che rappresenta il buffer di input della richiesta e quindi posizionare tale handle nella struttura WDF_MEMORY_DESCRIPTOR che MemoryDescriptor punta.

Per altre informazioni sull'inoltro di una richiesta di I/O, vedere Inoltro di richieste di I/O.

I driver spesso dividono le richieste di I/O ricevute in richieste più piccole inviate a una destinazione di I/O, in modo che il driver possa creare nuove richieste.

Per creare una nuova richiesta di I/O:

Specificare un handle di richiesta NULL
per il parametro WdfUsbTargetPipeWriteSynchronously del metodo Request oppure creare un nuovo oggetto richiesta e specificarne l'handle:
- Se si specifica un handle di richiesta NULL , il framework usa un oggetto richiesta interno. Questa tecnica è semplice da usare, ma il driver non può annullare la richiesta.
- Se si chiama WdfRequestCreate per creare uno o più oggetti richiesta, è possibile riutilizzare questi oggetti richiesta chiamando WdfRequestReuse. Questa tecnica consente al driver di EvtDriverDeviceAdd funzione di callback per preallocare gli oggetti richiesta per un dispositivo. Inoltre, un altro thread del driver può chiamare WdfRequestCancelSentRequest per annullare la richiesta, se necessario.
Il driver può specificare un parametro nullNULLnull, indipendentemente dal fatto che il driver fornisca un NULL nono un parametro RequestNULL . È ad esempio possibile usare il parametro RequestOptions per specificare un valore di timeout.
Specificare lo spazio del buffer per il parametro
MemoryDescriptor WdfUsbTargetPipeWriteSynchronously metodo.
Il driver può specificare questo spazio buffer come buffer allocato in locale, come handle WDFMEMORY o come MDL. È possibile usare qualsiasi metodo sia più pratico.

Se necessario, il framework converte la descrizione del buffer in una descrizione corretta per il metodo di della destinazione di I/O per l'accesso ai buffer di dati.

Sono disponibili le tecniche seguenti:
- Fornire un buffer locale
  Poiché WdfUsbTargetPipeWriteSynchronously gestisce le richieste di I/O in modo sincrono, il driver può creare buffer di richiesta locali per la routine chiamante, come illustrato nell'esempio di codice seguente.
```
WDF_MEMORY_DESCRIPTOR  memoryDescriptor;
MY_BUFFER_TYPE  myBuffer;
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&memoryDescriptor,
                                  (PVOID) &myBuffer,
                                  sizeof(myBuffer));
```
- Fornire un handle WDFMEMORY
  Chiamare WdfMemoryCreare o WdfMemoryCreatePreallocated per ottenere un handle per la memoria gestita dal framework, come illustrato nell'esempio di codice seguente.
```
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);
```
  In alternativa, il driver può chiamare WdfRequestRetrieveInputMemory per ottenere un handle a un oggetto memoria del framework che rappresenta il buffer di input di una richiesta di I/O ricevuta, se si vuole che il driver passi il contenuto del buffer alla destinazione di I/O. Il driver non deve completare la richiesta di I/O ricevuta fino a quando la nuova richiesta che WdfUsbTargetPipeWriteSynchronously invia alla destinazione di I/O è stata eliminata, riutilizzata o riformattata. (WdfUsbTargetPipeWriteSynchronously incrementa il conteggio dei riferimenti dell'oggetto memoria. L'eliminazione, il riutilizzo o la riformattazione di un oggetto richiesta decrementa il conteggio dei riferimenti dell'oggetto memoria.
- Specificare un file MDL
  I driver possono ottenere il file MDL associato a una richiesta di I/O ricevuta chiamando WdfRequestRetrieveInputWdmMdl.

Per informazioni su come ottenere informazioni sullo stato dopo il completamento di una richiesta di I/O, vedere ottenere informazioni di completamento.

Per altre informazioni sul metodo WdfUsbTargetPipeWriteSynchronously e sulle destinazioni di I/O USB, vedere Destinazioni I/O USB.

Esempi

L'esempio di codice seguente crea un oggetto memoria, ottiene un puntatore al buffer dell'oggetto, riempie il buffer e usa il buffer come input per 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
                                            );

Fabbisogno

Requisito	Valore
piattaforma di destinazione	Universale
versione minima di KMDF	1.0
versione minima di UMDF	2.0
intestazione	wdfusb.h (include Wdfusb.h)
libreria	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
regole di conformità DDI	DriverCreate(kmdf), InternalIoctlReqs(kmdf), IoctlReqs(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), ReadReqs(kmdf), SyncReqSend(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)