From: Martin Ling <redacted>
Date: Fri, 22 Nov 2013 20:12:39 +0000 (+0000)
Subject: Use new SP_ERR_SUPP error to indicate unsupported operations.
X-Git-Tag: libserialport-0.1.0~70
X-Git-Url: https://sigrok.org/gitaction?a=commitdiff_plain;h=6aabf62a90915a94c8415ba4e29da96c05b0526b;p=libserialport.git

Use new SP_ERR_SUPP error to indicate unsupported operations.
---

diff --git a/libserialport.h.in b/libserialport.h.in
index 6a76f98..7c50c7e 100644
--- a/libserialport.h.in
+++ b/libserialport.h.in
@@ -49,15 +49,25 @@
  * port. These structures are always allocated and freed by the library, using
  * the functions in the @ref Enumeration "Enumeration" section.
  *
- * All functions can return only three possible error values. @ref SP_ERR_ARG
- * indicates the function was called with invalid arguments. @ref SP_ERR_FAIL
- * indicates that the OS reported a failure. @ref SP_ERR_MEM indicates that a
- * memory allocation failed. All of these error values are negative.
+ * All functions can return only four possible error values:
  *
- * When @ref SP_ERR_FAIL is returned, an error code or string description of
- * the error can be obtained by calling sp_last_error_code() or
- * sp_last_error_message(). The error code or message is that provided by the
- * OS; libserialport does not define any error codes or messages of its own.
+ * - @ref SP_ERR_ARG means that a function was called with invalid
+ *   arguments. This implies a bug in the caller. The arguments passed would
+ *   be invalid regardless of the underlying OS or serial device involved.
+ *
+ * - @ref SP_ERR_FAIL means that the OS reported a failure. The error code or
+ *   message provided by the OS can be obtained by calling sp_last_error_code()
+ *   or sp_last_error_message().
+ *
+ * - @ref SP_ERR_SUPP indicates that there is no support for the requested
+ *   operation in the current OS, driver or device. No error message is
+ *   available from the OS in this case. There is either no way to request
+ *   the operation in the first place, or libserialport does not know how to
+ *   do so in the current version.
+ *
+ * - @ref SP_ERR_MEM indicates that a memory allocation failed.
+ *
+ * All of these error values are negative.
  *
  * Function calls that succeed return @ref SP_OK, which is equal to zero,
  * or where otherwise documented a positive value.
@@ -97,6 +107,8 @@ enum sp_return {
 	SP_ERR_FAIL = -2,
 	/** A memory allocation failed while executing the operation. */
 	SP_ERR_MEM = -3,
+	/** The requested operation is not supported by this system or device. */
+	SP_ERR_SUPP = -4,
 };
 
 /** Port access modes. */
diff --git a/serialport.c b/serialport.c
index 0f1b5a5..007de43 100644
--- a/serialport.c
+++ b/serialport.c
@@ -1055,7 +1055,7 @@ static enum sp_return set_config(struct sp_port *port, struct port_data *data,
 #elif defined(__linux__)
 			baud_nonstd = 1;
 #else
-			return SP_ERR_ARG;
+			return SP_ERR_SUPP;
 #endif
 		}
 	}
@@ -1141,17 +1141,17 @@ static enum sp_return set_config(struct sp_port *port, struct port_data *data,
 				/* Flow control can only be disabled for both RTS & CTS together. */
 				if (config->rts >= 0 && config->rts != SP_RTS_FLOW_CONTROL) {
 					if (config->cts != SP_CTS_IGNORE)
-						return SP_ERR_ARG;
+						return SP_ERR_SUPP;
 				}
 				if (config->cts >= 0 && config->cts != SP_CTS_FLOW_CONTROL) {
 					if (config->rts <= 0 || config->rts == SP_RTS_FLOW_CONTROL)
-						return SP_ERR_ARG;
+						return SP_ERR_SUPP;
 				}
 			} else {
 				/* Flow control can only be enabled for both RTS & CTS together. */
 				if (((config->rts == SP_RTS_FLOW_CONTROL) && (config->cts != SP_CTS_FLOW_CONTROL)) ||
 					((config->cts == SP_CTS_FLOW_CONTROL) && (config->rts != SP_RTS_FLOW_CONTROL)))
-					return SP_ERR_ARG;
+					return SP_ERR_SUPP;
 			}
 
 			if (config->rts >= 0) {
@@ -1188,7 +1188,7 @@ static enum sp_return set_config(struct sp_port *port, struct port_data *data,
 		} else {
 			/* DTR/DSR flow control not supported. */
 			if (config->dtr == SP_DTR_FLOW_CONTROL || config->dsr == SP_DSR_FLOW_CONTROL)
-				return SP_ERR_ARG;
+				return SP_ERR_SUPP;
 
 			if (config->dtr >= 0) {
 				controlbits = TIOCM_DTR;