Consistently use the "@" notation for Doxygen tags.

[libserialport.git] / libserialport.h.in

/*
 * This file is part of the libserialport project.
 *
 * Copyright (C) 2013 Martin Ling <martin-libserialport@earth.li>
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation, either version 3 of the
 * License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

/**

@mainpage libserialport API

Introduction
============

libserialport is a minimal library written in C that is intended to take care
of the OS-specific details when writing software that uses serial ports.

By writing your serial code to use libserialport, you enable it to work
transparently on any platform supported by the library.

The operations that are supported are:

- @ref Enumeration (obtaining a list of serial ports on the system).
- @ref Ports
- @ref Configuration (baud rate, parity, etc)
- @ref Data
- @ref Errors

libserialport is an open source project released under the LGPL3+ license.

API principles
==============

The API is simple, and designed to be a minimal wrapper around the serial port
support in each OS.

Most functions take a pointer to a struct sp_port, which represents a serial
port. These structures are always allocated and freed by the library, using
the functions in the @ref Enumeration "Enumeration" section.

All functions can return only three possible error values. SP_ERR_ARG indicates
the function was called with invalid arguments. SP_ERR_FAIL indicates that the
OS reported a failure. SP_ERR_MEM indicates that a memory allocation failed.
All of these error values are negative.

When SP_ERR_FAIL is returned, an error code or string description of the error
can be obtained by calling sp_last_error_code() or sp_last_error_message(). The
error code or message is that provided by the OS; libserialport does not define
any error codes or messages of its own.

Function calls that succeed return SP_OK, which is equal to zero, or where
otherwise documented a positive value.

*/

#ifndef LIBSERIALPORT_H
#define LIBSERIALPORT_H

#ifdef __cplusplus
extern "C" {
#endif

#include <stddef.h>
#ifdef _WIN32
#include <windows.h>
#endif

/* Package version macros (e.g. for conditional compilation). */
#define SP_PACKAGE_VERSION_MAJOR @SP_PACKAGE_VERSION_MAJOR@
#define SP_PACKAGE_VERSION_MINOR @SP_PACKAGE_VERSION_MINOR@
#define SP_PACKAGE_VERSION_STRING "@SP_PACKAGE_VERSION@"

/* Library/libtool version macros (e.g. for conditional compilation). */
#define SP_LIB_VERSION_CURRENT @SP_LIB_VERSION_CURRENT@
#define SP_LIB_VERSION_REVISION @SP_LIB_VERSION_REVISION@
#define SP_LIB_VERSION_AGE @SP_LIB_VERSION_AGE@
#define SP_LIB_VERSION_STRING "@SP_LIB_VERSION@"

/** Return values. */
enum sp_return {
	/** Operation completed successfully. */
	SP_OK = 0,
	/** Invalid arguments were passed to the function. */
	SP_ERR_ARG = -1,
	/** A system error occured while executing the operation. */
	SP_ERR_FAIL = -2,
	/** A memory allocation failed while executing the operation. */
	SP_ERR_MEM = -3,
};

/** Port access modes. */
enum sp_mode {
	/** Open port for read/write access. */
	SP_MODE_RDWR = 1,
	/** Open port for read access only. */
	SP_MODE_RDONLY = 2,
	/** Open port in non-blocking mode. */
	SP_MODE_NONBLOCK = 4,
};

/** Parity settings. */
enum sp_parity {
	/** Special value to indicate setting should be left alone. */
	SP_PARITY_INVALID = -1,
	/** No parity. */
	SP_PARITY_NONE = 0,
	/** Even parity. */
	SP_PARITY_EVEN = 1,
	/** Odd parity. */
	SP_PARITY_ODD = 2,
};

/** RTS pin behaviour. */
enum sp_rts {
	/** Special value to indicate setting should be left alone. */
	SP_RTS_INVALID = -1,
	/** RTS off. */
	SP_RTS_OFF = 0,
	/** RTS on. */
	SP_RTS_ON = 1,
	/** RTS used for flow control. */
	SP_RTS_FLOW_CONTROL = 2
};

/** CTS pin behaviour. */
enum sp_cts {
	/** Special value to indicate setting should be left alone. */
	SP_CTS_INVALID = -1,
	/** CTS ignored. */
	SP_CTS_IGNORE = 0,
	/** CTS used for flow control. */
	SP_CTS_FLOW_CONTROL = 1
};

/** DTR pin behaviour. */
enum sp_dtr {
	/** Special value to indicate setting should be left alone. */
	SP_DTR_INVALID = -1,
	/** DTR off. */
	SP_DTR_OFF = 0,
	/** DTR on. */
	SP_DTR_ON = 1,
	/** DTR used for flow control. */
	SP_DTR_FLOW_CONTROL = 2
};

/** DSR pin behaviour. */
enum sp_dsr {
	/** Special value to indicate setting should be left alone. */
	SP_DSR_INVALID = -1,
	/** DSR ignored. */
	SP_DSR_IGNORE = 0,
	/** DSR used for flow control. */
	SP_DSR_FLOW_CONTROL = 1
};

/** XON/XOFF flow control behaviour. */
enum sp_xonxoff {
	/** Special value to indicate setting should be left alone. */
	SP_XONXOFF_INVALID = -1,
	/** XON/XOFF disabled. */
	SP_XONXOFF_DISABLED = 0,
	/** XON/XOFF enabled for input only. */
	SP_XONXOFF_IN = 1,
	/** XON/XOFF enabled for output only. */
	SP_XONXOFF_OUT = 2,
	/** XON/XOFF enabled for input and output. */
	SP_XONXOFF_INOUT = 3
};

/** Standard flow control combinations. */
enum sp_flowcontrol {
	/** No flow control. */
	SP_FLOWCONTROL_NONE = 0,
	/** Software flow control using XON/XOFF characters. */
	SP_FLOWCONTROL_XONXOFF = 1,
	/** Hardware flow control using RTS/CTS signals. */
	SP_FLOWCONTROL_RTSCTS = 2,
	/** Hardware flow control using DTR/DSR signals. */
	SP_FLOWCONTROL_DTRDSR = 3
};

/** A serial port. */
struct sp_port {
	/** Name used to open the port */
	char *name;
/** @cond 0 */
	/* OS-specific port handle */
#ifdef _WIN32
	HANDLE hdl;
#else
	int fd;
#endif
/** @endcond */
};

/** Configuration for a serial port. */
struct sp_port_config {
	/** Baud rate in bits per second. */
	int baudrate;
	/** Number of data bits to use. Valid values are 5 to 8. */
	int bits;
	/** Parity setting to use. */
	enum sp_parity parity;
	/** Number of stop bits to use (1 or 2). */
	int stopbits;
	/** RTS pin mode. */
	enum sp_rts rts;
	/** CTS pin mode. */
	enum sp_cts cts;
	/** DTR pin mode. */
	enum sp_dtr dtr;
	/** DSR pin mode. */
	enum sp_dsr dsr;
	/** XON/XOFF flow control mode. */
	enum sp_xonxoff xon_xoff;
};

/**
@defgroup Enumeration Port enumeration
@{
*/

/**
 Obtains a pointer to a new sp_port structure representing the named port. The
 user should allocate a variable of type "struct sp_port *" and pass a pointer
 to this to receive the result.

 The result should be freed after use by calling sp_free_port().
 
 @return  SP_OK on success, SP_ERR_FAIL on failure, SP_ERR_MEM on allocation
          failure, or SP_ERR_ARG if an invalid pointer is passed. If any error
          is returned, the variable pointed to by port_ptr will be set to NULL.
          Otherwise, it will be set to point to the newly allocated port.
*/
enum sp_return sp_get_port_by_name(const char *portname, struct sp_port **port_ptr);

/**
Frees a port structure obtained from sp_get_port_by_name() or sp_copy_port().
*/
void sp_free_port(struct sp_port *port);

/**
 Lists the serial ports available on the system. The result obtained is an
 array of pointers to sp_port structures, terminated by a NULL. The user should
 allocate a variable of type "struct sp_port **" and pass a pointer to this to
 receive the result.

 The result should be freed after use by calling sp_free_port_list(). If a port
 from the list is to be used after freeing the list, it must be copied first
 using sp_copy_port().

 @return  SP_OK on success, SP_ERR_FAIL on failure, SP_ERR_MEM on allocation
          failure, or SP_ERR_ARG if an invalid pointer is passed. If any error
          is returned, the variable pointed to by list_ptr will be set to NULL.
          Otherwise, it will be set to point to the newly allocated array.
*/
enum sp_return sp_list_ports(struct sp_port ***list_ptr);

/**
 Makes a new copy of a sp_port structure. The user should allocate a variable
 of type "struct sp_port *" and pass a pointer to this to receive the result.

 The copy should be freed after use by calling sp_free_port().

 @return  SP_OK on success, SP_ERR_MEM on allocation failure, or SP_ERR_ARG
          if an invalid port or pointer is passed. If any error is returned,
          the variable pointed to by copy_ptr will be set to NULL. Otherwise,
          it will be set to point to the newly allocated copy.
*/
enum sp_return sp_copy_port(const struct sp_port *port, struct sp_port **copy_ptr);

/**
 Frees a port list obtained from sp_list_ports(). This will also free all
 the sp_port structures referred to from the list; any that are to be retained
 must be copied first using sp_copy_port().
*/
void sp_free_port_list(struct sp_port **ports);

/**
 @}
@defgroup Ports Opening & closing ports
@{
*/

/**
 Opens the specified serial port.

 @param port      Pointer to port structure.
 @param flags     Flags to use when opening the serial port.

 @return  SP_OK on success, SP_ERR_FAIL on failure, SP_ERR_MEM on allocation
          failure, or SP_ERR_ARG if an invalid port is passed.
*/
enum sp_return sp_open(struct sp_port *port, enum sp_mode flags);

/**
 Closes the specified serial port.

 @return  SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
          if an invalid port is passed.
*/
enum sp_return sp_close(struct sp_port *port);

/**
 @}
@defgroup Configuration Setting port parameters
@{
*/

/**
 Gets current configuration of the specified serial port.

 The user should allocate a struct sp_port_config, then pass a pointer to it
 as the config parameter. The struct will be populated with the port
 configuration.

 Any setting that is in a state not recognised or supported by
 libserialport will have its value set to -1 in the struct.

 @return  SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
          for invalid arguments.
*/
enum sp_return sp_get_config(struct sp_port *port, struct sp_port_config *config);

/**
 Sets configuration for the specified serial port.

 The user should populate a struct sp_port_config, then pass a pointer to it
 as the config parameter.

 To retain the current value of any setting, set that field to -1.

 @return  SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
          for invalid arguments.
*/
enum sp_return sp_set_config(struct sp_port *port, const struct sp_port_config *config);

/**
 Sets the baud rate for the specified serial port.

 @param port Pointer to port structure.
 @param baudrate Baud rate in bits per second.

 @return  SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
          for invalid arguments.
*/
enum sp_return sp_set_baudrate(struct sp_port *port, int baudrate);

/**
 Sets the number of data bits for the specified serial port.

 @param port Pointer to port structure.
 @param bits Number of data bits to use. Valid values are 5 to 8.

 @return  SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
          for invalid arguments.
*/
enum sp_return sp_set_bits(struct sp_port *port, int bits);

/**
 Sets the parity for the specified serial port.

 @param port   Pointer to port structure.
 @param parity Parity setting to use.

 @return  SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
          for invalid arguments.
*/
enum sp_return sp_set_parity(struct sp_port *port, enum sp_parity parity);

/**
 Sets the number of stop bits for the specified port.

 @param port     Pointer to port structure.
 @param stopbits Number of stop bits to use (1 or 2).

 @return  SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
          for invalid arguments.
*/
enum sp_return sp_set_stopbits(struct sp_port *port, int stopbits);

/**
 Sets the flow control type for the specified serial port.

 This function is a wrapper that sets the RTS, CTS, DTR, DSR and
 XON/XOFF settings as necessary for the specified flow control
 type. For more fine-grained control of these settings, use their
 individual configuration functions or the sp_set_config() function.

 @param port        Pointer to port structure.
 @param flowcontrol Flow control setting to use.

 @return  SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
          for invalid arguments.
*/
enum sp_return sp_set_flowcontrol(struct sp_port *port, enum sp_flowcontrol flowcontrol);

/**
 Sets the RTS pin behaviour for the specified port.

 @param port Pointer to port structure.
 @param rts  RTS pin mode.

 @return  SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
          for invalid arguments.
*/
enum sp_return sp_set_rts(struct sp_port *port, enum sp_rts rts);

/**
 Sets the CTS pin behaviour for the specified port.

 @param port Pointer to port structure.
 @param cts  CTS pin mode.

 @return  SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
          for invalid arguments.
*/
enum sp_return sp_set_cts(struct sp_port *port, enum sp_cts cts);

/**
 Sets the DTR pin behaviour for the specified port.

 @param port Pointer to port structure.
 @param dtr  DTR pin mode.

 @return  SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
          for invalid arguments.
*/
enum sp_return sp_set_dtr(struct sp_port *port, enum sp_dtr dtr);

/**
 Sets the RTS pin behaviour for the specified port.

 @param port Pointer to port structure.
 @param dsr  DSR pin mode.

 @return  SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
          for invalid arguments.
*/
enum sp_return sp_set_dsr(struct sp_port *port, enum sp_dsr dsr);

/**
 Configures XON/XOFF flow control for the specified port.

 @param port     Pointer to port structure.
 @param xon_xoff XON/XOFF flow control mode.

 @return  SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
          for invalid arguments.
*/
enum sp_return sp_set_xon_xoff(struct sp_port *port, enum sp_xonxoff xon_xoff);

/**
 @}
@defgroup Data Reading, writing & flushing data
@{
*/

/**
 Reads bytes from the specified serial port. Note that this function may
 return after reading less than the specified number of bytes; it is the
 user's responsibility to iterate as necessary in this case.

 @param port  Pointer to port structure.
 @param buf   Buffer in which to store the bytes read.
 @param count Maximum number of bytes to read.

 @return  The number of bytes read, SP_ERR_FAIL on failure,
          or SP_ERR_ARG for invalid arguments.
*/
enum sp_return sp_read(struct sp_port *port, void *buf, size_t count);

/**
 Write bytes to the specified serial port. Note that this function may
 return after writing less than the specified number of bytes; it is the
 user's responsibility to iterate as necessary in this case.

 @param port  Pointer to port structure.
 @param buf   Buffer containing the bytes to write.
 @param count Maximum number of bytes to write.

 @return  The number of bytes written, SP_ERR_FAIL on failure,
          or SP_ERR_ARG for invalid arguments.
*/
enum sp_return sp_write(struct sp_port *port, const void *buf, size_t count);

/**
 Flushes serial port buffers.

 @return  SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
          if an invalid port is passed.
*/
enum sp_return sp_flush(struct sp_port *port);

/**
 @}
@defgroup Errors Obtaining error information
@{
*/

/**
 Gets the error code for a failed operation.

 In order to obtain the correct result, this function should be called
 straight after the failure, before executing any other system operations.

 @return  The system's numeric code for the error that caused the last
          operation to fail.
*/
int sp_last_error_code(void);

/**
 Gets the error message for a failed operation.

 In order to obtain the correct result, this function should be called
 straight after the failure, before executing other system operations.

 @return  The system's message for the error that caused the last
          operation to fail. This string may be allocated by the function,
          and should be freed after use by calling sp_free_error_message.
*/
char *sp_last_error_message(void);

/**
 Frees an error message returned by sp_last_error_message().
*/
void sp_free_error_message(char *message);

/**
 @}
*/

#ifdef __cplusplus
}
#endif

#endif /* LIBSERIALPORT_H */