libserialport.h.in

   1 /*
   2  * This file is part of the libserialport project.
   3  *
   4  * Copyright (C) 2013 Martin Ling <martin-libserialport@earth.li>
   5  *
   6  * This program is free software: you can redistribute it and/or modify
   7  * it under the terms of the GNU Lesser General Public License as
   8  * published by the Free Software Foundation, either version 3 of the
   9  * License, or (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public License
  17  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  18  */
  19
  20 /**
  21  * @mainpage libserialport API
  22  *
  23  * Introduction
  24  * ============
  25  *
  26  * libserialport is a minimal library written in C that is intended to take
  27  * care of the OS-specific details when writing software that uses serial ports.
  28  *
  29  * By writing your serial code to use libserialport, you enable it to work
  30  * transparently on any platform supported by the library.
  31  *
  32  * The operations that are supported are:
  33  *
  34  * - @ref Enumeration (obtaining a list of serial ports on the system)
  35  * - @ref Ports
  36  * - @ref Configuration (baud rate, parity, etc.)
  37  * - @ref Data
  38  * - @ref Errors
  39  *
  40  * libserialport is an open source project released under the LGPL3+ license.
  41  *
  42  * API principles
  43  * ==============
  44  *
  45  * The API is simple, and designed to be a minimal wrapper around the serial
  46  * port support in each OS.
  47  *
  48  * Most functions take a pointer to a struct sp_port, which represents a serial
  49  * port. These structures are always allocated and freed by the library, using
  50  * the functions in the @ref Enumeration "Enumeration" section.
  51  *
  52  * All functions can return only three possible error values. @ref SP_ERR_ARG
  53  * indicates the function was called with invalid arguments. @ref SP_ERR_FAIL
  54  * indicates that the OS reported a failure. @ref SP_ERR_MEM indicates that a
  55  * memory allocation failed. All of these error values are negative.
  56  *
  57  * When @ref SP_ERR_FAIL is returned, an error code or string description of
  58  * the error can be obtained by calling sp_last_error_code() or
  59  * sp_last_error_message(). The error code or message is that provided by the
  60  * OS; libserialport does not define any error codes or messages of its own.
  61  *
  62  * Function calls that succeed return @ref SP_OK, which is equal to zero,
  63  * or where otherwise documented a positive value.
  64  */
  65
  66 #ifndef LIBSERIALPORT_LIBSERIALPORT_H
  67 #define LIBSERIALPORT_LIBSERIALPORT_H
  68
  69 #ifdef __cplusplus
  70 extern "C" {
  71 #endif
  72
  73 #include <stddef.h>
  74 #ifdef _WIN32
  75 #include <windows.h>
  76 #endif
  77
  78 /* Package version macros (e.g. for conditional compilation). */
  79 #define SP_PACKAGE_VERSION_MAJOR @SP_PACKAGE_VERSION_MAJOR@
  80 #define SP_PACKAGE_VERSION_MINOR @SP_PACKAGE_VERSION_MINOR@
  81 #define SP_PACKAGE_VERSION_MICRO @SP_PACKAGE_VERSION_MICRO@
  82 #define SP_PACKAGE_VERSION_STRING "@SP_PACKAGE_VERSION@"
  83
  84 /* Library/libtool version macros (e.g. for conditional compilation). */
  85 #define SP_LIB_VERSION_CURRENT @SP_LIB_VERSION_CURRENT@
  86 #define SP_LIB_VERSION_REVISION @SP_LIB_VERSION_REVISION@
  87 #define SP_LIB_VERSION_AGE @SP_LIB_VERSION_AGE@
  88 #define SP_LIB_VERSION_STRING "@SP_LIB_VERSION@"
  89
  90 /** Return values. */
  91 enum sp_return {
  92         /** Operation completed successfully. */
  93         SP_OK = 0,
  94         /** Invalid arguments were passed to the function. */
  95         SP_ERR_ARG = -1,
  96         /** A system error occured while executing the operation. */
  97         SP_ERR_FAIL = -2,
  98         /** A memory allocation failed while executing the operation. */
  99         SP_ERR_MEM = -3,
 100 };
 101
 102 /** Port access modes. */
 103 enum sp_mode {
 104         /** Open port for read access. */
 105         SP_MODE_READ = 1,
 106         /** Open port for write access. */
 107         SP_MODE_WRITE = 2,
 108         /** Open port in non-blocking mode. */
 109         SP_MODE_NONBLOCK = 4,
 110 };
 111
 112 /** Buffer selection. */
 113 enum sp_buffer {
 114         /** Input buffer. */
 115         SP_BUF_INPUT = 1,
 116         /** Output buffer. */
 117         SP_BUF_OUTPUT = 2,
 118         /** Both buffers. */
 119         SP_BUF_BOTH = 3,
 120 };
 121
 122 /** Parity settings. */
 123 enum sp_parity {
 124         /** Special value to indicate setting should be left alone. */
 125         SP_PARITY_INVALID = -1,
 126         /** No parity. */
 127         SP_PARITY_NONE = 0,
 128         /** Odd parity. */
 129         SP_PARITY_ODD = 1,
 130         /** Even parity. */
 131         SP_PARITY_EVEN = 2,
 132 };
 133
 134 /** RTS pin behaviour. */
 135 enum sp_rts {
 136         /** Special value to indicate setting should be left alone. */
 137         SP_RTS_INVALID = -1,
 138         /** RTS off. */
 139         SP_RTS_OFF = 0,
 140         /** RTS on. */
 141         SP_RTS_ON = 1,
 142         /** RTS used for flow control. */
 143         SP_RTS_FLOW_CONTROL = 2,
 144 };
 145
 146 /** CTS pin behaviour. */
 147 enum sp_cts {
 148         /** Special value to indicate setting should be left alone. */
 149         SP_CTS_INVALID = -1,
 150         /** CTS ignored. */
 151         SP_CTS_IGNORE = 0,
 152         /** CTS used for flow control. */
 153         SP_CTS_FLOW_CONTROL = 1,
 154 };
 155
 156 /** DTR pin behaviour. */
 157 enum sp_dtr {
 158         /** Special value to indicate setting should be left alone. */
 159         SP_DTR_INVALID = -1,
 160         /** DTR off. */
 161         SP_DTR_OFF = 0,
 162         /** DTR on. */
 163         SP_DTR_ON = 1,
 164         /** DTR used for flow control. */
 165         SP_DTR_FLOW_CONTROL = 2,
 166 };
 167
 168 /** DSR pin behaviour. */
 169 enum sp_dsr {
 170         /** Special value to indicate setting should be left alone. */
 171         SP_DSR_INVALID = -1,
 172         /** DSR ignored. */
 173         SP_DSR_IGNORE = 0,
 174         /** DSR used for flow control. */
 175         SP_DSR_FLOW_CONTROL = 1,
 176 };
 177
 178 /** XON/XOFF flow control behaviour. */
 179 enum sp_xonxoff {
 180         /** Special value to indicate setting should be left alone. */
 181         SP_XONXOFF_INVALID = -1,
 182         /** XON/XOFF disabled. */
 183         SP_XONXOFF_DISABLED = 0,
 184         /** XON/XOFF enabled for input only. */
 185         SP_XONXOFF_IN = 1,
 186         /** XON/XOFF enabled for output only. */
 187         SP_XONXOFF_OUT = 2,
 188         /** XON/XOFF enabled for input and output. */
 189         SP_XONXOFF_INOUT = 3,
 190 };
 191
 192 /** Standard flow control combinations. */
 193 enum sp_flowcontrol {
 194         /** No flow control. */
 195         SP_FLOWCONTROL_NONE = 0,
 196         /** Software flow control using XON/XOFF characters. */
 197         SP_FLOWCONTROL_XONXOFF = 1,
 198         /** Hardware flow control using RTS/CTS signals. */
 199         SP_FLOWCONTROL_RTSCTS = 2,
 200         /** Hardware flow control using DTR/DSR signals. */
 201         SP_FLOWCONTROL_DTRDSR = 3,
 202 };
 203
 204 /** Input signals. */
 205 enum sp_signal {
 206         /** Clear to send. */
 207         SP_SIG_CTS = 1,
 208         /** Data set ready. */
 209         SP_SIG_DSR = 2,
 210         /** Data carrier detect. */
 211         SP_SIG_DCD = 4,
 212         /** Ring indicator. */
 213         SP_SIG_RI = 8,
 214 };
 215
 216 /** A serial port. */
 217 struct sp_port {
 218         /** Name used to open the port. */
 219         char *name;
 220 /** @cond 0 */
 221         /** OS-specific port handle. */
 222 #ifdef _WIN32
 223         HANDLE hdl;
 224 #else
 225         int fd;
 226 #endif
 227 /** @endcond */
 228 };
 229
 230 /** Configuration for a serial port. */
 231 struct sp_port_config {
 232         /** Baud rate in bits per second. */
 233         int baudrate;
 234         /** Number of data bits to use. Valid values are 5 to 8. */
 235         int bits;
 236         /** Parity setting to use. */
 237         enum sp_parity parity;
 238         /** Number of stop bits to use (1 or 2). */
 239         int stopbits;
 240         /** RTS pin mode. */
 241         enum sp_rts rts;
 242         /** CTS pin mode. */
 243         enum sp_cts cts;
 244         /** DTR pin mode. */
 245         enum sp_dtr dtr;
 246         /** DSR pin mode. */
 247         enum sp_dsr dsr;
 248         /** XON/XOFF flow control mode. */
 249         enum sp_xonxoff xon_xoff;
 250 };
 251
 252 /**
 253 @defgroup Enumeration Port enumeration
 254 @{
 255 */
 256
 257 /**
 258  * Obtain a pointer to a new sp_port structure representing the named port.
 259  *
 260  * The user should allocate a variable of type "struct sp_port *" and pass a
 261  * pointer to this to receive the result.
 262  *
 263  * The result should be freed after use by calling sp_free_port().
 264  *
 265  * @return SP_OK on success, SP_ERR_FAIL on failure, SP_ERR_MEM on allocation
 266  *         failure, or SP_ERR_ARG if an invalid pointer is passed. If any error
 267  *         is returned, the variable pointed to by port_ptr will be set to NULL.
 268  *         Otherwise, it will be set to point to the newly allocated port.
 269  */
 270 enum sp_return sp_get_port_by_name(const char *portname, struct sp_port **port_ptr);
 271
 272 /**
 273  * Free a port structure obtained from sp_get_port_by_name() or sp_copy_port().
 274  */
 275 void sp_free_port(struct sp_port *port);
 276
 277 /**
 278  * List the serial ports available on the system.
 279  *
 280  * The result obtained is an array of pointers to sp_port structures,
 281  * terminated by a NULL. The user should allocate a variable of type
 282  * "struct sp_port **" and pass a pointer to this to receive the result.
 283  *
 284  * The result should be freed after use by calling sp_free_port_list().
 285  * If a port from the list is to be used after freeing the list, it must be
 286  * copied first using sp_copy_port().
 287  *
 288  * @return SP_OK on success, SP_ERR_FAIL on failure, SP_ERR_MEM on allocation
 289  *         failure, or SP_ERR_ARG if an invalid pointer is passed. If any error
 290  *         is returned, the variable pointed to by list_ptr will be set to NULL.
 291  *         Otherwise, it will be set to point to the newly allocated array.
 292  */
 293 enum sp_return sp_list_ports(struct sp_port ***list_ptr);
 294
 295 /**
 296  * Make a new copy of a sp_port structure.
 297  *
 298  * The user should allocate a variable of type "struct sp_port *" and pass a
 299  * pointer to this to receive the result.
 300  *
 301  * The copy should be freed after use by calling sp_free_port().
 302  *
 303  * @return SP_OK on success, SP_ERR_MEM on allocation failure, or SP_ERR_ARG
 304  *         if an invalid port or pointer is passed. If any error is returned,
 305  *         the variable pointed to by copy_ptr will be set to NULL. Otherwise,
 306  *         it will be set to point to the newly allocated copy.
 307  */
 308 enum sp_return sp_copy_port(const struct sp_port *port, struct sp_port **copy_ptr);
 309
 310 /**
 311  * Free a port list obtained from sp_list_ports().
 312  *
 313  * This will also free all the sp_port structures referred to from the list;
 314  * any that are to be retained must be copied first using sp_copy_port().
 315  */
 316 void sp_free_port_list(struct sp_port **ports);
 317
 318 /**
 319  * @}
 320  * @defgroup Ports Opening and closing ports
 321  * @{
 322  */
 323
 324 /**
 325  * Open the specified serial port.
 326  *
 327  * @param port Pointer to port structure.
 328  * @param flags Flags to use when opening the serial port.
 329  *
 330  * @return SP_OK on success, SP_ERR_FAIL on failure, SP_ERR_MEM on allocation
 331  *         failure, or SP_ERR_ARG if an invalid port is passed.
 332  */
 333 enum sp_return sp_open(struct sp_port *port, enum sp_mode flags);
 334
 335 /**
 336  * Close the specified serial port.
 337  *
 338  * @return SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 339  *         if an invalid port is passed.
 340  */
 341 enum sp_return sp_close(struct sp_port *port);
 342
 343 /**
 344  * @}
 345  * @defgroup Configuration Setting port parameters
 346  * @{
 347  */
 348
 349 /**
 350  * Get the current configuration of the specified serial port.
 351  *
 352  * The user should allocate a struct sp_port_config, then pass a pointer to it
 353  * as the config parameter. The struct will be populated with the port
 354  * configuration.
 355  *
 356  * Any setting that is in a state not recognised or supported by
 357  * libserialport will have its value set to -1 in the struct.
 358  *
 359  * @return SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 360  *         for invalid arguments.
 361  */
 362 enum sp_return sp_get_config(struct sp_port *port, struct sp_port_config *config);
 363
 364 /**
 365  * Set the configuration for the specified serial port.
 366  *
 367  * The user should populate a struct sp_port_config, then pass a pointer to it
 368  * as the config parameter.
 369  *
 370  * To retain the current value of any setting, set that field to -1.
 371  *
 372  * @return SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 373  *         for invalid arguments.
 374  */
 375 enum sp_return sp_set_config(struct sp_port *port, const struct sp_port_config *config);
 376
 377 /**
 378  * Set the baud rate for the specified serial port.
 379  *
 380  * @param port Pointer to port structure.
 381  * @param baudrate Baud rate in bits per second.
 382  *
 383  * @return SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 384  *         for invalid arguments.
 385  */
 386 enum sp_return sp_set_baudrate(struct sp_port *port, int baudrate);
 387
 388 /**
 389  * Set the number of data bits for the specified serial port.
 390  *
 391  * @param port Pointer to port structure.
 392  * @param bits Number of data bits to use. Valid values are 5 to 8.
 393  *
 394  * @return SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 395  *         for invalid arguments.
 396  */
 397 enum sp_return sp_set_bits(struct sp_port *port, int bits);
 398
 399 /**
 400  * Set the parity for the specified serial port.
 401  *
 402  * @param port Pointer to port structure.
 403  * @param parity Parity setting to use.
 404  *
 405  * @return SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 406  *         for invalid arguments.
 407  */
 408 enum sp_return sp_set_parity(struct sp_port *port, enum sp_parity parity);
 409
 410 /**
 411  * Set the number of stop bits for the specified port.
 412  *
 413  * @param port Pointer to port structure.
 414  * @param stopbits Number of stop bits to use (1 or 2).
 415  *
 416  * @return SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 417  *         for invalid arguments.
 418  */
 419 enum sp_return sp_set_stopbits(struct sp_port *port, int stopbits);
 420
 421 /**
 422  * Set the flow control type for the specified serial port.
 423  *
 424  * This function is a wrapper that sets the RTS, CTS, DTR, DSR and
 425  * XON/XOFF settings as necessary for the specified flow control
 426  * type. For more fine-grained control of these settings, use their
 427  * individual configuration functions or the sp_set_config() function.
 428  *
 429  * @param port Pointer to port structure.
 430  * @param flowcontrol Flow control setting to use.
 431  *
 432  * @return SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 433  *         for invalid arguments.
 434  */
 435 enum sp_return sp_set_flowcontrol(struct sp_port *port, enum sp_flowcontrol flowcontrol);
 436
 437 /**
 438  * Set the RTS pin behaviour for the specified port.
 439  *
 440  * @param port Pointer to port structure.
 441  * @param rts RTS pin mode.
 442  *
 443  * @return SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 444  *         for invalid arguments.
 445  */
 446 enum sp_return sp_set_rts(struct sp_port *port, enum sp_rts rts);
 447
 448 /**
 449  * Set the CTS pin behaviour for the specified port.
 450  *
 451  * @param port Pointer to port structure.
 452  * @param cts CTS pin mode.
 453  *
 454  * @return SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 455  *         for invalid arguments.
 456  */
 457 enum sp_return sp_set_cts(struct sp_port *port, enum sp_cts cts);
 458
 459 /**
 460  * Set the DTR pin behaviour for the specified port.
 461  *
 462  * @param port Pointer to port structure.
 463  * @param dtr DTR pin mode.
 464  *
 465  * @return SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 466  *         for invalid arguments.
 467  */
 468 enum sp_return sp_set_dtr(struct sp_port *port, enum sp_dtr dtr);
 469
 470 /**
 471  * Set the RTS pin behaviour for the specified port.
 472  *
 473  * @param port Pointer to port structure.
 474  * @param dsr DSR pin mode.
 475  *
 476  * @return SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 477  *         for invalid arguments.
 478  */
 479 enum sp_return sp_set_dsr(struct sp_port *port, enum sp_dsr dsr);
 480
 481 /**
 482  * Configure XON/XOFF flow control for the specified port.
 483  *
 484  * @param port Pointer to port structure.
 485  * @param xon_xoff XON/XOFF flow control mode.
 486  *
 487  * @return SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 488  *         for invalid arguments.
 489  */
 490 enum sp_return sp_set_xon_xoff(struct sp_port *port, enum sp_xonxoff xon_xoff);
 491
 492 /**
 493  * @}
 494  * @defgroup Data Reading, writing, and flushing data
 495  * @{
 496 */
 497
 498 /**
 499  * Read bytes from the specified serial port.
 500  *
 501  * Note that this function may return after reading less than the specified
 502  * number of bytes; it is the user's responsibility to iterate as necessary
 503  * in this case.
 504  *
 505  * @param port Pointer to port structure.
 506  * @param buf Buffer in which to store the bytes read.
 507  * @param count Maximum number of bytes to read.
 508  *
 509  * @return The number of bytes read, SP_ERR_FAIL on failure,
 510  *         or SP_ERR_ARG for invalid arguments.
 511  */
 512 enum sp_return sp_read(struct sp_port *port, void *buf, size_t count);
 513
 514 /**
 515  * Write bytes to the specified serial port.
 516  *
 517  * Note that this function may return after writing less than the specified
 518  * number of bytes; it is the user's responsibility to iterate as necessary
 519  * in this case.
 520  *
 521  * @param port Pointer to port structure.
 522  * @param buf Buffer containing the bytes to write.
 523  * @param count Maximum number of bytes to write.
 524  *
 525  * @return The number of bytes written, SP_ERR_FAIL on failure,
 526  *         or SP_ERR_ARG for invalid arguments.
 527  */
 528 enum sp_return sp_write(struct sp_port *port, const void *buf, size_t count);
 529
 530 /**
 531  * Flush serial port buffers. Data in the selected buffer(s) is discarded.
 532  *
 533  * @param port Pointer to port structure.
 534  * @param buffers Which buffer(s) to flush.
 535  *
 536  * @return SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 537  *         if an invalid port is passed.
 538  */
 539 enum sp_return sp_flush(struct sp_port *port, enum sp_buffer buffers);
 540
 541 /**
 542  * Wait for buffered data to be transmitted.
 543  *
 544  * @param port Pointer to port structure.
 545  *
 546  * @return SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 547  *         if an invalid port is passed.
 548  */
 549 enum sp_return sp_drain(struct sp_port *port);
 550
 551 /**
 552  * @}
 553  * @defgroup Signal Port signalling operations
 554  * @{
 555  */
 556
 557 /**
 558  * Gets the status of the control signals for the specified port.
 559  *
 560  * The user should allocate a variable of type "enum sp_signal" and pass a
 561  * pointer to this variable to receive the result. The result is a bitmask
 562  * in which individual signals can be checked by bitwise OR with values of
 563  * the sp_signal enum.
 564  *
 565  * @param port Pointer to port structure.
 566  * @param signals Pointer to variable to receive result.
 567  *
 568  * @return SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 569  *         if an an invalid port or pointer is passed.
 570  */
 571 enum sp_return sp_get_signals(struct sp_port *port, enum sp_signal *signals);
 572
 573 /**
 574  * Put the port transmit line into the break state.
 575  *
 576  * @param port Pointer to port structure.
 577  *
 578  * @return SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 579  *         if an invalid port is passed.
 580  */
 581 enum sp_return sp_start_break(struct sp_port *port);
 582
 583 /**
 584  * Take the port transmit line out of the break state.
 585  *
 586  * @param port Pointer to port structure.
 587  *
 588  * @return SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 589  *         if an invalid port is passed.
 590  */
 591 enum sp_return sp_end_break(struct sp_port *port);
 592
 593 /**
 594  * @}
 595  * @defgroup Errors Obtaining error information
 596  * @{
 597 */
 598
 599 /**
 600  * Get the error code for a failed operation.
 601  *
 602  * In order to obtain the correct result, this function should be called
 603  * straight after the failure, before executing any other system operations.
 604  *
 605  * @return The system's numeric code for the error that caused the last
 606  *         operation to fail.
 607  */
 608 int sp_last_error_code(void);
 609
 610 /**
 611  * Get the error message for a failed operation.
 612  *
 613  * In order to obtain the correct result, this function should be called
 614  * straight after the failure, before executing other system operations.
 615  *
 616  * @return The system's message for the error that caused the last
 617  *         operation to fail. This string may be allocated by the function,
 618  *         and should be freed after use by calling sp_free_error_message().
 619  */
 620 char *sp_last_error_message(void);
 621
 622 /**
 623  * Free an error message returned by sp_last_error_message().
 624  */
 625 void sp_free_error_message(char *message);
 626
 627 /** @} */
 628
 629 #ifdef __cplusplus
 630 }
 631 #endif
 632
 633 #endif