funzione WinUsb_WritePipe (winusb.h)

Articolo
08/27/2023

La funzione WinUsb_WritePipe scrive i dati in una pipe.

Sintassi

BOOL WinUsb_WritePipe(
  [in]            WINUSB_INTERFACE_HANDLE InterfaceHandle,
  [in]            UCHAR                   PipeID,
  [in]            PUCHAR                  Buffer,
  [in]            ULONG                   BufferLength,
  [out, optional] PULONG                  LengthTransferred,
  [in, optional]  LPOVERLAPPED            Overlapped
);

Parametri

[in] InterfaceHandle

Handle opaco per l'interfaccia che contiene l'endpoint a cui è associata la pipe.

Per scrivere in una pipe associata a un endpoint nella prima interfaccia, usare l'handle restituito da WinUsb_Initialize. Per tutte le altre interfacce, usare l'handle per l'interfaccia di destinazione, recuperata da WinUsb_GetAssociatedInterface.

[in] PipeID

PipeID corrisponde al campo bEndpointAddress nel descrittore dell'endpoint. Per informazioni sul layout di questo campo, vedere La tabella 9-13 in "Universal Serial Bus Specification Revision 2.0" in TECNOLOGIA USB. Nel campo bEndpointAddress bit 7 indica la direzione dell'endpoint: 0 per OUT; 1 per IN.

[in] Buffer

Buffer allocato dal chiamante che contiene i dati da scrivere.

[in] BufferLength

Numero di byte da scrivere. Questo numero deve essere minore o uguale alla dimensione, espressa in byte, di Buffer.

[out, optional] LengthTransferred

Puntatore a una variabile ULONG che riceve il numero effettivo di byte scritti nella pipe. Per altre informazioni, vedere la sezione Osservazioni.

[in, optional] Overlapped

Puntatore facoltativo a una struttura OVERLAPPED, utilizzata per le operazioni asincrone. Se questo parametro viene specificato, WinUsb_WritePipe restituisce immediatamente e l'evento viene segnalato al termine dell'operazione.

Valore restituito

WinUsb_WritePipe restituisceTRUE se l'operazione ha esito positivo. In caso contrario, questa funzione restituisce FALSE e il chiamante può recuperare l'errore registrato chiamando GetLastError.

GetLastError può restituire il codice di errore seguente.

Codice restituito	Descrizione
ERROR_INVALID_HANDLE	Il chiamante ha passato NULL nel parametro InterfaceHandle .
ERROR_IO_PENDING	Indica che un'operazione di I/O sovrapposta è in corso ma non è stata completata. Se l'operazione sovrapposta non può essere completata immediatamente, la funzione restituisce FALSE e la funzione GetLastError restituisce ERROR_IO_PENDING, a indicare che l'operazione è in esecuzione in background. Chiamare WinUsb_GetOverlappedResult per verificare l'esito positivo o negativo dell'operazione.
ERROR_NOT_ENOUGH_MEMORY	Indica che la memoria non è sufficiente per eseguire l'operazione.
ERROR_SEM_TIMEOUT	Operazione di scrittura avviata da WinUsb_WritePipe nello stack USB timeout prima del completamento dell'operazione.

Commenti

Per creare una richiesta di scrittura, l'applicazione deve allocare un buffer, riempirlo con i dati da scrivere nel dispositivo e inviare il buffer al controller host chiamando WinUsb_WritePipe.

Le restrizioni seguenti si applicano alle dimensioni del buffer se RAW_IO è impostato:

La lunghezza del buffer deve essere un multiplo delle dimensioni massime del pacchetto dell'endpoint.
La lunghezza deve essere minore o uguale al valore di MAXIMUM_TRANSFER_SIZE recuperato da WinUsb_GetPipePolicy.

Non esistono restrizioni per le dimensioni del buffer se RAW_IO non è impostato come tipo di criterio della pipe. Se le dimensioni del buffer sono maggiori della lunghezza massima di trasferimento segnalata da MAXIMUM_TRANSFER_SIZE, WinUSB divide la richiesta in richieste più piccole e le invia in modo seriale al controller host.

Una richiesta di scrittura che contiene dati di lunghezza zero viene inoltrata nello stack USB.

Se un'applicazione passa NULL nel parametro Sovrapposto (operazione sincrona), deve assicurarsi che LengthTransferred non sia NULL, anche quando un'operazione non produce dati di output.

Se Overlapped non è NULL (operazione asincrona), LengthTransferred può essere impostato su NULL. Per un'operazione sovrapposta (e se LengthTransferred è un valore non NULL ), il valore ricevuto in LengthTransferred dopo WinUsb_WritePipe restituisce è senza significato fino al completamento dell'operazione sovrapposta. Per recuperare il numero effettivo di byte restituiti, chiamare WinUsb_GetOverlappedResult.

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Intestazione	winusb.h (include Winusb.h)
Libreria	Winusb.lib
DLL	Winusb.dll

Vedi anche

WinUSB

Funzioni WinUSB

WinUsb_Initialize

Condividi tramite