FT_ListDevices

Supported Operating Systems by FT_ListDevices

Linux
Mac OS X (10.4 and later)
Windows (2000 and later)
Windows CE (4.2 and later)

Summary of FT_ListDevices

Gets information concerning the devices currently connected. This function can return information such
as the number of devices connected, the device serial number and device description strings, and the
location IDs of connected devices.

Definition of FT_ListDevices

FT_STATUS FT_ListDevices (PVOID pvArg1, PVOID pvArg2, DWORD dwFlags)

Parameters of FT_ListDevices

pvArg1        Meaning depends on dwFlags.
pvArg2        Meaning depends on dwFlags.
dwFlags      Determines format of returned information.

Return Value of FT_ListDevices

FT_OK if successful, otherwise the return value is an FT error code.

Remarks about FT_ListDevices

This function can be used in a number of ways to return different types of information.  A more powerful
way to get device information is to use the FT_CreateDeviceInfoList, FT_GetDeviceInfoList and
FT_GetDeviceInfoDetail functions as they return all the available information on devices.
In its simplest form, it can be used to return the number of devices currently connected. If
FT_LIST_NUMBER_ONLY bit is set in dwFlags, the parameter pvArg1 is interpreted as a pointer to a
DWORD location to store the number of devices currently connected.
It can be used to return device information: if FT_OPEN_BY_SERIAL_NUMBER bit is set in dwFlags, the
serial number string will be returned; if FT_OPEN_BY_DESCRIPTION bit is set in dwFlags, the product
description string will be returned; if FT_OPEN_BY_LOCATION bit is set in dwFlags, the Location ID will be
returned; if none of these bits is set, the serial number string will be returned by default.
It can be used to return device string information for a single device. If FT_LIST_BY_INDEX and
FT_OPEN_BY_SERIAL_NUMBER or FT_OPEN_BY_DESCRIPTION bits are set in dwFlags, the parameter
pvArg1 is interpreted as the index of the device, and the parameter pvArg2 is interpreted as a pointer to

a buffer to contain the appropriate string. Indexes are zero-based, and the error code
FT_DEVICE_NOT_FOUND is returned for an invalid index.
It can be used to return device string information for all connected devices. If FT_LIST_ALL  and
FT_OPEN_BY_SERIAL_NUMBER or FT_OPEN_BY_DESCRIPTION bits are set in dwFlags, the parameter
pvArg1 is interpreted as a pointer to an array of pointers to buffers to contain the appropriate strings and
the parameter pvArg2 is interpreted as a pointer to a DWORD location to store the number of devices
currently connected. Note that, for pvArg1, the last entry in the array of pointers to buffers should be a
NULL pointer so the array will contain one more location than the number of devices connected.
The location ID of a device is returned if FT_LIST_BY_INDEX and FT_OPEN_BY_LOCATION bits are set in
dwFlags. In this case the parameter pvArg1 is interpreted as the index of the device, and the parameter
pvArg2 is interpreted as a pointer to a variable of type long to contain the location ID. Indexes are zero-based, and the error code FT_DEVICE_NOT_FOUND is returned for an invalid index.  Please note that
Windows CE and Linux do not support location IDs.
The location IDs of all connected devices are returned if FT_LIST_ALL and FT_OPEN_BY_LOCATION bits
are set in dwFlags.  In this case, the parameter pvArg1 is interpreted as a pointer to an array of variables
of type long to contain the location IDs, and the parameter pvArg2 is interpreted as a pointer to a
DWORD location to store the number of devices currently connected.

Examples of FT_ListDevices

The examples that follow use these variables.
FT_STATUS ftStatus;
DWORD numDevs;
1. Get the number of devices currently connected
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. Get serial number of first device
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
}
Note that indexes are zero-based. If more than one device is connected, incrementing devIndex will get
the serial number of each connected device in turn.
3. Get device descriptions of all devices currently connected
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
}
Note that this example assumes that two devices are connected. If more devices are connected, then the
size of the array of pointers must be increased and more description buffers allocated.
4. Get locations of all devices currently connected
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
}
Note that this example assumes that no more than 16 devices are connected. If more devices are
connected, then the size of the array of pointers must be increased.