From: Martin Ling <redacted>
Date: Sat, 23 Nov 2013 17:50:45 +0000 (+0000)
Subject: Add sp_get_port_handle() function.
X-Git-Tag: libserialport-0.1.0~57
X-Git-Url: https://sigrok.org/gitweb/?p=libserialport.git;a=commitdiff_plain;h=3c126654b3d92584d0a9cd4e13f1cee764146ca6

Add sp_get_port_handle() function.
---

diff --git a/libserialport.h.in b/libserialport.h.in
index 2492f68..d2dd037 100644
--- a/libserialport.h.in
+++ b/libserialport.h.in
@@ -285,6 +285,30 @@ enum sp_return sp_get_port_by_name(const char *portname, struct sp_port **port_p
  */
 char *sp_get_port_name(const struct sp_port *port);
 
+/**
+ * Get the operating system handle for a port.
+ *
+ * The type of the handle depends on the operating system. On Unix based
+ * systems, the handle is a file descriptor of type "int". On Windows, the
+ * handle is of type "HANDLE". The user should allocate a variable of the
+ * appropriate type and pass a pointer to this to receive the result.
+ *
+ * To obtain a valid handle, 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 handle may
+ * no longer be valid.
+ *
+ * @warning This feature is provided so that programs may make use of
+ *          OS-specific functionality where desired. Obviously this comes
+ *          at a cost in portability, however it also cannot be guaranteed
+ *          that direct usage of the OS handle will not conflict with the
+ *          library's own usage of the port. Be careful.
+ *
+ * @return SP_OK upon success, a negative error code otherwise.
+ */
+enum sp_return sp_get_port_handle(const struct sp_port *port, void *result);
+
 /**
  * Free a port structure obtained from sp_get_port_by_name() or sp_copy_port().
  */
diff --git a/serialport.c b/serialport.c
index 0ec664a..739a6ed 100644
--- a/serialport.c
+++ b/serialport.c
@@ -203,6 +203,24 @@ char *sp_get_port_name(const struct sp_port *port)
 	RETURN_VALUE("%s", port->name);
 }
 
+enum sp_return sp_get_port_handle(const struct sp_port *port, void *result_ptr)
+{
+	TRACE("%p", port);
+
+	if (!port)
+		RETURN_ERROR(SP_ERR_ARG, "Null port");
+
+#ifdef _WIN32
+	HANDLE *handle_ptr = result_ptr;
+	*handle_ptr = port->hdl;
+#else
+	int *fd_ptr = result_ptr;
+	*fd_ptr = port->fd;
+#endif
+
+	RETURN_OK();
+}
+
 enum sp_return sp_copy_port(const struct sp_port *port, struct sp_port **copy_ptr)
 {
 	TRACE("%p, %p", port, copy_ptr);