FT_W32_ReadFile函数的用法

介绍 FT_W32_ReadFile函数的用法、参数、返回值、注意事项、适用的操作系统环境、调用代码示例等。

支持的操作系统

Linux

Mac OS X 10.4 以上版本

Windows 2000 以上版本

Windows CE 4.2 以上版本

概述

FT_W32_ReadFile 函数从设备读取数据。

定义

BOOL FT_W32_ReadFile (FT_HANDLE ftHandle, LPVOID lpBuffer, DWORD dwBytesToRead, LPDWORD lpdwBytesReturned, LPOVERLAPPED lpOverlapped)

参数说明

ftHandle— 设备句柄。

lpBuffer — 数据接收缓冲区。

dwBytesToRead — 要读取的数据的长度。

lpdwBytesReturned— 返回实际读取到的数据的长度。

lpOverlapped — 重叠的数据结构指针。

返回值

成功则返回非零值；如果失败则返回0。

备注

FT_W32_ReadFile 函数支持重叠I/O和非重叠I/O两种方式，但在 Linux, Mac OS X 和 Windows CE 系统平台下只支持非重叠I/O。

非重叠I/O

非重叠I/O方式，参数 lpOverlapped 必须设置为 NULL。

FT_W32_ReadFile 函数通过参数 lpdwBytesReturned 返回读取到的数据长度。

FT_W32_ReadFile 函数直到读取 dwBytesToRead 长度的数据到缓冲区才返回。接收缓冲区中的数据个数可以通过调用 FT_GetStatus 或 FT_GetQueueStatus 来获取，然后传递给参数 dwBytesToRead，这样函数可以迅速读取对应长度的数据然后立即返回。

如果调用 FT_W32_ReadFile 函数之前通过调用 FT_W32_SetCommTimeouts 函数设置了超时，FT_W32_ReadFile 函数在发生超时或 dwBytesToRead 长度的数据已经读完时返回。如果产生超时，函数读取一定的数据，返回非零值。

应用程度使用 FT_W32_ReadFile 函数时，应该判断函数的返回值以及参数 lpdwBytesReturned 的值，然后对缓冲区的数据做读写，防止越界。

如果函数返回TRUE，而且参数 lpdwBytesReturned 与参数 dwBytesToRead 的值相等，即读取到的长度与计划读取的长度相同，那么，该函数正常完成；如果返回TRUE，但参数 lpdwBytesReturned 的值小于参数 dwBytesToRead 的值，说明产生了超时，读取操作只完成了一部分。

注意，当发生超时，且没有读取到任何数据，返回值仍旧为TRUE。

如果返回值为 FALSE 表明函数的参数有问题，或者发生致命错误（诸如USB连接中断）。

重叠 I/O

当设备以重叠I/O方式打开时，向设备发起请求等待设备响应时，可以处理其他的任务，完成额外的工作。这种方式与非重叠I/O中向设备发起请求等待设备响应后才能继续执行后续操作的方式完全不同。

参数 lpOverlapped 必须指向经过初始化的 OVERLAPPED 结构体。

如果输入缓冲区中有足够的数据满足读取请求，则函数调用读取到数据后立即返回；如果输入缓冲区中数据长度小于请求的数据长度，则请求立即返回，且触发错误。调用者可以通过 FT_W32_GetLastError 函数来查询错误原因。；如果错误码为 ERROR_IO_PENDING，说明重叠操作仍在执行，程序可以去处理别的工作；程序可以通过调用 FT_W32_GetOverlappedResult 函数来查询重叠I/O的执行结果。

如果成功，读取到的数据字节数通过参数 lpdwBytesReturned 返回。

代码示例

1. 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, &osRead)) {
if (dwToRead == dwRead){
// FT_W32_ReadFile OK
}
else{
// FT_W32_ReadFile timeout
}
}
else{
// FT_W32_ReadFile failed
}
2. 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 };
osRead.hEvent = CreateEvent (NULL, FALSE, FALSE, NULL);
if (!FT_W32_ReadFile(ftHandle, Buf, dwToRead, &dwRead, &osRead)) {
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
}

CloseHandle (osRead.hEvent);