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 four possible error values:
  53  *
  54  * - @ref SP_ERR_ARG means that a function was called with invalid
  55  *   arguments. This implies a bug in the caller. The arguments passed would
  56  *   be invalid regardless of the underlying OS or serial device involved.
  57  *
  58  * - @ref SP_ERR_FAIL means that the OS reported a failure. The error code or
  59  *   message provided by the OS can be obtained by calling sp_last_error_code()
  60  *   or sp_last_error_message().
  61  *
  62  * - @ref SP_ERR_SUPP indicates that there is no support for the requested
  63  *   operation in the current OS, driver or device. No error message is
  64  *   available from the OS in this case. There is either no way to request
  65  *   the operation in the first place, or libserialport does not know how to
  66  *   do so in the current version.
  67  *
  68  * - @ref SP_ERR_MEM indicates that a memory allocation failed.
  69  *
  70  * All of these error values are negative.
  71  *
  72  * Function calls that succeed return @ref SP_OK, which is equal to zero,
  73  * or where otherwise documented a positive value.
  74  */
  75
  76 #ifndef LIBSERIALPORT_LIBSERIALPORT_H
  77 #define LIBSERIALPORT_LIBSERIALPORT_H
  78
  79 #ifdef __cplusplus
  80 extern "C" {
  81 #endif
  82
  83 #include <stddef.h>
  84 #ifdef _WIN32
  85 #include <windows.h>
  86 #endif
  87
  88 /* Package version macros (e.g. for conditional compilation). */
  89 #define SP_PACKAGE_VERSION_MAJOR @SP_PACKAGE_VERSION_MAJOR@
  90 #define SP_PACKAGE_VERSION_MINOR @SP_PACKAGE_VERSION_MINOR@
  91 #define SP_PACKAGE_VERSION_MICRO @SP_PACKAGE_VERSION_MICRO@
  92 #define SP_PACKAGE_VERSION_STRING "@SP_PACKAGE_VERSION@"
  93
  94 /* Library/libtool version macros (e.g. for conditional compilation). */
  95 #define SP_LIB_VERSION_CURRENT @SP_LIB_VERSION_CURRENT@
  96 #define SP_LIB_VERSION_REVISION @SP_LIB_VERSION_REVISION@
  97 #define SP_LIB_VERSION_AGE @SP_LIB_VERSION_AGE@
  98 #define SP_LIB_VERSION_STRING "@SP_LIB_VERSION@"
  99
 100 /** Return values. */
 101 enum sp_return {
 102         /** Operation completed successfully. */
 103         SP_OK = 0,
 104         /** Invalid arguments were passed to the function. */
 105         SP_ERR_ARG = -1,
 106         /** A system error occured while executing the operation. */
 107         SP_ERR_FAIL = -2,
 108         /** A memory allocation failed while executing the operation. */
 109         SP_ERR_MEM = -3,
 110         /** The requested operation is not supported by this system or device. */
 111         SP_ERR_SUPP = -4,
 112 };
 113
 114 /** Port access modes. */
 115 enum sp_mode {
 116         /** Open port for read access. */
 117         SP_MODE_READ = 1,
 118         /** Open port for write access. */
 119         SP_MODE_WRITE = 2,
 120         /** Open port in non-blocking mode. */
 121         SP_MODE_NONBLOCK = 4,
 122 };
 123
 124 /** Buffer selection. */
 125 enum sp_buffer {
 126         /** Input buffer. */
 127         SP_BUF_INPUT = 1,
 128         /** Output buffer. */
 129         SP_BUF_OUTPUT = 2,
 130         /** Both buffers. */
 131         SP_BUF_BOTH = 3,
 132 };
 133
 134 /** Parity settings. */
 135 enum sp_parity {
 136         /** Special value to indicate setting should be left alone. */
 137         SP_PARITY_INVALID = -1,
 138         /** No parity. */
 139         SP_PARITY_NONE = 0,
 140         /** Odd parity. */
 141         SP_PARITY_ODD = 1,
 142         /** Even parity. */
 143         SP_PARITY_EVEN = 2,
 144 };
 145
 146 /** RTS pin behaviour. */
 147 enum sp_rts {
 148         /** Special value to indicate setting should be left alone. */
 149         SP_RTS_INVALID = -1,
 150         /** RTS off. */
 151         SP_RTS_OFF = 0,
 152         /** RTS on. */
 153         SP_RTS_ON = 1,
 154         /** RTS used for flow control. */
 155         SP_RTS_FLOW_CONTROL = 2,
 156 };
 157
 158 /** CTS pin behaviour. */
 159 enum sp_cts {
 160         /** Special value to indicate setting should be left alone. */
 161         SP_CTS_INVALID = -1,
 162         /** CTS ignored. */
 163         SP_CTS_IGNORE = 0,
 164         /** CTS used for flow control. */
 165         SP_CTS_FLOW_CONTROL = 1,
 166 };
 167
 168 /** DTR pin behaviour. */
 169 enum sp_dtr {
 170         /** Special value to indicate setting should be left alone. */
 171         SP_DTR_INVALID = -1,
 172         /** DTR off. */
 173         SP_DTR_OFF = 0,
 174         /** DTR on. */
 175         SP_DTR_ON = 1,
 176         /** DTR used for flow control. */
 177         SP_DTR_FLOW_CONTROL = 2,
 178 };
 179
 180 /** DSR pin behaviour. */
 181 enum sp_dsr {
 182         /** Special value to indicate setting should be left alone. */
 183         SP_DSR_INVALID = -1,
 184         /** DSR ignored. */
 185         SP_DSR_IGNORE = 0,
 186         /** DSR used for flow control. */
 187         SP_DSR_FLOW_CONTROL = 1,
 188 };
 189
 190 /** XON/XOFF flow control behaviour. */
 191 enum sp_xonxoff {
 192         /** Special value to indicate setting should be left alone. */
 193         SP_XONXOFF_INVALID = -1,
 194         /** XON/XOFF disabled. */
 195         SP_XONXOFF_DISABLED = 0,
 196         /** XON/XOFF enabled for input only. */
 197         SP_XONXOFF_IN = 1,
 198         /** XON/XOFF enabled for output only. */
 199         SP_XONXOFF_OUT = 2,
 200         /** XON/XOFF enabled for input and output. */
 201         SP_XONXOFF_INOUT = 3,
 202 };
 203
 204 /** Standard flow control combinations. */
 205 enum sp_flowcontrol {
 206         /** No flow control. */
 207         SP_FLOWCONTROL_NONE = 0,
 208         /** Software flow control using XON/XOFF characters. */
 209         SP_FLOWCONTROL_XONXOFF = 1,
 210         /** Hardware flow control using RTS/CTS signals. */
 211         SP_FLOWCONTROL_RTSCTS = 2,
 212         /** Hardware flow control using DTR/DSR signals. */
 213         SP_FLOWCONTROL_DTRDSR = 3,
 214 };
 215
 216 /** Input signals. */
 217 enum sp_signal {
 218         /** Clear to send. */
 219         SP_SIG_CTS = 1,
 220         /** Data set ready. */
 221         SP_SIG_DSR = 2,
 222         /** Data carrier detect. */
 223         SP_SIG_DCD = 4,
 224         /** Ring indicator. */
 225         SP_SIG_RI = 8,
 226 };
 227
 228 /** A serial port. */
 229 struct sp_port;
 230
 231 /** Configuration for a serial port. */
 232 struct sp_port_config {
 233         /** Baud rate in bits per second. */
 234         int baudrate;
 235         /** Number of data bits to use. Valid values are 5 to 8. */
 236         int bits;
 237         /** Parity setting to use. */
 238         enum sp_parity parity;
 239         /** Number of stop bits to use (1 or 2). */
 240         int stopbits;
 241         /** RTS pin mode. */
 242         enum sp_rts rts;
 243         /** CTS pin mode. */
 244         enum sp_cts cts;
 245         /** DTR pin mode. */
 246         enum sp_dtr dtr;
 247         /** DSR pin mode. */
 248         enum sp_dsr dsr;
 249         /** XON/XOFF flow control mode. */
 250         enum sp_xonxoff xon_xoff;
 251 };
 252
 253 /**
 254 @defgroup Enumeration Port enumeration
 255 @{
 256 */
 257
 258 /**
 259  * Obtain a pointer to a new sp_port structure representing the named port.
 260  *
 261  * The user should allocate a variable of type "struct sp_port *" and pass a
 262  * pointer to this to receive the result.
 263  *
 264  * The result should be freed after use by calling sp_free_port().
 265  *
 266  * If any error is returned, the variable pointed to by port_ptr will be set
 267  * to NULL. Otherwise, it will be set to point to the newly allocated port.
 268  *
 269  * @return SP_OK upon success, a negative error code otherwise.
 270  */
 271 enum sp_return sp_get_port_by_name(const char *portname, struct sp_port **port_ptr);
 272
 273 /**
 274  * Get the name of a port.
 275  *
 276  * The name returned is whatever is normally used to refer to a port on the
 277  * current operating system; e.g. for Windows it will usually be a "COMn"
 278  * device name, and for Unix it will be a device path beginning with "/dev/".
 279  *
 280  * @param port Pointer to port structure.
 281  *
 282  * @return The port name, or NULL if an invalid port is passed. The name
 283  * string is part of the port structure and may not be used after the
 284  * port structure has been freed.
 285  */
 286 char *sp_get_port_name(const struct sp_port *port);
 287
 288 /**
 289  * Get the operating system handle for a port.
 290  *
 291  * The type of the handle depends on the operating system. On Unix based
 292  * systems, the handle is a file descriptor of type "int". On Windows, the
 293  * handle is of type "HANDLE". The user should allocate a variable of the
 294  * appropriate type and pass a pointer to this to receive the result.
 295  *
 296  * To obtain a valid handle, the port must first be opened by calling
 297  * sp_open() using the same port structure.
 298  *
 299  * After the port is closed or the port structure freed, the handle may
 300  * no longer be valid.
 301  *
 302  * @warning This feature is provided so that programs may make use of
 303  *          OS-specific functionality where desired. Obviously this comes
 304  *          at a cost in portability, however it also cannot be guaranteed
 305  *          that direct usage of the OS handle will not conflict with the
 306  *          library's own usage of the port. Be careful.
 307  *
 308  * @return SP_OK upon success, a negative error code otherwise.
 309  */
 310 enum sp_return sp_get_port_handle(const struct sp_port *port, void *result);
 311
 312 /**
 313  * Free a port structure obtained from sp_get_port_by_name() or sp_copy_port().
 314  */
 315 void sp_free_port(struct sp_port *port);
 316
 317 /**
 318  * List the serial ports available on the system.
 319  *
 320  * The result obtained is an array of pointers to sp_port structures,
 321  * terminated by a NULL. The user should allocate a variable of type
 322  * "struct sp_port **" and pass a pointer to this to receive the result.
 323  *
 324  * The result should be freed after use by calling sp_free_port_list().
 325  * If a port from the list is to be used after freeing the list, it must be
 326  * copied first using sp_copy_port().
 327  *
 328  * If any error is returned, the variable pointed to by list_ptr will be set
 329  * to NULL. Otherwise, it will be set to point to the newly allocated array.
 330  *
 331  * @return SP_OK upon success, a negative error code otherwise.
 332  */
 333 enum sp_return sp_list_ports(struct sp_port ***list_ptr);
 334
 335 /**
 336  * Make a new copy of a sp_port structure.
 337  *
 338  * The user should allocate a variable of type "struct sp_port *" and pass a
 339  * pointer to this to receive the result.
 340  *
 341  * The copy should be freed after use by calling sp_free_port().
 342  *
 343  * If any error is returned, the variable pointed to by copy_ptr will be set
 344  * to NULL. Otherwise, it will be set to point to the newly allocated copy.
 345  *
 346  * @return SP_OK upon success, a negative error code otherwise.
 347  */
 348 enum sp_return sp_copy_port(const struct sp_port *port, struct sp_port **copy_ptr);
 349
 350 /**
 351  * Free a port list obtained from sp_list_ports().
 352  *
 353  * This will also free all the sp_port structures referred to from the list;
 354  * any that are to be retained must be copied first using sp_copy_port().
 355  */
 356 void sp_free_port_list(struct sp_port **ports);
 357
 358 /**
 359  * @}
 360  * @defgroup Ports Opening and closing ports
 361  * @{
 362  */
 363
 364 /**
 365  * Open the specified serial port.
 366  *
 367  * @param port Pointer to port structure.
 368  * @param flags Flags to use when opening the serial port.
 369  *
 370  * @return SP_OK upon success, a negative error code otherwise.
 371  */
 372 enum sp_return sp_open(struct sp_port *port, enum sp_mode flags);
 373
 374 /**
 375  * Close the specified serial port.
 376  *
 377  * @return SP_OK upon success, a negative error code otherwise.
 378  */
 379 enum sp_return sp_close(struct sp_port *port);
 380
 381 /**
 382  * @}
 383  * @defgroup Configuration Setting port parameters
 384  * @{
 385  */
 386
 387 /**
 388  * Get the current configuration of the specified serial port.
 389  *
 390  * The user should allocate a struct sp_port_config, then pass a pointer to it
 391  * as the config parameter. The struct will be populated with the port
 392  * configuration.
 393  *
 394  * Any setting that is in a state not recognised or supported by
 395  * libserialport will have its value set to -1 in the struct.
 396  *
 397  * @return SP_OK upon success, a negative error code otherwise.
 398  */
 399 enum sp_return sp_get_config(struct sp_port *port, struct sp_port_config *config);
 400
 401 /**
 402  * Set the configuration for the specified serial port.
 403  *
 404  * The user should populate a struct sp_port_config, then pass a pointer to it
 405  * as the config parameter.
 406  *
 407  * To retain the current value of any setting, set that field to -1.
 408  *
 409  * @return SP_OK upon success, a negative error code otherwise.
 410  */
 411 enum sp_return sp_set_config(struct sp_port *port, const struct sp_port_config *config);
 412
 413 /**
 414  * Set the baud rate for the specified serial port.
 415  *
 416  * @param port Pointer to port structure.
 417  * @param baudrate Baud rate in bits per second.
 418  *
 419  * @return SP_OK upon success, a negative error code otherwise.
 420  */
 421 enum sp_return sp_set_baudrate(struct sp_port *port, int baudrate);
 422
 423 /**
 424  * Set the number of data bits for the specified serial port.
 425  *
 426  * @param port Pointer to port structure.
 427  * @param bits Number of data bits to use. Valid values are 5 to 8.
 428  *
 429  * @return SP_OK upon success, a negative error code otherwise.
 430  */
 431 enum sp_return sp_set_bits(struct sp_port *port, int bits);
 432
 433 /**
 434  * Set the parity for the specified serial port.
 435  *
 436  * @param port Pointer to port structure.
 437  * @param parity Parity setting to use.
 438  *
 439  * @return SP_OK upon success, a negative error code otherwise.
 440  */
 441 enum sp_return sp_set_parity(struct sp_port *port, enum sp_parity parity);
 442
 443 /**
 444  * Set the number of stop bits for the specified port.
 445  *
 446  * @param port Pointer to port structure.
 447  * @param stopbits Number of stop bits to use (1 or 2).
 448  *
 449  * @return SP_OK upon success, a negative error code otherwise.
 450  */
 451 enum sp_return sp_set_stopbits(struct sp_port *port, int stopbits);
 452
 453 /**
 454  * Set the flow control type for the specified serial port.
 455  *
 456  * This function is a wrapper that sets the RTS, CTS, DTR, DSR and
 457  * XON/XOFF settings as necessary for the specified flow control
 458  * type. For more fine-grained control of these settings, use their
 459  * individual configuration functions or the sp_set_config() function.
 460  *
 461  * @param port Pointer to port structure.
 462  * @param flowcontrol Flow control setting to use.
 463  *
 464  * @return SP_OK upon success, a negative error code otherwise.
 465  */
 466 enum sp_return sp_set_flowcontrol(struct sp_port *port, enum sp_flowcontrol flowcontrol);
 467
 468 /**
 469  * Set the RTS pin behaviour for the specified port.
 470  *
 471  * @param port Pointer to port structure.
 472  * @param rts RTS pin mode.
 473  *
 474  * @return SP_OK upon success, a negative error code otherwise.
 475  */
 476 enum sp_return sp_set_rts(struct sp_port *port, enum sp_rts rts);
 477
 478 /**
 479  * Set the CTS pin behaviour for the specified port.
 480  *
 481  * @param port Pointer to port structure.
 482  * @param cts CTS pin mode.
 483  *
 484  * @return SP_OK upon success, a negative error code otherwise.
 485  */
 486 enum sp_return sp_set_cts(struct sp_port *port, enum sp_cts cts);
 487
 488 /**
 489  * Set the DTR pin behaviour for the specified port.
 490  *
 491  * @param port Pointer to port structure.
 492  * @param dtr DTR pin mode.
 493  *
 494  * @return SP_OK upon success, a negative error code otherwise.
 495  */
 496 enum sp_return sp_set_dtr(struct sp_port *port, enum sp_dtr dtr);
 497
 498 /**
 499  * Set the RTS pin behaviour for the specified port.
 500  *
 501  * @param port Pointer to port structure.
 502  * @param dsr DSR pin mode.
 503  *
 504  * @return SP_OK upon success, a negative error code otherwise.
 505  */
 506 enum sp_return sp_set_dsr(struct sp_port *port, enum sp_dsr dsr);
 507
 508 /**
 509  * Configure XON/XOFF flow control for the specified port.
 510  *
 511  * @param port Pointer to port structure.
 512  * @param xon_xoff XON/XOFF flow control mode.
 513  *
 514  * @return SP_OK upon success, a negative error code otherwise.
 515  */
 516 enum sp_return sp_set_xon_xoff(struct sp_port *port, enum sp_xonxoff xon_xoff);
 517
 518 /**
 519  * @}
 520  * @defgroup Data Reading, writing, and flushing data
 521  * @{
 522 */
 523
 524 /**
 525  * Read bytes from the specified serial port.
 526  *
 527  * Note that this function may return after reading less than the specified
 528  * number of bytes; it is the user's responsibility to iterate as necessary
 529  * in this case.
 530  *
 531  * @param port Pointer to port structure.
 532  * @param buf Buffer in which to store the bytes read.
 533  * @param count Maximum number of bytes to read.
 534  *
 535  * @return The number of bytes read on success, or a negative error code.
 536  */
 537 enum sp_return sp_read(struct sp_port *port, void *buf, size_t count);
 538
 539 /**
 540  * Write bytes to the specified serial port.
 541  *
 542  * Note that this function may return after writing less than the specified
 543  * number of bytes; it is the user's responsibility to iterate as necessary
 544  * in this case.
 545  *
 546  * @param port Pointer to port structure.
 547  * @param buf Buffer containing the bytes to write.
 548  * @param count Maximum number of bytes to write.
 549  *
 550  * @return The number of bytes written on success, or a negative error code.
 551  */
 552 enum sp_return sp_write(struct sp_port *port, const void *buf, size_t count);
 553
 554 /**
 555  * Flush serial port buffers. Data in the selected buffer(s) is discarded.
 556  *
 557  * @param port Pointer to port structure.
 558  * @param buffers Which buffer(s) to flush.
 559  *
 560  * @return SP_OK upon success, a negative error code otherwise.
 561  */
 562 enum sp_return sp_flush(struct sp_port *port, enum sp_buffer buffers);
 563
 564 /**
 565  * Wait for buffered data to be transmitted.
 566  *
 567  * @param port Pointer to port structure.
 568  *
 569  * @return SP_OK upon success, a negative error code otherwise.
 570  */
 571 enum sp_return sp_drain(struct sp_port *port);
 572
 573 /**
 574  * @}
 575  * @defgroup Signal Port signalling operations
 576  * @{
 577  */
 578
 579 /**
 580  * Gets the status of the control signals for the specified port.
 581  *
 582  * The user should allocate a variable of type "enum sp_signal" and pass a
 583  * pointer to this variable to receive the result. The result is a bitmask
 584  * in which individual signals can be checked by bitwise OR with values of
 585  * the sp_signal enum.
 586  *
 587  * @param port Pointer to port structure.
 588  * @param signals Pointer to variable to receive result.
 589  *
 590  * @return SP_OK upon success, a negative error code otherwise.
 591  */
 592 enum sp_return sp_get_signals(struct sp_port *port, enum sp_signal *signals);
 593
 594 /**
 595  * Put the port transmit line into the break state.
 596  *
 597  * @param port Pointer to port structure.
 598  *
 599  * @return SP_OK upon success, a negative error code otherwise.
 600  */
 601 enum sp_return sp_start_break(struct sp_port *port);
 602
 603 /**
 604  * Take the port transmit line out of the break state.
 605  *
 606  * @param port Pointer to port structure.
 607  *
 608  * @return SP_OK upon success, a negative error code otherwise.
 609  */
 610 enum sp_return sp_end_break(struct sp_port *port);
 611
 612 /**
 613  * @}
 614  * @defgroup Errors Obtaining error information
 615  * @{
 616 */
 617
 618 /**
 619  * Get the error code for a failed operation.
 620  *
 621  * In order to obtain the correct result, this function should be called
 622  * straight after the failure, before executing any other system operations.
 623  *
 624  * @return The system's numeric code for the error that caused the last
 625  *         operation to fail.
 626  */
 627 int sp_last_error_code(void);
 628
 629 /**
 630  * Get the error message for a failed operation.
 631  *
 632  * In order to obtain the correct result, this function should be called
 633  * straight after the failure, before executing other system operations.
 634  *
 635  * @return The system's message for the error that caused the last
 636  *         operation to fail. This string may be allocated by the function,
 637  *         and should be freed after use by calling sp_free_error_message().
 638  */
 639 char *sp_last_error_message(void);
 640
 641 /**
 642  * Free an error message returned by sp_last_error_message().
 643  */
 644 void sp_free_error_message(char *message);
 645
 646 /**
 647  * Set the handler function for library debugging messages.
 648  *
 649  * Debugging messages are generated by the library during each operation,
 650  * to help in diagnosing problems. The handler will be called for each
 651  * message. The handler can be set to NULL to ignore all debug messages.
 652  *
 653  * The handler function should accept a format string and variable length
 654  * argument list, in the same manner as e.g. printf().
 655  *
 656  * The default handler is sp_default_debug_handler().
 657  */
 658 void sp_set_debug_handler(void (*handler)(const char *format, ...));
 659
 660 /**
 661  * Default handler function for library debugging messages.
 662  *
 663  * This function prints debug messages to the standard error stream if the
 664  * environment variable LIBSERIALPORT_DEBUG is set. Otherwise, they are
 665  * ignored.
 666  */
 667 void sp_default_debug_handler(const char *format, ...);
 668
 669 /** @} */
 670
 671 #ifdef __cplusplus
 672 }
 673 #endif
 674
 675 #endif