libserialport 0.1.1
cross-platform library for accessing serial ports
Loading...
Searching...
No Matches
libserialport.h
Go to the documentation of this file.
1/* libserialport.h. Generated from libserialport.h.in by configure. */
2/*
3 * This file is part of the libserialport project.
4 *
5 * Copyright (C) 2013, 2015 Martin Ling <martin-libserialport@earth.li>
6 * Copyright (C) 2014 Uwe Hermann <uwe@hermann-uwe.de>
7 * Copyright (C) 2014 Aurelien Jacobs <aurel@gnuage.org>
8 *
9 * This program is free software: you can redistribute it and/or modify
10 * it under the terms of the GNU Lesser General Public License as
11 * published by the Free Software Foundation, either version 3 of the
12 * License, or (at your option) any later version.
13 *
14 * This program is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU General Public License for more details.
18 *
19 * You should have received a copy of the GNU Lesser General Public License
20 * along with this program. If not, see <http://www.gnu.org/licenses/>.
21 */
22
23/**
24 * @mainpage libserialport API
25 *
26 * Introduction
27 * ============
28 *
29 * libserialport is a minimal library written in C that is intended to take
30 * care of the OS-specific details when writing software that uses serial ports.
31 *
32 * By writing your serial code to use libserialport, you enable it to work
33 * transparently on any platform supported by the library.
34 *
35 * libserialport is an open source project released under the LGPL3+ license.
36 *
37 * The library is maintained by the [sigrok](http://sigrok.org/) project. See
38 * the [libserialport homepage](http://sigrok.org/wiki/Libserialport) for the
39 * latest information.
40 *
41 * Source code is maintained in git at
42 * [git://sigrok.org/libserialport](http://sigrok.org/gitweb/?p=libserialport.git).
43 *
44 * Bugs are tracked at http://sigrok.org/bugzilla/.
45 *
46 * The library was conceived and designed by Martin Ling, is maintained by
47 * Uwe Hermann, and has received contributions from several other developers.
48 * See the git history for full credits.
49 *
50 * API information
51 * ===============
52 *
53 * The API has been designed from scratch. It does not exactly resemble the
54 * serial API of any particular operating system. Instead it aims to provide
55 * a set of functions that can reliably be implemented across all operating
56 * systems. These form a sufficient basis for higher level behaviour to
57 * be implemented in a platform independent manner.
58 *
59 * If you are porting code written for a particular OS, you may find you need
60 * to restructure things somewhat, or do without some specialised features.
61 * For particular notes on porting existing code, see @ref Porting.
62 *
63 * The following subsections will help explain the principles of the API.
64 *
65 * Headers
66 * -------
67 *
68 * To use libserialport functions in your code, you should include the
69 * libserialport.h header, i.e. "#include <libserialport.h>".
70 *
71 * Namespace
72 * ---------
73 *
74 * All identifiers defined by the public libserialport headers use the prefix
75 * sp_ (for functions and data types) or SP_ (for macros and constants).
76 *
77 * Functions
78 * ---------
79 *
80 * The functions provided by the library are documented in detail in
81 * the following sections:
82 *
83 * - @ref Enumeration (obtaining a list of serial ports on the system)
84 * - @ref Ports (opening, closing and getting information about ports)
85 * - @ref Configuration (baud rate, parity, etc.)
86 * - @ref Signals (modem control lines, breaks, etc.)
87 * - @ref Data (reading and writing data, and buffer management)
88 * - @ref Waiting (waiting for ports to be ready, integrating with event loops)
89 * - @ref Errors (getting error and debugging information)
90 *
91 * Data structures
92 * ---------------
93 *
94 * The library defines three data structures:
95 *
96 * - @ref sp_port, which represents a serial port.
97 * See @ref Enumeration.
98 * - @ref sp_port_config, which represents a port configuration.
99 * See @ref Configuration.
100 * - @ref sp_event_set, which represents a set of events.
101 * See @ref Waiting.
102 *
103 * All these structures are allocated and freed by library functions. It is
104 * the caller's responsibility to ensure that the correct calls are made to
105 * free allocated structures after use.
106 *
107 * Return codes and error handling
108 * -------------------------------
109 *
110 * Most functions have return type @ref sp_return and can return only four
111 * possible error values:
112 *
113 * - @ref SP_ERR_ARG means that a function was called with invalid
114 * arguments. This implies a bug in the caller. The arguments passed would
115 * be invalid regardless of the underlying OS or serial device involved.
116 *
117 * - @ref SP_ERR_FAIL means that the OS reported a failure. The error code or
118 * message provided by the OS can be obtained by calling sp_last_error_code()
119 * or sp_last_error_message().
120 *
121 * - @ref SP_ERR_SUPP indicates that there is no support for the requested
122 * operation in the current OS, driver or device. No error message is
123 * available from the OS in this case. There is either no way to request
124 * the operation in the first place, or libserialport does not know how to
125 * do so in the current version.
126 *
127 * - @ref SP_ERR_MEM indicates that a memory allocation failed.
128 *
129 * All of these error values are negative.
130 *
131 * Calls that succeed return @ref SP_OK, which is equal to zero. Some functions
132 * declared @ref sp_return can also return a positive value for a successful
133 * numeric result, e.g. sp_blocking_read() or sp_blocking_write().
134 *
135 * An error message is only available via sp_last_error_message() in the case
136 * where SP_ERR_FAIL was returned by the previous function call. The error
137 * message returned is that provided by the OS, using the current language
138 * settings. It is an error to call sp_last_error_code() or
139 * sp_last_error_message() except after a previous function call returned
140 * SP_ERR_FAIL. The library does not define its own error codes or messages
141 * to accompany other return codes.
142 *
143 * Thread safety
144 * -------------
145 *
146 * Certain combinations of calls can be made concurrently, as follows.
147 *
148 * - Calls using different ports may always be made concurrently, i.e.
149 * it is safe for separate threads to handle their own ports.
150 *
151 * - Calls using the same port may be made concurrently when one call
152 * is a read operation and one call is a write operation, i.e. it is safe
153 * to use separate "reader" and "writer" threads for the same port. See
154 * below for which operations meet these definitions.
155 *
156 * Read operations:
157 *
158 * - sp_blocking_read()
159 * - sp_blocking_read_next()
160 * - sp_nonblocking_read()
161 * - sp_input_waiting()
162 * - sp_flush() with @ref SP_BUF_INPUT only.
163 * - sp_wait() with @ref SP_EVENT_RX_READY only.
164 *
165 * Write operations:
166 *
167 * - sp_blocking_write()
168 * - sp_nonblocking_write()
169 * - sp_output_waiting()
170 * - sp_drain()
171 * - sp_flush() with @ref SP_BUF_OUTPUT only.
172 * - sp_wait() with @ref SP_EVENT_TX_READY only.
173 *
174 * If two calls, on the same port, do not fit into one of these categories
175 * each, then they may not be made concurrently.
176 *
177 * Debugging
178 * ---------
179 *
180 * The library can output extensive tracing and debugging information. The
181 * simplest way to use this is to set the environment variable
182 * LIBSERIALPORT_DEBUG to any value; messages will then be output to the
183 * standard error stream.
184 *
185 * This behaviour is implemented by a default debug message handling
186 * callback. An alternative callback can be set using sp_set_debug_handler(),
187 * in order to e.g. redirect the output elsewhere or filter it.
188 *
189 * No guarantees are made about the content of the debug output; it is chosen
190 * to suit the needs of the developers and may change between releases.
191 *
192 * @anchor Porting
193 * Porting
194 * -------
195 *
196 * The following guidelines may help when porting existing OS-specific code
197 * to use libserialport.
198 *
199 * ### Porting from Unix-like systems ###
200 *
201 * There are two main differences to note when porting code written for Unix.
202 *
203 * The first is that Unix traditionally provides a wide range of functionality
204 * for dealing with serial devices at the OS level; this is exposed through the
205 * termios API and dates to the days when serial terminals were common. If your
206 * code relies on many of these facilities you will need to adapt it, because
207 * libserialport provides only a raw binary channel with no special handling.
208 *
209 * The second relates to blocking versus non-blocking I/O behaviour. In
210 * Unix-like systems this is normally specified by setting the O_NONBLOCK
211 * flag on the file descriptor, affecting the semantics of subsequent read()
212 * and write() calls.
213 *
214 * In libserialport, blocking and nonblocking operations are both available at
215 * any time. If your existing code ѕets O_NONBLOCK, you should use
216 * sp_nonblocking_read() and sp_nonblocking_write() to get the same behaviour
217 * as your existing read() and write() calls. If it does not, you should use
218 * sp_blocking_read() and sp_blocking_write() instead. You may also find
219 * sp_blocking_read_next() useful, which reproduces the semantics of a blocking
220 * read() with VTIME = 0 and VMIN = 1 set in termios.
221 *
222 * Finally, you should take care if your program uses custom signal handlers.
223 * The blocking calls provided by libserialport will restart system calls that
224 * return with EINTR, so you will need to make your own arrangements if you
225 * need to interrupt blocking operations when your signal handlers are called.
226 * This is not an issue if you only use the default handlers.
227 *
228 * ### Porting from Windows ###
229 *
230 * The main consideration when porting from Windows is that there is no
231 * direct equivalent for overlapped I/O operations.
232 *
233 * If your program does not use overlapped I/O, you can simply use
234 * sp_blocking_read() and sp_blocking_write() as direct equivalents for
235 * ReadFile() and WriteFile(). You may also find sp_blocking_read_next()
236 * useful, which reproduces the special semantics of ReadFile() with
237 * ReadIntervalTimeout and ReadTotalTimeoutMultiplier set to MAXDWORD
238 * and 0 < ReadTotalTimeoutConstant < MAXDWORD.
239 *
240 * If your program makes use of overlapped I/O to continue work while a serial
241 * operation is in progress, then you can achieve the same results using
242 * sp_nonblocking_read() and sp_nonblocking_write().
243 *
244 * Generally, overlapped I/O is combined with either waiting for completion
245 * once there is no more background work to do (using WaitForSingleObject() or
246 * WaitForMultipleObjects()), or periodically checking for completion with
247 * GetOverlappedResult(). If the aim is to start a new operation for further
248 * data once the previous one has completed, you can instead simply call the
249 * nonblocking functions again with the next data. If you need to wait for
250 * completion, use sp_wait() to determine when the port is ready to send or
251 * receive further data.
252 */
253
254#ifndef LIBSERIALPORT_LIBSERIALPORT_H
255#define LIBSERIALPORT_LIBSERIALPORT_H
256
257#ifdef __cplusplus
258extern "C" {
259#endif
260
261#include <stddef.h>
262
263/** Return values. */
265 /** Operation completed successfully. */
266 SP_OK = 0,
267 /** Invalid arguments were passed to the function. */
269 /** A system error occurred while executing the operation. */
271 /** A memory allocation failed while executing the operation. */
273 /** The requested operation is not supported by this system or device. */
274 SP_ERR_SUPP = -4
276
277/** Port access modes. */
279 /** Open port for read access. */
281 /** Open port for write access. */
283 /** Open port for read and write access. @since 0.1.1 */
286
287/** Port events. */
289 /** Data received and ready to read. */
291 /** Ready to transmit new data. */
293 /** Error occurred. */
296
297/** Buffer selection. */
299 /** Input buffer. */
301 /** Output buffer. */
303 /** Both buffers. */
304 SP_BUF_BOTH = 3
306
307/** Parity settings. */
309 /** Special value to indicate setting should be left alone. */
311 /** No parity. */
313 /** Odd parity. */
315 /** Even parity. */
317 /** Mark parity. */
319 /** Space parity. */
322
323/** RTS pin behaviour. */
324enum sp_rts {
325 /** Special value to indicate setting should be left alone. */
327 /** RTS off. */
329 /** RTS on. */
331 /** RTS used for flow control. */
334
335/** CTS pin behaviour. */
336enum sp_cts {
337 /** Special value to indicate setting should be left alone. */
339 /** CTS ignored. */
341 /** CTS used for flow control. */
344
345/** DTR pin behaviour. */
346enum sp_dtr {
347 /** Special value to indicate setting should be left alone. */
349 /** DTR off. */
351 /** DTR on. */
353 /** DTR used for flow control. */
356
357/** DSR pin behaviour. */
358enum sp_dsr {
359 /** Special value to indicate setting should be left alone. */
361 /** DSR ignored. */
363 /** DSR used for flow control. */
366
367/** XON/XOFF flow control behaviour. */
369 /** Special value to indicate setting should be left alone. */
371 /** XON/XOFF disabled. */
373 /** XON/XOFF enabled for input only. */
375 /** XON/XOFF enabled for output only. */
377 /** XON/XOFF enabled for input and output. */
380
381/** Standard flow control combinations. */
383 /** No flow control. */
385 /** Software flow control using XON/XOFF characters. */
387 /** Hardware flow control using RTS/CTS signals. */
389 /** Hardware flow control using DTR/DSR signals. */
392
393/** Input signals. */
395 /** Clear to send. */
397 /** Data set ready. */
399 /** Data carrier detect. */
401 /** Ring indicator. */
402 SP_SIG_RI = 8
404
405/**
406 * Transport types.
407 *
408 * @since 0.1.1
409 */
411 /** Native platform serial port. @since 0.1.1 */
413 /** USB serial port adapter. @since 0.1.1 */
415 /** Bluetooth serial port adapter. @since 0.1.1 */
418
419/**
420 * @struct sp_port
421 * An opaque structure representing a serial port.
422 */
423struct sp_port;
424
425/**
426 * @struct sp_port_config
427 * An opaque structure representing the configuration for a serial port.
428 */
429struct sp_port_config;
430
431/**
432 * @struct sp_event_set
433 * A set of handles to wait on for events.
434 */
436 /** Array of OS-specific handles. */
437 void *handles;
438 /** Array of bitmasks indicating which events apply for each handle. */
440 /** Number of handles. */
441 unsigned int count;
442};
443
444/**
445 * @defgroup Enumeration Port enumeration
446 *
447 * Enumerating the serial ports of a system.
448 *
449 * @{
450 */
451
452/**
453 * Obtain a pointer to a new sp_port structure representing the named port.
454 *
455 * The user should allocate a variable of type "struct sp_port *" and pass a
456 * pointer to this to receive the result.
457 *
458 * The result should be freed after use by calling sp_free_port().
459 *
460 * @param[in] portname The OS-specific name of a serial port. Must not be NULL.
461 * @param[out] port_ptr If any error is returned, the variable pointed to by
462 * port_ptr will be set to NULL. Otherwise, it will be set
463 * to point to the newly allocated port. Must not be NULL.
464 *
465 * @return SP_OK upon success, a negative error code otherwise.
466 *
467 * @since 0.1.0
468 */
469enum sp_return sp_get_port_by_name(const char *portname, struct sp_port **port_ptr);
470
471/**
472 * Free a port structure obtained from sp_get_port_by_name() or sp_copy_port().
473 *
474 * @param[in] port Pointer to a port structure. Must not be NULL.
475 *
476 * @since 0.1.0
477 */
478void sp_free_port(struct sp_port *port);
479
480/**
481 * List the serial ports available on the system.
482 *
483 * The result obtained is an array of pointers to sp_port structures,
484 * terminated by a NULL. The user should allocate a variable of type
485 * "struct sp_port **" and pass a pointer to this to receive the result.
486 *
487 * The result should be freed after use by calling sp_free_port_list().
488 * If a port from the list is to be used after freeing the list, it must be
489 * copied first using sp_copy_port().
490 *
491 * @param[out] list_ptr If any error is returned, the variable pointed to by
492 * list_ptr will be set to NULL. Otherwise, it will be set
493 * to point to the newly allocated array. Must not be NULL.
494 *
495 * @return SP_OK upon success, a negative error code otherwise.
496 *
497 * @since 0.1.0
498 */
499enum sp_return sp_list_ports(struct sp_port ***list_ptr);
500
501/**
502 * Make a new copy of an sp_port structure.
503 *
504 * The user should allocate a variable of type "struct sp_port *" and pass a
505 * pointer to this to receive the result.
506 *
507 * The copy should be freed after use by calling sp_free_port().
508 *
509 * @param[in] port Pointer to a port structure. Must not be NULL.
510 * @param[out] copy_ptr If any error is returned, the variable pointed to by
511 * copy_ptr will be set to NULL. Otherwise, it will be set
512 * to point to the newly allocated copy. Must not be NULL.
513 *
514 * @return SP_OK upon success, a negative error code otherwise.
515 *
516 * @since 0.1.0
517 */
518enum sp_return sp_copy_port(const struct sp_port *port, struct sp_port **copy_ptr);
519
520/**
521 * Free a port list obtained from sp_list_ports().
522 *
523 * This will also free all the sp_port structures referred to from the list;
524 * any that are to be retained must be copied first using sp_copy_port().
525 *
526 * @param[in] ports Pointer to a list of port structures. Must not be NULL.
527 *
528 * @since 0.1.0
529 */
530void sp_free_port_list(struct sp_port **ports);
531
532/**
533 * @}
534 * @defgroup Ports Port handling
535 *
536 * Opening, closing and querying ports.
537 *
538 * @{
539 */
540
541/**
542 * Open the specified serial port.
543 *
544 * @param[in] port Pointer to a port structure. Must not be NULL.
545 * @param[in] flags Flags to use when opening the serial port.
546 *
547 * @return SP_OK upon success, a negative error code otherwise.
548 *
549 * @since 0.1.0
550 */
551enum sp_return sp_open(struct sp_port *port, enum sp_mode flags);
552
553/**
554 * Close the specified serial port.
555 *
556 * @param[in] port Pointer to a port structure. Must not be NULL.
557 *
558 * @return SP_OK upon success, a negative error code otherwise.
559 *
560 * @since 0.1.0
561 */
562enum sp_return sp_close(struct sp_port *port);
563
564/**
565 * Get the name of a port.
566 *
567 * The name returned is whatever is normally used to refer to a port on the
568 * current operating system; e.g. for Windows it will usually be a "COMn"
569 * device name, and for Unix it will be a device path beginning with "/dev/".
570 *
571 * @param[in] port Pointer to a port structure. Must not be NULL.
572 *
573 * @return The port name, or NULL if an invalid port is passed. The name
574 * string is part of the port structure and may not be used after
575 * the port structure has been freed.
576 *
577 * @since 0.1.0
578 */
579char *sp_get_port_name(const struct sp_port *port);
580
581/**
582 * Get a description for a port, to present to end user.
583 *
584 * @param[in] port Pointer to a port structure. Must not be NULL.
585 *
586 * @return The port description, or NULL if an invalid port is passed.
587 * The description string is part of the port structure and may not
588 * be used after the port structure has been freed.
589 *
590 * @since 0.1.1
591 */
592char *sp_get_port_description(const struct sp_port *port);
593
594/**
595 * Get the transport type used by a port.
596 *
597 * @param[in] port Pointer to a port structure. Must not be NULL.
598 *
599 * @return The port transport type.
600 *
601 * @since 0.1.1
602 */
604
605/**
606 * Get the USB bus number and address on bus of a USB serial adapter port.
607 *
608 * @param[in] port Pointer to a port structure. Must not be NULL.
609 * @param[out] usb_bus Pointer to a variable to store the USB bus.
610 * Can be NULL (in that case it will be ignored).
611 * @param[out] usb_address Pointer to a variable to store the USB address.
612 * Can be NULL (in that case it will be ignored).
613 *
614 * @return SP_OK upon success, a negative error code otherwise.
615 *
616 * @since 0.1.1
617 */
619 int *usb_bus, int *usb_address);
620
621/**
622 * Get the USB Vendor ID and Product ID of a USB serial adapter port.
623 *
624 * @param[in] port Pointer to a port structure. Must not be NULL.
625 * @param[out] usb_vid Pointer to a variable to store the USB VID.
626 * Can be NULL (in that case it will be ignored).
627 * @param[out] usb_pid Pointer to a variable to store the USB PID.
628 * Can be NULL (in that case it will be ignored).
629 *
630 * @return SP_OK upon success, a negative error code otherwise.
631 *
632 * @since 0.1.1
633 */
634enum sp_return sp_get_port_usb_vid_pid(const struct sp_port *port, int *usb_vid, int *usb_pid);
635
636/**
637 * Get the USB manufacturer string of a USB serial adapter port.
638 *
639 * @param[in] port Pointer to a port structure. Must not be NULL.
640 *
641 * @return The port manufacturer string, or NULL if an invalid port is passed.
642 * The manufacturer string is part of the port structure and may not
643 * be used after the port structure has been freed.
644 *
645 * @since 0.1.1
646 */
647char *sp_get_port_usb_manufacturer(const struct sp_port *port);
648
649/**
650 * Get the USB product string of a USB serial adapter port.
651 *
652 * @param[in] port Pointer to a port structure. Must not be NULL.
653 *
654 * @return The port product string, or NULL if an invalid port is passed.
655 * The product string is part of the port structure and may not be
656 * used after the port structure has been freed.
657 *
658 * @since 0.1.1
659 */
660char *sp_get_port_usb_product(const struct sp_port *port);
661
662/**
663 * Get the USB serial number string of a USB serial adapter port.
664 *
665 * @param[in] port Pointer to a port structure. Must not be NULL.
666 *
667 * @return The port serial number, or NULL if an invalid port is passed.
668 * The serial number string is part of the port structure and may
669 * not be used after the port structure has been freed.
670 *
671 * @since 0.1.1
672 */
673char *sp_get_port_usb_serial(const struct sp_port *port);
674
675/**
676 * Get the MAC address of a Bluetooth serial adapter port.
677 *
678 * @param[in] port Pointer to a port structure. Must not be NULL.
679 *
680 * @return The port MAC address, or NULL if an invalid port is passed.
681 * The MAC address string is part of the port structure and may not
682 * be used after the port structure has been freed.
683 *
684 * @since 0.1.1
685 */
686char *sp_get_port_bluetooth_address(const struct sp_port *port);
687
688/**
689 * Get the operating system handle for a port.
690 *
691 * The type of the handle depends on the operating system. On Unix based
692 * systems, the handle is a file descriptor of type "int". On Windows, the
693 * handle is of type "HANDLE". The user should allocate a variable of the
694 * appropriate type and pass a pointer to this to receive the result.
695 *
696 * To obtain a valid handle, the port must first be opened by calling
697 * sp_open() using the same port structure.
698 *
699 * After the port is closed or the port structure freed, the handle may
700 * no longer be valid.
701 *
702 * @warning This feature is provided so that programs may make use of
703 * OS-specific functionality where desired. Doing so obviously
704 * comes at a cost in portability. It also cannot be guaranteed
705 * that direct usage of the OS handle will not conflict with the
706 * library's own usage of the port. Be careful.
707 *
708 * @param[in] port Pointer to a port structure. Must not be NULL.
709 * @param[out] result_ptr If any error is returned, the variable pointed to by
710 * result_ptr will have unknown contents and should not
711 * be used. Otherwise, it will be set to point to the
712 * OS handle. Must not be NULL.
713 *
714 * @return SP_OK upon success, a negative error code otherwise.
715 *
716 * @since 0.1.0
717 */
718enum sp_return sp_get_port_handle(const struct sp_port *port, void *result_ptr);
719
720/**
721 * @}
722 *
723 * @defgroup Configuration Configuration
724 *
725 * Setting and querying serial port parameters.
726 * @{
727 */
728
729/**
730 * Allocate a port configuration structure.
731 *
732 * The user should allocate a variable of type "struct sp_port_config *" and
733 * pass a pointer to this to receive the result. The variable will be updated
734 * to point to the new configuration structure. The structure is opaque and
735 * must be accessed via the functions provided.
736 *
737 * All parameters in the structure will be initialised to special values which
738 * are ignored by sp_set_config().
739 *
740 * The structure should be freed after use by calling sp_free_config().
741 *
742 * @param[out] config_ptr If any error is returned, the variable pointed to by
743 * config_ptr will be set to NULL. Otherwise, it will
744 * be set to point to the allocated config structure.
745 * Must not be NULL.
746 *
747 * @return SP_OK upon success, a negative error code otherwise.
748 *
749 * @since 0.1.0
750 */
751enum sp_return sp_new_config(struct sp_port_config **config_ptr);
752
753/**
754 * Free a port configuration structure.
755 *
756 * @param[in] config Pointer to a configuration structure. Must not be NULL.
757 *
758 * @since 0.1.0
759 */
760void sp_free_config(struct sp_port_config *config);
761
762/**
763 * Get the current configuration of the specified serial port.
764 *
765 * The user should allocate a configuration structure using sp_new_config()
766 * and pass this as the config parameter. The configuration structure will
767 * be updated with the port configuration.
768 *
769 * Any parameters that are configured with settings not recognised or
770 * supported by libserialport, will be set to special values that are
771 * ignored by sp_set_config().
772 *
773 * @param[in] port Pointer to a port structure. Must not be NULL.
774 * @param[out] config Pointer to a configuration structure that will hold
775 * the result. Upon errors the contents of the config
776 * struct will not be changed. Must not be NULL.
777 *
778 * @return SP_OK upon success, a negative error code otherwise.
779 *
780 * @since 0.1.0
781 */
782enum sp_return sp_get_config(struct sp_port *port, struct sp_port_config *config);
783
784/**
785 * Set the configuration for the specified serial port.
786 *
787 * For each parameter in the configuration, there is a special value (usually
788 * -1, but see the documentation for each field). These values will be ignored
789 * and the corresponding setting left unchanged on the port.
790 *
791 * Upon errors, the configuration of the serial port is unknown since
792 * partial/incomplete config updates may have happened.
793 *
794 * @param[in] port Pointer to a port structure. Must not be NULL.
795 * @param[in] config Pointer to a configuration structure. Must not be NULL.
796 *
797 * @return SP_OK upon success, a negative error code otherwise.
798 *
799 * @since 0.1.0
800 */
801enum sp_return sp_set_config(struct sp_port *port, const struct sp_port_config *config);
802
803/**
804 * Set the baud rate for the specified serial port.
805 *
806 * @param[in] port Pointer to a port structure. Must not be NULL.
807 * @param[in] baudrate Baud rate in bits per second.
808 *
809 * @return SP_OK upon success, a negative error code otherwise.
810 *
811 * @since 0.1.0
812 */
813enum sp_return sp_set_baudrate(struct sp_port *port, int baudrate);
814
815/**
816 * Get the baud rate from a port configuration.
817 *
818 * The user should allocate a variable of type int and
819 * pass a pointer to this to receive the result.
820 *
821 * @param[in] config Pointer to a configuration structure. Must not be NULL.
822 * @param[out] baudrate_ptr Pointer to a variable to store the result. Must not be NULL.
823 *
824 * @return SP_OK upon success, a negative error code otherwise.
825 *
826 * @since 0.1.0
827 */
828enum sp_return sp_get_config_baudrate(const struct sp_port_config *config, int *baudrate_ptr);
829
830/**
831 * Set the baud rate in a port configuration.
832 *
833 * @param[in] config Pointer to a configuration structure. Must not be NULL.
834 * @param[in] baudrate Baud rate in bits per second, or -1 to retain the current setting.
835 *
836 * @return SP_OK upon success, a negative error code otherwise.
837 *
838 * @since 0.1.0
839 */
840enum sp_return sp_set_config_baudrate(struct sp_port_config *config, int baudrate);
841
842/**
843 * Set the data bits for the specified serial port.
844 *
845 * @param[in] port Pointer to a port structure. Must not be NULL.
846 * @param[in] bits Number of data bits.
847 *
848 * @return SP_OK upon success, a negative error code otherwise.
849 *
850 * @since 0.1.0
851 */
852enum sp_return sp_set_bits(struct sp_port *port, int bits);
853
854/**
855 * Get the data bits from a port configuration.
856 *
857 * The user should allocate a variable of type int and
858 * pass a pointer to this to receive the result.
859 *
860 * @param[in] config Pointer to a configuration structure. Must not be NULL.
861 * @param[out] bits_ptr Pointer to a variable to store the result. Must not be NULL.
862 *
863 * @return SP_OK upon success, a negative error code otherwise.
864 *
865 * @since 0.1.0
866 */
867enum sp_return sp_get_config_bits(const struct sp_port_config *config, int *bits_ptr);
868
869/**
870 * Set the data bits in a port configuration.
871 *
872 * @param[in] config Pointer to a configuration structure. Must not be NULL.
873 * @param[in] bits Number of data bits, or -1 to retain the current setting.
874 *
875 * @return SP_OK upon success, a negative error code otherwise.
876 *
877 * @since 0.1.0
878 */
879enum sp_return sp_set_config_bits(struct sp_port_config *config, int bits);
880
881/**
882 * Set the parity setting for the specified serial port.
883 *
884 * @param[in] port Pointer to a port structure. Must not be NULL.
885 * @param[in] parity Parity setting.
886 *
887 * @return SP_OK upon success, a negative error code otherwise.
888 *
889 * @since 0.1.0
890 */
891enum sp_return sp_set_parity(struct sp_port *port, enum sp_parity parity);
892
893/**
894 * Get the parity setting from a port configuration.
895 *
896 * The user should allocate a variable of type enum sp_parity and
897 * pass a pointer to this to receive the result.
898 *
899 * @param[in] config Pointer to a configuration structure. Must not be NULL.
900 * @param[out] parity_ptr Pointer to a variable to store the result. Must not be NULL.
901 *
902 * @return SP_OK upon success, a negative error code otherwise.
903 *
904 * @since 0.1.0
905 */
906enum sp_return sp_get_config_parity(const struct sp_port_config *config, enum sp_parity *parity_ptr);
907
908/**
909 * Set the parity setting in a port configuration.
910 *
911 * @param[in] config Pointer to a configuration structure. Must not be NULL.
912 * @param[in] parity Parity setting, or -1 to retain the current setting.
913 *
914 * @return SP_OK upon success, a negative error code otherwise.
915 *
916 * @since 0.1.0
917 */
918enum sp_return sp_set_config_parity(struct sp_port_config *config, enum sp_parity parity);
919
920/**
921 * Set the stop bits for the specified serial port.
922 *
923 * @param[in] port Pointer to a port structure. Must not be NULL.
924 * @param[in] stopbits Number of stop bits.
925 *
926 * @return SP_OK upon success, a negative error code otherwise.
927 *
928 * @since 0.1.0
929 */
930enum sp_return sp_set_stopbits(struct sp_port *port, int stopbits);
931
932/**
933 * Get the stop bits from a port configuration.
934 *
935 * The user should allocate a variable of type int and
936 * pass a pointer to this to receive the result.
937 *
938 * @param[in] config Pointer to a configuration structure. Must not be NULL.
939 * @param[out] stopbits_ptr Pointer to a variable to store the result. Must not be NULL.
940 *
941 * @return SP_OK upon success, a negative error code otherwise.
942 *
943 * @since 0.1.0
944 */
945enum sp_return sp_get_config_stopbits(const struct sp_port_config *config, int *stopbits_ptr);
946
947/**
948 * Set the stop bits in a port configuration.
949 *
950 * @param[in] config Pointer to a configuration structure. Must not be NULL.
951 * @param[in] stopbits Number of stop bits, or -1 to retain the current setting.
952 *
953 * @return SP_OK upon success, a negative error code otherwise.
954 *
955 * @since 0.1.0
956 */
957enum sp_return sp_set_config_stopbits(struct sp_port_config *config, int stopbits);
958
959/**
960 * Set the RTS pin behaviour for the specified serial port.
961 *
962 * @param[in] port Pointer to a port structure. Must not be NULL.
963 * @param[in] rts RTS pin mode.
964 *
965 * @return SP_OK upon success, a negative error code otherwise.
966 *
967 * @since 0.1.0
968 */
969enum sp_return sp_set_rts(struct sp_port *port, enum sp_rts rts);
970
971/**
972 * Get the RTS pin behaviour from a port configuration.
973 *
974 * The user should allocate a variable of type enum sp_rts and
975 * pass a pointer to this to receive the result.
976 *
977 * @param[in] config Pointer to a configuration structure. Must not be NULL.
978 * @param[out] rts_ptr Pointer to a variable to store the result. Must not be NULL.
979 *
980 * @return SP_OK upon success, a negative error code otherwise.
981 *
982 * @since 0.1.0
983 */
984enum sp_return sp_get_config_rts(const struct sp_port_config *config, enum sp_rts *rts_ptr);
985
986/**
987 * Set the RTS pin behaviour in a port configuration.
988 *
989 * @param[in] config Pointer to a configuration structure. Must not be NULL.
990 * @param[in] rts RTS pin mode, or -1 to retain the current setting.
991 *
992 * @return SP_OK upon success, a negative error code otherwise.
993 *
994 * @since 0.1.0
995 */
996enum sp_return sp_set_config_rts(struct sp_port_config *config, enum sp_rts rts);
997
998/**
999 * Set the CTS pin behaviour for the specified serial port.
1000 *
1001 * @param[in] port Pointer to a port structure. Must not be NULL.
1002 * @param[in] cts CTS pin mode.
1003 *
1004 * @return SP_OK upon success, a negative error code otherwise.
1005 *
1006 * @since 0.1.0
1007 */
1008enum sp_return sp_set_cts(struct sp_port *port, enum sp_cts cts);
1009
1010/**
1011 * Get the CTS pin behaviour from a port configuration.
1012 *
1013 * The user should allocate a variable of type enum sp_cts and
1014 * pass a pointer to this to receive the result.
1015 *
1016 * @param[in] config Pointer to a configuration structure. Must not be NULL.
1017 * @param[out] cts_ptr Pointer to a variable to store the result. Must not be NULL.
1018 *
1019 * @return SP_OK upon success, a negative error code otherwise.
1020 *
1021 * @since 0.1.0
1022 */
1023enum sp_return sp_get_config_cts(const struct sp_port_config *config, enum sp_cts *cts_ptr);
1024
1025/**
1026 * Set the CTS pin behaviour in a port configuration.
1027 *
1028 * @param[in] config Pointer to a configuration structure. Must not be NULL.
1029 * @param[in] cts CTS pin mode, or -1 to retain the current setting.
1030 *
1031 * @return SP_OK upon success, a negative error code otherwise.
1032 *
1033 * @since 0.1.0
1034 */
1035enum sp_return sp_set_config_cts(struct sp_port_config *config, enum sp_cts cts);
1036
1037/**
1038 * Set the DTR pin behaviour for the specified serial port.
1039 *
1040 * @param[in] port Pointer to a port structure. Must not be NULL.
1041 * @param[in] dtr DTR pin mode.
1042 *
1043 * @return SP_OK upon success, a negative error code otherwise.
1044 *
1045 * @since 0.1.0
1046 */
1047enum sp_return sp_set_dtr(struct sp_port *port, enum sp_dtr dtr);
1048
1049/**
1050 * Get the DTR pin behaviour from a port configuration.
1051 *
1052 * The user should allocate a variable of type enum sp_dtr and
1053 * pass a pointer to this to receive the result.
1054 *
1055 * @param[in] config Pointer to a configuration structure. Must not be NULL.
1056 * @param[out] dtr_ptr Pointer to a variable to store the result. Must not be NULL.
1057 *
1058 * @return SP_OK upon success, a negative error code otherwise.
1059 *
1060 * @since 0.1.0
1061 */
1062enum sp_return sp_get_config_dtr(const struct sp_port_config *config, enum sp_dtr *dtr_ptr);
1063
1064/**
1065 * Set the DTR pin behaviour in a port configuration.
1066 *
1067 * @param[in] config Pointer to a configuration structure. Must not be NULL.
1068 * @param[in] dtr DTR pin mode, or -1 to retain the current setting.
1069 *
1070 * @return SP_OK upon success, a negative error code otherwise.
1071 *
1072 * @since 0.1.0
1073 */
1074enum sp_return sp_set_config_dtr(struct sp_port_config *config, enum sp_dtr dtr);
1075
1076/**
1077 * Set the DSR pin behaviour for the specified serial port.
1078 *
1079 * @param[in] port Pointer to a port structure. Must not be NULL.
1080 * @param[in] dsr DSR pin mode.
1081 *
1082 * @return SP_OK upon success, a negative error code otherwise.
1083 *
1084 * @since 0.1.0
1085 */
1086enum sp_return sp_set_dsr(struct sp_port *port, enum sp_dsr dsr);
1087
1088/**
1089 * Get the DSR pin behaviour from a port configuration.
1090 *
1091 * The user should allocate a variable of type enum sp_dsr and
1092 * pass a pointer to this to receive the result.
1093 *
1094 * @param[in] config Pointer to a configuration structure. Must not be NULL.
1095 * @param[out] dsr_ptr Pointer to a variable to store the result. Must not be NULL.
1096 *
1097 * @return SP_OK upon success, a negative error code otherwise.
1098 *
1099 * @since 0.1.0
1100 */
1101enum sp_return sp_get_config_dsr(const struct sp_port_config *config, enum sp_dsr *dsr_ptr);
1102
1103/**
1104 * Set the DSR pin behaviour in a port configuration.
1105 *
1106 * @param[in] config Pointer to a configuration structure. Must not be NULL.
1107 * @param[in] dsr DSR pin mode, or -1 to retain the current setting.
1108 *
1109 * @return SP_OK upon success, a negative error code otherwise.
1110 *
1111 * @since 0.1.0
1112 */
1113enum sp_return sp_set_config_dsr(struct sp_port_config *config, enum sp_dsr dsr);
1114
1115/**
1116 * Set the XON/XOFF configuration for the specified serial port.
1117 *
1118 * @param[in] port Pointer to a port structure. Must not be NULL.
1119 * @param[in] xon_xoff XON/XOFF mode.
1120 *
1121 * @return SP_OK upon success, a negative error code otherwise.
1122 *
1123 * @since 0.1.0
1124 */
1125enum sp_return sp_set_xon_xoff(struct sp_port *port, enum sp_xonxoff xon_xoff);
1126
1127/**
1128 * Get the XON/XOFF configuration from a port configuration.
1129 *
1130 * The user should allocate a variable of type enum sp_xonxoff and
1131 * pass a pointer to this to receive the result.
1132 *
1133 * @param[in] config Pointer to a configuration structure. Must not be NULL.
1134 * @param[out] xon_xoff_ptr Pointer to a variable to store the result. Must not be NULL.
1135 *
1136 * @return SP_OK upon success, a negative error code otherwise.
1137 *
1138 * @since 0.1.0
1139 */
1140enum sp_return sp_get_config_xon_xoff(const struct sp_port_config *config, enum sp_xonxoff *xon_xoff_ptr);
1141
1142/**
1143 * Set the XON/XOFF configuration in a port configuration.
1144 *
1145 * @param[in] config Pointer to a configuration structure. Must not be NULL.
1146 * @param[in] xon_xoff XON/XOFF mode, or -1 to retain the current setting.
1147 *
1148 * @return SP_OK upon success, a negative error code otherwise.
1149 *
1150 * @since 0.1.0
1151 */
1152enum sp_return sp_set_config_xon_xoff(struct sp_port_config *config, enum sp_xonxoff xon_xoff);
1153
1154/**
1155 * Set the flow control type in a port configuration.
1156 *
1157 * This function is a wrapper that sets the RTS, CTS, DTR, DSR and
1158 * XON/XOFF settings as necessary for the specified flow control
1159 * type. For more fine-grained control of these settings, use their
1160 * individual configuration functions.
1161 *
1162 * @param[in] config Pointer to a configuration structure. Must not be NULL.
1163 * @param[in] flowcontrol Flow control setting to use.
1164 *
1165 * @return SP_OK upon success, a negative error code otherwise.
1166 *
1167 * @since 0.1.0
1168 */
1170
1171/**
1172 * Set the flow control type for the specified serial port.
1173 *
1174 * This function is a wrapper that sets the RTS, CTS, DTR, DSR and
1175 * XON/XOFF settings as necessary for the specified flow control
1176 * type. For more fine-grained control of these settings, use their
1177 * individual configuration functions.
1178 *
1179 * @param[in] port Pointer to a port structure. Must not be NULL.
1180 * @param[in] flowcontrol Flow control setting to use.
1181 *
1182 * @return SP_OK upon success, a negative error code otherwise.
1183 *
1184 * @since 0.1.0
1185 */
1186enum sp_return sp_set_flowcontrol(struct sp_port *port, enum sp_flowcontrol flowcontrol);
1187
1188/**
1189 * @}
1190 *
1191 * @defgroup Data Data handling
1192 *
1193 * Reading, writing, and flushing data.
1194 *
1195 * @{
1196 */
1197
1198/**
1199 * Read bytes from the specified serial port, blocking until complete.
1200 *
1201 * @warning If your program runs on Unix, defines its own signal handlers, and
1202 * needs to abort blocking reads when these are called, then you
1203 * should not use this function. It repeats system calls that return
1204 * with EINTR. To be able to abort a read from a signal handler, you
1205 * should implement your own blocking read using sp_nonblocking_read()
1206 * together with a blocking method that makes sense for your program.
1207 * E.g. you can obtain the file descriptor for an open port using
1208 * sp_get_port_handle() and use this to call select() or pselect(),
1209 * with appropriate arrangements to return if a signal is received.
1210 *
1211 * @param[in] port Pointer to a port structure. Must not be NULL.
1212 * @param[out] buf Buffer in which to store the bytes read. Must not be NULL.
1213 * @param[in] count Requested number of bytes to read.
1214 * @param[in] timeout_ms Timeout in milliseconds, or zero to wait indefinitely.
1215 *
1216 * @return The number of bytes read on success, or a negative error code. If
1217 * the number of bytes returned is less than that requested, the
1218 * timeout was reached before the requested number of bytes was
1219 * available. If timeout is zero, the function will always return
1220 * either the requested number of bytes or a negative error code.
1221 *
1222 * @since 0.1.0
1223 */
1224enum sp_return sp_blocking_read(struct sp_port *port, void *buf, size_t count, unsigned int timeout_ms);
1225
1226/**
1227 * Read bytes from the specified serial port, returning as soon as any data is
1228 * available.
1229 *
1230 * @warning If your program runs on Unix, defines its own signal handlers, and
1231 * needs to abort blocking reads when these are called, then you
1232 * should not use this function. It repeats system calls that return
1233 * with EINTR. To be able to abort a read from a signal handler, you
1234 * should implement your own blocking read using sp_nonblocking_read()
1235 * together with a blocking method that makes sense for your program.
1236 * E.g. you can obtain the file descriptor for an open port using
1237 * sp_get_port_handle() and use this to call select() or pselect(),
1238 * with appropriate arrangements to return if a signal is received.
1239 *
1240 * @param[in] port Pointer to a port structure. Must not be NULL.
1241 * @param[out] buf Buffer in which to store the bytes read. Must not be NULL.
1242 * @param[in] count Maximum number of bytes to read. Must not be zero.
1243 * @param[in] timeout_ms Timeout in milliseconds, or zero to wait indefinitely.
1244 *
1245 * @return The number of bytes read on success, or a negative error code. If
1246 * the result is zero, the timeout was reached before any bytes were
1247 * available. If timeout_ms is zero, the function will always return
1248 * either at least one byte, or a negative error code.
1249 *
1250 * @since 0.1.1
1251 */
1252enum sp_return sp_blocking_read_next(struct sp_port *port, void *buf, size_t count, unsigned int timeout_ms);
1253
1254/**
1255 * Read bytes from the specified serial port, without blocking.
1256 *
1257 * @param[in] port Pointer to a port structure. Must not be NULL.
1258 * @param[out] buf Buffer in which to store the bytes read. Must not be NULL.
1259 * @param[in] count Maximum number of bytes to read.
1260 *
1261 * @return The number of bytes read on success, or a negative error code. The
1262 * number of bytes returned may be any number from zero to the maximum
1263 * that was requested.
1264 *
1265 * @since 0.1.0
1266 */
1267enum sp_return sp_nonblocking_read(struct sp_port *port, void *buf, size_t count);
1268
1269/**
1270 * Write bytes to the specified serial port, blocking until complete.
1271 *
1272 * Note that this function only ensures that the accepted bytes have been
1273 * written to the OS; they may be held in driver or hardware buffers and not
1274 * yet physically transmitted. To check whether all written bytes have actually
1275 * been transmitted, use the sp_output_waiting() function. To wait until all
1276 * written bytes have actually been transmitted, use the sp_drain() function.
1277 *
1278 * @warning If your program runs on Unix, defines its own signal handlers, and
1279 * needs to abort blocking writes when these are called, then you
1280 * should not use this function. It repeats system calls that return
1281 * with EINTR. To be able to abort a write from a signal handler, you
1282 * should implement your own blocking write using sp_nonblocking_write()
1283 * together with a blocking method that makes sense for your program.
1284 * E.g. you can obtain the file descriptor for an open port using
1285 * sp_get_port_handle() and use this to call select() or pselect(),
1286 * with appropriate arrangements to return if a signal is received.
1287 *
1288 * @param[in] port Pointer to a port structure. Must not be NULL.
1289 * @param[in] buf Buffer containing the bytes to write. Must not be NULL.
1290 * @param[in] count Requested number of bytes to write.
1291 * @param[in] timeout_ms Timeout in milliseconds, or zero to wait indefinitely.
1292 *
1293 * @return The number of bytes written on success, or a negative error code.
1294 * If the number of bytes returned is less than that requested, the
1295 * timeout was reached before the requested number of bytes was
1296 * written. If timeout is zero, the function will always return
1297 * either the requested number of bytes or a negative error code. In
1298 * the event of an error there is no way to determine how many bytes
1299 * were sent before the error occurred.
1300 *
1301 * @since 0.1.0
1302 */
1303enum sp_return sp_blocking_write(struct sp_port *port, const void *buf, size_t count, unsigned int timeout_ms);
1304
1305/**
1306 * Write bytes to the specified serial port, without blocking.
1307 *
1308 * Note that this function only ensures that the accepted bytes have been
1309 * written to the OS; they may be held in driver or hardware buffers and not
1310 * yet physically transmitted. To check whether all written bytes have actually
1311 * been transmitted, use the sp_output_waiting() function. To wait until all
1312 * written bytes have actually been transmitted, use the sp_drain() function.
1313 *
1314 * @param[in] port Pointer to a port structure. Must not be NULL.
1315 * @param[in] buf Buffer containing the bytes to write. Must not be NULL.
1316 * @param[in] count Maximum number of bytes to write.
1317 *
1318 * @return The number of bytes written on success, or a negative error code.
1319 * The number of bytes returned may be any number from zero to the
1320 * maximum that was requested.
1321 *
1322 * @since 0.1.0
1323 */
1324enum sp_return sp_nonblocking_write(struct sp_port *port, const void *buf, size_t count);
1325
1326/**
1327 * Gets the number of bytes waiting in the input buffer.
1328 *
1329 * @param[in] port Pointer to a port structure. Must not be NULL.
1330 *
1331 * @return Number of bytes waiting on success, a negative error code otherwise.
1332 *
1333 * @since 0.1.0
1334 */
1336
1337/**
1338 * Gets the number of bytes waiting in the output buffer.
1339 *
1340 * @param[in] port Pointer to a port structure. Must not be NULL.
1341 *
1342 * @return Number of bytes waiting on success, a negative error code otherwise.
1343 *
1344 * @since 0.1.0
1345 */
1347
1348/**
1349 * Flush serial port buffers. Data in the selected buffer(s) is discarded.
1350 *
1351 * @param[in] port Pointer to a port structure. Must not be NULL.
1352 * @param[in] buffers Which buffer(s) to flush.
1353 *
1354 * @return SP_OK upon success, a negative error code otherwise.
1355 *
1356 * @since 0.1.0
1357 */
1358enum sp_return sp_flush(struct sp_port *port, enum sp_buffer buffers);
1359
1360/**
1361 * Wait for buffered data to be transmitted.
1362 *
1363 * @warning If your program runs on Unix, defines its own signal handlers, and
1364 * needs to abort draining the output buffer when when these are
1365 * called, then you should not use this function. It repeats system
1366 * calls that return with EINTR. To be able to abort a drain from a
1367 * signal handler, you would need to implement your own blocking
1368 * drain by polling the result of sp_output_waiting().
1369 *
1370 * @param[in] port Pointer to a port structure. Must not be NULL.
1371 *
1372 * @return SP_OK upon success, a negative error code otherwise.
1373 *
1374 * @since 0.1.0
1375 */
1376enum sp_return sp_drain(struct sp_port *port);
1377
1378/**
1379 * @}
1380 *
1381 * @defgroup Waiting Waiting
1382 *
1383 * Waiting for events and timeout handling.
1384 *
1385 * @{
1386 */
1387
1388/**
1389 * Allocate storage for a set of events.
1390 *
1391 * The user should allocate a variable of type struct sp_event_set *,
1392 * then pass a pointer to this variable to receive the result.
1393 *
1394 * The result should be freed after use by calling sp_free_event_set().
1395 *
1396 * @param[out] result_ptr If any error is returned, the variable pointed to by
1397 * result_ptr will be set to NULL. Otherwise, it will
1398 * be set to point to the event set. Must not be NULL.
1399 *
1400 * @return SP_OK upon success, a negative error code otherwise.
1401 *
1402 * @since 0.1.0
1403 */
1404enum sp_return sp_new_event_set(struct sp_event_set **result_ptr);
1405
1406/**
1407 * Add events to a struct sp_event_set for a given port.
1408 *
1409 * The port must first be opened by calling sp_open() using the same port
1410 * structure.
1411 *
1412 * After the port is closed or the port structure freed, the results may
1413 * no longer be valid.
1414 *
1415 * @param[in,out] event_set Event set to update. Must not be NULL.
1416 * @param[in] port Pointer to a port structure. Must not be NULL.
1417 * @param[in] mask Bitmask of events to be waited for.
1418 *
1419 * @return SP_OK upon success, a negative error code otherwise.
1420 *
1421 * @since 0.1.0
1422 */
1424 const struct sp_port *port, enum sp_event mask);
1425
1426/**
1427 * Wait for any of a set of events to occur.
1428 *
1429 * @param[in] event_set Event set to wait on. Must not be NULL.
1430 * @param[in] timeout_ms Timeout in milliseconds, or zero to wait indefinitely.
1431 *
1432 * @return SP_OK upon success, a negative error code otherwise.
1433 *
1434 * @since 0.1.0
1435 */
1436enum sp_return sp_wait(struct sp_event_set *event_set, unsigned int timeout_ms);
1437
1438/**
1439 * Free a structure allocated by sp_new_event_set().
1440 *
1441 * @param[in] event_set Event set to free. Must not be NULL.
1442 *
1443 * @since 0.1.0
1444 */
1445void sp_free_event_set(struct sp_event_set *event_set);
1446
1447/**
1448 * @}
1449 *
1450 * @defgroup Signals Signals
1451 *
1452 * Port signalling operations.
1453 *
1454 * @{
1455 */
1456
1457/**
1458 * Gets the status of the control signals for the specified port.
1459 *
1460 * The user should allocate a variable of type "enum sp_signal" and pass a
1461 * pointer to this variable to receive the result. The result is a bitmask
1462 * in which individual signals can be checked by bitwise OR with values of
1463 * the sp_signal enum.
1464 *
1465 * @param[in] port Pointer to a port structure. Must not be NULL.
1466 * @param[out] signal_mask Pointer to a variable to receive the result.
1467 * Must not be NULL.
1468 *
1469 * @return SP_OK upon success, a negative error code otherwise.
1470 *
1471 * @since 0.1.0
1472 */
1473enum sp_return sp_get_signals(struct sp_port *port, enum sp_signal *signal_mask);
1474
1475/**
1476 * Put the port transmit line into the break state.
1477 *
1478 * @param[in] port Pointer to a port structure. Must not be NULL.
1479 *
1480 * @return SP_OK upon success, a negative error code otherwise.
1481 *
1482 * @since 0.1.0
1483 */
1485
1486/**
1487 * Take the port transmit line out of the break state.
1488 *
1489 * @param[in] port Pointer to a port structure. Must not be NULL.
1490 *
1491 * @return SP_OK upon success, a negative error code otherwise.
1492 *
1493 * @since 0.1.0
1494 */
1495enum sp_return sp_end_break(struct sp_port *port);
1496
1497/**
1498 * @}
1499 *
1500 * @defgroup Errors Errors
1501 *
1502 * Obtaining error information.
1503 *
1504 * @{
1505 */
1506
1507/**
1508 * Get the error code for a failed operation.
1509 *
1510 * In order to obtain the correct result, this function should be called
1511 * straight after the failure, before executing any other system operations.
1512 * The result is thread-specific, and only valid when called immediately
1513 * after a previous call returning SP_ERR_FAIL.
1514 *
1515 * @return The system's numeric code for the error that caused the last
1516 * operation to fail.
1517 *
1518 * @since 0.1.0
1519 */
1521
1522/**
1523 * Get the error message for a failed operation.
1524 *
1525 * In order to obtain the correct result, this function should be called
1526 * straight after the failure, before executing other system operations.
1527 * The result is thread-specific, and only valid when called immediately
1528 * after a previous call returning SP_ERR_FAIL.
1529 *
1530 * @return The system's message for the error that caused the last
1531 * operation to fail. This string may be allocated by the function,
1532 * and should be freed after use by calling sp_free_error_message().
1533 *
1534 * @since 0.1.0
1535 */
1537
1538/**
1539 * Free an error message returned by sp_last_error_message().
1540 *
1541 * @param[in] message The error message string to free. Must not be NULL.
1542 *
1543 * @since 0.1.0
1544 */
1545void sp_free_error_message(char *message);
1546
1547/**
1548 * Set the handler function for library debugging messages.
1549 *
1550 * Debugging messages are generated by the library during each operation,
1551 * to help in diagnosing problems. The handler will be called for each
1552 * message. The handler can be set to NULL to ignore all debug messages.
1553 *
1554 * The handler function should accept a format string and variable length
1555 * argument list, in the same manner as e.g. printf().
1556 *
1557 * The default handler is sp_default_debug_handler().
1558 *
1559 * @param[in] handler The handler function to use. Can be NULL (in that case
1560 * all debug messages will be ignored).
1561 *
1562 * @since 0.1.0
1563 */
1564void sp_set_debug_handler(void (*handler)(const char *format, ...));
1565
1566/**
1567 * Default handler function for library debugging messages.
1568 *
1569 * This function prints debug messages to the standard error stream if the
1570 * environment variable LIBSERIALPORT_DEBUG is set. Otherwise, they are
1571 * ignored.
1572 *
1573 * @param[in] format The format string to use. Must not be NULL.
1574 * @param[in] ... The variable length argument list to use.
1575 *
1576 * @since 0.1.0
1577 */
1578void sp_default_debug_handler(const char *format, ...);
1579
1580/** @} */
1581
1582/**
1583 * @defgroup Versions Versions
1584 *
1585 * Version number querying functions, definitions, and macros.
1586 *
1587 * This set of API calls returns two different version numbers related
1588 * to libserialport. The "package version" is the release version number of the
1589 * libserialport tarball in the usual "major.minor.micro" format, e.g. "0.1.0".
1590 *
1591 * The "library version" is independent of that; it is the libtool version
1592 * number in the "current:revision:age" format, e.g. "2:0:0".
1593 * See http://www.gnu.org/software/libtool/manual/libtool.html#Libtool-versioning for details.
1594 *
1595 * Both version numbers (and/or individual components of them) can be
1596 * retrieved via the API calls at runtime, and/or they can be checked at
1597 * compile/preprocessor time using the respective macros.
1598 *
1599 * @{
1600 */
1601
1602/*
1603 * Package version macros (can be used for conditional compilation).
1604 */
1605
1606/** The libserialport package 'major' version number. */
1607#define SP_PACKAGE_VERSION_MAJOR 0
1608
1609/** The libserialport package 'minor' version number. */
1610#define SP_PACKAGE_VERSION_MINOR 1
1611
1612/** The libserialport package 'micro' version number. */
1613#define SP_PACKAGE_VERSION_MICRO 1
1614
1615/** The libserialport package version ("major.minor.micro") as string. */
1616#define SP_PACKAGE_VERSION_STRING "0.1.1"
1617
1618/*
1619 * Library/libtool version macros (can be used for conditional compilation).
1620 */
1621
1622/** The libserialport libtool 'current' version number. */
1623#define SP_LIB_VERSION_CURRENT 1
1624
1625/** The libserialport libtool 'revision' version number. */
1626#define SP_LIB_VERSION_REVISION 0
1627
1628/** The libserialport libtool 'age' version number. */
1629#define SP_LIB_VERSION_AGE 1
1630
1631/** The libserialport libtool version ("current:revision:age") as string. */
1632#define SP_LIB_VERSION_STRING "1:0:1"
1633
1634/**
1635 * Get the major libserialport package version number.
1636 *
1637 * @return The major package version number.
1638 *
1639 * @since 0.1.0
1640 */
1642
1643/**
1644 * Get the minor libserialport package version number.
1645 *
1646 * @return The minor package version number.
1647 *
1648 * @since 0.1.0
1649 */
1651
1652/**
1653 * Get the micro libserialport package version number.
1654 *
1655 * @return The micro package version number.
1656 *
1657 * @since 0.1.0
1658 */
1660
1661/**
1662 * Get the libserialport package version number as a string.
1663 *
1664 * @return The package version number string. The returned string is
1665 * static and thus should NOT be free'd by the caller.
1666 *
1667 * @since 0.1.0
1668 */
1670
1671/**
1672 * Get the "current" part of the libserialport library version number.
1673 *
1674 * @return The "current" library version number.
1675 *
1676 * @since 0.1.0
1677 */
1679
1680/**
1681 * Get the "revision" part of the libserialport library version number.
1682 *
1683 * @return The "revision" library version number.
1684 *
1685 * @since 0.1.0
1686 */
1688
1689/**
1690 * Get the "age" part of the libserialport library version number.
1691 *
1692 * @return The "age" library version number.
1693 *
1694 * @since 0.1.0
1695 */
1697
1698/**
1699 * Get the libserialport library version number as a string.
1700 *
1701 * @return The library version number string. The returned string is
1702 * static and thus should NOT be free'd by the caller.
1703 *
1704 * @since 0.1.0
1705 */
1707
1708/** @} */
1709
1710#ifdef __cplusplus
1711}
1712#endif
1713
1714#endif
sp_parity
Parity settings.
@ SP_PARITY_INVALID
Special value to indicate setting should be left alone.
@ SP_PARITY_EVEN
Even parity.
@ SP_PARITY_MARK
Mark parity.
@ SP_PARITY_ODD
Odd parity.
@ SP_PARITY_NONE
No parity.
@ SP_PARITY_SPACE
Space parity.
sp_mode
Port access modes.
@ SP_MODE_READ_WRITE
Open port for read and write access.
@ SP_MODE_READ
Open port for read access.
@ SP_MODE_WRITE
Open port for write access.
sp_signal
Input signals.
@ SP_SIG_RI
Ring indicator.
@ SP_SIG_DCD
Data carrier detect.
@ SP_SIG_CTS
Clear to send.
@ SP_SIG_DSR
Data set ready.
sp_rts
RTS pin behaviour.
@ SP_RTS_OFF
RTS off.
@ SP_RTS_ON
RTS on.
@ SP_RTS_FLOW_CONTROL
RTS used for flow control.
@ SP_RTS_INVALID
Special value to indicate setting should be left alone.
sp_dsr
DSR pin behaviour.
@ SP_DSR_FLOW_CONTROL
DSR used for flow control.
@ SP_DSR_INVALID
Special value to indicate setting should be left alone.
@ SP_DSR_IGNORE
DSR ignored.
sp_dtr
DTR pin behaviour.
@ SP_DTR_INVALID
Special value to indicate setting should be left alone.
@ SP_DTR_FLOW_CONTROL
DTR used for flow control.
@ SP_DTR_OFF
DTR off.
@ SP_DTR_ON
DTR on.
sp_buffer
Buffer selection.
@ SP_BUF_OUTPUT
Output buffer.
@ SP_BUF_BOTH
Both buffers.
@ SP_BUF_INPUT
Input buffer.
sp_flowcontrol
Standard flow control combinations.
@ SP_FLOWCONTROL_NONE
No flow control.
@ SP_FLOWCONTROL_DTRDSR
Hardware flow control using DTR/DSR signals.
@ SP_FLOWCONTROL_XONXOFF
Software flow control using XON/XOFF characters.
@ SP_FLOWCONTROL_RTSCTS
Hardware flow control using RTS/CTS signals.
sp_transport
Transport types.
@ SP_TRANSPORT_USB
USB serial port adapter.
@ SP_TRANSPORT_NATIVE
Native platform serial port.
@ SP_TRANSPORT_BLUETOOTH
Bluetooth serial port adapter.
sp_return
Return values.
@ SP_ERR_SUPP
The requested operation is not supported by this system or device.
@ SP_ERR_FAIL
A system error occurred while executing the operation.
@ SP_ERR_MEM
A memory allocation failed while executing the operation.
@ SP_OK
Operation completed successfully.
@ SP_ERR_ARG
Invalid arguments were passed to the function.
sp_event
Port events.
@ SP_EVENT_TX_READY
Ready to transmit new data.
@ SP_EVENT_ERROR
Error occurred.
@ SP_EVENT_RX_READY
Data received and ready to read.
sp_cts
CTS pin behaviour.
@ SP_CTS_FLOW_CONTROL
CTS used for flow control.
@ SP_CTS_INVALID
Special value to indicate setting should be left alone.
@ SP_CTS_IGNORE
CTS ignored.
sp_xonxoff
XON/XOFF flow control behaviour.
@ SP_XONXOFF_OUT
XON/XOFF enabled for output only.
@ SP_XONXOFF_DISABLED
XON/XOFF disabled.
@ SP_XONXOFF_INOUT
XON/XOFF enabled for input and output.
@ SP_XONXOFF_INVALID
Special value to indicate setting should be left alone.
@ SP_XONXOFF_IN
XON/XOFF enabled for input only.
void sp_free_port(struct sp_port *port)
Free a port structure obtained from sp_get_port_by_name() or sp_copy_port().
enum sp_return sp_get_port_by_name(const char *portname, struct sp_port **port_ptr)
Obtain a pointer to a new sp_port structure representing the named port.
enum sp_return sp_list_ports(struct sp_port ***list_ptr)
List the serial ports available on the system.
enum sp_return sp_copy_port(const struct sp_port *port, struct sp_port **copy_ptr)
Make a new copy of an sp_port structure.
void sp_free_port_list(struct sp_port **ports)
Free a port list obtained from sp_list_ports().
char * sp_get_port_usb_serial(const struct sp_port *port)
Get the USB serial number string of a USB serial adapter port.
enum sp_transport sp_get_port_transport(const struct sp_port *port)
Get the transport type used by a port.
char * sp_get_port_usb_manufacturer(const struct sp_port *port)
Get the USB manufacturer string of a USB serial adapter port.
char * sp_get_port_usb_product(const struct sp_port *port)
Get the USB product string of a USB serial adapter port.
enum sp_return sp_get_port_handle(const struct sp_port *port, void *result_ptr)
Get the operating system handle for a port.
enum sp_return sp_get_port_usb_vid_pid(const struct sp_port *port, int *usb_vid, int *usb_pid)
Get the USB Vendor ID and Product ID of a USB serial adapter port.
enum sp_return sp_close(struct sp_port *port)
Close the specified serial port.
char * sp_get_port_description(const struct sp_port *port)
Get a description for a port, to present to end user.
enum sp_return sp_open(struct sp_port *port, enum sp_mode flags)
Open the specified serial port.
enum sp_return sp_get_port_usb_bus_address(const struct sp_port *port, int *usb_bus, int *usb_address)
Get the USB bus number and address on bus of a USB serial adapter port.
char * sp_get_port_bluetooth_address(const struct sp_port *port)
Get the MAC address of a Bluetooth serial adapter port.
char * sp_get_port_name(const struct sp_port *port)
Get the name of a port.
enum sp_return sp_set_config_parity(struct sp_port_config *config, enum sp_parity parity)
Set the parity setting in a port configuration.
void sp_free_config(struct sp_port_config *config)
Free a port configuration structure.
enum sp_return sp_get_config_bits(const struct sp_port_config *config, int *bits_ptr)
Get the data bits from a port configuration.
enum sp_return sp_set_config_dtr(struct sp_port_config *config, enum sp_dtr dtr)
Set the DTR pin behaviour in a port configuration.
enum sp_return sp_get_config_stopbits(const struct sp_port_config *config, int *stopbits_ptr)
Get the stop bits from a port configuration.
enum sp_return sp_set_stopbits(struct sp_port *port, int stopbits)
Set the stop bits for the specified serial port.
enum sp_return sp_set_config_rts(struct sp_port_config *config, enum sp_rts rts)
Set the RTS pin behaviour in a port configuration.
enum sp_return sp_set_config(struct sp_port *port, const struct sp_port_config *config)
Set the configuration for the specified serial port.
enum sp_return sp_set_dsr(struct sp_port *port, enum sp_dsr dsr)
Set the DSR pin behaviour for the specified serial port.
enum sp_return sp_set_bits(struct sp_port *port, int bits)
Set the data bits for the specified serial port.
enum sp_return sp_set_config_cts(struct sp_port_config *config, enum sp_cts cts)
Set the CTS pin behaviour in a port configuration.
enum sp_return sp_new_config(struct sp_port_config **config_ptr)
Allocate a port configuration structure.
enum sp_return sp_set_xon_xoff(struct sp_port *port, enum sp_xonxoff xon_xoff)
Set the XON/XOFF configuration for the specified serial port.
enum sp_return sp_get_config_dtr(const struct sp_port_config *config, enum sp_dtr *dtr_ptr)
Get the DTR pin behaviour from a port configuration.
enum sp_return sp_set_cts(struct sp_port *port, enum sp_cts cts)
Set the CTS pin behaviour for the specified serial port.
enum sp_return sp_set_rts(struct sp_port *port, enum sp_rts rts)
Set the RTS pin behaviour for the specified serial port.
enum sp_return sp_get_config_xon_xoff(const struct sp_port_config *config, enum sp_xonxoff *xon_xoff_ptr)
Get the XON/XOFF configuration from a port configuration.
enum sp_return sp_get_config_baudrate(const struct sp_port_config *config, int *baudrate_ptr)
Get the baud rate from a port configuration.
enum sp_return sp_get_config_rts(const struct sp_port_config *config, enum sp_rts *rts_ptr)
Get the RTS pin behaviour from a port configuration.
enum sp_return sp_set_config_flowcontrol(struct sp_port_config *config, enum sp_flowcontrol flowcontrol)
Set the flow control type in a port configuration.
enum sp_return sp_set_baudrate(struct sp_port *port, int baudrate)
Set the baud rate for the specified serial port.
enum sp_return sp_get_config_cts(const struct sp_port_config *config, enum sp_cts *cts_ptr)
Get the CTS pin behaviour from a port configuration.
enum sp_return sp_get_config(struct sp_port *port, struct sp_port_config *config)
Get the current configuration of the specified serial port.
enum sp_return sp_set_config_bits(struct sp_port_config *config, int bits)
Set the data bits in a port configuration.
enum sp_return sp_get_config_parity(const struct sp_port_config *config, enum sp_parity *parity_ptr)
Get the parity setting from a port configuration.
enum sp_return sp_set_flowcontrol(struct sp_port *port, enum sp_flowcontrol flowcontrol)
Set the flow control type for the specified serial port.
enum sp_return sp_set_config_stopbits(struct sp_port_config *config, int stopbits)
Set the stop bits in a port configuration.
enum sp_return sp_set_parity(struct sp_port *port, enum sp_parity parity)
Set the parity setting for the specified serial port.
enum sp_return sp_set_config_xon_xoff(struct sp_port_config *config, enum sp_xonxoff xon_xoff)
Set the XON/XOFF configuration in a port configuration.
enum sp_return sp_set_dtr(struct sp_port *port, enum sp_dtr dtr)
Set the DTR pin behaviour for the specified serial port.
enum sp_return sp_set_config_baudrate(struct sp_port_config *config, int baudrate)
Set the baud rate in a port configuration.
enum sp_return sp_get_config_dsr(const struct sp_port_config *config, enum sp_dsr *dsr_ptr)
Get the DSR pin behaviour from a port configuration.
enum sp_return sp_set_config_dsr(struct sp_port_config *config, enum sp_dsr dsr)
Set the DSR pin behaviour in a port configuration.
enum sp_return sp_output_waiting(struct sp_port *port)
Gets the number of bytes waiting in the output buffer.
enum sp_return sp_drain(struct sp_port *port)
Wait for buffered data to be transmitted.
enum sp_return sp_nonblocking_write(struct sp_port *port, const void *buf, size_t count)
Write bytes to the specified serial port, without blocking.
enum sp_return sp_blocking_read(struct sp_port *port, void *buf, size_t count, unsigned int timeout_ms)
Read bytes from the specified serial port, blocking until complete.
enum sp_return sp_flush(struct sp_port *port, enum sp_buffer buffers)
Flush serial port buffers.
enum sp_return sp_blocking_read_next(struct sp_port *port, void *buf, size_t count, unsigned int timeout_ms)
Read bytes from the specified serial port, returning as soon as any data is available.
enum sp_return sp_nonblocking_read(struct sp_port *port, void *buf, size_t count)
Read bytes from the specified serial port, without blocking.
enum sp_return sp_input_waiting(struct sp_port *port)
Gets the number of bytes waiting in the input buffer.
enum sp_return sp_blocking_write(struct sp_port *port, const void *buf, size_t count, unsigned int timeout_ms)
Write bytes to the specified serial port, blocking until complete.
enum sp_return sp_add_port_events(struct sp_event_set *event_set, const struct sp_port *port, enum sp_event mask)
Add events to a struct sp_event_set for a given port.
enum sp_return sp_wait(struct sp_event_set *event_set, unsigned int timeout_ms)
Wait for any of a set of events to occur.
enum sp_return sp_new_event_set(struct sp_event_set **result_ptr)
Allocate storage for a set of events.
void sp_free_event_set(struct sp_event_set *event_set)
Free a structure allocated by sp_new_event_set().
enum sp_return sp_end_break(struct sp_port *port)
Take the port transmit line out of the break state.
enum sp_return sp_get_signals(struct sp_port *port, enum sp_signal *signal_mask)
Gets the status of the control signals for the specified port.
enum sp_return sp_start_break(struct sp_port *port)
Put the port transmit line into the break state.
char * sp_last_error_message(void)
Get the error message for a failed operation.
void sp_set_debug_handler(void(*handler)(const char *format,...))
Set the handler function for library debugging messages.
int sp_last_error_code(void)
Get the error code for a failed operation.
void sp_default_debug_handler(const char *format,...)
Default handler function for library debugging messages.
void sp_free_error_message(char *message)
Free an error message returned by sp_last_error_message().
const char * sp_get_lib_version_string(void)
Get the libserialport library version number as a string.
int sp_get_revision_lib_version(void)
Get the "revision" part of the libserialport library version number.
int sp_get_current_lib_version(void)
Get the "current" part of the libserialport library version number.
int sp_get_micro_package_version(void)
Get the micro libserialport package version number.
int sp_get_minor_package_version(void)
Get the minor libserialport package version number.
int sp_get_major_package_version(void)
Get the major libserialport package version number.
int sp_get_age_lib_version(void)
Get the "age" part of the libserialport library version number.
const char * sp_get_package_version_string(void)
Get the libserialport package version number as a string.
A set of handles to wait on for events.
enum sp_event * masks
Array of bitmasks indicating which events apply for each handle.
unsigned int count
Number of handles.
void * handles
Array of OS-specific handles.
An opaque structure representing a serial port.
An opaque structure representing the configuration for a serial port.