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         /** Special value to indicate setting should be left alone. */
 116         SP_PARITY_INVALID = -1,
 117         /** No parity. */
 118         SP_PARITY_NONE = 0,
 119         /** Even parity. */
 120         SP_PARITY_EVEN = 1,
 121         /** Odd parity. */
 122         SP_PARITY_ODD = 2,
 123 };
 124
 125 /** RTS pin behaviour. */
 126 enum sp_rts {
 127         /** Special value to indicate setting should be left alone. */
 128         SP_RTS_INVALID = -1,
 129         /** RTS off. */
 130         SP_RTS_OFF = 0,
 131         /** RTS on. */
 132         SP_RTS_ON = 1,
 133         /** RTS used for flow control. */
 134         SP_RTS_FLOW_CONTROL = 2
 135 };
 136
 137 /** CTS pin behaviour. */
 138 enum sp_cts {
 139         /** Special value to indicate setting should be left alone. */
 140         SP_CTS_INVALID = -1,
 141         /** CTS ignored. */
 142         SP_CTS_IGNORE = 0,
 143         /** CTS used for flow control. */
 144         SP_CTS_FLOW_CONTROL = 1
 145 };
 146
 147 /** DTR pin behaviour. */
 148 enum sp_dtr {
 149         /** Special value to indicate setting should be left alone. */
 150         SP_DTR_INVALID = -1,
 151         /** DTR off. */
 152         SP_DTR_OFF = 0,
 153         /** DTR on. */
 154         SP_DTR_ON = 1,
 155         /** DTR used for flow control. */
 156         SP_DTR_FLOW_CONTROL = 2
 157 };
 158
 159 /** DSR pin behaviour. */
 160 enum sp_dsr {
 161         /** Special value to indicate setting should be left alone. */
 162         SP_DSR_INVALID = -1,
 163         /** DSR ignored. */
 164         SP_DSR_IGNORE = 0,
 165         /** DSR used for flow control. */
 166         SP_DSR_FLOW_CONTROL = 1
 167 };
 168
 169 /** XON/XOFF flow control behaviour. */
 170 enum sp_xonxoff {
 171         /** Special value to indicate setting should be left alone. */
 172         SP_XONXOFF_INVALID = -1,
 173         /** XON/XOFF disabled. */
 174         SP_XONXOFF_DISABLED = 0,
 175         /** XON/XOFF enabled for input only. */
 176         SP_XONXOFF_IN = 1,
 177         /** XON/XOFF enabled for output only. */
 178         SP_XONXOFF_OUT = 2,
 179         /** XON/XOFF enabled for input and output. */
 180         SP_XONXOFF_INOUT = 3
 181 };
 182
 183 /** Standard flow control combinations. */
 184 enum sp_flowcontrol {
 185         /** No flow control. */
 186         SP_FLOWCONTROL_NONE = 0,
 187         /** Software flow control using XON/XOFF characters. */
 188         SP_FLOWCONTROL_XONXOFF = 1,
 189         /** Hardware flow control using RTS/CTS signals. */
 190         SP_FLOWCONTROL_RTSCTS = 2,
 191         /** Hardware flow control using DTR/DSR signals. */
 192         SP_FLOWCONTROL_DTRDSR = 3
 193 };
 194
 195 /** A serial port. */
 196 struct sp_port {
 197         /** Name used to open the port */
 198         char *name;
 199 /** \cond 0 */
 200         /* OS-specific port handle */
 201 #ifdef _WIN32
 202         HANDLE hdl;
 203 #else
 204         int fd;
 205 #endif
 206 /** \endcond */
 207 };
 208
 209 /** Configuration for a serial port. */
 210 struct sp_port_config {
 211         /** Baud rate in bits per second. */
 212         int baudrate;
 213         /** Number of data bits to use. Valid values are 5 to 8. */
 214         int bits;
 215         /** Parity setting to use. */
 216         enum sp_parity parity;
 217         /** Number of stop bits to use (1 or 2). */
 218         int stopbits;
 219         /** RTS pin mode. */
 220         enum sp_rts rts;
 221         /** CTS pin mode. */
 222         enum sp_cts cts;
 223         /** DTR pin mode. */
 224         enum sp_dtr dtr;
 225         /** DSR pin mode. */
 226         enum sp_dsr dsr;
 227         /** XON/XOFF flow control mode. */
 228         enum sp_xonxoff xon_xoff;
 229 };
 230
 231 /**
 232 \defgroup Enumeration Port enumeration
 233 @{
 234 */
 235
 236 /**
 237  Obtains a pointer to a new sp_port structure representing the named port. The
 238  user should allocate a variable of type "struct sp_port *" and pass a pointer
 239  to this to receive the result.
 240
 241  The result should be freed after use by calling sp_free_port().
 242
 243  @return  SP_OK on success, SP_ERR_FAIL on failure, SP_ERR_MEM on allocation
 244           failure, or SP_ERR_ARG if an invalid pointer is passed. If any error
 245           is returned, the variable pointed to by port_ptr will be set to NULL.
 246           Otherwise, it will be set to point to the newly allocated port.
 247 */
 248 enum sp_return sp_get_port_by_name(const char *portname, struct sp_port **port_ptr);
 249
 250 /**
 251 Frees a port structure obtained from sp_get_port_by_name() or sp_copy_port().
 252 */
 253 void sp_free_port(struct sp_port *port);
 254
 255 /**
 256  Lists the serial ports available on the system. The result obtained is an
 257  array of pointers to sp_port structures, terminated by a NULL. The user should
 258  allocate a variable of type "struct sp_port **" and pass a pointer to this to
 259  receive the result.
 260
 261  The result should be freed after use by calling sp_free_port_list(). If a port
 262  from the list is to be used after freeing the list, it must be copied first
 263  using sp_copy_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 list_ptr will be set to NULL.
 268           Otherwise, it will be set to point to the newly allocated array.
 269 */
 270 enum sp_return sp_list_ports(struct sp_port ***list_ptr);
 271
 272 /**
 273  Makes a new copy of a sp_port structure. The user should allocate a variable
 274  of type "struct sp_port *" and pass a pointer to this to receive the result.
 275
 276  The copy should be freed after use by calling sp_free_port().
 277
 278  @return  SP_OK on success, SP_ERR_MEM on allocation failure, or SP_ERR_ARG
 279           if an invalid port or pointer is passed. If any error is returned,
 280           the variable pointed to by copy_ptr will be set to NULL. Otherwise,
 281           it will be set to point to the newly allocated copy.
 282 */
 283 enum sp_return sp_copy_port(const struct sp_port *port, struct sp_port **copy_ptr);
 284
 285 /**
 286  Frees a port list obtained from sp_list_ports(). This will also free all
 287  the sp_port structures referred to from the list; any that are to be retained
 288  must be copied first using sp_copy_port().
 289 */
 290 void sp_free_port_list(struct sp_port **ports);
 291
 292 /**
 293  @}
 294 \defgroup Ports Opening & closing ports
 295 @{
 296 */
 297
 298 /**
 299  Opens the specified serial port.
 300
 301  @param port      Pointer to port structure.
 302  @param flags     Flags to use when opening the serial port.
 303
 304  @return  SP_OK on success, SP_ERR_FAIL on failure, SP_ERR_MEM on allocation
 305           failure, or SP_ERR_ARG if an invalid port is passed.
 306 */
 307 enum sp_return sp_open(struct sp_port *port, enum sp_mode flags);
 308
 309 /**
 310  Closes the specified serial port.
 311
 312  @return  SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 313           if an invalid port is passed.
 314 */
 315 enum sp_return sp_close(struct sp_port *port);
 316
 317 /**
 318  @}
 319 \defgroup Configuration Setting port parameters
 320 @{
 321 */
 322
 323 /**
 324  Gets current configuration of the specified serial port.
 325
 326  The user should allocate a struct sp_port_config, then pass a pointer to it
 327  as the config parameter. The struct will be populated with the port
 328  configuration.
 329
 330  Any setting that is in a state not recognised or supported by
 331  libserialport will have its value set to -1 in the struct.
 332
 333  @return  SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 334           for invalid arguments.
 335 */
 336 enum sp_return sp_get_config(struct sp_port *port, struct sp_port_config *config);
 337
 338 /**
 339  Sets configuration for the specified serial port.
 340
 341  The user should populate a struct sp_port_config, then pass a pointer to it
 342  as the config parameter.
 343
 344  To retain the current value of any setting, set that field to -1.
 345
 346  @return  SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 347           for invalid arguments.
 348 */
 349 enum sp_return sp_set_config(struct sp_port *port, const struct sp_port_config *config);
 350
 351 /**
 352  Sets the baud rate for the specified serial port.
 353
 354  @param port Pointer to port structure.
 355  @param baudrate Baud rate in bits per second.
 356
 357  @return  SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 358           for invalid arguments.
 359 */
 360 enum sp_return sp_set_baudrate(struct sp_port *port, int baudrate);
 361
 362 /**
 363  Sets the number of data bits for the specified serial port.
 364
 365  @param port Pointer to port structure.
 366  @param bits Number of data bits to use. Valid values are 5 to 8.
 367
 368  @return  SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 369           for invalid arguments.
 370 */
 371 enum sp_return sp_set_bits(struct sp_port *port, int bits);
 372
 373 /**
 374  Sets the parity for the specified serial port.
 375
 376  @param port   Pointer to port structure.
 377  @param parity Parity setting to use.
 378
 379  @return  SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 380           for invalid arguments.
 381 */
 382 enum sp_return sp_set_parity(struct sp_port *port, enum sp_parity parity);
 383
 384 /**
 385  Sets the number of stop bits for the specified port.
 386
 387  @param port     Pointer to port structure.
 388  @param stopbits Number of stop bits to use (1 or 2).
 389
 390  @return  SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 391           for invalid arguments.
 392 */
 393 enum sp_return sp_set_stopbits(struct sp_port *port, int stopbits);
 394
 395 /**
 396  Sets the flow control type for the specified serial port.
 397
 398  This function is a wrapper that sets the RTS, CTS, DTR, DSR and
 399  XON/XOFF settings as necessary for the specified flow control
 400  type. For more fine-grained control of these settings, use their
 401  individual configuration functions or the sp_set_config() function.
 402
 403  @param port        Pointer to port structure.
 404  @param flowcontrol Flow control setting to use.
 405
 406  @return  SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 407           for invalid arguments.
 408 */
 409 enum sp_return sp_set_flowcontrol(struct sp_port *port, enum sp_flowcontrol flowcontrol);
 410
 411 /**
 412  Sets the RTS pin behaviour for the specified port.
 413
 414  @param port Pointer to port structure.
 415  @param rts  RTS pin mode.
 416
 417  @return  SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 418           for invalid arguments.
 419 */
 420 enum sp_return sp_set_rts(struct sp_port *port, enum sp_rts rts);
 421
 422 /**
 423  Sets the CTS pin behaviour for the specified port.
 424
 425  @param port Pointer to port structure.
 426  @param cts  CTS pin mode.
 427
 428  @return  SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 429           for invalid arguments.
 430 */
 431 enum sp_return sp_set_cts(struct sp_port *port, enum sp_cts cts);
 432
 433 /**
 434  Sets the DTR pin behaviour for the specified port.
 435
 436  @param port Pointer to port structure.
 437  @param dtr  DTR pin mode.
 438
 439  @return  SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 440           for invalid arguments.
 441 */
 442 enum sp_return sp_set_dtr(struct sp_port *port, enum sp_dtr dtr);
 443
 444 /**
 445  Sets the RTS pin behaviour for the specified port.
 446
 447  @param port Pointer to port structure.
 448  @param dsr  DSR pin mode.
 449
 450  @return  SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 451           for invalid arguments.
 452 */
 453 enum sp_return sp_set_dsr(struct sp_port *port, enum sp_dsr dsr);
 454
 455 /**
 456  Configures XON/XOFF flow control for the specified port.
 457
 458  @param port     Pointer to port structure.
 459  @param xon_xoff XON/XOFF flow control mode.
 460
 461  @return  SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 462           for invalid arguments.
 463 */
 464 enum sp_return sp_set_xon_xoff(struct sp_port *port, enum sp_xonxoff xon_xoff);
 465
 466 /**
 467  @}
 468 \defgroup Data Reading, writing & flushing data
 469 @{
 470 */
 471
 472 /**
 473  Reads bytes from the specified serial port. Note that this function may
 474  return after reading less than the specified number of bytes; it is the
 475  user's responsibility to iterate as necessary in this case.
 476
 477  @param port  Pointer to port structure.
 478  @param buf   Buffer in which to store the bytes read.
 479  @param count Maximum number of bytes to read.
 480
 481  @return  The number of bytes read, SP_ERR_FAIL on failure,
 482           or SP_ERR_ARG for invalid arguments.
 483 */
 484 enum sp_return sp_read(struct sp_port *port, void *buf, size_t count);
 485
 486 /**
 487  Write bytes to the specified serial port. Note that this function may
 488  return after writing less than the specified number of bytes; it is the
 489  user's responsibility to iterate as necessary in this case.
 490
 491  @param port  Pointer to port structure.
 492  @param buf   Buffer containing the bytes to write.
 493  @param count Maximum number of bytes to write.
 494
 495  @return  The number of bytes written, SP_ERR_FAIL on failure,
 496           or SP_ERR_ARG for invalid arguments.
 497 */
 498 enum sp_return sp_write(struct sp_port *port, const void *buf, size_t count);
 499
 500 /**
 501  Flushes serial port buffers.
 502
 503  @return  SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 504           if an invalid port is passed.
 505 */
 506 enum sp_return sp_flush(struct sp_port *port);
 507
 508 /**
 509  @}
 510 \defgroup Errors Obtaining error information
 511 @{
 512 */
 513
 514 /**
 515  Gets the error code for a failed operation.
 516
 517  In order to obtain the correct result, this function should be called
 518  straight after the failure, before executing any other system operations.
 519
 520  @return  The system's numeric code for the error that caused the last
 521           operation to fail.
 522 */
 523 int sp_last_error_code(void);
 524
 525 /**
 526  Gets the error message for a failed operation.
 527
 528  In order to obtain the correct result, this function should be called
 529  straight after the failure, before executing other system operations.
 530
 531  @return  The system's message for the error that caused the last
 532           operation to fail. This string may be allocated by the function,
 533           and should be freed after use by calling sp_free_error_message.
 534 */
 535 char *sp_last_error_message(void);
 536
 537 /**
 538  Frees an error message returned by sp_last_error_message().
 539 */
 540 void sp_free_error_message(char *message);
 541
 542 /**
 543  @}
 544 */
 545
 546 #ifdef __cplusplus
 547 }
 548 #endif
 549
 550 #endif /* LIBSERIALPORT_H */
 551