change type of result variables to ssize_t

[libserialport.git] / libserialport.h

diff --git a/libserialport.h b/libserialport.h
index 33f3e9183313647f2217757121c144da64053589..7467f7438fb9fb878ccb817be4acce24f8779532 100644 (file)
--- a/libserialport.h
+++ b/libserialport.h
@@ -67,6 +67,10 @@
  *
  * - @ref list_ports.c - Getting a list of ports present on the system.
  * - @ref port_info.c - Getting information on a particular serial port.
+ * - @ref port_config.c - Accessing configuration settings of a port.
+ * - @ref send_receive.c - Sending and receiving data.
+ * - @ref await_events.c - Awaiting events on multiple ports.
+ * - @ref handle_errors.c - Handling errors returned from the library.
  *
  * These examples are linked with the API documentation. Each function
  * in the API reference includes links to where it is used in an example
@@ -760,6 +764,63 @@ SP_API enum sp_return sp_get_port_handle(const struct sp_port *port, void *resul
  * @defgroup Configuration Configuration
  *
  * Setting and querying serial port parameters.
+ *
+ * See @ref 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 @ref 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:
+ *
+ * Configuration structures
+ * ------------------------
+ *
+ * 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.
+ *
+ * Direct functions for changing port settings
+ * -------------------------------------------
+ *
+ * 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.
+ *
  * @{
  */
 
@@ -1229,6 +1290,8 @@ SP_API enum sp_return sp_set_flowcontrol(struct sp_port *port, enum sp_flowcontr
  *
  * Reading, writing, and flushing data.
  *
+ * See @ref send_receive.c for an example of sending and receiving data.
+ *
  * @{
  */
 
@@ -1419,6 +1482,8 @@ SP_API enum sp_return sp_drain(struct sp_port *port);
  *
  * Waiting for events and timeout handling.
  *
+ * See @ref await_events.c for an example of awaiting events on multiple ports.
+ *
  * @{
  */
 
@@ -1538,6 +1603,8 @@ SP_API enum sp_return sp_end_break(struct sp_port *port);
  *
  * Obtaining error information.
  *
+ * See @ref handle_errors.c for an example of error handling.
+ *
  * @{
  */
 
@@ -1747,6 +1814,10 @@ SP_API const char *sp_get_lib_version_string(void);
 /**
  * @example list_ports.c Getting a list of ports present on the system.
  * @example port_info.c Getting information on a particular serial port.
+ * @example port_config.c Accessing configuration settings of a port.
+ * @example send_receive.c Sending and receiving data.
+ * @example await_events.c Awaiting events on multiple ports.
+ * @example handle_errors.c Handling errors returned from the library.
 */
 
 #ifdef __cplusplus