Add example of waiting for events.

diff --git a/Makefile.am b/Makefile.am
index d7e9fadb2558203efb384eacc7541cf9359d62e7..9b017eb4504dc004eaa700a7d5ea542f2f038ca3 100644 (file)
--- a/Makefile.am
+++ b/Makefile.am
@@ -67,6 +67,7 @@ EXTRA_DIST = Doxyfile \
        examples/list_ports.c \
        examples/port_info.c \
        examples/port_config.c \
+       examples/await_events.c \
        examples/handle_errors.c
 
 MAINTAINERCLEANFILES = ChangeLog

diff --git a/examples/.gitignore b/examples/.gitignore
index 80e56cee16603465553711d156b202c361662476..afe6f4af7230cf61b27f19f91c438161af7b53d9 100644 (file)
--- a/examples/.gitignore
+++ b/examples/.gitignore
@@ -1,3 +1,4 @@
+await_events
 handle_errors
 list_ports
 port_info

diff --git a/examples/await_events.c b/examples/await_events.c
new file mode 100644 (file)
index 0000000..133d899
--- /dev/null
+++ b/examples/await_events.c
@@ -0,0 +1,99 @@
+#include <libserialport.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+/* Example of how to wait for events on multiple ports.
+ *
+ * This example file is released to the public domain. */
+
+/* Helper function for error handling. */
+int check(enum sp_return result);
+
+int main(int argc, char **argv)
+{
+       /* Get the port names from the command line. */
+       if (argc < 2) {
+               printf("Usage: %s <port name>...\n", argv[0]);
+               return -1;
+       }
+       int num_ports = argc - 1;
+       char **port_names = argv + 1;
+
+       /* The ports we will use. */
+       struct sp_port *ports[num_ports];
+
+       /* The set of events we will wait for. */
+       struct sp_event_set *event_set;
+
+       /* Allocate the event set. */
+       check(sp_new_event_set(&event_set));
+
+       /* Open and configure each port, and then add its RX event
+        * to the event set. */
+       for (int i = 0; i < num_ports; i++) {
+
+               printf("Looking for port %s.\n", port_names[i]);
+               check(sp_get_port_by_name(port_names[i], &ports[i]));
+
+               printf("Opening port.\n");
+               check(sp_open(ports[i], SP_MODE_READ));
+
+               printf("Setting port to 9600 8N1, no flow control.\n");
+               check(sp_set_baudrate(ports[i], 9600));
+               check(sp_set_bits(ports[i], 8));
+               check(sp_set_parity(ports[i], SP_PARITY_NONE));
+               check(sp_set_stopbits(ports[i], 1));
+               check(sp_set_flowcontrol(ports[i], SP_FLOWCONTROL_NONE));
+
+               printf("Adding port RX event to event set.\n");
+               check(sp_add_port_events(event_set, ports[i], SP_EVENT_RX_READY));
+       }
+
+       /* Now we can call sp_wait() to await any event in the set.
+        * It will return when an event occurs, or the timeout elapses. */
+       printf("Waiting up to 5 seconds for RX on any port...\n");
+       check(sp_wait(event_set, 5000));
+
+       /* Iterate over ports to see which have data waiting. */
+       for (int i = 0; i < num_ports; i++) {
+               /* Get number of bytes waiting. */
+               int bytes_waiting = check(sp_input_waiting(ports[i]));
+               printf("Port %s: %d bytes received.\n",
+                               sp_get_port_name(ports[i]), bytes_waiting);
+       }
+
+       /* Close ports and free resources. */
+       sp_free_event_set(event_set);
+       for (int i = 0; i < num_ports; i++) {
+               check(sp_close(ports[i]));
+               sp_free_port(ports[i]);
+       }
+
+       return 0;
+}
+
+/* Helper function for error handling. */
+int check(enum sp_return result)
+{
+       /* For this example we'll just exit on any error by calling abort(). */
+       char *error_message;
+       switch (result) {
+               case SP_ERR_ARG:
+                       printf("Error: Invalid argument.\n");
+                       abort();
+               case SP_ERR_FAIL:
+                       error_message = sp_last_error_message();
+                       printf("Error: Failed: %s\n", error_message);
+                       sp_free_error_message(error_message);
+                       abort();
+               case SP_ERR_SUPP:
+                       printf("Error: Not supported.\n");
+                       abort();
+               case SP_ERR_MEM:
+                       printf("Error: Couldn't allocate memory.\n");
+                       abort();
+               case SP_OK:
+               default:
+                       return result;
+       }
+}

diff --git a/libserialport.h b/libserialport.h
index 65f96799933a008fab903cc9be95b175668e744e..1ff0b68e95efdc5773a69e9cc72c42c2d5434d97 100644 (file)
--- a/libserialport.h
+++ b/libserialport.h
@@ -68,6 +68,7 @@
  * - @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 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
@@ -1478,6 +1479,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.
+ *
  * @{
  */
 
@@ -1809,6 +1812,7 @@ 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 await_events.c - Awaiting events on multiple ports.
  * @example handle_errors.c - Handling errors returned from the library.
 */