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