介绍FT_ListDevices函数的用法、参数、返回值、注意事项、适用的操作系统环境、调用代码示例等。
支持的操作系统
Linux
Mac OS X 10.4 以上版本
Windows 2000 以上版本
Windows CE 4.2 以上版本
概述
该函数返回接入系统的设备的特定项的信息,如接入系统的设备数量、设备序列号、设备描述符、LocationID等。
定义
FT_STATUS FT_ListDevices (PVOID pvArg1, PVOID pvArg2, DWORD dwFlags)
参数说明
pvArg1— 其功能和含义根据dwFlags确定。
pvArg2 — 其功能和含义根据dwFlags确定。
dwFlags— 定义返回的信息的格式和内容。
返回值
成功则返回FT_OK,如果失败则根据错误原因返回特定的错误码(FT_*).
备注
该函数根据参数值不同,可以获取多种形式的信息。相对而言,调用FT_CreateDeviceInfoList、FT_GetDeviceInfoList和FT_GetDeviceInfoDetail功能更丰富一些,因为可以一次获取设备的所有信息。
本函数最简单的信息格式,可以获取接入系统的设备的个数。如果dwFlags中设置FT_LIST_NUMBER_ONLY位,则pvArg1为指向存储设备个数的DWORD地址的指针。
除了可以获取设备数,还可以获取是信息和调用形式包括:
FT_OPEN_BY_SERIAL_NUMBER,获取设备的序列号;
FT_OPEN_BY_DESCRIPTION,获取设备的描述符;
FT_OPEN_BY_LOCATION ,获取设备的LocationID;
以上几个标志位均未设置时,默认返回序列号。
获取单一设备的字符串类型的信息(序列号、描述符)
本函数可以用于获取单一指定设备的信息,以字符串形式输出给参数pvArg2。在dwFlags中设置FT_LIST_BY_INDEX标志位、FT_OPEN_BY_SERIAL_NUMBER 或 FT_OPEN_BY_DESCRIPTION 标志位, 则,参数pvArg1为指定的设备索引, 参数pvArg2 为指向设备信息字符串的指针。设备索引值从0开始,如果索引值无效,函数返回错误码FT_DEVICE_NOT_FOUND。
获取所有设备的字符串类型的信息(序列号、描述符)
本函数也可以用于获取所有接入的设备的信息,以字符串形式输出给参数pvArg1。在dwFlags中设置FT_LIST_ALL标志位、FT_OPEN_BY_SERIAL_NUMBER 或 FT_OPEN_BY_DESCRIPTION 标志位, 则,参数pvArg1为指向指针数组的指针,指针数组每个元素为指向存储设备信息字符串的缓冲区的指针, 参数pvArg2 为指向存储设备个数的地址的指针。注意,参数pvArg1指向的指针数组中最后一个元素为NULL指针,这样,该数组中元素个数比设备个数多出一个。
获取单一设备的location ID的信息
特定设备的 location ID 通过在dwFlags中设置 FT_LIST_BY_INDEX 和 FT_OPEN_BY_LOCATION 标志位来获取。 这时,参数pvArg1 代表设备索引;参数pvArg2 为指向long类型的指针,其指向空间存储 location ID。设备索引值从0开始,如果索引值无效,函数返回FT_DEVICE_NOT_FOUND。注意:Windows CE and Linux 操作系统下不支持LocationID。
获取单一设备的location ID的信息
所有设备的location IDs通过在dwFlags中设置 FT_LIST_ALL 和 FT_OPEN_BY_LOCATION 标志位来获取。 参数 pvArg1 指向long类型数组的指针,数组元素为各个设备的locationID。参数 pvArg2 为存储设备个数的DWORD类型空间的指针.。
代码示例
代码示例中用到如下变量:
FT_STATUS ftStatus;
DWORD numDevs;
1. 获取接入系统的设备的个数
ftStatus = FT_ListDevices(&numDevs,NULL,FT_LIST_NUMBER_ONLY);
if (ftStatus == FT_OK) {
// FT_ListDevices OK, number of devices connected is in numDevs
}
else {
// FT_ListDevices failed
}
2. 获取第一个设备的序列号
DWORD devIndex = 0; // first device
char Buffer[64]; // more than enough room!
ftStatus =
FT_ListDevices((PVOID)devIndex,Buffer,FT_LIST_BY_INDEX|FT_OPEN_BY_SERIAL_NUMBER);
if (ftStatus == FT_OK) {
// FT_ListDevices OK, serial number is in Buffer
}
else {
// FT_ListDevices failed
}
注意设备索引从0开始编号. 有多个设备接入时,可以递增设备索引号来依次获取每个设备的序列号。
3. 获取所有设备的描述符
char *BufPtrs[3]; // pointer to array of 3 pointers
char Buffer1[64]; // buffer for description of first device
char Buffer2[64]; // buffer for description of second device
// initialize the array of pointers
BufPtrs[0] = Buffer1;
BufPtrs[1] = Buffer2;
BufPtrs[2] = NULL; // last entry should be NULLftStatus = FT_ListDevices(BufPtrs,&numDevs,FT_LIST_ALL|FT_OPEN_BY_DESCRIPTION);
if (ftStatus == FT_OK) {
// FT_ListDevices OK, product descriptions are in Buffer1 and Buffer2, and
// numDevs contains the number of devices connected
}
else {
// FT_ListDevices failed
}
注意:本示例中接入两台设备;实际使用中,需要根据设备数量分配足够的空间来存储。
4. 获取所有设备的locationID
long locIdBuf[16];
ftStatus = FT_ListDevices(locIdBuf,&numDevs,FT_LIST_ALL|FT_OPEN_BY_LOCATION);
if (ftStatus == FT_OK) {
// FT_ListDevices OK, location IDs are in locIdBuf, and
// numDevs contains the number of devices connected
}
else {
// FT_ListDevices failed
}
暂无评论内容