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