forked from mikepb/go-serial
-
Notifications
You must be signed in to change notification settings - Fork 1
/
libserialport.h
1430 lines (1310 loc) · 42 KB
/
libserialport.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
/*
* This file is part of the libserialport project.
*
* Copyright (C) 2013 Martin Ling <[email protected]>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as
* published by the Free Software Foundation, either version 3 of the
* License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
/**
* @mainpage libserialport API
*
* Introduction
* ============
*
* libserialport is a minimal library written in C that is intended to take
* care of the OS-specific details when writing software that uses serial ports.
*
* By writing your serial code to use libserialport, you enable it to work
* transparently on any platform supported by the library.
*
* The operations that are supported are:
*
* - @ref Enumeration (obtaining a list of serial ports on the system)
* - @ref Ports
* - @ref Configuration (baud rate, parity, etc.)
* - @ref Signals (modem control lines, breaks, etc.)
* - @ref Data
* - @ref Waiting
* - @ref Errors
*
* libserialport is an open source project released under the LGPL3+ license.
*
* API principles
* ==============
*
* The API is simple, and designed to be a minimal wrapper around the serial
* port support in each OS.
*
* Most functions take a pointer to a struct sp_port, which represents a serial
* port. These structures are always allocated and freed by the library, using
* the functions in the @ref Enumeration "Enumeration" section.
*
* Most functions have return type @ref sp_return and can return only four
* possible error values:
*
* - @ref SP_ERR_ARG means that a function was called with invalid
* arguments. This implies a bug in the caller. The arguments passed would
* be invalid regardless of the underlying OS or serial device involved.
*
* - @ref SP_ERR_FAIL means that the OS reported a failure. The error code or
* message provided by the OS can be obtained by calling sp_last_error_code()
* or sp_last_error_message().
*
* - @ref SP_ERR_SUPP indicates that there is no support for the requested
* operation in the current OS, driver or device. No error message is
* available from the OS in this case. There is either no way to request
* the operation in the first place, or libserialport does not know how to
* do so in the current version.
*
* - @ref SP_ERR_MEM indicates that a memory allocation failed.
*
* All of these error values are negative.
*
* Calls that succeed return @ref SP_OK, which is equal to zero. Some functions
* declared @ref sp_return can also return a positive value for a successful
* numeric result, e.g. sp_blocking_read() or sp_blocking_write().
*/
#ifndef LIBSERIALPORT_LIBSERIALPORT_H
#define LIBSERIALPORT_LIBSERIALPORT_H
#ifdef __cplusplus
extern "C" {
#endif
#include <stddef.h>
#ifdef _WIN32
#include <windows.h>
#endif
/** Return values. */
enum sp_return {
/** Operation completed successfully. */
SP_OK = 0,
/** Invalid arguments were passed to the function. */
SP_ERR_ARG = -1,
/** A system error occured while executing the operation. */
SP_ERR_FAIL = -2,
/** A memory allocation failed while executing the operation. */
SP_ERR_MEM = -3,
/** The requested operation is not supported by this system or device. */
SP_ERR_SUPP = -4
};
/** Port access modes. */
enum sp_mode {
/** Open port for read access. */
SP_MODE_READ = 1,
/** Open port for write access. */
SP_MODE_WRITE = 2,
/** Open port for read and write access. */
SP_MODE_READ_WRITE = 3
};
/** Port events. */
enum sp_event {
/* Data received and ready to read. */
SP_EVENT_RX_READY = 1,
/* Ready to transmit new data. */
SP_EVENT_TX_READY = 2,
/* Error occured. */
SP_EVENT_ERROR = 4
};
/** Buffer selection. */
enum sp_buffer {
/** Input buffer. */
SP_BUF_INPUT = 1,
/** Output buffer. */
SP_BUF_OUTPUT = 2,
/** Both buffers. */
SP_BUF_BOTH = 3
};
/** Parity settings. */
enum sp_parity {
/** Special value to indicate setting should be left alone. */
SP_PARITY_INVALID = -1,
/** No parity. */
SP_PARITY_NONE = 0,
/** Odd parity. */
SP_PARITY_ODD = 1,
/** Even parity. */
SP_PARITY_EVEN = 2,
/** Mark parity. */
SP_PARITY_MARK = 3,
/** Space parity. */
SP_PARITY_SPACE = 4
};
/** RTS pin behaviour. */
enum sp_rts {
/** Special value to indicate setting should be left alone. */
SP_RTS_INVALID = -1,
/** RTS off. */
SP_RTS_OFF = 0,
/** RTS on. */
SP_RTS_ON = 1,
/** RTS used for flow control. */
SP_RTS_FLOW_CONTROL = 2
};
/** CTS pin behaviour. */
enum sp_cts {
/** Special value to indicate setting should be left alone. */
SP_CTS_INVALID = -1,
/** CTS ignored. */
SP_CTS_IGNORE = 0,
/** CTS used for flow control. */
SP_CTS_FLOW_CONTROL = 1
};
/** DTR pin behaviour. */
enum sp_dtr {
/** Special value to indicate setting should be left alone. */
SP_DTR_INVALID = -1,
/** DTR off. */
SP_DTR_OFF = 0,
/** DTR on. */
SP_DTR_ON = 1,
/** DTR used for flow control. */
SP_DTR_FLOW_CONTROL = 2
};
/** DSR pin behaviour. */
enum sp_dsr {
/** Special value to indicate setting should be left alone. */
SP_DSR_INVALID = -1,
/** DSR ignored. */
SP_DSR_IGNORE = 0,
/** DSR used for flow control. */
SP_DSR_FLOW_CONTROL = 1
};
/** XON/XOFF flow control behaviour. */
enum sp_xonxoff {
/** Special value to indicate setting should be left alone. */
SP_XONXOFF_INVALID = -1,
/** XON/XOFF disabled. */
SP_XONXOFF_DISABLED = 0,
/** XON/XOFF enabled for input only. */
SP_XONXOFF_IN = 1,
/** XON/XOFF enabled for output only. */
SP_XONXOFF_OUT = 2,
/** XON/XOFF enabled for input and output. */
SP_XONXOFF_INOUT = 3
};
/** Standard flow control combinations. */
enum sp_flowcontrol {
/** No flow control. */
SP_FLOWCONTROL_NONE = 0,
/** Software flow control using XON/XOFF characters. */
SP_FLOWCONTROL_XONXOFF = 1,
/** Hardware flow control using RTS/CTS signals. */
SP_FLOWCONTROL_RTSCTS = 2,
/** Hardware flow control using DTR/DSR signals. */
SP_FLOWCONTROL_DTRDSR = 3
};
/** Input signals. */
enum sp_signal {
/** Clear to send. */
SP_SIG_CTS = 1,
/** Data set ready. */
SP_SIG_DSR = 2,
/** Data carrier detect. */
SP_SIG_DCD = 4,
/** Ring indicator. */
SP_SIG_RI = 8
};
/** Transport types. */
enum sp_transport {
/** Native platform serial port. */
SP_TRANSPORT_NATIVE,
/** USB serial port adapter. */
SP_TRANSPORT_USB,
/** Bluetooth serial port adapter. */
SP_TRANSPORT_BLUETOOTH
};
/**
* @struct sp_port
* An opaque structure representing a serial port.
*/
struct sp_port;
/**
* @struct sp_port_config
* An opaque structure representing the configuration for a serial port.
*/
struct sp_port_config;
/**
* @struct sp_event_set
* A set of handles to wait on for events.
*/
struct sp_event_set {
/** Array of OS-specific handles. */
void *handles;
/** Array of bitmasks indicating which events apply for each handle. */
enum sp_event *masks;
/** Number of handles. */
unsigned int count;
};
/**
@defgroup Enumeration Port enumeration
@{
*/
/**
* Obtain a pointer to a new sp_port structure representing the named port.
*
* The user should allocate a variable of type "struct sp_port *" and pass a
* pointer to this to receive the result.
*
* The result should be freed after use by calling sp_free_port().
*
* If any error is returned, the variable pointed to by port_ptr will be set
* to NULL. Otherwise, it will be set to point to the newly allocated port.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_get_port_by_name(const char *portname, struct sp_port **port_ptr);
/**
* Free a port structure obtained from sp_get_port_by_name() or sp_copy_port().
*
* @since 0.1.0
*/
void sp_free_port(struct sp_port *port);
/**
* List the serial ports available on the system.
*
* The result obtained is an array of pointers to sp_port structures,
* terminated by a NULL. The user should allocate a variable of type
* "struct sp_port **" and pass a pointer to this to receive the result.
*
* The result should be freed after use by calling sp_free_port_list().
* If a port from the list is to be used after freeing the list, it must be
* copied first using sp_copy_port().
*
* If any error is returned, the variable pointed to by list_ptr will be set
* to NULL. Otherwise, it will be set to point to the newly allocated array.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_list_ports(struct sp_port ***list_ptr);
/**
* Make a new copy of a sp_port structure.
*
* The user should allocate a variable of type "struct sp_port *" and pass a
* pointer to this to receive the result.
*
* The copy should be freed after use by calling sp_free_port().
*
* If any error is returned, the variable pointed to by copy_ptr will be set
* to NULL. Otherwise, it will be set to point to the newly allocated copy.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_copy_port(const struct sp_port *port, struct sp_port **copy_ptr);
/**
* Free a port list obtained from sp_list_ports().
*
* This will also free all the sp_port structures referred to from the list;
* any that are to be retained must be copied first using sp_copy_port().
*
* @since 0.1.0
*/
void sp_free_port_list(struct sp_port **ports);
/**
* @}
* @defgroup Ports Opening, closing and querying ports
* @{
*/
/**
* Open the specified serial port.
*
* @param port Pointer to port structure.
* @param flags Flags to use when opening the serial port.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_open(struct sp_port *port, enum sp_mode flags);
/**
* Close the specified serial port.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_close(struct sp_port *port);
/**
* Get the name of a port.
*
* The name returned is whatever is normally used to refer to a port on the
* current operating system; e.g. for Windows it will usually be a "COMn"
* device name, and for Unix it will be a device path beginning with "/dev/".
*
* @param port Pointer to port structure.
*
* @return The port name, or NULL if an invalid port is passed. The name
* string is part of the port structure and may not be used after the
* port structure has been freed.
*
* @since 0.1.0
*/
char *sp_get_port_name(const struct sp_port *port);
/**
* Get a description for a port, to present to end user.
*
* @param port Pointer to port structure.
*
* @return The port description, or NULL if an invalid port is passed.
* The description string is part of the port structure and may not be used
* after the port structure has been freed.
*
* @since 0.2.0
*/
char *sp_get_port_description(struct sp_port *port);
/**
* Get the transport type used by a port.
*
* @param port Pointer to port structure.
*
* @return The port transport type.
*
* @since 0.2.0
*/
enum sp_transport sp_get_port_transport(struct sp_port *port);
/**
* Get the USB bus number and address on bus of a USB serial adapter port.
*
* @param port Pointer to port structure.
* @param usb_bus Pointer to variable to store USB bus.
* @param usb_address Pointer to variable to store USB address
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.2.0
*/
enum sp_return sp_get_port_usb_bus_address(const struct sp_port *port,
int *usb_bus, int *usb_address);
/**
* Get the USB Vendor ID and Product ID of a USB serial adapter port.
*
* @param port Pointer to port structure.
* @param usb_vid Pointer to variable to store USB VID.
* @param usb_pid Pointer to variable to store USB PID
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.2.0
*/
enum sp_return sp_get_port_usb_vid_pid(const struct sp_port *port, int *usb_vid, int *usb_pid);
/**
* Get the USB manufacturer string of a USB serial adapter port.
*
* @param port Pointer to port structure.
*
* @return The port manufacturer string, or NULL if an invalid port is passed.
* The manufacturer string is part of the port structure and may not be used
* after the port structure has been freed.
*
* @since 0.2.0
*/
char *sp_get_port_usb_manufacturer(const struct sp_port *port);
/**
* Get the USB product string of a USB serial adapter port.
*
* @param port Pointer to port structure.
*
* @return The port product string, or NULL if an invalid port is passed.
* The product string is part of the port structure and may not be used
* after the port structure has been freed.
*
* @since 0.2.0
*/
char *sp_get_port_usb_product(const struct sp_port *port);
/**
* Get the USB serial number string of a USB serial adapter port.
*
* @param port Pointer to port structure.
*
* @return The port serial number, or NULL if an invalid port is passed.
* The serial number string is part of the port structure and may not be used
* after the port structure has been freed.
*
* @since 0.2.0
*/
char *sp_get_port_usb_serial(const struct sp_port *port);
/**
* Get the MAC address of a Bluetooth serial adapter port.
*
* @param port Pointer to port structure.
*
* @return The port MAC address, or NULL if an invalid port is passed.
* The MAC address string is part of the port structure and may not be used
* after the port structure has been freed.
*
* @since 0.2.0
*/
char *sp_get_port_bluetooth_address(const struct sp_port *port);
/**
* Get the operating system handle for a port.
*
* The type of the handle depends on the operating system. On Unix based
* systems, the handle is a file descriptor of type "int". On Windows, the
* handle is of type "HANDLE". The user should allocate a variable of the
* appropriate type and pass a pointer to this to receive the result.
*
* To obtain a valid handle, the port must first be opened by calling
* sp_open() using the same port structure.
*
* After the port is closed or the port structure freed, the handle may
* no longer be valid.
*
* @warning This feature is provided so that programs may make use of
* OS-specific functionality where desired. Doing so obviously
* comes at a cost in portability. It also cannot be guaranteed
* that direct usage of the OS handle will not conflict with the
* library's own usage of the port. Be careful.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_get_port_handle(const struct sp_port *port, void *result_ptr);
/**
* @}
* @defgroup Configuration Setting port parameters
* @{
*/
/**
* Allocate a port configuration structure.
*
* The user should allocate a variable of type "struct sp_config *" and pass a
* pointer to this to receive the result. The variable will be updated to
* point to the new configuration structure. The structure is opaque and must
* be accessed via the functions provided.
*
* All parameters in the structure will be initialised to special values which
* are ignored by sp_set_config().
*
* The structure should be freed after use by calling sp_free_config().
*
* @param config_ptr Pointer to variable to receive result.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_new_config(struct sp_port_config **config_ptr);
/**
* Free a port configuration structure.
*
* @param config Pointer to configuration structure.
*
* @since 0.1.0
*/
void sp_free_config(struct sp_port_config *config);
/**
* Get the current configuration of the specified serial port.
*
* The user should allocate a configuration structure using sp_new_config()
* and pass this as the config parameter. The configuration structure will
* be updated with the port configuration.
*
* Any parameters that are configured with settings not recognised or
* supported by libserialport, will be set to special values that are
* ignored by sp_set_config().
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_get_config(struct sp_port *port, struct sp_port_config *config);
/**
* Set the configuration for the specified serial port.
*
* For each parameter in the configuration, there is a special value (usually
* -1, but see the documentation for each field). These values will be ignored
* and the corresponding setting left unchanged on the port.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_set_config(struct sp_port *port, const struct sp_port_config *config);
/**
* Set the baud rate for the specified serial port.
*
* @param port Pointer to port structure.
* @param baudrate Baud rate in bits per second.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_set_baudrate(struct sp_port *port, int baudrate);
/**
* Get the baud rate from a port configuration.
*
* The user should allocate a variable of type int and pass a pointer to this
* to receive the result.
*
* @param config Pointer to configuration structure.
* @param baudrate_ptr Pointer to variable to store result.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_get_config_baudrate(const struct sp_port_config *config, int *baudrate_ptr);
/**
* Set the baud rate in a port configuration.
*
* @param config Pointer to configuration structure.
* @param baudrate Baud rate in bits per second, or -1 to retain current setting.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_set_config_baudrate(struct sp_port_config *config, int baudrate);
/**
* Set the data bits for the specified serial port.
*
* @param port Pointer to port structure.
* @param bits Number of data bits.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_set_bits(struct sp_port *port, int bits);
/**
* Get the data bits from a port configuration.
*
* The user should allocate a variable of type int and pass a pointer to this
* to receive the result.
*
* @param config Pointer to configuration structure.
* @param bits_ptr Pointer to variable to store result.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_get_config_bits(const struct sp_port_config *config, int *bits_ptr);
/**
* Set the data bits in a port configuration.
*
* @param config Pointer to configuration structure.
* @param bits Number of data bits, or -1 to retain current setting.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_set_config_bits(struct sp_port_config *config, int bits);
/**
* Set the parity setting for the specified serial port.
*
* @param port Pointer to port structure.
* @param parity Parity setting.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_set_parity(struct sp_port *port, enum sp_parity parity);
/**
* Get the parity setting from a port configuration.
*
* The user should allocate a variable of type enum sp_parity and pass a pointer to this
* to receive the result.
*
* @param config Pointer to configuration structure.
* @param parity_ptr Pointer to variable to store result.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_get_config_parity(const struct sp_port_config *config, enum sp_parity *parity_ptr);
/**
* Set the parity setting in a port configuration.
*
* @param config Pointer to configuration structure.
* @param parity Parity setting, or -1 to retain current setting.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_set_config_parity(struct sp_port_config *config, enum sp_parity parity);
/**
* Set the stop bits for the specified serial port.
*
* @param port Pointer to port structure.
* @param stopbits Number of stop bits.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_set_stopbits(struct sp_port *port, int stopbits);
/**
* Get the stop bits from a port configuration.
*
* The user should allocate a variable of type int and pass a pointer to this
* to receive the result.
*
* @param config Pointer to configuration structure.
* @param stopbits_ptr Pointer to variable to store result.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_get_config_stopbits(const struct sp_port_config *config, int *stopbits_ptr);
/**
* Set the stop bits in a port configuration.
*
* @param config Pointer to configuration structure.
* @param stopbits Number of stop bits, or -1 to retain current setting.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_set_config_stopbits(struct sp_port_config *config, int stopbits);
/**
* Set the RTS pin behaviour for the specified serial port.
*
* @param port Pointer to port structure.
* @param rts RTS pin mode.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_set_rts(struct sp_port *port, enum sp_rts rts);
/**
* Get the RTS pin behaviour from a port configuration.
*
* The user should allocate a variable of type enum sp_rts and pass a pointer to this
* to receive the result.
*
* @param config Pointer to configuration structure.
* @param rts_ptr Pointer to variable to store result.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_get_config_rts(const struct sp_port_config *config, enum sp_rts *rts_ptr);
/**
* Set the RTS pin behaviour in a port configuration.
*
* @param config Pointer to configuration structure.
* @param rts RTS pin mode, or -1 to retain current setting.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_set_config_rts(struct sp_port_config *config, enum sp_rts rts);
/**
* Set the CTS pin behaviour for the specified serial port.
*
* @param port Pointer to port structure.
* @param cts CTS pin mode.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_set_cts(struct sp_port *port, enum sp_cts cts);
/**
* Get the CTS pin behaviour from a port configuration.
*
* The user should allocate a variable of type enum sp_cts and pass a pointer to this
* to receive the result.
*
* @param config Pointer to configuration structure.
* @param cts_ptr Pointer to variable to store result.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_get_config_cts(const struct sp_port_config *config, enum sp_cts *cts_ptr);
/**
* Set the CTS pin behaviour in a port configuration.
*
* @param config Pointer to configuration structure.
* @param cts CTS pin mode, or -1 to retain current setting.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_set_config_cts(struct sp_port_config *config, enum sp_cts cts);
/**
* Set the DTR pin behaviour for the specified serial port.
*
* @param port Pointer to port structure.
* @param dtr DTR pin mode.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_set_dtr(struct sp_port *port, enum sp_dtr dtr);
/**
* Get the DTR pin behaviour from a port configuration.
*
* The user should allocate a variable of type enum sp_dtr and pass a pointer to this
* to receive the result.
*
* @param config Pointer to configuration structure.
* @param dtr_ptr Pointer to variable to store result.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_get_config_dtr(const struct sp_port_config *config, enum sp_dtr *dtr_ptr);
/**
* Set the DTR pin behaviour in a port configuration.
*
* @param config Pointer to configuration structure.
* @param dtr DTR pin mode, or -1 to retain current setting.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_set_config_dtr(struct sp_port_config *config, enum sp_dtr dtr);
/**
* Set the DSR pin behaviour for the specified serial port.
*
* @param port Pointer to port structure.
* @param dsr DSR pin mode.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_set_dsr(struct sp_port *port, enum sp_dsr dsr);
/**
* Get the DSR pin behaviour from a port configuration.
*
* The user should allocate a variable of type enum sp_dsr and pass a pointer to this
* to receive the result.
*
* @param config Pointer to configuration structure.
* @param dsr_ptr Pointer to variable to store result.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_get_config_dsr(const struct sp_port_config *config, enum sp_dsr *dsr_ptr);
/**
* Set the DSR pin behaviour in a port configuration.
*
* @param config Pointer to configuration structure.
* @param dsr DSR pin mode, or -1 to retain current setting.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_set_config_dsr(struct sp_port_config *config, enum sp_dsr dsr);
/**
* Set the XON/XOFF configuration for the specified serial port.
*
* @param port Pointer to port structure.
* @param xon_xoff XON/XOFF mode.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_set_xon_xoff(struct sp_port *port, enum sp_xonxoff xon_xoff);
/**
* Get the XON/XOFF configuration from a port configuration.
*
* The user should allocate a variable of type enum sp_xonxoff and pass a pointer to this
* to receive the result.
*
* @param config Pointer to configuration structure.
* @param xon_xoff_ptr Pointer to variable to store result.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_get_config_xon_xoff(const struct sp_port_config *config, enum sp_xonxoff *xon_xoff_ptr);
/**
* Set the XON/XOFF configuration in a port configuration.
*
* @param config Pointer to configuration structure.
* @param xon_xoff XON/XOFF mode, or -1 to retain current setting.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_set_config_xon_xoff(struct sp_port_config *config, enum sp_xonxoff xon_xoff);
/**
* Set the flow control type in a port configuration.
*
* This function is a wrapper that sets the RTS, CTS, DTR, DSR and
* XON/XOFF settings as necessary for the specified flow control
* type. For more fine-grained control of these settings, use their
* individual configuration functions.
*
* @param config Pointer to configuration structure.
* @param flowcontrol Flow control setting to use.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_set_config_flowcontrol(struct sp_port_config *config, enum sp_flowcontrol flowcontrol);
/**
* Set the flow control type for the specified serial port.
*
* This function is a wrapper that sets the RTS, CTS, DTR, DSR and
* XON/XOFF settings as necessary for the specified flow control
* type. For more fine-grained control of these settings, use their
* individual configuration functions.
*
* @param port Pointer to port structure.
* @param flowcontrol Flow control setting to use.
*
* @return SP_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/
enum sp_return sp_set_flowcontrol(struct sp_port *port, enum sp_flowcontrol flowcontrol);
/**
* @}
* @defgroup Data Reading, writing, and flushing data
* @{
*/
/**
* Read bytes from the specified serial port, blocking until complete.
*
* @warning If your program runs on Unix, defines its own signal handlers, and
* needs to abort blocking reads when these are called, then you
* should not use this function. It repeats system calls that return
* with EINTR. To be able to abort a read from a signal handler, you
* should implement your own blocking read using sp_nonblocking_read()
* together with a blocking method that makes sense for your program.
* E.g. you can obtain the file descriptor for an open port using
* sp_get_port_handle() and use this to call select() or pselect(),
* with appropriate arrangements to return if a signal is received.
*
* @param port Pointer to port structure.
* @param buf Buffer in which to store the bytes read.
* @param count Requested number of bytes to read.
* @param timeout Timeout in milliseconds, or zero to wait indefinitely.
*
* @return The number of bytes read on success, or a negative error code. If
* the number of bytes returned is less than that requested, the
* timeout was reached before the requested number of bytes was
* available. If timeout is zero, the function will always return
* either the requested number of bytes or a negative error code.
*
* @since 0.1.0
*/