*
* - @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
#include <stddef.h>
+/** @cond */
+#ifdef _MSC_VER
+/* Microsoft Visual C/C++ compiler in use */
+#ifdef LIBSERIALPORT_MSBUILD
+/* Building the library - need to export DLL symbols */
+#define SP_API __declspec(dllexport)
+#else
+/* Using the library - need to import DLL symbols */
+#define SP_API __declspec(dllimport)
+#endif
+#else
+/* Some other compiler in use */
+#ifndef LIBSERIALPORT_ATBUILD
+/* Not building the library itself - don't need any special prefixes. */
+#define SP_API
+#endif
+#endif
+/** @endcond */
+
/** Return values. */
enum sp_return {
/** Operation completed successfully. */
*
* @since 0.1.0
*/
-enum sp_return sp_get_port_by_name(const char *portname, struct sp_port **port_ptr);
+SP_API enum sp_return sp_get_port_by_name(const char *portname, struct sp_port **port_ptr);
/**
* Free a port structure obtained from sp_get_port_by_name() or sp_copy_port().
*
* @since 0.1.0
*/
-void sp_free_port(struct sp_port *port);
+SP_API void sp_free_port(struct sp_port *port);
/**
* List the serial ports available on the system.
*
* @since 0.1.0
*/
-enum sp_return sp_list_ports(struct sp_port ***list_ptr);
+SP_API enum sp_return sp_list_ports(struct sp_port ***list_ptr);
/**
* Make a new copy of an sp_port structure.
*
* @since 0.1.0
*/
-enum sp_return sp_copy_port(const struct sp_port *port, struct sp_port **copy_ptr);
+SP_API enum sp_return sp_copy_port(const struct sp_port *port, struct sp_port **copy_ptr);
/**
* Free a port list obtained from sp_list_ports().
*
* @since 0.1.0
*/
-void sp_free_port_list(struct sp_port **ports);
+SP_API void sp_free_port_list(struct sp_port **ports);
/**
* @}
*
* @since 0.1.0
*/
-enum sp_return sp_open(struct sp_port *port, enum sp_mode flags);
+SP_API enum sp_return sp_open(struct sp_port *port, enum sp_mode flags);
/**
* Close the specified serial port.
*
* @since 0.1.0
*/
-enum sp_return sp_close(struct sp_port *port);
+SP_API enum sp_return sp_close(struct sp_port *port);
/**
* Get the name of a port.
*
* @since 0.1.0
*/
-char *sp_get_port_name(const struct sp_port *port);
+SP_API char *sp_get_port_name(const struct sp_port *port);
/**
* Get a description for a port, to present to end user.
*
* @since 0.1.1
*/
-char *sp_get_port_description(const struct sp_port *port);
+SP_API char *sp_get_port_description(const struct sp_port *port);
/**
* Get the transport type used by a port.
*
* @since 0.1.1
*/
-enum sp_transport sp_get_port_transport(const struct sp_port *port);
+SP_API enum sp_transport sp_get_port_transport(const struct sp_port *port);
/**
* Get the USB bus number and address on bus of a USB serial adapter port.
*
* @since 0.1.1
*/
-enum sp_return sp_get_port_usb_bus_address(const struct sp_port *port,
+SP_API enum sp_return sp_get_port_usb_bus_address(const struct sp_port *port,
int *usb_bus, int *usb_address);
/**
*
* @since 0.1.1
*/
-enum sp_return sp_get_port_usb_vid_pid(const struct sp_port *port, int *usb_vid, int *usb_pid);
+SP_API enum sp_return sp_get_port_usb_vid_pid(const struct sp_port *port, int *usb_vid, int *usb_pid);
/**
* Get the USB manufacturer string of a USB serial adapter port.
*
* @since 0.1.1
*/
-char *sp_get_port_usb_manufacturer(const struct sp_port *port);
+SP_API char *sp_get_port_usb_manufacturer(const struct sp_port *port);
/**
* Get the USB product string of a USB serial adapter port.
*
* @since 0.1.1
*/
-char *sp_get_port_usb_product(const struct sp_port *port);
+SP_API char *sp_get_port_usb_product(const struct sp_port *port);
/**
* Get the USB serial number string of a USB serial adapter port.
*
* @since 0.1.1
*/
-char *sp_get_port_usb_serial(const struct sp_port *port);
+SP_API char *sp_get_port_usb_serial(const struct sp_port *port);
/**
* Get the MAC address of a Bluetooth serial adapter port.
*
* @since 0.1.1
*/
-char *sp_get_port_bluetooth_address(const struct sp_port *port);
+SP_API char *sp_get_port_bluetooth_address(const struct sp_port *port);
/**
* Get the operating system handle for a port.
*
* @since 0.1.0
*/
-enum sp_return sp_get_port_handle(const struct sp_port *port, void *result_ptr);
+SP_API enum sp_return sp_get_port_handle(const struct sp_port *port, void *result_ptr);
/**
* @}
* @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.
+ *
* @{
*/
*
* @since 0.1.0
*/
-enum sp_return sp_new_config(struct sp_port_config **config_ptr);
+SP_API enum sp_return sp_new_config(struct sp_port_config **config_ptr);
/**
* Free a port configuration structure.
*
* @since 0.1.0
*/
-void sp_free_config(struct sp_port_config *config);
+SP_API void sp_free_config(struct sp_port_config *config);
/**
* Get the current configuration of the specified serial port.
*
* @since 0.1.0
*/
-enum sp_return sp_get_config(struct sp_port *port, struct sp_port_config *config);
+SP_API enum sp_return sp_get_config(struct sp_port *port, struct sp_port_config *config);
/**
* Set the configuration for the specified serial port.
*
* @since 0.1.0
*/
-enum sp_return sp_set_config(struct sp_port *port, const struct sp_port_config *config);
+SP_API enum sp_return sp_set_config(struct sp_port *port, const struct sp_port_config *config);
/**
* Set the baud rate for the specified serial port.
*
* @since 0.1.0
*/
-enum sp_return sp_set_baudrate(struct sp_port *port, int baudrate);
+SP_API enum sp_return sp_set_baudrate(struct sp_port *port, int baudrate);
/**
* Get the baud rate from a port configuration.
*
* @since 0.1.0
*/
-enum sp_return sp_get_config_baudrate(const struct sp_port_config *config, int *baudrate_ptr);
+SP_API enum sp_return sp_get_config_baudrate(const struct sp_port_config *config, int *baudrate_ptr);
/**
* Set the baud rate in a port configuration.
*
* @since 0.1.0
*/
-enum sp_return sp_set_config_baudrate(struct sp_port_config *config, int baudrate);
+SP_API enum sp_return sp_set_config_baudrate(struct sp_port_config *config, int baudrate);
/**
* Set the data bits for the specified serial port.
*
* @since 0.1.0
*/
-enum sp_return sp_set_bits(struct sp_port *port, int bits);
+SP_API enum sp_return sp_set_bits(struct sp_port *port, int bits);
/**
* Get the data bits from a port configuration.
*
* @since 0.1.0
*/
-enum sp_return sp_get_config_bits(const struct sp_port_config *config, int *bits_ptr);
+SP_API enum sp_return sp_get_config_bits(const struct sp_port_config *config, int *bits_ptr);
/**
* Set the data bits in a port configuration.
*
* @since 0.1.0
*/
-enum sp_return sp_set_config_bits(struct sp_port_config *config, int bits);
+SP_API enum sp_return sp_set_config_bits(struct sp_port_config *config, int bits);
/**
* Set the parity setting for the specified serial port.
*
* @since 0.1.0
*/
-enum sp_return sp_set_parity(struct sp_port *port, enum sp_parity parity);
+SP_API enum sp_return sp_set_parity(struct sp_port *port, enum sp_parity parity);
/**
* Get the parity setting from a port configuration.
*
* @since 0.1.0
*/
-enum sp_return sp_get_config_parity(const struct sp_port_config *config, enum sp_parity *parity_ptr);
+SP_API enum sp_return sp_get_config_parity(const struct sp_port_config *config, enum sp_parity *parity_ptr);
/**
* Set the parity setting in a port configuration.
*
* @since 0.1.0
*/
-enum sp_return sp_set_config_parity(struct sp_port_config *config, enum sp_parity parity);
+SP_API enum sp_return sp_set_config_parity(struct sp_port_config *config, enum sp_parity parity);
/**
* Set the stop bits for the specified serial port.
*
* @since 0.1.0
*/
-enum sp_return sp_set_stopbits(struct sp_port *port, int stopbits);
+SP_API enum sp_return sp_set_stopbits(struct sp_port *port, int stopbits);
/**
* Get the stop bits from a port configuration.
*
* @since 0.1.0
*/
-enum sp_return sp_get_config_stopbits(const struct sp_port_config *config, int *stopbits_ptr);
+SP_API enum sp_return sp_get_config_stopbits(const struct sp_port_config *config, int *stopbits_ptr);
/**
* Set the stop bits in a port configuration.
*
* @since 0.1.0
*/
-enum sp_return sp_set_config_stopbits(struct sp_port_config *config, int stopbits);
+SP_API enum sp_return sp_set_config_stopbits(struct sp_port_config *config, int stopbits);
/**
* Set the RTS pin behaviour for the specified serial port.
*
* @since 0.1.0
*/
-enum sp_return sp_set_rts(struct sp_port *port, enum sp_rts rts);
+SP_API enum sp_return sp_set_rts(struct sp_port *port, enum sp_rts rts);
/**
* Get the RTS pin behaviour from a port configuration.
*
* @since 0.1.0
*/
-enum sp_return sp_get_config_rts(const struct sp_port_config *config, enum sp_rts *rts_ptr);
+SP_API enum sp_return sp_get_config_rts(const struct sp_port_config *config, enum sp_rts *rts_ptr);
/**
* Set the RTS pin behaviour in a port configuration.
*
* @since 0.1.0
*/
-enum sp_return sp_set_config_rts(struct sp_port_config *config, enum sp_rts rts);
+SP_API enum sp_return sp_set_config_rts(struct sp_port_config *config, enum sp_rts rts);
/**
* Set the CTS pin behaviour for the specified serial port.
*
* @since 0.1.0
*/
-enum sp_return sp_set_cts(struct sp_port *port, enum sp_cts cts);
+SP_API enum sp_return sp_set_cts(struct sp_port *port, enum sp_cts cts);
/**
* Get the CTS pin behaviour from a port configuration.
*
* @since 0.1.0
*/
-enum sp_return sp_get_config_cts(const struct sp_port_config *config, enum sp_cts *cts_ptr);
+SP_API enum sp_return sp_get_config_cts(const struct sp_port_config *config, enum sp_cts *cts_ptr);
/**
* Set the CTS pin behaviour in a port configuration.
*
* @since 0.1.0
*/
-enum sp_return sp_set_config_cts(struct sp_port_config *config, enum sp_cts cts);
+SP_API enum sp_return sp_set_config_cts(struct sp_port_config *config, enum sp_cts cts);
/**
* Set the DTR pin behaviour for the specified serial port.
*
* @since 0.1.0
*/
-enum sp_return sp_set_dtr(struct sp_port *port, enum sp_dtr dtr);
+SP_API enum sp_return sp_set_dtr(struct sp_port *port, enum sp_dtr dtr);
/**
* Get the DTR pin behaviour from a port configuration.
*
* @since 0.1.0
*/
-enum sp_return sp_get_config_dtr(const struct sp_port_config *config, enum sp_dtr *dtr_ptr);
+SP_API enum sp_return sp_get_config_dtr(const struct sp_port_config *config, enum sp_dtr *dtr_ptr);
/**
* Set the DTR pin behaviour in a port configuration.
*
* @since 0.1.0
*/
-enum sp_return sp_set_config_dtr(struct sp_port_config *config, enum sp_dtr dtr);
+SP_API enum sp_return sp_set_config_dtr(struct sp_port_config *config, enum sp_dtr dtr);
/**
* Set the DSR pin behaviour for the specified serial port.
*
* @since 0.1.0
*/
-enum sp_return sp_set_dsr(struct sp_port *port, enum sp_dsr dsr);
+SP_API enum sp_return sp_set_dsr(struct sp_port *port, enum sp_dsr dsr);
/**
* Get the DSR pin behaviour from a port configuration.
*
* @since 0.1.0
*/
-enum sp_return sp_get_config_dsr(const struct sp_port_config *config, enum sp_dsr *dsr_ptr);
+SP_API enum sp_return sp_get_config_dsr(const struct sp_port_config *config, enum sp_dsr *dsr_ptr);
/**
* Set the DSR pin behaviour in a port configuration.
*
* @since 0.1.0
*/
-enum sp_return sp_set_config_dsr(struct sp_port_config *config, enum sp_dsr dsr);
+SP_API enum sp_return sp_set_config_dsr(struct sp_port_config *config, enum sp_dsr dsr);
/**
* Set the XON/XOFF configuration for the specified serial port.
*
* @since 0.1.0
*/
-enum sp_return sp_set_xon_xoff(struct sp_port *port, enum sp_xonxoff xon_xoff);
+SP_API enum sp_return sp_set_xon_xoff(struct sp_port *port, enum sp_xonxoff xon_xoff);
/**
* Get the XON/XOFF configuration from a port configuration.
*
* @since 0.1.0
*/
-enum sp_return sp_get_config_xon_xoff(const struct sp_port_config *config, enum sp_xonxoff *xon_xoff_ptr);
+SP_API enum sp_return sp_get_config_xon_xoff(const struct sp_port_config *config, enum sp_xonxoff *xon_xoff_ptr);
/**
* Set the XON/XOFF configuration in a port configuration.
*
* @since 0.1.0
*/
-enum sp_return sp_set_config_xon_xoff(struct sp_port_config *config, enum sp_xonxoff xon_xoff);
+SP_API enum sp_return sp_set_config_xon_xoff(struct sp_port_config *config, enum sp_xonxoff xon_xoff);
/**
* Set the flow control type in a port configuration.
*
* @since 0.1.0
*/
-enum sp_return sp_set_config_flowcontrol(struct sp_port_config *config, enum sp_flowcontrol flowcontrol);
+SP_API enum sp_return sp_set_config_flowcontrol(struct sp_port_config *config, enum sp_flowcontrol flowcontrol);
/**
* Set the flow control type for the specified serial port.
*
* @since 0.1.0
*/
-enum sp_return sp_set_flowcontrol(struct sp_port *port, enum sp_flowcontrol flowcontrol);
+SP_API enum sp_return sp_set_flowcontrol(struct sp_port *port, enum sp_flowcontrol flowcontrol);
/**
* @}
*
* Reading, writing, and flushing data.
*
+ * See @ref send_receive.c for an example of sending and receiving data.
+ *
* @{
*/
*
* @since 0.1.0
*/
-enum sp_return sp_blocking_read(struct sp_port *port, void *buf, size_t count, unsigned int timeout_ms);
+SP_API 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, returning as soon as any data is
*
* @since 0.1.1
*/
-enum sp_return sp_blocking_read_next(struct sp_port *port, void *buf, size_t count, unsigned int timeout_ms);
+SP_API 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, without blocking.
*
* @since 0.1.0
*/
-enum sp_return sp_nonblocking_read(struct sp_port *port, void *buf, size_t count);
+SP_API enum sp_return sp_nonblocking_read(struct sp_port *port, void *buf, size_t count);
/**
* Write bytes to the specified serial port, blocking until complete.
*
* @since 0.1.0
*/
-enum sp_return sp_blocking_write(struct sp_port *port, const void *buf, size_t count, unsigned int timeout_ms);
+SP_API 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, without blocking.
*
* @since 0.1.0
*/
-enum sp_return sp_nonblocking_write(struct sp_port *port, const void *buf, size_t count);
+SP_API enum sp_return sp_nonblocking_write(struct sp_port *port, const void *buf, size_t count);
/**
* Gets the number of bytes waiting in the input buffer.
*
* @since 0.1.0
*/
-enum sp_return sp_input_waiting(struct sp_port *port);
+SP_API enum sp_return sp_input_waiting(struct sp_port *port);
/**
* Gets the number of bytes waiting in the output buffer.
*
* @since 0.1.0
*/
-enum sp_return sp_output_waiting(struct sp_port *port);
+SP_API enum sp_return sp_output_waiting(struct sp_port *port);
/**
* Flush serial port buffers. Data in the selected buffer(s) is discarded.
*
* @since 0.1.0
*/
-enum sp_return sp_flush(struct sp_port *port, enum sp_buffer buffers);
+SP_API enum sp_return sp_flush(struct sp_port *port, enum sp_buffer buffers);
/**
* Wait for buffered data to be transmitted.
*
* @since 0.1.0
*/
-enum sp_return sp_drain(struct sp_port *port);
+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.
+ *
* @{
*/
*
* @since 0.1.0
*/
-enum sp_return sp_new_event_set(struct sp_event_set **result_ptr);
+SP_API enum sp_return sp_new_event_set(struct sp_event_set **result_ptr);
/**
* Add events to a struct sp_event_set for a given port.
*
* @since 0.1.0
*/
-enum sp_return sp_add_port_events(struct sp_event_set *event_set,
+SP_API enum sp_return sp_add_port_events(struct sp_event_set *event_set,
const struct sp_port *port, enum sp_event mask);
/**
*
* @since 0.1.0
*/
-enum sp_return sp_wait(struct sp_event_set *event_set, unsigned int timeout_ms);
+SP_API enum sp_return sp_wait(struct sp_event_set *event_set, unsigned int timeout_ms);
/**
* Free a structure allocated by sp_new_event_set().
*
* @since 0.1.0
*/
-void sp_free_event_set(struct sp_event_set *event_set);
+SP_API void sp_free_event_set(struct sp_event_set *event_set);
/**
* @}
*
* @since 0.1.0
*/
-enum sp_return sp_get_signals(struct sp_port *port, enum sp_signal *signal_mask);
+SP_API enum sp_return sp_get_signals(struct sp_port *port, enum sp_signal *signal_mask);
/**
* Put the port transmit line into the break state.
*
* @since 0.1.0
*/
-enum sp_return sp_start_break(struct sp_port *port);
+SP_API enum sp_return sp_start_break(struct sp_port *port);
/**
* Take the port transmit line out of the break state.
*
* @since 0.1.0
*/
-enum sp_return sp_end_break(struct sp_port *port);
+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.
+ *
* @{
*/
*
* @since 0.1.0
*/
-int sp_last_error_code(void);
+SP_API int sp_last_error_code(void);
/**
* Get the error message for a failed operation.
*
* @since 0.1.0
*/
-char *sp_last_error_message(void);
+SP_API char *sp_last_error_message(void);
/**
* Free an error message returned by sp_last_error_message().
*
* @since 0.1.0
*/
-void sp_free_error_message(char *message);
+SP_API void sp_free_error_message(char *message);
/**
* Set the handler function for library debugging messages.
*
* @since 0.1.0
*/
-void sp_set_debug_handler(void (*handler)(const char *format, ...));
+SP_API void sp_set_debug_handler(void (*handler)(const char *format, ...));
/**
* Default handler function for library debugging messages.
*
* @since 0.1.0
*/
-void sp_default_debug_handler(const char *format, ...);
+SP_API void sp_default_debug_handler(const char *format, ...);
/** @} */
*
* @since 0.1.0
*/
-int sp_get_major_package_version(void);
+SP_API int sp_get_major_package_version(void);
/**
* Get the minor libserialport package version number.
*
* @since 0.1.0
*/
-int sp_get_minor_package_version(void);
+SP_API int sp_get_minor_package_version(void);
/**
* Get the micro libserialport package version number.
*
* @since 0.1.0
*/
-int sp_get_micro_package_version(void);
+SP_API int sp_get_micro_package_version(void);
/**
* Get the libserialport package version number as a string.
*
* @since 0.1.0
*/
-const char *sp_get_package_version_string(void);
+SP_API const char *sp_get_package_version_string(void);
/**
* Get the "current" part of the libserialport library version number.
*
* @since 0.1.0
*/
-int sp_get_current_lib_version(void);
+SP_API int sp_get_current_lib_version(void);
/**
* Get the "revision" part of the libserialport library version number.
*
* @since 0.1.0
*/
-int sp_get_revision_lib_version(void);
+SP_API int sp_get_revision_lib_version(void);
/**
* Get the "age" part of the libserialport library version number.
*
* @since 0.1.0
*/
-int sp_get_age_lib_version(void);
+SP_API int sp_get_age_lib_version(void);
/**
* Get the libserialport library version number as a string.
*
* @since 0.1.0
*/
-const char *sp_get_lib_version_string(void);
+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
projects / libserialport.git / blobdiff