libserialport  unreleased development snapshot
cross-platform library for accessing serial ports
Data Structures | Macros | Enumerations | Functions
libserialport.h File Reference
#include <stddef.h>
+ Include dependency graph for libserialport.h:

Go to the source code of this file.

Data Structures

struct  sp_event_set
 A set of handles to wait on for events. More...
 

Macros

#define SP_PACKAGE_VERSION_MAJOR   0
 The libserialport package 'major' version number. More...
 
#define SP_PACKAGE_VERSION_MINOR   1
 The libserialport package 'minor' version number. More...
 
#define SP_PACKAGE_VERSION_MICRO   1
 The libserialport package 'micro' version number. More...
 
#define SP_PACKAGE_VERSION_STRING   "0.1.1"
 The libserialport package version ("major.minor.micro") as string. More...
 
#define SP_LIB_VERSION_CURRENT   1
 The libserialport libtool 'current' version number. More...
 
#define SP_LIB_VERSION_REVISION   0
 The libserialport libtool 'revision' version number. More...
 
#define SP_LIB_VERSION_AGE   1
 The libserialport libtool 'age' version number. More...
 
#define SP_LIB_VERSION_STRING   "1:0:1"
 The libserialport libtool version ("current:revision:age") as string. More...
 

Enumerations

enum  sp_return {
  SP_OK = 0,
  SP_ERR_ARG = -1,
  SP_ERR_FAIL = -2,
  SP_ERR_MEM = -3,
  SP_ERR_SUPP = -4
}
 Return values. More...
 
enum  sp_mode {
  SP_MODE_READ = 1,
  SP_MODE_WRITE = 2,
  SP_MODE_READ_WRITE = 3
}
 Port access modes. More...
 
enum  sp_event {
  SP_EVENT_RX_READY = 1,
  SP_EVENT_TX_READY = 2,
  SP_EVENT_ERROR = 4
}
 Port events. More...
 
enum  sp_buffer {
  SP_BUF_INPUT = 1,
  SP_BUF_OUTPUT = 2,
  SP_BUF_BOTH = 3
}
 Buffer selection. More...
 
enum  sp_parity {
  SP_PARITY_INVALID = -1,
  SP_PARITY_NONE = 0,
  SP_PARITY_ODD = 1,
  SP_PARITY_EVEN = 2,
  SP_PARITY_MARK = 3,
  SP_PARITY_SPACE = 4
}
 Parity settings. More...
 
enum  sp_rts {
  SP_RTS_INVALID = -1,
  SP_RTS_OFF = 0,
  SP_RTS_ON = 1,
  SP_RTS_FLOW_CONTROL = 2
}
 RTS pin behaviour. More...
 
enum  sp_cts {
  SP_CTS_INVALID = -1,
  SP_CTS_IGNORE = 0,
  SP_CTS_FLOW_CONTROL = 1
}
 CTS pin behaviour. More...
 
enum  sp_dtr {
  SP_DTR_INVALID = -1,
  SP_DTR_OFF = 0,
  SP_DTR_ON = 1,
  SP_DTR_FLOW_CONTROL = 2
}
 DTR pin behaviour. More...
 
enum  sp_dsr {
  SP_DSR_INVALID = -1,
  SP_DSR_IGNORE = 0,
  SP_DSR_FLOW_CONTROL = 1
}
 DSR pin behaviour. More...
 
enum  sp_xonxoff {
  SP_XONXOFF_INVALID = -1,
  SP_XONXOFF_DISABLED = 0,
  SP_XONXOFF_IN = 1,
  SP_XONXOFF_OUT = 2,
  SP_XONXOFF_INOUT = 3
}
 XON/XOFF flow control behaviour. More...
 
enum  sp_flowcontrol {
  SP_FLOWCONTROL_NONE = 0,
  SP_FLOWCONTROL_XONXOFF = 1,
  SP_FLOWCONTROL_RTSCTS = 2,
  SP_FLOWCONTROL_DTRDSR = 3
}
 Standard flow control combinations. More...
 
enum  sp_signal {
  SP_SIG_CTS = 1,
  SP_SIG_DSR = 2,
  SP_SIG_DCD = 4,
  SP_SIG_RI = 8
}
 Input signals. More...
 
enum  sp_transport {
  SP_TRANSPORT_NATIVE,
  SP_TRANSPORT_USB,
  SP_TRANSPORT_BLUETOOTH
}
 Transport types. More...
 

Functions

enum sp_return sp_get_port_by_name (const char *portname, struct sp_port **port_ptr)
 Obtain a pointer to a new sp_port structure representing the named port. More...
 
void sp_free_port (struct sp_port *port)
 Free a port structure obtained from sp_get_port_by_name() or sp_copy_port(). More...
 
enum sp_return sp_list_ports (struct sp_port ***list_ptr)
 List the serial ports available on the system. More...
 
enum sp_return sp_copy_port (const struct sp_port *port, struct sp_port **copy_ptr)
 Make a new copy of an sp_port structure. More...
 
void sp_free_port_list (struct sp_port **ports)
 Free a port list obtained from sp_list_ports(). More...
 
enum sp_return sp_open (struct sp_port *port, enum sp_mode flags)
 Open the specified serial port. More...
 
enum sp_return sp_close (struct sp_port *port)
 Close the specified serial port. More...
 
char * sp_get_port_name (const struct sp_port *port)
 Get the name of a port. More...
 
char * sp_get_port_description (const struct sp_port *port)
 Get a description for a port, to present to end user. More...
 
enum sp_transport sp_get_port_transport (const struct sp_port *port)
 Get the transport type used by a port. More...
 
enum sp_return sp_get_port_usb_bus_address (const struct sp_port *port, int *usb_bus, int *usb_address)
 Get the USB bus number and address on bus of a USB serial adapter port. More...
 
enum sp_return sp_get_port_usb_vid_pid (const struct sp_port *port, int *usb_vid, int *usb_pid)
 Get the USB Vendor ID and Product ID of a USB serial adapter port. More...
 
char * sp_get_port_usb_manufacturer (const struct sp_port *port)
 Get the USB manufacturer string of a USB serial adapter port. More...
 
char * sp_get_port_usb_product (const struct sp_port *port)
 Get the USB product string of a USB serial adapter port. More...
 
char * sp_get_port_usb_serial (const struct sp_port *port)
 Get the USB serial number string of a USB serial adapter port. More...
 
char * sp_get_port_bluetooth_address (const struct sp_port *port)
 Get the MAC address of a Bluetooth serial adapter port. More...
 
enum sp_return sp_get_port_handle (const struct sp_port *port, void *result_ptr)
 Get the operating system handle for a port. More...
 
enum sp_return sp_new_config (struct sp_port_config **config_ptr)
 Allocate a port configuration structure. More...
 
void sp_free_config (struct sp_port_config *config)
 Free a port configuration structure. More...
 
enum sp_return sp_get_config (struct sp_port *port, struct sp_port_config *config)
 Get the current configuration of the specified serial port. More...
 
enum sp_return sp_set_config (struct sp_port *port, const struct sp_port_config *config)
 Set the configuration for the specified serial port. More...
 
enum sp_return sp_set_baudrate (struct sp_port *port, int baudrate)
 Set the baud rate for the specified serial port. More...
 
enum sp_return sp_get_config_baudrate (const struct sp_port_config *config, int *baudrate_ptr)
 Get the baud rate from a port configuration. More...
 
enum sp_return sp_set_config_baudrate (struct sp_port_config *config, int baudrate)
 Set the baud rate in a port configuration. More...
 
enum sp_return sp_set_bits (struct sp_port *port, int bits)
 Set the data bits for the specified serial port. More...
 
enum sp_return sp_get_config_bits (const struct sp_port_config *config, int *bits_ptr)
 Get the data bits from a port configuration. More...
 
enum sp_return sp_set_config_bits (struct sp_port_config *config, int bits)
 Set the data bits in a port configuration. More...
 
enum sp_return sp_set_parity (struct sp_port *port, enum sp_parity parity)
 Set the parity setting for the specified serial port. More...
 
enum sp_return sp_get_config_parity (const struct sp_port_config *config, enum sp_parity *parity_ptr)
 Get the parity setting from a port configuration. More...
 
enum sp_return sp_set_config_parity (struct sp_port_config *config, enum sp_parity parity)
 Set the parity setting in a port configuration. More...
 
enum sp_return sp_set_stopbits (struct sp_port *port, int stopbits)
 Set the stop bits for the specified serial port. More...
 
enum sp_return sp_get_config_stopbits (const struct sp_port_config *config, int *stopbits_ptr)
 Get the stop bits from a port configuration. More...
 
enum sp_return sp_set_config_stopbits (struct sp_port_config *config, int stopbits)
 Set the stop bits in a port configuration. More...
 
enum sp_return sp_set_rts (struct sp_port *port, enum sp_rts rts)
 Set the RTS pin behaviour for the specified serial port. More...
 
enum sp_return sp_get_config_rts (const struct sp_port_config *config, enum sp_rts *rts_ptr)
 Get the RTS pin behaviour from a port configuration. More...
 
enum sp_return sp_set_config_rts (struct sp_port_config *config, enum sp_rts rts)
 Set the RTS pin behaviour in a port configuration. More...
 
enum sp_return sp_set_cts (struct sp_port *port, enum sp_cts cts)
 Set the CTS pin behaviour for the specified serial port. More...
 
enum sp_return sp_get_config_cts (const struct sp_port_config *config, enum sp_cts *cts_ptr)
 Get the CTS pin behaviour from a port configuration. More...
 
enum sp_return sp_set_config_cts (struct sp_port_config *config, enum sp_cts cts)
 Set the CTS pin behaviour in a port configuration. More...
 
enum sp_return sp_set_dtr (struct sp_port *port, enum sp_dtr dtr)
 Set the DTR pin behaviour for the specified serial port. More...
 
enum sp_return sp_get_config_dtr (const struct sp_port_config *config, enum sp_dtr *dtr_ptr)
 Get the DTR pin behaviour from a port configuration. More...
 
enum sp_return sp_set_config_dtr (struct sp_port_config *config, enum sp_dtr dtr)
 Set the DTR pin behaviour in a port configuration. More...
 
enum sp_return sp_set_dsr (struct sp_port *port, enum sp_dsr dsr)
 Set the DSR pin behaviour for the specified serial port. More...
 
enum sp_return sp_get_config_dsr (const struct sp_port_config *config, enum sp_dsr *dsr_ptr)
 Get the DSR pin behaviour from a port configuration. More...
 
enum sp_return sp_set_config_dsr (struct sp_port_config *config, enum sp_dsr dsr)
 Set the DSR pin behaviour in a port configuration. More...
 
enum sp_return sp_set_xon_xoff (struct sp_port *port, enum sp_xonxoff xon_xoff)
 Set the XON/XOFF configuration for the specified serial port. More...
 
enum sp_return sp_get_config_xon_xoff (const struct sp_port_config *config, enum sp_xonxoff *xon_xoff_ptr)
 Get the XON/XOFF configuration from a port configuration. More...
 
enum sp_return sp_set_config_xon_xoff (struct sp_port_config *config, enum sp_xonxoff xon_xoff)
 Set the XON/XOFF configuration in a port configuration. More...
 
enum sp_return sp_set_config_flowcontrol (struct sp_port_config *config, enum sp_flowcontrol flowcontrol)
 Set the flow control type in a port configuration. More...
 
enum sp_return sp_set_flowcontrol (struct sp_port *port, enum sp_flowcontrol flowcontrol)
 Set the flow control type for the specified serial port. More...
 
enum sp_return sp_blocking_read (struct sp_port *port, void *buf, size_t count, unsigned int timeout_ms)
 Read bytes from the specified serial port, blocking until complete. More...
 
enum sp_return sp_blocking_read_next (struct sp_port *port, void *buf, size_t count, unsigned int timeout_ms)
 Read bytes from the specified serial port, returning as soon as any data is available. More...
 
enum sp_return sp_nonblocking_read (struct sp_port *port, void *buf, size_t count)
 Read bytes from the specified serial port, without blocking. More...
 
enum sp_return sp_blocking_write (struct sp_port *port, const void *buf, size_t count, unsigned int timeout_ms)
 Write bytes to the specified serial port, blocking until complete. More...
 
enum sp_return sp_nonblocking_write (struct sp_port *port, const void *buf, size_t count)
 Write bytes to the specified serial port, without blocking. More...
 
enum sp_return sp_input_waiting (struct sp_port *port)
 Gets the number of bytes waiting in the input buffer. More...
 
enum sp_return sp_output_waiting (struct sp_port *port)
 Gets the number of bytes waiting in the output buffer. More...
 
enum sp_return sp_flush (struct sp_port *port, enum sp_buffer buffers)
 Flush serial port buffers. More...
 
enum sp_return sp_drain (struct sp_port *port)
 Wait for buffered data to be transmitted. More...
 
enum sp_return sp_new_event_set (struct sp_event_set **result_ptr)
 Allocate storage for a set of events. More...
 
enum sp_return sp_add_port_events (struct sp_event_set *event_set, const struct sp_port *port, enum sp_event mask)
 Add events to a struct sp_event_set for a given port. More...
 
enum sp_return sp_wait (struct sp_event_set *event_set, unsigned int timeout_ms)
 Wait for any of a set of events to occur. More...
 
void sp_free_event_set (struct sp_event_set *event_set)
 Free a structure allocated by sp_new_event_set(). More...
 
enum sp_return sp_get_signals (struct sp_port *port, enum sp_signal *signal_mask)
 Gets the status of the control signals for the specified port. More...
 
enum sp_return sp_start_break (struct sp_port *port)
 Put the port transmit line into the break state. More...
 
enum sp_return sp_end_break (struct sp_port *port)
 Take the port transmit line out of the break state. More...
 
int sp_last_error_code (void)
 Get the error code for a failed operation. More...
 
char * sp_last_error_message (void)
 Get the error message for a failed operation. More...
 
void sp_free_error_message (char *message)
 Free an error message returned by sp_last_error_message(). More...
 
void sp_set_debug_handler (void(*handler)(const char *format,...))
 Set the handler function for library debugging messages. More...
 
void sp_default_debug_handler (const char *format,...)
 Default handler function for library debugging messages. More...
 
int sp_get_major_package_version (void)
 Get the major libserialport package version number. More...
 
int sp_get_minor_package_version (void)
 Get the minor libserialport package version number. More...
 
int sp_get_micro_package_version (void)
 Get the micro libserialport package version number. More...
 
const char * sp_get_package_version_string (void)
 Get the libserialport package version number as a string. More...
 
int sp_get_current_lib_version (void)
 Get the "current" part of the libserialport library version number. More...
 
int sp_get_revision_lib_version (void)
 Get the "revision" part of the libserialport library version number. More...
 
int sp_get_age_lib_version (void)
 Get the "age" part of the libserialport library version number. More...
 
const char * sp_get_lib_version_string (void)
 Get the libserialport library version number as a string. More...
 

Enumeration Type Documentation

enum sp_buffer

Buffer selection.

Enumerator
SP_BUF_INPUT 

Input buffer.

SP_BUF_OUTPUT 

Output buffer.

SP_BUF_BOTH 

Both buffers.

Definition at line 335 of file libserialport.h.

enum sp_cts

CTS pin behaviour.

Enumerator
SP_CTS_INVALID 

Special value to indicate setting should be left alone.

SP_CTS_IGNORE 

CTS ignored.

SP_CTS_FLOW_CONTROL 

CTS used for flow control.

Definition at line 373 of file libserialport.h.

enum sp_dsr

DSR pin behaviour.

Enumerator
SP_DSR_INVALID 

Special value to indicate setting should be left alone.

SP_DSR_IGNORE 

DSR ignored.

SP_DSR_FLOW_CONTROL 

DSR used for flow control.

Definition at line 395 of file libserialport.h.

enum sp_dtr

DTR pin behaviour.

Enumerator
SP_DTR_INVALID 

Special value to indicate setting should be left alone.

SP_DTR_OFF 

DTR off.

SP_DTR_ON 

DTR on.

SP_DTR_FLOW_CONTROL 

DTR used for flow control.

Definition at line 383 of file libserialport.h.

enum sp_event

Port events.

Enumerator
SP_EVENT_RX_READY 

Data received and ready to read.

SP_EVENT_TX_READY 

Ready to transmit new data.

SP_EVENT_ERROR 

Error occurred.

Definition at line 325 of file libserialport.h.

Standard flow control combinations.

Enumerator
SP_FLOWCONTROL_NONE 

No flow control.

SP_FLOWCONTROL_XONXOFF 

Software flow control using XON/XOFF characters.

SP_FLOWCONTROL_RTSCTS 

Hardware flow control using RTS/CTS signals.

SP_FLOWCONTROL_DTRDSR 

Hardware flow control using DTR/DSR signals.

Definition at line 419 of file libserialport.h.

enum sp_mode

Port access modes.

Enumerator
SP_MODE_READ 

Open port for read access.

SP_MODE_WRITE 

Open port for write access.

SP_MODE_READ_WRITE 

Open port for read and write access.

Since
0.1.1

Definition at line 315 of file libserialport.h.

enum sp_parity

Parity settings.

Enumerator
SP_PARITY_INVALID 

Special value to indicate setting should be left alone.

SP_PARITY_NONE 

No parity.

SP_PARITY_ODD 

Odd parity.

SP_PARITY_EVEN 

Even parity.

SP_PARITY_MARK 

Mark parity.

SP_PARITY_SPACE 

Space parity.

Definition at line 345 of file libserialport.h.

enum sp_return

Return values.

Enumerator
SP_OK 

Operation completed successfully.

SP_ERR_ARG 

Invalid arguments were passed to the function.

SP_ERR_FAIL 

A system error occurred while executing the operation.

SP_ERR_MEM 

A memory allocation failed while executing the operation.

SP_ERR_SUPP 

The requested operation is not supported by this system or device.

Definition at line 301 of file libserialport.h.

enum sp_rts

RTS pin behaviour.

Enumerator
SP_RTS_INVALID 

Special value to indicate setting should be left alone.

SP_RTS_OFF 

RTS off.

SP_RTS_ON 

RTS on.

SP_RTS_FLOW_CONTROL 

RTS used for flow control.

Definition at line 361 of file libserialport.h.

enum sp_signal

Input signals.

Enumerator
SP_SIG_CTS 

Clear to send.

SP_SIG_DSR 

Data set ready.

SP_SIG_DCD 

Data carrier detect.

SP_SIG_RI 

Ring indicator.

Definition at line 431 of file libserialport.h.

Transport types.

Since
0.1.1
Enumerator
SP_TRANSPORT_NATIVE 

Native platform serial port.

Since
0.1.1
SP_TRANSPORT_USB 

USB serial port adapter.

Since
0.1.1
SP_TRANSPORT_BLUETOOTH 

Bluetooth serial port adapter.

Since
0.1.1

Definition at line 447 of file libserialport.h.

enum sp_xonxoff

XON/XOFF flow control behaviour.

Enumerator
SP_XONXOFF_INVALID 

Special value to indicate setting should be left alone.

SP_XONXOFF_DISABLED 

XON/XOFF disabled.

SP_XONXOFF_IN 

XON/XOFF enabled for input only.

SP_XONXOFF_OUT 

XON/XOFF enabled for output only.

SP_XONXOFF_INOUT 

XON/XOFF enabled for input and output.

Definition at line 405 of file libserialport.h.