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