FT_Read函数的用法

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

支持的操作系统

Linux

Mac OS X 10.4 以上版本

Windows 2000 以上版本

Windows CE 4.2以上版本

概述

FT_Read函数从打开的设备中读取数据。

定义

FT_STATUS FT_Read (FT_HANDLE ftHandle, LPVOID lpBuffer, DWORD dwBytesToRead, LPDWORD lpdwBytesReturned)

参数说明

ftHandle—设备句柄。
lpBuffer—缓冲区指针，缓冲区用于存储从设备读取的数据。
dwBytesToRead—要读取的数据字节数。
lpdwBytesReturned—DWORD类型指针，返回真正读取到的数据字节数。

返回值

成功则返回FT_OK,如果失败则根据返回错误码(FT_IO_ERROR).

备注

FT_Read 始终通过参数 lpdwBytesReturned告知给调用者读取到的数据字节数。

FT_Read函数在读取完dwBytesToRead字节数的数据前不会自动返回，除非提前设置了超时参数。我们可以通过调用 FT_GetStatus 或 FT_GetQueueStatus 来先获取接收缓冲区中的数据长度，传递给FT_Read函数的参数dwBytesToRead ，这样，T_Read函数就可以迅速读取完毕并返回。防止设置的要读取数据长度超过实际存在的数据长度，导致函数等待。

防止T_Read函数无限等待，可以通过调用FT_SetTimeouts设置最长超时时间。当超时或 dwBytesToRead 个字节的数据已经读到，函数返回。如果发生超时，FT_Read函数读取可获取的数据放入缓冲区，返回 FT_OK。

使用该函数时，需要同时考虑函数返回值和参数 lpdwBytesReturned的值，以此来处理缓冲区，防止读取错误。
如果函数返回 FT_OK， 且参数lpdwBytesReturned 等于 dwBytesToRead的值，则 FT_Read 函数正常完成任务；如果返回FT_OK, 但 lpdwBytesReturned < dwBytesToRead ,则读取操作超时，仅读取到部分数据；如果超时，读取字节数为0，返回值仍旧是 FT_OK。函数返回 FT_IO_ERROR ，可能是由于参数指定错误，或者发生类似USB连接中断之类的错误。

代码示例

1. 获取接收缓冲区所有的数据
FT_HANDLE ftHandle;
FT_STATUS ftStatus;
DWORD EventDWord;
DWORD TxBytes;
DWORD RxBytes;
DWORD BytesReceived;
char RxBuffer[256];
ftStatus = FT_Open(0, &ftHandle);
if(ftStatus != FT_OK) {
// FT_Open failed
return;
}
FT_GetStatus(ftHandle,&RxBytes,&TxBytes,&EventDWord);
if (RxBytes > 0) {
ftStatus = FT_Read(ftHandle,RxBuffer,RxBytes,&BytesReceived);
if (ftStatus == FT_OK) {
// FT_Read OK
}
else {
// FT_Read Failed
}
}
FT_Close(ftHandle);
2. 设置5s超时
FT_HANDLE ftHandle;
FT_STATUS ftStatus;
DWORD RxBytes = 10;
DWORD BytesReceived;
char RxBuffer[256];
ftStatus = FT_Open(0, &ftHandle);
if(ftStatus != FT_OK) {
// FT_Open failed
return;
}
FT_SetTimeouts(ftHandle,5000,0);
ftStatus = FT_Read(ftHandle,RxBuffer,RxBytes,&BytesReceived);
if (ftStatus == FT_OK) {
if (BytesReceived == RxBytes) {
// FT_Read OK
}
else {
// FT_Read Timeout
}
}
else {
// FT_Read Failed
}
FT_Close(ftHandle);