X-Git-Url: http://sigrok.org/gitweb/?a=blobdiff_plain;f=libserialport.h.in;h=01c20af414b28baed977b360a656428ed7b9156d;hb=104f093dba21da6e88b3c6d3349c489a5ac51be8;hp=46e2fda55fc467f2ba770cf56259081b7db76e0d;hpb=b87deb7c70b739ffac312112950c4481f6f4666d;p=libserialport.git

diff --git a/libserialport.h.in b/libserialport.h.in
index 46e2fda..01c20af 100644
--- a/libserialport.h.in
+++ b/libserialport.h.in
@@ -36,6 +36,7 @@
  * - @ref Configuration (baud rate, parity, etc.)
  * - @ref Signals (modem control lines, breaks, etc.)
  * - @ref Data
+ * - @ref Waiting
  * - @ref Errors
  *
  * libserialport is an open source project released under the LGPL3+ license.
@@ -73,7 +74,7 @@
  *
  * Calls that succeed return @ref SP_OK, which is equal to zero. Some functions
  * declared @ref sp_return can also return a positive value for a successful
- * numeric result, e.g. sp_read() and sp_write().
+ * numeric result, e.g. sp_blocking_read() or sp_blocking_write().
  */
 
 #ifndef LIBSERIALPORT_LIBSERIALPORT_H
@@ -122,6 +123,16 @@ enum sp_mode {
 	SP_MODE_WRITE = 2,
 };
 
+/** Port events. */
+enum sp_event {
+	/* Data received and ready to read. */
+	SP_EVENT_RX_READY = 1,
+	/* Ready to transmit new data. */
+	SP_EVENT_TX_READY = 2,
+	/* Error occured. */
+	SP_EVENT_ERROR = 4,
+};
+
 /** Buffer selection. */
 enum sp_buffer {
 	/** Input buffer. */
@@ -230,12 +241,31 @@ enum sp_signal {
 	SP_SIG_RI = 8,
 };
 
-/** A serial port. */
+/**
+ * @struct sp_port
+ * An opaque structure representing a serial port.
+ */
 struct sp_port;
 
-/** Configuration for a serial port. */
+/**
+ * @struct sp_port_config
+ * An opaque structure representing the configuration for a serial port.
+ */
 struct sp_port_config;
 
+/**
+ * @struct sp_event_set
+ * A set of handles to wait on for events.
+ */
+struct sp_event_set {
+	/** Array of OS-specific handles. */
+	void *handles;
+	/** Array of bitmasks indicating which events apply for each handle. */
+	enum sp_event *masks;
+	/** Number of handles. */
+	unsigned int count;
+};
+
 /**
 @defgroup Enumeration Port enumeration
 @{
@@ -878,12 +908,70 @@ enum sp_return sp_flush(struct sp_port *port, enum sp_buffer buffers);
 /**
  * Wait for buffered data to be transmitted.
  *
+ * @warning If your program runs on Unix, defines its own signal handlers, and
+ *          needs to abort draining the output buffer when when these are
+ *          called, then you should not use this function. It repeats system
+ *          calls that return with EINTR. To be able to abort a drain from a
+ *          signal handler, you would need to implement your own blocking
+ *          drain by polling the result of sp_output_waiting().
+ *
  * @param port Pointer to port structure.
  *
  * @return SP_OK upon success, a negative error code otherwise.
  */
 enum sp_return sp_drain(struct sp_port *port);
 
+/**
+ * @}
+ * @defgroup Waiting Waiting for events
+ * @{
+ */
+
+/**
+ * Allocate storage for a set of events.
+ *
+ * The user should allocate a variable of type struct sp_event_set *,
+ * then pass a pointer to this variable to receive the result.
+ *
+ * The result should be freed after use by calling sp_free_event_set().
+ *
+ * @return SP_OK upon success, a negative error code otherwise.
+ */
+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.
+ *
+ * The port must first be opened by calling sp_open() using the same port
+ * structure.
+ *
+ * After the port is closed or the port structure freed, the results may
+ * no longer be valid.
+ *
+ * @param event_set Event set to update.
+ * @param port Pointer to port structure.
+ * @param mask Bitmask of events to be waited for.
+ *
+ * @return SP_OK upon success, a negative error code otherwise.
+ */
+enum sp_return sp_add_port_events(struct sp_event_set *event_set,
+	const struct sp_port *port, enum sp_event mask);
+
+/**
+ * Wait for any of a set of events to occur.
+ *
+ * @param handles Event set to wait on.
+ * @param timeout Timeout in milliseconds, or zero to wait indefinitely.
+ *
+ * @return SP_OK upon success, a negative error code otherwise.
+ */
+enum sp_return sp_wait(struct sp_event_set *event_set, unsigned int timeout);
+
+/**
+ * Free a structure allocated by sp_new_event_set().
+ */
+void sp_free_event_set(struct sp_event_set *event_set);
+
 /**
  * @}
  * @defgroup Signals Port signalling operations