|
BOOL
|
FT_W32_ReadFile
|
(FT_HANDLE ftHandle, LPVOID lpBuffer, DWORD dwBytesToRead, LPDWORD lpdwBytesReturned, LPOVERLAPPED lpOverlapped)
|
Parameters
|
ftHandle
|
Handle of the device.
|
|
lpBuffer
|
Pointer to a buffer that receives the data from the device.
|
|
dwBytesToRead
|
Number of bytes to read from the device.
|
|
lpdwBytesReturned
|
Pointer to a variable that receives the number of bytes read from the device.
|
|
lpOverlapped
|
Pointer to an overlapped structure. Ignored in Linux.
|
Return Value
If the function is successful, the return value is nonzero.
If the function is unsuccessful, the return value is zero.
Remarks
This function supports both non-overlapped and overlapped I/O, except under Windows CE and Linux where only non-overlapped IO is supported.
Non-overlapped I/O
The parameter, lpOverlapped, must be NULL for non-overlapped I/O.
This function always returns the number of bytes read in lpdwBytesReturned.
This function does not return until dwBytesToRead have been read into the buffer. The number of bytes in the receive queue can be determined by calling FT_GetStatus or FT_GetQueueStatus, and passed as dwBytesToRead so that the function reads the device and returns immediately.
When a read timeout has been setup in a previous call to FT_W32_SetCommTimeouts, this function returns when the timer expires or dwBytesToRead have been read, whichever occurs first. If a timeout occurred, any available data is read into lpBuffer and the function returns a non-zero value.
An application should use the function return value and lpdwBytesReturned when processing the buffer. If the return value is non-zero and lpdwBytesReturned is equal to dwBytesToRead then the function has completed normally. If the return value is non-zero and lpdwBytesReturned is less then dwBytesToRead then a timeout has occurred, and the read request has been partially completed. Note that if a timeout occurred and no data was read, the return value is still non-zero.
A return value of FT_IO_ERROR suggests an error in the parameters of the function, or a fatal error like USB disconnect has occurred.
Overlapped I/O
When the device has been opened for overlapped I/O, an application can issue a request and perform some additional work while the request is pending. This contrasts with the case of non-overlapped I/O in which the application issues a request and receives control again only after the request has been completed.
The parameter, lpOverlapped, must point to an initialized OVERLAPPED structure.
If there is enough data in the receive queue to satisfy the request, the request completes immediately and the return code is non-zero. The number of bytes read is returned in lpdwBytesReturned.
If there is not enough data in the receive queue to satisfy the request, the request completes immediately, and the return code is zero, signifying an error. An application should call FT_W32_GetLastError to get the cause of the error. If the error code is ERROR_IO_PENDING, the overlapped operation is still in progress, and the application can perform other processing. Eventually, the application checks the result of the overlapped request by calling FT_W32_GetOverlappedResult.
If successful, the number of bytes read is returned in lpdwBytesReturned.
Example
This example shows how to read 256 bytes from the device using non-overlapped I/O.
FT_HANDLE ftHandle; // setup by FT_W32_CreateFile for non-overlapped i/o
char Buf[256];
DWORD dwToRead = 256;
DWORD dwRead;
if (FT_W32_ReadFile(ftHandle, Buf, dwToRead, &dwRead, &osWrite)) {
if (dwToRead == dwRead){
// FT_W32_ReadFile OK}
else{
// FT_W32_ReadFile timeout}
{
else{
// FT_W32_ReadFile failed}
This example shows how to read 256 bytes from the device using overlapped I/O.
FT_HANDLE ftHandle; // setup by FT_W32_CreateFile for overlapped i/o
char Buf[256];
DWORD dwToRead = 256;
DWORD dwRead;
OVERLAPPED osRead = { 0 };
if (!FT_W32_ReadFile(ftHandle, Buf, dwToRead, &dwRead, &osWrite)) {
if (FT_W32_GetLastError(ftHandle) == ERROR_IO_PENDING) {
// write is delayed so do some other stuff until ...
if (!FT_W32_GetOverlappedResult(ftHandle, &osRead, &dwRead, FALSE)){
// error}
else {
if (dwToRead == dwRead){
// FT_W32_ReadFile OK}
else{
// FT_W32_ReadFile timeout}
}
}
}
else {
// FT_W32_ReadFile OK
}