The operations that are supported are:
-- Port enumeration (obtaining a list of serial ports on the system).
-- Opening and closing ports.
-- Setting port parameters (baud rate, parity, etc).
-- Reading, writing and flushing data.
-- Obtaining error information.
+- \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
-===
+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.
+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
/** Parity settings. */
enum sp_parity {
+ /** Special value to indicate setting should be left alone. */
SP_PARITY_INVALID = -1,
/** No parity. */
SP_PARITY_NONE = 0,
/** 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,
/** 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,
/** 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,
/** 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,
/** 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,
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
*/
void sp_free_port_list(struct sp_port **ports);
+/**
+ @}
+\defgroup Ports Opening & closing ports
+@{
+*/
+
/**
Opens the specified serial port.
enum sp_return sp_close(struct sp_port *port);
/**
- 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.
+ @}
+\defgroup Configuration Setting port parameters
+@{
*/
-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);
/**
Gets current configuration of the specified serial port.
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 all parameters for the specified serial port.
+ 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 the field to to a
- negative value.
+ 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_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.
*/
void sp_free_error_message(char *message);
+/**
+ @}
+*/
+
#ifdef __cplusplus
}
#endif