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