Make port structure opaque.

[libserialport.git] / libserialport.h.in

diff --git a/libserialport.h.in b/libserialport.h.in
index 0e3dc1b1968f67324b83785fe13afd0bf42953ac..2492f68fe23f8b28b21651de4e97b702a6718484 100644 (file)
--- a/libserialport.h.in
+++ b/libserialport.h.in
@@ -226,18 +226,7 @@ enum sp_signal {
 };
 
 /** A serial port. */
-struct sp_port {
-       /** Name used to open the port. */
-       char *name;
-/** @cond 0 */
-       /** OS-specific port handle. */
-#ifdef _WIN32
-       HANDLE hdl;
-#else
-       int fd;
-#endif
-/** @endcond */
-};
+struct sp_port;
 
 /** Configuration for a serial port. */
 struct sp_port_config {
@@ -281,6 +270,21 @@ struct sp_port_config {
  */
 enum sp_return sp_get_port_by_name(const char *portname, struct sp_port **port_ptr);
 
+/**
+ * Get the name of a port.
+ *
+ * The name returned is whatever is normally used to refer to a port on the
+ * current operating system; e.g. for Windows it will usually be a "COMn"
+ * device name, and for Unix it will be a device path beginning with "/dev/".
+ *
+ * @param port Pointer to port structure.
+ *
+ * @return The port name, or NULL if an invalid port is passed. The name
+ * string is part of the port structure and may not be used after the
+ * port structure has been freed.
+ */
+char *sp_get_port_name(const struct sp_port *port);
+
 /**
  * Free a port structure obtained from sp_get_port_by_name() or sp_copy_port().
  */
@@ -615,6 +619,29 @@ char *sp_last_error_message(void);
  */
 void sp_free_error_message(char *message);
 
+/**
+ * Set the handler function for library debugging messages.
+ *
+ * Debugging messages are generated by the library during each operation,
+ * to help in diagnosing problems. The handler will be called for each
+ * message. The handler can be set to NULL to ignore all debug messages.
+ *
+ * The handler function should accept a format string and variable length
+ * argument list, in the same manner as e.g. printf().
+ *
+ * The default handler is sp_default_debug_handler().
+ */
+void sp_set_debug_handler(void (*handler)(const char *format, ...));
+
+/**
+ * Default handler function for library debugging messages.
+ *
+ * This function prints debug messages to the standard error stream if the
+ * environment variable LIBSERIALPORT_DEBUG is set. Otherwise, they are
+ * ignored.
+ */
+void sp_default_debug_handler(const char *format, ...);
+
 /** @} */
 
 #ifdef __cplusplus