Funzione WdfUsbTargetPipeWriteSynchronously (wdfusb.h)
[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 a 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 ulteriori informazioni, vedere la sezione Osservazioni successiva.
[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 ulteriori informazioni, vedere la sezione Osservazioni successiva.
[in, optional] MemoryDescriptor
Puntatore a una struttura WDF_MEMORY_DESCRIPTOR allocata dal chiamante che descrive il buffer che contiene dati scritti nel dispositivo. Per altre informazioni su questo buffer, vedere la sezione Osservazioni seguenti.
[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 di I/O se l'operazione ha esito positivo. In caso contrario, questo metodo potrebbe restituire uno dei valori seguenti:
Codice restituito | Descrizione |
---|---|
|
Dimensioni della struttura WDF_REQUEST_SEND_OPTIONS a cui punta il parametro RequestOptions non è corretto. |
|
È stato rilevato un parametro non valido. |
|
Memoria insufficiente disponibile. |
|
IrQL del chiamante non era 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 specificata. |
|
Il driver ha fornito un valore di timeout e la richiesta non è stata completata entro il tempo assegnato. |
|
Il pacchetto di richiesta I/O (IRP) che il parametro Request rappresenta non fornisce strutture IO_STACK_LOCATION sufficienti per consentire al driver di inoltrare la richiesta. |
Questo metodo potrebbe restituire anche altri valori NTSTATUS.
Un controllo di bug si verifica se il driver fornisce un handle di oggetti non valido.
Commenti
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 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 WDF_REQUEST_SEND_OPTIONS del parametro RequestOptions 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 è possibile creare e inviare una nuova richiesta. In entrambi i casi, il framework richiede un oggetto request 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 del framework che rappresenta il buffer di input della richiesta e quindi posizionare tale handle nella struttura WDF_MEMORY_DESCRIPTOR a cui MemoryDescriptor punta.
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 Request del metodo WdfUsbTargetPipeWriteSynchronously, oppure creare un nuovo oggetto request e fornire il relativo handle:
- Se si specifica un handle di richiesta NULL , il framework usa un oggetto request 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 all'evtDriverDevice del driverAggiungi la funzione di callback per preallocare gli oggetti di richiesta per un dispositivo. Inoltre, un altro thread driver può chiamare WdfRequestCancelSentRequest per annullare la richiesta, se necessario.
Il driver può specificare un parametroRequestOptions diverso da NULL, indipendentemente dal fatto che il driver fornisca un parametro non NULL o null Request. È possibile, ad esempio, usare il parametro RequestOptions per specificare un valore di timeout.
-
Fornire spazio del buffer per il parametro MemoryDescriptor del metodo WdfUsbTargetPipeWriteSynchronously.
Il driver può specificare questo spazio buffer come buffer allocato in locale, come handle WDFMEMORY o come MDL. È possibile usare il metodo più pratico.
Se necessario, il framework converte la descrizione del buffer in un oggetto corretto per il metodo di destinazione di I/O per l'accesso ai buffer 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 alla 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));
-
Specificare un handle WDFMEMORY
Chiamare WdfMemoryCreate 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 della richiesta di I/O ricevuto, se si vuole che il driver passi il contenuto del buffer alla destinazione I/O. Il driver non deve completare la richiesta di I/O ricevuta fino alla nuova richiesta che WdfUsbTargetPipeWriteSynchronously invia alla destinazione di I/O è stata eliminata, riutilizzata o riformattata. (WdfUsbTargetPipeWriteSynchronously incrementa il numero di riferimenti dell'oggetto memoria. Eliminazione, riutilizzo o riformattamento di un oggetto request decrementa il numero di riferimenti dell'oggetto memoria.
-
Specificare un MDL
I driver possono ottenere l'MDL associato a una richiesta di I/O ricevuta chiamando WdfRequestRetrieveInputWdmMdl.
-
Fornire un buffer locale
Per altre informazioni sul metodo WdfUsbTargetPipeWriteSynchronously e sulle destinazioni di I/O USB, vedere Destinazioni di I/O USB.
Esempio
L'esempio di codice seguente crea un oggetto memory, 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
);
Requisiti
Requisito | Valore |
---|---|
Piattaforma di destinazione | Universale |
Versione KMDF minima | 1.0 |
Versione UMDF minima | 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) |
Vedi anche
Commenti e suggerimenti
https://aka.ms/ContentUserFeedback.
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedereInvia e visualizza il feedback per