libserialport  0.1.1
cross-platform library for accessing serial ports
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
258 extern "C" {
259 #endif
260 
261 #include <stddef.h>
262 
263 /** Return values. */
264 enum sp_return {
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. */
275 };
276 
277 /** Port access modes. */
278 enum sp_mode {
279  /** Open port for read access. */
281  /** Open port for write access. */
283  /** Open port for read and write access. @since 0.1.1 */
285 };
286 
287 /** Port events. */
288 enum sp_event {
289  /** Data received and ready to read. */
291  /** Ready to transmit new data. */
293  /** Error occurred. */
295 };
296 
297 /** Buffer selection. */
298 enum sp_buffer {
299  /** Input buffer. */
301  /** Output buffer. */
303  /** Both buffers. */
305 };
306 
307 /** Parity settings. */
308 enum sp_parity {
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. */
321 };
322 
323 /** RTS pin behaviour. */
324 enum sp_rts {
325  /** Special value to indicate setting should be left alone. */
327  /** RTS off. */
329  /** RTS on. */
331  /** RTS used for flow control. */
333 };
334 
335 /** CTS pin behaviour. */
336 enum sp_cts {
337  /** Special value to indicate setting should be left alone. */
339  /** CTS ignored. */
341  /** CTS used for flow control. */
343 };
344 
345 /** DTR pin behaviour. */
346 enum sp_dtr {
347  /** Special value to indicate setting should be left alone. */
349  /** DTR off. */
351  /** DTR on. */
353  /** DTR used for flow control. */
355 };
356 
357 /** DSR pin behaviour. */
358 enum sp_dsr {
359  /** Special value to indicate setting should be left alone. */
361  /** DSR ignored. */
363  /** DSR used for flow control. */
365 };
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. */
379 };
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. */
391 };
392 
393 /** Input signals. */
394 enum sp_signal {
395  /** Clear to send. */
397  /** Data set ready. */
399  /** Data carrier detect. */
401  /** Ring indicator. */
403 };
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 */
417 };
418 
419 /**
420  * @struct sp_port
421  * An opaque structure representing a serial port.
422  */
423 struct sp_port;
424 
425 /**
426  * @struct sp_port_config
427  * An opaque structure representing the configuration for a serial port.
428  */
429 struct sp_port_config;
430 
431 /**
432  * @struct sp_event_set
433  * A set of handles to wait on for events.
434  */
435 struct sp_event_set {
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  */
469 enum 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  */
478 void 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  */
499 enum 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  */
518 enum 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  */
530 void 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  */
551 enum 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  */
562 enum 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  */
579 char *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  */
592 char *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  */
603 enum sp_transport sp_get_port_transport(const struct sp_port *port);
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  */
618 enum sp_return sp_get_port_usb_bus_address(const struct sp_port *port,
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  */
634 enum 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  */
647 char *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  */
660 char *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  */
673 char *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  */
686 char *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  */
718 enum 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  */
751 enum 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  */
760 void 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  */
782 enum 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  */
801 enum 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  */
813 enum 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  */
828 enum 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  */
840 enum 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  */
852 enum 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  */
867 enum 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  */
879 enum 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  */
891 enum 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  */
906 enum 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  */
918 enum 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  */
930 enum 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  */
945 enum 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  */
957 enum 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  */
969 enum 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  */
984 enum 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  */
996 enum 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  */
1008 enum 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  */
1023 enum 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  */
1035 enum 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  */
1047 enum 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  */
1062 enum 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  */
1074 enum 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  */
1086 enum 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  */
1101 enum 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  */
1113 enum 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  */
1125 enum 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  */
1140 enum 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  */
1152 enum 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  */
1169 enum sp_return sp_set_config_flowcontrol(struct sp_port_config *config, enum sp_flowcontrol flowcontrol);
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  */
1186 enum 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  */
1224 enum 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  */
1252 enum 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  */
1267 enum 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  */
1303 enum 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  */
1324 enum 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  */
1335 enum sp_return sp_input_waiting(struct sp_port *port);
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  */
1346 enum sp_return sp_output_waiting(struct sp_port *port);
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  */
1358 enum 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  */
1376 enum 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  */
1404 enum 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  */
1423 enum sp_return sp_add_port_events(struct sp_event_set *event_set,
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  */
1436 enum 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  */
1445 void 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  */
1473 enum 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  */
1484 enum sp_return sp_start_break(struct sp_port *port);
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  */
1495 enum 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  */
1520 int sp_last_error_code(void);
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  */
1536 char *sp_last_error_message(void);
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  */
1545 void 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  */
1564 void 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  */
1578 void 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  */
1669 const char *sp_get_package_version_string(void);
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  */
1678 int sp_get_current_lib_version(void);
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  */
1687 int sp_get_revision_lib_version(void);
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  */
1696 int sp_get_age_lib_version(void);
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  */
1706 const char *sp_get_lib_version_string(void);
1707 
1708 /** @} */
1709 
1710 #ifdef __cplusplus
1711 }
1712 #endif
1713 
1714 #endif
void sp_free_event_set(struct sp_event_set *event_set)
Free a structure allocated by sp_new_event_set().
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.
A system error occurred while executing the operation.
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.
CTS used for flow control.
Operation completed successfully.
Hardware flow control using DTR/DSR signals.
int sp_get_micro_package_version(void)
Get the micro libserialport package version number.
enum sp_return sp_set_stopbits(struct sp_port *port, int stopbits)
Set the stop bits for the specified serial port.
enum sp_event * masks
Array of bitmasks indicating which events apply for each handle.
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_set_config_flowcontrol(struct sp_port_config *config, enum sp_flowcontrol flowcontrol)
Set the flow control type in a port configuration.
void sp_free_error_message(char *message)
Free an error message returned by sp_last_error_message().
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_return sp_get_port_handle(const struct sp_port *port, void *result_ptr)
Get the operating system handle for a port.
Data received and ready to read.
enum sp_return sp_set_rts(struct sp_port *port, enum sp_rts rts)
Set the RTS pin behaviour for the specified serial port.
An opaque structure representing the configuration for a serial port.
A set of handles to wait on for events.
DTR on.
enum sp_return sp_flush(struct sp_port *port, enum sp_buffer buffers)
Flush serial port buffers.
Ring indicator.
char * sp_get_port_bluetooth_address(const struct sp_port *port)
Get the MAC address of a Bluetooth serial adapter 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.
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.
Open port for read and write access.
enum sp_return sp_input_waiting(struct sp_port *port)
Gets the number of bytes waiting in the input buffer.
Output buffer.
Open port for read access.
Special value to indicate setting should be left alone.
A memory allocation failed while executing the operation.
Ready to transmit new data.
enum sp_return sp_output_waiting(struct sp_port *port)
Gets the number of bytes waiting in the output buffer.
enum sp_return sp_nonblocking_read(struct sp_port *port, void *buf, size_t count)
Read bytes from the specified serial port, without blocking.
Open port for write access.
enum sp_return sp_end_break(struct sp_port *port)
Take the port transmit line out of the break state.
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_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.
void sp_set_debug_handler(void(*handler)(const char *format,...))
Set the handler function for library debugging messages.
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_new_event_set(struct sp_event_set **result_ptr)
Allocate storage for a set of events.
void sp_free_port_list(struct sp_port **ports)
Free a port list obtained from sp_list_ports().
Even parity.
DTR off.
int sp_get_major_package_version(void)
Get the major libserialport package version number.
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_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.
XON/XOFF enabled for input and output.
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.
char * sp_get_port_name(const struct sp_port *port)
Get the name of a port.
Space parity.
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_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_set_config_rts(struct sp_port_config *config, enum sp_rts rts)
Set the RTS pin behaviour in a port configuration.
char * sp_get_port_description(const struct sp_port *port)
Get a description for a port, to present to end user.
DSR ignored.
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.
The requested operation is not supported by this system or device.
sp_transport
Transport types.
enum sp_return sp_start_break(struct sp_port *port)
Put the port transmit line into the break state.
sp_return
Return values.
void * handles
Array of OS-specific handles.
RTS used for flow control.
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.
Invalid arguments were passed to the function.
Special value to indicate setting should be left alone.
sp_dtr
DTR pin behaviour.
RTS on.
No parity.
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_last_error_code(void)
Get the error code for a failed operation.
sp_signal
Input signals.
char * sp_get_port_usb_manufacturer(const struct sp_port *port)
Get the USB manufacturer string of a USB serial adapter port.
enum sp_return sp_close(struct sp_port *port)
Close the specified serial port.
enum sp_return sp_drain(struct sp_port *port)
Wait for buffered data to be transmitted.
sp_parity
Parity settings.
sp_mode
Port access modes.
int sp_get_minor_package_version(void)
Get the minor libserialport package version number.
Data set ready.
sp_rts
RTS pin behaviour.
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_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.
const char * sp_get_lib_version_string(void)
Get the libserialport library version number as a string.
unsigned int count
Number of handles.
enum sp_return sp_set_baudrate(struct sp_port *port, int baudrate)
Set the baud rate for the specified serial port.
Special value to indicate setting should be left alone.
enum sp_return sp_set_parity(struct sp_port *port, enum sp_parity parity)
Set the parity setting for the specified serial port.
XON/XOFF disabled.
XON/XOFF enabled for input only.
enum sp_return sp_open(struct sp_port *port, enum sp_mode flags)
Open the specified serial port.
char * sp_last_error_message(void)
Get the error message for a failed operation.
enum sp_return sp_get_config_baudrate(const struct sp_port_config *config, int *baudrate_ptr)
Get the baud rate from a port configuration.
USB serial port adapter.
int sp_get_age_lib_version(void)
Get the "age" part of the libserialport library version number.
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(struct sp_port *port, struct sp_port_config *config)
Get the current configuration of the specified serial port.
sp_xonxoff
XON/XOFF flow control behaviour.
Mark parity.
Special value to indicate setting should be left alone.
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_dsr(struct sp_port *port, enum sp_dsr dsr)
Set the DSR pin behaviour for the specified serial 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_default_debug_handler(const char *format,...)
Default handler function for library debugging messages.
const char * sp_get_package_version_string(void)
Get the libserialport package version number as a string.
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.
Clear to send.
Software flow control using XON/XOFF characters.
Both buffers.
sp_buffer
Buffer selection.
sp_cts
CTS pin behaviour.
XON/XOFF enabled for output only.
char * sp_get_port_usb_product(const struct sp_port *port)
Get the USB product string of a USB serial adapter port.
int sp_get_revision_lib_version(void)
Get the "revision" part of the libserialport library version number.
sp_flowcontrol
Standard flow control combinations.
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_list_ports(struct sp_port ***list_ptr)
List the serial ports available on the system.
sp_dsr
DSR pin behaviour.
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_get_config_bits(const struct sp_port_config *config, int *bits_ptr)
Get the data bits from a port configuration.
void sp_free_config(struct sp_port_config *config)
Free a port configuration structure.
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_get_config_parity(const struct sp_port_config *config, enum sp_parity *parity_ptr)
Get the parity setting from a port configuration.
Odd parity.
No flow control.
CTS ignored.
RTS off.
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.
Hardware flow control using RTS/CTS signals.
enum sp_transport sp_get_port_transport(const struct sp_port *port)
Get the transport type used by a port.
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.
Input buffer.
Data carrier detect.
sp_event
Port events.
void sp_free_port(struct sp_port *port)
Free a port structure obtained from sp_get_port_by_name() or sp_copy_port().
Native platform serial port.
Error occurred.
An opaque structure representing a serial port.
DTR used for flow control.
DSR used for flow control.
int sp_get_current_lib_version(void)
Get the "current" part of the libserialport library version number.
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.
Special value to indicate setting should be left alone.
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_set_dtr(struct sp_port *port, enum sp_dtr dtr)
Set the DTR pin behaviour for the specified serial port.