funzione WinUsb_ReadPipe (winusb.h)

  • Articolo

La funzione WinUsb_ReadPipe legge i dati dalla pipe specificata.

Sintassi

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

Parametri

[in] InterfaceHandle

Handle opaco all'interfaccia contenente l'endpoint con cui è associata la pipe.

Per leggere i dati dalla 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 Tabella 9-13 in "Universal Serial Bus Specification Revision 2.0" in USB Technology. Nel campo bEndpointAddress bit 7 indica la direzione dell'endpoint: 0 per OUT; 1 per IN.

[out] Buffer

Buffer allocato dal chiamante che riceve i dati letti.

[in] BufferLength

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

[out, optional] LengthTransferred

Puntatore a una variabile ULONG che riceve il numero effettivo di byte copiati nel buffer. Per altre informazioni, vedere la sezione Osservazioni.

[in, optional] Overlapped

Puntatore facoltativo a una struttura OVERLAPPED usata per le operazioni asincrone. Se questo parametro viene specificato, WinUsb_ReadPipe restituisce immediatamente anziché attendere in modo sincrono il completamento dell'operazione prima di restituire. Un evento viene segnalato al termine dell'operazione.

Valore restituito

WinUsb_ReadPipe restituisce TRUE 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
 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, indicando che l'operazione viene eseguita in background. Chiamare WinUsb_GetOverlappedResult per verificare l'esito positivo o negativo dell'operazione.
ERROR_NOT_ENOUGH_MEMORY
 Memoria insufficiente per eseguire l'operazione.
ERROR_SEM_TIMEOUT
 Operazione di lettura avviata da WinUsb_ReadPipe nello stack USB timeout prima del completamento dell'operazione.

Commenti

Se i dati restituiti dal dispositivo sono maggiori di una lunghezza massima di trasferimento, WinUSB divide la richiesta in richieste più piccole di lunghezza massima di trasferimento e li invia serialmente. Se la lunghezza del trasferimento non è un multiplo delle dimensioni massime del pacchetto dell'endpoint (recuperabile tramite il membro MaximumPacketSize della struttura di WINUSB_PIPE_INFORMATION), WinUSB aumenta le dimensioni del trasferimento al successivo multiplo di MaximumPacketSize.

Le dimensioni dei pacchetti USB non influisce sul trasferimento per una richiesta di lettura. Se il dispositivo risponde con un pacchetto troppo grande per il buffer client, il comportamento della richiesta di lettura corrisponde al tipo di criterio impostato sulla pipe. Se il tipo di criterio per la pipe è ALLOW_PARTIAL_READS, WinUSB aggiunge i dati rimanenti all'inizio del trasferimento successivo. Se ALLOW_PARTIAL_READS non è impostato, la richiesta di lettura ha esito negativo. Per altre informazioni sui tipi di criteri, vedere Funzioni WinUSB per la modifica dei criteri di pipe.

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

Se la sovrapposizione non è NULL (operazione asincrona), LengthTransferred può essere impostata su NULL. Per un'operazione sovrapposta (e se LengthTransferred è un valore non NULL ), il valore ricevuto in LengthTransferred dopo WinUsb_ReadPipe restituisce è senza significato fino al completamento dell'operazione sovrapposta. Per recuperare il numero effettivo di byte letti dalla pipe, chiamare WinUsb_GetOverlappedResult.

Quando non sono disponibili dati nell'endpoint (pipe è vuoto), WinUsb_ReadPipe non restituisce finché non sono presenti dati nella pipe. Se si verifica una condizione di errore o il timeout specificato dall'applicazione scade, WinUsb_ReadPipe restituisce sempre FALSE. Per determinare il motivo effettivo per tale valore restituito, chiamare sempre GetLastError. Ad esempio, in questi casi il valore di errore GetLastError indica il motivo effettivo:

  • Se l'applicazione ha specificato un valore di timeout nei criteri della pipe e tale timeout scade, WinUsb_ReadPipe restituisce FALSE e GetLastError restituisce ERROR_SEM_TIMEOUT.
  • Se si verifica una condizione di errore durante la lettura dei dati dalla pipe, WinUsb_ReadPipe restituisce FALSE e GetLastError restituisce ERROR_GEN_FAILURE.

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