libserialport 0.1.1
cross-platform library for accessing serial ports
Loading...
Searching...
No Matches
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.
 
#define SP_PACKAGE_VERSION_MINOR   1
 The libserialport package 'minor' version number.
 
#define SP_PACKAGE_VERSION_MICRO   1
 The libserialport package 'micro' version number.
 
#define SP_PACKAGE_VERSION_STRING   "0.1.1"
 The libserialport package version ("major.minor.micro") as string.
 
#define SP_LIB_VERSION_CURRENT   1
 The libserialport libtool 'current' version number.
 
#define SP_LIB_VERSION_REVISION   0
 The libserialport libtool 'revision' version number.
 
#define SP_LIB_VERSION_AGE   1
 The libserialport libtool 'age' version number.
 
#define SP_LIB_VERSION_STRING   "1:0:1"
 The libserialport libtool version ("current:revision:age") as string.
 

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.
 
void sp_free_port (struct sp_port *port)
 Free a port structure obtained from sp_get_port_by_name() or sp_copy_port().
 
enum sp_return sp_list_ports (struct sp_port ***list_ptr)
 List the serial ports available on the system.
 
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.
 
void sp_free_port_list (struct sp_port **ports)
 Free a port list obtained from sp_list_ports().
 
enum sp_return sp_open (struct sp_port *port, enum sp_mode flags)
 Open the specified serial port.
 
enum sp_return sp_close (struct sp_port *port)
 Close the specified serial port.
 
char * sp_get_port_name (const struct sp_port *port)
 Get the name of a port.
 
char * sp_get_port_description (const struct sp_port *port)
 Get a description for a port, to present to end user.
 
enum sp_transport sp_get_port_transport (const struct sp_port *port)
 Get the transport type used by a port.
 
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.
 
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.
 
char * sp_get_port_usb_manufacturer (const struct sp_port *port)
 Get the USB manufacturer string of a USB serial adapter port.
 
char * sp_get_port_usb_product (const struct sp_port *port)
 Get the USB product string of a USB serial adapter port.
 
char * sp_get_port_usb_serial (const struct sp_port *port)
 Get the USB serial number string of a USB serial adapter port.
 
char * sp_get_port_bluetooth_address (const struct sp_port *port)
 Get the MAC address of a Bluetooth serial adapter port.
 
enum sp_return sp_get_port_handle (const struct sp_port *port, void *result_ptr)
 Get the operating system handle for a port.
 
enum sp_return sp_new_config (struct sp_port_config **config_ptr)
 Allocate a port configuration structure.
 
void sp_free_config (struct sp_port_config *config)
 Free a port configuration structure.
 
enum sp_return sp_get_config (struct sp_port *port, struct sp_port_config *config)
 Get the current configuration of the specified serial port.
 
enum sp_return sp_set_config (struct sp_port *port, const struct sp_port_config *config)
 Set the configuration for the specified serial port.
 
enum sp_return sp_set_baudrate (struct sp_port *port, int baudrate)
 Set the baud rate for the specified serial port.
 
enum sp_return sp_get_config_baudrate (const struct sp_port_config *config, int *baudrate_ptr)
 Get the baud rate from a port configuration.
 
enum sp_return sp_set_config_baudrate (struct sp_port_config *config, int baudrate)
 Set the baud rate in a port configuration.
 
enum sp_return sp_set_bits (struct sp_port *port, int bits)
 Set the data bits for the specified serial port.
 
enum sp_return sp_get_config_bits (const struct sp_port_config *config, int *bits_ptr)
 Get the data bits from a port configuration.
 
enum sp_return sp_set_config_bits (struct sp_port_config *config, int bits)
 Set the data bits in a port configuration.
 
enum sp_return sp_set_parity (struct sp_port *port, enum sp_parity parity)
 Set the parity setting for the specified serial port.
 
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.
 
enum sp_return sp_set_config_parity (struct sp_port_config *config, enum sp_parity parity)
 Set the parity setting in a port configuration.
 
enum sp_return sp_set_stopbits (struct sp_port *port, int stopbits)
 Set the stop bits for the specified serial port.
 
enum sp_return sp_get_config_stopbits (const struct sp_port_config *config, int *stopbits_ptr)
 Get the stop bits from a port configuration.
 
enum sp_return sp_set_config_stopbits (struct sp_port_config *config, int stopbits)
 Set the stop bits in a port configuration.
 
enum sp_return sp_set_rts (struct sp_port *port, enum sp_rts rts)
 Set the RTS pin behaviour for the specified serial port.
 
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.
 
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.
 
enum sp_return sp_set_cts (struct sp_port *port, enum sp_cts cts)
 Set the CTS pin behaviour for the specified serial port.
 
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.
 
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.
 
enum sp_return sp_set_dtr (struct sp_port *port, enum sp_dtr dtr)
 Set the DTR pin behaviour for the specified serial port.
 
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.
 
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.
 
enum sp_return sp_set_dsr (struct sp_port *port, enum sp_dsr dsr)
 Set the DSR pin behaviour for the specified serial port.
 
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.
 
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.
 
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.
 
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.
 
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.
 
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.
 
enum sp_return sp_set_flowcontrol (struct sp_port *port, enum sp_flowcontrol flowcontrol)
 Set the flow control type for the specified serial port.
 
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.
 
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.
 
enum sp_return sp_nonblocking_read (struct sp_port *port, void *buf, size_t count)
 Read bytes from the specified serial port, without blocking.
 
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.
 
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.
 
enum sp_return sp_input_waiting (struct sp_port *port)
 Gets the number of bytes waiting in the input buffer.
 
enum sp_return sp_output_waiting (struct sp_port *port)
 Gets the number of bytes waiting in the output buffer.
 
enum sp_return sp_flush (struct sp_port *port, enum sp_buffer buffers)
 Flush serial port buffers.
 
enum sp_return sp_drain (struct sp_port *port)
 Wait for buffered data to be transmitted.
 
enum sp_return sp_new_event_set (struct sp_event_set **result_ptr)
 Allocate storage for a set of events.
 
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.
 
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.
 
void sp_free_event_set (struct sp_event_set *event_set)
 Free a structure allocated by sp_new_event_set().
 
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.
 
enum sp_return sp_start_break (struct sp_port *port)
 Put the port transmit line into the break state.
 
enum sp_return sp_end_break (struct sp_port *port)
 Take the port transmit line out of the break state.
 
int sp_last_error_code (void)
 Get the error code for a failed operation.
 
char * sp_last_error_message (void)
 Get the error message for a failed operation.
 
void sp_free_error_message (char *message)
 Free an error message returned by sp_last_error_message().
 
void sp_set_debug_handler (void(*handler)(const char *format,...))
 Set the handler function for library debugging messages.
 
void sp_default_debug_handler (const char *format,...)
 Default handler function for library debugging messages.
 
int sp_get_major_package_version (void)
 Get the major libserialport package version number.
 
int sp_get_minor_package_version (void)
 Get the minor libserialport package version number.
 
int sp_get_micro_package_version (void)
 Get the micro libserialport package version number.
 
const char * sp_get_package_version_string (void)
 Get the libserialport package version number as a string.
 
int sp_get_current_lib_version (void)
 Get the "current" part of the libserialport library version number.
 
int sp_get_revision_lib_version (void)
 Get the "revision" part of the libserialport library version number.
 
int sp_get_age_lib_version (void)
 Get the "age" part of the libserialport library version number.
 
const char * sp_get_lib_version_string (void)
 Get the libserialport library version number as a string.
 

Enumeration Type Documentation

◆ sp_buffer

enum sp_buffer

Buffer selection.

Enumerator
SP_BUF_INPUT 

Input buffer.

SP_BUF_OUTPUT 

Output buffer.

SP_BUF_BOTH 

Both buffers.

Definition at line 298 of file libserialport.h.

◆ sp_cts

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 336 of file libserialport.h.

◆ sp_dsr

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 358 of file libserialport.h.

◆ sp_dtr

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 346 of file libserialport.h.

◆ sp_event

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 288 of file libserialport.h.

◆ sp_flowcontrol

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 382 of file libserialport.h.

◆ sp_mode

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 278 of file libserialport.h.

◆ sp_parity

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 308 of file libserialport.h.

◆ sp_return

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 264 of file libserialport.h.

◆ sp_rts

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 324 of file libserialport.h.

◆ sp_signal

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 394 of file libserialport.h.

◆ sp_transport

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 410 of file libserialport.h.

◆ sp_xonxoff

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 368 of file libserialport.h.