libserialport
0.1.0
cross-platform library for accessing serial ports
Main Page
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Enumerations
Enumerator
Groups
Pages
libserialport.h
Go to the documentation of this file.
1
/*
2
* This file is part of the libserialport project.
3
*
4
* Copyright (C) 2013 Martin Ling <martin-libserialport@earth.li>
5
*
6
* This program is free software: you can redistribute it and/or modify
7
* it under the terms of the GNU Lesser General Public License as
8
* published by the Free Software Foundation, either version 3 of the
9
* License, or (at your option) any later version.
10
*
11
* This program is distributed in the hope that it will be useful,
12
* but WITHOUT ANY WARRANTY; without even the implied warranty of
13
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14
* GNU General Public License for more details.
15
*
16
* You should have received a copy of the GNU Lesser General Public License
17
* along with this program. If not, see <http://www.gnu.org/licenses/>.
18
*/
19
20
/**
21
* @mainpage libserialport API
22
*
23
* Introduction
24
* ============
25
*
26
* libserialport is a minimal library written in C that is intended to take
27
* care of the OS-specific details when writing software that uses serial ports.
28
*
29
* By writing your serial code to use libserialport, you enable it to work
30
* transparently on any platform supported by the library.
31
*
32
* The operations that are supported are:
33
*
34
* - @ref Enumeration (obtaining a list of serial ports on the system)
35
* - @ref Ports
36
* - @ref Configuration (baud rate, parity, etc.)
37
* - @ref Signals (modem control lines, breaks, etc.)
38
* - @ref Data
39
* - @ref Waiting
40
* - @ref Errors
41
*
42
* libserialport is an open source project released under the LGPL3+ license.
43
*
44
* API principles
45
* ==============
46
*
47
* The API is simple, and designed to be a minimal wrapper around the serial
48
* port support in each OS.
49
*
50
* Most functions take a pointer to a struct sp_port, which represents a serial
51
* port. These structures are always allocated and freed by the library, using
52
* the functions in the @ref Enumeration "Enumeration" section.
53
*
54
* Most functions have return type @ref sp_return and can return only four
55
* possible error values:
56
*
57
* - @ref SP_ERR_ARG means that a function was called with invalid
58
* arguments. This implies a bug in the caller. The arguments passed would
59
* be invalid regardless of the underlying OS or serial device involved.
60
*
61
* - @ref SP_ERR_FAIL means that the OS reported a failure. The error code or
62
* message provided by the OS can be obtained by calling sp_last_error_code()
63
* or sp_last_error_message().
64
*
65
* - @ref SP_ERR_SUPP indicates that there is no support for the requested
66
* operation in the current OS, driver or device. No error message is
67
* available from the OS in this case. There is either no way to request
68
* the operation in the first place, or libserialport does not know how to
69
* do so in the current version.
70
*
71
* - @ref SP_ERR_MEM indicates that a memory allocation failed.
72
*
73
* All of these error values are negative.
74
*
75
* Calls that succeed return @ref SP_OK, which is equal to zero. Some functions
76
* declared @ref sp_return can also return a positive value for a successful
77
* numeric result, e.g. sp_blocking_read() or sp_blocking_write().
78
*/
79
80
#ifndef LIBSERIALPORT_LIBSERIALPORT_H
81
#define LIBSERIALPORT_LIBSERIALPORT_H
82
83
#ifdef __cplusplus
84
extern
"C"
{
85
#endif
86
87
#include <stddef.h>
88
#ifdef _WIN32
89
#include <windows.h>
90
#endif
91
92
/** Return values. */
93
enum
sp_return
{
94
/** Operation completed successfully. */
95
SP_OK
= 0,
96
/** Invalid arguments were passed to the function. */
97
SP_ERR_ARG
= -1,
98
/** A system error occured while executing the operation. */
99
SP_ERR_FAIL
= -2,
100
/** A memory allocation failed while executing the operation. */
101
SP_ERR_MEM
= -3,
102
/** The requested operation is not supported by this system or device. */
103
SP_ERR_SUPP
= -4,
104
};
105
106
/** Port access modes. */
107
enum
sp_mode
{
108
/** Open port for read access. */
109
SP_MODE_READ
= 1,
110
/** Open port for write access. */
111
SP_MODE_WRITE
= 2,
112
};
113
114
/** Port events. */
115
enum
sp_event
{
116
/* Data received and ready to read. */
117
SP_EVENT_RX_READY
= 1,
118
/* Ready to transmit new data. */
119
SP_EVENT_TX_READY
= 2,
120
/* Error occured. */
121
SP_EVENT_ERROR
= 4,
122
};
123
124
/** Buffer selection. */
125
enum
sp_buffer
{
126
/** Input buffer. */
127
SP_BUF_INPUT
= 1,
128
/** Output buffer. */
129
SP_BUF_OUTPUT
= 2,
130
/** Both buffers. */
131
SP_BUF_BOTH
= 3,
132
};
133
134
/** Parity settings. */
135
enum
sp_parity
{
136
/** Special value to indicate setting should be left alone. */
137
SP_PARITY_INVALID
= -1,
138
/** No parity. */
139
SP_PARITY_NONE
= 0,
140
/** Odd parity. */
141
SP_PARITY_ODD
= 1,
142
/** Even parity. */
143
SP_PARITY_EVEN
= 2,
144
/** Mark parity. */
145
SP_PARITY_MARK
= 3,
146
/** Space parity. */
147
SP_PARITY_SPACE
= 4,
148
};
149
150
/** RTS pin behaviour. */
151
enum
sp_rts
{
152
/** Special value to indicate setting should be left alone. */
153
SP_RTS_INVALID
= -1,
154
/** RTS off. */
155
SP_RTS_OFF
= 0,
156
/** RTS on. */
157
SP_RTS_ON
= 1,
158
/** RTS used for flow control. */
159
SP_RTS_FLOW_CONTROL
= 2,
160
};
161
162
/** CTS pin behaviour. */
163
enum
sp_cts
{
164
/** Special value to indicate setting should be left alone. */
165
SP_CTS_INVALID
= -1,
166
/** CTS ignored. */
167
SP_CTS_IGNORE
= 0,
168
/** CTS used for flow control. */
169
SP_CTS_FLOW_CONTROL
= 1,
170
};
171
172
/** DTR pin behaviour. */
173
enum
sp_dtr
{
174
/** Special value to indicate setting should be left alone. */
175
SP_DTR_INVALID
= -1,
176
/** DTR off. */
177
SP_DTR_OFF
= 0,
178
/** DTR on. */
179
SP_DTR_ON
= 1,
180
/** DTR used for flow control. */
181
SP_DTR_FLOW_CONTROL
= 2,
182
};
183
184
/** DSR pin behaviour. */
185
enum
sp_dsr
{
186
/** Special value to indicate setting should be left alone. */
187
SP_DSR_INVALID
= -1,
188
/** DSR ignored. */
189
SP_DSR_IGNORE
= 0,
190
/** DSR used for flow control. */
191
SP_DSR_FLOW_CONTROL
= 1,
192
};
193
194
/** XON/XOFF flow control behaviour. */
195
enum
sp_xonxoff
{
196
/** Special value to indicate setting should be left alone. */
197
SP_XONXOFF_INVALID
= -1,
198
/** XON/XOFF disabled. */
199
SP_XONXOFF_DISABLED
= 0,
200
/** XON/XOFF enabled for input only. */
201
SP_XONXOFF_IN
= 1,
202
/** XON/XOFF enabled for output only. */
203
SP_XONXOFF_OUT
= 2,
204
/** XON/XOFF enabled for input and output. */
205
SP_XONXOFF_INOUT
= 3,
206
};
207
208
/** Standard flow control combinations. */
209
enum
sp_flowcontrol
{
210
/** No flow control. */
211
SP_FLOWCONTROL_NONE
= 0,
212
/** Software flow control using XON/XOFF characters. */
213
SP_FLOWCONTROL_XONXOFF
= 1,
214
/** Hardware flow control using RTS/CTS signals. */
215
SP_FLOWCONTROL_RTSCTS
= 2,
216
/** Hardware flow control using DTR/DSR signals. */
217
SP_FLOWCONTROL_DTRDSR
= 3,
218
};
219
220
/** Input signals. */
221
enum
sp_signal
{
222
/** Clear to send. */
223
SP_SIG_CTS
= 1,
224
/** Data set ready. */
225
SP_SIG_DSR
= 2,
226
/** Data carrier detect. */
227
SP_SIG_DCD
= 4,
228
/** Ring indicator. */
229
SP_SIG_RI
= 8,
230
};
231
232
/**
233
* @struct sp_port
234
* An opaque structure representing a serial port.
235
*/
236
struct
sp_port
;
237
238
/**
239
* @struct sp_port_config
240
* An opaque structure representing the configuration for a serial port.
241
*/
242
struct
sp_port_config
;
243
244
/**
245
* @struct sp_event_set
246
* A set of handles to wait on for events.
247
*/
248
struct
sp_event_set
{
249
/** Array of OS-specific handles. */
250
void
*
handles
;
251
/** Array of bitmasks indicating which events apply for each handle. */
252
enum
sp_event
*
masks
;
253
/** Number of handles. */
254
unsigned
int
count
;
255
};
256
257
/**
258
@defgroup Enumeration Port enumeration
259
@{
260
*/
261
262
/**
263
* Obtain a pointer to a new sp_port structure representing the named port.
264
*
265
* The user should allocate a variable of type "struct sp_port *" and pass a
266
* pointer to this to receive the result.
267
*
268
* The result should be freed after use by calling sp_free_port().
269
*
270
* If any error is returned, the variable pointed to by port_ptr will be set
271
* to NULL. Otherwise, it will be set to point to the newly allocated port.
272
*
273
* @return SP_OK upon success, a negative error code otherwise.
274
*
275
* @since 0.1.0
276
*/
277
enum
sp_return
sp_get_port_by_name
(
const
char
*portname,
struct
sp_port
**port_ptr);
278
279
/**
280
* Free a port structure obtained from sp_get_port_by_name() or sp_copy_port().
281
*
282
* @since 0.1.0
283
*/
284
void
sp_free_port
(
struct
sp_port
*port);
285
286
/**
287
* List the serial ports available on the system.
288
*
289
* The result obtained is an array of pointers to sp_port structures,
290
* terminated by a NULL. The user should allocate a variable of type
291
* "struct sp_port **" and pass a pointer to this to receive the result.
292
*
293
* The result should be freed after use by calling sp_free_port_list().
294
* If a port from the list is to be used after freeing the list, it must be
295
* copied first using sp_copy_port().
296
*
297
* If any error is returned, the variable pointed to by list_ptr will be set
298
* to NULL. Otherwise, it will be set to point to the newly allocated array.
299
*
300
* @return SP_OK upon success, a negative error code otherwise.
301
*
302
* @since 0.1.0
303
*/
304
enum
sp_return
sp_list_ports
(
struct
sp_port
***list_ptr);
305
306
/**
307
* Make a new copy of a sp_port structure.
308
*
309
* The user should allocate a variable of type "struct sp_port *" and pass a
310
* pointer to this to receive the result.
311
*
312
* The copy should be freed after use by calling sp_free_port().
313
*
314
* If any error is returned, the variable pointed to by copy_ptr will be set
315
* to NULL. Otherwise, it will be set to point to the newly allocated copy.
316
*
317
* @return SP_OK upon success, a negative error code otherwise.
318
*
319
* @since 0.1.0
320
*/
321
enum
sp_return
sp_copy_port
(
const
struct
sp_port
*port,
struct
sp_port
**copy_ptr);
322
323
/**
324
* Free a port list obtained from sp_list_ports().
325
*
326
* This will also free all the sp_port structures referred to from the list;
327
* any that are to be retained must be copied first using sp_copy_port().
328
*
329
* @since 0.1.0
330
*/
331
void
sp_free_port_list
(
struct
sp_port
**ports);
332
333
/**
334
* @}
335
* @defgroup Ports Opening, closing and querying ports
336
* @{
337
*/
338
339
/**
340
* Open the specified serial port.
341
*
342
* @param port Pointer to port structure.
343
* @param flags Flags to use when opening the serial port.
344
*
345
* @return SP_OK upon success, a negative error code otherwise.
346
*
347
* @since 0.1.0
348
*/
349
enum
sp_return
sp_open
(
struct
sp_port
*port,
enum
sp_mode
flags);
350
351
/**
352
* Close the specified serial port.
353
*
354
* @return SP_OK upon success, a negative error code otherwise.
355
*
356
* @since 0.1.0
357
*/
358
enum
sp_return
sp_close
(
struct
sp_port
*port);
359
360
/**
361
* Get the name of a port.
362
*
363
* The name returned is whatever is normally used to refer to a port on the
364
* current operating system; e.g. for Windows it will usually be a "COMn"
365
* device name, and for Unix it will be a device path beginning with "/dev/".
366
*
367
* @param port Pointer to port structure.
368
*
369
* @return The port name, or NULL if an invalid port is passed. The name
370
* string is part of the port structure and may not be used after the
371
* port structure has been freed.
372
*
373
* @since 0.1.0
374
*/
375
char
*
sp_get_port_name
(
const
struct
sp_port
*port);
376
377
/**
378
* Get the operating system handle for a port.
379
*
380
* The type of the handle depends on the operating system. On Unix based
381
* systems, the handle is a file descriptor of type "int". On Windows, the
382
* handle is of type "HANDLE". The user should allocate a variable of the
383
* appropriate type and pass a pointer to this to receive the result.
384
*
385
* To obtain a valid handle, the port must first be opened by calling
386
* sp_open() using the same port structure.
387
*
388
* After the port is closed or the port structure freed, the handle may
389
* no longer be valid.
390
*
391
* @warning This feature is provided so that programs may make use of
392
* OS-specific functionality where desired. Doing so obviously
393
* comes at a cost in portability. It also cannot be guaranteed
394
* that direct usage of the OS handle will not conflict with the
395
* library's own usage of the port. Be careful.
396
*
397
* @return SP_OK upon success, a negative error code otherwise.
398
*
399
* @since 0.1.0
400
*/
401
enum
sp_return
sp_get_port_handle
(
const
struct
sp_port
*port,
void
*result_ptr);
402
403
/**
404
* @}
405
* @defgroup Configuration Setting port parameters
406
* @{
407
*/
408
409
/**
410
* Allocate a port configuration structure.
411
*
412
* The user should allocate a variable of type "struct sp_config *" and pass a
413
* pointer to this to receive the result. The variable will be updated to
414
* point to the new configuration structure. The structure is opaque and must
415
* be accessed via the functions provided.
416
*
417
* All parameters in the structure will be initialised to special values which
418
* are ignored by sp_set_config().
419
*
420
* The structure should be freed after use by calling sp_free_config().
421
*
422
* @param config_ptr Pointer to variable to receive result.
423
*
424
* @return SP_OK upon success, a negative error code otherwise.
425
*
426
* @since 0.1.0
427
*/
428
enum
sp_return
sp_new_config
(
struct
sp_port_config
**config_ptr);
429
430
/**
431
* Free a port configuration structure.
432
*
433
* @param config Pointer to configuration structure.
434
*
435
* @since 0.1.0
436
*/
437
void
sp_free_config
(
struct
sp_port_config
*config);
438
439
/**
440
* Get the current configuration of the specified serial port.
441
*
442
* The user should allocate a configuration structure using sp_new_config()
443
* and pass this as the config parameter. The configuration structure will
444
* be updated with the port configuration.
445
*
446
* Any parameters that are configured with settings not recognised or
447
* supported by libserialport, will be set to special values that are
448
* ignored by sp_set_config().
449
*
450
* @return SP_OK upon success, a negative error code otherwise.
451
*
452
* @since 0.1.0
453
*/
454
enum
sp_return
sp_get_config
(
struct
sp_port
*port,
struct
sp_port_config
*config);
455
456
/**
457
* Set the configuration for the specified serial port.
458
*
459
* For each parameter in the configuration, there is a special value (usually
460
* -1, but see the documentation for each field). These values will be ignored
461
* and the corresponding setting left unchanged on the port.
462
*
463
* @return SP_OK upon success, a negative error code otherwise.
464
*
465
* @since 0.1.0
466
*/
467
enum
sp_return
sp_set_config
(
struct
sp_port
*port,
const
struct
sp_port_config
*config);
468
469
/**
470
* Set the baud rate for the specified serial port.
471
*
472
* @param port Pointer to port structure.
473
* @param baudrate Baud rate in bits per second.
474
*
475
* @return SP_OK upon success, a negative error code otherwise.
476
*
477
* @since 0.1.0
478
*/
479
enum
sp_return
sp_set_baudrate
(
struct
sp_port
*port,
int
baudrate);
480
481
/**
482
* Get the baud rate from a port configuration.
483
*
484
* The user should allocate a variable of type int and pass a pointer to this
485
* to receive the result.
486
*
487
* @param config Pointer to configuration structure.
488
* @param baudrate_ptr Pointer to variable to store result.
489
*
490
* @return SP_OK upon success, a negative error code otherwise.
491
*
492
* @since 0.1.0
493
*/
494
enum
sp_return
sp_get_config_baudrate
(
const
struct
sp_port_config
*config,
int
*baudrate_ptr);
495
496
/**
497
* Set the baud rate in a port configuration.
498
*
499
* @param config Pointer to configuration structure.
500
* @param baudrate Baud rate in bits per second, or -1 to retain current setting.
501
*
502
* @return SP_OK upon success, a negative error code otherwise.
503
*
504
* @since 0.1.0
505
*/
506
enum
sp_return
sp_set_config_baudrate
(
struct
sp_port_config
*config,
int
baudrate);
507
508
/**
509
* Set the data bits for the specified serial port.
510
*
511
* @param port Pointer to port structure.
512
* @param bits Number of data bits.
513
*
514
* @return SP_OK upon success, a negative error code otherwise.
515
*
516
* @since 0.1.0
517
*/
518
enum
sp_return
sp_set_bits
(
struct
sp_port
*port,
int
bits);
519
520
/**
521
* Get the data bits from a port configuration.
522
*
523
* The user should allocate a variable of type int and pass a pointer to this
524
* to receive the result.
525
*
526
* @param config Pointer to configuration structure.
527
* @param bits_ptr Pointer to variable to store result.
528
*
529
* @return SP_OK upon success, a negative error code otherwise.
530
*
531
* @since 0.1.0
532
*/
533
enum
sp_return
sp_get_config_bits
(
const
struct
sp_port_config
*config,
int
*bits_ptr);
534
535
/**
536
* Set the data bits in a port configuration.
537
*
538
* @param config Pointer to configuration structure.
539
* @param bits Number of data bits, or -1 to retain current setting.
540
*
541
* @return SP_OK upon success, a negative error code otherwise.
542
*
543
* @since 0.1.0
544
*/
545
enum
sp_return
sp_set_config_bits
(
struct
sp_port_config
*config,
int
bits);
546
547
/**
548
* Set the parity setting for the specified serial port.
549
*
550
* @param port Pointer to port structure.
551
* @param parity Parity setting.
552
*
553
* @return SP_OK upon success, a negative error code otherwise.
554
*
555
* @since 0.1.0
556
*/
557
enum
sp_return
sp_set_parity
(
struct
sp_port
*port,
enum
sp_parity
parity);
558
559
/**
560
* Get the parity setting from a port configuration.
561
*
562
* The user should allocate a variable of type enum sp_parity and pass a pointer to this
563
* to receive the result.
564
*
565
* @param config Pointer to configuration structure.
566
* @param parity_ptr Pointer to variable to store result.
567
*
568
* @return SP_OK upon success, a negative error code otherwise.
569
*
570
* @since 0.1.0
571
*/
572
enum
sp_return
sp_get_config_parity
(
const
struct
sp_port_config
*config,
enum
sp_parity
*parity_ptr);
573
574
/**
575
* Set the parity setting in a port configuration.
576
*
577
* @param config Pointer to configuration structure.
578
* @param parity Parity setting, or -1 to retain current setting.
579
*
580
* @return SP_OK upon success, a negative error code otherwise.
581
*
582
* @since 0.1.0
583
*/
584
enum
sp_return
sp_set_config_parity
(
struct
sp_port_config
*config,
enum
sp_parity
parity);
585
586
/**
587
* Set the stop bits for the specified serial port.
588
*
589
* @param port Pointer to port structure.
590
* @param stopbits Number of stop bits.
591
*
592
* @return SP_OK upon success, a negative error code otherwise.
593
*
594
* @since 0.1.0
595
*/
596
enum
sp_return
sp_set_stopbits
(
struct
sp_port
*port,
int
stopbits);
597
598
/**
599
* Get the stop bits from a port configuration.
600
*
601
* The user should allocate a variable of type int and pass a pointer to this
602
* to receive the result.
603
*
604
* @param config Pointer to configuration structure.
605
* @param stopbits_ptr Pointer to variable to store result.
606
*
607
* @return SP_OK upon success, a negative error code otherwise.
608
*
609
* @since 0.1.0
610
*/
611
enum
sp_return
sp_get_config_stopbits
(
const
struct
sp_port_config
*config,
int
*stopbits_ptr);
612
613
/**
614
* Set the stop bits in a port configuration.
615
*
616
* @param config Pointer to configuration structure.
617
* @param stopbits Number of stop bits, or -1 to retain current setting.
618
*
619
* @return SP_OK upon success, a negative error code otherwise.
620
*
621
* @since 0.1.0
622
*/
623
enum
sp_return
sp_set_config_stopbits
(
struct
sp_port_config
*config,
int
stopbits);
624
625
/**
626
* Set the RTS pin behaviour for the specified serial port.
627
*
628
* @param port Pointer to port structure.
629
* @param rts RTS pin mode.
630
*
631
* @return SP_OK upon success, a negative error code otherwise.
632
*
633
* @since 0.1.0
634
*/
635
enum
sp_return
sp_set_rts
(
struct
sp_port
*port,
enum
sp_rts
rts);
636
637
/**
638
* Get the RTS pin behaviour from a port configuration.
639
*
640
* The user should allocate a variable of type enum sp_rts and pass a pointer to this
641
* to receive the result.
642
*
643
* @param config Pointer to configuration structure.
644
* @param rts_ptr Pointer to variable to store result.
645
*
646
* @return SP_OK upon success, a negative error code otherwise.
647
*
648
* @since 0.1.0
649
*/
650
enum
sp_return
sp_get_config_rts
(
const
struct
sp_port_config
*config,
enum
sp_rts
*rts_ptr);
651
652
/**
653
* Set the RTS pin behaviour in a port configuration.
654
*
655
* @param config Pointer to configuration structure.
656
* @param rts RTS pin mode, or -1 to retain current setting.
657
*
658
* @return SP_OK upon success, a negative error code otherwise.
659
*
660
* @since 0.1.0
661
*/
662
enum
sp_return
sp_set_config_rts
(
struct
sp_port_config
*config,
enum
sp_rts
rts);
663
664
/**
665
* Set the CTS pin behaviour for the specified serial port.
666
*
667
* @param port Pointer to port structure.
668
* @param cts CTS pin mode.
669
*
670
* @return SP_OK upon success, a negative error code otherwise.
671
*
672
* @since 0.1.0
673
*/
674
enum
sp_return
sp_set_cts
(
struct
sp_port
*port,
enum
sp_cts
cts);
675
676
/**
677
* Get the CTS pin behaviour from a port configuration.
678
*
679
* The user should allocate a variable of type enum sp_cts and pass a pointer to this
680
* to receive the result.
681
*
682
* @param config Pointer to configuration structure.
683
* @param cts_ptr Pointer to variable to store result.
684
*
685
* @return SP_OK upon success, a negative error code otherwise.
686
*
687
* @since 0.1.0
688
*/
689
enum
sp_return
sp_get_config_cts
(
const
struct
sp_port_config
*config,
enum
sp_cts
*cts_ptr);
690
691
/**
692
* Set the CTS pin behaviour in a port configuration.
693
*
694
* @param config Pointer to configuration structure.
695
* @param cts CTS pin mode, or -1 to retain current setting.
696
*
697
* @return SP_OK upon success, a negative error code otherwise.
698
*
699
* @since 0.1.0
700
*/
701
enum
sp_return
sp_set_config_cts
(
struct
sp_port_config
*config,
enum
sp_cts
cts);
702
703
/**
704
* Set the DTR pin behaviour for the specified serial port.
705
*
706
* @param port Pointer to port structure.
707
* @param dtr DTR pin mode.
708
*
709
* @return SP_OK upon success, a negative error code otherwise.
710
*
711
* @since 0.1.0
712
*/
713
enum
sp_return
sp_set_dtr
(
struct
sp_port
*port,
enum
sp_dtr
dtr);
714
715
/**
716
* Get the DTR pin behaviour from a port configuration.
717
*
718
* The user should allocate a variable of type enum sp_dtr and pass a pointer to this
719
* to receive the result.
720
*
721
* @param config Pointer to configuration structure.
722
* @param dtr_ptr Pointer to variable to store result.
723
*
724
* @return SP_OK upon success, a negative error code otherwise.
725
*
726
* @since 0.1.0
727
*/
728
enum
sp_return
sp_get_config_dtr
(
const
struct
sp_port_config
*config,
enum
sp_dtr
*dtr_ptr);
729
730
/**
731
* Set the DTR pin behaviour in a port configuration.
732
*
733
* @param config Pointer to configuration structure.
734
* @param dtr DTR pin mode, or -1 to retain current setting.
735
*
736
* @return SP_OK upon success, a negative error code otherwise.
737
*
738
* @since 0.1.0
739
*/
740
enum
sp_return
sp_set_config_dtr
(
struct
sp_port_config
*config,
enum
sp_dtr
dtr);
741
742
/**
743
* Set the DSR pin behaviour for the specified serial port.
744
*
745
* @param port Pointer to port structure.
746
* @param dsr DSR pin mode.
747
*
748
* @return SP_OK upon success, a negative error code otherwise.
749
*
750
* @since 0.1.0
751
*/
752
enum
sp_return
sp_set_dsr
(
struct
sp_port
*port,
enum
sp_dsr
dsr);
753
754
/**
755
* Get the DSR pin behaviour from a port configuration.
756
*
757
* The user should allocate a variable of type enum sp_dsr and pass a pointer to this
758
* to receive the result.
759
*
760
* @param config Pointer to configuration structure.
761
* @param dsr_ptr Pointer to variable to store result.
762
*
763
* @return SP_OK upon success, a negative error code otherwise.
764
*
765
* @since 0.1.0
766
*/
767
enum
sp_return
sp_get_config_dsr
(
const
struct
sp_port_config
*config,
enum
sp_dsr
*dsr_ptr);
768
769
/**
770
* Set the DSR pin behaviour in a port configuration.
771
*
772
* @param config Pointer to configuration structure.
773
* @param dsr DSR pin mode, or -1 to retain current setting.
774
*
775
* @return SP_OK upon success, a negative error code otherwise.
776
*
777
* @since 0.1.0
778
*/
779
enum
sp_return
sp_set_config_dsr
(
struct
sp_port_config
*config,
enum
sp_dsr
dsr);
780
781
/**
782
* Set the XON/XOFF configuration for the specified serial port.
783
*
784
* @param port Pointer to port structure.
785
* @param xon_xoff XON/XOFF mode.
786
*
787
* @return SP_OK upon success, a negative error code otherwise.
788
*
789
* @since 0.1.0
790
*/
791
enum
sp_return
sp_set_xon_xoff
(
struct
sp_port
*port,
enum
sp_xonxoff
xon_xoff);
792
793
/**
794
* Get the XON/XOFF configuration from a port configuration.
795
*
796
* The user should allocate a variable of type enum sp_xonxoff and pass a pointer to this
797
* to receive the result.
798
*
799
* @param config Pointer to configuration structure.
800
* @param xon_xoff_ptr Pointer to variable to store result.
801
*
802
* @return SP_OK upon success, a negative error code otherwise.
803
*
804
* @since 0.1.0
805
*/
806
enum
sp_return
sp_get_config_xon_xoff
(
const
struct
sp_port_config
*config,
enum
sp_xonxoff
*xon_xoff_ptr);
807
808
/**
809
* Set the XON/XOFF configuration in a port configuration.
810
*
811
* @param config Pointer to configuration structure.
812
* @param xon_xoff XON/XOFF mode, or -1 to retain current setting.
813
*
814
* @return SP_OK upon success, a negative error code otherwise.
815
*
816
* @since 0.1.0
817
*/
818
enum
sp_return
sp_set_config_xon_xoff
(
struct
sp_port_config
*config,
enum
sp_xonxoff
xon_xoff);
819
820
/**
821
* Set the flow control type in a port configuration.
822
*
823
* This function is a wrapper that sets the RTS, CTS, DTR, DSR and
824
* XON/XOFF settings as necessary for the specified flow control
825
* type. For more fine-grained control of these settings, use their
826
* individual configuration functions.
827
*
828
* @param config Pointer to configuration structure.
829
* @param flowcontrol Flow control setting to use.
830
*
831
* @return SP_OK upon success, a negative error code otherwise.
832
*
833
* @since 0.1.0
834
*/
835
enum
sp_return
sp_set_config_flowcontrol
(
struct
sp_port_config
*config,
enum
sp_flowcontrol
flowcontrol);
836
837
/**
838
* Set the flow control type for the specified serial port.
839
*
840
* This function is a wrapper that sets the RTS, CTS, DTR, DSR and
841
* XON/XOFF settings as necessary for the specified flow control
842
* type. For more fine-grained control of these settings, use their
843
* individual configuration functions.
844
*
845
* @param port Pointer to port structure.
846
* @param flowcontrol Flow control setting to use.
847
*
848
* @return SP_OK upon success, a negative error code otherwise.
849
*
850
* @since 0.1.0
851
*/
852
enum
sp_return
sp_set_flowcontrol
(
struct
sp_port
*port,
enum
sp_flowcontrol
flowcontrol);
853
854
/**
855
* @}
856
* @defgroup Data Reading, writing, and flushing data
857
* @{
858
*/
859
860
/**
861
* Read bytes from the specified serial port, blocking until complete.
862
*
863
* @warning If your program runs on Unix, defines its own signal handlers, and
864
* needs to abort blocking reads when these are called, then you
865
* should not use this function. It repeats system calls that return
866
* with EINTR. To be able to abort a read from a signal handler, you
867
* should implement your own blocking read using sp_nonblocking_read()
868
* together with a blocking method that makes sense for your program.
869
* E.g. you can obtain the file descriptor for an open port using
870
* sp_get_port_handle() and use this to call select() or pselect(),
871
* with appropriate arrangements to return if a signal is received.
872
*
873
* @param port Pointer to port structure.
874
* @param buf Buffer in which to store the bytes read.
875
* @param count Requested number of bytes to read.
876
* @param timeout Timeout in milliseconds, or zero to wait indefinitely.
877
*
878
* @return The number of bytes read on success, or a negative error code. If
879
* the number of bytes returned is less than that requested, the
880
* timeout was reached before the requested number of bytes was
881
* available. If timeout is zero, the function will always return
882
* either the requested number of bytes or a negative error code.
883
*
884
* @since 0.1.0
885
*/
886
enum
sp_return
sp_blocking_read
(
struct
sp_port
*port,
void
*buf,
size_t
count,
unsigned
int
timeout);
887
888
/**
889
* Read bytes from the specified serial port, without blocking.
890
*
891
* @param port Pointer to port structure.
892
* @param buf Buffer in which to store the bytes read.
893
* @param count Maximum number of bytes to read.
894
*
895
* @return The number of bytes read on success, or a negative error code. The
896
* number of bytes returned may be any number from zero to the maximum
897
* that was requested.
898
*
899
* @since 0.1.0
900
*/
901
enum
sp_return
sp_nonblocking_read
(
struct
sp_port
*port,
void
*buf,
size_t
count);
902
903
/**
904
* Write bytes to the specified serial port, blocking until complete.
905
*
906
* Note that this function only ensures that the accepted bytes have been
907
* written to the OS; they may be held in driver or hardware buffers and not
908
* yet physically transmitted. To check whether all written bytes have actually
909
* been transmitted, use the sp_output_waiting() function. To wait until all
910
* written bytes have actually been transmitted, use the sp_drain() function.
911
*
912
* @warning If your program runs on Unix, defines its own signal handlers, and
913
* needs to abort blocking writes when these are called, then you
914
* should not use this function. It repeats system calls that return
915
* with EINTR. To be able to abort a write from a signal handler, you
916
* should implement your own blocking write using sp_nonblocking_write()
917
* together with a blocking method that makes sense for your program.
918
* E.g. you can obtain the file descriptor for an open port using
919
* sp_get_port_handle() and use this to call select() or pselect(),
920
* with appropriate arrangements to return if a signal is received.
921
*
922
* @param port Pointer to port structure.
923
* @param buf Buffer containing the bytes to write.
924
* @param count Requested number of bytes to write.
925
* @param timeout Timeout in milliseconds, or zero to wait indefinitely.
926
*
927
* @return The number of bytes written on success, or a negative error code.
928
* If the number of bytes returned is less than that requested, the
929
* timeout was reached before the requested number of bytes was
930
* written. If timeout is zero, the function will always return
931
* either the requested number of bytes or a negative error code. In
932
* the event of an error there is no way to determine how many bytes
933
* were sent before the error occured.
934
*
935
* @since 0.1.0
936
*/
937
enum
sp_return
sp_blocking_write
(
struct
sp_port
*port,
const
void
*buf,
size_t
count,
unsigned
int
timeout);
938
939
/**
940
* Write bytes to the specified serial port, without blocking.
941
*
942
* Note that this function only ensures that the accepted bytes have been
943
* written to the OS; they may be held in driver or hardware buffers and not
944
* yet physically transmitted. To check whether all written bytes have actually
945
* been transmitted, use the sp_output_waiting() function. To wait until all
946
* written bytes have actually been transmitted, use the sp_drain() function.
947
*
948
* @param port Pointer to port structure.
949
* @param buf Buffer containing the bytes to write.
950
* @param count Maximum number of bytes to write.
951
*
952
* @return The number of bytes written on success, or a negative error code.
953
* The number of bytes returned may be any number from zero to the
954
* maximum that was requested.
955
*
956
* @since 0.1.0
957
*/
958
enum
sp_return
sp_nonblocking_write
(
struct
sp_port
*port,
const
void
*buf,
size_t
count);
959
960
/**
961
* Gets the number of bytes waiting in the input buffer.
962
*
963
* @param port Pointer to port structure.
964
*
965
* @return Number of bytes waiting on success, a negative error code otherwise.
966
*
967
* @since 0.1.0
968
*/
969
enum
sp_return
sp_input_waiting
(
struct
sp_port
*port);
970
971
/**
972
* Gets the number of bytes waiting in the output buffer.
973
*
974
* @param port Pointer to port structure.
975
*
976
* @return Number of bytes waiting on success, a negative error code otherwise.
977
*
978
* @since 0.1.0
979
*/
980
enum
sp_return
sp_output_waiting
(
struct
sp_port
*port);
981
982
/**
983
* Flush serial port buffers. Data in the selected buffer(s) is discarded.
984
*
985
* @param port Pointer to port structure.
986
* @param buffers Which buffer(s) to flush.
987
*
988
* @return SP_OK upon success, a negative error code otherwise.
989
*
990
* @since 0.1.0
991
*/
992
enum
sp_return
sp_flush
(
struct
sp_port
*port,
enum
sp_buffer
buffers);
993
994
/**
995
* Wait for buffered data to be transmitted.
996
*
997
* @warning If your program runs on Unix, defines its own signal handlers, and
998
* needs to abort draining the output buffer when when these are
999
* called, then you should not use this function. It repeats system
1000
* calls that return with EINTR. To be able to abort a drain from a
1001
* signal handler, you would need to implement your own blocking
1002
* drain by polling the result of sp_output_waiting().
1003
*
1004
* @param port Pointer to port structure.
1005
*
1006
* @return SP_OK upon success, a negative error code otherwise.
1007
*
1008
* @since 0.1.0
1009
*/
1010
enum
sp_return
sp_drain
(
struct
sp_port
*port);
1011
1012
/**
1013
* @}
1014
* @defgroup Waiting Waiting for events
1015
* @{
1016
*/
1017
1018
/**
1019
* Allocate storage for a set of events.
1020
*
1021
* The user should allocate a variable of type struct sp_event_set *,
1022
* then pass a pointer to this variable to receive the result.
1023
*
1024
* The result should be freed after use by calling sp_free_event_set().
1025
*
1026
* @return SP_OK upon success, a negative error code otherwise.
1027
*
1028
* @since 0.1.0
1029
*/
1030
enum
sp_return
sp_new_event_set
(
struct
sp_event_set
**result_ptr);
1031
1032
/**
1033
* Add events to a struct sp_event_set for a given port.
1034
*
1035
* The port must first be opened by calling sp_open() using the same port
1036
* structure.
1037
*
1038
* After the port is closed or the port structure freed, the results may
1039
* no longer be valid.
1040
*
1041
* @param event_set Event set to update.
1042
* @param port Pointer to port structure.
1043
* @param mask Bitmask of events to be waited for.
1044
*
1045
* @return SP_OK upon success, a negative error code otherwise.
1046
*
1047
* @since 0.1.0
1048
*/
1049
enum
sp_return
sp_add_port_events
(
struct
sp_event_set
*event_set,
1050
const
struct
sp_port
*port,
enum
sp_event
mask);
1051
1052
/**
1053
* Wait for any of a set of events to occur.
1054
*
1055
* @param event_set Event set to wait on.
1056
* @param timeout Timeout in milliseconds, or zero to wait indefinitely.
1057
*
1058
* @return SP_OK upon success, a negative error code otherwise.
1059
*
1060
* @since 0.1.0
1061
*/
1062
enum
sp_return
sp_wait
(
struct
sp_event_set
*event_set,
unsigned
int
timeout);
1063
1064
/**
1065
* Free a structure allocated by sp_new_event_set().
1066
*
1067
* @since 0.1.0
1068
*/
1069
void
sp_free_event_set
(
struct
sp_event_set
*event_set);
1070
1071
/**
1072
* @}
1073
* @defgroup Signals Port signalling operations
1074
* @{
1075
*/
1076
1077
/**
1078
* Gets the status of the control signals for the specified port.
1079
*
1080
* The user should allocate a variable of type "enum sp_signal" and pass a
1081
* pointer to this variable to receive the result. The result is a bitmask
1082
* in which individual signals can be checked by bitwise OR with values of
1083
* the sp_signal enum.
1084
*
1085
* @param port Pointer to port structure.
1086
* @param signals Pointer to variable to receive result.
1087
*
1088
* @return SP_OK upon success, a negative error code otherwise.
1089
*
1090
* @since 0.1.0
1091
*/
1092
enum
sp_return
sp_get_signals
(
struct
sp_port
*port,
enum
sp_signal
*signals);
1093
1094
/**
1095
* Put the port transmit line into the break state.
1096
*
1097
* @param port Pointer to port structure.
1098
*
1099
* @return SP_OK upon success, a negative error code otherwise.
1100
*
1101
* @since 0.1.0
1102
*/
1103
enum
sp_return
sp_start_break
(
struct
sp_port
*port);
1104
1105
/**
1106
* Take the port transmit line out of the break state.
1107
*
1108
* @param port Pointer to port structure.
1109
*
1110
* @return SP_OK upon success, a negative error code otherwise.
1111
*
1112
* @since 0.1.0
1113
*/
1114
enum
sp_return
sp_end_break
(
struct
sp_port
*port);
1115
1116
/**
1117
* @}
1118
* @defgroup Errors Obtaining error information
1119
* @{
1120
*/
1121
1122
/**
1123
* Get the error code for a failed operation.
1124
*
1125
* In order to obtain the correct result, this function should be called
1126
* straight after the failure, before executing any other system operations.
1127
*
1128
* @return The system's numeric code for the error that caused the last
1129
* operation to fail.
1130
*
1131
* @since 0.1.0
1132
*/
1133
int
sp_last_error_code
(
void
);
1134
1135
/**
1136
* Get the error message for a failed operation.
1137
*
1138
* In order to obtain the correct result, this function should be called
1139
* straight after the failure, before executing other system operations.
1140
*
1141
* @return The system's message for the error that caused the last
1142
* operation to fail. This string may be allocated by the function,
1143
* and should be freed after use by calling sp_free_error_message().
1144
*
1145
* @since 0.1.0
1146
*/
1147
char
*
sp_last_error_message
(
void
);
1148
1149
/**
1150
* Free an error message returned by sp_last_error_message().
1151
*
1152
* @since 0.1.0
1153
*/
1154
void
sp_free_error_message
(
char
*message);
1155
1156
/**
1157
* Set the handler function for library debugging messages.
1158
*
1159
* Debugging messages are generated by the library during each operation,
1160
* to help in diagnosing problems. The handler will be called for each
1161
* message. The handler can be set to NULL to ignore all debug messages.
1162
*
1163
* The handler function should accept a format string and variable length
1164
* argument list, in the same manner as e.g. printf().
1165
*
1166
* The default handler is sp_default_debug_handler().
1167
*
1168
* @since 0.1.0
1169
*/
1170
void
sp_set_debug_handler
(
void
(*handler)(
const
char
*format, ...));
1171
1172
/**
1173
* Default handler function for library debugging messages.
1174
*
1175
* This function prints debug messages to the standard error stream if the
1176
* environment variable LIBSERIALPORT_DEBUG is set. Otherwise, they are
1177
* ignored.
1178
*
1179
* @since 0.1.0
1180
*/
1181
void
sp_default_debug_handler
(
const
char
*format, ...);
1182
1183
/** @} */
1184
1185
/**
1186
* @defgroup Versions Version number querying functions, definitions, and macros
1187
*
1188
* This set of API calls returns two different version numbers related
1189
* to libserialport. The "package version" is the release version number of the
1190
* libserialport tarball in the usual "major.minor.micro" format, e.g. "0.1.0".
1191
*
1192
* The "library version" is independent of that; it is the libtool version
1193
* number in the "current:revision:age" format, e.g. "2:0:0".
1194
* See http://www.gnu.org/software/libtool/manual/libtool.html#Libtool-versioning for details.
1195
*
1196
* Both version numbers (and/or individual components of them) can be
1197
* retrieved via the API calls at runtime, and/or they can be checked at
1198
* compile/preprocessor time using the respective macros.
1199
*
1200
* @{
1201
*/
1202
1203
/*
1204
* Package version macros (can be used for conditional compilation).
1205
*/
1206
1207
/** The libserialport package 'major' version number. */
1208
#define SP_PACKAGE_VERSION_MAJOR 0
1209
1210
/** The libserialport package 'minor' version number. */
1211
#define SP_PACKAGE_VERSION_MINOR 1
1212
1213
/** The libserialport package 'micro' version number. */
1214
#define SP_PACKAGE_VERSION_MICRO 0
1215
1216
/** The libserialport package version ("major.minor.micro") as string. */
1217
#define SP_PACKAGE_VERSION_STRING "0.1.0"
1218
1219
/*
1220
* Library/libtool version macros (can be used for conditional compilation).
1221
*/
1222
1223
/** The libserialport libtool 'current' version number. */
1224
#define SP_LIB_VERSION_CURRENT 0
1225
1226
/** The libserialport libtool 'revision' version number. */
1227
#define SP_LIB_VERSION_REVISION 0
1228
1229
/** The libserialport libtool 'age' version number. */
1230
#define SP_LIB_VERSION_AGE 0
1231
1232
/** The libserialport libtool version ("current:revision:age") as string. */
1233
#define SP_LIB_VERSION_STRING "0:0:0"
1234
1235
/**
1236
* Get the major libserialport package version number.
1237
*
1238
* @return The major package version number.
1239
*
1240
* @since 0.1.0
1241
*/
1242
int
sp_get_major_package_version
(
void
);
1243
1244
/**
1245
* Get the minor libserialport package version number.
1246
*
1247
* @return The minor package version number.
1248
*
1249
* @since 0.1.0
1250
*/
1251
int
sp_get_minor_package_version
(
void
);
1252
1253
/**
1254
* Get the micro libserialport package version number.
1255
*
1256
* @return The micro package version number.
1257
*
1258
* @since 0.1.0
1259
*/
1260
int
sp_get_micro_package_version
(
void
);
1261
1262
/**
1263
* Get the libserialport package version number as a string.
1264
*
1265
* @return The package version number string. The returned string is
1266
* static and thus should NOT be free'd by the caller.
1267
*
1268
* @since 0.1.0
1269
*/
1270
const
char
*
sp_get_package_version_string
(
void
);
1271
1272
/**
1273
* Get the "current" part of the libserialport library version number.
1274
*
1275
* @return The "current" library version number.
1276
*
1277
* @since 0.1.0
1278
*/
1279
int
sp_get_current_lib_version
(
void
);
1280
1281
/**
1282
* Get the "revision" part of the libserialport library version number.
1283
*
1284
* @return The "revision" library version number.
1285
*
1286
* @since 0.1.0
1287
*/
1288
int
sp_get_revision_lib_version
(
void
);
1289
1290
/**
1291
* Get the "age" part of the libserialport library version number.
1292
*
1293
* @return The "age" library version number.
1294
*
1295
* @since 0.1.0
1296
*/
1297
int
sp_get_age_lib_version
(
void
);
1298
1299
/**
1300
* Get the libserialport library version number as a string.
1301
*
1302
* @return The library version number string. The returned string is
1303
* static and thus should NOT be free'd by the caller.
1304
*
1305
* @since 0.1.0
1306
*/
1307
const
char
*
sp_get_lib_version_string
(
void
);
1308
1309
/** @} */
1310
1311
#ifdef __cplusplus
1312
}
1313
#endif
1314
1315
#endif
Generated on Fri Sep 19 2014 18:04:35 for libserialport by
1.8.3.1