-
Notifications
You must be signed in to change notification settings - Fork 1
/
ftd2xx.h
executable file
·3392 lines (3201 loc) · 141 KB
/
ftd2xx.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/*++
Copyright (c) 2001-2021 Future Technology Devices International Limited
THIS SOFTWARE IS PROVIDED BY FUTURE TECHNOLOGY DEVICES INTERNATIONAL LIMITED "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
FUTURE TECHNOLOGY DEVICES INTERNATIONAL LIMITED BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
OF SUBSTITUTE GOODS OR SERVICES LOSS OF USE, DATA, OR PROFITS OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
FTDI DRIVERS MAY BE USED ONLY IN CONJUNCTION WITH PRODUCTS BASED ON FTDI PARTS.
FTDI DRIVERS MAY BE DISTRIBUTED IN ANY FORM AS LONG AS LICENSE INFORMATION IS NOT MODIFIED.
IF A CUSTOM VENDOR ID AND/OR PRODUCT ID OR DESCRIPTION STRING ARE USED, IT IS THE
RESPONSIBILITY OF THE PRODUCT MANUFACTURER TO MAINTAIN ANY CHANGES AND SUBSEQUENT WHQL
RE-CERTIFICATION AS A RESULT OF MAKING THESE CHANGES.
Module Name:
ftd2xx.h
Abstract:
Native USB device driver for FTDI FT232x, FT245x, FT2232x, FT4232x, FT2233H and FT4233H devices
FTD2XX library definitions
Environment:
kernel & user mode
--*/
/** @file ftd2xx.h
*/
#ifndef FTD2XX_H
#define FTD2XX_H
#ifdef _WIN32
// Compiling on Windows
#include <windows.h>
// The following ifdef block is the standard way of creating macros
// which make exporting from a DLL simpler. All files within this DLL
// are compiled with the FTD2XX_EXPORTS symbol defined on the command line.
// This symbol should not be defined on any project that uses this DLL.
// This way any other project whose source files include this file see
// FTD2XX_API functions as being imported from a DLL, whereas this DLL
// sees symbols defined with this macro as being exported.
#ifdef FTD2XX_EXPORTS
#define FTD2XX_API __declspec(dllexport)
#elif defined(FTD2XX_STATIC)
// Avoid decorations when linking statically to D2XX.
#define FTD2XX_API
// Static D2XX depends on these Windows libs:
#pragma comment(lib, "setupapi.lib")
#pragma comment(lib, "advapi32.lib")
#pragma comment(lib, "user32.lib")
#else
#define FTD2XX_API __declspec(dllimport)
#endif
#else // _WIN32
// Compiling on non-Windows platform.
#include "WinTypes.h"
// No decorations needed.
#define FTD2XX_API
#endif // _WIN32
/** @name FT_HANDLE
* An opaque value used as a handle to an opened FT device.
*/
typedef PVOID FT_HANDLE;
/** @{
* @name FT_STATUS
* @details Return status values for API calls.
*/
typedef ULONG FT_STATUS;
enum {
FT_OK,
FT_INVALID_HANDLE,
FT_DEVICE_NOT_FOUND,
FT_DEVICE_NOT_OPENED,
FT_IO_ERROR,
FT_INSUFFICIENT_RESOURCES,
FT_INVALID_PARAMETER,
FT_INVALID_BAUD_RATE,
FT_DEVICE_NOT_OPENED_FOR_ERASE,
FT_DEVICE_NOT_OPENED_FOR_WRITE,
FT_FAILED_TO_WRITE_DEVICE,
FT_EEPROM_READ_FAILED,
FT_EEPROM_WRITE_FAILED,
FT_EEPROM_ERASE_FAILED,
FT_EEPROM_NOT_PRESENT,
FT_EEPROM_NOT_PROGRAMMED,
FT_INVALID_ARGS,
FT_NOT_SUPPORTED,
FT_OTHER_ERROR,
FT_DEVICE_LIST_NOT_READY,
};
/** @} */
/** @name FT_SUCCESS Macro
* Macro to determine success of an API call.
* @returns Non-zero for successful call.
*/
#define FT_SUCCESS(status) ((status) == FT_OK)
/** @{
* @name FT_OpenEx Flags
* @see FT_OpenEx
*/
#define FT_OPEN_BY_SERIAL_NUMBER 1
#define FT_OPEN_BY_DESCRIPTION 2
#define FT_OPEN_BY_LOCATION 4
#define FT_OPEN_MASK (FT_OPEN_BY_SERIAL_NUMBER | \
FT_OPEN_BY_DESCRIPTION | \
FT_OPEN_BY_LOCATION)
/** @} */
/** @{
* @name FT_ListDevices Flags
* @remarks Used in conjunction with FT_OpenEx Flags
* @see FT_ListDevices
* @see FT_OpenEx
*/
#define FT_LIST_NUMBER_ONLY 0x80000000
#define FT_LIST_BY_INDEX 0x40000000
#define FT_LIST_ALL 0x20000000
#define FT_LIST_MASK (FT_LIST_NUMBER_ONLY|FT_LIST_BY_INDEX|FT_LIST_ALL)
/** @} */
/** @{
* @name Baud Rates
* Standard baud rates supported by many implementations and applications.
* @see FT_SetBaudRate
*/
#define FT_BAUD_300 300
#define FT_BAUD_600 600
#define FT_BAUD_1200 1200
#define FT_BAUD_2400 2400
#define FT_BAUD_4800 4800
#define FT_BAUD_9600 9600
#define FT_BAUD_14400 14400
#define FT_BAUD_19200 19200
#define FT_BAUD_38400 38400
#define FT_BAUD_57600 57600
#define FT_BAUD_115200 115200
#define FT_BAUD_230400 230400
#define FT_BAUD_460800 460800
#define FT_BAUD_921600 921600
/** @} */
/** @{
* @name Word Lengths
* @see FT_SetDataCharacteristics
*/
#define FT_BITS_8 (UCHAR) 8
#define FT_BITS_7 (UCHAR) 7
/** @} */
/** @{
* @name Stop Bits
* @see FT_SetDataCharacteristics
*/
#define FT_STOP_BITS_1 (UCHAR) 0
#define FT_STOP_BITS_2 (UCHAR) 2
/** @} */
/* * @name Parity
* @see FT_SetDataCharacteristics
* @{
*/
#define FT_PARITY_NONE (UCHAR) 0
#define FT_PARITY_ODD (UCHAR) 1
#define FT_PARITY_EVEN (UCHAR) 2
#define FT_PARITY_MARK (UCHAR) 3
#define FT_PARITY_SPACE (UCHAR) 4
/** @} */
/** @{
* @name Flow Control
* @see FT_SetFlowControl
*/
#define FT_FLOW_NONE 0x0000
#define FT_FLOW_RTS_CTS 0x0100
#define FT_FLOW_DTR_DSR 0x0200
#define FT_FLOW_XON_XOFF 0x0400
/** @} */
/** @{
* @name Purge rx and tx buffers
* @see FT_Purge
*/
#define FT_PURGE_RX 1
#define FT_PURGE_TX 2
/** @} */
/** @{
* @name Events
* @see FT_SetEventNotification
*/
typedef void(*PFT_EVENT_HANDLER)(DWORD, DWORD);
#define FT_EVENT_RXCHAR 1
#define FT_EVENT_MODEM_STATUS 2
#define FT_EVENT_LINE_STATUS 4
/** @} */
/** @{
* @name Timeouts
* @see FT_SetTimeouts
*/
#define FT_DEFAULT_RX_TIMEOUT 300
#define FT_DEFAULT_TX_TIMEOUT 300
/** @} */
/** @{
* @name Device Types
* @details Known supported FTDI device types supported by this library.
*/
typedef ULONG FT_DEVICE;
enum {
FT_DEVICE_BM,
FT_DEVICE_AM,
FT_DEVICE_100AX,
FT_DEVICE_UNKNOWN,
FT_DEVICE_2232C,
FT_DEVICE_232R,
FT_DEVICE_2232H,
FT_DEVICE_4232H,
FT_DEVICE_232H,
FT_DEVICE_X_SERIES,
FT_DEVICE_4222H_0,
FT_DEVICE_4222H_1_2,
FT_DEVICE_4222H_3,
FT_DEVICE_4222_PROG,
FT_DEVICE_900,
FT_DEVICE_930,
FT_DEVICE_UMFTPD3A,
FT_DEVICE_2233HP,
FT_DEVICE_4233HP,
FT_DEVICE_2232HP,
FT_DEVICE_4232HP,
FT_DEVICE_233HP,
FT_DEVICE_232HP,
FT_DEVICE_2232HA,
FT_DEVICE_4232HA,
};
/** @} */
/** @{
* @name Bit Modes
* @see FT_SetBitMode FT_GetBitMode
*/
#define FT_BITMODE_RESET 0x00
#define FT_BITMODE_ASYNC_BITBANG 0x01
#define FT_BITMODE_MPSSE 0x02
#define FT_BITMODE_SYNC_BITBANG 0x04
#define FT_BITMODE_MCU_HOST 0x08
#define FT_BITMODE_FAST_SERIAL 0x10
#define FT_BITMODE_CBUS_BITBANG 0x20
#define FT_BITMODE_SYNC_FIFO 0x40
/** @} */
/** @{
* @name FT232R CBUS Options EEPROM values
*/
#define FT_232R_CBUS_TXDEN 0x00 // Tx Data Enable
#define FT_232R_CBUS_PWRON 0x01 // Power On
#define FT_232R_CBUS_RXLED 0x02 // Rx LED
#define FT_232R_CBUS_TXLED 0x03 // Tx LED
#define FT_232R_CBUS_TXRXLED 0x04 // Tx and Rx LED
#define FT_232R_CBUS_SLEEP 0x05 // Sleep
#define FT_232R_CBUS_CLK48 0x06 // 48MHz clock
#define FT_232R_CBUS_CLK24 0x07 // 24MHz clock
#define FT_232R_CBUS_CLK12 0x08 // 12MHz clock
#define FT_232R_CBUS_CLK6 0x09 // 6MHz clock
#define FT_232R_CBUS_IOMODE 0x0A // IO Mode for CBUS bit-bang
#define FT_232R_CBUS_BITBANG_WR 0x0B // Bit-bang write strobe
#define FT_232R_CBUS_BITBANG_RD 0x0C // Bit-bang read strobe
#define FT_232R_CBUS0_RXF 0x0D // CBUS0 RXF#
#define FT_232R_CBUS1_TXE 0x0D // CBUS1 TXE#
#define FT_232R_CBUS2_RD 0x0D // CBUS2 RD#
#define FT_232R_CBUS3_WR 0x0D // CBUS3 WR#
/** @} */
/** @{
* @name FT232H CBUS Options EEPROM values
*/
#define FT_232H_CBUS_TRISTATE 0x00 // Tristate
#define FT_232H_CBUS_TXLED 0x01 // Tx LED
#define FT_232H_CBUS_RXLED 0x02 // Rx LED
#define FT_232H_CBUS_TXRXLED 0x03 // Tx and Rx LED
#define FT_232H_CBUS_PWREN 0x04 // Power Enable
#define FT_232H_CBUS_SLEEP 0x05 // Sleep
#define FT_232H_CBUS_DRIVE_0 0x06 // Drive pin to logic 0
#define FT_232H_CBUS_DRIVE_1 0x07 // Drive pin to logic 1
#define FT_232H_CBUS_IOMODE 0x08 // IO Mode for CBUS bit-bang
#define FT_232H_CBUS_TXDEN 0x09 // Tx Data Enable
#define FT_232H_CBUS_CLK30 0x0A // 30MHz clock
#define FT_232H_CBUS_CLK15 0x0B // 15MHz clock
#define FT_232H_CBUS_CLK7_5 0x0C // 7.5MHz clock
/** @} */
/** @{
* @name FT X Series CBUS Options EEPROM values
*/
#define FT_X_SERIES_CBUS_TRISTATE 0x00 // Tristate
#define FT_X_SERIES_CBUS_TXLED 0x01 // Tx LED
#define FT_X_SERIES_CBUS_RXLED 0x02 // Rx LED
#define FT_X_SERIES_CBUS_TXRXLED 0x03 // Tx and Rx LED
#define FT_X_SERIES_CBUS_PWREN 0x04 // Power Enable
#define FT_X_SERIES_CBUS_SLEEP 0x05 // Sleep
#define FT_X_SERIES_CBUS_DRIVE_0 0x06 // Drive pin to logic 0
#define FT_X_SERIES_CBUS_DRIVE_1 0x07 // Drive pin to logic 1
#define FT_X_SERIES_CBUS_IOMODE 0x08 // IO Mode for CBUS bit-bang
#define FT_X_SERIES_CBUS_TXDEN 0x09 // Tx Data Enable
#define FT_X_SERIES_CBUS_CLK24 0x0A // 24MHz clock
#define FT_X_SERIES_CBUS_CLK12 0x0B // 12MHz clock
#define FT_X_SERIES_CBUS_CLK6 0x0C // 6MHz clock
#define FT_X_SERIES_CBUS_BCD_CHARGER 0x0D // Battery charger detected
#define FT_X_SERIES_CBUS_BCD_CHARGER_N 0x0E // Battery charger detected inverted
#define FT_X_SERIES_CBUS_I2C_TXE 0x0F // I2C Tx empty
#define FT_X_SERIES_CBUS_I2C_RXF 0x10 // I2C Rx full
#define FT_X_SERIES_CBUS_VBUS_SENSE 0x11 // Detect VBUS
#define FT_X_SERIES_CBUS_BITBANG_WR 0x12 // Bit-bang write strobe
#define FT_X_SERIES_CBUS_BITBANG_RD 0x13 // Bit-bang read strobe
#define FT_X_SERIES_CBUS_TIMESTAMP 0x14 // Toggle output when a USB SOF token is received
#define FT_X_SERIES_CBUS_KEEP_AWAKE 0x15 //
/** @} */
/** @{
* @name Driver Types
*/
#define FT_DRIVER_TYPE_D2XX 0
#define FT_DRIVER_TYPE_VCP 1
/** @} */
/** @{
* @name FT_DEVICE_LIST_INFO_NODE Device Information Flags
* @par Summary
* These flags are used in the Flags member of FT_DEVICE_LIST_INFO_NODE to indicated the state of
* the device and speed of the device.
*/
enum {
FT_FLAGS_OPENED = 1,
FT_FLAGS_HISPEED = 2
};
/** @} */
#ifdef __cplusplus
extern "C" {
#endif
#ifdef FTD2XX_STATIC
FTD2XX_API FT_STATUS WINAPI FT_Initialise(
void
);
FTD2XX_API void WINAPI FT_Finalise(
void
);
#endif // FTD2XX_STATIC
/** * @name D2XX Classic Functions
The functions listed in this section are compatible with all FTDI devices.
*/
/** @{ */
#ifndef _WIN32
/** @noop FT_SetVIDPID
* @par Supported Operating Systems
* Linux
* Mac OS X (10.4 and later)
* @par Summary
* A command to include a custom VID and PID combination within the internal device list table.
* This will allow the driver to load for the specified VID and PID combination.
* @param dwVID Device Vendor ID (VID)
* @param dwPID Device Product ID (PID)
* @returns
* FT_OK if successful, otherwise the return value is an FT error code.
* @remarks
* By default, the driver will support a limited set of VID and PID matched devices (VID 0x0403
* with PIDs for standard FTDI devices only).
* @n In order to use the driver with other VID and PID combinations the FT_SetVIDPID function
* must be used prior to calling FT_ListDevices, FT_Open, FT_OpenEx or FT_CreateDeviceInfoList.
* @note Extra function for non-Windows platforms to compensate for lack of .INF file to specify
* Vendor and Product IDs.
*/
FTD2XX_API FT_STATUS FT_SetVIDPID(
DWORD dwVID,
DWORD dwPID
);
/** @noop FT_GetVIDPID
* @par Supported Operating Systems
* Linux
* Mac OS X (10.4 and later)
* @par Summary
* A command to retrieve the current VID and PID combination from within the internal device list table.
* @param pdwVID Pointer to DWORD that will contain the internal VID
* @param pdwPID Pointer to DWORD that will contain the internal PID
* @returns
* FT_OK if successful, otherwise the return value is an FT error code.
* @remarks
* @note Extra function for non-Windows platforms to compensate for lack of .INF file to specify Vendor and Product IDs.
* @see FT_SetVIDPID.
*/
FTD2XX_API FT_STATUS FT_GetVIDPID(
DWORD * pdwVID,
DWORD * pdwPID
);
#endif // _WIN32
/** @noop FT_CreateDeviceInfoList
* @par Supported Operating Systems
* Linux
* Mac OS X (10.4 and later)
* Windows (2000 and later)
* Windows CE (4.2 and later)
* @par Summary
* This function builds a device information list and returns the number of D2XX devices connected to the
* system. The list contains information about both unopen and open devices.
* @param lpdwNumDevs Pointer to unsigned long to store the number of devices connected.
* @returns
* FT_OK if successful, otherwise the return value is an FT error code.
* @remarks
* An application can use this function to get the number of devices attached to the system. It can then
* allocate space for the device information list and retrieve the list using FT_GetDeviceInfoList or
* FT_GetDeviceInfoDetail.
* @n If the devices connected to the system change, the device info list will not be updated until
* FT_CreateDeviceInfoList is called again.
* @see FT_GetDeviceInfoList
* @see FT_GetDeviceInfoDetail
*/
FTD2XX_API FT_STATUS WINAPI FT_CreateDeviceInfoList(
LPDWORD lpdwNumDevs
);
/** @noop FT_DEVICE_LIST_INFO_NODE
* @par Summary
* This structure is used for passing information about a device back from the FT_GetDeviceInfoList function.
* @see FT_GetDeviceInfoList
*/
typedef struct _ft_device_list_info_node {
ULONG Flags;
ULONG Type;
ULONG ID;
DWORD LocId;
char SerialNumber[16];
char Description[64];
FT_HANDLE ftHandle;
} FT_DEVICE_LIST_INFO_NODE;
/** @noop FT_GetDeviceInfoList
* @par Supported Operating Systems
* Linux
* Mac OS X (10.4 and later)
* Windows (2000 and later)
* Windows CE (4.2 and later)
* @par Summary
* This function returns a device information list and the number of D2XX devices in the list.
* @param *pDest Pointer to an array of FT_DEVICE_LIST_INFO_NODE structures.
* @param lpdwNumDevs Pointer to the number of elements in the array.
* @returns
* FT_OK if successful, otherwise the return value is an FT error code.
* @remarks
* This function should only be called after calling FT_CreateDeviceInfoList. If the devices connected to the
* system change, the device info list will not be updated until FT_CreateDeviceInfoList is called again.
* Location ID information is not returned for devices that are open when FT_CreateDeviceInfoList is called.
* Information is not available for devices which are open in other processes. In this case, the Flags
* parameter of the FT_DEVICE_LIST_INFO_NODE will indicate that the device is open, but other fields will
* be unpopulated.
* @n The flag value is a 4-byte bit map containing miscellaneous data as defined Appendix A - Type
* Definitions. Bit 0 (least significant bit) of this number indicates if the port is open (1) or closed (0). Bit 1
* indicates if the device is enumerated as a high-speed USB device (2) or a full-speed USB device (0). The
* remaining bits (2 - 31) are reserved.
* @n The array of FT_DEVICE_LIST_INFO_NODES contains all available data on each device. The structure of
* FT_DEVICE_LIST_INFO_NODES is given in the Appendix. The storage for the list must be allocated by
* the application. The number of devices returned by FT_CreateDeviceInfoList can be used to do this.
* When programming in Visual Basic, LabVIEW or similar languages, FT_GetDeviceInfoDetail may be
* required instead of this function.
* @note Please note that Windows CE does not support location IDs. As such, the Location ID parameter in the
* structure will be empty.
* @see FT_CreateDeviceInfoList
*/
FTD2XX_API FT_STATUS WINAPI FT_GetDeviceInfoList(
FT_DEVICE_LIST_INFO_NODE *pDest,
LPDWORD lpdwNumDevs
);
/** @noop FT_GetDeviceInfoDetail
* @par Supported Operating Systems
* Linux
* Mac OS X (10.4 and later)
* Windows (2000 and later)
* Windows CE (4.2 and later)
* @par Summary
* This function returns an entry from the device information list.
* @param dwIndex Index of the entry in the device info list.
* @param lpdwFlags Pointer to unsigned long to store the flag value.
* @param lpdwType Pointer to unsigned long to store device type.
* @param lpdwID Pointer to unsigned long to store device ID.
* @param lpdwLocId Pointer to unsigned long to store the device location ID.
* @param lpSerialNumber Pointer to buffer to store device serial number as a nullterminated string.
* @param lpDescription Pointer to buffer to store device description as a null-terminated string.
* @param *pftHandle Pointer to a variable of type FT_HANDLE where the handle will be stored.
* @returns
* FT_OK if successful, otherwise the return value is an FT error code.
* @remarks
* This function should only be called after calling FT_CreateDeviceInfoList. If the devices connected to the
* system change, the device info list will not be updated until FT_CreateDeviceInfoList is called again.
* @n The index value is zero-based.
* @n The flag value is a 4-byte bit map containing miscellaneous data as defined Appendix A - Type
* Definitions. Bit 0 (least significant bit) of this number indicates if the port is open (1) or closed (0). Bit 1
* indicates if the device is enumerated as a high-speed USB device (2) or a full-speed USB device (0). The
* remaining bits (2 - 31) are reserved.
* @n Location ID information is not returned for devices that are open when FT_CreateDeviceInfoList is called.
* Information is not available for devices which are open in other processes. In this case, the lpdwFlags
* parameter will indicate that the device is open, but other fields will be unpopulated.
* To return the whole device info list as an array of FT_DEVICE_LIST_INFO_NODE structures, use
* FT_CreateDeviceInfoList.
* @note Please note that Windows CE does not support location IDs. As such, the Location ID parameter in the
* structure will be empty.
* @see FT_CreateDeviceInfoList
*/
FTD2XX_API FT_STATUS WINAPI FT_GetDeviceInfoDetail(
DWORD dwIndex,
LPDWORD lpdwFlags,
LPDWORD lpdwType,
LPDWORD lpdwID,
LPDWORD lpdwLocId,
LPVOID lpSerialNumber,
LPVOID lpDescription,
FT_HANDLE *pftHandle
);
/** @noop FT_ListDevices
* @par Summary
* 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.
* @param pvArg1 Meaning depends on dwFlags.
* @param pvArg2 Meaning depends on dwFlags.
* @param dwFlags Determines format of returned information.
* @returns
* 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.
* @n 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.
* @n 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.
* @n 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.
* @n 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
* zerobased, 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.
* @n 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.
* @see FT_CreateDeviceInfoList
* @see FT_GetDeviceInfoList
* @see FT_GetDeviceInfoDetail
*/
FTD2XX_API FT_STATUS WINAPI FT_ListDevices(
PVOID pvArg1,
PVOID pvArg2,
DWORD dwFlags
);
/** @noop FT_Open
* @par Supported Operating Systems
* Linux
* Mac OS X (10.4 and later)
* Windows (2000 and later)
* Windows CE (4.2 and later)
* @par Summary
* Open the device and return a handle which will be used for subsequent accesses.
* @param deviceNumber Index of the device to open. Indices are 0 based.
* @param pHandle Pointer to a variable of type FT_HANDLE where the handle will be stored. This handle must
* be used to access the device.
* @return
* FT_OK if successful, otherwise the return value is an FT error code.
* @remarks
* Although this function can be used to open multiple devices by setting iDevice to 0, 1, 2 etc. there is no
* ability to open a specific device. To open named devices, use the function FT_OpenEx.
* @see FT_OpenEx.
*/
FTD2XX_API FT_STATUS WINAPI FT_Open(
int deviceNumber,
FT_HANDLE *pHandle
);
/** @noop FT_OpenEx
* @par Supported Operating Systems
* Linux
* Mac OS X (10.4 and later)
* Windows (2000 and later)
* Windows CE (4.2 and later)
* @par Summary
* Open the specified device and return a handle that will be used for subsequent accesses. The device can
* be specified by its serial number, device description or location.
* @n This function can also be used to open multiple devices simultaneously. Multiple devices can be specified
* by serial number, device description or location ID (location information derived from the physical
* location of a device on USB). Location IDs for specific USB ports can be obtained using the utility
* USBView and are given in hexadecimal format. Location IDs for devices connected to a system can be
* obtained by calling FT_GetDeviceInfoList or FT_ListDevices with the appropriate flags.
* @param pvArg1 Pointer to an argument whose type depends on the value of dwFlags.
* It is normally be interpreted as a pointer to a null terminated string.
* @param dwFlags FT_OPEN_BY_SERIAL_NUMBER, FT_OPEN_BY_DESCRIPTION or FT_OPEN_BY_LOCATION.
* @param pHandle Pointer to a variable of type FT_HANDLE where the handle will be
* stored. This handle must be used to access the device.
* @returns
* FT_OK if successful, otherwise the return value is an FT error code.
* @remarks
* The parameter specified in pvArg1 depends on dwFlags: if dwFlags is FT_OPEN_BY_SERIAL_NUMBER,
* pvArg1 is interpreted as a pointer to a null-terminated string that represents the serial number of the
* device; if dwFlags is FT_OPEN_BY_DESCRIPTION, pvArg1 is interpreted as a pointer to a nullterminated
* string that represents the device description; if dwFlags is FT_OPEN_BY_LOCATION, pvArg1
* is interpreted as a long value that contains the location ID of the device. Please note that Windows CE
* and Linux do not support location IDs.
* @n ftHandle is a pointer to a variable of type FT_HANDLE where the handle is to be stored. This handle must
* be used to access the device.
*/
FTD2XX_API FT_STATUS WINAPI FT_OpenEx(
PVOID pvArg1,
DWORD dwFlags,
FT_HANDLE *pHandle
);
/** @noop FT_Close
* @par Supported Operating Systems
* Linux
* Mac OS X (10.4 and later)
* Windows (2000 and later)
* Windows CE (4.2 and later)
* @par Summary
* Close an open device.
* @param ftHandle Handle of the device.
* @returns
* FT_OK if successful, otherwise the return value is an FT error code.
*/
FTD2XX_API FT_STATUS WINAPI FT_Close(
FT_HANDLE ftHandle
);
/** @noop FT_Read
* @par Supported Operating Systems
* Linux
* Mac OS X (10.4 and later)
* Windows (2000 and later)
* Windows CE (4.2 and later)
* @par Summary
* Read data from the device.
* @param ftHandle Handle of the device.
* @param lpBuffer Pointer to the buffer that receives the data from the device.
* @param dwBytesToRead Number of bytes to be read from the device.
* @param lpdwBytesReturned Pointer to a variable of type DWORD which receives the number of
* bytes read from the device.
* @returns
* FT_OK if successful, FT_IO_ERROR otherwise. $see FT_STATUS
* @remarks
* FT_Read always returns the number of bytes read in lpdwBytesReturned.
* @n This function does not return until dwBytesToRead bytes have been read into the buffer. The number of
* bytes in the receive queue can be determined by calling FT_GetStatus or FT_GetQueueStatus, and
* passed to FT_Read as dwBytesToRead so that the function reads the device and returns immediately.
* When a read timeout value has been specified in a previous call to FT_SetTimeouts, FT_Read returns
* when the timer expires or dwBytesToRead have been read, whichever occurs first. If the timeout
* occurred, FT_Read reads available data into the buffer and returns FT_OK.
* @n An application should use the function return value and lpdwBytesReturned when processing the buffer.
* If the return value is FT_OK, and lpdwBytesReturned is equal to dwBytesToRead then FT_Read has
* completed normally. If the return value is FT_OK, and lpdwBytesReturned is less then dwBytesToRead
* then a timeout has occurred and the read has been partially completed. Note that if a timeout occurred
* and no data was read, the return value is still FT_OK.
* @n A return value of FT_IO_ERROR suggests an error in the parameters of the function, or a fatal error like a
* USB disconnect has occurred.
*/
FTD2XX_API FT_STATUS WINAPI FT_Read(
FT_HANDLE ftHandle,
LPVOID lpBuffer,
DWORD dwBytesToRead,
LPDWORD lpdwBytesReturned
);
/** @noop FT_Write
* @par Supported Operating Systems
* Linux
* Mac OS X (10.4 and later)
* Windows (2000 and later)
* Windows CE (4.2 and later)
* @par Summary
* Write data to the device.
* @param ftHandle Handle of the device.
* @param lpBuffer Pointer to the buffer that contains the data to be written to the device.
* @param dwBytesToWrite Number of bytes to write to the device.
* @param lpdwBytesWritten Pointer to a variable of type DWORD which receives the number of
* bytes written to the device.
* @returns
* FT_OK if successful, otherwise the return value is an FT error code.
*/
FTD2XX_API FT_STATUS WINAPI FT_Write(
FT_HANDLE ftHandle,
LPVOID lpBuffer,
DWORD dwBytesToWrite,
LPDWORD lpdwBytesWritten
);
/** @noop FT_SetBaudRate
* @par Supported Operating Systems
* Linux
* Mac OS X (10.4 and later)
* Windows (2000 and later)
* Windows CE (4.2 and later)
* @par Summary
* This function sets the baud rate for the device.
* @param ftHandle Handle of the device.
* @param dwBaudRate Baud rate.
* @returns
* FT_OK if successful, otherwise the return value is an FT error code
*/
FTD2XX_API FT_STATUS WINAPI FT_SetBaudRate(
FT_HANDLE ftHandle,
ULONG dwBaudRate
);
/** @noop FT_SetDivisor
* @par Supported Operating Systems
* Linux
* Mac OS X (10.4 and later)
* Windows (2000 and later)
* Windows CE (4.2 and later)
* @par Summary
* This function sets the baud rate for the device. It is used to set non-standard baud rates.
* @param ftHandle Handle of the device.
* @param usDivisor Divisor.
* @returns
* FT_OK if successful, otherwise the return value is an FT error code.
* @remarks
* This function is no longer required as FT_SetBaudRate will now automatically calculate the required
* divisor for a requested baud rate. The application note "Setting baud rates for the FT8U232AM" is
* available from the Application Notes section of the FTDI website describes how to calculate the divisor for
* a non-standard baud rate.
*/
FTD2XX_API FT_STATUS WINAPI FT_SetDivisor(
FT_HANDLE ftHandle,
USHORT usDivisor
);
/** @noop FT_SetDataCharacteristics
* @par Supported Operating Systems
* Linux
* Mac OS X (10.4 and later)
* Windows (2000 and later)
* Windows CE (4.2 and later)
* @par Summary
* This function sets the data characteristics for the device.
* @param ftHandle Handle of the device.
* @param uWordLength Number of bits per word - must be FT_BITS_8 or FT_BITS_7.
* @param uStopBits Number of stop bits - must be FT_STOP_BITS_1 or FT_STOP_BITS_2.
* @param uParity Parity - must be FT_PARITY_NONE, FT_PARITY_ODD, FT_PARITY_EVEN,
* FT_PARITY_MARK or FT_PARITY SPACE.
* @returns
* FT_OK if successful, otherwise the return value is an FT error code.
*/
FTD2XX_API FT_STATUS WINAPI FT_SetDataCharacteristics(
FT_HANDLE ftHandle,
UCHAR uWordLength,
UCHAR uStopBits,
UCHAR uParity
);
/** @noop FT_SetTimeouts
* @par Supported Operating Systems
* Linux
* Mac OS X (10.4 and later)
* Windows (2000 and later)
* Windows CE (4.2 and later)
* @par Summary
* This function sets the read and write timeouts for the device.
* @param ftHandle Handle of the device.
* @param dwReadTimeout Read timeout in milliseconds.
* @param dwWriteTimeout Write timeout in milliseconds.
* @returns
* FT_OK if successful, otherwise the return value is an FT error code.
*/
FTD2XX_API FT_STATUS WINAPI FT_SetTimeouts(
FT_HANDLE ftHandle,
ULONG dwReadTimeout,
ULONG dwWriteTimeout
);
/** @noop FT_SetFlowControl
* @par Supported Operating Systems
* Linux
* Mac OS X (10.4 and later)
* Windows (2000 and later)
* Windows CE (4.2 and later)
* @par Summary
* This function sets the flow control for the device.
* @param ftHandle Handle of the device.
* @param usFlowControl Must be one of FT_FLOW_NONE, FT_FLOW_RTS_CTS, FT_FLOW_DTR_DSR or
* FT_FLOW_XON_XOFF.
* @param uXonChar Character used to signal Xon. Only used if flow control is FT_FLOW_XON_XOFF.
* @param uXoffChar Character used to signal Xoff. Only used if flow control is FT_FLOW_XON_XOFF.
* @returns
* FT_OK if successful, otherwise the return value is an FT error code.
*/
FTD2XX_API FT_STATUS WINAPI FT_SetFlowControl(
FT_HANDLE ftHandle,
USHORT usFlowControl,
UCHAR uXonChar,
UCHAR uXoffChar
);
/** @noop FT_SetDtr
* @par Supported Operating Systems
* Linux
* Mac OS X (10.4 and later)
* Windows (2000 and later)
* Windows CE (4.2 and later)
* @par Summary
* This function sets the Data Terminal Ready (DTR) control signal.
* @param ftHandle Handle of the device.
* @returns
* FT_OK if successful, otherwise the return value is an FT error code.
* @remarks
* This function asserts the Data Terminal Ready (DTR) line of the device.
*/
FTD2XX_API FT_STATUS WINAPI FT_SetDtr(
FT_HANDLE ftHandle
);
/** @noop FT_ClrDtr
* @par Supported Operating Systems
* Linux
* Mac OS X (10.4 and later)
* Windows (2000 and later)
* Windows CE (4.2 and later)
* @par Summary
* This function clears the Data Terminal Ready (DTR) control signal.
* @param ftHandle Handle of the device.
* @returns
* FT_OK if successful, otherwise the return value is an FT error code.
* @remarks
* This function de-asserts the Data Terminal Ready (DTR) line of the device.
*/
FTD2XX_API FT_STATUS WINAPI FT_ClrDtr(
FT_HANDLE ftHandle
);
/** @noop FT_SetRts
* @par Supported Operating Systems
* Linux
* Mac OS X (10.4 and later)
* Windows (2000 and later)
* Windows CE (4.2 and later)
* @par Summary
* This function sets the Request To Send (RTS) control signal.
* @param ftHandle Handle of the device.
* @returns
* FT_OK if successful, otherwise the return value is an FT error code.
* @remarks
* This function asserts the Request To Send (RTS) line of the device.
*/
FTD2XX_API FT_STATUS WINAPI FT_SetRts(
FT_HANDLE ftHandle
);
/** @noop FT_ClrRts
* @par Supported Operating Systems
* Linux
* Mac OS X (10.4 and later)
* Windows (2000 and later)
* Windows CE (4.2 and later)
* @par Summary
* This function clears the Request To Send (RTS) control signal.
* @param ftHandle Handle of the device.
* @returns
* FT_OK if successful, otherwise the return value is an FT error code.
* @remarks
* This function de-asserts the Request To Send (RTS) line of the device.
*/
FTD2XX_API FT_STATUS WINAPI FT_ClrRts(
FT_HANDLE ftHandle
);
/** @noop FT_GetModemStatus
* @par Supported Operating Systems
* Linux
* Mac OS X (10.4 and later)
* Windows (2000 and later)
* Windows CE (4.2 and later)
* @par Summary
* Gets the modem status and line status from the device.
* @param ftHandle Handle of the device.
* @param lpdwModemStatus Pointer to a variable of type DWORD which receives the modem
* status and line status from the device.
* @returns
* FT_OK if successful, otherwise the return value is an FT error code.
* @remarks
* The least significant byte of the lpdwModemStatus value holds the modem status. On Windows and
* Windows CE, the line status is held in the second least significant byte of the lpdwModemStatus value.
* @n The modem status is bit-mapped as follows: Clear To Send (CTS) = 0x10, Data Set Ready (DSR) = 0x20,
* Ring Indicator (RI) = 0x40, Data Carrier Detect (DCD) = 0x80.
* @n The line status is bit-mapped as follows: Overrun Error (OE) = 0x02, Parity Error (PE) = 0x04, Framing
* Error (FE) = 0x08, Break Interrupt (BI) = 0x10.
*/
FTD2XX_API FT_STATUS WINAPI FT_GetModemStatus(
FT_HANDLE ftHandle,
ULONG *lpdwModemStatus
);
/** @noop FT_GetQueueStatus
* @par Supported Operating Systems
* Linux
* Mac OS X (10.4 and later)
* Windows (2000 and later)
* Windows CE (4.2 and later)
* @par Summary
* Gets the number of bytes in the receive queue.
* @param ftHandle Handle of the device.
* @param lpdwAmountInRxQueue Pointer to a variable of type DWORD which receives the number of
* bytes in the receive queue.
* @returns
* FT_OK if successful, otherwise the return value is an FT error code.
*/
FTD2XX_API FT_STATUS WINAPI FT_GetQueueStatus(
FT_HANDLE ftHandle,
DWORD *lpdwAmountInRxQueue
);
/** @noop FT_GetDeviceInfo
* @par Supported Operating Systems
* Linux
* Mac OS X (10.4 and later)
* Windows (2000 and later)
* Windows CE (4.2 and later)
* @par Summary
* Get device information for an open device.
* @param ftHandle Handle of the device.
* @param lpftDevice Pointer to unsigned long to store device type.
* @param lpdwID Pointer to unsigned long to store device ID.
* @param pcSerialNumber Pointer to buffer to store device serial number as a nullterminated string.
* @param pcDescription Pointer to buffer to store device description as a null-terminated string.
* @param pvDummy Reserved for future use - should be set to NULL.
* @returns
* FT_OK if successful, otherwise the return value is an FT error code.
* @remarks
* This function is used to return the device type, device ID, device description and serial number.
* The device ID is encoded in a DWORD - the most significant word contains the vendor ID, and the least
* significant word contains the product ID. So the returned ID 0x04036001 corresponds to the device ID
* VID_0403&PID_6001.
*/
FTD2XX_API FT_STATUS WINAPI FT_GetDeviceInfo(
FT_HANDLE ftHandle,
FT_DEVICE *lpftDevice,
LPDWORD lpdwID,
PCHAR pcSerialNumber,
PCHAR pcDescription,
LPVOID pvDummy
);
#ifndef _WIN32
/**
* @note Extra function for non-Windows platforms to compensate for lack of .INF file to specify Vendor and Product IDs.