libserialport.h

00001 /* libserialport.h.  Generated from libserialport.h.in by configure.  */
00002 /*
00003  * This file is part of the libserialport project.
00004  *
00005  * Copyright (C) 2013, 2015 Martin Ling <martin-libserialport@earth.li>
00006  * Copyright (C) 2014 Uwe Hermann <uwe@hermann-uwe.de>
00007  * Copyright (C) 2014 Aurelien Jacobs <aurel@gnuage.org>
00008  *
00009  * This program is free software: you can redistribute it and/or modify
00010  * it under the terms of the GNU Lesser General Public License as
00011  * published by the Free Software Foundation, either version 3 of the
00012  * License, or (at your option) any later version.
00013  *
00014  * This program is distributed in the hope that it will be useful,
00015  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00016  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00017  * GNU General Public License for more details.
00018  *
00019  * You should have received a copy of the GNU Lesser General Public License
00020  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
00021  */
00022 
00023 /**
00024  * @mainpage libserialport API
00025  *
00026  * Introduction
00027  * ============
00028  *
00029  * libserialport is a minimal library written in C that is intended to take
00030  * care of the OS-specific details when writing software that uses serial ports.
00031  *
00032  * By writing your serial code to use libserialport, you enable it to work
00033  * transparently on any platform supported by the library.
00034  *
00035  * libserialport is an open source project released under the LGPL3+ license.
00036  *
00037  * The library is maintained by the [sigrok](http://sigrok.org/) project. See
00038  * the [libserialport homepage](http://sigrok.org/wiki/Libserialport) for the
00039  * latest information.
00040  *
00041  * Source code is maintained in git at
00042  * [git://sigrok.org/libserialport](http://sigrok.org/gitweb/?p=libserialport.git).
00043  *
00044  * Bugs are tracked at http://sigrok.org/bugzilla/.
00045  *
00046  * The library was conceived and designed by Martin Ling, is maintained by
00047  * Uwe Hermann, and has received contributions from several other developers.
00048  * See the git history for full credits.
00049  *
00050  * API information
00051  * ===============
00052  *
00053  * The API has been designed from scratch. It does not exactly resemble the
00054  * serial API of any particular operating system. Instead it aims to provide
00055  * a set of functions that can reliably be implemented across all operating
00056  * systems. These form a sufficient basis for higher level behaviour to
00057  * be implemented in a platform independent manner.
00058  *
00059  * If you are porting code written for a particular OS, you may find you need
00060  * to restructure things somewhat, or do without some specialised features.
00061  * For particular notes on porting existing code, see @ref Porting.
00062  *
00063  * The following subsections will help explain the principles of the API.
00064  *
00065  * Headers
00066  * -------
00067  *
00068  * To use libserialport functions in your code, you should include the
00069  * libserialport.h header, i.e. "#include <libserialport.h>".
00070  *
00071  * Namespace
00072  * ---------
00073  *
00074  * All identifiers defined by the public libserialport headers use the prefix
00075  * sp_ (for functions and data types) or SP_ (for macros and constants).
00076  *
00077  * Functions
00078  * ---------
00079  *
00080  * The functions provided by the library are documented in detail in
00081  * the following sections:
00082  *
00083  * - @ref Enumeration (obtaining a list of serial ports on the system)
00084  * - @ref Ports (opening, closing and getting information about ports)
00085  * - @ref Configuration (baud rate, parity, etc.)
00086  * - @ref Signals (modem control lines, breaks, etc.)
00087  * - @ref Data (reading and writing data, and buffer management)
00088  * - @ref Waiting (waiting for ports to be ready, integrating with event loops)
00089  * - @ref Errors (getting error and debugging information)
00090  *
00091  * Data structures
00092  * ---------------
00093  *
00094  * The library defines three data structures:
00095  *
00096  * - @ref sp_port, which represents a serial port.
00097  *   See @ref Enumeration.
00098  * - @ref sp_port_config, which represents a port configuration.
00099  *   See @ref Configuration.
00100  * - @ref sp_event_set, which represents a set of events.
00101  *   See @ref Waiting.
00102  *
00103  * All these structures are allocated and freed by library functions. It is
00104  * the caller's responsibility to ensure that the correct calls are made to
00105  * free allocated structures after use.
00106  *
00107  * Return codes and error handling
00108  * -------------------------------
00109  *
00110  * Most functions have return type @ref sp_return and can return only four
00111  * possible error values:
00112  *
00113  * - @ref SP_ERR_ARG means that a function was called with invalid
00114  *   arguments. This implies a bug in the caller. The arguments passed would
00115  *   be invalid regardless of the underlying OS or serial device involved.
00116  *
00117  * - @ref SP_ERR_FAIL means that the OS reported a failure. The error code or
00118  *   message provided by the OS can be obtained by calling sp_last_error_code()
00119  *   or sp_last_error_message().
00120  *
00121  * - @ref SP_ERR_SUPP indicates that there is no support for the requested
00122  *   operation in the current OS, driver or device. No error message is
00123  *   available from the OS in this case. There is either no way to request
00124  *   the operation in the first place, or libserialport does not know how to
00125  *   do so in the current version.
00126  *
00127  * - @ref SP_ERR_MEM indicates that a memory allocation failed.
00128  *
00129  * All of these error values are negative.
00130  *
00131  * Calls that succeed return @ref SP_OK, which is equal to zero. Some functions
00132  * declared @ref sp_return can also return a positive value for a successful
00133  * numeric result, e.g. sp_blocking_read() or sp_blocking_write().
00134  *
00135  * An error message is only available via sp_last_error_message() in the case
00136  * where SP_ERR_FAIL was returned by the previous function call. The error
00137  * message returned is that provided by the OS, using the current language
00138  * settings. It is an error to call sp_last_error_code() or
00139  * sp_last_error_message() except after a previous function call returned
00140  * SP_ERR_FAIL. The library does not define its own error codes or messages
00141  * to accompany other return codes.
00142  *
00143  * Thread safety
00144  * -------------
00145  *
00146  * Certain combinations of calls can be made concurrently, as follows.
00147  *
00148  * - Calls using different ports may always be made concurrently, i.e.
00149  *   it is safe for separate threads to handle their own ports.
00150  *
00151  * - Calls using the same port may be made concurrently when one call
00152  *   is a read operation and one call is a write operation, i.e. it is safe
00153  *   to use separate "reader" and "writer" threads for the same port. See
00154  *   below for which operations meet these definitions.
00155  *
00156  * Read operations:
00157  *
00158  * - sp_blocking_read()
00159  * - sp_blocking_read_next()
00160  * - sp_nonblocking_read()
00161  * - sp_input_waiting()
00162  * - sp_flush() with @ref SP_BUF_INPUT only.
00163  * - sp_wait() with @ref SP_EVENT_RX_READY only.
00164  *
00165  * Write operations:
00166  *
00167  * - sp_blocking_write()
00168  * - sp_nonblocking_write()
00169  * - sp_output_waiting()
00170  * - sp_drain()
00171  * - sp_flush() with @ref SP_BUF_OUTPUT only.
00172  * - sp_wait() with @ref SP_EVENT_TX_READY only.
00173  *
00174  * If two calls, on the same port, do not fit into one of these categories
00175  * each, then they may not be made concurrently.
00176  *
00177  * Debugging
00178  * ---------
00179  *
00180  * The library can output extensive tracing and debugging information. The
00181  * simplest way to use this is to set the environment variable
00182  * LIBSERIALPORT_DEBUG to any value; messages will then be output to the
00183  * standard error stream.
00184  *
00185  * This behaviour is implemented by a default debug message handling
00186  * callback. An alternative callback can be set using sp_set_debug_handler(),
00187  * in order to e.g. redirect the output elsewhere or filter it.
00188  *
00189  * No guarantees are made about the content of the debug output; it is chosen
00190  * to suit the needs of the developers and may change between releases.
00191  *
00192  * @anchor Porting
00193  * Porting
00194  * -------
00195  *
00196  * The following guidelines may help when porting existing OS-specific code
00197  * to use libserialport.
00198  *
00199  * ### Porting from Unix-like systems ###
00200  *
00201  * There are two main differences to note when porting code written for Unix.
00202  *
00203  * The first is that Unix traditionally provides a wide range of functionality
00204  * for dealing with serial devices at the OS level; this is exposed through the
00205  * termios API and dates to the days when serial terminals were common. If your
00206  * code relies on many of these facilities you will need to adapt it, because
00207  * libserialport provides only a raw binary channel with no special handling.
00208  *
00209  * The second relates to blocking versus non-blocking I/O behaviour. In
00210  * Unix-like systems this is normally specified by setting the O_NONBLOCK
00211  * flag on the file descriptor, affecting the semantics of subsequent read()
00212  * and write() calls.
00213  *
00214  * In libserialport, blocking and nonblocking operations are both available at
00215  * any time. If your existing code ѕets O_NONBLOCK, you should use
00216  * sp_nonblocking_read() and sp_nonblocking_write() to get the same behaviour
00217  * as your existing read() and write() calls. If it does not, you should use
00218  * sp_blocking_read() and sp_blocking_write() instead. You may also find
00219  * sp_blocking_read_next() useful, which reproduces the semantics of a blocking
00220  * read() with VTIME = 0 and VMIN = 1 set in termios.
00221  *
00222  * Finally, you should take care if your program uses custom signal handlers.
00223  * The blocking calls provided by libserialport will restart system calls that
00224  * return with EINTR, so you will need to make your own arrangements if you
00225  * need to interrupt blocking operations when your signal handlers are called.
00226  * This is not an issue if you only use the default handlers.
00227  *
00228  * ### Porting from Windows ###
00229  *
00230  * The main consideration when porting from Windows is that there is no
00231  * direct equivalent for overlapped I/O operations.
00232  *
00233  * If your program does not use overlapped I/O, you can simply use
00234  * sp_blocking_read() and sp_blocking_write() as direct equivalents for
00235  * ReadFile() and WriteFile(). You may also find sp_blocking_read_next()
00236  * useful, which reproduces the special semantics of ReadFile() with
00237  * ReadIntervalTimeout and ReadTotalTimeoutMultiplier set to MAXDWORD
00238  * and 0 < ReadTotalTimeoutConstant < MAXDWORD.
00239  *
00240  * If your program makes use of overlapped I/O to continue work while a serial
00241  * operation is in progress, then you can achieve the same results using
00242  * sp_nonblocking_read() and sp_nonblocking_write().
00243  *
00244  * Generally, overlapped I/O is combined with either waiting for completion
00245  * once there is no more background work to do (using WaitForSingleObject() or
00246  * WaitForMultipleObjects()), or periodically checking for completion with
00247  * GetOverlappedResult(). If the aim is to start a new operation for further
00248  * data once the previous one has completed, you can instead simply call the
00249  * nonblocking functions again with the next data. If you need to wait for
00250  * completion, use sp_wait() to determine when the port is ready to send or
00251  * receive further data.
00252  */
00253 
00254 #ifndef LIBSERIALPORT_LIBSERIALPORT_H
00255 #define LIBSERIALPORT_LIBSERIALPORT_H
00256 
00257 #ifdef __cplusplus
00258 extern "C" {
00259 #endif
00260 
00261 #include <stddef.h>
00262 
00263 /** Return values. */
00264 enum sp_return {
00265     /** Operation completed successfully. */
00266     SP_OK = 0,
00267     /** Invalid arguments were passed to the function. */
00268     SP_ERR_ARG = -1,
00269     /** A system error occurred while executing the operation. */
00270     SP_ERR_FAIL = -2,
00271     /** A memory allocation failed while executing the operation. */
00272     SP_ERR_MEM = -3,
00273     /** The requested operation is not supported by this system or device. */
00274     SP_ERR_SUPP = -4
00275 };
00276 
00277 /** Port access modes. */
00278 enum sp_mode {
00279     /** Open port for read access. */
00280     SP_MODE_READ = 1,
00281     /** Open port for write access. */
00282     SP_MODE_WRITE = 2,
00283     /** Open port for read and write access. @since 0.1.1 */
00284     SP_MODE_READ_WRITE = 3
00285 };
00286 
00287 /** Port events. */
00288 enum sp_event {
00289     /** Data received and ready to read. */
00290     SP_EVENT_RX_READY = 1,
00291     /** Ready to transmit new data. */
00292     SP_EVENT_TX_READY = 2,
00293     /** Error occurred. */
00294     SP_EVENT_ERROR = 4
00295 };
00296 
00297 /** Buffer selection. */
00298 enum sp_buffer {
00299     /** Input buffer. */
00300     SP_BUF_INPUT = 1,
00301     /** Output buffer. */
00302     SP_BUF_OUTPUT = 2,
00303     /** Both buffers. */
00304     SP_BUF_BOTH = 3
00305 };
00306 
00307 /** Parity settings. */
00308 enum sp_parity {
00309     /** Special value to indicate setting should be left alone. */
00310     SP_PARITY_INVALID = -1,
00311     /** No parity. */
00312     SP_PARITY_NONE = 0,
00313     /** Odd parity. */
00314     SP_PARITY_ODD = 1,
00315     /** Even parity. */
00316     SP_PARITY_EVEN = 2,
00317     /** Mark parity. */
00318     SP_PARITY_MARK = 3,
00319     /** Space parity. */
00320     SP_PARITY_SPACE = 4
00321 };
00322 
00323 /** RTS pin behaviour. */
00324 enum sp_rts {
00325     /** Special value to indicate setting should be left alone. */
00326     SP_RTS_INVALID = -1,
00327     /** RTS off. */
00328     SP_RTS_OFF = 0,
00329     /** RTS on. */
00330     SP_RTS_ON = 1,
00331     /** RTS used for flow control. */
00332     SP_RTS_FLOW_CONTROL = 2
00333 };
00334 
00335 /** CTS pin behaviour. */
00336 enum sp_cts {
00337     /** Special value to indicate setting should be left alone. */
00338     SP_CTS_INVALID = -1,
00339     /** CTS ignored. */
00340     SP_CTS_IGNORE = 0,
00341     /** CTS used for flow control. */
00342     SP_CTS_FLOW_CONTROL = 1
00343 };
00344 
00345 /** DTR pin behaviour. */
00346 enum sp_dtr {
00347     /** Special value to indicate setting should be left alone. */
00348     SP_DTR_INVALID = -1,
00349     /** DTR off. */
00350     SP_DTR_OFF = 0,
00351     /** DTR on. */
00352     SP_DTR_ON = 1,
00353     /** DTR used for flow control. */
00354     SP_DTR_FLOW_CONTROL = 2
00355 };
00356 
00357 /** DSR pin behaviour. */
00358 enum sp_dsr {
00359     /** Special value to indicate setting should be left alone. */
00360     SP_DSR_INVALID = -1,
00361     /** DSR ignored. */
00362     SP_DSR_IGNORE = 0,
00363     /** DSR used for flow control. */
00364     SP_DSR_FLOW_CONTROL = 1
00365 };
00366 
00367 /** XON/XOFF flow control behaviour. */
00368 enum sp_xonxoff {
00369     /** Special value to indicate setting should be left alone. */
00370     SP_XONXOFF_INVALID = -1,
00371     /** XON/XOFF disabled. */
00372     SP_XONXOFF_DISABLED = 0,
00373     /** XON/XOFF enabled for input only. */
00374     SP_XONXOFF_IN = 1,
00375     /** XON/XOFF enabled for output only. */
00376     SP_XONXOFF_OUT = 2,
00377     /** XON/XOFF enabled for input and output. */
00378     SP_XONXOFF_INOUT = 3
00379 };
00380 
00381 /** Standard flow control combinations. */
00382 enum sp_flowcontrol {
00383     /** No flow control. */
00384     SP_FLOWCONTROL_NONE = 0,
00385     /** Software flow control using XON/XOFF characters. */
00386     SP_FLOWCONTROL_XONXOFF = 1,
00387     /** Hardware flow control using RTS/CTS signals. */
00388     SP_FLOWCONTROL_RTSCTS = 2,
00389     /** Hardware flow control using DTR/DSR signals. */
00390     SP_FLOWCONTROL_DTRDSR = 3
00391 };
00392 
00393 /** Input signals. */
00394 enum sp_signal {
00395     /** Clear to send. */
00396     SP_SIG_CTS = 1,
00397     /** Data set ready. */
00398     SP_SIG_DSR = 2,
00399     /** Data carrier detect. */
00400     SP_SIG_DCD = 4,
00401     /** Ring indicator. */
00402     SP_SIG_RI = 8
00403 };
00404 
00405 /**
00406  * Transport types.
00407  *
00408  * @since 0.1.1
00409  */
00410 enum sp_transport {
00411     /** Native platform serial port. @since 0.1.1 */
00412     SP_TRANSPORT_NATIVE,
00413     /** USB serial port adapter. @since 0.1.1 */
00414     SP_TRANSPORT_USB,
00415     /** Bluetooth serial port adapter. @since 0.1.1 */
00416     SP_TRANSPORT_BLUETOOTH
00417 };
00418 
00419 /**
00420  * @struct sp_port
00421  * An opaque structure representing a serial port.
00422  */
00423 struct sp_port;
00424 
00425 /**
00426  * @struct sp_port_config
00427  * An opaque structure representing the configuration for a serial port.
00428  */
00429 struct sp_port_config;
00430 
00431 /**
00432  * @struct sp_event_set
00433  * A set of handles to wait on for events.
00434  */
00435 struct sp_event_set {
00436     /** Array of OS-specific handles. */
00437     void *handles;
00438     /** Array of bitmasks indicating which events apply for each handle. */
00439     enum sp_event *masks;
00440     /** Number of handles. */
00441     unsigned int count;
00442 };
00443 
00444 /**
00445  * @defgroup Enumeration Port enumeration
00446  *
00447  * Enumerating the serial ports of a system.
00448  *
00449  * @{
00450  */
00451 
00452 /**
00453  * Obtain a pointer to a new sp_port structure representing the named port.
00454  *
00455  * The user should allocate a variable of type "struct sp_port *" and pass a
00456  * pointer to this to receive the result.
00457  *
00458  * The result should be freed after use by calling sp_free_port().
00459  *
00460  * @param[in] portname The OS-specific name of a serial port. Must not be NULL.
00461  * @param[out] port_ptr If any error is returned, the variable pointed to by
00462  *                      port_ptr will be set to NULL. Otherwise, it will be set
00463  *                      to point to the newly allocated port. Must not be NULL.
00464  *
00465  * @return SP_OK upon success, a negative error code otherwise.
00466  *
00467  * @since 0.1.0
00468  */
00469 enum sp_return sp_get_port_by_name(const char *portname, struct sp_port **port_ptr);
00470 
00471 /**
00472  * Free a port structure obtained from sp_get_port_by_name() or sp_copy_port().
00473  *
00474  * @param[in] port Pointer to a port structure. Must not be NULL.
00475  *
00476  * @since 0.1.0
00477  */
00478 void sp_free_port(struct sp_port *port);
00479 
00480 /**
00481  * List the serial ports available on the system.
00482  *
00483  * The result obtained is an array of pointers to sp_port structures,
00484  * terminated by a NULL. The user should allocate a variable of type
00485  * "struct sp_port **" and pass a pointer to this to receive the result.
00486  *
00487  * The result should be freed after use by calling sp_free_port_list().
00488  * If a port from the list is to be used after freeing the list, it must be
00489  * copied first using sp_copy_port().
00490  *
00491  * @param[out] list_ptr If any error is returned, the variable pointed to by
00492  *                      list_ptr will be set to NULL. Otherwise, it will be set
00493  *                      to point to the newly allocated array. Must not be NULL.
00494  *
00495  * @return SP_OK upon success, a negative error code otherwise.
00496  *
00497  * @since 0.1.0
00498  */
00499 enum sp_return sp_list_ports(struct sp_port ***list_ptr);
00500 
00501 /**
00502  * Make a new copy of an sp_port structure.
00503  *
00504  * The user should allocate a variable of type "struct sp_port *" and pass a
00505  * pointer to this to receive the result.
00506  *
00507  * The copy should be freed after use by calling sp_free_port().
00508  *
00509  * @param[in] port Pointer to a port structure. Must not be NULL.
00510  * @param[out] copy_ptr If any error is returned, the variable pointed to by
00511  *                      copy_ptr will be set to NULL. Otherwise, it will be set
00512  *                      to point to the newly allocated copy. Must not be NULL.
00513  *
00514  * @return SP_OK upon success, a negative error code otherwise.
00515  *
00516  * @since 0.1.0
00517  */
00518 enum sp_return sp_copy_port(const struct sp_port *port, struct sp_port **copy_ptr);
00519 
00520 /**
00521  * Free a port list obtained from sp_list_ports().
00522  *
00523  * This will also free all the sp_port structures referred to from the list;
00524  * any that are to be retained must be copied first using sp_copy_port().
00525  *
00526  * @param[in] ports Pointer to a list of port structures. Must not be NULL.
00527  *
00528  * @since 0.1.0
00529  */
00530 void sp_free_port_list(struct sp_port **ports);
00531 
00532 /**
00533  * @}
00534  * @defgroup Ports Port handling
00535  *
00536  * Opening, closing and querying ports.
00537  *
00538  * @{
00539  */
00540 
00541 /**
00542  * Open the specified serial port.
00543  *
00544  * @param[in] port Pointer to a port structure. Must not be NULL.
00545  * @param[in] flags Flags to use when opening the serial port.
00546  *
00547  * @return SP_OK upon success, a negative error code otherwise.
00548  *
00549  * @since 0.1.0
00550  */
00551 enum sp_return sp_open(struct sp_port *port, enum sp_mode flags);
00552 
00553 /**
00554  * Close the specified serial port.
00555  *
00556  * @param[in] port Pointer to a port structure. Must not be NULL.
00557  *
00558  * @return SP_OK upon success, a negative error code otherwise.
00559  *
00560  * @since 0.1.0
00561  */
00562 enum sp_return sp_close(struct sp_port *port);
00563 
00564 /**
00565  * Get the name of a port.
00566  *
00567  * The name returned is whatever is normally used to refer to a port on the
00568  * current operating system; e.g. for Windows it will usually be a "COMn"
00569  * device name, and for Unix it will be a device path beginning with "/dev/".
00570  *
00571  * @param[in] port Pointer to a port structure. Must not be NULL.
00572  *
00573  * @return The port name, or NULL if an invalid port is passed. The name
00574  *         string is part of the port structure and may not be used after
00575  *         the port structure has been freed.
00576  *
00577  * @since 0.1.0
00578  */
00579 char *sp_get_port_name(const struct sp_port *port);
00580 
00581 /**
00582  * Get a description for a port, to present to end user.
00583  *
00584  * @param[in] port Pointer to a port structure. Must not be NULL.
00585  *
00586  * @return The port description, or NULL if an invalid port is passed.
00587  *         The description string is part of the port structure and may not
00588  *         be used after the port structure has been freed.
00589  *
00590  * @since 0.1.1
00591  */
00592 char *sp_get_port_description(const struct sp_port *port);
00593 
00594 /**
00595  * Get the transport type used by a port.
00596  *
00597  * @param[in] port Pointer to a port structure. Must not be NULL.
00598  *
00599  * @return The port transport type.
00600  *
00601  * @since 0.1.1
00602  */
00603 enum sp_transport sp_get_port_transport(const struct sp_port *port);
00604 
00605 /**
00606  * Get the USB bus number and address on bus of a USB serial adapter port.
00607  *
00608  * @param[in] port Pointer to a port structure. Must not be NULL.
00609  * @param[out] usb_bus Pointer to a variable to store the USB bus.
00610  *                     Can be NULL (in that case it will be ignored).
00611  * @param[out] usb_address Pointer to a variable to store the USB address.
00612  *                         Can be NULL (in that case it will be ignored).
00613  *
00614  * @return SP_OK upon success, a negative error code otherwise.
00615  *
00616  * @since 0.1.1
00617  */
00618 enum sp_return sp_get_port_usb_bus_address(const struct sp_port *port,
00619                                            int *usb_bus, int *usb_address);
00620 
00621 /**
00622  * Get the USB Vendor ID and Product ID of a USB serial adapter port.
00623  *
00624  * @param[in] port Pointer to a port structure. Must not be NULL.
00625  * @param[out] usb_vid Pointer to a variable to store the USB VID.
00626  *                     Can be NULL (in that case it will be ignored).
00627  * @param[out] usb_pid Pointer to a variable to store the USB PID.
00628  *                     Can be NULL (in that case it will be ignored).
00629  *
00630  * @return SP_OK upon success, a negative error code otherwise.
00631  *
00632  * @since 0.1.1
00633  */
00634 enum sp_return sp_get_port_usb_vid_pid(const struct sp_port *port, int *usb_vid, int *usb_pid);
00635 
00636 /**
00637  * Get the USB manufacturer string of a USB serial adapter port.
00638  *
00639  * @param[in] port Pointer to a port structure. Must not be NULL.
00640  *
00641  * @return The port manufacturer string, or NULL if an invalid port is passed.
00642  *         The manufacturer string is part of the port structure and may not
00643  *         be used after the port structure has been freed.
00644  *
00645  * @since 0.1.1
00646  */
00647 char *sp_get_port_usb_manufacturer(const struct sp_port *port);
00648 
00649 /**
00650  * Get the USB product string of a USB serial adapter port.
00651  *
00652  * @param[in] port Pointer to a port structure. Must not be NULL.
00653  *
00654  * @return The port product string, or NULL if an invalid port is passed.
00655  *         The product string is part of the port structure and may not be
00656  *         used after the port structure has been freed.
00657  *
00658  * @since 0.1.1
00659  */
00660 char *sp_get_port_usb_product(const struct sp_port *port);
00661 
00662 /**
00663  * Get the USB serial number string of a USB serial adapter port.
00664  *
00665  * @param[in] port Pointer to a port structure. Must not be NULL.
00666  *
00667  * @return The port serial number, or NULL if an invalid port is passed.
00668  *         The serial number string is part of the port structure and may
00669  *         not be used after the port structure has been freed.
00670  *
00671  * @since 0.1.1
00672  */
00673 char *sp_get_port_usb_serial(const struct sp_port *port);
00674 
00675 /**
00676  * Get the MAC address of a Bluetooth serial adapter port.
00677  *
00678  * @param[in] port Pointer to a port structure. Must not be NULL.
00679  *
00680  * @return The port MAC address, or NULL if an invalid port is passed.
00681  *         The MAC address string is part of the port structure and may not
00682  *         be used after the port structure has been freed.
00683  *
00684  * @since 0.1.1
00685  */
00686 char *sp_get_port_bluetooth_address(const struct sp_port *port);
00687 
00688 /**
00689  * Get the operating system handle for a port.
00690  *
00691  * The type of the handle depends on the operating system. On Unix based
00692  * systems, the handle is a file descriptor of type "int". On Windows, the
00693  * handle is of type "HANDLE". The user should allocate a variable of the
00694  * appropriate type and pass a pointer to this to receive the result.
00695  *
00696  * To obtain a valid handle, the port must first be opened by calling
00697  * sp_open() using the same port structure.
00698  *
00699  * After the port is closed or the port structure freed, the handle may
00700  * no longer be valid.
00701  *
00702  * @warning This feature is provided so that programs may make use of
00703  *          OS-specific functionality where desired. Doing so obviously
00704  *          comes at a cost in portability. It also cannot be guaranteed
00705  *          that direct usage of the OS handle will not conflict with the
00706  *          library's own usage of the port. Be careful.
00707  *
00708  * @param[in] port Pointer to a port structure. Must not be NULL.
00709  * @param[out] result_ptr If any error is returned, the variable pointed to by
00710  *                        result_ptr will have unknown contents and should not
00711  *                        be used. Otherwise, it will be set to point to the
00712  *                        OS handle. Must not be NULL.
00713  *
00714  * @return SP_OK upon success, a negative error code otherwise.
00715  *
00716  * @since 0.1.0
00717  */
00718 enum sp_return sp_get_port_handle(const struct sp_port *port, void *result_ptr);
00719 
00720 /**
00721  * @}
00722  *
00723  * @defgroup Configuration Configuration
00724  *
00725  * Setting and querying serial port parameters.
00726  * @{
00727  */
00728 
00729 /**
00730  * Allocate a port configuration structure.
00731  *
00732  * The user should allocate a variable of type "struct sp_port_config *" and
00733  * pass a pointer to this to receive the result. The variable will be updated
00734  * to point to the new configuration structure. The structure is opaque and
00735  * must be accessed via the functions provided.
00736  *
00737  * All parameters in the structure will be initialised to special values which
00738  * are ignored by sp_set_config().
00739  *
00740  * The structure should be freed after use by calling sp_free_config().
00741  *
00742  * @param[out] config_ptr If any error is returned, the variable pointed to by
00743  *                        config_ptr will be set to NULL. Otherwise, it will
00744  *                        be set to point to the allocated config structure.
00745  *                        Must not be NULL.
00746  *
00747  * @return SP_OK upon success, a negative error code otherwise.
00748  *
00749  * @since 0.1.0
00750  */
00751 enum sp_return sp_new_config(struct sp_port_config **config_ptr);
00752 
00753 /**
00754  * Free a port configuration structure.
00755  *
00756  * @param[in] config Pointer to a configuration structure. Must not be NULL.
00757  *
00758  * @since 0.1.0
00759  */
00760 void sp_free_config(struct sp_port_config *config);
00761 
00762 /**
00763  * Get the current configuration of the specified serial port.
00764  *
00765  * The user should allocate a configuration structure using sp_new_config()
00766  * and pass this as the config parameter. The configuration structure will
00767  * be updated with the port configuration.
00768  *
00769  * Any parameters that are configured with settings not recognised or
00770  * supported by libserialport, will be set to special values that are
00771  * ignored by sp_set_config().
00772  *
00773  * @param[in] port Pointer to a port structure. Must not be NULL.
00774  * @param[out] config Pointer to a configuration structure that will hold
00775  *                    the result. Upon errors the contents of the config
00776  *                    struct will not be changed. Must not be NULL.
00777  *
00778  * @return SP_OK upon success, a negative error code otherwise.
00779  *
00780  * @since 0.1.0
00781  */
00782 enum sp_return sp_get_config(struct sp_port *port, struct sp_port_config *config);
00783 
00784 /**
00785  * Set the configuration for the specified serial port.
00786  *
00787  * For each parameter in the configuration, there is a special value (usually
00788  * -1, but see the documentation for each field). These values will be ignored
00789  * and the corresponding setting left unchanged on the port.
00790  *
00791  * Upon errors, the configuration of the serial port is unknown since
00792  * partial/incomplete config updates may have happened.
00793  *
00794  * @param[in] port Pointer to a port structure. Must not be NULL.
00795  * @param[in] config Pointer to a configuration structure. Must not be NULL.
00796  *
00797  * @return SP_OK upon success, a negative error code otherwise.
00798  *
00799  * @since 0.1.0
00800  */
00801 enum sp_return sp_set_config(struct sp_port *port, const struct sp_port_config *config);
00802 
00803 /**
00804  * Set the baud rate for the specified serial port.
00805  *
00806  * @param[in] port Pointer to a port structure. Must not be NULL.
00807  * @param[in] baudrate Baud rate in bits per second.
00808  *
00809  * @return SP_OK upon success, a negative error code otherwise.
00810  *
00811  * @since 0.1.0
00812  */
00813 enum sp_return sp_set_baudrate(struct sp_port *port, int baudrate);
00814 
00815 /**
00816  * Get the baud rate from a port configuration.
00817  *
00818  * The user should allocate a variable of type int and
00819  * pass a pointer to this to receive the result.
00820  *
00821  * @param[in] config Pointer to a configuration structure. Must not be NULL.
00822  * @param[out] baudrate_ptr Pointer to a variable to store the result. Must not be NULL.
00823  *
00824  * @return SP_OK upon success, a negative error code otherwise.
00825  *
00826  * @since 0.1.0
00827  */
00828 enum sp_return sp_get_config_baudrate(const struct sp_port_config *config, int *baudrate_ptr);
00829 
00830 /**
00831  * Set the baud rate in a port configuration.
00832  *
00833  * @param[in] config Pointer to a configuration structure. Must not be NULL.
00834  * @param[in] baudrate Baud rate in bits per second, or -1 to retain the current setting.
00835  *
00836  * @return SP_OK upon success, a negative error code otherwise.
00837  *
00838  * @since 0.1.0
00839  */
00840 enum sp_return sp_set_config_baudrate(struct sp_port_config *config, int baudrate);
00841 
00842 /**
00843  * Set the data bits for the specified serial port.
00844  *
00845  * @param[in] port Pointer to a port structure. Must not be NULL.
00846  * @param[in] bits Number of data bits.
00847  *
00848  * @return SP_OK upon success, a negative error code otherwise.
00849  *
00850  * @since 0.1.0
00851  */
00852 enum sp_return sp_set_bits(struct sp_port *port, int bits);
00853 
00854 /**
00855  * Get the data bits from a port configuration.
00856  *
00857  * The user should allocate a variable of type int and
00858  * pass a pointer to this to receive the result.
00859  *
00860  * @param[in] config Pointer to a configuration structure. Must not be NULL.
00861  * @param[out] bits_ptr Pointer to a variable to store the result. Must not be NULL.
00862  *
00863  * @return SP_OK upon success, a negative error code otherwise.
00864  *
00865  * @since 0.1.0
00866  */
00867 enum sp_return sp_get_config_bits(const struct sp_port_config *config, int *bits_ptr);
00868 
00869 /**
00870  * Set the data bits in a port configuration.
00871  *
00872  * @param[in] config Pointer to a configuration structure. Must not be NULL.
00873  * @param[in] bits Number of data bits, or -1 to retain the current setting.
00874  *
00875  * @return SP_OK upon success, a negative error code otherwise.
00876  *
00877  * @since 0.1.0
00878  */
00879 enum sp_return sp_set_config_bits(struct sp_port_config *config, int bits);
00880 
00881 /**
00882  * Set the parity setting for the specified serial port.
00883  *
00884  * @param[in] port Pointer to a port structure. Must not be NULL.
00885  * @param[in] parity Parity setting.
00886  *
00887  * @return SP_OK upon success, a negative error code otherwise.
00888  *
00889  * @since 0.1.0
00890  */
00891 enum sp_return sp_set_parity(struct sp_port *port, enum sp_parity parity);
00892 
00893 /**
00894  * Get the parity setting from a port configuration.
00895  *
00896  * The user should allocate a variable of type enum sp_parity and
00897  * pass a pointer to this to receive the result.
00898  *
00899  * @param[in] config Pointer to a configuration structure. Must not be NULL.
00900  * @param[out] parity_ptr Pointer to a variable to store the result. Must not be NULL.
00901  *
00902  * @return SP_OK upon success, a negative error code otherwise.
00903  *
00904  * @since 0.1.0
00905  */
00906 enum sp_return sp_get_config_parity(const struct sp_port_config *config, enum sp_parity *parity_ptr);
00907 
00908 /**
00909  * Set the parity setting in a port configuration.
00910  *
00911  * @param[in] config Pointer to a configuration structure. Must not be NULL.
00912  * @param[in] parity Parity setting, or -1 to retain the current setting.
00913  *
00914  * @return SP_OK upon success, a negative error code otherwise.
00915  *
00916  * @since 0.1.0
00917  */
00918 enum sp_return sp_set_config_parity(struct sp_port_config *config, enum sp_parity parity);
00919 
00920 /**
00921  * Set the stop bits for the specified serial port.
00922  *
00923  * @param[in] port Pointer to a port structure. Must not be NULL.
00924  * @param[in] stopbits Number of stop bits.
00925  *
00926  * @return SP_OK upon success, a negative error code otherwise.
00927  *
00928  * @since 0.1.0
00929  */
00930 enum sp_return sp_set_stopbits(struct sp_port *port, int stopbits);
00931 
00932 /**
00933  * Get the stop bits from a port configuration.
00934  *
00935  * The user should allocate a variable of type int and
00936  * pass a pointer to this to receive the result.
00937  *
00938  * @param[in] config Pointer to a configuration structure. Must not be NULL.
00939  * @param[out] stopbits_ptr Pointer to a variable to store the result. Must not be NULL.
00940  *
00941  * @return SP_OK upon success, a negative error code otherwise.
00942  *
00943  * @since 0.1.0
00944  */
00945 enum sp_return sp_get_config_stopbits(const struct sp_port_config *config, int *stopbits_ptr);
00946 
00947 /**
00948  * Set the stop bits in a port configuration.
00949  *
00950  * @param[in] config Pointer to a configuration structure. Must not be NULL.
00951  * @param[in] stopbits Number of stop bits, or -1 to retain the current setting.
00952  *
00953  * @return SP_OK upon success, a negative error code otherwise.
00954  *
00955  * @since 0.1.0
00956  */
00957 enum sp_return sp_set_config_stopbits(struct sp_port_config *config, int stopbits);
00958 
00959 /**
00960  * Set the RTS pin behaviour for the specified serial port.
00961  *
00962  * @param[in] port Pointer to a port structure. Must not be NULL.
00963  * @param[in] rts RTS pin mode.
00964  *
00965  * @return SP_OK upon success, a negative error code otherwise.
00966  *
00967  * @since 0.1.0
00968  */
00969 enum sp_return sp_set_rts(struct sp_port *port, enum sp_rts rts);
00970 
00971 /**
00972  * Get the RTS pin behaviour from a port configuration.
00973  *
00974  * The user should allocate a variable of type enum sp_rts and
00975  * pass a pointer to this to receive the result.
00976  *
00977  * @param[in] config Pointer to a configuration structure. Must not be NULL.
00978  * @param[out] rts_ptr Pointer to a variable to store the result. Must not be NULL.
00979  *
00980  * @return SP_OK upon success, a negative error code otherwise.
00981  *
00982  * @since 0.1.0
00983  */
00984 enum sp_return sp_get_config_rts(const struct sp_port_config *config, enum sp_rts *rts_ptr);
00985 
00986 /**
00987  * Set the RTS pin behaviour in a port configuration.
00988  *
00989  * @param[in] config Pointer to a configuration structure. Must not be NULL.
00990  * @param[in] rts RTS pin mode, or -1 to retain the current setting.
00991  *
00992  * @return SP_OK upon success, a negative error code otherwise.
00993  *
00994  * @since 0.1.0
00995  */
00996 enum sp_return sp_set_config_rts(struct sp_port_config *config, enum sp_rts rts);
00997 
00998 /**
00999  * Set the CTS pin behaviour for the specified serial port.
01000  *
01001  * @param[in] port Pointer to a port structure. Must not be NULL.
01002  * @param[in] cts CTS pin mode.
01003  *
01004  * @return SP_OK upon success, a negative error code otherwise.
01005  *
01006  * @since 0.1.0
01007  */
01008 enum sp_return sp_set_cts(struct sp_port *port, enum sp_cts cts);
01009 
01010 /**
01011  * Get the CTS pin behaviour from a port configuration.
01012  *
01013  * The user should allocate a variable of type enum sp_cts and
01014  * pass a pointer to this to receive the result.
01015  *
01016  * @param[in] config Pointer to a configuration structure. Must not be NULL.
01017  * @param[out] cts_ptr Pointer to a variable to store the result. Must not be NULL.
01018  *
01019  * @return SP_OK upon success, a negative error code otherwise.
01020  *
01021  * @since 0.1.0
01022  */
01023 enum sp_return sp_get_config_cts(const struct sp_port_config *config, enum sp_cts *cts_ptr);
01024 
01025 /**
01026  * Set the CTS pin behaviour in a port configuration.
01027  *
01028  * @param[in] config Pointer to a configuration structure. Must not be NULL.
01029  * @param[in] cts CTS pin mode, or -1 to retain the current setting.
01030  *
01031  * @return SP_OK upon success, a negative error code otherwise.
01032  *
01033  * @since 0.1.0
01034  */
01035 enum sp_return sp_set_config_cts(struct sp_port_config *config, enum sp_cts cts);
01036 
01037 /**
01038  * Set the DTR pin behaviour for the specified serial port.
01039  *
01040  * @param[in] port Pointer to a port structure. Must not be NULL.
01041  * @param[in] dtr DTR pin mode.
01042  *
01043  * @return SP_OK upon success, a negative error code otherwise.
01044  *
01045  * @since 0.1.0
01046  */
01047 enum sp_return sp_set_dtr(struct sp_port *port, enum sp_dtr dtr);
01048 
01049 /**
01050  * Get the DTR pin behaviour from a port configuration.
01051  *
01052  * The user should allocate a variable of type enum sp_dtr and
01053  * pass a pointer to this to receive the result.
01054  *
01055  * @param[in] config Pointer to a configuration structure. Must not be NULL.
01056  * @param[out] dtr_ptr Pointer to a variable to store the result. Must not be NULL.
01057  *
01058  * @return SP_OK upon success, a negative error code otherwise.
01059  *
01060  * @since 0.1.0
01061  */
01062 enum sp_return sp_get_config_dtr(const struct sp_port_config *config, enum sp_dtr *dtr_ptr);
01063 
01064 /**
01065  * Set the DTR pin behaviour in a port configuration.
01066  *
01067  * @param[in] config Pointer to a configuration structure. Must not be NULL.
01068  * @param[in] dtr DTR pin mode, or -1 to retain the current setting.
01069  *
01070  * @return SP_OK upon success, a negative error code otherwise.
01071  *
01072  * @since 0.1.0
01073  */
01074 enum sp_return sp_set_config_dtr(struct sp_port_config *config, enum sp_dtr dtr);
01075 
01076 /**
01077  * Set the DSR pin behaviour for the specified serial port.
01078  *
01079  * @param[in] port Pointer to a port structure. Must not be NULL.
01080  * @param[in] dsr DSR pin mode.
01081  *
01082  * @return SP_OK upon success, a negative error code otherwise.
01083  *
01084  * @since 0.1.0
01085  */
01086 enum sp_return sp_set_dsr(struct sp_port *port, enum sp_dsr dsr);
01087 
01088 /**
01089  * Get the DSR pin behaviour from a port configuration.
01090  *
01091  * The user should allocate a variable of type enum sp_dsr and
01092  * pass a pointer to this to receive the result.
01093  *
01094  * @param[in] config Pointer to a configuration structure. Must not be NULL.
01095  * @param[out] dsr_ptr Pointer to a variable to store the result. Must not be NULL.
01096  *
01097  * @return SP_OK upon success, a negative error code otherwise.
01098  *
01099  * @since 0.1.0
01100  */
01101 enum sp_return sp_get_config_dsr(const struct sp_port_config *config, enum sp_dsr *dsr_ptr);
01102 
01103 /**
01104  * Set the DSR pin behaviour in a port configuration.
01105  *
01106  * @param[in] config Pointer to a configuration structure. Must not be NULL.
01107  * @param[in] dsr DSR pin mode, or -1 to retain the current setting.
01108  *
01109  * @return SP_OK upon success, a negative error code otherwise.
01110  *
01111  * @since 0.1.0
01112  */
01113 enum sp_return sp_set_config_dsr(struct sp_port_config *config, enum sp_dsr dsr);
01114 
01115 /**
01116  * Set the XON/XOFF configuration for the specified serial port.
01117  *
01118  * @param[in] port Pointer to a port structure. Must not be NULL.
01119  * @param[in] xon_xoff XON/XOFF mode.
01120  *
01121  * @return SP_OK upon success, a negative error code otherwise.
01122  *
01123  * @since 0.1.0
01124  */
01125 enum sp_return sp_set_xon_xoff(struct sp_port *port, enum sp_xonxoff xon_xoff);
01126 
01127 /**
01128  * Get the XON/XOFF configuration from a port configuration.
01129  *
01130  * The user should allocate a variable of type enum sp_xonxoff and
01131  * pass a pointer to this to receive the result.
01132  *
01133  * @param[in] config Pointer to a configuration structure. Must not be NULL.
01134  * @param[out] xon_xoff_ptr Pointer to a variable to store the result. Must not be NULL.
01135  *
01136  * @return SP_OK upon success, a negative error code otherwise.
01137  *
01138  * @since 0.1.0
01139  */
01140 enum sp_return sp_get_config_xon_xoff(const struct sp_port_config *config, enum sp_xonxoff *xon_xoff_ptr);
01141 
01142 /**
01143  * Set the XON/XOFF configuration in a port configuration.
01144  *
01145  * @param[in] config Pointer to a configuration structure. Must not be NULL.
01146  * @param[in] xon_xoff XON/XOFF mode, or -1 to retain the current setting.
01147  *
01148  * @return SP_OK upon success, a negative error code otherwise.
01149  *
01150  * @since 0.1.0
01151  */
01152 enum sp_return sp_set_config_xon_xoff(struct sp_port_config *config, enum sp_xonxoff xon_xoff);
01153 
01154 /**
01155  * Set the flow control type in a port configuration.
01156  *
01157  * This function is a wrapper that sets the RTS, CTS, DTR, DSR and
01158  * XON/XOFF settings as necessary for the specified flow control
01159  * type. For more fine-grained control of these settings, use their
01160  * individual configuration functions.
01161  *
01162  * @param[in] config Pointer to a configuration structure. Must not be NULL.
01163  * @param[in] flowcontrol Flow control setting to use.
01164  *
01165  * @return SP_OK upon success, a negative error code otherwise.
01166  *
01167  * @since 0.1.0
01168  */
01169 enum sp_return sp_set_config_flowcontrol(struct sp_port_config *config, enum sp_flowcontrol flowcontrol);
01170 
01171 /**
01172  * Set the flow control type for the specified serial port.
01173  *
01174  * This function is a wrapper that sets the RTS, CTS, DTR, DSR and
01175  * XON/XOFF settings as necessary for the specified flow control
01176  * type. For more fine-grained control of these settings, use their
01177  * individual configuration functions.
01178  *
01179  * @param[in] port Pointer to a port structure. Must not be NULL.
01180  * @param[in] flowcontrol Flow control setting to use.
01181  *
01182  * @return SP_OK upon success, a negative error code otherwise.
01183  *
01184  * @since 0.1.0
01185  */
01186 enum sp_return sp_set_flowcontrol(struct sp_port *port, enum sp_flowcontrol flowcontrol);
01187 
01188 /**
01189  * @}
01190  *
01191  * @defgroup Data Data handling
01192  *
01193  * Reading, writing, and flushing data.
01194  *
01195  * @{
01196  */
01197 
01198 /**
01199  * Read bytes from the specified serial port, blocking until complete.
01200  *
01201  * @warning If your program runs on Unix, defines its own signal handlers, and
01202  *          needs to abort blocking reads when these are called, then you
01203  *          should not use this function. It repeats system calls that return
01204  *          with EINTR. To be able to abort a read from a signal handler, you
01205  *          should implement your own blocking read using sp_nonblocking_read()
01206  *          together with a blocking method that makes sense for your program.
01207  *          E.g. you can obtain the file descriptor for an open port using
01208  *          sp_get_port_handle() and use this to call select() or pselect(),
01209  *          with appropriate arrangements to return if a signal is received.
01210  *
01211  * @param[in] port Pointer to a port structure. Must not be NULL.
01212  * @param[out] buf Buffer in which to store the bytes read. Must not be NULL.
01213  * @param[in] count Requested number of bytes to read.
01214  * @param[in] timeout_ms Timeout in milliseconds, or zero to wait indefinitely.
01215  *
01216  * @return The number of bytes read on success, or a negative error code. If
01217  *         the number of bytes returned is less than that requested, the
01218  *         timeout was reached before the requested number of bytes was
01219  *         available. If timeout is zero, the function will always return
01220  *         either the requested number of bytes or a negative error code.
01221  *
01222  * @since 0.1.0
01223  */
01224 enum sp_return sp_blocking_read(struct sp_port *port, void *buf, size_t count, unsigned int timeout_ms);
01225 
01226 /**
01227  * Read bytes from the specified serial port, returning as soon as any data is
01228  * available.
01229  *
01230  * @warning If your program runs on Unix, defines its own signal handlers, and
01231  *          needs to abort blocking reads when these are called, then you
01232  *          should not use this function. It repeats system calls that return
01233  *          with EINTR. To be able to abort a read from a signal handler, you
01234  *          should implement your own blocking read using sp_nonblocking_read()
01235  *          together with a blocking method that makes sense for your program.
01236  *          E.g. you can obtain the file descriptor for an open port using
01237  *          sp_get_port_handle() and use this to call select() or pselect(),
01238  *          with appropriate arrangements to return if a signal is received.
01239  *
01240  * @param[in] port Pointer to a port structure. Must not be NULL.
01241  * @param[out] buf Buffer in which to store the bytes read. Must not be NULL.
01242  * @param[in] count Maximum number of bytes to read. Must not be zero.
01243  * @param[in] timeout_ms Timeout in milliseconds, or zero to wait indefinitely.
01244  *
01245  * @return The number of bytes read on success, or a negative error code. If
01246  *         the result is zero, the timeout was reached before any bytes were
01247  *         available. If timeout_ms is zero, the function will always return
01248  *         either at least one byte, or a negative error code.
01249  *
01250  * @since 0.1.1
01251  */
01252 enum sp_return sp_blocking_read_next(struct sp_port *port, void *buf, size_t count, unsigned int timeout_ms);
01253 
01254 /**
01255  * Read bytes from the specified serial port, without blocking.
01256  *
01257  * @param[in] port Pointer to a port structure. Must not be NULL.
01258  * @param[out] buf Buffer in which to store the bytes read. Must not be NULL.
01259  * @param[in] count Maximum number of bytes to read.
01260  *
01261  * @return The number of bytes read on success, or a negative error code. The
01262  *         number of bytes returned may be any number from zero to the maximum
01263  *         that was requested.
01264  *
01265  * @since 0.1.0
01266  */
01267 enum sp_return sp_nonblocking_read(struct sp_port *port, void *buf, size_t count);
01268 
01269 /**
01270  * Write bytes to the specified serial port, blocking until complete.
01271  *
01272  * Note that this function only ensures that the accepted bytes have been
01273  * written to the OS; they may be held in driver or hardware buffers and not
01274  * yet physically transmitted. To check whether all written bytes have actually
01275  * been transmitted, use the sp_output_waiting() function. To wait until all
01276  * written bytes have actually been transmitted, use the sp_drain() function.
01277  *
01278  * @warning If your program runs on Unix, defines its own signal handlers, and
01279  *          needs to abort blocking writes when these are called, then you
01280  *          should not use this function. It repeats system calls that return
01281  *          with EINTR. To be able to abort a write from a signal handler, you
01282  *          should implement your own blocking write using sp_nonblocking_write()
01283  *          together with a blocking method that makes sense for your program.
01284  *          E.g. you can obtain the file descriptor for an open port using
01285  *          sp_get_port_handle() and use this to call select() or pselect(),
01286  *          with appropriate arrangements to return if a signal is received.
01287  *
01288  * @param[in] port Pointer to a port structure. Must not be NULL.
01289  * @param[in] buf Buffer containing the bytes to write. Must not be NULL.
01290  * @param[in] count Requested number of bytes to write.
01291  * @param[in] timeout_ms Timeout in milliseconds, or zero to wait indefinitely.
01292  *
01293  * @return The number of bytes written on success, or a negative error code.
01294  *         If the number of bytes returned is less than that requested, the
01295  *         timeout was reached before the requested number of bytes was
01296  *         written. If timeout is zero, the function will always return
01297  *         either the requested number of bytes or a negative error code. In
01298  *         the event of an error there is no way to determine how many bytes
01299  *         were sent before the error occurred.
01300  *
01301  * @since 0.1.0
01302  */
01303 enum sp_return sp_blocking_write(struct sp_port *port, const void *buf, size_t count, unsigned int timeout_ms);
01304 
01305 /**
01306  * Write bytes to the specified serial port, without blocking.
01307  *
01308  * Note that this function only ensures that the accepted bytes have been
01309  * written to the OS; they may be held in driver or hardware buffers and not
01310  * yet physically transmitted. To check whether all written bytes have actually
01311  * been transmitted, use the sp_output_waiting() function. To wait until all
01312  * written bytes have actually been transmitted, use the sp_drain() function.
01313  *
01314  * @param[in] port Pointer to a port structure. Must not be NULL.
01315  * @param[in] buf Buffer containing the bytes to write. Must not be NULL.
01316  * @param[in] count Maximum number of bytes to write.
01317  *
01318  * @return The number of bytes written on success, or a negative error code.
01319  *         The number of bytes returned may be any number from zero to the
01320  *         maximum that was requested.
01321  *
01322  * @since 0.1.0
01323  */
01324 enum sp_return sp_nonblocking_write(struct sp_port *port, const void *buf, size_t count);
01325 
01326 /**
01327  * Gets the number of bytes waiting in the input buffer.
01328  *
01329  * @param[in] port Pointer to a port structure. Must not be NULL.
01330  *
01331  * @return Number of bytes waiting on success, a negative error code otherwise.
01332  *
01333  * @since 0.1.0
01334  */
01335 enum sp_return sp_input_waiting(struct sp_port *port);
01336 
01337 /**
01338  * Gets the number of bytes waiting in the output buffer.
01339  *
01340  * @param[in] port Pointer to a port structure. Must not be NULL.
01341  *
01342  * @return Number of bytes waiting on success, a negative error code otherwise.
01343  *
01344  * @since 0.1.0
01345  */
01346 enum sp_return sp_output_waiting(struct sp_port *port);
01347 
01348 /**
01349  * Flush serial port buffers. Data in the selected buffer(s) is discarded.
01350  *
01351  * @param[in] port Pointer to a port structure. Must not be NULL.
01352  * @param[in] buffers Which buffer(s) to flush.
01353  *
01354  * @return SP_OK upon success, a negative error code otherwise.
01355  *
01356  * @since 0.1.0
01357  */
01358 enum sp_return sp_flush(struct sp_port *port, enum sp_buffer buffers);
01359 
01360 /**
01361  * Wait for buffered data to be transmitted.
01362  *
01363  * @warning If your program runs on Unix, defines its own signal handlers, and
01364  *          needs to abort draining the output buffer when when these are
01365  *          called, then you should not use this function. It repeats system
01366  *          calls that return with EINTR. To be able to abort a drain from a
01367  *          signal handler, you would need to implement your own blocking
01368  *          drain by polling the result of sp_output_waiting().
01369  *
01370  * @param[in] port Pointer to a port structure. Must not be NULL.
01371  *
01372  * @return SP_OK upon success, a negative error code otherwise.
01373  *
01374  * @since 0.1.0
01375  */
01376 enum sp_return sp_drain(struct sp_port *port);
01377 
01378 /**
01379  * @}
01380  *
01381  * @defgroup Waiting Waiting
01382  *
01383  * Waiting for events and timeout handling.
01384  *
01385  * @{
01386  */
01387 
01388 /**
01389  * Allocate storage for a set of events.
01390  *
01391  * The user should allocate a variable of type struct sp_event_set *,
01392  * then pass a pointer to this variable to receive the result.
01393  *
01394  * The result should be freed after use by calling sp_free_event_set().
01395  *
01396  * @param[out] result_ptr If any error is returned, the variable pointed to by
01397  *                        result_ptr will be set to NULL. Otherwise, it will
01398  *                        be set to point to the event set. Must not be NULL.
01399  *
01400  * @return SP_OK upon success, a negative error code otherwise.
01401  *
01402  * @since 0.1.0
01403  */
01404 enum sp_return sp_new_event_set(struct sp_event_set **result_ptr);
01405 
01406 /**
01407  * Add events to a struct sp_event_set for a given port.
01408  *
01409  * The port must first be opened by calling sp_open() using the same port
01410  * structure.
01411  *
01412  * After the port is closed or the port structure freed, the results may
01413  * no longer be valid.
01414  *
01415  * @param[in,out] event_set Event set to update. Must not be NULL.
01416  * @param[in] port Pointer to a port structure. Must not be NULL.
01417  * @param[in] mask Bitmask of events to be waited for.
01418  *
01419  * @return SP_OK upon success, a negative error code otherwise.
01420  *
01421  * @since 0.1.0
01422  */
01423 enum sp_return sp_add_port_events(struct sp_event_set *event_set,
01424     const struct sp_port *port, enum sp_event mask);
01425 
01426 /**
01427  * Wait for any of a set of events to occur.
01428  *
01429  * @param[in] event_set Event set to wait on. Must not be NULL.
01430  * @param[in] timeout_ms Timeout in milliseconds, or zero to wait indefinitely.
01431  *
01432  * @return SP_OK upon success, a negative error code otherwise.
01433  *
01434  * @since 0.1.0
01435  */
01436 enum sp_return sp_wait(struct sp_event_set *event_set, unsigned int timeout_ms);
01437 
01438 /**
01439  * Free a structure allocated by sp_new_event_set().
01440  *
01441  * @param[in] event_set Event set to free. Must not be NULL.
01442  *
01443  * @since 0.1.0
01444  */
01445 void sp_free_event_set(struct sp_event_set *event_set);
01446 
01447 /**
01448  * @}
01449  *
01450  * @defgroup Signals Signals
01451  *
01452  * Port signalling operations.
01453  *
01454  * @{
01455  */
01456 
01457 /**
01458  * Gets the status of the control signals for the specified port.
01459  *
01460  * The user should allocate a variable of type "enum sp_signal" and pass a
01461  * pointer to this variable to receive the result. The result is a bitmask
01462  * in which individual signals can be checked by bitwise OR with values of
01463  * the sp_signal enum.
01464  *
01465  * @param[in] port Pointer to a port structure. Must not be NULL.
01466  * @param[out] signal_mask Pointer to a variable to receive the result.
01467  *                         Must not be NULL.
01468  *
01469  * @return SP_OK upon success, a negative error code otherwise.
01470  *
01471  * @since 0.1.0
01472  */
01473 enum sp_return sp_get_signals(struct sp_port *port, enum sp_signal *signal_mask);
01474 
01475 /**
01476  * Put the port transmit line into the break state.
01477  *
01478  * @param[in] port Pointer to a port structure. Must not be NULL.
01479  *
01480  * @return SP_OK upon success, a negative error code otherwise.
01481  *
01482  * @since 0.1.0
01483  */
01484 enum sp_return sp_start_break(struct sp_port *port);
01485 
01486 /**
01487  * Take the port transmit line out of the break state.
01488  *
01489  * @param[in] port Pointer to a port structure. Must not be NULL.
01490  *
01491  * @return SP_OK upon success, a negative error code otherwise.
01492  *
01493  * @since 0.1.0
01494  */
01495 enum sp_return sp_end_break(struct sp_port *port);
01496 
01497 /**
01498  * @}
01499  *
01500  * @defgroup Errors Errors
01501  *
01502  * Obtaining error information.
01503  *
01504  * @{
01505  */
01506 
01507 /**
01508  * Get the error code for a failed operation.
01509  *
01510  * In order to obtain the correct result, this function should be called
01511  * straight after the failure, before executing any other system operations.
01512  * The result is thread-specific, and only valid when called immediately
01513  * after a previous call returning SP_ERR_FAIL.
01514  *
01515  * @return The system's numeric code for the error that caused the last
01516  *         operation to fail.
01517  *
01518  * @since 0.1.0
01519  */
01520 int sp_last_error_code(void);
01521 
01522 /**
01523  * Get the error message for a failed operation.
01524  *
01525  * In order to obtain the correct result, this function should be called
01526  * straight after the failure, before executing other system operations.
01527  * The result is thread-specific, and only valid when called immediately
01528  * after a previous call returning SP_ERR_FAIL.
01529  *
01530  * @return The system's message for the error that caused the last
01531  *         operation to fail. This string may be allocated by the function,
01532  *         and should be freed after use by calling sp_free_error_message().
01533  *
01534  * @since 0.1.0
01535  */
01536 char *sp_last_error_message(void);
01537 
01538 /**
01539  * Free an error message returned by sp_last_error_message().
01540  *
01541  * @param[in] message The error message string to free. Must not be NULL.
01542  *
01543  * @since 0.1.0
01544  */
01545 void sp_free_error_message(char *message);
01546 
01547 /**
01548  * Set the handler function for library debugging messages.
01549  *
01550  * Debugging messages are generated by the library during each operation,
01551  * to help in diagnosing problems. The handler will be called for each
01552  * message. The handler can be set to NULL to ignore all debug messages.
01553  *
01554  * The handler function should accept a format string and variable length
01555  * argument list, in the same manner as e.g. printf().
01556  *
01557  * The default handler is sp_default_debug_handler().
01558  *
01559  * @param[in] handler The handler function to use. Can be NULL (in that case
01560  *                    all debug messages will be ignored).
01561  *
01562  * @since 0.1.0
01563  */
01564 void sp_set_debug_handler(void (*handler)(const char *format, ...));
01565 
01566 /**
01567  * Default handler function for library debugging messages.
01568  *
01569  * This function prints debug messages to the standard error stream if the
01570  * environment variable LIBSERIALPORT_DEBUG is set. Otherwise, they are
01571  * ignored.
01572  *
01573  * @param[in] format The format string to use. Must not be NULL.
01574  * @param[in] ... The variable length argument list to use.
01575  *
01576  * @since 0.1.0
01577  */
01578 void sp_default_debug_handler(const char *format, ...);
01579 
01580 /** @} */
01581 
01582 /**
01583  * @defgroup Versions Versions
01584  *
01585  * Version number querying functions, definitions, and macros.
01586  *
01587  * This set of API calls returns two different version numbers related
01588  * to libserialport. The "package version" is the release version number of the
01589  * libserialport tarball in the usual "major.minor.micro" format, e.g. "0.1.0".
01590  *
01591  * The "library version" is independent of that; it is the libtool version
01592  * number in the "current:revision:age" format, e.g. "2:0:0".
01593  * See http://www.gnu.org/software/libtool/manual/libtool.html#Libtool-versioning for details.
01594  *
01595  * Both version numbers (and/or individual components of them) can be
01596  * retrieved via the API calls at runtime, and/or they can be checked at
01597  * compile/preprocessor time using the respective macros.
01598  *
01599  * @{
01600  */
01601 
01602 /*
01603  * Package version macros (can be used for conditional compilation).
01604  */
01605 
01606 /** The libserialport package 'major' version number. */
01607 #define SP_PACKAGE_VERSION_MAJOR 0
01608 
01609 /** The libserialport package 'minor' version number. */
01610 #define SP_PACKAGE_VERSION_MINOR 1
01611 
01612 /** The libserialport package 'micro' version number. */
01613 #define SP_PACKAGE_VERSION_MICRO 1
01614 
01615 /** The libserialport package version ("major.minor.micro") as string. */
01616 #define SP_PACKAGE_VERSION_STRING "0.1.1"
01617 
01618 /*
01619  * Library/libtool version macros (can be used for conditional compilation).
01620  */
01621 
01622 /** The libserialport libtool 'current' version number. */
01623 #define SP_LIB_VERSION_CURRENT 1
01624 
01625 /** The libserialport libtool 'revision' version number. */
01626 #define SP_LIB_VERSION_REVISION 0
01627 
01628 /** The libserialport libtool 'age' version number. */
01629 #define SP_LIB_VERSION_AGE 1
01630 
01631 /** The libserialport libtool version ("current:revision:age") as string. */
01632 #define SP_LIB_VERSION_STRING "1:0:1"
01633 
01634 /**
01635  * Get the major libserialport package version number.
01636  *
01637  * @return The major package version number.
01638  *
01639  * @since 0.1.0
01640  */
01641 int sp_get_major_package_version(void);
01642 
01643 /**
01644  * Get the minor libserialport package version number.
01645  *
01646  * @return The minor package version number.
01647  *
01648  * @since 0.1.0
01649  */
01650 int sp_get_minor_package_version(void);
01651 
01652 /**
01653  * Get the micro libserialport package version number.
01654  *
01655  * @return The micro package version number.
01656  *
01657  * @since 0.1.0
01658  */
01659 int sp_get_micro_package_version(void);
01660 
01661 /**
01662  * Get the libserialport package version number as a string.
01663  *
01664  * @return The package version number string. The returned string is
01665  *         static and thus should NOT be free'd by the caller.
01666  *
01667  * @since 0.1.0
01668  */
01669 const char *sp_get_package_version_string(void);
01670 
01671 /**
01672  * Get the "current" part of the libserialport library version number.
01673  *
01674  * @return The "current" library version number.
01675  *
01676  * @since 0.1.0
01677  */
01678 int sp_get_current_lib_version(void);
01679 
01680 /**
01681  * Get the "revision" part of the libserialport library version number.
01682  *
01683  * @return The "revision" library version number.
01684  *
01685  * @since 0.1.0
01686  */
01687 int sp_get_revision_lib_version(void);
01688 
01689 /**
01690  * Get the "age" part of the libserialport library version number.
01691  *
01692  * @return The "age" library version number.
01693  *
01694  * @since 0.1.0
01695  */
01696 int sp_get_age_lib_version(void);
01697 
01698 /**
01699  * Get the libserialport library version number as a string.
01700  *
01701  * @return The library version number string. The returned string is
01702  *         static and thus should NOT be free'd by the caller.
01703  *
01704  * @since 0.1.0
01705  */
01706 const char *sp_get_lib_version_string(void);
01707 
01708 /** @} */
01709 
01710 #ifdef __cplusplus
01711 }
01712 #endif
01713 
01714 #endif