|
libserialport
unreleased development snapshot
cross-platform library for accessing serial ports
|
|
libserialport
unreleased development snapshot
cross-platform library for accessing serial ports
|
Setting and querying serial port parameters. More...
Functions | |
| 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... | |
Setting and querying serial port parameters.
See port_config.c for a working example of port configuration.
You should always configure all settings before using a port. There are no default settings applied by libserialport. When you open a port it may have default settings from the OS or driver, or the settings left over by the last program to use it.
You should always set baud rate, data bits, parity and stop bits.
You should normally also set one of the preset sp_flowcontrol flow control modes, which will set up the RTS, CTS, DTR and DSR pin behaviours and enable or disable XON/XOFF. If you need an unusual configuration not covered by the preset flow control modes, you will need to configure these settings individually, and avoid calling sp_set_flowcontrol() or sp_set_config_flowcontrol() which will overwrite these settings.
A port must be opened before you can change its settings.
There are two ways of accessing port settings:
You can read and write a whole configuration (all settings at once) using sp_get_config() and sp_set_config(). This is handy if you want to change between some preset combinations, or save and restore an existing configuration. It also ensures the changes are made together, via an efficient set of calls into the OS - in some cases a single system call can be used.
Use accessor functions like sp_get_config_baudrate() and sp_set_config_baudrate() to get and set individual settings from a configuration.
For each setting in a port configuration, a special value of -1 can be used, which will cause that setting to be left alone when the configuration is applied by sp_set_config().
This value is also be used by sp_get_config() for any settings which are unconfigured at the OS level, or in a state that is not representable within the libserialport API.
Configurations are allocated using sp_new_config() and freed with sp_free_config(). You need to manage them yourself. When a new configuration is allocated by sp_new_config(), all of its settings are initially set to the special -1 value.
As a shortcut, you can set individual settings on a port directly by calling functions like sp_set_baudrate() and sp_set_parity(). This saves you the work of allocating a temporary config, setting it up, applying it to a port and then freeing it.
| void sp_free_config | ( | struct sp_port_config * | config | ) |
Free a port configuration structure.
| [in] | config | Pointer to a configuration structure. Must not be NULL. |
| enum sp_return sp_get_config | ( | struct sp_port * | port, |
| struct sp_port_config * | config | ||
| ) |
Get the current configuration of the specified serial port.
The user should allocate a configuration structure using sp_new_config() and pass this as the config parameter. The configuration structure will be updated with the port configuration.
Any parameters that are configured with settings not recognised or supported by libserialport, will be set to special values that are ignored by sp_set_config().
| [in] | port | Pointer to a port structure. Must not be NULL. |
| [out] | config | Pointer to a configuration structure that will hold the result. Upon errors the contents of the config struct will not be changed. Must not be NULL. |
| enum sp_return sp_get_config_baudrate | ( | const struct sp_port_config * | config, |
| int * | baudrate_ptr | ||
| ) |
Get the baud rate from a port configuration.
The user should allocate a variable of type int and pass a pointer to this to receive the result.
| [in] | config | Pointer to a configuration structure. Must not be NULL. |
| [out] | baudrate_ptr | Pointer to a variable to store the result. Must not be NULL. |
| enum sp_return sp_get_config_bits | ( | const struct sp_port_config * | config, |
| int * | bits_ptr | ||
| ) |
Get the data bits from a port configuration.
The user should allocate a variable of type int and pass a pointer to this to receive the result.
| [in] | config | Pointer to a configuration structure. Must not be NULL. |
| [out] | bits_ptr | Pointer to a variable to store the result. Must not be NULL. |
| 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.
The user should allocate a variable of type enum sp_cts and pass a pointer to this to receive the result.
| [in] | config | Pointer to a configuration structure. Must not be NULL. |
| [out] | cts_ptr | Pointer to a variable to store the result. Must not be NULL. |
| 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.
The user should allocate a variable of type enum sp_dsr and pass a pointer to this to receive the result.
| [in] | config | Pointer to a configuration structure. Must not be NULL. |
| [out] | dsr_ptr | Pointer to a variable to store the result. Must not be NULL. |
| 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.
The user should allocate a variable of type enum sp_dtr and pass a pointer to this to receive the result.
| [in] | config | Pointer to a configuration structure. Must not be NULL. |
| [out] | dtr_ptr | Pointer to a variable to store the result. Must not be NULL. |
| 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.
The user should allocate a variable of type enum sp_parity and pass a pointer to this to receive the result.
| [in] | config | Pointer to a configuration structure. Must not be NULL. |
| [out] | parity_ptr | Pointer to a variable to store the result. Must not be NULL. |
| 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.
The user should allocate a variable of type enum sp_rts and pass a pointer to this to receive the result.
| [in] | config | Pointer to a configuration structure. Must not be NULL. |
| [out] | rts_ptr | Pointer to a variable to store the result. Must not be NULL. |
| enum sp_return sp_get_config_stopbits | ( | const struct sp_port_config * | config, |
| int * | stopbits_ptr | ||
| ) |
Get the stop bits from a port configuration.
The user should allocate a variable of type int and pass a pointer to this to receive the result.
| [in] | config | Pointer to a configuration structure. Must not be NULL. |
| [out] | stopbits_ptr | Pointer to a variable to store the result. Must not be NULL. |
| 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.
The user should allocate a variable of type enum sp_xonxoff and pass a pointer to this to receive the result.
| [in] | config | Pointer to a configuration structure. Must not be NULL. |
| [out] | xon_xoff_ptr | Pointer to a variable to store the result. Must not be NULL. |
| enum sp_return sp_new_config | ( | struct sp_port_config ** | config_ptr | ) |
Allocate a port configuration structure.
The user should allocate a variable of type "struct sp_port_config *" and pass a pointer to this to receive the result. The variable will be updated to point to the new configuration structure. The structure is opaque and must be accessed via the functions provided.
All parameters in the structure will be initialised to special values which are ignored by sp_set_config().
The structure should be freed after use by calling sp_free_config().
| [out] | config_ptr | If any error is returned, the variable pointed to by config_ptr will be set to NULL. Otherwise, it will be set to point to the allocated config structure. Must not be NULL. |
Set the baud rate for the specified serial port.
| [in] | port | Pointer to a port structure. Must not be NULL. |
| [in] | baudrate | Baud rate in bits per second. |
Set the data bits for the specified serial port.
| [in] | port | Pointer to a port structure. Must not be NULL. |
| [in] | bits | Number of data bits. |
| enum sp_return sp_set_config | ( | struct sp_port * | port, |
| const struct sp_port_config * | config | ||
| ) |
Set the configuration for the specified serial port.
For each parameter in the configuration, there is a special value (usually -1, but see the documentation for each field). These values will be ignored and the corresponding setting left unchanged on the port.
Upon errors, the configuration of the serial port is unknown since partial/incomplete config updates may have happened.
| [in] | port | Pointer to a port structure. Must not be NULL. |
| [in] | config | Pointer to a configuration structure. Must not be NULL. |
| enum sp_return sp_set_config_baudrate | ( | struct sp_port_config * | config, |
| int | baudrate | ||
| ) |
Set the baud rate in a port configuration.
| [in] | config | Pointer to a configuration structure. Must not be NULL. |
| [in] | baudrate | Baud rate in bits per second, or -1 to retain the current setting. |
| enum sp_return sp_set_config_bits | ( | struct sp_port_config * | config, |
| int | bits | ||
| ) |
Set the data bits in a port configuration.
| [in] | config | Pointer to a configuration structure. Must not be NULL. |
| [in] | bits | Number of data bits, or -1 to retain the current setting. |
| 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.
| [in] | config | Pointer to a configuration structure. Must not be NULL. |
| [in] | cts | CTS pin mode, or -1 to retain the current setting. |
| 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.
| [in] | config | Pointer to a configuration structure. Must not be NULL. |
| [in] | dsr | DSR pin mode, or -1 to retain the current setting. |
| 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.
| [in] | config | Pointer to a configuration structure. Must not be NULL. |
| [in] | dtr | DTR pin mode, or -1 to retain the current setting. |
| 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.
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.
| [in] | config | Pointer to a configuration structure. Must not be NULL. |
| [in] | flowcontrol | Flow control setting to use. |
| enum sp_return sp_set_config_parity | ( | struct sp_port_config * | config, |
| enum sp_parity | parity | ||
| ) |
Set the parity setting in a port configuration.
| [in] | config | Pointer to a configuration structure. Must not be NULL. |
| [in] | parity | Parity setting, or -1 to retain the current setting. |
| 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.
| [in] | config | Pointer to a configuration structure. Must not be NULL. |
| [in] | rts | RTS pin mode, or -1 to retain the current setting. |
| enum sp_return sp_set_config_stopbits | ( | struct sp_port_config * | config, |
| int | stopbits | ||
| ) |
Set the stop bits in a port configuration.
| [in] | config | Pointer to a configuration structure. Must not be NULL. |
| [in] | stopbits | Number of stop bits, or -1 to retain the current setting. |
| 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.
| [in] | config | Pointer to a configuration structure. Must not be NULL. |
| [in] | xon_xoff | XON/XOFF mode, or -1 to retain the current setting. |
Set the CTS pin behaviour for the specified serial port.
| [in] | port | Pointer to a port structure. Must not be NULL. |
| [in] | cts | CTS pin mode. |
Set the DSR pin behaviour for the specified serial port.
| [in] | port | Pointer to a port structure. Must not be NULL. |
| [in] | dsr | DSR pin mode. |
Set the DTR pin behaviour for the specified serial port.
| [in] | port | Pointer to a port structure. Must not be NULL. |
| [in] | dtr | DTR pin mode. |
| enum sp_return sp_set_flowcontrol | ( | struct sp_port * | port, |
| enum sp_flowcontrol | flowcontrol | ||
| ) |
Set 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.
| [in] | port | Pointer to a port structure. Must not be NULL. |
| [in] | flowcontrol | Flow control setting to use. |
Set the parity setting for the specified serial port.
| [in] | port | Pointer to a port structure. Must not be NULL. |
| [in] | parity | Parity setting. |
Set the RTS pin behaviour for the specified serial port.
| [in] | port | Pointer to a port structure. Must not be NULL. |
| [in] | rts | RTS pin mode. |
Set the stop bits for the specified serial port.
| [in] | port | Pointer to a port structure. Must not be NULL. |
| [in] | stopbits | Number of stop bits. |
| 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.
| [in] | port | Pointer to a port structure. Must not be NULL. |
| [in] | xon_xoff | XON/XOFF mode. |
1.8.11
