FT_W32_WriteFile函数的用法

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

支持的操作系统

Linux

Mac OS X 10.4 以上版本

Windows 2000 以上版本

Windows CE 4.2 以上版本

概述

FT_W32_WriteFile 函数向设备输出数据。

定义

BOOL FT_W32_WriteFile (FT_HANDLE ftHandle, LPVOID lpBuffer, DWORD dwBytesToWrite,LPDWORD lpdwBytesWritten, LPOVERLAPPED lpOverlapped)

参数说明

ftHandle— 设备句柄。

lpBuffer — 存储要输出到设备的数据的缓冲区。

dwBytesToWrite— 要输出的数据的长度。

lpdwBytesWritten— 返回实际发送给设备的数据的长度。

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

返回值

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

备注

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

非重叠I/O

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

FT_W32_WriteFile 函数通过参数 lpdwBytesWritten 返回读取到的数据长度。

FT_W32_WriteFile 函数直到发送 dwBytesToWrite长度的数据到设备才返回。

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

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

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

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

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

重叠 I/O

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

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

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

如果成功，发送的数据字节数通过参数 lpdwBytesWritten 返回。

代码示例

1. This example shows how to write 128 bytes to the device using non-overlapped I/O.
FT_HANDLE ftHandle; // setup by FT_W32_CreateFile for overlapped i/o
char Buf[128]; // contains data to write to the device
DWORD dwToWrite = 128;
DWORD dwWritten;
if (FT_W32_WriteFile(ftHandle, Buf, dwToWrite, &dwWritten, &osWrite)) {
if (dwToWrite == dwWritten){
// FT_W32_WriteFile OK
}
else{
// FT_W32_WriteFile timeout
}
}
else{
// FT_W32_WriteFile failed
}
2. This example shows how to write 128 bytes to the device using overlapped I/O.
FT_HANDLE ftHandle; // setup by FT_W32_CreateFile for overlapped i/o
char Buf[128]; // contains data to write to the device
DWORD dwToWrite = 128;
DWORD dwWritten;
OVERLAPPED osWrite = { 0 };
if (!FT_W32_WriteFile(ftHandle, Buf, dwToWrite, &dwWritten, &osWrite)) {
if (FT_W32_GetLastError(ftHandle) == ERROR_IO_PENDING) {
// write is delayed so do some other stuff until …
if (!FT_W32_GetOverlappedResult(ftHandle, &osWrite, &dwWritten, FALSE)){
// error
}
else {
if (dwToWrite == dwWritten){
// FT_W32_WriteFile OK
}
else{
// FT_W32_WriteFile timeout
}

}
}
}
else {
// FT_W32_WriteFIle OK
}