FT_ListDevices函数的用法

介绍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 NULL

ftStatus = 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
}