|
FT_STATUS
|
FT_ListDevices
|
(PVOID pvArg1, PVOID pvArg2, DWORD dwFlags)
|
Parameters
|
pvArg1
|
Meaning depends on dwFlags.
|
|
pvArg2
|
Meaning depends on dwFlags.
|
|
dwFlags
|
Determines format of returned information.
|
Return Value
FT_OK if successful, otherwise the return value is an FT error code.
Remarks
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
The examples that follow use these variables.
FT_STATUS ftStatus;
DWORD numDevs;
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
}
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.
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.
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.